coreboot(4) · carta

NAME

coreboot – coreboot firmware table driver

SYNOPSIS

To compile this driver into the kernel, place the following line in your kernel configuration file:

device coreboot

Alternatively, to load the driver as a module at boot time, place the following line in loader.conf(5):

coreboot_load="YES"

DESCRIPTION

The coreboot driver provides access to firmware tables created by the coreboot open-source firmware project. It discovers the coreboot table by scanning low memory for the “LBIO” signature, follows any forward pointer to the real table in high memory, and validates the IP-style checksums.

The driver exposes firmware information through three interfaces:

sysctl: A sysctl(8) tree under hw.coreboot provides access to:

firmware version, build date, and compiler information

mainboard identification and board configuration

MAC addresses, framebuffer, GPIO, and SPI flash details

TPM information and SMMSTORE configuration

ACPI RSDP address, PCIe controller base, and TSC frequency

boot timestamps and CBMEM entry enumeration
/dev/coreboot_console: A character device providing read-only access to the CBMEM firmware console ring buffer. This contains coreboot's own boot log, analogous to dmesg(8) but for the firmware stage before the OS kernel starts. The ring buffer uses bit 31 of its cursor as an overflow indicator; when set, the buffer has wrapped and data is read starting from the cursor position.
/dev/cbmem: A character device providing ioctl(2) access to individual CBMEM entries. CBMEM is coreboot's mechanism for passing data between firmware stages and to the operating system.

Verbose Output

By default, the driver prints a single attach summary line showing table location and size.

When bootverbose is set (e.g., “boot -v”), the driver additionally prints firmware identity and parsed hardware details such as mainboard, board config, MAC count, ACPI RSDP, SPI flash, framebuffer, GPIO, and TPM summary.

When hw.coreboot.debug is non-zero, the driver prints extra internal diagnostics such as SMMSTORE, timestamp, TPM CB log, and FMAP addresses.

All sysctl nodes are registered regardless of verbosity settings.

sysctl Variables

The following sysctl(8) variables are available when the driver is loaded (variables only appear if the corresponding table record exists):

hw.coreboot.debug: Enable verbose coreboot diagnostics (read-write, default 0). Tunable via loader.conf(5) as hw.coreboot.debug.
hw.coreboot.version: Firmware version string.
hw.coreboot.build: Build date and time.
hw.coreboot.compile_time: Firmware compile time string.
hw.coreboot.compiler: Compiler identification string.
hw.coreboot.extra_version: Extra version information.
hw.coreboot.platform_blob_version: Platform blob version string.
hw.coreboot.serialno: Board serial number.
hw.coreboot.version_timestamp: Firmware version timestamp.
hw.coreboot.table_addr: Physical address of the coreboot table.
hw.coreboot.table_size: Total size of the coreboot table in bytes.
hw.coreboot.mainboard.vendor: Mainboard vendor name.
hw.coreboot.mainboard.part: Mainboard part number.
hw.coreboot.serial.baseaddr: Serial port base address.
hw.coreboot.serial.baud: Serial port baud rate.
hw.coreboot.serial.regwidth: Serial port register width.
hw.coreboot.tsc_freq_khz: TSC frequency in kilohertz as reported by firmware.
hw.coreboot.pcie_ctrl_base: PCIe controller base address.
hw.coreboot.acpi_rsdp: ACPI RSDP physical address.
hw.coreboot.board.fw_config: Firmware configuration bitmask.
hw.coreboot.board.board_id: Board ID.
hw.coreboot.board.ram_code: RAM code.
hw.coreboot.board.sku_id: SKU ID.
hw.coreboot.mac.N: Factory MAC address N (formatted as xx:xx:xx:xx:xx:xx).
hw.coreboot.boot_media.fmap_offset: FMAP offset from boot media start.
hw.coreboot.boot_media.cbfs_offset: CBFS offset from boot media start.
hw.coreboot.boot_media.cbfs_size: CBFS size in bytes.
hw.coreboot.boot_media.size: Boot media size in bytes.
hw.coreboot.mmc_early_cmd1_status: Early eMMC/MMC CMD1 status value.
hw.coreboot.spi_flash.size: SPI flash size in bytes.
hw.coreboot.spi_flash.sector_size: SPI flash sector size in bytes.
hw.coreboot.spi_flash.erase_cmd: SPI flash erase command byte.
hw.coreboot.console_type: Firmware console type (0=serial8250, 1=VGA, 2=BTEXT, 3=LOGBUF, 4=SROM, 5=EHCI, 6=serial8250mem).
hw.coreboot.framebuffer.addr: Framebuffer physical address.
hw.coreboot.framebuffer.x_res: Framebuffer horizontal resolution.
hw.coreboot.framebuffer.y_res: Framebuffer vertical resolution.
hw.coreboot.framebuffer.bpp: Framebuffer bits per pixel.
hw.coreboot.gpio.N.name: GPIO pin N name.
hw.coreboot.gpio.N.port: GPIO pin N port number.
hw.coreboot.gpio.N.value: GPIO pin N value.
hw.coreboot.gpio.N.polarity: GPIO pin N polarity.
hw.coreboot.tpm.version: TPM version (1=TPM 1.2, 2=TPM 2.0).
hw.coreboot.tpm.ppi_addr: TPM Physical Presence Interface address.
hw.coreboot.tpm.cblog_addr: TPM event log physical address.
hw.coreboot.smmstore.num_blocks: SMMSTORE v2 number of blocks.
hw.coreboot.smmstore.block_size: SMMSTORE v2 block size in bytes.
hw.coreboot.smmstore.mmap_addr: SMMSTORE v2 memory-mapped address.
hw.coreboot.smmstore.com_buffer: SMMSTORE v2 communication buffer address.
hw.coreboot.smmstore.apm_cmd: SMMSTORE v2 APM command byte.
hw.coreboot.cbmem_refs.acpi_gnvs: ACPI GNVS CBMEM physical address.
hw.coreboot.cbmem_refs.acpi_cnvs: ACPI CNVS CBMEM physical address.
hw.coreboot.cbmem_refs.vpd: VPD CBMEM physical address.
hw.coreboot.cbmem_refs.wifi_calibration: WiFi calibration CBMEM physical address.
hw.coreboot.cbmem_refs.fmap: FMAP CBMEM physical address.
hw.coreboot.cbmem_refs.vboot_workbuf: Vboot work buffer CBMEM physical address.
hw.coreboot.cbmem_refs.type_c_info: Type-C info CBMEM physical address.
hw.coreboot.cbmem_refs.root_bridge_info: Root bridge info CBMEM physical address.
hw.coreboot.timestamps_addr: Timestamps CBMEM physical address.
hw.coreboot.timestamps: Formatted boot stage timing table (read-only). Each line shows the timestamp ID, stage name, absolute time in microseconds, and delta from the previous stage.
hw.coreboot.cbmem.N.id: CBMEM entry ID.
hw.coreboot.cbmem.N.name: Human-readable CBMEM entry name.
hw.coreboot.cbmem.N.address: Physical address of the CBMEM entry.
hw.coreboot.cbmem.N.size: Size of the CBMEM entry in bytes.

