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>