Devices

Device and Power Management. More...

Collaboration diagram for Devices:

Detailed Description

Device and Power Management.

Handles enumeration and configuration of ACPI devices, along with dynamic loading of device drivers.

Each device found under the \_SB namespace with a _HID method will have its HID collected and the module system will be notified that a device with that HID exists, if there is no module supporting that HID then the devices _CID method will be evaluated (if it exists) and the module system will be notified of the CID returned by that method.

Processor Container Devices (HID "ACPI0010") are ignored as their use is deprecated so even if the hardware provides them, we dont want to use them. Its also possible that certain devices such as the HPET are not reported even if they exist, in these cases we manually check for them and add their HIDs.

Hardware IDs (HIDs) and Compatible IDs (CIDs)

The difference between HIDs and CIDs is that HIDs are unique identifiers for the specific device type, while CIDs are more generic identifiers. Its the difference between a specific model of network card and just a generic network card.

Trying HIDs first and CIDs after means we try to load a module for the exact device, or if that fails a generic module that can handle the device, tho perhaps not optimally.

Device Configuration

Each ACPI device specifies the resources it needs via its AML, for example via the _CRS method. This can include IRQs, IO ports, etc. During device initialization, this data is parsed and the necessary resources are allocated and configured for the device.

Module Loading and Device Configuration Order

For the sake of ensuring consistency across different systems, all modules will be loaded based on their ACPI HIDs or CIDs in alphanumerical order, this also applies to device configuration. This means that a device with the ACPI HID "ACPI0001" will be loaded before a device with the ACPI HID "ACPI0002" and that one before the device with the ACPI HID "PNP0000". This only applies to the module loading and device configuration but not to device enumeration.

Todo:

Implement hotplugging support.

See also

PNP ACPI Registry for a list of known ACPI HIDs.

Section 6.1.2 and 6.1.5 of the ACPI specification for more details on HIDs and CIDs.

Data Structures
struct	acpi_device_irq_t
	Represents a IRQ assigned to an ACPI device. More...
struct	acpi_device_io_t
	Represents an IO port range assigned to an ACPI device. More...
struct	acpi_device_cfg_t
	ACPI device configuration structure. More...

Macros
#define	ACPI_STA_FLAGS_DEFAULT   (ACPI_STA_PRESENT | ACPI_STA_ENABLED | ACPI_STA_SHOW_IN_UI | ACPI_STA_FUNCTIONAL)
	Default _STA flags if the _STA method does not exist.

Enumerations
enum	acpi_sta_flags_t {   ACPI_STA_PRESENT = 1 << 0 , ACPI_STA_ENABLED = 1 << 1 , ACPI_STA_SHOW_IN_UI = 1 << 2 , ACPI_STA_FUNCTIONAL ,   ACPI_STA_BATTERY_PRESENT = 1 << 4 }
	Flags for the _STA method. More...

Functions
uint64_t	acpi_devices_init (void)
	Enumerate, configure and load modules for ACPI devices.
acpi_device_cfg_t *	acpi_device_cfg_lookup (const char *name)
	Retrieves the ACPI device configuration for a device by its name.
uint64_t	acpi_device_cfg_get_port (acpi_device_cfg_t *cfg, uint64_t index, port_t *out)
	Retrieves an the nth IO port assigned to an ACPI device.

Macro Definition Documentation

ACPI_STA_FLAGS_DEFAULT

#define ACPI_STA_FLAGS_DEFAULT   (ACPI_STA_PRESENT | ACPI_STA_ENABLED | ACPI_STA_SHOW_IN_UI | ACPI_STA_FUNCTIONAL)

Default _STA flags if the _STA method does not exist.

If the _STA method does not exist, the device is assumed to be present, enabled, shown in the UI and functioning.

See also

Section 6.3.7 of the ACPI specification for more details.

Definition at line 80 of file devices.h.

Enumeration Type Documentation

acpi_sta_flags_t

enum acpi_sta_flags_t

Flags for the _STA method.

See also

Section 6.3.7 of the ACPI specification for more details.

Enumerator
ACPI_STA_PRESENT	Set if the device is present.
ACPI_STA_ENABLED	Set if the device is enabled and decoding its resources.
ACPI_STA_SHOW_IN_UI	Set if the device should be shown in the UI.
ACPI_STA_FUNCTIONAL	Set if the device is functioning properly (cleared if device failed its diagnostics)
ACPI_STA_BATTERY_PRESENT	Set if a battery is present.

Definition at line 63 of file devices.h.

Function Documentation

acpi_devices_init()

uint64_t acpi_devices_init

(

void

)

Enumerate, configure and load modules for ACPI devices.

This function always evaluates the _SB._INI node if it exists, enumerates ACPI devices (found under _SB), evaluates their _STA object retrieving its present and functional status (if it exists) and then evaluates their _INI object according to these rules:

• If the _INI object does not exist it is ignored.
• If the _STA object does not exist the device is assumed to be present and functional
• If the _STA object does exist its status is read.
• Depending on the status returned by _STA or assumed, the device is treated in one of four ways:
  • If the device is not present and not functional, the device is ignored.
  • If the device is not present and functional, the device's _INI is ignored but its children are enumerated.
  • If the device is present and not functional, the device's _INI is evaluated and its children are enumerated.
  • If the device is present and functional, the device's _INI is evaluated and its children are enumerated.

See also

Section 6.5.1 of the ACPI specification for more details.

Returns

On success, 0. On failure, ERR.

Definition at line 480 of file devices.c.

Here is the call graph for this function:

Here is the caller graph for this function:

acpi_device_cfg_lookup()

acpi_device_cfg_t * acpi_device_cfg_lookup

(

const char *

name

)

Retrieves the ACPI device configuration for a device by its name.

Parameters

name	The name of the device to retrieve the configuration for.

Returns

On success, a pointer to the device configuration. On failure, NULL and errno is set to:

• EINVAL: Invalid parameters.
• ENOENT: The specified name does not exist in the ACPI namespace.
• ENOTTY: The specified name is not a device.
• ENODEV: The specified device has no configuration.

Definition at line 567 of file devices.c.

Here is the call graph for this function:

Here is the caller graph for this function:

acpi_device_cfg_get_port()

uint64_t acpi_device_cfg_get_port	(	acpi_device_cfg_t *	cfg,
		uint64_t	index,
		port_t *	out
	)

Retrieves an the nth IO port assigned to an ACPI device.

Useful as each IO entry contains a base and length, making it rather complex to just, for example, get the 5th port.

Parameters

cfg	The device configuration to retrieve the port from.
index	The index of the IO port to retrieve.
out	Output pointer to store the retrieved port.

Returns

On success, 0. On failure, ERR and errno is set to:

• EINVAL: Invalid parameters.
• ENOSPC: The specified index is out of bounds.

Definition at line 603 of file devices.c.

Here is the caller graph for this function: