DynamicTablesPkg/Include/ConfigurationManagerHelper.h

   1 /** @file
   2
   3   Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.
   4
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Glossary:
   8     - Cm or CM   - Configuration Manager
   9     - Obj or OBJ - Object
  10 **/
  11
  12 #ifndef CONFIGURATION_MANAGER_HELPER_H_
  13 #define CONFIGURATION_MANAGER_HELPER_H_
  14
  15 /** The GET_OBJECT_LIST macro expands to a function that is used to retrieve
  16     an object or an object list from the Configuration Manager using the
  17     Configuration Manager Protocol interface.
  18
  19   The macro expands to a function which has the following prototype:
  20
  21   STATIC
  22   EFI_STATUS
  23   EFIAPI
  24   Get<CmObjectId> (
  25     IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL * CONST CfgMgrProtocol,
  26     IN  CONST CM_OBJECT_TOKEN                              Token OPTIONAL,
  27     OUT       Type                                **       List,
  28     OUT       UINT32                               *       Count OPTIONAL
  29     );
  30
  31   Generated function parameters:
  32   @param [in]  CfgMgrProtocol Pointer to the Configuration Manager protocol
  33                               interface.
  34   @param [in]  Token          Reference token for the Object.
  35   @param [out] List           Pointer to the Object list.
  36   @param [out] Count          Count of the objects returned in the list.
  37
  38   Macro Parameters:
  39   @param [in] CmObjectNameSpace The Object Namespace
  40   @param [in] CmObjectId        Object Id.
  41   @param [in] Type              Structure used to describe the Object.
  42
  43   @retval EFI_SUCCESS           Success.
  44   @retval EFI_INVALID_PARAMETER A parameter is invalid.
  45   @retval EFI_NOT_FOUND         The required object information is not found.
  46   @retval EFI_BAD_BUFFER_SIZE   The size returned by the Configuration
  47                                 Manager is less than the Object size for the
  48                                 requested object.
  49 **/
  50 #define GET_OBJECT_LIST(CmObjectNameSpace, CmObjectId, Type)                  \
  51 STATIC                                                                        \
  52 EFI_STATUS                                                                    \
  53 EFIAPI                                                                        \
  54 Get##CmObjectId (                                                             \
  55   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,     \
  56   IN  CONST CM_OBJECT_TOKEN                               Token OPTIONAL,     \
  57   OUT       Type                                 **       List,               \
  58   OUT       UINT32                                * CONST Count OPTIONAL      \
  59   )                                                                           \
  60 {                                                                             \
  61   EFI_STATUS         Status;                                                  \
  62   CM_OBJ_DESCRIPTOR  CmObjectDesc;                                            \
  63   UINT32             ObjCount = 0;                                            \
  64   if (List == NULL) {                                                         \
  65     Status = EFI_INVALID_PARAMETER;                                           \
  66     DEBUG ((                                                                  \
  67       DEBUG_ERROR,                                                            \
  68       "ERROR: Get" #CmObjectId ": Invalid out parameter for"                  \
  69       " object list. Status = %r\n",                                          \
  70       Status                                                                  \
  71       ));                                                                     \
  72     goto error_handler;                                                       \
  73   }                                                                           \
  74   Status = CfgMgrProtocol->GetObject (                                        \
  75                              CfgMgrProtocol,                                  \
  76                              CREATE_CM_OBJECT_ID (                            \
  77                                CmObjectNameSpace,                             \
  78                                CmObjectId                                     \
  79                                ),                                             \
  80                              Token,                                           \
  81                              &CmObjectDesc                                    \
  82                              );                                               \
  83   if (EFI_ERROR (Status)) {                                                   \
  84     DEBUG ((                                                                  \
  85       DEBUG_INFO,                                                             \
  86       "INFO: Get" #CmObjectId ": Platform does not implement "                \
  87       #CmObjectId ". Status = %r\n",                                          \
  88       Status                                                                  \
  89       ));                                                                     \
  90     *List = NULL;                                                             \
  91     goto error_handler;                                                       \
  92   }                                                                           \
  93   if (CmObjectDesc.ObjectId !=                                                \
  94       CREATE_CM_OBJECT_ID (CmObjectNameSpace, CmObjectId)) {                  \
  95     DEBUG ((                                                                  \
  96       DEBUG_ERROR,                                                            \
  97       "ERROR: Get" #CmObjectId ": " #CmObjectId                               \
  98       ": Invalid ObjectId = 0x%x\n, expected Id = 0x%x\n",                    \
  99       CmObjectDesc.ObjectId,                                                  \
 100       CREATE_CM_OBJECT_ID (CmObjectNameSpace, CmObjectId)                     \
 101       ));                                                                     \
 102     ASSERT (FALSE);                                                           \
 103     Status = EFI_INVALID_PARAMETER;                                           \
 104     goto error_handler;                                                       \
 105   }                                                                           \
 106   if (CmObjectDesc.Size < (sizeof (Type) * CmObjectDesc.Count)) {             \
 107     DEBUG ((                                                                  \
 108       DEBUG_ERROR,                                                            \
 109       "ERROR: Get" #CmObjectId ": " #CmObjectId                               \
 110       ": Buffer too small, size = 0x%x\n",                                    \
 111       CmObjectDesc.Size                                                       \
 112       ));                                                                     \
 113     ASSERT (FALSE);                                                           \
 114     Status = EFI_BAD_BUFFER_SIZE;                                             \
 115     goto error_handler;                                                       \
 116   }                                                                           \
 117   ObjCount = CmObjectDesc.Count;                                              \
 118   *List = (Type*)CmObjectDesc.Data;                                           \
 119 error_handler:                                                                \
 120   if (Count != NULL) {                                                        \
 121     *Count = ObjCount;                                                        \
 122   }                                                                           \
 123   return Status;                                                              \
 124 }
 125
 126 #endif // CONFIGURATION_MANAGER_HELPER_H_