Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 11 Apr 2019 00:41:07 +0000 (UTC)
From:      Guangyuan Yang <ygy@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-12@freebsd.org
Subject:   svn commit: r346111 - stable/12/share/man/man4
Message-ID:  <201904110041.x3B0f7RP081758@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: ygy (doc committer)
Date: Thu Apr 11 00:41:07 2019
New Revision: 346111
URL: https://svnweb.freebsd.org/changeset/base/346111

Log:
  MFC r345887:
  
  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
  
  PR:		236970
  Submitted by:	andrew@tao173.riddles.org.uk
  Reviewed by:	0mp
  Differential Revision:	https://reviews.freebsd.org/D19799

Modified:
  stable/12/share/man/man4/intro.4
Directory Properties:
  stable/12/   (props changed)

Modified: stable/12/share/man/man4/intro.4
==============================================================================
--- stable/12/share/man/man4/intro.4	Thu Apr 11 00:39:06 2019	(r346110)
+++ stable/12/share/man/man4/intro.4	Thu Apr 11 00:41:07 2019	(r346111)
@@ -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.
+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
-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).
-.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 .



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201904110041.x3B0f7RP081758>