Skip to content

Overview

  • Feature Name: ACPI Debug
  • PI Phase(s) Supported: DXE and SMM
  • SMM Required? No

Purpose

This feature is an alternative ACPI debug mechanism to port 0x80 or a kernel debugger such as WinDBG.

DO NOT use this feature in a production system. It may not handle SMM memory buffers or data input/output from SMM in a safe manner.

High-Level Theory of Operation

There are two driver modes: 1. DXE - ACPI debug messages should be manually read from a memory buffer on the target machine using a utility that has the ability to read main memory. 2. SMM - ACPI debug messages should be read from the firmware debug message output port.

The DXE driver is required and the SMM driver is optional. The SMM driver eases retrieval of the ACPI debug messages from a message ring buffer in memory by sending the messages over the SMM debug mechanism. ASL code writes messages up to 32 characters in length (shorter strings will be padded with zeroes and longer strings will be truncated) to an ASL debug method.

Firmware Volumes

  • FvAdvancedPostMemory

Modules

  • AcpiDebugDxe
  • AcpiDebugSmm

AcpiDebugDxe

The entry point registers an end of DXE notification. Further action is deferred until end of DXE to allow the feature PCDs to be customized at boot time in DXE if desired. The notification handler allocates a EfiReservedMemoryType buffer (memory not available to the operating system) of the size specified in PcdAcpiDebugBufferSize. The actual buffer size is allocated on a page boundary of size EFI_PAGE_SIZE. The allocated buffer address is written out as a debug message AcpiDebugAddress - 0xXXXXXXXX. In addition, the address is written to PcdAcpiDebugAddress and the actual allocation size is written to PcdAcpiDebugBufferSize.

To expose the ACPI debug buffer to ASL code, an ACPI debug SSDT (defined in AcpiDebug.asl) is installed. The pointer fields in the SSDT are patched by AcpiDebugDxe to the actual buffer address. The SSDT is installed using the EFI_ACPI_TABLE_PROTOCOL.

AcpiDebugSmm

The entry point registers an end of DXE notification. Further action is deferred until end of DXE to allow the feature PCDs to be customized at boot time if desired. The notification handler registers a SW SMI that can be triggered in ACPI debug SSDT to invoke the SMI handler AcpiDebugSmmCallback (). The SMI handler retrieves the debug message from the buffer at PcdAcpiDebugAddress and sends it to the DEBUG function for the given SMM DebugLib instance assigned to AcpiDebugSmm.

Key Functions

  • MDBG (ASL method)

This method is given a single argument with a number or string to write to the ACPI memory debug buffer. If AcpiDebugSmm is used, an SMI will be used to send the message as a DEBUG message.

It is recommended to instrument the ASL code with a method called ADBG. An ASL caller sends a debug message as follows:

ADBG("This is a test.")
ADBG(Arg0)
  • ADBG (ASL method) is intended to be a wrapper of MDBG that allows the ADBG references to remain in the ASL code even if the ACPI debug advanced feature is disabled. Below is a code snippet with a sample implementation for ADBG.
External (MDBG, MethodObj)
Method (ADBG, 1, Serialized)
{
  If (CondRefOf (MDBG)) // Check if ACPI Debug SSDT is loaded
  {
    Return (MDBG (Arg0))
  }
  Return (0)
}

Configuration

  • PcdAcpiDebugEnable - Enables this feature.
  • PcdAcpiDebugFeatureActive - Activates this feature.
  • PcdAcpiDebugAddress - The address of the ACPI debug message buffer.
  • PcdAcpiDebugBufferSize - The size of the ACPI debug message buffer.

Data Flows

TODO Architecturally defined data structures and flows for the feature.

Control Flows

TODO Key control flows for the feature.

Build Flows

TODO Any special build flows should be described in this section.

This is particularly useful for features that use custom build tools or require non-standard tool configuration. If the standard flow in the feature package template is used, this section may be empty.

Test Point Results

TODO The test(s) that can verify porting is complete for the feature.

Each feature must describe at least one test point to verify the feature is successful. If the test point is not implemented, this should be stated.

Functional Exit Criteria

TODO The testable functionality for the feature.

This section should provide an ordered list of criteria that a board integrator can reference to ensure the feature is functional on their board.

Feature Enabling Checklist

TODO An ordered list of required activities to achieve desired functionality for the feature.

Performance Impact

A general expectation for the impact on overall boot performance due to using this feature.

This section is expected to provide guidance on: * How to estimate performance impact due to the feature * How to measure performance impact of the feature * How to manage performance impact of the feature

Common Optimizations

TODO Common size or performance tuning options for this feature.

This section is recommended but not required. If not used, the contents should be left empty.