Changeset 863d45e in mainline for uspace/lib/usb/src/usbdrvreq.c

Timestamp:

2011-01-10T11:55:13Z (13 years ago)

Author:

Vojtech Horky <vojtechhorky@…>

Branches:

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

Children:

1ffa73b, a97ea0f

Parents:

263a9f1

Message:

Add some missing comments

File:

• uspace/lib/usb/src/usbdrvreq.c (modified) (17 diffs)

uspace/lib/usb/src/usbdrvreq.c

@@ -36 +36 @@
 #include <errno.h>
 
+/**  Prepare USB target for control endpoint.
+ *
+ * @param name Variable name with the USB target.
+ * @param target_address Target USB address.
+ */
 #define PREPARE_TARGET(name, target_address) \
         usb_target_t name = { \
@@ -42 +47 @@
         }
 
-#define PREPARE_SETUP_PACKET(name, p_direction, p_type, p_recipient, p_request, p_value, p_index, p_length) \
+/** Prepare setup packet.
+ *
+ * @param name Variable name with the setup packet.
+ * @param p_direction Data transfer direction.
+ * @param p_type Request type (standard/class/vendor)
+ * @param p_recipient Recipient of the request.
+ * @param p_request Request.
+ * @param p_value wValue field of setup packet.
+ * @param p_index wIndex field of setup packet.
+ * @param p_length Length of extra data.
+ */
+#define PREPARE_SETUP_PACKET(name, p_direction, p_type, p_recipient, \
+    p_request, p_value, p_index, p_length) \
         usb_device_request_setup_packet_t setup_packet = { \
                 .request_type = \
@@ -54 +71 @@
         }
 
