share/man/man5/device.hints.5

   1 .\" Copyright (c) 2001
   2 .\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
   3 .\" All rights reserved.
   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 as
  10 .\"    the first lines of this file unmodified.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 11, 2009
  29 .Dt DEVICE.HINTS 5
  30 .Os
  31 .Sh NAME
  32 .Nm device.hints
  33 .Nd device resource hints
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 file is read in by the boot
  38 .Xr loader 8
  39 when the system is about to start, and its contents are
  40 passed to the kernel.
  41 It contains various variables to control the boot behavior of
  42 the kernel.
  43 These variables are typically
  44 .Dq device hints .
  45 .\" .Dq device hints ,
  46 .\" and other control variables.
  47 .Pp
  48 The file contains one variable per line.
  49 Lines starting with the
  50 .Ql #
  51 character are comments and are ignored by the boot loader.
  52 .Pp
  53 After the file is read by the boot loader, you may examine
  54 the variables with the
  55 .Ic show
  56 command, and may add a new variable, modify an existing one,
  57 or delete a variable with the
  58 .Ic set
  59 and
  60 .Ic unset
  61 commands of the boot loader
  62 (see
  63 .Xr loader 8 ) .
  64 .Pp
  65 After the system has started, you can dump these variables
  66 with the
  67 .Xr kenv 1
  68 command.
  69 .Sh DEVICE HINTS
  70 Device hint variables are used by device drivers to set up
  71 the device.
  72 They are most often used by ISA device drivers to specify
  73 where the driver will probe for the relevant devices, and what
  74 resources it will attempt to use.
  75 .Pp
  76 A device hint line looks like:
  77 .Pp
  78 .Sm off
  79 .D1 Li hint. Ar driver . Ar unit . Ar keyword Li = Qq Ar value
  80 .Sm on
  81 .Pp
  82 where
  83 .Ar driver
  84 is the name of a device driver,
  85 .Ar unit
  86 is the unit number, and
  87 .Ar keyword
  88 is the keyword of the hint.
  89 The keyword may be:
  90 .Pp
  91 .Bl -tag -width ".Li disabled" -compact -offset indent
  92 .It Li at
  93 specifies a bus to which the device is attached.
  94 .It Li port
  95 specifies the start address of I/O ports to be used by the device.
  96 .It Li portsize
  97 specifies the number of ports used by the device.
  98 .It Li irq
  99 is the interrupt line number to be used.
 100 .It Li drq
 101 is the DMA channel number.
 102 .It Li maddr
 103 specifies the physical memory address used by the device.
 104 .It Li msize
 105 specifies the physical memory size used by the device.
 106 .It Li flags
 107 sets various flag bits for the device.
 108 .It Li disabled
 109 can be set to
 110 .Qq 1
 111 to disable the device.
 112 .El
 113 .Pp
 114 A device driver may require one or more hint lines with these keywords,
 115 and may accept other keywords not listed here, through
 116 .Xr resource_int_value 9 .
 117 Consult individual device drivers' manual pages for available
 118 keywords and their possible values.
 119 .\" .Sh CONTROL VARIABLES
 120 .\" Lines not starting with
 121 .\" .Dq hint.
 122 .\" specify other control variables for the kernel.
 123 .\" They look:
 124 .\" .Pp
 125 .\" .Dl <name>="<value>"
 126 .\" XXX
 127 .\" WE SHOULD LIST AVAILABLE VARIABLE NAMES AND THEIR POSSIBLE VALUES HERE!
 128 .\" .Pp
 129 .Sh FILES
 130 .Bl -tag -width ".Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints" -compact
 131 .It Pa /boot/device.hints
 132 Device resource hints file.
 133 .It Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints
 134 Sample resource hints for the
 135 .Pa GENERIC
 136 kernel.
 137 .It Pa /sys/ Ns Ar ARCH Ns Pa /conf/NOTES
 138 Notes on the kernel configuration file and device resource hints.
 139 .El
 140 .Sh EXAMPLES
 141 The following example sets up resources for the
 142 .Xr sio 4
 143 driver on the ISA bus:
 144 .Bd -literal -offset indent
 145 hint.sio.0.at="isa"
 146 hint.sio.0.port="0x3F8"
 147 hint.sio.0.flags="0x10"
 148 hint.sio.0.irq="4"
 149 .Ed
 150 .Pp
 151 The following example disables the ACPI driver:
 152 .Bd -literal -offset indent
 153 hint.acpi.0.disabled="1"
 154 .Ed
 155 .\" .Pp
 156 .\" A control variable may look like:
 157 .\" .Pp
 158 .\" .Bd -literal -offset indent
 159 .\" debug.acpi.layer="ACPI_RESOURCES"
 160 .\" .Ed
 161 .Sh SEE ALSO
 162 .Xr kenv 1 ,
 163 .Xr loader.conf 5 ,
 164 .Xr loader 8 ,
 165 .Xr resource_int_value 9
 166 .Sh HISTORY
 167 The
 168 .Nm
 169 file first appeared in
 170 .Fx 5.0 .