x86 Device Enumeration

The following is a summary of x86 ACPI implementation and PCIe enumeration generated by Gemini Deep Research.

Title: Comprehensive Hardware Enumeration and Device Abstraction on x86-64 Architectures

1. Architectural Foundations of System Initialization

The initialization of a modern operating system kernel on the x86-64 architecture is a deterministic yet intricate procedure that bridges the gap between firmware-initialized states and kernel-managed resource control. When a bootloader such as Limine transfers control to the kernel, the system resides in a transient state. The processor operates in Long Mode (64-bit), paging is active, but the kernel lacks a coherent map of the physical topology it inhabits. The primary objective during this early boot phase is the discovery and cataloging of hardware resources—a process known as enumeration.

This report articulates a rigorous methodology for enumerating physical devices, starting from the distinct physical addresses of the ACPI Root System Description Pointer (RSDP) and the System Management BIOS (SMBIOS) entry tables provided by the Limine boot protocol. It explores the traversal of the ACPI namespace, the recursive scanning of the PCI Express (PCIe) fabric, and the initialization of critical peripherals including consoles, network interfaces, graphics processing units (GPUs), and storage controllers. Furthermore, it proposes a robust, object-oriented kernel interface design to abstract these heterogeneous devices into a unified device model.

1.1 The Limine Boot Protocol and Memory Context

The Limine boot protocol represents a modern departure from legacy Multiboot standards, specifically designed to support 64-bit higher-half kernels with 5-level paging support. A critical conceptual hurdle in this phase is the distinction between physical and virtual addressing. The kernel is linked to a high virtual address (typically 0xFFFFFFFF80000000 or similar), while the firmware and hardware registers reside at physical addresses often located in the lower 4 GiB of memory.

When the kernel entry point is invoked, Limine provides a set of response structures in response to requests defined in limine.h. The kernel must verify these responses to locate the root pointers for hardware discovery.

1.1.1 The Higher Half Direct Map (HHDM)

To access firmware tables like the RSDP or SMBIOS, the kernel cannot dereference physical addresses directly, as this would trigger a page fault. Limine provides a Higher Half Direct Map (HHDM) feature, which maps the entire physical memory of the system to a contiguous virtual address range (e.g., starting at 0xFFFF800000000000).

The kernel must retrieve the HHDM offset from the limine_hhdm_response structure. For any physical address $P_{addr}$ returned by a firmware table request, the accessible virtual address $V_{addr}$ is calculated as:

$V_{addr}=P_{addr}+\text{HHDM\_Offset}$

This transformation is foundational. Every pointer read from an ACPI table or PCI Base Address Register (BAR) that refers to system memory must be adjusted by this offset before the CPU can read the data structure it points to.

1.1.2 Retrieving Root Pointers

The user query necessitates starting with the RSDP and SMBIOS addresses. In Limine, these are obtained via limine_rsdp_request and limine_smbios_request.

• RSDP Retrieval: The limine_rsdp_response contains a address field. This is the physical address of the ACPI 2.0+ Root System Description Pointer. If this is NULL, the system may be non-ACPI compliant (highly unlikely on x86-64) or the bootloader failed to locate it.

• SMBIOS Retrieval: The limine_smbios_response provides the entry_64 (for SMBIOS 3.0+) or entry_32 (for legacy SMBIOS 2.x) physical addresses. The kernel must prioritize the 64-bit entry point if present to ensure access to the full 64-bit address space of the structure table.

1.2 The System Map

Before traversing these tables, the kernel developer must recognize the “safe” regions of memory. The BIOS/UEFI reserves specific regions for itself (runtime services) or hardware mapped I/O (MMIO). The Limine memory map (limine_memmap_request) details these usable and reserved regions. Blindly writing to addresses derived from PCI BARs without cross-referencing the memory map can lead to bus errors or corruption of firmware runtime data.

---

2. ACPI: The Hierarchy of Configuration

The Advanced Configuration and Power Interface (ACPI) is the central repository for platform discovery. Unlike the plug-and-play nature of PCI, ACPI describes devices that cannot be probed, such as interrupt controllers, timers, and legacy UARTs, as well as the routing logic that connects them.

2.1 RSDP: The Root Anchor

