Changeset cf002dbf in mainline

Timestamp:

2011-05-11T19:31:16Z (14 years ago)

Author:

Vojtech Horky <vojtechhorky@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

5f0fe4e9

Parents:

70c12d6

Message:

Add comments to mass storage driver

Location:

uspace/drv/usbmast

Files:

• inquiry.c (modified) (4 diffs)
• mast.c (modified) (3 diffs)
• mast.h (modified) (1 diff)

uspace/drv/usbmast/inquiry.c

@@ -55 +55 @@
 
 #define STR_UNKNOWN "<unknown>"
+
+/** String constants for SCSI peripheral device types. */
 static const char *str_peripheral_device_types[] = {
         "direct-access device",
@@ -92 +94 @@
         (sizeof(str_peripheral_device_types)/sizeof(str_peripheral_device_types[0]))
 
+/** Get string representation for SCSI peripheral device type.
+ *
+ * See for example here for a list
+ * http://en.wikipedia.org/wiki/SCSI_Peripheral_Device_Type.
+ *
+ * @param type SCSI peripheral device type code.
+ * @return String representation.
+ */
 const char *usb_str_masstor_scsi_peripheral_device_type(int type)
 {
@@ -101 +111 @@
 }
 
+/** Trim trailing spaces from a string (rewrite with string terminator).
+ *
+ * @param name String to be trimmed (in-out parameter).
+ */
 static void trim_trailing_spaces(char *name)
 {
@@ -110 +124 @@
 }
 
+/** Perform SCSI INQUIRY command on USB mass storage device.
+ *
+ * @param dev USB device.
+ * @param bulk_in_idx Index (in dev->pipes) of bulk in pipe.
+ * @param bulk_out_idx Index of bulk out pipe.
+ * @param inquiry_result Where to store parsed inquiry result.
+ * @return Error code.
+ */
 int usb_massstor_inquiry(usb_device_t *dev,
     size_t bulk_in_idx, size_t bulk_out_idx,

uspace/drv/usbmast/mast.c

@@ -139 +139 @@
 }
 
+/** Perform bulk-only mass storage reset.
+ *
+ * @param dev Device to be reseted.
+ * @return Error code.
+ */
 int usb_massstor_reset(usb_device_t *dev)
 {
@@ -146 +151 @@
 }
 
+/** Perform complete reset recovery of bulk-only mass storage.
+ *
+ * Notice that no error is reported because if this fails, the error
+ * would reappear on next transaction somehow.
+ *
+ * @param dev Device to be reseted.
+ * @param bulk_in_idx Index of bulk in pipe.
+ * @param bulk_out_idx Index of bulk out pipe.
+ */
 void usb_massstor_reset_recovery(usb_device_t *dev,
     size_t bulk_in_idx, size_t bulk_out_idx)
@@ -157 +171 @@
 }
 
+/** Get max LUN of a mass storage device.
+ *
+ * @warning Error from this command does not necessarily indicate malfunction
+ * of the device. Device does not need to support this request.
+ *
+ * @param dev Mass storage device.
+ * @return Error code of maximum LUN (index, not count).
+ */
 int usb_massstor_get_max_lun(usb_device_t *dev)
 {

uspace/drv/usbmast/mast.h

@@ -42 +42 @@
 #include <usb/devdrv.h>
 
+/** Result of SCSI INQUIRY command.
+ * This is already parsed structure, not the original buffer returned by
+ * the device.
+ */
 typedef struct {
+        /** SCSI peripheral device type. */
         int peripheral_device_type;
+        /** Whether the device is removable. */
         bool removable;
+        /** Vendor ID string. */
         char vendor_id[9];
+        /** Product ID and product revision string. */
         char product_and_revision[12];
 } usb_massstor_inquiry_result_t;