-#define PREPARE_SETUP_PACKET_LOHI(name, p_direction, p_type, p_recipient, p_request, p_value_low, p_value_high, p_index, p_length) \
+/** Prepare setup packet.
+ *
+ * @param name Variable name with the setup packet.
+ * @param p_direction Data transfer direction.
+ * @param p_type Request type (standard/class/vendor)
+ * @param p_recipient Recipient of the request.
+ * @param p_request Request.
+ * @param p_value_low wValue field of setup packet (low byte).
+ * @param p_value_high wValue field of setup packet (high byte).
+ * @param p_index wIndex field of setup packet.
+ * @param p_length Length of extra data.
+ */
+#define PREPARE_SETUP_PACKET_LOHI(name, p_direction, p_type, p_recipient, \
+    p_request, p_value_low, p_value_high, p_index, p_length) \
         PREPARE_SETUP_PACKET(name, p_direction, p_type, p_recipient, \
             p_request, (p_value_low) | ((p_value_high) << 8), \
@@ -61 +91 @@
 /** Retrieve status of a USB device.
  *
- * @param hc_phone
- * @param address
- * @param recipient
- * @param recipient_index
- * @param status
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[in] recipient Recipient of the request.
+ * @param[in] recipient_index Index of @p recipient.
+ * @param[out] status Status (see figure 9-4 in USB 1.1 specification).
+ * @return Error code.
  */
 int usb_drv_req_get_status(int hc_phone, usb_address_t address,
@@ -100 +130 @@
 /** Clear or disable USB device feature.
  *
- * @param hc_phone
- * @param address
- * @param recipient
- * @param selector
- * @param index
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[in] recipient Recipient of the request.
+ * @param[in] selector Feature selector.
+ * @param[in] index Index of @p recipient.
+ * @return Error code.
  */
 int usb_drv_req_clear_feature(int hc_phone, usb_address_t address,
@@ -125 +155 @@
 /** Set or enable USB device feature.
  *
- * @param hc_phone
- * @param address
- * @param recipient
- * @param selector
- * @param index
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[in] recipient Recipient of the request.
+ * @param[in] selector Feature selector.
+ * @param[in] index Index of @p recipient.
+ * @return Error code.
  */
 int usb_drv_req_set_feature(int hc_phone, usb_address_t address,
@@ -156 +186 @@
  * @see usb_drv_bind_address
  *
- * @param phone Open phone to HC driver.
- * @param old_address Current address.
- * @param address Address to be set.
+ * @param[in] phone Open phone to HC driver.
+ * @param[in] old_address Current address.
+ * @param[in] address Address to be set.
  * @return Error code.
  */
@@ -179 +209 @@
  *
  * @param[in] hc_phone Open phone to HC driver.
- * @param[in] address Device USB address.
+ * @param[in] address Device address.
  * @param[in] request_type Request type (standard/class/vendor).
  * @param[in] descriptor_type Descriptor type (device/configuration/HID/...).
@@ -221 +251 @@
  *
  * @param[in] phone Open phone to HC driver.
- * @param[in] address Device USB address.
+ * @param[in] address Device address.
  * @param[out] descriptor Storage for the device descriptor.
  * @return Error code.
@@ -266 +296 @@
  *
  * @param[in] phone Open phone to HC driver.
- * @param[in] address Device USB address.
+ * @param[in] address Device address.
  * @param[in] index Configuration descriptor index.
  * @param[out] descriptor Storage for the configuration descriptor.
@@ -308 +338 @@
  *
  * @warning The @p buffer might be touched (i.e. its contents changed)
- * even when error occurres.
+ * even when error occurs.
  *
  * @param[in] phone Open phone to HC driver.
- * @param[in] address Device USB address.
+ * @param[in] address Device address.
  * @param[in] index Configuration descriptor index.
  * @param[out] buffer Buffer for the whole configuration descriptor.
@@ -335 +365 @@
 /** Update existing descriptor of a USB device.
  *
- * @param hc_phone
- * @param address
- * @param descriptor_type
- * @param descriptor_index
- * @param language
- * @param descriptor
- * @param descriptor_size
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[in] descriptor_type Descriptor type (device/configuration/...).
+ * @param[in] descriptor_index Descriptor index.
+ * @param[in] language Language index.
+ * @param[in] descriptor Actual descriptor data.
+ * @param[in] descriptor_size Descriptor size.
+ * @return Error code.
  */
 int usb_drv_req_set_descriptor(int hc_phone, usb_address_t address,
@@ -349 +379 @@
     void *descriptor, size_t descriptor_size)
 {
+        // FIXME: check that descriptor is not too big
+
         PREPARE_TARGET(target, address);
 
@@ -365 +397 @@
 /** Determine current configuration value of USB device.
  *
- * @param hc_phone
- * @param address
- * @param configuration_value
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[out] configuration_value Current configuration value.
+ * @return Error code.
  */
 int usb_drv_req_get_configuration(int hc_phone, usb_address_t address,
@@ -403 +435 @@
 /** Set configuration of USB device.
  *
- * @param hc_phone
- * @param address
- * @param configuration_value
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[in] configuration_value New configuration value.
+ * @return Error code.
  */
 int usb_drv_req_set_configuration(int hc_phone, usb_address_t address,
@@ -426 +458 @@
 /** Determine alternate setting of USB device interface.
  *
- * @param hc_phone
- * @param address
- * @param interface_index
- * @param alternate_setting
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[in] interface_index Interface index.
+ * @param[out] alternate_setting Value of alternate setting.
+ * @return Error code.
  */
 int usb_drv_req_get_interface(int hc_phone, usb_address_t address,
@@ -465 +497 @@
 /** Select an alternate setting of USB device interface.
  *
- * @param hc_phone
- * @param address
- * @param interface_index
- * @param alternate_setting
- * @return
+ * @param[in] hc_phone Open phone to HC driver.
+ * @param[in] address Device address.
+ * @param[in] interface_index Interface index.
+ * @param[in] alternate_setting Value of alternate setting.
+ * @return Error code.
  */
 int usb_drv_req_set_interface(int hc_phone, usb_address_t address,