The Root System Description Pointer (RSDP) is the only data structure located via a heuristic scan (in legacy BIOS) or explicit pointer (in UEFI/Limine). It serves one purpose: to locate the System Description Tables.

2.1.1 Validation and Parsing

The RSDP structure varies by revision. ACPI 1.0 (Revision 0) provides a 32-bit pointer to the RSDT. ACPI 2.0+ (Revision 2) provides a 64-bit pointer to the XSDT. On an x86-64 system, the XSDT is mandatory for accessing tables located above the 4 GiB physical barrier.

The kernel must validate the RSDP to ensure integrity:

1. Signature Check: The first 8 bytes must match the string "RSD PTR " (note the trailing space).

2. Checksum V1: Sum the first 20 bytes (inclusive of Signature, Checksum, OEMID, Revision, and RsdtAddress). The lowest 8 bits of the sum must be zero.

3. Checksum V2: If Revision >= 2, sum the entire structure (length specified by Length field). This validates the XsdtAddress.

If the signature matches and checksums are valid, the kernel extracts the XsdtAddress (physical). After applying the HHDM offset, the kernel can access the Extended System Description Table (XSDT).

2.2 XSDT: The System Description Table

The XSDT acts as a directory. It contains a standard ACPI header followed by an array of 64-bit physical pointers to other tables.

Standard ACPI Header Format:

Offset	Field	Size	Description
0	Signature	4	ASCII Table Identifier (e.g., “APIC”, “MCFG”)
4	Length	4	Length of table in bytes, including header
8	Revision	1	Table Revision
9	Checksum	1	Sum of all bytes in table must be 0
10	OEMID	6	OEM Identifier
16	OEM Table ID	8	Manufacturer Model ID
24	OEM Revision	4	Manufacturer Revision
28	Creator ID	4	Vendor ID of utility that created the table
32	Creator Rev	4	Revision of utility

The kernel iterates through the pointer array found after this header. The number of entries is calculated as:

$N=\frac{\text{Length}-36}{8}$

(where 36 is the size of the standard header). For each pointer, the kernel maps the header, checks the signature, and stores the virtual address in a global registry for later retrieval (e.g., acpi_get_table("APIC")).

2.3 The Interrupt Controllers (MADT)

To enable the system’s nervous system—interrupts—the kernel must parse the Multiple APIC Description Table (MADT), identified by the signature "APIC".

The MADT describes the interrupt model. It starts with the standard header, followed by the Local APIC Address (physical) and Flags. If the PCAT_COMPAT flag (Bit 0) is set, the system also contains legacy 8259 PICs, which must be masked or disabled before enabling the APIC subsystem.

Following the flags, the MADT contains a variable-length sequence of Interrupt Controller Structures (ICS). The kernel must parse these sequentially:

• Type 0 (Local APIC): Represents a physical CPU core. The kernel records the APIC ID and Processor ID to enable Symmetric Multiprocessing (SMP) later via Limine’s SMP request or manual startup IPIs.

• Type 1 (I/O APIC): Describes the external interrupt controller. The kernel records the I/O APIC ID, Address (MMIO), and Global System Interrupt (GSI) Base. The GSI Base is crucial; if I/O APIC A has GSI Base 0 and supports 24 inputs, and I/O APIC B has GSI Base 24, then an interrupt routed to GSI 25 is handled by Pin 1 of I/O APIC B.

• Type 2 (Interrupt Source Override - ISO): This is critical for PC compatibility. The legacy ISA timer (IRQ 0) is often physically wired to Pin 2 of the I/O APIC (GSI 2). The ISO structure informs the OS of this remapping (Bus 0, Source 0 -> GSI 2). Ignoring ISOs results in a kernel that receives no timer interrupts.

• Type 4 (NMI): Defines the configuration for Non-Maskable Interrupts, which are essential for hardware error reporting and watchdog mechanisms.

2.4 The Fixed ACPI Description Table (FADT)

The FADT (Signature "FACP") contains fixed-register definitions for power management. It provides the physical address of the DSDT (Differentiated System Description Table) and the ACPI Enable (ACPI_ENABLE) and Disable commands used to transition the hardware from legacy BIOS mode to ACPI mode.

Specifically, the PM1a_CNT_BLK and PM1b_CNT_BLK registers defined here are used to execute the system shutdown sequence (transition to S5 Soft Off).

