1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2026 Abdelkader Boudih <freebsd@seuros.com> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd March 2, 2026 27.Dt COREBOOT 4 28.Os 29.Sh NAME 30.Nm coreboot 31.Nd coreboot firmware table driver 32.Sh SYNOPSIS 33To compile this driver into the kernel, 34place the following line in your 35kernel configuration file: 36.Bd -ragged -offset indent 37.Cd "device coreboot" 38.Ed 39.Pp 40Alternatively, to load the driver as a 41module at boot time, place the following line in 42.Xr loader.conf 5 : 43.Bd -literal -offset indent 44coreboot_load="YES" 45.Ed 46.Sh DESCRIPTION 47The 48.Nm 49driver provides access to firmware tables created by the coreboot 50open-source firmware project. 51It discovers the coreboot table by scanning low memory for the 52.Dq LBIO 53signature, follows any forward pointer to the real table in high memory, 54and validates the IP-style checksums. 55.Pp 56The driver exposes firmware information through three interfaces: 57.Bl -tag -width "/dev/coreboot_console" 58.It Sy sysctl 59A 60.Xr sysctl 8 61tree under 62.Va hw.coreboot 63provides access to: 64.Bl -bullet -compact 65.It 66firmware version, build date, and compiler information 67.It 68mainboard identification and board configuration 69.It 70MAC addresses, framebuffer, GPIO, and SPI flash details 71.It 72TPM information and SMMSTORE configuration 73.It 74ACPI RSDP address, PCIe controller base, and TSC frequency 75.It 76boot timestamps and CBMEM entry enumeration 77.El 78.It Pa /dev/coreboot_console 79A character device providing read-only access to the CBMEM firmware console 80ring buffer. 81This contains coreboot's own boot log, analogous to 82.Xr dmesg 8 83but for the firmware stage before the OS kernel starts. 84The ring buffer uses bit 31 of its cursor as an overflow indicator; 85when set, the buffer has wrapped and data is read starting from the 86cursor position. 87.It Pa /dev/cbmem 88A character device providing 89.Xr ioctl 2 90access to individual CBMEM entries. 91CBMEM is coreboot's mechanism for passing data between firmware stages 92and to the operating system. 93.El 94.Ss Verbose Output 95By default, the driver prints a single attach summary line showing table 96location and size. 97.Pp 98When 99.Va bootverbose 100is set 101.Pq e.g., Dq Li boot -v , 102the driver additionally prints firmware identity and parsed hardware details 103such as mainboard, board config, MAC count, ACPI RSDP, SPI flash, framebuffer, 104GPIO, and TPM summary. 105.Pp 106When 107.Va hw.coreboot.debug 108is non-zero, the driver prints extra internal diagnostics such as SMMSTORE, 109timestamp, TPM CB log, and FMAP addresses. 110.Pp 111All sysctl nodes are registered regardless of verbosity settings. 112.Ss sysctl Variables 113The following 114.Xr sysctl 8 115variables are available when the driver is loaded 116(variables only appear if the corresponding table record exists): 117.Bl -tag -width "hw.coreboot.smmstore.com_buffer" 118.It Va hw.coreboot.debug 119Enable verbose coreboot diagnostics (read-write, default 0). 120Tunable via 121.Xr loader.conf 5 122as 123.Va hw.coreboot.debug . 124.It Va hw.coreboot.version 125Firmware version string. 126.It Va hw.coreboot.build 127Build date and time. 128.It Va hw.coreboot.compile_time 129Firmware compile time string. 130.It Va hw.coreboot.compiler 131Compiler identification string. 132.It Va hw.coreboot.extra_version 133Extra version information. 134.It Va hw.coreboot.platform_blob_version 135Platform blob version string. 136.It Va hw.coreboot.serialno 137Board serial number. 138.It Va hw.coreboot.version_timestamp 139Firmware version timestamp. 140.It Va hw.coreboot.table_addr 141Physical address of the coreboot table. 142.It Va hw.coreboot.table_size 143Total size of the coreboot table in bytes. 144.It Va hw.coreboot.mainboard.vendor 145Mainboard vendor name. 146.It Va hw.coreboot.mainboard.part 147Mainboard part number. 148.It Va hw.coreboot.serial.baseaddr 149Serial port base address. 150.It Va hw.coreboot.serial.baud 151Serial port baud rate. 152.It Va hw.coreboot.serial.regwidth 153Serial port register width. 154.It Va hw.coreboot.tsc_freq_khz 155TSC frequency in kilohertz as reported by firmware. 156.It Va hw.coreboot.pcie_ctrl_base 157PCIe controller base address. 158.It Va hw.coreboot.acpi_rsdp 159ACPI RSDP physical address. 160.It Va hw.coreboot.board.fw_config 161Firmware configuration bitmask. 162.It Va hw.coreboot.board.board_id 163Board ID. 164.It Va hw.coreboot.board.ram_code 165RAM code. 166.It Va hw.coreboot.board.sku_id 167SKU ID. 168.It Va hw.coreboot.mac.N 169Factory MAC address N (formatted as xx:xx:xx:xx:xx:xx). 170.It Va hw.coreboot.boot_media.fmap_offset 171FMAP offset from boot media start. 172.It Va hw.coreboot.boot_media.cbfs_offset 173CBFS offset from boot media start. 174.It Va hw.coreboot.boot_media.cbfs_size 175CBFS size in bytes. 176.It Va hw.coreboot.boot_media.size 177Boot media size in bytes. 178.It Va hw.coreboot.mmc_early_cmd1_status 179Early eMMC/MMC CMD1 status value. 180.It Va hw.coreboot.spi_flash.size 181SPI flash size in bytes. 182.It Va hw.coreboot.spi_flash.sector_size 183SPI flash sector size in bytes. 184.It Va hw.coreboot.spi_flash.erase_cmd 185SPI flash erase command byte. 186.It Va hw.coreboot.console_type 187Firmware console type (0=serial8250, 1=VGA, 2=BTEXT, 3=LOGBUF, 4=SROM, 1885=EHCI, 6=serial8250mem). 189.It Va hw.coreboot.framebuffer.addr 190Framebuffer physical address. 191.It Va hw.coreboot.framebuffer.x_res 192Framebuffer horizontal resolution. 193.It Va hw.coreboot.framebuffer.y_res 194Framebuffer vertical resolution. 195.It Va hw.coreboot.framebuffer.bpp 196Framebuffer bits per pixel. 197.It Va hw.coreboot.gpio.N.name 198GPIO pin N name. 199.It Va hw.coreboot.gpio.N.port 200GPIO pin N port number. 201.It Va hw.coreboot.gpio.N.value 202GPIO pin N value. 203.It Va hw.coreboot.gpio.N.polarity 204GPIO pin N polarity. 205.It Va hw.coreboot.tpm.version 206TPM version (1=TPM 1.2, 2=TPM 2.0). 207.It Va hw.coreboot.tpm.ppi_addr 208TPM Physical Presence Interface address. 209.It Va hw.coreboot.tpm.cblog_addr 210TPM event log physical address. 211.It Va hw.coreboot.smmstore.num_blocks 212SMMSTORE v2 number of blocks. 213.It Va hw.coreboot.smmstore.block_size 214SMMSTORE v2 block size in bytes. 215.It Va hw.coreboot.smmstore.mmap_addr 216SMMSTORE v2 memory-mapped address. 217.It Va hw.coreboot.smmstore.com_buffer 218SMMSTORE v2 communication buffer address. 219.It Va hw.coreboot.smmstore.apm_cmd 220SMMSTORE v2 APM command byte. 221.It Va hw.coreboot.cbmem_refs.acpi_gnvs 222ACPI GNVS CBMEM physical address. 223.It Va hw.coreboot.cbmem_refs.acpi_cnvs 224ACPI CNVS CBMEM physical address. 225.It Va hw.coreboot.cbmem_refs.vpd 226VPD CBMEM physical address. 227.It Va hw.coreboot.cbmem_refs.wifi_calibration 228WiFi calibration CBMEM physical address. 229.It Va hw.coreboot.cbmem_refs.fmap 230FMAP CBMEM physical address. 231.It Va hw.coreboot.cbmem_refs.vboot_workbuf 232Vboot work buffer CBMEM physical address. 233.It Va hw.coreboot.cbmem_refs.type_c_info 234Type-C info CBMEM physical address. 235.It Va hw.coreboot.cbmem_refs.root_bridge_info 236Root bridge info CBMEM physical address. 237.It Va hw.coreboot.timestamps_addr 238Timestamps CBMEM physical address. 239.It Va hw.coreboot.timestamps 240Formatted boot stage timing table (read-only). 241Each line shows the timestamp ID, stage name, absolute time in 242microseconds, and delta from the previous stage. 243.It Va hw.coreboot.cbmem.N.id 244CBMEM entry ID. 245.It Va hw.coreboot.cbmem.N.name 246Human-readable CBMEM entry name. 247.It Va hw.coreboot.cbmem.N.address 248Physical address of the CBMEM entry. 249.It Va hw.coreboot.cbmem.N.size 250Size of the CBMEM entry in bytes. 251.El 252.Ss ioctl Interface 253The 254.Pa /dev/cbmem 255device supports the following 256.Xr ioctl 2 257commands, defined in 258.In dev/coreboot/corebootio.h : 259.Bl -tag -width CBMEM_IOC_LIST 260.It Dv CBMEM_IOC_LIST 261Returns a 262.Vt struct cbmem_list 263containing the count and metadata of all discovered CBMEM entries. 264.It Dv CBMEM_IOC_READ 265Reads data from a CBMEM entry identified by its ID. 266Takes a 267.Vt struct cbmem_read_req 268specifying the entry ID, offset, size, and a userspace buffer. 269.El 270.Sh FILES 271.Bl -tag -width "/dev/coreboot_console" 272.It Pa /dev/coreboot_console 273Firmware console ring buffer (read-only). 274.It Pa /dev/cbmem 275CBMEM entry access device. 276.El 277.Sh EXAMPLES 278Display the coreboot firmware version: 279.Pp 280.Dl "sysctl hw.coreboot.version" 281.Pp 282Read the firmware boot log: 283.Pp 284.Dl "cat /dev/coreboot_console" 285.Pp 286List all CBMEM entries: 287.Pp 288.Dl "sysctl hw.coreboot.cbmem" 289.Pp 290Show board identification: 291.Pp 292.Dl "sysctl hw.coreboot.board" 293.Pp 294Show factory MAC addresses: 295.Pp 296.Dl "sysctl hw.coreboot.mac" 297.Pp 298Display boot stage timestamps: 299.Pp 300.Dl "sysctl hw.coreboot.timestamps" 301.Pp 302Enable debug output and reload the module (the sysctl value resets on 303unload, so it must be set again or persisted via 304.Xr loader.conf 5 ) : 305.Bd -literal -offset indent 306kldunload coreboot 307kldload coreboot 308sysctl hw.coreboot.debug=1 309dmesg | grep coreboot 310.Ed 311.Pp 312To persist debug across reboots, add to 313.Xr loader.conf 5 : 314.Bd -literal -offset indent 315hw.coreboot.debug=1 316.Ed 317.Sh COMPATIBILITY 318The 319.Nm 320driver works with any x86 system running coreboot firmware. 321The coreboot table format uses a stable ABI with forward-compatible 322tagged records; unknown tags are safely skipped. 323.Pp 324Linux provides similar functionality through a custom bus type with 325separate modules for each table record type, exposed via sysfs. 326The 327.Fx 328driver uses a single module with native 329.Xr sysctl 8 330and 331.Xr ioctl 2 332interfaces instead. 333.Sh SEE ALSO 334.Xr ioctl 2 , 335.Xr smbios 4 , 336.Xr sysctl 8 337.Sh HISTORY 338The 339.Nm 340driver first appeared in 341.Fx 16.0 . 342.Sh AUTHORS 343.An Abdelkader Boudih Aq Mt freebsd@seuros.com . 344.Sh CAVEATS 345The driver discovers the coreboot table by scanning physical memory 346addresses 0x0 through 0x1000 for the 347.Dq LBIO 348signature. 349On systems without coreboot firmware, the driver will silently 350not attach. 351.Pp 352The 353.Pa /dev/coreboot_console 354content is static after boot; coreboot does not write to the 355console buffer after handing off control to the payload. 356