PERFORCE change 37356 for review

[Marcel Moolenaar]

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

Change 37356 by marcel at 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;
 };