2.5 The Namespace and AML

While tables like MADT are static binaries, the DSDT and SSDT (Secondary System Description Tables) contain ACPI Machine Language (AML) bytecode. This bytecode defines the ACPI Namespace—a hierarchical tree of devices (\_SB System Bus, \_PCI0 PCI Bus, etc.).

Navigating this tree to find devices like the HPET, EC (Embedded Controller), or legacy UARTs requires an AML interpreter.

• Approach A (Full Interpretation): Porting ACPICA or uACPI into the kernel. This allows executing _STA (Status), _INI (Initialize), and _PRT (PCI Routing) methods directly. This is the robust “design in-kernel” approach.

• Approach B (Static Parsing): For a from-scratch kernel, one might search the AML byte stream for specific opcodes (e.g., _HID strings like "PNP0501" for serial ports) or rely on standard locations (e.g., HPET table for the High Precision Event Timer). However, parsing PCI IRQ routing (_PRT) without an interpreter is notoriously difficult due to the dynamic nature of AML packages.

For the purpose of this report, we assume the integration of a lightweight interpreter (like uACPI) or a structured parser capable of decoding _PRT packages, as “designing in-kernel device interfaces” implies a scalable solution.

---

3. System Management BIOS (SMBIOS): Asset Inventory

While ACPI governs control and power, SMBIOS (System Management BIOS) governs asset identification. It provides a static inventory of the system’s physical makeup: chassis type, RAM slots, CPU model strings, and motherboard version.

3.1 Locating the Entry Point

The Limine bootloader provides the physical address of the SMBIOS Entry Point Structure (EPS). The kernel must check the anchor string:

• _SM_ (4 bytes) for 32-bit (SMBIOS 2.1-2.9).

• _SM3_ (5 bytes) for 64-bit (SMBIOS 3.0+).

The EPS contains the Structure Table Address (Physical) and Structure Table Length. It also includes a checksum that must be validated before trusting the table address.

3.2 Parsing the Structure Table

The SMBIOS table is not an array of fixed-size structures. It is a sequence of packed records, each followed by a variable-length string set.

Structure Header:

Offset	Field	Size	Description
0	Type	1	Structure Type (e.g., 0=BIOS, 1=System, 4=CPU)
1	Length	1	Length of the formatted part of the structure
2	Handle	2	Unique handle number

The String Table:

Immediately following the Length bytes of data is the string section. This is a sequence of null-terminated C-strings, terminated by a double null byte (0x00 0x00).

Fields in the formatted section refer to strings by index (1-based). For example, if the Vendor field in Type 0 has value 1, it refers to the first string in the following section.

3.3 Enumeration Algorithm

To enumerate all devices in SMBIOS:

1. Start at the Structure Table Address.

2. Read the Header.

3. Process the formatted data based on Type.

4. Advance the pointer by Length.

5. Scan forward for the double-null terminator (\0\0) to skip the string table.

6. The pointer is now at the start of the next structure.

7. Repeat until the total length or structure count is reached.

3.4 Key Structures for Enumeration

• Type 1 (System Information): Provides UUID, Wake-up Type, and SKU Number.

• Type 4 (Processor Information): Complements ACPI MADT by providing Socket Designation (e.g., “CPU 1”), Max Speed, and Status (Populated/Enabled).

• Type 16/17 (Memory Device): Enumerates physical RAM slots (DIMMs), speed, and form factor. Essential for memory diagnostics.

• Type 11 (OEM Strings): Often contains configuration strings passed by the cloud provider or virtualization host (e.g., limine:config: strings).

---

4. The PCI Express Bus: The Backbone of Device Discovery

The Peripheral Component Interconnect Express (PCIe) bus is the primary conduit for high-speed peripherals: GPUs, NVMe drives, USB controllers, and Network Interfaces. Enumerating PCIe is the single most productive step in device discovery.

4.1 Enhanced Configuration Access Mechanism (ECAM)

Legacy PCI access used I/O ports 0xCF8 and 0xCFC. This method is non-atomic and slow. Modern systems use ECAM, which maps the entire configuration space of the PCIe segment to MMIO.

The base address for ECAM is found in the ACPI MCFG table. The MCFG contains “Allocation Structures” defining the mapping:

• Base Address (64-bit Physical)

• PCI Segment Group (0-65535)

