DynamicTablesPkg: Configuration Manager Helper

This patch defines a helper macro 'GET_OBJECT_LIST()' that
expands to a function that uses the configuration manager
protocol to retrieve configuration manager object(s).

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <alexei.fedorov@arm.com>

diff --git a/DynamicTablesPkg/Include/ConfigurationManagerHelper.h b/DynamicTablesPkg/Include/ConfigurationManagerHelper.h
new file mode 100644 (file)
index 0000000..cf99600
--- /dev/null
+++ b/DynamicTablesPkg/Include/ConfigurationManagerHelper.h
@@ -0,0 +1,132 @@
+/** @file\r
+\r
+  Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.\r
+\r
+  This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions of the BSD License\r
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+  @par Glossary:\r
+    - Cm or CM   - Configuration Manager\r
+    - Obj or OBJ - Object\r
+**/\r
+\r
+#ifndef CONFIGURATION_MANAGER_HELPER_H_\r
+#define CONFIGURATION_MANAGER_HELPER_H_\r
+\r
+/** The GET_OBJECT_LIST macro expands to a function that is used to retrieve\r
+    an object or an object list from the Configuration Manager using the\r
+    Configuration Manager Protocol interface.\r
+\r
+  The macro expands to a function which has the following prototype:\r
+\r
+  STATIC\r
+  EFI_STATUS\r
+  EFIAPI\r
+  Get<CmObjectId> (\r
+    IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL * CONST CfgMgrProtocol,\r
+    IN  CONST CM_OBJECT_TOKEN                              Token OPTIONAL,\r
+    OUT       Type                                **       List,\r
+    OUT       UINT32                               *       Count OPTIONAL\r
+    );\r
+\r
+  Generated function parameters:\r
+  @param [in]  CfgMgrProtocol Pointer to the Configuration Manager protocol\r
+                              interface.\r
+  @param [in]  Token          Reference token for the Object.\r
+  @param [out] List           Pointer to the Object list.\r
+  @param [out] Count          Count of the objects returned in the list.\r
+\r
+  Macro Parameters:\r
+  @param [in] CmObjectNameSpace The Object Namespace\r
+  @param [in] CmObjectId        Object Id.\r
+  @param [in] Type              Structure used to describe the Object.\r
+\r
+  @retval EFI_SUCCESS           Success.\r
+  @retval EFI_INVALID_PARAMETER A parameter is invalid.\r
+  @retval EFI_NOT_FOUND         The required object information is not found.\r
+  @retval EFI_BAD_BUFFER_SIZE   The size returned by the Configuration\r
+                                Manager is less than the Object size for the\r
+                                requested object.\r
+**/\r
+#define GET_OBJECT_LIST(CmObjectNameSpace, CmObjectId, Type)                  \\r
+STATIC                                                                        \\r
+EFI_STATUS                                                                    \\r
+EFIAPI                                                                        \\r
+Get##CmObjectId (                                                             \\r
+  IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,     \\r
+  IN  CONST CM_OBJECT_TOKEN                               Token OPTIONAL,     \\r
+  OUT       Type                                 **       List,               \\r
+  OUT       UINT32                                * CONST Count OPTIONAL      \\r
+  )                                                                           \\r
+{                                                                             \\r
+  EFI_STATUS         Status;                                                  \\r
+  CM_OBJ_DESCRIPTOR  CmObjectDesc;                                            \\r
+  UINT32             ObjCount = 0;                                            \\r
+  if (List == NULL) {                                                         \\r
+    Status = EFI_INVALID_PARAMETER;                                           \\r
+    DEBUG ((                                                                  \\r
+      DEBUG_ERROR,                                                            \\r
+      "ERROR: Get" #CmObjectId ": Invalid out parameter for"                  \\r
+      " object list. Status = %r\n",                                          \\r
+      Status                                                                  \\r
+      ));                                                                     \\r
+    goto error_handler;                                                       \\r
+  }                                                                           \\r
+  Status = CfgMgrProtocol->GetObject (                                        \\r
+                             CfgMgrProtocol,                                  \\r
+                             CREATE_CM_OBJECT_ID (                            \\r
+                               CmObjectNameSpace,                             \\r
+                               CmObjectId                                     \\r
+                               ),                                             \\r
+                             Token,                                           \\r
+                             &CmObjectDesc                                    \\r
+                             );                                               \\r
+  if (EFI_ERROR (Status)) {                                                   \\r
+    DEBUG ((                                                                  \\r
+      DEBUG_INFO,                                                             \\r
+      "INFO: Get" #CmObjectId ": Platform does not implement "                \\r
+      #CmObjectId ". Status = %r\n",                                          \\r
+      Status                                                                  \\r
+      ));                                                                     \\r
+    *List = NULL;                                                             \\r
+    goto error_handler;                                                       \\r
+  }                                                                           \\r
+  if (CmObjectDesc.ObjectId !=                                                \\r
+      CREATE_CM_OBJECT_ID (CmObjectNameSpace, CmObjectId)) {                  \\r
+    DEBUG ((                                                                  \\r
+      DEBUG_ERROR,                                                            \\r
+      "ERROR: Get" #CmObjectId ": " #CmObjectId                               \\r
+      ": Invalid ObjectId = 0x%x\n, expected Id = 0x%x\n",                    \\r
+      CmObjectDesc.ObjectId,                                                  \\r
+      CREATE_CM_OBJECT_ID (CmObjectNameSpace, CmObjectId)                     \\r
+      ));                                                                     \\r
+    ASSERT (FALSE);                                                           \\r
+    Status = EFI_INVALID_PARAMETER;                                           \\r
+    goto error_handler;                                                       \\r
+  }                                                                           \\r
+  if (CmObjectDesc.Size < (sizeof (Type) * CmObjectDesc.Count)) {             \\r
+    DEBUG ((                                                                  \\r
+      DEBUG_ERROR,                                                            \\r
+      "ERROR: Get" #CmObjectId ": " #CmObjectId                               \\r
+      ": Buffer too small, size = 0x%x\n",                                    \\r
+      CmObjectDesc.Size                                                       \\r
+      ));                                                                     \\r
+    ASSERT (FALSE);                                                           \\r
+    Status = EFI_BAD_BUFFER_SIZE;                                             \\r
+    goto error_handler;                                                       \\r
+  }                                                                           \\r
+  ObjCount = CmObjectDesc.Count;                                              \\r
+  *List = (Type*)CmObjectDesc.Data;                                           \\r
+error_handler:                                                                \\r
+  if (Count != NULL) {                                                        \\r
+    *Count = ObjCount;                                                        \\r
+  }                                                                           \\r
+  return Status;                                                              \\r
+}\r
+\r
+#endif // CONFIGURATION_MANAGER_HELPER_H_\r