Rewrite intro(4) man page.

- Remove issues that no longer apply thanks to devfs
- Add language pointing out devfs's role and referencing its config
- Add a "historical notes" section and move discussion of block vs character devs to it, including pointing out the removal of block devs
- Modernize some examples

MFC after:	1 week
PR:		236970
Submitted by:	andrew@tao173.riddles.org.uk
Reviewed by:	0mp
Differential Revision:	https://reviews.freebsd.org/D19799

share/man/man4/intro.4

@@ -1,5 +1,6 @@
 .\"
 .\" Copyright (c) 1996 David E. O'Brien, Joerg Wunsch
+.\" Copyright (c) 2019 Andrew Gierth
 .\"
 .\" All rights reserved.
 .\"
@@ -25,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 20, 1996
+.Dd April 3, 2019
 .Dt INTRO 4
 .Os
 .Sh NAME
@@ -45,14 +46,13 @@ without any particular underlying hardware.
 A typical example for
 the latter class is
 .Pa /dev/mem ,
-a loophole where the physical memory can be accessed using the regular
-file access semantics.
+a mechanism whereby the physical memory can be accessed using file
+access semantics.
 .Pp
-The device abstraction generally provides a common set of system calls
-layered on top of them, which are dispatched to the corresponding
-device driver by the upper layers of the kernel.
-The set of system
-calls available for devices is chosen from
+The device abstraction generally provides a common set of system
+calls, which are dispatched to the corresponding device driver by the
+upper layers of the kernel.
+The set of system calls available for devices is chosen from
 .Xr open 2 ,
 .Xr close 2 ,
 .Xr read 2 ,
@@ -61,77 +61,56 @@ calls available for devices is chosen from
 .Xr select 2 ,
 and
 .Xr mmap 2 .
-Not all drivers implement all system calls, for example, calling
+Not all drivers implement all system calls; for example, calling
 .Xr mmap 2
-on terminal devices is likely to be not useful at all.
+on a keyboard device is not likely to be useful.
+.Pp
+Aspects of the device abstraction have changed significantly in
+.Fx
+over the past two decades.
+The section
+.Sx Historical Notes
+describes some of the more important differences.
 .Ss Accessing Devices
-Most of the devices in a
-.Ux Ns
--like operating system are accessed
-through so-called
+Most of the devices in
+.Fx
+are accessed through
 .Em device nodes ,
 sometimes also called
 .Em special files .
-They are usually located under the directory
+They are located within instances of the
+.Xr devfs 5
+filesystem, which is conventionally mounted on the directory
 .Pa /dev
 in the file system hierarchy
 (see also
 .Xr hier 7 ) .
 .Pp
-Note that this could lead to an inconsistent state, where either there
-are device nodes that do not have a configured driver associated with
-them, or there may be drivers that have successfully probed for their
-devices, but cannot be accessed since the corresponding device node is
-still missing.
-In the first case, any attempt to reference the device
-through the device node will result in an error, returned by the upper
-layers of the kernel, usually
-.Er ENXIO .
-In the second case, the device node needs to be created before the
-driver and its device will be usable.
-.Pp
-Some devices come in two flavors:
-.Em block
-and
-.Em character
-devices, or to use better terms, buffered and unbuffered
-(raw)
-devices.
-The traditional names are reflected by the letters
-.Ql b
-and
-.Ql c
-as the file type identification in the output of
-.Ql ls -l .
-Buffered devices are being accessed through the buffer cache of the
-operating system, and they are solely intended to layer a file system
-on top of them.
-They are normally implemented for disks and disk-like
-devices only and, for historical reasons, for tape devices.
-.Pp
-Raw devices are available for all drivers, including those that also
-implement a buffered device.
-For the latter group of devices, the
-differentiation is conventionally done by prepending the letter
-.Ql r
-to the path name of the device node, for example
-.Pa /dev/rda0
-denotes the raw device for the first SCSI disk, while
-.Pa /dev/da0
-is the corresponding device node for the buffered device.
-.Pp
-Unbuffered devices should be used for all actions that are not related
-to file system operations, even if the device in question is a disk
-device.
-This includes making backups of entire disk partitions, or
-to
-.Em raw
-floppy disks
-(i.e., those used like tapes).
+The
+.Xr devfs 5
+filesystem creates or removes device nodes automatically according to
+the physical hardware recognized as present at any given time.
+For pseudo-devices, device nodes may be created and removed dynamically
+as required, depending on the nature of the device.
 .Pp
 Access restrictions to device nodes are usually subject to the regular
 file permissions of the device node entry, instead of being enforced
 directly by the drivers in the kernel.
