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