[PATCH 4/8] DynamicTablesPkg: Update ConfigurationManagerProtocol

["Tomas Pilar (tpilar)" <tomas@nuviainc.com>]

The Configuration Manager Protocol is updated to include
a FreeObject function that must be used by the callers to
GetObject to clean up any dynamic allocations and other resources
reserved by the Configuration Manager in the process of fulfilling the
request in GetObject.

A NULL inline static FreeObject function is provided for the ease
of transition for v1.0 managers.

Cc: Sami Mujawar <Sami.Mujawar@arm.com>
Cc: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Tomas Pilar <tomas@nuviainc.com>
---
 .../Protocol/ConfigurationManagerProtocol.h   | 83 ++++++++++++++++++-
 1 file changed, 80 insertions(+), 3 deletions(-)

diff --git a/DynamicTablesPkg/Include/Protocol/ConfigurationManagerProtocol.h b/DynamicTablesPkg/Include/Protocol/ConfigurationManagerProtocol.h
index 7de1be3b23..72bf3c79bc 100644
--- a/DynamicTablesPkg/Include/Protocol/ConfigurationManagerProtocol.h
+++ b/DynamicTablesPkg/Include/Protocol/ConfigurationManagerProtocol.h
@@ -25,7 +25,7 @@
 
 /** This macro defines the Configuration Manager Protocol Revision.
 */
-#define EDKII_CONFIGURATION_MANAGER_PROTOCOL_REVISION  CREATE_REVISION (1, 0)
+#define EDKII_CONFIGURATION_MANAGER_PROTOCOL_REVISION  CREATE_REVISION (1, 1)
 
 #pragma pack(1)
 
@@ -35,10 +35,18 @@
 typedef struct ConfigurationManagerProtocol EDKII_CONFIGURATION_MANAGER_PROTOCOL;
 typedef struct PlatformRepositoryInfo       EDKII_PLATFORM_REPOSITORY_INFO;
 
-/** The GetObject function defines the interface implemented by the
+/** The GetObject function defines the interface of the
     Configuration Manager Protocol for returning the Configuration
     Manager Objects.
 
+    If Token is CM_NULL_TOKEN, the function provides in its output all
+    the objects of the given CmObjectId. If the Token is not CM_NULL_TOKEN,
+    the function provides only those object that match both the CmObjectId
+    and Token.
+
+    The memory in CmObject.Data may be static or dynamic. The caller of this
+    function must call FreeObject on the CmObject populated by this function.
+
   @param [in]  This        Pointer to the Configuration Manager Protocol.
   @param [in]  CmObjectId  The Configuration Manager Object ID.
   @param [in]  Token       An optional token identifying the object. If
@@ -62,10 +70,24 @@ EFI_STATUS
   IN  OUT   CM_OBJ_DESCRIPTOR                     * CONST CmObject
   );
 
-/** The SetObject function defines the interface implemented by the
+/** The SetObject function defines the interface of the
     Configuration Manager Protocol for updating the Configuration
     Manager Objects.
 
+    If Token is CM_NULL_TOKEN, and CmObject is not NULL, then the objects
+    in the configuration manager that match the CmObjectId and do not
+    have an associated cross reference Token are replaced by the contents of
+    CmObject.
+
+    If Token is not CM_NULL_TOKEN and CmObject is not NULL, then the objects
+    that match both CmObjectId and Token in the configuration manager are
+    replaced with the contents of CmObject.
+
+    If CmObject is NULL, then objects that match the CmObjectId and Token
+    are removed from the configuration manager. If Token is also CM_NULL_TOKEN,
+    then all objects of given CmObjectId are removed, regardless of their
+    cross-reference Token.
+
   @param [in]  This        Pointer to the Configuration Manager Protocol.
   @param [in]  CmObjectId  The Configuration Manager Object ID.
   @param [in]  Token       An optional token identifying the object. If
@@ -90,6 +112,29 @@ EFI_STATUS
   IN        CM_OBJ_DESCRIPTOR                     * CONST CmObject
   );
 
+/** The FreeObject function defines the interface of the
+    Configuration Manager Protocol for correctly freeing resources
+    that have been reserved by calls to the GetObject interface.
+
+    The caller of GetObject must use this function to dispose of CmObject
+    populated by the GetObject call when the CmObject is no longer needed.
+
+    If an implementation of the Configuration Manager Protocol does not
+    use dynamically allocated memory, this function should simply return
+    EFI_SUCCESS.
+
+    @param [in]  This         Pointer to the Configuration Manager Protocol
+    @param [in]  CmObject     Pointer to the CmObject that has been populated
+                              by the GetObject function and is to be destroyed.
+    @retval EFI_SUCCESS       The CmObject was successfully destroyed
+**/
+typedef
+EFI_STATUS
+(EFIAPI * EDKII_CONFIGURATION_MANAGER_FREE_OBJECT) (
+  IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST This,
+  IN        CM_OBJ_DESCRIPTOR                     *       CmObject
+  );
+
 /** The EDKII_CONFIGURATION_MANAGER_PROTOCOL structure describes the
     Configuration Manager Protocol interface.
 */
@@ -111,12 +156,44 @@ typedef struct ConfigurationManagerProtocol {
       provisioned by the Configuration Manager.
   */
   EDKII_PLATFORM_REPOSITORY_INFO        * PlatRepoInfo;
+
+  /** The interface used to destroy CmObject instances
+      populated by calls to GetObject
+  */
+  EDKII_CONFIGURATION_MANAGER_FREE_OBJECT FreeObject;
 } EDKII_CONFIGURATION_MANAGER_PROTOCOL;
 
 /** The Configuration Manager Protocol GUID.
 */
 extern EFI_GUID gEdkiiConfigurationManagerProtocolGuid;
 
+/** Inline NULL implementation of FreeObject for backward compatibility
+    of configuration managers that do not require to deallocate any
+    memory following a call to GetObject.
+
+    @param[in] This       Pointer to Configuration Manager Protocol instance
+    @param[in] CmObject   Pointer to CmObject populated by GetObject
+
+    @retval EFI_SUCCESS            Successfully handled CmObject.
+    @retval EFI_INVALID_PARAMETER  CmObject is NULL.
+    @retval EFI_INVALID_PARAMETER  This is NULL.
+    @retval EFI_INVALID_PARAMETER  CmObject is not valid.
+**/
+static
+inline
+EFI_STATUS
+EFIAPI EdkiiCfgMgrFreeObjectNull (
+  IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST This,
+  IN        CM_OBJ_DESCRIPTOR                     *       CmObject
+  )
+{
+  if (!This || !CmObject) {
+    return EFI_INVALID_PARAMETER;
+  }
+
+  return EFI_SUCCESS;
+}
+
 #pragma pack()
 
 #endif // CONFIGURATION_MANAGER_PROTOCOL_H_
-- 
2.25.1