PERFORCE change 37468 for review

[Marcel Moolenaar]

http://perforce.freebsd.org/chv.cgi?CH=37468

Change 37468 by marcel at marcel_nfs on 2003/09/03 17:48:26

	Flesh-out the manpage. Describe the 4 components: core, hardware
	drivers, system devices and kernel interfaces. The intend is to
	provide a structure in which we can explain options, tunables
	and whatnots. With the potential of the driver I expect a wealth
	of options in the (near) future and we need a good way to explain
	them.

Affected files ...

.. //depot/projects/uart/dev/uart/uart.4#3 edit

Differences ...

==== //depot/projects/uart/dev/uart/uart.4#3 (text+ko) ====

@@ -28,15 +28,18 @@
 .Dd August 25, 2003
 .Dt UART 4
 .Os
+.\"
 .Sh NAME
 .Nm uart
 .Nd driver for Universal Asynchronous Receiver/Transmitter (UART) devices
+.\"
 .Sh SYNOPSIS
 .Cd "device uart"
 .Pp
 .Cd "device puc"
 .Cd "device uart"
 .Pp
+.\"
 .Sh DESCRIPTION
 The
 .Nm
@@ -46,8 +49,8 @@
 the
 .Nm
 driver.
-The primary support for devices that provide multiple serial interfaces or
-that provide other functionality besides one or more serial interfaces is
+The primary support for devices that contain multiple serial interfaces or
+that contain other functionality besides one or more serial interfaces is
 provided by the
 .Xr puc 4
 device driver.
@@ -62,8 +65,49 @@
 .Nm
 driver and hides the complexities that are inherent when elementary components
 are packaged together.
+.Pp
+The
+.Nm
+driver has a modular design to allow it to be used on differing hardware and
+for various purposes.
+In the following sections the components are discussed in detail.
+Options are described in the section that covers the component to which each
+option applies.
+.\"
+.Ss CORE COMPONENT
+At the heart of the
+.Nm
+driver is the core component. It contains the bus attachments and the low-level
+interrupt handler.
+.\"
+.Ss HARDWARE DRIVERS
+The core component and the kernel interfaces talk to the hardware through the
+hardware interface.
+This interface serves as an abstraction of the hardware and allows varying
+UARTs to be used for serial communications.
+.\"
+.Ss SYSTEM DEVICES
+System devices are UARTs that have a special purpose by way of hardware
+design or software setup.
+For example, Sun UltraSparc machines use UARTs as their keyboard interface.
+Such an UART cannot be used for general purpose communications.
+Likewise, when the kernel is configured for a serial console, the
+corresponding UART will in turn be a system device so that the kernel can
+output boot messages early on in the boot process.
+.\"
+.Ss KERNEL INTERFACES
+The last but not least of the components is the kernel interface.
+This component ultimately determines how the UART is made visible to the
+kernel in particular and to users in general.
+The default kernel interface is the TTY interface.
+This allows the UART to be used for terminals, modems and serial line IP
+applications.
+System devices, with the notable exception of serial consoles, generally
+have specialized kernel interfaces.
+.\"
 .Sh SEE ALSO
 .Xr puc 4
+.\"
 .Sh HISTORY
 The
 .Nm