DynamicTablesPkg/Library/FdtHwInfoParserLib/CmObjectDescUtility.h

   1 /** @file
   2   Configuration manager Object Descriptor Utility.
   3
   4   Copyright (c) 2021, ARM Limited. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6 **/
   7
   8 #ifndef CM_OBJECT_DESC_UTILITY_H_
   9 #define CM_OBJECT_DESC_UTILITY_H_
  10
  11 #include <ConfigurationManagerObject.h>
  12
  13 #include "FdtHwInfoParser.h"
  14
  15 /** Create a CM_OBJ_DESCRIPTOR.
  16
  17   @param [in]  ObjectId       CM_OBJECT_ID of the node.
  18   @param [in]  Count          Number of CmObj stored in the
  19                               data field.
  20   @param [in]  Data           Pointer to one or more CmObj objects.
  21                               The content of this Data buffer is copied.
  22   @param [in]  Size           Size of the Data buffer.
  23   @param [out] NewCmObjDesc   The created CM_OBJ_DESCRIPTOR.
  24
  25   @retval EFI_SUCCESS             The function completed successfully.
  26   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  27   @retval EFI_OUT_OF_RESOURCES    An allocation has failed.
  28 **/
  29 EFI_STATUS
  30 EFIAPI
  31 CreateCmObjDesc (
  32   IN  CM_OBJECT_ID       ObjectId,
  33   IN  UINT32             Count,
  34   IN  VOID               *Data,
  35   IN  UINT32             Size,
  36   OUT CM_OBJ_DESCRIPTOR  **NewCmObjDesc
  37   );
  38
  39 /** Free resources allocated for the CM_OBJ_DESCRIPTOR.
  40
  41   @param [in] CmObjDesc           Pointer to the CM_OBJ_DESCRIPTOR.
  42
  43   @retval EFI_SUCCESS             The function completed successfully.
  44   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  45 **/
  46 EFI_STATUS
  47 EFIAPI
  48 FreeCmObjDesc (
  49   IN CM_OBJ_DESCRIPTOR  *CmObjDesc
  50   );
  51
  52 /** Add a single CmObj to the Configuration Manager.
  53
  54   @param  [in]  FdtParserHandle   A handle to the parser instance.
  55   @param  [in]  ObjectId          CmObj ObjectId.
  56   @param  [in]  Data              CmObj Data.
  57   @param  [in]  Size              CmObj Size.
  58   @param  [out] Token             If provided and success,
  59                                   token generated for this CmObj.
  60
  61   @retval EFI_SUCCESS             The function completed successfully.
  62   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  63 **/
  64 EFI_STATUS
  65 EFIAPI
  66 AddSingleCmObj (
  67   IN  CONST FDT_HW_INFO_PARSER_HANDLE  FdtParserHandle,
  68   IN        CM_OBJECT_ID               ObjectId,
  69   IN        VOID                       *Data,
  70   IN        UINT32                     Size,
  71   OUT       CM_OBJECT_TOKEN            *Token    OPTIONAL
  72   );
  73
  74 /** Add multiple CmObj to the Configuration Manager.
  75
  76   @param  [in]  FdtParserHandle   A handle to the parser instance.
  77   @param  [in]  CmObjDesc         CmObjDesc containing multiple CmObj
  78                                   to add.
  79   @param  [in]  TokenCount        If provided, count of entries in the
  80                                   TokenTable.
  81   @param  [out] TokenTable        If provided and success,
  82                                   token generated for these CmObj.
  83                                   Address of an array of CM_OBJECT_TOKEN
  84                                   with the same number of elements as the
  85                                   CmObjDesc.
  86
  87   @retval EFI_SUCCESS             The function completed successfully.
  88   @retval EFI_INVALID_PARAMETER   Invalid parameter.
  89 **/
  90 EFI_STATUS
  91 EFIAPI
  92 AddMultipleCmObj (
  93   IN  CONST FDT_HW_INFO_PARSER_HANDLE FdtParserHandle,
  94   IN  CONST CM_OBJ_DESCRIPTOR *CmObjDesc,
  95   IN        UINT32 TokenCount, OPTIONAL
  96   OUT       CM_OBJECT_TOKEN             *TokenTable   OPTIONAL
  97   );
  98
  99 /** Add multiple CmObj to the Configuration Manager.
 100
 101   Get one token referencing a EArmObjCmRef CmObj itself referencing
 102   the input CmObj. In the table below, RefToken is returned.
 103
 104   Token referencing an      Array of tokens             Array of CmObj
 105   array of EArmObjCmRef     referencing each            from the input:
 106   CmObj:                    CmObj from the input:
 107
 108   RefToken         --->     CmObjToken[0]        --->   CmObj[0]
 109                             CmObjToken[1]        --->   CmObj[1]
 110                             CmObjToken[2]        --->   CmObj[2]
 111
 112   @param  [in]  FdtParserHandle   A handle to the parser instance.
 113   @param  [in]  CmObjDesc         CmObjDesc containing multiple CmObj
 114                                   to add.
 115   @param  [out] Token             If success, token referencing an array
 116                                   of EArmObjCmRef CmObj, themselves
 117                                   referencing the input CmObjs.
 118
 119   @retval EFI_SUCCESS             The function completed successfully.
 120   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 121   @retval EFI_OUT_OF_RESOURCES    An allocation has failed.
 122 **/
 123 EFI_STATUS
 124 EFIAPI
 125 AddMultipleCmObjWithCmObjRef (
 126   IN  CONST FDT_HW_INFO_PARSER_HANDLE  FdtParserHandle,
 127   IN  CM_OBJ_DESCRIPTOR                *CmObjDesc,
 128   OUT CM_OBJECT_TOKEN                  *Token
 129   );
 130
 131 #endif // CM_OBJECT_DESC_UTILITY_H_