xref: /src/sys/external/bsd/acpica/dist/compiler/new_table.txt

How to add a new ACPI table to ACPICA and the iASL compiler.
------------------------------------------------------------

There are four main tasks that are needed to provide support for a
new ACPI table:
    1) Create a full definition of the table and any subtables
       in the ACPICA headers.
    2) Add disassembler support for the new table
    3) Add iASL table compiler support for the new table
    4) Create a default template for the new table for iASL -T
       option.

Notes for each of these tasks provided below.


1) Header Support
-----------------

New tables should be added to the appropriate header:
    actbl2.h: Used for new tables that are not defined in the ACPI spec.
    actbl3.h: Used for new tables that are defined in the ACPI spec.

Use ACPI_TABLE_HEADER for the common ACPI table header.
Subtables should be defined separately from the main table.
Don't add placeholder fields for subtables and other multiple data items.
    (Don't use xxxxx[1] for a field that can have multiple items.)
    The disassembler and data table compiler depends on this.
For tables not defined in the ACPI spec, add a comment to indicate where
    the table came from.
Use other table definitions for additional guidance.


2) iASL Disassembler Support
----------------------------

Add definition of the table (and subtables) in common/dmtbinfo.c
Add table access macro(s) of the form ACPI_xxxx_OFFSET
Add ACPI_DMT_TERMINATOR at the end of every table/subtable definition

Add externals for the table/subtable definitions in acdisasm.h
Add an entry for the new table in the AcpiDmTableData in common/dmtable.c

If there are no subtables, add the AcpiDmTableInfoXXXX name to the
    AcpiDmTableData and it will automatically be disassembled.

If there are subtables, a dump routine must be written:
Add an AcpiDmDumpXXXX function to dmtbdump.c -- note, code for another
    similar table can often be ported for the new table.
Add an external for this function to acdisasm.h
Add this function to the AcpiDmTableData entry for the new ACPI table

Debug/Test: Either find an existing example of the new ACPI table, or
    create one using the "generic ACPI table support" included in the
    iASL data table compiler. Use the -G option to force a
    generic compile. It is often best to create the table from scratch,
    since this clearly exposes the dependencies (lengths, offsets, etc.)
    that the Table Compiler support will need to generate.


3) iASL Table Compiler Support
------------------------------

Simple tables do not require a compile routine. The definition of the
    table in common/dmtbinfo.c (created in step 2 above) will suffice.

Complex tables with subtables will require a compile routine with a name
    of the form DtCompileXXXX.
Add a DtCompileXXXX function to the dttable.c module.
Add an external for this function in dtcompiler.h
Add this function to the AcpiDmTableData entry for the new ACPI table
    in common/dmtable.c


4) Template Support (-T iASL option)
------------------------------------

Create an example of the new ACPI table. This example should create
    multiple subtables (if supported), and multiple instances of any
    variable length data.

Compile the example file with the -sc option. This will create a C
    array that contains the table contents.

Add this array to the dttemplate.h file. Name the array TemplateXXXX.
Add this array name to the AcpiDmTableData entry for the new ACPI table

Debug/Test: Create the template file. Compile the file. Disassemble the file.
    Compile the disassembly file.