paulbergmann_mpstubs/machine/acpi.h

/*! \file
 *  \brief Structs and methods related to the \ref ACPI "Advanced Configuration and Power Interface (ACPI)"
 */

#pragma once
#include "types.h"

/*! \brief Abstracts the ACPI standard that provides interfaces for hardware detection, device configuration,
 *         and energy management.
 *  \ingroup io
 *
 *  ACPI is the successor to APM (Advanced Power Management), aiming to give the operating system more control
 *  over the hardware. This extended control, for instance, enables the operating system to assign a particular amount
 *  of energy to every device (e.g., by disabling a device or changing to standby mode).
 *  For this purpose, BIOS and chipset provide a set of tables that describe the system and its components and provide
 *  routines the OS can call.
 *  These tables contain details about the system, such as the number of CPU cores and the LAPIC/IOAPIC, which are
 *  determined during system boot.
 */

namespace ACPI {

/*! \brief Root System Description Pointer (RSDP)
 *
 * The first step to using ACPI is finding the RSDP that is used to find the RSDT / XSDT, which themselves
 * contain pointers to even more tables.
 *
 * On UEFI systems, the RSDP can be found in the EFI_SYSTEM_TABLE; for non-UEFI systems we have to search for the
 * signature 'RSD PTR ' in the EBDA (Extended Bios Data Area) or in the memory area up to `FFFFFh`.
 *
 * \see [ACPI-Specification 5.2.5.3; Root System Description Pointer (RSDP) Structure](acpi.pdf#page=161)
 */

struct RSDP {
	char signature[8];     /* must exactly be equal to 'RSD PTR ' */
	uint8_t checksum;
	char oemid[6];
	uint8_t revision;      /* specifies the ACPI version */
	uint32_t rsdtaddress;  /* physical address of the RSDT */
	uint32_t length;
	uint64_t xsdtaddress;  /* physical address of the XSDT */
	uint8_t extended_checksum;
	uint8_t reserved[3];
} __attribute__((packed));

/*! \brief System Description Table Header (SDTH)
 *
 * All System Description Tables (e.g., the RSDT) contain the same entries at the very beginning of
 * the structure, which are abstracted in the SDTH.
 *
 * \see [ACPI-Specification 5.2.6; System Description Table Header](acpi.pdf#page=162)
 */
struct SDTH {
	uint32_t signature; /* table id */
	uint32_t length;
	uint8_t revision;
	uint8_t checksum;
	char oemid[6];
	char oem_table_id[8];
	uint32_t oem_revision;
	uint32_t creator_id;
	uint32_t creator_revision;

	/* \brief Helper method
	 * \return Pointer to the end of the table
	 */
	void *end() {
		return reinterpret_cast<uint8_t*>(this)+length;
	}
} __attribute__((packed));

/*! \brief Root System Description Table (RSDT)
 *
 * The RSDT can be found in the RSDP. The RSDT contains physical addresses of all other System Description Tables,
 * for example the MADT.
 *
 * \see [ACPI-Specification 5.2.7; Root System Description Table (RSDT)](acpi.pdf#page=167)
 */

struct RSDT : SDTH {
	uint32_t entries[];
} __attribute__((packed));

/*! \brief Extended System Description Table (XSDT)
 *
 * Like RSDT, but contains 64-bit instead of 32-bit addresses.
 *
 * \see [ACPI-Specification 5.2.8; Extended System Description Table (XSDT)](acpi.pdf#page=168)
 */

struct XSDT : SDTH {
	uint64_t entries[];
} __attribute__((packed));

/*! \brief Helper structure
 *
 * Is used for accessing the substructures present in SRAT / MADT.
 *
 */
struct SubHeader {
	uint8_t type;
	uint8_t length;

	/* Method to traverse multiple substructures  */
	SubHeader *next() {
		return reinterpret_cast<SubHeader*>(reinterpret_cast<uint8_t*>(this)+length);
	}
} __attribute__((packed));

/*! \brief Multiple APIC Description Table (MADT)
 *
 * Describes all interrupt controllers present within the system. Is used to obtain the IDs of the APICs, along with
 * the number of available processor cores.
 *
 * \see [ACPI-Specification 5.2.12; Multiple APIC Description Table (MADT)](acpi.pdf#page=193)
 */
struct MADT : SDTH {
	uint32_t local_apic_address;
	uint32_t flags_pcat_compat:1,
		flags_reserved:31;