• Start Bus (0-255)

• End Bus (0-255)

Address Calculation:

To access the configuration header of a device at Bus $B$, Device $D$, Function $F$:

$\text{Offset}=((B-\text{Start Bus})\ll 20)\vee (D\ll 15)\vee (F\ll 12)$

$\text{Physical Address}=\text{Base Address}+\text{Offset}$

The kernel maps this 4KB page (virtual uncacheable) to read the configuration header.

4.2 Recursive Enumeration Logic

The PCIe topology is a tree, formed by Root Complexes, Switches, and Endpoints. Software sees this as PCI-to-PCI bridges.

Algorithm:

1. Scan Bus: Start at Bus 0 (or Start Bus from MCFG).

2. Scan Slot: Iterate slots 0–31.

3. Scan Function: Iterate functions 0–7.

   • Read Vendor ID (Offset 0x00). If 0xFFFF, the device is not present.

   • Read Header Type (Offset 0x0E). Bit 7 indicates a multi-function device.

4. Device Identification:

   • Read Class Code (Offset 0x0B), Subclass (0x0A), and Prog IF (0x09). These three bytes classify the device (e.g., 0x01 0x06 0x01 is AHCI SATA).

5. Bridge Traversal:

   • If Class is 0x06 (Bridge) and Subclass is 0x04 (PCI-to-PCI), this is a bridge.

   • Read the Secondary Bus Number register (Offset 0x19).

   • Recursively call the scan function on that Secondary Bus Number.

4.3 Base Address Registers (BARs) and Resources

BARs define the memory or I/O resources the device requires.

• Sizing BARs: To determine the size of the memory region, write 0xFFFFFFFF to the BAR, read it back, clear the encoding bits, and calculate ~(read_value) + 1. The kernel must restore the original value immediately.

• 64-bit BARs: If the BAR type (Bits 2:1) is 0x2, the BAR consumes two 32-bit registers to form a 64-bit address.

• Kernel Interface: The device abstraction layer should store these resources in a resource_list attached to the device_t struct, allowing drivers to request mappings via bus_map_resource() rather than manipulating raw pointers.

4.4 Enabling the Device

Discovery is not enough; the device must be activated via the Command Register (Offset 0x04).

• Bus Master (Bit 2): Mandatory for DMA. If this bit is clear, the device cannot initiate memory transactions (DMA), causing NICs and NVMe drives to hang silently.

• Memory Space (Bit 1): Must be set to respond to MMIO accesses.

• I/O Space (Bit 0): Must be set for Legacy I/O port access (deprecated but used by UHCI/COM).

---

5. Interrupts and DMA: The Control Plane

Once devices are found, the kernel must establish the channels for control (Interrupts) and data movement (DMA).

5.1 Interrupt Routing (The _PRT)

Legacy systems hardwired PCI interrupt lines (LNK A-D) to specific ISA IRQs. In APIC systems, this routing is dynamic and described by the ACPI _PRT object in the DSDT.

The Routing Problem:

A PCI device asserts pin INTA#. This signal traverses the motherboard traces and arrives at an Input Pin on an I/O APIC. The kernel needs to know which I/O APIC input corresponds to PCI Device X, Pin A.

Parsing _PRT:

The _PRT returns a package of mappings:

{ Address (Device << 16 | Function), Pin, Source, SourceIndex }

1. Link Device: If Source is a NamePath (e.g., \_SB.LNKA), it refers to a PCI Interrupt Link Device. The kernel must evaluate the _CRS (Current Resource Settings) of that Link Device to find the Global System Interrupt (GSI).

2. Hardwired: If Source is 0, SourceIndex is the GSI directly.

Programming the I/O APIC:

Once the GSI is known (e.g., GSI 16), the kernel programs the corresponding Redirection Table Entry (RTE) in the I/O APIC:

• Vector: A free IDT vector (e.g., 0x30 + index).

• Trigger Mode: Level Sensitive (for PCI).

• Polarity: Active Low (for PCI).

• Destination: Local APIC ID of the handling CPU.

• Mask: Unmasked.

5.2 Message Signaled Interrupts (MSI/MSI-X)

Modern PCIe devices prefer MSI, bypassing the complex wire routing of the I/O APIC.

