Changes in uspace/lib/drv/include/usbhc_iface.h [357a302:6edd494] in mainline

File:

• uspace/lib/drv/include/usbhc_iface.h (modified) (9 diffs)

uspace/lib/drv/include/usbhc_iface.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libdrv
- * @addtogroup usb
+/** @addtogroup libdrv usb
  * @{
  */
@@ -40 +39 @@
 #include "driver.h"
 #include <usb/usb.h>
-#include <bool.h>
 
 
@@ -53 +51 @@
  *   - argument #1 is target address
  *   - argument #2 is target endpoint
- *   - argument #3 is max packet size of the endpoint
+ *   - argument #3 is buffer size
  * - this call is immediately followed by IPC data write (from caller)
  * - the initial call (and the whole transaction) is answer after the
@@ -66 +64 @@
  *   - argument #1 is target address
  *   - argument #2 is target endpoint
- *   - argument #3 is max packet size of the endpoint
- * - this call is immediately followed by IPC data read (async version)
+ *   - argument #3 is buffer size
  * - the call is not answered until the device returns some data (or until
  *   error occurs)
+ * - if the call is answered with EOK, first argument of the answer is buffer
+ *   hash that could be used to retrieve the actual data
  *
  * Some special methods (NO-DATA transactions) do not send any data. These
  * might behave as both OUT or IN transactions because communication parts
  * where actual buffers are exchanged are omitted.
- **
+ *
+ * The mentioned data retrieval can be done any time after receiving EOK
+ * answer to IN method.
+ * This retrieval is done using the IPC_M_USBHC_GET_BUFFER where
+ * the first argument is buffer hash from call answer.
+ * This call must be immediately followed by data read-in and after the
+ * data are transferred, the initial call (IPC_M_USBHC_GET_BUFFER)
+ * is answered. Each buffer can be retrieved only once.
+ *
  * For all these methods, wrap functions exists. Important rule: functions
  * for IN transactions have (as parameters) buffers where retrieved data
@@ -85 +92 @@
  */
 typedef enum {
+        /** Tell USB address assigned to device.
+         * Parameters:
+         * - devman handle id
+         * Answer:
+         * - EINVAL - unknown handle or handle not managed by this driver
+         * - ENOTSUP - operation not supported by HC (shall not happen)
+         * - arbitrary error code if returned by remote implementation
+         * - EOK - handle found, first parameter contains the USB address
+         */
+        IPC_M_USBHC_GET_ADDRESS,
+
+        /** Asks for data buffer.
+         * See explanation at usb_iface_funcs_t.
+         * This function does not have counter part in functional interface
+         * as it is handled by the remote part itself.
+         */
+        IPC_M_USBHC_GET_BUFFER,
+
+
         /** Reserve usage of default address.
          * This call informs the host controller that the caller will be
@@ -141 +167 @@
         IPC_M_USBHC_INTERRUPT_IN,
 
-        /** Send bulk data to device.
-         * See explanation at usb_iface_funcs_t (OUT transaction).
-         */
-        IPC_M_USBHC_BULK_OUT,
-
-        /** Get bulk data from device.
+
+        /** Start WRITE control transfer.
+         * See explanation at usb_iface_funcs_t (OUT transaction).
+         */
+        IPC_M_USBHC_CONTROL_WRITE_SETUP,
+
+        /** Send control-transfer data to device.
+         * See explanation at usb_iface_funcs_t (OUT transaction).
+         */
+        IPC_M_USBHC_CONTROL_WRITE_DATA,
+
+        /** Terminate WRITE control transfer.
+         * See explanation at usb_iface_funcs_t (NO-DATA transaction).
+         */
+        IPC_M_USBHC_CONTROL_WRITE_STATUS,
+
+
+
+        /** Start READ control transfer.
+         * See explanation at usb_iface_funcs_t (OUT transaction).
+         */
+        IPC_M_USBHC_CONTROL_READ_SETUP,
+
+        /** Get control-transfer data from device.
          * See explanation at usb_iface_funcs_t (IN transaction).
          */
-        IPC_M_USBHC_BULK_IN,
-
-        /** Issue control WRITE transfer.
-         * See explanation at usb_iface_funcs_t (OUT transaction) for
-         * call parameters.
-         * This call is immediately followed by two IPC data writes
-         * from the caller (setup packet and actual data).
-         */
-        IPC_M_USBHC_CONTROL_WRITE,
-
-        /** Issue control READ transfer.
-         * See explanation at usb_iface_funcs_t (IN transaction) for
-         * call parameters.
-         * This call is immediately followed by IPC data write from the caller
-         * (setup packet) and IPC data read (buffer that was read).
-         */
-        IPC_M_USBHC_CONTROL_READ,
+        IPC_M_USBHC_CONTROL_READ_DATA,
+
+        /** Terminate READ control transfer.
+         * See explanation at usb_iface_funcs_t (NO-DATA transaction).
+         */
+        IPC_M_USBHC_CONTROL_READ_STATUS,
+
 
         /* IPC_M_USB_ */
@@ -172 +206 @@
 /** Callback for outgoing transfer. */
 typedef void (*usbhc_iface_transfer_out_callback_t)(device_t *,
-    int, void *);
+    usb_transaction_outcome_t, void *);
 
 /** Callback for incoming transfer. */
 typedef void (*usbhc_iface_transfer_in_callback_t)(device_t *,
-    int, size_t, void *);
+    usb_transaction_outcome_t, size_t, void *);
 
 
 /** Out transfer processing function prototype. */
