From owner-svn-src-all@freebsd.org Thu Apr 4 18:52:04 2019 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 363261553646; Thu, 4 Apr 2019 18:52:04 +0000 (UTC) (envelope-from ygy@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id CB3C1875C8; Thu, 4 Apr 2019 18:52:03 +0000 (UTC) (envelope-from ygy@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id B282F17AE; Thu, 4 Apr 2019 18:52:03 +0000 (UTC) (envelope-from ygy@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x34Iq3o6081611; Thu, 4 Apr 2019 18:52:03 GMT (envelope-from ygy@FreeBSD.org) Received: (from ygy@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x34Iq3Rs081610; Thu, 4 Apr 2019 18:52:03 GMT (envelope-from ygy@FreeBSD.org) Message-Id: <201904041852.x34Iq3Rs081610@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: ygy set sender to ygy@FreeBSD.org using -f From: Guangyuan Yang Date: Thu, 4 Apr 2019 18:52:03 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r345887 - head/share/man/man4 X-SVN-Group: head X-SVN-Commit-Author: ygy X-SVN-Commit-Paths: head/share/man/man4 X-SVN-Commit-Revision: 345887 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: CB3C1875C8 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.96 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.999,0]; NEURAL_HAM_SHORT(-0.96)[-0.962,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US]; NEURAL_HAM_LONG(-1.00)[-1.000,0] X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 04 Apr 2019 18:52:04 -0000 Author: ygy (doc committer) Date: Thu Apr 4 18:52:03 2019 New Revision: 345887 URL: https://svnweb.freebsd.org/changeset/base/345887 Log: 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 Modified: head/share/man/man4/intro.4 Modified: head/share/man/man4/intro.4 ============================================================================== --- head/share/man/man4/intro.4 Thu Apr 4 18:37:30 2019 (r345886) +++ head/share/man/man4/intro.4 Thu Apr 4 18:52:03 2019 (r345887) @@ -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 .