From owner-p4-projects@FreeBSD.ORG Mon Sep 1 22:16:08 2003 Return-Path: Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id F396116A4C1; Mon, 1 Sep 2003 22:16:07 -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 A136816A4BF for ; Mon, 1 Sep 2003 22:16:07 -0700 (PDT) Received: from repoman.freebsd.org (repoman.freebsd.org [216.136.204.115]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0D2FB43F3F for ; Mon, 1 Sep 2003 22:16:07 -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 h825G60U031958 for ; Mon, 1 Sep 2003 22:16:06 -0700 (PDT) (envelope-from marcel@freebsd.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.12.6/8.12.6/Submit) id h825G6jD031955 for perforce@freebsd.org; Mon, 1 Sep 2003 22:16:06 -0700 (PDT) Date: Mon, 1 Sep 2003 22:16:06 -0700 (PDT) Message-Id: <200309020516.h825G6jD031955@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 37356 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: Tue, 02 Sep 2003 05:16:08 -0000 http://perforce.freebsd.org/chv.cgi?CH=37356 Change 37356 by marcel@marcel_nfs on 2003/09/01 22:15:23 FLesh-out the comments. It's rather minimally now, but better than nothing. Affected files ... .. //depot/projects/uart/dev/uart/uart_if.m#8 edit Differences ... ==== //depot/projects/uart/dev/uart/uart_if.m#8 (text+ko) ==== @@ -34,20 +34,27 @@ INTERFACE uart; -# attach() -# XXX needs explanation. +# attach() - attach hardware. +# This method is called when the device is being attached. All resources +# have been allocated. The transmit and receive buffers exist, but no +# high-level (ie tty) initialization has been done yet. +# The intend of this method is to setup the hardware for normal operation. METHOD int attach { struct uart_softc *this; }; -# detach() -# XXX needs explanation. +# detach() - detach hardware. +# This method is called when a device is being detached from its bus. It +# is the first action performed, so even the high-level (ie tty) interface +# is still operational. +# The intend of this method is to disable the hardware. METHOD int detach { struct uart_softc *this; }; -# flush() -# XXX needs explanation. +# flush() - flush FIFOs. +# This method is called to flush the transmitter and/or the receiver as +# specified by the what argument. Characters are expected to be lost. METHOD int flush { struct uart_softc *this; int what; @@ -58,8 +65,8 @@ # delta bits. The delta bits include those corresponding to DTE signals # when they were changed by a call to setsig. The delta bits maintained # by the hardware driver are cleared as a side-effect. A second call to -# this function will have not have any delta bits set, unless there was -# a change in the signals in the mean time. +# this function will not have any delta bits set, unless there was a +# change in the signals in the mean time. METHOD int getsig { struct uart_softc *this; }; @@ -77,8 +84,8 @@ struct uart_softc *this; } -# param() -# XXX needs explanation. +# param() - set communication parameters. +# This method is called to change the communication parameters. METHOD int param { struct uart_softc *this; int baudrate; @@ -87,8 +94,10 @@ int parity; }; -# probe() -# XXX needs explanation. +# probe() - detect hardware. +# This method is called as part of the bus probe to make sure the +# hardware exists. This function should also set the device description +# to something that represents the hardware. METHOD int probe { struct uart_softc *this; }; @@ -111,7 +120,9 @@ }; # transmit() - move data from the transmit buffer to the transmit FIFO. -# XXX needs explanation. +# This method is responsible for writing the Tx buffer to the UART and +# additionally should make sure that a transmit interrupt is generated +# when transmission is complete. METHOD int transmit { struct uart_softc *this; };