Changeset 69df9373 in mainline

Timestamp:

2011-04-07T12:14:21Z (13 years ago)

Author:

Vojtech Horky <vojtechhorky@…>

Branches:

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

Children:

a82889e, c1b1944

Parents:

c50941f

Message:

Add missing documentation

Location:

uspace/drv/usbhub

Files:

• ports.c (modified) (7 diffs)
• ports.h (modified) (1 diff)

uspace/drv/usbhub/ports.c

@@ -40 +40 @@
 #include <usb/debug.h>
 
+/** Retrieve port status.
+ *
+ * @param[in] ctrl_pipe Control pipe to use.
+ * @param[in] port Port number (starting at 1).
+ * @param[out] status Where to store the port status.
+ * @return Error code.
+ */
 static int get_port_status(usb_pipe_t *ctrl_pipe, size_t port,
     usb_port_status_t *status)
@@ -66 +73 @@
 }
 
+/** Information for fibril for device discovery. */
 struct add_device_phase1 {
         usb_hub_info_t *hub;
@@ -72 +80 @@
 };
 
+/** Callback for enabling a specific port.
+ *
+ * We wait on a CV until port is reseted.
+ * That is announced via change on interrupt pipe.
+ *
+ * @param port_no Port number (starting at 1).
+ * @param arg Custom argument, points to @c usb_hub_info_t.
+ * @return Error code.
+ */
 static int enable_port_callback(int port_no, void *arg)
 {
@@ -108 +125 @@
 }
 
+/** Fibril for adding a new device.
+ *
+ * Separate fibril is needed because the port reset completion is announced
+ * via interrupt pipe and thus we cannot block here.
+ *
+ * @param arg Pointer to struct add_device_phase1.
+ * @return 0 Always.
+ */
 static int add_device_phase1_worker_fibril(void *arg)
 {
@@ -142 +167 @@
 }
 
+/** Start device adding when connection change is detected.
+ *
+ * This fires a new fibril to complete the device addition.
+ *
+ * @param hub Hub where the change occured.
+ * @param port Port index (starting at 1).
+ * @param speed Speed of the device.
+ * @return Error code.
+ */
 static int add_device_phase1_new_fibril(usb_hub_info_t *hub, size_t port,
     usb_speed_t speed)
@@ -179 +213 @@
 }
 
+/** Process change on a single port.
+ *
+ * @param hub Hub to which the port belongs.
+ * @param port Port index (starting at 1).
+ */
 static void process_port_change(usb_hub_info_t *hub, size_t port)
 {
@@ -252 +291 @@
 }
 
+
+/** Callback for polling hub for port changes.
+ *
+ * @param dev Device where the change occured.
+ * @param change_bitmap Bitmap of changed ports.
+ * @param change_bitmap_size Size of the bitmap in bytes.
+ * @param arg Custom argument, points to @c usb_hub_info_t.
+ * @return Whether to continue polling.
+ */
 bool hub_port_changes_callback(usb_device_t *dev,
     uint8_t *change_bitmap, size_t change_bitmap_size, void *arg)

uspace/drv/usbhub/ports.h

@@ -46 +46 @@
 #include <usb/devdrv.h>
 
+/** Information about single port on a hub. */
 typedef struct {
+        /** Mutex needed by CV for checking port reset. */
         fibril_mutex_t reset_mutex;
+        /** CV for waiting to port reset completion. */
         fibril_condvar_t reset_cv;
+        /** Whether port reset is completed.
+         * Guarded by @c reset_mutex.
+         */
+        bool reset_completed;
+
+        /** Information about attached device. */
         usb_hc_attached_device_t attached_device;
-        bool reset_completed;
 } usb_hub_port_t;
 
+/** Initialize hub port information.
+ *
+ * @param port Port to be initialized.
+ */
 static inline void usb_hub_port_init(usb_hub_port_t *port) {
         port->attached_device.address = -1;