Page MenuHomeFreeBSD
Differential D3178 Diff 7278 share/man/man5/device.hints.5

Changeset View

Standalone View

View Options

share/man/man5/device.hints.5

Show All 28 Lines
.Dt DEVICE.HINTS 5 .Dt DEVICE.HINTS 5
.Os .Os
.Sh NAME .Sh NAME
.Nm device.hints .Nm device.hints
.Nd device resource hints .Nd device resource hints
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
file is read in by the boot file is read by the boot loader,
.Xr loader 8 .Xr loader 8 ,
when the system is about to start, and its contents are when the system is starting.
passed to the kernel. The contents of the file
It contains various variables to control the boot behavior of are read, parsed into variables, and passed to the kernel.
the kernel. Variables that control the boot behavior of
the kernel are defined here.
These variables are typically These variables are typically
.Dq device hints , .Dq device hints ,
but can include any kernel tunable values. but can include any kernel tunable values.
.Pp .Pp
The file contains one variable per line. One variable is defined per line.
Lines starting with the Lines starting with the
.Ql # .Ql #
character are comments and are ignored by the boot loader. character are comments and are ignored by the boot loader.
.Pp .Pp
After the file is read by the boot loader, you may examine After the boot loader has read the file, variables can be
the variables with the examined with the
.Ic show .Ic show
command, and may add a new variable, modify an existing one, command, or added, modified, or deleted with the
or delete a variable with the
.Ic set .Ic set
and and
.Ic unset .Ic unset
commands of the boot loader commands
(see .Pq see Xr loader 8 .
.Xr loader 8 ) .
.Pp .Pp
After the system has started, you can dump these variables
with the
.Xr kenv 1 .Xr kenv 1
command. can be used to dump these and other kernel environment variables
after the kernel has booted.
.Sh DEVICE HINTS .Sh DEVICE HINTS
Device hint variables are used by device drivers to set up Device hint variables are used by device drivers to set up
the device. the device.
They are most often used by ISA device drivers to specify They are most often used for ISA or System-on-Chip device drivers, specifying
where the driver will probe for the relevant devices, and what the location to probe for the devices and which
resources it will attempt to use. resources are to be used.
brooksUnsubmitted
Done
Inline Actions

I'd say: "ISA or system on chip device drivers"

brooks: I'd say: "ISA or system on chip device drivers"
.Pp .Pp
A device hint line looks like: A device hint line looks like:
.Pp .Pp
.Sm off .Sm off
.D1 Li hint. Ar driver . Ar unit . Ar keyword Li = Qq Ar value .D1 Li hint. Ar driver . Ar unit . Ar keyword Li = Qq Ar value
.Sm on .Sm on
.Pp .Pp
where where
.Ar driver .Ar driver
is the name of a device driver, is the name of a device driver,
.Ar unit .Ar unit
is the unit number, and is the unit number, and
.Ar keyword .Ar keyword
is the keyword of the hint. is the keyword of the hint.
The keyword may be: Typical keywords include:
.Pp .Pp
.Bl -tag -width ".Li disabled" -compact -offset indent .Bl -tag -width ".Li disabled" -compact -offset indent
.It Li at .It Li at
brooksUnsubmitted
Not Done
Inline Actions

I'm skeptical of the value of this list unless we're going to make a pass through the manpages for all the keywords currently in use. In general, the set accepted by a given driver are documented in the driver manpage.

brooks: I'm skeptical of the value of this list unless we're going to make a pass through the manpages…
wblockAuthorUnsubmitted
Not Done
Inline Actions

They do serve as examples of typical entries. We could trim it a bit to just the most common ones.

wblock: They do serve as examples of typical entries. We could trim it a bit to just the most common…
impUnsubmitted
Not Done
Inline Actions

'flags' 'at' and 'disabled' at least, are used inside of subr_bus.c

While I share the skepticism, some simple wording may help. Many of these things like IRQ and DRQ are up to the bus to configure, not the driver. And the ISA bus at that. But this is by far our biggest use of hints, so it seems reasonable to include carefully worded messages here.

imp: 'flags' 'at' and 'disabled' at least, are used inside of subr_bus.c While I share the…
brooksUnsubmitted
Not Done
Inline Actions

I'm fine with leaving this alone. My main issue is that while it does tell you what the standard values mean, that's not very useful to the reader since they can't know which ones (other than 'flags' 'at' and 'disabled') even apply to their device. Directing users to consult the manpage for their device for supported flags is likely one more helpful.