	/* method to access the first subheader */
	SubHeader *first() {
		return reinterpret_cast<SubHeader*>(reinterpret_cast<uint8_t*>(this)+sizeof(MADT));
	}
} __attribute__((packed));

enum class AddressSpace : uint8_t {
	MEMORY = 0x0,
	IO     = 0x1,
};

/*! \brief ACPI address format
 *
 * The ACPI standard defines its own address format that is able to handle addresses both in memory address space,
 * as well as IO-port address space.
 */
struct Address {
	AddressSpace address_space;
	uint8_t register_bit_width;
	uint8_t register_bit_offset;
	uint8_t reserved;
	uint64_t address;
} __attribute__((packed));

// Multiple APIC Definition Structure
namespace MADS {
enum Type {
	Type_LAPIC = 0,
	Type_IOAPIC = 1,
	Type_Interrupt_Source_Override = 2,
	Type_LAPIC_Address_Override = 5,
};

/*! \brief Processor Local APIC (LAPIC) Structure
 *
 * Represents a physical processor along with its local interrupt controller.
 * The MADT contains a LAPIC structure for every processor available in the system.
 *
 * \see [ACPI-Specification 5.2.12.2; Processor Local APIC Structure](acpi.pdf#page=195)
 */
struct LAPIC : SubHeader {
	uint8_t acpi_processor_id;
	uint8_t apic_id;
	uint32_t flags_enabled  :  1,
	         flags_reserved : 31; /* must be 0 */
} __attribute__((packed));

/*! \brief I/O APIC Structure
 *
 * Represents an I/O-APIC.
 * The MADT contains an IOAPIC structure for every I/O APIC present in the system.
 *
 * \see [ACPI-Specification 5.2.12.3; I/O APIC Structure](acpi.pdf#page=196)
 */

struct IOAPIC : SubHeader {
	uint8_t ioapic_id;
	uint8_t reserved;
	uint32_t ioapic_address;
	uint32_t global_system_interrupt_base;
} __attribute__((packed));

/*! \brief Interrupt Source Override Structure
 *
 * Is required to describe differences between the IA-PC standard interrupt definition and the actual
 * hardware implementation.
 *
 * \see [ACPI-Specification 5.2.12.5; Interrupt Source Override Structure](acpi.pdf#page=197)
 */
struct Interrupt_Source_Override : SubHeader {
	uint8_t bus;
	uint8_t source;
	uint32_t global_system_interrupt;
	uint16_t flags_polarity     :  2,
	         flags_trigger_mode :  2,
	         flags_reserved     : 12; /* must be 0 */
} __attribute__((packed));

/*! \brief Local APIC Address Override Structure
 *
 * Support for 64-bit systems is achieved by replacing the 32-bit physical LAPIC address stored in the MADT
 * with the corresponding 64-bit address.
 *
 * \see [ACPI-Specification 5.2.12.8; Local APIC Address Override Structure](acpi.pdf#page=199)
 */

struct LAPIC_Address_Override : SubHeader {
	uint16_t reserved;
	union {
		uint64_t lapic_address;
		struct {
			uint32_t lapic_address_low;
			uint32_t lapic_address_high;
		} __attribute__((packed));
	};
} __attribute__((packed));

}  // namespace MADS

/*! \brief Initialize the ACPI description table
 *
 * Searches physical memory ranges o 16-byte boundaries for a valid Root System Description Pointer (RSDP)
 * structure signature and checksum.
 * If present, the superseding Extended System Description Table (XSDT) is used.
 *
 * \see [ACPI-Specification 5.2.5 Root System Description Pointer (RSDP)](acpi.pdf#page=160)
 * \see [ACPI-Specification 5.2.8 Extended System Description Table (XSDT)](acpi.pdf#page=168)
 */
bool init();

/*! \brief Number of entries in the description table
 */
unsigned count();

/*! \brief Get entry of description table by index
 *
 * \param num index in description table
 * \return Pointer to corresponding entry or `nullptr` if not available
 */
SDTH *get(unsigned num);

/*! \brief Get entry of description table by four character identifier
 *
 * \param a first character of identifier
 * \param b second character of identifier
 * \param c third character of identifier
 * \param d forth and last character of identifier
 * \return Pointer to corresponding entry or `nullptr` if not available
 */
SDTH *get(char a, char b, char c, char d);

/*! \brief Retrieve the revision from the Root System Description Pointer (RSDP)
 */
int revision();

}  // namespace ACPI