PERFORCE change 135738 for review

[Hans Petter Selasky]

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

Change 135738 by hselasky at hselasky_laptop001 on 2008/02/19 18:56:05

	
	Add more documentation.

Affected files ...

.. //depot/projects/usb/src/sys/dev/usb/usb_template.c#15 edit

Differences ...

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

@@ -48,6 +48,9 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_make_raw_desc
+ *
+ * This function will insert a raw USB descriptor into the generated
+ * USB configuration.
  *------------------------------------------------------------------------*/
 static void
 usbd_make_raw_desc(struct usbd_temp_setup *temp,
@@ -87,6 +90,10 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_make_endpoint_desc
+ *
+ * This function will generate an USB endpoint descriptor from the
+ * given USB template endpoint descriptor, which will be inserted into
+ * the USB configuration.
  *------------------------------------------------------------------------*/
 static void
 usbd_make_endpoint_desc(struct usbd_temp_setup *temp,
@@ -184,6 +191,10 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_make_interface_desc
+ *
+ * This function will generate an USB interface descriptor from the
+ * given USB template interface descriptor, which will be inserted
+ * into the USB configuration.
  *------------------------------------------------------------------------*/
 static void
 usbd_make_interface_desc(struct usbd_temp_setup *temp,
@@ -252,6 +263,10 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_make_config_desc
+ *
+ * This function will generate an USB config descriptor from the given
+ * USB template config descriptor, which will be inserted into the USB
+ * configuration.
  *------------------------------------------------------------------------*/
 static void
 usbd_make_config_desc(struct usbd_temp_setup *temp,
@@ -311,6 +326,9 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_make_device_desc
+ *
+ * This function will generate an USB device descriptor from the
+ * given USB template device descriptor.
  *------------------------------------------------------------------------*/
 static void
 usbd_make_device_desc(struct usbd_temp_setup *temp,
@@ -404,6 +422,10 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_hw_ep_match
+ *
+ * Return values:
+ *    0: The endpoint profile does not match the criterias
+ * Else: The endpoint profile matches the criterias
  *------------------------------------------------------------------------*/
 static uint8_t
 usbd_hw_ep_match(const struct usbd_hw_ep_profile *pf,
@@ -426,6 +448,13 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_hw_ep_find_match
+ *
+ * This function is used to find the best matching endpoint profile
+ * for and endpoint belonging to an USB descriptor.
+ *
+ * Return values:
+ *    0: Success. Got a match.
+ * Else: Failure. No match.
  *------------------------------------------------------------------------*/
 static uint8_t
 usbd_hw_ep_find_match(struct usbd_hw_ep_scratch *ues,
@@ -540,6 +569,13 @@
 
 /*------------------------------------------------------------------------*
  *	usbd_hw_ep_get_needs
+ *
+ * This function will figure out the type and number of endpoints
+ * which are needed for an USB configuration.
+ *
+ * Return values:
+ *    0: Success.
+ * Else: Failure.
  *------------------------------------------------------------------------*/
 static uint8_t
 usbd_hw_ep_get_needs(struct usbd_hw_ep_scratch *ues,
@@ -692,6 +728,9 @@
 /*------------------------------------------------------------------------*
  *	usbd_hw_ep_resolve
  *
+ * This function will try to resolve endpoint requirements by the
+ * given endpoint profiles that the USB hardware reports.
+ *
  * Return values:
  *    0: Success
  * Else: Failure
@@ -962,7 +1001,8 @@
 /*------------------------------------------------------------------------*
  *	usbd_temp_get_desc
  *
- * This function is a demultiplexer for USB device requests.
+ * This function is a demultiplexer for local USB device side control
+ * endpoint requests.
  *------------------------------------------------------------------------*/
 void
 usbd_temp_get_desc(struct usbd_device *udev, usb_device_request_t *req,