PERFORCE change 134943 for review

[Hans Petter Selasky]

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

Change 134943 by hselasky at hselasky_laptop001 on 2008/02/07 00:48:21

	
	Add more documentation - not complete yet.

Affected files ...

.. //depot/projects/usb/src/sys/dev/usb/usb_transfer.c#111 edit

Differences ...

==== //depot/projects/usb/src/sys/dev/usb/usb_transfer.c#111 (text+ko) ====

@@ -154,6 +154,12 @@
 
 #endif
 
+/*------------------------------------------------------------------------*
+ *	usb_get_devid
+ *
+ * This function returns the USB Vendor and Product ID like a 32-bit
+ * unsigned integer.
+ *------------------------------------------------------------------------*/
 uint32_t
 usb_get_devid(device_t dev)
 {
@@ -201,6 +207,16 @@
 	return (pipe);
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_get_pipe
+ *
+ * This function searches for an USB pipe based on the information
+ * given by the passed "struct usbd_config" pointer.
+ *
+ * Return values:
+ * NULL: No match.
+ * Else: Pointer to "struct usbd_pipe".
+ *------------------------------------------------------------------------*/
 struct usbd_pipe *
 usbd_get_pipe(struct usbd_device *udev, uint8_t iface_index,
     const struct usbd_config *setup)
@@ -292,6 +308,13 @@
 	return (pipe);
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_interface_count
+ *
+ * This function stores the number of USB interfaces excluding
+ * alternate settings, which the USB config descriptor reports into
+ * the unsigned 8-bit integer pointed to by "count".
+ *------------------------------------------------------------------------*/
 usbd_status_t
 usbd_interface_count(struct usbd_device *udev, uint8_t *count)
 {
@@ -312,6 +335,10 @@
 
 };
 
+/*
+ * This table stores the all the allowed packet sizes based on
+ * endpoint type and USB speed:
+ */
 static const struct usbd_std_packet_size
 	usbd_std_packet_size[4][USB_SPEED_MAX] = {
 
@@ -344,6 +371,12 @@
 	},
 };
 
+/*------------------------------------------------------------------------*
+ *	usbd_compute_max_frame_size
+ *
+ * This function computes the maximum frame size, hence high speed USB
+ * can transfer multiple consecutive packets.
+ *------------------------------------------------------------------------*/
 static void
 usbd_compute_max_frame_size(struct usbd_xfer *xfer)
 {
@@ -2076,6 +2109,12 @@
 	return;
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_callback_intr_sched
+ *
+ * This function gets the USB callback thread running if it is
+ * sleeping.
+ *------------------------------------------------------------------------*/
 static void
 usbd_callback_intr_sched(struct usbd_memory_info *info)
 {
@@ -2088,6 +2127,11 @@
 	return;
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_callback_intr_td_sub - factored out code
+ *
+ * This function performs USB callbacks.
+ *------------------------------------------------------------------------*/
 static void
 usbd_callback_intr_td_sub(struct usbd_xfer **xfer, uint8_t dropcount)
 {
@@ -2190,6 +2234,14 @@
 	return;
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_dma_delay_done_cb
+ *
+ * This function is called when the DMA delay has been exectuded, and
+ * will make sure that the callback is called to complete the USB
+ * transfer. This code path is ususally only used when there is an USB
+ * error like USBD_ERR_CANCELLED.
+ *------------------------------------------------------------------------*/
 static void
 usbd_dma_delay_done_cb(struct usbd_xfer *xfer)
 {
@@ -2489,6 +2541,13 @@
 	return;
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_delayed_transfer_start
+ *
+ * This function is called to start the USB transfer when
+ * "xfer->interval" is greater than zero, and and the endpoint type is
+ * BULK or CONTROL.
+ *------------------------------------------------------------------------*/
 static void
 usbd_delayed_transfer_start(void *arg)
 {
@@ -3803,6 +3862,9 @@
 	return (err);
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_fill_get_report - factored out code
+ *------------------------------------------------------------------------*/
 void
 usbd_fill_get_report(usb_device_request_t *req, uint8_t iface_no,
     uint8_t type, uint8_t id, uint16_t size)
@@ -3816,6 +3878,9 @@
 	return;
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_fill_set_report - factored out code
+ *------------------------------------------------------------------------*/
 void
 usbd_fill_set_report(usb_device_request_t *req, uint8_t iface_no,
     uint8_t type, uint8_t id, uint16_t size)
@@ -3829,6 +3894,11 @@
 	return;
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_clear_data_toggle - factored out code
+ *
+ * NOTE: the job of this function is not to reset the hardware data toggle.
+ *------------------------------------------------------------------------*/
 void
 usbd_clear_data_toggle(struct usbd_device *udev, struct usbd_pipe *pipe)
 {
@@ -3932,9 +4002,11 @@
  * };
  */
 
-/*
+/*------------------------------------------------------------------------*
+ *	usbd_do_poll
+ *
  * called from keyboard driver when in polling mode
- */
+ *------------------------------------------------------------------------*/
 void
 usbd_do_poll(struct usbd_device *udev)
 {
@@ -3942,10 +4014,12 @@
 	return;
 }
 
-/*
+/*------------------------------------------------------------------------*
+ *	usb_match_device
+ *
  * Search for a vendor/product pair in an array.  The item size is
  * given as an argument.
- */
+ *------------------------------------------------------------------------*/
 const struct usb_devno *
 usb_match_device(const struct usb_devno *tbl, u_int nentries, u_int size,
     uint16_t vendor, uint16_t product)
@@ -3962,6 +4036,9 @@
 	return (NULL);
 }
 
+/*------------------------------------------------------------------------*
+ *	usbd_driver_load
+ *------------------------------------------------------------------------*/
 int
 usbd_driver_load(struct module *mod, int what, void *arg)
 {