+But since device nodes are not stored persistently between reboots,
+those file permissions are set at boot time from rules specified in
+.Xr devfs.conf 5 ,
+or dynamically according to rules defined in
+.Xr devfs.rules 5
+or set using the
+.Xr devfs 8
+command.
+In the latter case, different rules may be used to make different sets
+of devices visible within different instances of the
+.Xr devfs 5
+filesystem, which may be used, for example, to prevent jailed
+subsystems from accessing unsafe devices.
+Manual changes to device
+node permissions may still be made, but will not persist.
 .Ss Drivers without device nodes
 Drivers for network devices do not use device nodes in order to be
 accessed.
@@ -149,12 +128,71 @@ See
 .Xr config 8
 for a detailed description of the files involved.
 The individual manual pages in this section provide a sample line for the
-configuration file in their synopsis portion.
-See also the sample config file
-.Pa /sys/i386/conf/LINT
-(for the
-.Em i386
-architecture).
+configuration file in their synopsis portions.
+See also the files
+.Pa /usr/src/sys/conf/NOTES
+and
+.Pa /usr/src/sys/${ARCH}/conf/NOTES .
+.Pp
+Drivers need not be statically compiled into the kernel; they may also be
+loaded as modules, in which case any device nodes they provide will appear
+only after the module is loaded (and has attached to suitable hardware,
+if applicable).
+.Ss Historical Notes
+Prior to
+.Fx 6.0 ,
+device nodes could be created in the traditional way as persistent
+entries in the file system.
+While such entries can still be created, they no longer function to
+access devices.
+.Pp
+Prior to
+.Fx 5.0 ,
+devices for disk and tape drives existed in two variants, known as
+.Em block
+and
+.Em character
+devices, or to use better terms, buffered and unbuffered
+(raw)
+devices.
+The traditional names are reflected by the letters
+.Dq Li b
+and
+.Dq Li c
+as the file type identification in the output of
+.Dq Li ls -l .
+Raw devices were traditionally named with a prefix of
+.Dq Li r ,
+for example
+.Pa /dev/rda0
+would denote the raw version of the disk whose buffered device was
+.Pa /dev/da0 .
+.Em This is no longer the case ;
+all disk devices are now
+.Dq raw
+in the traditional sense, even though they are not given
+.Dq Li r
+prefixes, and
+.Dq buffered
+devices no longer exist at all.
+.Pp
+Buffered devices were accessed through a buffer cache maintained by
+the operating system; historically this was the system's primary disk
+cache, but in
+.Fx
+this was rendered obsolete by the introduction of unified virtual
+memory management.
+Buffered devices could be read or written at any
+byte position, with the buffer mechanism handling the reading and
+writing of disk blocks.
+In contrast, raw disk devices can be read or
+written only at positions and lengths that are multiples of the
+underlying device block size, and
+.Xr write 2
+calls are
+.Em synchronous ,
+not returning to the caller until the data has been handed off to the
+device.
 .Sh SEE ALSO
 .Xr close 2 ,
 .Xr ioctl 2 ,
@@ -172,7 +210,9 @@ This manual page first appeared in
 .Fx 2.1 .
 .Sh AUTHORS
 .An -nosplit
-This man page has been written by
+This man page has been rewritten by
+.An Andrew Gierth
+from an earlier version written by
 .An J\(:org Wunsch
 with initial input by
 .An David E. O'Brien .