ACPI resource settings. More...

Collaboration diagram for Resources:

Detailed Description

ACPI resource settings.

In the AML namespace heirarchy each device uses a buffer object, usually returned by their _CRS method, to describe the resources they require, for example IO ports, IRQs, DMA channels, etc.

For the vast majority of use cases, its recommended to use the device abstraction layer provided by the devices.h file or Devices instead of directly parsing these overcomplicated structures.

Example

So, lets take a PS2 keyboard as an example. The PS2 keyboard device will have _CRS method that when evaluated will return a buffer object. This buffer object will contain data in the format outlined by the structures within this section, which describe the IO ports and the IRQ that the keyboard expects to use, most likely IO ports 0x60 and 0x64 and IRQ 1. Much more could be described, like IRQ trigger modes, polarity, DMA channels, etc. but this is a simple example.

Resource Data Format

The resource data is made up of a series of resource descriptors of varying formats and lengths. All descriptor types are either "small" or "large", depending on the value of the first byte of the descriptor, which decides the header used by the descriptor. After the header comes the actual data for the descriptor, which is descriptor specific, finally either another descriptor follows or the end of the resource data is reached, indicated by the "End Tag" descriptor.

Helpers

Since the resource descriptor format is kinda messy, a abstraction layer is provided in the form of helper macros which should always be used instead of directly parsing the resource data.

See also: Section 6.4 of the ACPI specification for more details.

Data Structures
struct	acpi_resource_small_t
	ACPI small resource header. More...

struct	acpi_resource_large_t
	ACPI large resource header. More...

struct	acpi_irq_descriptor_t
	ACPI IRQ resource descriptor. More...

struct	acpi_io_port_descriptor_t
	ACPI IO port resource descriptor. More...

struct	acpi_end_tag_t
	ACPI end tag resource descriptor. More...

struct	acpi_resources_t
	ACPI resources structure. More...

struct	acpi_resource_t
	Generic ACPI resource descriptor. More...

Macros
#define	ACPI_IRQ_DESCRIPTOR_INFO(descriptor)
	Retrieves the IRQ descriptor info flags from an IRQ resource descriptor.

#define	ACPI_RESOURCE_ITEM_NAME(resource)
	Helper macro to get the generic item name of a resource descriptor.

#define	ACPI_RESOURCE_SIZE(resource)
	Helper macro to get the size of a resource descriptor.

#define	ACPI_RESOURCES_FOR_EACH(resource, resources)
	Helper macro to iterate over all resource descriptors in an ACPI resources structure.

Enumerations
enum	acpi_irq_descriptor_info_t { ACPI_IRQ_LEVEL_TRIGGERED = 0 << 0 , ACPI_IRQ_EDGE_TRIGGERED , ACPI_IRQ_ACTIVE_HIGH = 0 << 3 , ACPI_IRQ_ACTIVE_LOW = 1 << 3 , ACPI_IRQ_SHARED = 0 << 4 , ACPI_IRQ_EXCLUSIVE = 1 << 4 , ACPI_IRQ_NOT_WAKE_CAPABLE = 0 << 5 , ACPI_IRQ_WAKE_CAPABLE , ACPI_IRQ_RESERVED1 = 1 << 6 , ACPI_IRQ_RESERVED2 = 1 << 7 }
	ACPI IRQ descriptor info flags. More...

enum	acpi_item_name_small_t { ACPI_ITEM_SMALL_IRQ = 0x04 , ACPI_ITEM_SMALL_IO_PORT = 0x08 , ACPI_ITEM_SMALL_END_TAG = 0x0F }
	Small ACPI resource item names. More...

enum	acpi_item_name_large_t { ACPI_LARGE_ITEM_24_MEM_RANGE = 0x01 }
	Large ACPI resource item names. More...