ioctl Interface

The /dev/cbmem device supports the following ioctl(2) commands, defined in ⟨dev/coreboot/corebootio.h⟩:

CBMEM_IOC_LIST: Returns a struct cbmem_list containing the count and metadata of all discovered CBMEM entries.
CBMEM_IOC_READ: Reads data from a CBMEM entry identified by its ID. Takes a struct cbmem_read_req specifying the entry ID, offset, size, and a userspace buffer.

FILES

/dev/coreboot_console: Firmware console ring buffer (read-only).
/dev/cbmem: CBMEM entry access device.

EXAMPLES

Display the coreboot firmware version:

sysctl hw.coreboot.version

Read the firmware boot log:

cat /dev/coreboot_console

List all CBMEM entries:

sysctl hw.coreboot.cbmem

Show board identification:

sysctl hw.coreboot.board

Show factory MAC addresses:

sysctl hw.coreboot.mac

Display boot stage timestamps:

sysctl hw.coreboot.timestamps

Enable debug output and reload the module (the sysctl value resets on unload, so it must be set again or persisted via loader.conf(5)):

kldunload coreboot
kldload coreboot
sysctl hw.coreboot.debug=1
dmesg | grep coreboot

To persist debug across reboots, add to loader.conf(5):

hw.coreboot.debug=1

COMPATIBILITY

The coreboot driver works with any x86 system running coreboot firmware. The coreboot table format uses a stable ABI with forward-compatible tagged records; unknown tags are safely skipped.

Linux provides similar functionality through a custom bus type with separate modules for each table record type, exposed via sysfs. The FreeBSD driver uses a single module with native sysctl(8) and ioctl(2) interfaces instead.

HISTORY

The coreboot driver first appeared in FreeBSD 16.0.

AUTHORS

Abdelkader Boudih ⟨[email protected]⟩.

CAVEATS

The driver discovers the coreboot table by scanning physical memory addresses 0x0 through 0x1000 for the “LBIO” signature. On systems without coreboot firmware, the driver will silently not attach.

The /dev/coreboot_console content is static after boot; coreboot does not write to the console buffer after handing off control to the payload.