1. Check Capability: Iterate the PCI Capability Linked List (Pointer at Offset 0x34) looking for ID 0x05 (MSI) or 0x11 (MSI-X).

2. Configure Address: The MSI Address Register is programmed with a special format: 0xFEE00000 | (DestAPIC << 12). This writes directly to the Local APIC’s doorbell.

3. Configure Data: The MSI Data Register contains the IDT Vector.

4. Enable: Set the Enable bit in the MSI Control Register.

5.3 Direct Memory Access (DMA)

Legacy 8237 DMA:

Restricted to the lower 16 MiB of physical memory and 64KB transfers. Used only for legacy Floppy or Sound Blaster support. Initialization involves cascading the controllers (Master/Slave) and setting the Mode, Address, and Count registers.

PCI Bus Mastering:

Modern DMA is initiated by the device (First-Party DMA). The kernel acts as a memory manager.

• Scatter-Gather: The kernel allocates non-contiguous physical pages and builds a Scatter-Gather List (SGL) or Physical Region Page (PRP) list.

• Translation: The kernel writes the physical address of the SGL to the device’s DMA registers (in BAR space).

• Coherency: x86 hardware is cache-coherent for DMA. However, the kernel must ensure strictly ordered writes to the device registers (using volatile or memory barriers) to prevent the CPU from reordering the “Start” command before the “Address” write.

---

6. Case Studies: Device Initialization and Testing

This section details the specific steps to initialize and test the devices requested in the prompt.

6.1 The System Console

A console is required immediately for debugging.

6.1.1 Serial Console (UART)

While often found at 0x3F8 (COM1), the ACPI SPCR (Serial Port Console Redirection) or DBG2 tables provide the authoritative address and parameters.

• Enumeration: Parse SPCR table to get Base Address, Register Width, and IRQ.

• Initialization:

  1. Disable Interrupts (IER = 0).

  2. Enable DLAB (Divisor Latch Access Bit) in Line Control Register (LCR).

  3. Set Divisor (Baud Rate): 115200 baud → Divisor 1.

  4. Set Data Format: 8 bits, No Parity, 1 Stop Bit (LCR = 0x03).

  5. Enable FIFO (FCR = 0xC7).

• Testing: Write a character to the Data Register. If running in QEMU with -serial stdio, the character appears in the terminal.

6.1.2 Graphics (Framebuffer)

Limine initializes the GPU into a linear framebuffer mode.

• Enumeration: Read limine_framebuffer_response.

• Initialization: Map the framebuffer address (Physical → Virtual).

• Testing: Write 0xFFFFFFFF (White) to the first 4 bytes of the buffer. A white pixel should appear at (0,0).

6.2 Storage: AHCI and NVMe

6.2.1 AHCI (SATA)

• Enumeration: PCI Class 0x01, Subclass 0x06.

• Init Steps:

  1. Map ABAR (AHCI Base Address) from BAR5.

  2. Check CAP.S64A to see if 64-bit addressing is supported.

  3. Set GHC.AE (AHCI Enable).

  4. Scan PI (Ports Implemented) bitmap. For each port, check SSTS.DET == 3 (Present).

  5. Stop the port (CMD.ST = 0, CMD.FRE = 0).

  6. Allocated Command List and FIS area in DMA-reachable memory. Program addresses into CLB and FB registers.

  7. Start port (CMD.FRE=1, CMD.ST=1).

• Testing: Issue an IDENTIFY DEVICE ATA command via a FIS. Check the returned 512-byte block for the model string.

6.2.2 NVMe

• Enumeration: PCI Class 0x01, Subclass 0x08.

• Init Steps:

  1. Map BAR0.

  2. Disable Controller (CC.EN = 0). Wait for CSTS.RDY = 0.

  3. Allocate Admin Submission and Completion Queues (4KB aligned).

  4. Write queue addresses to ASQ and ACQ registers.

  5. Enable Controller (CC.EN = 1). Wait for CSTS.RDY = 1.

• Testing: Submit an Identify Controller command (Opcode 0x06) to the Admin Submission Queue. Ring the Doorbell. Poll the Completion Queue Phase Tag.

6.3 Universal Serial Bus (xHCI)

• Enumeration: PCI Class 0x0C, Subclass 0x03, ProgIF 0x30.