enum	acpi_item_name_t { ACPI_ITEM_NAME_IRQ = ACPI_ITEM_SMALL_IRQ , ACPI_ITEM_NAME_IO_PORT = ACPI_ITEM_SMALL_IO_PORT , ACPI_ITEM_NAME_END_TAG = ACPI_ITEM_SMALL_END_TAG , ACPI_ITEM_NAME_LARGE_BASE = 0x100 , ACPI_ITEM_NAME_24_MEM_RANGE = ACPI_ITEM_NAME_LARGE_BASE + ACPI_LARGE_ITEM_24_MEM_RANGE }
	Generic ACPI resource item names. More...

Functions
acpi_resources_t *	acpi_resources_current (aml_object_t *device)
	Get the current ACPI resource settings for a device.

void	acpi_resources_free (acpi_resources_t *resources)
	Free an ACPI resources structure.

Macro Definition Documentation

◆ ACPI_IRQ_DESCRIPTOR_INFO

#define ACPI_IRQ_DESCRIPTOR_INFO ( descriptor )

Value:

    ((acpi_irq_descriptor_info_t)((descriptor)->header.length >= 3 \
            ? *((((uint8_t*)(descriptor)) + sizeof(acpi_irq_descriptor_t))) \
            : 0))

Retrieves the IRQ descriptor info flags from an IRQ resource descriptor.

Will assume all zeroes if the optional third byte is not present.

Parameters

descriptor Pointer to an acpi_irq_descriptor_t structure.

Returns: The IRQ descriptor info flags as an acpi_irq_descriptor_info_t value.

Definition at line 115 of file resources.h.

◆ ACPI_RESOURCE_ITEM_NAME

#define ACPI_RESOURCE_ITEM_NAME ( resource )

Value:

    (((resource)->isLarge) \
            ? (acpi_item_name_t)(ACPI_ITEM_NAME_LARGE_BASE + ((acpi_resource_large_t*)(resource))->itemName) \
            : (acpi_item_name_t)((acpi_resource_small_t*)(resource))->itemName)

Helper macro to get the generic item name of a resource descriptor.

Abstracts away the difference between small and large resource descriptors, after this any resource can be type cast to the expected structure based on the returned item name.

Parameters

resource Pointer to an acpi_resource_t structure.

Returns: The item name of the resource descriptor as an acpi_item_name_t value.

Definition at line 243 of file resources.h.

◆ ACPI_RESOURCE_SIZE

#define ACPI_RESOURCE_SIZE ( resource )

Value:

(((resource)->isLarge) ? ((acpi_resource_large_t*)(resource))->length + sizeof(acpi_resource_large_t) \

: ((acpi_resource_small_t*)(resource))->length + sizeof(acpi_resource_small_t))

Helper macro to get the size of a resource descriptor.

Parameters

resource Pointer to an acpi_resource_t structure.

Returns: The size of the entire resource descriptor, including the header.

Definition at line 254 of file resources.h.

◆ ACPI_RESOURCES_FOR_EACH

#define ACPI_RESOURCES_FOR_EACH	(	resource,
		resources
	)

Value:

    for (uint8_t* __ptr = (resources)->data; \
        (__ptr < (resources)->data + (resources)->length) && ((resource) = (acpi_resource_t*)__ptr) && \
        (__ptr + ACPI_RESOURCE_SIZE(resource) <= (resources)->data + (resources)->length); \
        __ptr += ACPI_RESOURCE_SIZE(resource))

Helper macro to iterate over all resource descriptors in an ACPI resources structure.

Works by initializing a pointer to the start of the resource data and then iterating over each descriptor by checking if its a small or large descriptor, retreving its size, and moving the pointer forward by that size.

Parameters

resource	Pointer to an `acpi_resource_t` structure that will be set to each resource descriptor in the iteration.
resources	The `acpi_resources_t` structure to iterate over.

Definition at line 268 of file resources.h.

Enumeration Type Documentation

◆ acpi_irq_descriptor_info_t

enum acpi_irq_descriptor_info_t

