Clean up comments

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3207 42af7a65-404d-4744-a932-0658087f49c3

3 files changed, 42 insertions, 34 deletions

diff --git a/nuttx/arch/arm/src/lpc17xx/lpc17_usbhost.c b/nuttx/arch/arm/src/lpc17xx/lpc17_usbhost.c
index 2f162556d..d739f9c2e 100755
--- a/nuttx/arch/arm/src/lpc17xx/lpc17_usbhost.c
+++ b/nuttx/arch/arm/src/lpc17xx/lpc17_usbhost.c
@@ -793,12 +793,12 @@ static int lpc17_classbind(struct lpc17_usbhost_s *priv,
           uvdbg("CLASS_CREATE: %p\n", priv->class);
           if (priv->class)
             {
-              /* Then initialize the newly instantiated class instance */
+              /* Then bind the newly instantiated class instance */
 
-              ret = CLASS_CONFIGDESC(priv->class, configdesc, desclen);
+              ret = CLASS_CONNECT(priv->class, configdesc, desclen);
               if (ret != OK)
                 {
-                  udbg("CLASS_CONFIGDESC failed: %d\n", ret);
+                  udbg("CLASS_CONNECT failed: %d\n", ret);
                   CLASS_DISCONNECTED(priv->class);
                   priv->class = NULL;
                 }
diff --git a/nuttx/drivers/usbhost/usbhost_storage.c b/nuttx/drivers/usbhost/usbhost_storage.c
index f807da758..efc087dcc 100644
--- a/nuttx/drivers/usbhost/usbhost_storage.c
+++ b/nuttx/drivers/usbhost/usbhost_storage.c
@@ -90,7 +90,7 @@
 #define DEV_FORMAT          "/dev/sd%c"
 #define DEV_NAMELEN         10
 
-/* Used in usbhost_configdesc() */
+/* Used in usbhost_connect() */
 
 #define USBHOST_IFFOUND     0x01
 #define USBHOST_BINFOUND    0x02
@@ -175,7 +175,7 @@ static inline int usbhost_inquiry(FAR struct usbhost_state_s *priv);
 /* Worker thread actions */
 
 static void usbhost_destroy(FAR void *arg);
-static void usbhost_statemachine(FAR void *arg);
+static void usbhost_initvolume(FAR void *arg);
 static void usbhost_work(FAR struct usbhost_state_s *priv, worker_t worker);
 
 /* (Little Endian) Data helpers */
@@ -201,8 +201,8 @@ static struct usbhost_class_s *usbhost_create(FAR struct usbhost_driver_s *drvr,
 
 /* struct usbhost_class_s methods */
 
-static int usbhost_configdesc(FAR struct usbhost_class_s *class,
-                              FAR const uint8_t *configdesc, int desclen);
+static int usbhost_connect(FAR struct usbhost_class_s *class,
+                           FAR const uint8_t *configdesc, int desclen);
 static int usbhost_disconnected(FAR struct usbhost_class_s *class);
 
 /* struct block_operations methods */
@@ -784,17 +784,16 @@ static void usbhost_destroy(FAR void *arg)
 }
 
 /****************************************************************************
- * Name: usbhost_statemachine
+ * Name: usbhost_initvolume
  *
  * Description:
- *   The USB mass storage device has been successfully connected.  This is
- *   the state machine for initialization operations.  It is first called
- *   after the configuration descriptor has been received; after that it is
- *   called only on transfer completion events.
+ *   The USB mass storage device has been successfully connected.  This
+ *   completes the initialization operations.  It is first called after the
+ *   configuration descriptor has been received.
  *
- *   When the block driver is fully initialized and registered, the 
- *   completion handler will be called again and this function should no
- *   longer be executed.
+ *   This function is called from the connect() method.  It may either
+ *   execute on (1) the thread of the caller of connect(), or (2) if
+ *   connect() was called from an interrupt handler, on the worker thread.
  *
  * Input Parameters:
  *   arg - A reference to the class instance.
@@ -804,7 +803,7 @@ static void usbhost_destroy(FAR void *arg)
  *
  ****************************************************************************/
 
-static void usbhost_statemachine(FAR void *arg)
+static void usbhost_initvolume(FAR void *arg)
 {
   FAR struct usbhost_state_s *priv = (FAR struct usbhost_state_s *)arg;
   FAR struct usbstrg_csw_s *csw;
@@ -909,7 +908,7 @@ static void usbhost_statemachine(FAR void *arg)
 
   if (result == OK)
     {
-      /* Set up for normal operation as a block device driver */
+      /* Ready for normal operation as a block device driver */
 
       uvdbg("Successfully initialized\n");
     }
@@ -934,7 +933,7 @@ static void usbhost_statemachine(FAR void *arg)
  *   worker - A reference to the worker function to be executed
  *
  * Returned Values:
- *   A uin16_t representing the whole 16-bit integer value
+ *   None
  *
  ****************************************************************************/
 
@@ -968,7 +967,7 @@ static void usbhost_work(FAR struct usbhost_state_s *priv, worker_t worker)
  *   val - A pointer to the first byte of the little endian value.
  *
  * Returned Values:
- *   A uin16_t representing the whole 16-bit integer value
+ *   A uint16_t representing the whole 16-bit integer value
  *
  ****************************************************************************/
 
@@ -987,7 +986,7 @@ static inline uint16_t usbhost_getle16(const uint8_t *val)
  *   val - A pointer to the first byte of the big endian value.
  *
  * Returned Values:
- *   A uin16_t representing the whole 16-bit integer value
+ *   A uint16_t representing the whole 16-bit integer value
  *
  ****************************************************************************/
 
@@ -1060,7 +1059,6 @@ static inline uint32_t usbhost_getbe32(const uint8_t *val)
   return (uint32_t)usbhost_getbe16(val) << 16 | (uint32_t)usbhost_getbe16(&val[2]);
 }
 
-
 /****************************************************************************
  * Name: usbhost_putle32
  *
@@ -1250,7 +1248,7 @@ static FAR struct usbhost_class_s *usbhost_create(FAR struct usbhost_driver_s *d
         {
          /* Initialize class method function pointers */
 
-          priv->class.configdesc   = usbhost_configdesc;
+          priv->class.connect      = usbhost_connect;
           priv->class.disconnected = usbhost_disconnected;
 
           /* The initial reference count is 1... One reference is held by the driver */
@@ -1286,10 +1284,10 @@ static FAR struct usbhost_class_s *usbhost_create(FAR struct usbhost_driver_s *d
  * struct usbhost_class_s methods
  ****************************************************************************/
 /****************************************************************************
- * Name: usbhost_configdesc
+ * Name: usbhost_connect
  *
  * Description:
- *   This function implemented the configdesc() method of struct
+ *   This function implements the connect() method of struct
  *   usbhost_class_s.  This method is a callback into the class
  *   implementation.  It is used to provide the device's configuration
  *   descriptor to the class so that the class may initialize properly
@@ -1303,10 +1301,15 @@ static FAR struct usbhost_class_s *usbhost_create(FAR struct usbhost_driver_s *d
  *   On success, zero (OK) is returned. On a failure, a negated errno value is
  *   returned indicating the nature of the failure
  *
+ * Assumptions:
+ *   This function is probably called on the same thread that called the driver
+ *   enumerate() method.  However, this function may also be called from an
+ *   interrupt handler.
+ *
  ****************************************************************************/
 
-static int usbhost_configdesc(FAR struct usbhost_class_s *class,
-                              FAR const uint8_t *configdesc, int desclen)
+static int usbhost_connect(FAR struct usbhost_class_s *class,
+                           FAR const uint8_t *configdesc, int desclen)
 {
   FAR struct usbhost_state_s *priv = (FAR struct usbhost_state_s *)class;
   FAR struct usb_cfgdesc_s *cfgdesc;
@@ -1446,7 +1449,7 @@ static int usbhost_configdesc(FAR struct usbhost_class_s *class,
 
   /* Now configure the LUNs and register the block driver(s) */
 
-  usbhost_work(priv, usbhost_statemachine);
+  usbhost_work(priv, usbhost_initvolume);
   return OK;
 }
 
@@ -1467,6 +1470,9 @@ static int usbhost_configdesc(FAR struct usbhost_class_s *class,
  *   On success, zero (OK) is returned. On a failure, a negated errno value
  *   is returned indicating the nature of the failure
  *
+ * Assumptions:
+ *   This function may be called from an interrupt handler.
+ *
  ****************************************************************************/
 
 static int usbhost_disconnected(struct usbhost_class_s *class)
diff --git a/nuttx/include/nuttx/usb/usbhost.h b/nuttx/include/nuttx/usb/usbhost.h
index 2139df5e2..8a7457bbd 100644
--- a/nuttx/include/nuttx/usb/usbhost.h
+++ b/nuttx/include/nuttx/usb/usbhost.h
@@ -94,10 +94,10 @@
 #define CLASS_CREATE(reg, drvr, id) ((reg)->create(drvr, id))
 
 /************************************************************************************
- * Name: CLASS_CONFIGDESC
+ * Name: CLASS_CONNECT
  *
  * Description:
- *   This macro will call the configdesc() method of struct usbhost_class_s.  This
+ *   This macro will call the connect() method of struct usbhost_class_s.  This
  *   method is a callback into the class implementation.  It is used to provide the
  *   device's configuration descriptor to the class so that the class may initialize
  *   properly
@@ -112,11 +112,13 @@
  *   returned indicating the nature of the failure
  *
  * Assumptions:
- *   This function may be called from an interrupt handler.
+ *   This function is probably called on the same thread that called the driver
+ *   enumerate() method.  However, this function may also be called from an
+ *   interrupt handler.
  *
  ************************************************************************************/
 
-#define CLASS_CONFIGDESC(class,configdesc,desclen) ((class)->configdesc(class,configdesc,desclen))
+#define CLASS_CONNECT(class,configdesc,desclen) ((class)->connect(class,configdesc,desclen))
 
 /************************************************************************************
  * Name: CLASS_DISCONNECTED
@@ -174,7 +176,7 @@
  *   extract the class ID info from the configuration descriptor, (3) call
  *   usbhost_findclass() to find the class that supports this device, (4)
  *   call the create() method on the struct usbhost_registry_s interface
- *   to get a class instance, and finally (5) call the configdesc() method
+ *   to get a class instance, and finally (5) call the connect() method
  *   of the struct usbhost_class_s interface.  After that, the class is in
  *   charge of the sequence of operations.
  *
@@ -399,7 +401,7 @@ struct usbhost_class_s
    * initialize properly (such as endpoint selections).
    */
 
-  int (*configdesc)(FAR struct usbhost_class_s *class, FAR const uint8_t *configdesc, int desclen);
+  int (*connect)(FAR struct usbhost_class_s *class, FAR const uint8_t *configdesc, int desclen);
 
   /* This method informs the class that the USB device has been disconnected. */
 
@@ -422,7 +424,7 @@ struct usbhost_driver_s
    * extract the class ID info from the configuration descriptor, (3) call
    * usbhost_findclass() to find the class that supports this device, (4)
    * call the create() method on the struct usbhost_registry_s interface
-   * to get a class instance, and finally (5) call the configdesc() method
+   * to get a class instance, and finally (5) call the connect() method
    * of the struct usbhost_class_s interface.  After that, the class is in
    * charge of the sequence of operations.
    */