Attachment 203325 Details for Bug 236970 – rewrite of intro(4)

[patch] rewrite of intro(4)

intro.diff (text/plain), 7.68 KB, created by Andrew "RhodiumToad" Gierth on 2019-04-02 17:54:06 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Andrew "RhodiumToad" Gierth

Created: 2019-04-02 17:54:06 UTC

Size: 7.68 KB

patch

obsolete

>diff --git a/share/man/man4/intro.4 b/share/man/man4/intro.4
>index 93a9ab59d25d..86732cf76fc3 100644
>--- a/share/man/man4/intro.4
>+++ b/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 2, 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,70 @@ 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
>+.Ql b
>+and
>+.Ql c
>+as the file type identification in the output of
>+.Ql ls -l .
>+Raw devices were traditionally named with a prefix of
>+.Ql 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
>+.Ql raw
>+in the traditional sense, even though they are not given
>+.Ql r
>+prefixes, and
>+.Ql 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 +209,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 .

Actions: View | Diff

Attachments on bug 236970: 203325 | 203339