-typedef int (*usbhc_iface_transfer_out_t)(device_t *, usb_target_t, size_t,
+typedef int (*usbhc_iface_transfer_out_t)(device_t *, usb_target_t,
     void *, size_t,
     usbhc_iface_transfer_out_callback_t, void *);
 
-/** Setup transfer processing function prototype. @deprecated */
+/** Setup transfer processing function prototype. */
 typedef usbhc_iface_transfer_out_t usbhc_iface_transfer_setup_t;
 
 /** In transfer processing function prototype. */
-typedef int (*usbhc_iface_transfer_in_t)(device_t *, usb_target_t, size_t,
+typedef int (*usbhc_iface_transfer_in_t)(device_t *, usb_target_t,
     void *, size_t,
     usbhc_iface_transfer_in_callback_t, void *);
@@ -194 +228 @@
 /** USB host controller communication interface. */
 typedef struct {
-        int (*reserve_default_address)(device_t *, usb_speed_t);
+        int (*tell_address)(device_t *, devman_handle_t, usb_address_t *);
+
+        int (*reserve_default_address)(device_t *);
         int (*release_default_address)(device_t *);
-        int (*request_address)(device_t *, usb_speed_t, usb_address_t *);
+        int (*request_address)(device_t *, usb_address_t *);
         int (*bind_address)(device_t *, usb_address_t, devman_handle_t);
         int (*release_address)(device_t *, usb_address_t);
@@ -203 +239 @@
         usbhc_iface_transfer_in_t interrupt_in;
 
-        usbhc_iface_transfer_out_t bulk_out;
-        usbhc_iface_transfer_in_t bulk_in;
-
-        int (*control_write)(device_t *, usb_target_t,
-            size_t,
-            void *, size_t, void *, size_t,
+        usbhc_iface_transfer_setup_t control_write_setup;
+        usbhc_iface_transfer_out_t control_write_data;
+        int (*control_write_status)(device_t *, usb_target_t,
+            usbhc_iface_transfer_in_callback_t, void *);
+
+        usbhc_iface_transfer_setup_t control_read_setup;
+        usbhc_iface_transfer_in_t control_read_data;
+        int (*control_read_status)(device_t *, usb_target_t,
             usbhc_iface_transfer_out_callback_t, void *);
-
-        int (*control_read)(device_t *, usb_target_t,
-            size_t,
-            void *, size_t, void *, size_t,
-            usbhc_iface_transfer_in_callback_t, void *);
 } usbhc_iface_t;