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