From owner-p4-projects@FreeBSD.ORG Wed Sep 3 17:49:19 2003 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 7BC1316A4C1; Wed, 3 Sep 2003 17:49:19 -0700 (PDT) Delivered-To: perforce@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 1001316A4BF for ; Wed, 3 Sep 2003 17:49:19 -0700 (PDT) Received: from repoman.freebsd.org (repoman.freebsd.org [216.136.204.115]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0640F43FEA for ; Wed, 3 Sep 2003 17:49:18 -0700 (PDT) (envelope-from marcel@freebsd.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.12.6/8.12.6) with ESMTP id h840nH0U041207 for ; Wed, 3 Sep 2003 17:49:17 -0700 (PDT) (envelope-from marcel@freebsd.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.12.6/8.12.6/Submit) id h840nHtg041204 for perforce@freebsd.org; Wed, 3 Sep 2003 17:49:17 -0700 (PDT) Date: Wed, 3 Sep 2003 17:49:17 -0700 (PDT) Message-Id: <200309040049.h840nHtg041204@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to marcel@freebsd.org using -f From: Marcel Moolenaar To: Perforce Change Reviews Subject: PERFORCE change 37468 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 04 Sep 2003 00:49:20 -0000 http://perforce.freebsd.org/chv.cgi?CH=37468 Change 37468 by marcel@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