ACPI IRQ descriptor info flags.

Stored in the optional third byte of the IRQ resource descriptor, if the third byte is not present then assume "edge sensitive, high true interrupts", as in all zeroes.

Enumerator
ACPI_IRQ_LEVEL_TRIGGERED	Interrupt is triggered in response to signal in a low state.
ACPI_IRQ_EDGE_TRIGGERED	Interrupt is triggered in response to a change in signal state from low to high.
ACPI_IRQ_ACTIVE_HIGH	This interrupt is sampled with the signal is high, or true.
ACPI_IRQ_ACTIVE_LOW	This interrupt is sampled with the signal is low, or false.
ACPI_IRQ_SHARED	This interrupt is shared with other devices.
ACPI_IRQ_EXCLUSIVE	This interrupt is not shared with other devices.
ACPI_IRQ_NOT_WAKE_CAPABLE	This interrupt is not capable of waking the system.
ACPI_IRQ_WAKE_CAPABLE	This interrupt is capable of waking the system from a low-power idle state or a system sleep state.
ACPI_IRQ_RESERVED1
ACPI_IRQ_RESERVED2

Definition at line 91 of file resources.h.

◆ acpi_item_name_small_t

enum acpi_item_name_small_t

Small ACPI resource item names.

This enum stores the values that will be found in the actual small resource descriptor headers.

Enumerator
ACPI_ITEM_SMALL_IRQ
ACPI_ITEM_SMALL_IO_PORT
ACPI_ITEM_SMALL_END_TAG

Definition at line 173 of file resources.h.

◆ acpi_item_name_large_t

enum acpi_item_name_large_t

Large ACPI resource item names.

This enum stores the values that will be found in the actual large resource descriptor headers.

Enumerator
ACPI_LARGE_ITEM_24_MEM_RANGE

Definition at line 186 of file resources.h.

◆ acpi_item_name_t

enum acpi_item_name_t

Generic ACPI resource item names.

This enum stores the values returned by ACPI_RESOURCE_ITEM_NAME() macro, NOT the actual values found in the resource descriptor headers.

Used to simplify checking the type of a resource descriptor.

Enumerator
ACPI_ITEM_NAME_IRQ
ACPI_ITEM_NAME_IO_PORT
ACPI_ITEM_NAME_END_TAG
ACPI_ITEM_NAME_LARGE_BASE
ACPI_ITEM_NAME_24_MEM_RANGE

Definition at line 224 of file resources.h.

Function Documentation

◆ acpi_resources_current()

acpi_resources_t * acpi_resources_current ( aml_object_t * device )

Get the current ACPI resource settings for a device.

Will ensure the data return by the device's _CRS method is valid, no need for the caller to do so.

Parameters

device The device object in the AML namespace.

Returns

On success, a allocated resources structure. On failure, NULL and errno is set to:

EINVAL: Invalid parameters.
ENOENT: The device has no _CRS method.
EILSEQ: Unexpected data from the _CRS method.
ENOMEM: Out of memory.
Other values from aml_evaluate().

Definition at line 25 of file resources.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ acpi_resources_free()

void acpi_resources_free ( acpi_resources_t * resources )

Free an ACPI resources structure.

Parameters

resources Pointer to the resources structure to free.

Definition at line 116 of file resources.c.

Here is the call graph for this function:

Detailed Description

Example

Resource Data Format

Helpers

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ ACPI_IRQ_DESCRIPTOR_INFO

◆ ACPI_RESOURCE_ITEM_NAME

◆ ACPI_RESOURCE_SIZE

◆ ACPI_RESOURCES_FOR_EACH

Enumeration Type Documentation

◆ acpi_irq_descriptor_info_t

◆ acpi_item_name_small_t

◆ acpi_item_name_large_t

◆ acpi_item_name_t

Function Documentation

◆ acpi_resources_current()

◆ acpi_resources_free()