Differential D19799 Diff 55812 head/share/man/man4/intro.4

Changeset View

Standalone View

head/share/man/man4/intro.4

	.\"			.\"
	.\" Copyright (c) 1996 David E. O'Brien, Joerg Wunsch			.\" Copyright (c) 1996 David E. O'Brien, Joerg Wunsch
				.\" Copyright (c) 2019 Andrew Gierth
	.\"			.\"
	.\" All rights reserved.			.\" All rights reserved.
	.\"			.\"
	.\" Redistribution and use in source and binary forms, with or without			.\" Redistribution and use in source and binary forms, with or without
	.\" modification, are permitted provided that the following conditions			.\" modification, are permitted provided that the following conditions
	.\" are met:			.\" are met:
	.\" 1. Redistributions of source code must retain the above copyright			.\" 1. Redistributions of source code must retain the above copyright
	.\" notice, this list of conditions and the following disclaimer.			.\" notice, this list of conditions and the following disclaimer.
	Show All 9 Lines
	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,			.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY			.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT			.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF			.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.			.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd January 20, 1996			.Dd April 3, 2019
	.Dt INTRO 4			.Dt INTRO 4
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm intro			.Nm intro
	.Nd introduction to devices and device drivers			.Nd introduction to devices and device drivers
	.Sh DESCRIPTION			.Sh DESCRIPTION
	This section contains information related to devices, device drivers			This section contains information related to devices, device drivers
	and miscellaneous hardware.			and miscellaneous hardware.
	.Ss The device abstraction			.Ss The device abstraction
	Device is a term used mostly for hardware-related stuff that belongs			Device is a term used mostly for hardware-related stuff that belongs
	to the system, like disks, printers, or a graphics display with its			to the system, like disks, printers, or a graphics display with its
	keyboard.			keyboard.
	There are also so-called			There are also so-called
	.Em pseudo-devices			.Em pseudo-devices
	where a device driver emulates the behaviour of a device in software			where a device driver emulates the behaviour of a device in software
	without any particular underlying hardware.			without any particular underlying hardware.
	A typical example for			A typical example for
	the latter class is			the latter class is
	.Pa /dev/mem ,			.Pa /dev/mem ,
	a loophole where the physical memory can be accessed using the regular			a mechanism whereby the physical memory can be accessed using file
	file access semantics.			access semantics.
	.Pp			.Pp
	The device abstraction generally provides a common set of system calls			The device abstraction generally provides a common set of system
	layered on top of them, which are dispatched to the corresponding			calls, which are dispatched to the corresponding device driver by the
	device driver by the upper layers of the kernel.			upper layers of the kernel.
	The set of system			The set of system calls available for devices is chosen from
	calls available for devices is chosen from
	.Xr open 2 ,			.Xr open 2 ,
	.Xr close 2 ,			.Xr close 2 ,
	.Xr read 2 ,			.Xr read 2 ,
	.Xr write 2 ,			.Xr write 2 ,
	.Xr ioctl 2 ,			.Xr ioctl 2 ,
	.Xr select 2 ,			.Xr select 2 ,
	and			and
	.Xr mmap 2 .			.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			.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			.Ss Accessing Devices
	Most of the devices in a			Most of the devices in
	.Ux Ns			.Fx
	-like operating system are accessed			are accessed through
	through so-called
	.Em device nodes ,			.Em device nodes ,
	sometimes also called			sometimes also called
	.Em special files .			.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			.Pa /dev
	in the file system hierarchy			in the file system hierarchy
	(see also			(see also
	.Xr hier 7 ) .			.Xr hier 7 ) .
	.Pp			.Pp
	Note that this could lead to an inconsistent state, where either there			The
	are device nodes that do not have a configured driver associated with			.Xr devfs 5
	them, or there may be drivers that have successfully probed for their			filesystem creates or removes device nodes automatically according to
	devices, but cannot be accessed since the corresponding device node is			the physical hardware recognized as present at any given time.
	still missing.			For pseudo-devices, device nodes may be created and removed dynamically
	In the first case, any attempt to reference the device			as required, depending on the nature of 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			.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			Access restrictions to device nodes are usually subject to the regular
	file permissions of the device node entry, instead of being enforced			file permissions of the device node entry, instead of being enforced
	directly by the drivers in the kernel.			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			.Ss Drivers without device nodes
	Drivers for network devices do not use device nodes in order to be			Drivers for network devices do not use device nodes in order to be
	accessed.			accessed.
	Their selection is based on other decisions inside the			Their selection is based on other decisions inside the
	kernel, and instead of calling			kernel, and instead of calling
	.Xr open 2 ,			.Xr open 2 ,
	use of a network device is generally introduced by using the system			use of a network device is generally introduced by using the system
	call			call
	.Xr socket 2 .			.Xr socket 2 .
	.Ss Configuring a driver into the kernel			.Ss Configuring a driver into the kernel
	For each kernel, there is a configuration file that is used as a base			For each kernel, there is a configuration file that is used as a base
	to select the facilities and drivers for that kernel, and to tune			to select the facilities and drivers for that kernel, and to tune
	several options.			several options.
	See			See
	.Xr config 8			.Xr config 8
	for a detailed description of the files involved.			for a detailed description of the files involved.
	The individual manual pages in this section provide a sample line for the			The individual manual pages in this section provide a sample line for the
	configuration file in their synopsis portion.			configuration file in their synopsis portions.
	See also the sample config file			See also the files
	.Pa /sys/i386/conf/LINT			.Pa /usr/src/sys/conf/NOTES
	(for the			and
	.Em i386			.Pa /usr/src/sys/${ARCH}/conf/NOTES .
	architecture).			.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			.Sh SEE ALSO
	.Xr close 2 ,			.Xr close 2 ,
	.Xr ioctl 2 ,			.Xr ioctl 2 ,
	.Xr mmap 2 ,			.Xr mmap 2 ,
	.Xr open 2 ,			.Xr open 2 ,
	.Xr read 2 ,			.Xr read 2 ,
	.Xr select 2 ,			.Xr select 2 ,
	.Xr socket 2 ,			.Xr socket 2 ,
	.Xr write 2 ,			.Xr write 2 ,
	.Xr devfs 5 ,			.Xr devfs 5 ,
	.Xr hier 7 ,			.Xr hier 7 ,
	.Xr config 8			.Xr config 8
	.Sh HISTORY			.Sh HISTORY
	This manual page first appeared in			This manual page first appeared in
	.Fx 2.1 .			.Fx 2.1 .
	.Sh AUTHORS			.Sh AUTHORS
	.An -nosplit			.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			.An J\(:org Wunsch
	with initial input by			with initial input by
	.An David E. O'Brien .			.An David E. O'Brien .