• Init Steps:

  1. Map BAR0 (Capability Registers).

  2. Read HCSPARAMS to get Max Device Slots and Ports.

  3. Claim controller from BIOS (Extended Cap USBLEGSUP).

  4. Reset Controller (USBCMD.HCRST).

  5. Set up Device Context Base Address Array (DCBAA).

  6. Set up Command Ring and Interrupter (Event Ring).

  7. Start Controller (USBCMD.RS).

• Testing: A No Op command can be sent to the Command Ring to verify the controller processes TRBs (Transfer Request Blocks).

6.4 Network Interface (NIC)

• Enumeration: PCI Class 0x02, Subclass 0x00.

• Generic Init:

  1. Enable Bus Mastering in PCI Command Register.

  2. Read MAC address (usually in MMIO or EEPROM).

  3. Allocate RX/TX Descriptor Rings.

  4. Write Ring Base Addresses to device registers (e.g., RDBAL/RDBAH for Intel E1000).

• Testing: Put the NIC in Loopback Mode (specifically supported by E1000/RTL8139 registers) and transmit a packet. Verify an interrupt fires and the packet appears in the RX ring.

---

7. In-Kernel Device Interface Design

To manage this diversity, the kernel requires an Object-Oriented hardware abstraction layer (HAL) implemented in C or C++.

7.1 The device_t Structure

The core unit is the device struct, forming a tree that mirrors the physical topology.

typedef struct device {
    char name;              // e.g., "pci0", "nvme0"
    uint32_t flags;             // Status flags (Initialized, Suspended)
    
    // Hierarchy
    struct device *parent;
    struct device *children;    // Linked list of children
    struct device *sibling;
    
    // Resources
    resource_list_t *resources; // List of BARs, IRQs owned by device
    
    // Driver Binding
    struct driver *driver;      // The driver controlling this device
    void *driver_data;          // Private data (e.g., nvme_state_t)
    
    // Interface Methods (Vtable)
    device_ops_t *ops;          // { read, write, ioctl, suspend, resume }
} device_t;

7.2 The Driver Model

Drivers are registered in a global list. During enumeration (e.g., scanning the PCI bus), the device_manager iterates the driver list calling the probe() method.

typedef struct driver {
    const char *name;
    bus_type_t bus;             // PCI, USB, ACPI
    
    // Returns priority > 0 if driver handles this device
    int (*probe)(device_t *dev);
    
    // Initializes hardware and exposes interfaces
    int (*attach)(device_t *dev);
    
    int (*detach)(device_t *dev);
} driver_t;

Example Flow:

1. PCI Bus Scanner creates device_t for a device with Vendor ID 0x8086, Device ID 0x10D3.

2. e1000_driver.probe(dev) checks these IDs. Returns Success.

3. device_manager calls e1000_driver.attach(dev).

4. attach() enables Bus Mastering, maps BAR0, allocates Rings, registers an interrupt handler, and finally registers a network interface (ifnet) with the network stack.

7.3 Resource Abstraction

Drivers should never access physical addresses directly. They request mappings via the bus parent.

• bus_alloc_resource(dev, TYPE_MEMORY, RID,...): Returns a virtual pointer to the MMIO region.

• bus_setup_intr(dev, RID, handler_func): Abstracts the complexity of IOAPIC vs MSI routing. The driver simply says “I need to handle my interrupt,” and the bus driver (PCI) talks to the interrupt manager (APIC) to route the vector.

---

8. Conclusion

Enumerating physical devices on an x86-64 platform is a multi-layered architectural challenge. It begins with the precise handling of Limine’s physical memory map and ACPI root pointers (RSDP/XSDT). It progresses through the interpretation of the ACPI namespace (MADT for interrupts, FADT for power) and the recursive traversal of the PCI Express fabric (via ECAM).

Success in this domain requires a kernel that respects the boundaries between physical and virtual memory, correctly manages the transition from legacy PIC to modern APIC/MSI interrupt models, and strictly enforces bus mastering protocols for DMA. By encapsulating these mechanisms within a hierarchical, object-oriented device manager, the operating system can present a unified, abstract interface to higher-level subsystems, transforming a chaotic collection of silicon into a coherent computing machine. The roadmap provided here—from the first RSDP checksum to the first NVMe command—constitutes the definitive initialization sequence for a modern bare-metal kernel.