brooks: I'm fine with leaving this alone. My main issue is that while it does tell you what the…
wblockAuthorUnsubmitted
Not Done
Inline Actions

What if we change the introduction to the table on line 86 from saying "The keyword may be:" to "Typical keywords include:"?

wblock: What if we change the introduction to the table on line 86 from saying "The keyword may be:" to…
brooksUnsubmitted
Not Done
Inline Actions

Works for me.

brooks: Works for me.
specifies a bus to which the device is attached. bus to which the device is attached
.It Li port .It Li port
specifies the start address of I/O ports to be used by the device. start address of I/O ports to be used by the device
.It Li portsize .It Li portsize
specifies the number of ports used by the device. number of ports used by the device
.It Li irq .It Li irq
is the interrupt line number to be used. interrupt line number to be used
.It Li drq .It Li drq
is the DMA channel number. DMA channel number
.It Li maddr .It Li maddr
specifies the physical memory address used by the device. physical memory address used by the device
.It Li msize .It Li msize
specifies the physical memory size used by the device. physical memory size used by the device
.It Li flags .It Li flags
sets various flag bits for the device. various flag bits for the device
.It Li disabled .It Li disabled
can be set to set to
.Qq 1 .Qq 1
to disable the device. to disable the device
.El .El
.Pp .Pp
A device driver may require one or more hint lines with these keywords, A device driver might require one or more hint lines with these keywords,
and may accept other keywords not listed here, through and can accept other keywords not listed here.
brooksUnsubmitted
Done
Inline Actions

resource_int_value.9 is an internal detail and seems out of place here.

brooks: resource_int_value.9 is an internal detail and seems out of place here.
wblockAuthorUnsubmitted
Done
Inline Actions

The intention might have been to show the formats or capabilities, but agreed, resource_int_value.9 really does not add much at all.

wblock: The intention might have been to show the formats or capabilities, but agreed…
.Xr resource_int_value 9 .
Consult individual device drivers' manual pages for available Consult individual device drivers' manual pages for available
keywords and their possible values. keywords and values.
.\" .Sh CONTROL VARIABLES .\" .Sh CONTROL VARIABLES
.\" Lines not starting with .\" Lines not starting with
.\" .Dq hint. .\" .Dq hint.
.\" specify other control variables for the kernel. .\" specify other control variables for the kernel.
.\" They look: .\" They look:
.\" .Pp .\" .Pp
.\" .Dl <name>="<value>" .\" .Dl <name>="<value>"
.\" XXX .\" XXX
.\" WE SHOULD LIST AVAILABLE VARIABLE NAMES AND THEIR POSSIBLE VALUES HERE! .\" WE SHOULD LIST AVAILABLE VARIABLE NAMES AND THEIR POSSIBLE VALUES HERE!
.\" .Pp .\" .Pp
.Sh FILES .Sh FILES
.Bl -tag -width ".Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints" -compact .Bl -tag -width ".Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints" -compact
.It Pa /boot/device.hints .It Pa /boot/device.hints
Device resource hints file. Device resource hints file.
.It Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints .It Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints
Sample resource hints for the Sample resource hints for the
.Pa GENERIC .Pa GENERIC
kernel. kernel.
.It Pa /sys/ Ns Ar ARCH Ns Pa /conf/NOTES .It Pa /sys/ Ns Ar ARCH Ns Pa /conf/NOTES
Notes on the kernel configuration file and device resource hints. Notes on the kernel configuration file and device resource hints.
.El .El
.Sh EXAMPLES .Sh EXAMPLES
The following example sets up resources for the Set up resources for the
.Xr sio 4 .Xr sio 4
driver on the ISA bus: driver on the ISA bus:
.Bd -literal -offset indent .Bd -literal -offset indent
hint.sio.0.at="isa" hint.sio.0.at="isa"
hint.sio.0.port="0x3F8" hint.sio.0.port="0x3F8"
hint.sio.0.flags="0x10" hint.sio.0.flags="0x10"
hint.sio.0.irq="4" hint.sio.0.irq="4"
.Ed .Ed
.Pp .Pp
The following example disables the ACPI driver: Disable the ACPI driver:
.Bd -literal -offset indent .Bd -literal -offset indent
hint.acpi.0.disabled="1" hint.acpi.0.disabled="1"
.Ed .Ed
.Pp .Pp
Setting a tunable variable: Setting a tunable variable:
.Bd -literal -offset indent .Bd -literal -offset indent
vm.pmap.pg_ps_enabled=1 vm.pmap.pg_ps_enabled=1
.Ed .Ed
Show All 10 Lines