17.4 Device Resource Hints

The device resource hints file (device.hints) is a configuration file used during the FreeBSD boot process. At system startup, loader(8) reads this file, and its contents are passed to the kernel to control kernel boot behavior, but it can also contain any kernel tunable parameter values.

device.hints stores configuration variables used during kernel startup, commonly referred to as "device hints," which are used by device drivers during device configuration.

The configuration files are structured hierarchically. /boot/device.hints is the static configuration file read by loader(8) at system startup.

device.hints File Structure

/
├── boot/ Programs and configuration files used during OS boot
│    └── device.hints Device resource hints file
└── sys/
     └── ARCH/ A specific architecture, see kernel for details
          └── conf/ Kernel configuration related files
               ├── GENERIC.hints Device resource hints example for the GENERIC kernel
               └── NOTES Notes about kernel configuration files and device resource hints

device.hints in the Base System

The default contents of the device.hints file in the base system vary by architecture:

# Most of the following drivers have been obsoleted by modern computers or are rare on personal PCs

# AT keyboard controller driver atkbdc(4) AT machine, a product of the 1980s
hint.atkbdc.0.at="isa"  # at: specifies the bus to which the device is connected
hint.atkbdc.0.port="0x060"  # port: specifies the starting I/O port address the device will use
hint.atkbd.0.at="atkbdc"
hint.atkbd.0.irq="1"  # irq: the interrupt line number to use

# PS/2 peripheral IBM compatible mouse driver psm(4), a product of the 1980s

#isa
# └── atkbdc0
#       ├── atkbd0
#       └── psm0

hint.psm.0.at="atkbdc"
hint.psm.0.irq="12"

# syscons(4) traditional console driver
# Note: syscons(4) has been gradually replaced by vt(4) (Newcons) since FreeBSD 9.x.
# vt(4) provides better Unicode support, KMS integration, and modern graphics card compatibility, and has become the default console driver.
# The following hint.sc entries are for historical reference only; modern FreeBSD uses vt(4) by default.
hint.sc.0.at="isa"
hint.sc.0.flags="0x100"  # flags: set flag bits for the device

# Serial port driver uart(4)
hint.uart.0.at="acpi"  # This sets COM1
hint.uart.0.port="0x3F8"
hint.uart.0.flags="0x10"
hint.uart.1.at="acpi"  # This sets COM2
hint.uart.1.port="0x2F8"

# RTC driver (real-time clock atrtc(4))
hint.atrtc.0.at="isa"
hint.atrtc.0.port="0x70"
hint.atrtc.0.irq="8"

# i8254 programmable interval timer (AT timer) driver attimer(4)
hint.attimer.0.at="isa"
hint.attimer.0.port="0x40"
hint.attimer.0.irq="0"

# Disable ACPI CPU throttle driver, see cpufreq(4)
hint.acpi_throttle.0.disabled="1"  # disabled: setting to "1" means disable this device

# Disable Pentium 4 thermal control, see cpufreq(4)
hint.p4tcc.0.disabled="1"

Based on source code analysis, sys/amd64/conf/GENERIC.hints is the default device.hints file for the amd64 architecture.

File version: amd64 GENERIC: Switch uart hints from "isa" to "acpi".

device.hints Syntax

device.hints uses a one-variable-per-line format with the following syntax:

hint.driver.unit_number.keyword="value"

This line sets a resource or property for the specified unit number device instance of the driver (comments are marked with #).

Where driver is the device driver name, unit_number is the unit number of the device driver, and keyword is the hint keyword. Keywords can be one of the following options:

Keyword	Description
at	Specifies the bus to which the device is connected
port	Specifies the starting I/O address to use
portsize	Specifies the number of I/O ports used by the device
irq	Specifies the interrupt request number to use
drq	Specifies the DMA channel number
maddr	Specifies the physical memory address occupied by the device
msize	Specifies the physical memory size occupied by the device
flags	Sets various flag bits for the device
disabled	If set to 1, disables the device

Explanation:

hint.atkbdc.0.at="isa"

Attaches device instance 0 of the atkbdc (AT keyboard controller) driver to the ISA bus, i.e., specifies that atkbdc device 0 is located on the ISA bus.

Stage 3 Boot Loader

Device hints can be specified at the stage 3 boot loader prompt, which will override variables in /boot/device.hints. Device hints entered in the boot loader only take effect for the current boot session and are lost after a reboot.

The syntax for the stage 3 boot loader is:

set hint.driver.unit_number.keyword=value

Use set to add variables, unset to delete variables, and show to view variables.

References

• FreeBSD Project. device.hints(5)[EB/OL]. [2026-04-17]. https://man.freebsd.org/cgi/man.cgi?query=device.hints&sektion=5. Device resource hints file manual page.
• FreeBSD Project. loader(8)[EB/OL]. [2026-04-17]. https://man.freebsd.org/cgi/man.cgi?query=loader&sektion=8. System boot loader manual page.
• FreeBSD Project. atkbdc -- AT keyboard controller driver[EB/OL]. [2026-04-17]. https://man.freebsd.org/cgi/man.cgi?query=atkbdc&sektion=4. AT keyboard controller driver manual page.

Exercises

1. Review the source code implementation of a disabled device in device.hints (such as hint.acpi_throttle.0.disabled), and analyze the mechanism by which the disabled flag operates in the device probe process.
2. Create a custom device.hints file, set resource hints for a virtual device, and verify whether it is correctly read by the kernel, recording the parameter passing path.
3. Compare the loading timing differences of kernel tunable parameters between the device.hints file and the loader.conf file, set the same parameter in both files and observe which one takes effect, and analyze the priority rules for loading order.