MdePkg/BaseLib: Add linked list iteration macros

REF:https://bugzilla.tianocore.org/show_bug.cgi?id=1959

The macros EFI_LIST_FOR_EACH and EFI_LIST_FOR_EACH_SAFE have been
duplicated across several drivers. These macros have proven useful and
established a commonly used pattern for linked list iteration.

This change defines the macros in BaseLib.h alongside other generic linked
list macros and functions.

Cc: Dandan Bi <dandan.bi@intel.com>
Cc: Hao A Wu <hao.a.wu@intel.com>
Cc: Jian J Wang <jian.j.wang@intel.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
Reviewed-by: Guomin Jiang <guomin.jiang@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
Reviewed-by: Bret Barkelew <bret.barkelew@microsoft.com>

diff --git a/MdePkg/Include/Library/BaseLib.h b/MdePkg/Include/Library/BaseLib.h
index ecadff8b235ee3ea112c0d2d19af57586b8bbc81..d066f1be2495e261c9f7340221fad4fd7541885b 100644 (file)
--- a/MdePkg/Include/Library/BaseLib.h
+++ b/MdePkg/Include/Library/BaseLib.h
@@ -4,6 +4,7 @@
 \r
 Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>\r
 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
+Copyright (c) Microsoft Corporation.<BR>\r
 SPDX-License-Identifier: BSD-2-Clause-Patent\r
 \r
 **/\r
@@ -2972,6 +2973,32 @@ PathCleanUpDirectories(
 **/\r
 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead)  {&(ListHead), &(ListHead)}\r
 \r
+/**\r
+  Iterates over each node in a doubly linked list using each node's forward link.\r
+\r
+  @param  Entry     A pointer to a list node used as a loop cursor during iteration\r
+  @param  ListHead  The head node of the doubly linked list\r
+\r
+**/\r
+#define BASE_LIST_FOR_EACH(Entry, ListHead)    \\r
+  for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)\r
+\r
+/**\r
+  Iterates over each node in a doubly linked list using each node's forward link\r
+  with safety against node removal.\r
+\r
+  This macro uses NextEntry to temporarily store the next list node so the node\r
+  pointed to by Entry may be deleted in the current loop iteration step and\r
+  iteration can continue from the node pointed to by NextEntry.\r
+\r
+  @param  Entry     A pointer to a list node used as a loop cursor during iteration\r
+  @param  NextEntry A pointer to a list node used to temporarily store the next node\r
+  @param  ListHead  The head node of the doubly linked list\r
+\r
+**/\r
+#define BASE_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead)            \\r
+  for(Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\\r
+      Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)\r
 \r
 /**\r
   Checks whether FirstEntry and SecondEntry are part of the same doubly-linked\r