share/man/man4/intro.4

   1 .\"
   2 .\" Copyright (c) 1996 David E. O'Brien, Joerg Wunsch
   3 .\" Copyright (c) 2019 Andrew Gierth
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd April 3, 2019
  28 .Dt INTRO 4
  29 .Os
  30 .Sh NAME
  31 .Nm intro
  32 .Nd introduction to devices and device drivers
  33 .Sh DESCRIPTION
  34 This section contains information related to devices, device drivers
  35 and miscellaneous hardware.
  36 .Ss The device abstraction
  37 Device is a term used mostly for hardware-related stuff that belongs
  38 to the system, like disks, printers, or a graphics display with its
  39 keyboard.
  40 There are also so-called
  41 .Em pseudo-devices
  42 where a device driver emulates the behaviour of a device in software
  43 without any particular underlying hardware.
  44 A typical example for
  45 the latter class is
  46 .Pa /dev/mem ,
  47 a mechanism whereby the physical memory can be accessed using file
  48 access semantics.
  49 .Pp
  50 The device abstraction generally provides a common set of system
  51 calls, which are dispatched to the corresponding device driver by the
  52 upper layers of the kernel.
  53 The set of system calls available for devices is chosen from
  54 .Xr open 2 ,
  55 .Xr close 2 ,
  56 .Xr read 2 ,
  57 .Xr write 2 ,
  58 .Xr ioctl 2 ,
  59 .Xr select 2 ,
  60 and
  61 .Xr mmap 2 .
  62 Not all drivers implement all system calls; for example, calling
  63 .Xr mmap 2
  64 on a keyboard device is not likely to be useful.
  65 .Pp
  66 Aspects of the device abstraction have changed significantly in
  67 .Fx
  68 over the past two decades.
  69 The section
  70 .Sx Historical Notes
  71 describes some of the more important differences.
  72 .Ss Accessing Devices
  73 Most of the devices in
  74 .Fx
  75 are accessed through
  76 .Em device nodes ,
  77 sometimes also called
  78 .Em special files .
  79 They are located within instances of the
  80 .Xr devfs 5
  81 filesystem, which is conventionally mounted on the directory
  82 .Pa /dev
  83 in the file system hierarchy
  84 (see also
  85 .Xr hier 7 ) .
  86 .Pp
  87 The
  88 .Xr devfs 5
  89 filesystem creates or removes device nodes automatically according to
  90 the physical hardware recognized as present at any given time.
  91 For pseudo-devices, device nodes may be created and removed dynamically
  92 as required, depending on the nature of the device.
  93 .Pp
  94 Access restrictions to device nodes are usually subject to the regular
  95 file permissions of the device node entry, instead of being enforced
  96 directly by the drivers in the kernel.
  97 But since device nodes are not stored persistently between reboots,
  98 those file permissions are set at boot time from rules specified in
  99 .Xr devfs.conf 5 ,
 100 or dynamically according to rules defined in
 101 .Xr devfs.rules 5
 102 or set using the
 103 .Xr devfs 8
 104 command.
 105 In the latter case, different rules may be used to make different sets
 106 of devices visible within different instances of the
 107 .Xr devfs 5
 108 filesystem, which may be used, for example, to prevent jailed
 109 subsystems from accessing unsafe devices.
 110 Manual changes to device
 111 node permissions may still be made, but will not persist.
 112 .Ss Drivers without device nodes
 113 Drivers for network devices do not use device nodes in order to be
 114 accessed.
 115 Their selection is based on other decisions inside the
 116 kernel, and instead of calling
 117 .Xr open 2 ,
 118 use of a network device is generally introduced by using the system
 119 call
 120 .Xr socket 2 .
 121 .Ss Configuring a driver into the kernel
 122 For each kernel, there is a configuration file that is used as a base
 123 to select the facilities and drivers for that kernel, and to tune
 124 several options.
 125 See
 126 .Xr config 8
 127 for a detailed description of the files involved.
 128 The individual manual pages in this section provide a sample line for the
 129 configuration file in their synopsis portions.
 130 See also the files
 131 .Pa /usr/src/sys/conf/NOTES
 132 and
 133 .Pa /usr/src/sys/${ARCH}/conf/NOTES .
 134 .Pp
 135 Drivers need not be statically compiled into the kernel; they may also be
 136 loaded as modules, in which case any device nodes they provide will appear
 137 only after the module is loaded (and has attached to suitable hardware,
 138 if applicable).
 139 .Ss Historical Notes
 140 Prior to
 141 .Fx 6.0 ,
 142 device nodes could be created in the traditional way as persistent
 143 entries in the file system.
 144 While such entries can still be created, they no longer function to
 145 access devices.
 146 .Pp
 147 Prior to
 148 .Fx 5.0 ,
 149 devices for disk and tape drives existed in two variants, known as
 150 .Em block
 151 and
 152 .Em character
 153 devices, or to use better terms, buffered and unbuffered
 154 (raw)
 155 devices.
 156 The traditional names are reflected by the letters
 157 .Dq Li b
 158 and
 159 .Dq Li c
 160 as the file type identification in the output of
 161 .Dq Li ls -l .
 162 Raw devices were traditionally named with a prefix of
 163 .Dq Li r ,
 164 for example
 165 .Pa /dev/rda0
 166 would denote the raw version of the disk whose buffered device was
 167 .Pa /dev/da0 .
 168 .Em This is no longer the case ;
 169 all disk devices are now
 170 .Dq raw
 171 in the traditional sense, even though they are not given
 172 .Dq Li r
 173 prefixes, and
 174 .Dq buffered
 175 devices no longer exist at all.
 176 .Pp
 177 Buffered devices were accessed through a buffer cache maintained by
 178 the operating system; historically this was the system's primary disk
 179 cache, but in
 180 .Fx
 181 this was rendered obsolete by the introduction of unified virtual
 182 memory management.
 183 Buffered devices could be read or written at any
 184 byte position, with the buffer mechanism handling the reading and
 185 writing of disk blocks.
 186 In contrast, raw disk devices can be read or
 187 written only at positions and lengths that are multiples of the
 188 underlying device block size, and
 189 .Xr write 2
 190 calls are
 191 .Em synchronous ,
 192 not returning to the caller until the data has been handed off to the
 193 device.
 194 .Sh SEE ALSO
 195 .Xr close 2 ,
 196 .Xr ioctl 2 ,
 197 .Xr mmap 2 ,
 198 .Xr open 2 ,
 199 .Xr read 2 ,
 200 .Xr select 2 ,
 201 .Xr socket 2 ,
 202 .Xr write 2 ,
 203 .Xr devfs 5 ,
 204 .Xr hier 7 ,
 205 .Xr config 8
 206 .Sh HISTORY
 207 This manual page first appeared in
 208 .Fx 2.1 .
 209 .Sh AUTHORS
 210 .An -nosplit
 211 This man page has been rewritten by
 212 .An Andrew Gierth
 213 from an earlier version written by
 214 .An J\(:org Wunsch
 215 with initial input by
 216 .An David E. O'Brien .