DynamicTablesPkg: AML code generation to Return a NameString

Add AmlCodeGenReturnNameString() to generate AML code for a
Return object node, returning the object as a NameString.

AmlCodeGenReturn ("NAM1", ParentNode, NewObjectNode) is
equivalent of the following ASL code:
  Return(NAM1)

Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>

DynamicTablesPkg/Library/Common/AmlLib/CodeGen/AmlCodeGen.c

@@ -1154,3 +1154,184 @@ error_handler1:
   }
   return Status;
 }
+
+/** AML code generation for a Return object node.
+
+  AmlCodeGenReturn (ReturnNode, ParentNode, NewObjectNode) is
+  equivalent of the following ASL code:
+    Return([Content of the ReturnNode])
+
+  The ACPI 6.3 specification, s20.2.5.3 "Type 1 Opcodes Encoding" states:
+    DefReturn := ReturnOp ArgObject
+    ReturnOp := 0xA4
+    ArgObject := TermArg => DataRefObject
+
+  Thus, the ReturnNode must be evaluated as a DataRefObject. It can
+  be a NameString referencing an object. As this CodeGen Api doesn't
+  do semantic checking, it is strongly advised to check the AML bytecode
+  generated by this function against an ASL compiler.
+
+  The ReturnNode must be generated inside a Method body scope.
+
+  @param [in]  ReturnNode     The object returned by the Return ASL statement.
+                              This node is deleted if an error occurs.
+  @param [in]  ParentNode     If provided, set ParentNode as the parent
+                              of the node created.
+                              Must be a MethodOp node.
+  @param [out] NewObjectNode  If success, contains the created node.
+
+  @retval EFI_SUCCESS             Success.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlCodeGenReturn (
+  IN  AML_NODE_HEADER     * ReturnNode,
+  IN  AML_NODE_HEADER     * ParentNode,     OPTIONAL
+  OUT AML_OBJECT_NODE    ** NewObjectNode   OPTIONAL
+  )
+{
+  EFI_STATUS        Status;
+  AML_OBJECT_NODE * ObjectNode;
+
+  if ((ReturnNode == NULL)                              ||
+      ((ParentNode == NULL) && (NewObjectNode == NULL)) ||
+      ((ParentNode != NULL) &&
+        !AmlNodeCompareOpCode (
+            (AML_OBJECT_NODE*)ParentNode, AML_METHOD_OP, 0))) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  Status = AmlCreateObjectNode (
+             AmlGetByteEncodingByOpCode (AML_RETURN_OP, 0),
+             0,
+             &ObjectNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto error_handler;
+  }
+
+  Status = AmlSetFixedArgument (
+             ObjectNode,
+             EAmlParseIndexTerm0,
+             (AML_NODE_HEADER*)ReturnNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto error_handler;
+  }
+
+  ReturnNode = NULL;
+
+  Status = LinkNode (
+             ObjectNode,
+             ParentNode,
+             NewObjectNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto error_handler;
+  }
+
+  return Status;
+
+error_handler:
+  if (ReturnNode != NULL) {
+    AmlDeleteTree (ReturnNode);
+  }
+  if (ObjectNode != NULL) {
+    AmlDeleteTree ((AML_NODE_HEADER*)ObjectNode);
+  }
+  return Status;
+}
+
+/** AML code generation for a Return object node,
+    returning the object as an input NameString.
+
+  AmlCodeGenReturn ("NAM1", ParentNode, NewObjectNode) is
+  equivalent of the following ASL code:
+    Return(NAM1)
+
+  The ACPI 6.3 specification, s20.2.5.3 "Type 1 Opcodes Encoding" states:
+    DefReturn := ReturnOp ArgObject
+    ReturnOp := 0xA4
+    ArgObject := TermArg => DataRefObject
+
+  Thus, the ReturnNode must be evaluated as a DataRefObject. It can
+  be a NameString referencing an object. As this CodeGen Api doesn't
+  do semantic checking, it is strongly advised to check the AML bytecode
+  generated by this function against an ASL compiler.
+
+  The ReturnNode must be generated inside a Method body scope.
+
+  @param [in]  NameString     The object referenced by this NameString
+                              is returned by the Return ASL statement.
+                              Must be a NULL-terminated ASL NameString
+                              e.g.: "NAM1", "_SB.NAM1", etc.
+                              The input string is copied.
+  @param [in]  ParentNode     If provided, set ParentNode as the parent
+                              of the node created.
+                              Must be a MethodOp node.
+  @param [out] NewObjectNode  If success, contains the created node.
+
+  @retval EFI_SUCCESS             Success.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    Failed to allocate memory.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+AmlCodeGenReturnNameString (
+  IN  CONST CHAR8               * NameString,
+  IN        AML_NODE_HEADER     * ParentNode,     OPTIONAL
+  OUT       AML_OBJECT_NODE    ** NewObjectNode   OPTIONAL
+  )
+{
+  EFI_STATUS          Status;
+  AML_DATA_NODE     * DataNode;
+  CHAR8             * AmlNameString;
+  UINT32              AmlNameStringSize;
+
+  DataNode = NULL;
+
+  Status = ConvertAslNameToAmlName (NameString, &AmlNameString);
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    return Status;
+  }
+
+  Status = AmlGetNameStringSize (AmlNameString, &AmlNameStringSize);
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+  Status = AmlCreateDataNode (
+             EAmlNodeDataTypeNameString,
+             (UINT8*)AmlNameString,
+             AmlNameStringSize,
+             &DataNode
+             );
+  if (EFI_ERROR (Status)) {
+    ASSERT (0);
+    goto exit_handler;
+  }
+
+  // AmlCodeGenReturn() deletes DataNode if error.
+  Status = AmlCodeGenReturn (
+             (AML_NODE_HEADER*)DataNode,
+             ParentNode,
+             NewObjectNode
+             );
+  ASSERT_EFI_ERROR (Status);
+
+exit_handler:
+  if (AmlNameString != NULL) {
+    FreePool (AmlNameString);
+  }
+  return Status;
+}