> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-17-system-administration/di-17.4-jie-she-bei-zi-yuan-ti-shi.md).

# 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

```sh
/
├── 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:

```ini
# 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](https://github.com/freebsd/freebsd-src/blob/main/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"](https://github.com/freebsd/freebsd-src/commit/9cc06bf7aa2846c35483de567779bb8afc289f53).

## **device.hints** Syntax

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

```ini
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:

```sh
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:

```sh
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.bsdcn.org/ask/flat/chapter-17-system-administration/di-17.4-jie-she-bei-zi-yuan-ti-shi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.