From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by spool.mail.gandi.net (Postfix) with ESMTPS id 58AEA740040 for ; Wed, 23 Aug 2023 08:53:29 +0000 (UTC) DKIM-Signature: a=rsa-sha256; bh=YM401xG2H/6EMiFQHYIpzsomIdD4wu+6V34r2I14DDg=; c=relaxed/simple; d=groups.io; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version:Precedence:List-Subscribe:List-Help:Sender:List-Id:Mailing-List:Delivered-To:Reply-To:List-Unsubscribe-Post:List-Unsubscribe:Content-Transfer-Encoding; s=20140610; t=1692780807; v=1; b=HZ7qDRmTxGSA2Nib6mAcERHzipI8UGkFx62pIDeiOx+Fl4n9JEFE5+twxDOYbLFia05dcx5s 0PhTala/VWdkRGNJM6fD8t3ITG8g1+d9ydUeG+wHIilVpXl9hnf0RlK/UN0xGcxxiDPe/AcDKwn 5D6kWW46FVbqIxtIWFGwqPBg= X-Received: by 127.0.0.2 with SMTP id 0H6xYY7687511xHQM7cp3qon; Wed, 23 Aug 2023 01:53:27 -0700 X-Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mx.groups.io with SMTP id smtpd.web10.7253.1692780806660670572 for ; Wed, 23 Aug 2023 01:53:27 -0700 X-Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id C36B61042; Wed, 23 Aug 2023 01:54:06 -0700 (PDT) X-Received: from josmar02Desktop.cambridge.arm.com (josmar02Desktop.cambridge.arm.com [10.2.78.53]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 59EF23F740; Wed, 23 Aug 2023 01:53:25 -0700 (PDT) From: "Jose Marinho" To: devel@edk2.groups.io Cc: Jose Marinho , Sami Mujawar , Pierre Gondois , Samer El-Haj-Mahmoud Subject: [edk2-devel] [PATCH v2] DynamicTablesPkg: HOWTO for Handcrafted tables Date: Wed, 23 Aug 2023 09:53:13 +0100 Message-Id: <20230823085313.792752-1-jose.marinho@arm.com> MIME-Version: 1.0 Precedence: Bulk List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,jose.marinho@arm.com List-Unsubscribe-Post: List-Unsubscribe=One-Click List-Unsubscribe: X-Gm-Message-State: oK4ycIYaU1YvUNPZSd5T3nglx7686176AA= Content-Transfer-Encoding: quoted-printable X-GND-Status: LEGIT Authentication-Results: spool.mail.gandi.net; dkim=pass header.d=groups.io header.s=20140610 header.b=HZ7qDRmT; dmarc=fail reason="SPF not aligned (relaxed), DKIM not aligned (relaxed)" header.from=arm.com (policy=none); spf=pass (spool.mail.gandi.net: domain of bounce@groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce@groups.io Update the DynamicTablesPkg documentation to explain how to specify ACPI tables in RAW format, or when there are no defined table generators. Cc: Sami Mujawar Cc: Pierre Gondois Cc: Samer El-Haj-Mahmoud Signed-off-by: Jose Marinho --- DynamicTablesPkg/Readme.md | 120 +++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/DynamicTablesPkg/Readme.md b/DynamicTablesPkg/Readme.md index 6b0a6c7a40..c691d2caeb 100644 --- a/DynamicTablesPkg/Readme.md +++ b/DynamicTablesPkg/Readme.md @@ -157,6 +157,126 @@ performed, and validate the generated output. - Disassemble the generated AML using the iASL compiler and verifying the output. =20 +### Bespoke ACPI tables + +The Dynamic Tables framework supports the creation of several tables usi= ng +standard generators, see Feature Summary Section for a list of such tabl= es. + +The supported platforms already contain several tables. +If a table is not present for the platform, two alternative processes ca= n be followed: + +- define the table in using ASL, +- define the table in packed C structures (also known as RAW). + +The two approaches are detailed below. + +#### Adding an ASL table for which the Dynamic Tables Framework does not= provide a standard generator + +This method creates the SSDT table from the ASL source, using a standard= generator. +Perform the following steps: + +1. Create the table source file, placing it within the ConfigurationMana= ger source tree, e.g.: + +Create a file Platform/ARM/VExpressPkg/ConfigurationManager/Configuratio= nManagerDxe/AslTables/NewTableSource.asl +with the following contents: + +``` +DefinitionBlock ("", "SSDT", 2, "XXXXXX", "XXXXXXXX", 1) { + Scope(_SB) { + Device(FLA0) { + Name(_HID, "XXXX0000") + Name(_UID, 0) + + // _DSM - Device Specific Method + Function(_DSM,{IntObj,BuffObj},{BuffObj, IntObj, IntObj, PkgObj}) + { + W0 =3D 0x1 + return (W0) + } + } + } +} +``` + +2. Reference the table source file in ConfigurationMangerDxe.inf + +``` + [Sources] + AslTables/NewTableSource.asl +``` + +3. Update the ConfigurationManager.h file +Platform/ARM/VExpressPkg/ConfigurationManager/ConfigurationManagerDxe/Co= nfigurationManager.h + + 1. Add an array to hold the AML code: +``` + extern CHAR8 newtablesource_aml_code[]; +``` + +Note: the array name is composed of the ASL source file name all in lowe= r case, followed by the _aml_code postfix. + +4. Increment the macro PLAT_ACPI_TABLE_COUNT + +5. Add a new CM_STD_OBJ_ACPI_TABLE_INFO structure entry and initialise. + + - the entry contains: + - the table signature, + - the table revision (unused in this case), + - the ID of the standard generator to be used (the SSDT generator in= this case). + - a pointer to the AML code, + +``` + // Table defined in the NewTableSource.asl file + { + EFI_ACPI_6_4_SECONDARY_SYSTEM_DESCRIPTION_TABLE_SIGNATURE, + 0, // Unused + CREATE_STD_ACPI_TABLE_GEN_ID (EStdAcpiTableIdSsdt), + (EFI_ACPI_DESCRIPTION_HEADER*)newtablesource_aml_code + }, +``` + +#### Add a RAW table for which there is no standard generator + +An ACPI table can be defined as a packed C struct in the C source code. = This is referred to as the "raw" table format. +The steps to create a table in raw format are detailed below: + +1. Define the table in a C source file and populate the ACPI table struc= ture field with the required values. + + For example, create the file Platform/ARM/VExpressPkg/ConfigurationMa= nager/ConfigurationManagerDxe/RawTable.c + +``` + // Example creating the HMAT in raw format + EFI_ACPI_HETEROGENEOUS_MEMORY_ATTRIBUTE_TABLE Hmat =3D { + ... + }; +``` + +2. Reference the table source file in ConfigurationMangerDxe.inf + +``` + [Sources] + RawTable.c +``` + +2. Increment the macro PLAT_ACPI_TABLE_COUNT + +3. Add a new CM_STD_OBJ_ACPI_TABLE_INFO structure entry and initialise. + + - the entry contains: + - the table signature, + - the table revision, + - the RAW generator ID. + - a pointer to the C packed struct that defines the table, + +``` + { + EFI_ACPI_6_3_HETEROGENEOUS_MEMORY_ATTRIBUTE_TABLE_SIGNATURE, + EFI_ACPI_6_3_HETEROGENEOUS_MEMORY_ATTRIBUTE_TABLE_REVISION, + CREATE_STD_ACPI_TABLE_GEN_ID (EStdAcpiTableIdRaw), + (EFI_ACPI_DESCRIPTION_HEADER*)&Hmat + }, +``` + # Roadmap =20 The current implementation of the Configuration Manager populates the --=20 2.40.0.141.g8d90352acc -=-=-=-=-=-=-=-=-=-=-=- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#107972): https://edk2.groups.io/g/devel/message/107972 Mute This Topic: https://groups.io/mt/100911254/7686176 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [rebecca@openfw.io] -=-=-=-=-=-=-=-=-=-=-=-