DynamicTablesPkg/Include/ConfigurationManagerHelper.h

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