Index: uspace/lib/usb/hcd.c =================================================================== --- uspace/lib/usb/hcd.c (revision 56cb9bd7d68d8fd78536ef420007013f70c97153) +++ uspace/lib/usb/hcd.c (revision fa2a3611e963c611a00be931fc762129e542bea4) @@ -40,10 +40,17 @@ #include +/** Information about pending transaction on HC. */ typedef struct { + /** Phone to host controller driver. */ int phone; + /** Data buffer. */ void *buffer; + /** Buffer size. */ size_t size; + /** Storage for actual number of bytes transferred. */ size_t *size_transferred; + /** Initial call replay data. */ ipc_call_t reply; + /** Initial call identifier. */ aid_t request; } transfer_info_t; @@ -355,5 +362,17 @@ * ================= */ - + +/** Send data to HCD. + * + * @param phone Opened phone to HCD. + * @param method Method used for calling. + * @param target Target device. + * @param buffer Data buffer (NULL to skip data transfer phase). + * @param size Buffer size (must be zero when @p buffer is NULL). + * @param handle Storage for transaction handle (cannot be NULL). + * @return Error status. + * @retval EINVAL Invalid parameter. + * @retval ENOMEM Not enough memory to complete the operation. + */ static int async_send_buffer(int phone, int method, usb_target_t target, @@ -405,4 +424,19 @@ } +/** Prepare data retrieval. + * + * @param phone Opened phone to HCD. + * @param method Method used for calling. + * @param target Target device. + * @param buffer Buffer where to store retrieved data + * (NULL to skip data transfer phase). + * @param size Buffer size (must be zero when @p buffer is NULL). + * @param actual_size Storage where actual number of bytes transferred will + * be stored. + * @param handle Storage for transaction handle (cannot be NULL). + * @return Error status. + * @retval EINVAL Invalid parameter. + * @retval ENOMEM Not enough memory to complete the operation. + */ static int async_recv_buffer(int phone, int method, usb_target_t target, @@ -444,4 +478,14 @@ } +/** Read buffer from HCD. + * + * @param phone Opened phone to HCD. + * @param hash Buffer hash (obtained after completing IN transaction). + * @param buffer Buffer where to store data data. + * @param size Buffer size. + * @param actual_size Storage where actual number of bytes transferred will + * be stored. + * @return Error status. + */ static int read_buffer_in(int phone, ipcarg_t hash, void *buffer, size_t size, size_t *actual_size) @@ -475,5 +519,14 @@ } - +/** Blocks caller until given USB transaction is finished. + * After the transaction is finished, the user can access all output data + * given to initial call function. + * + * @param handle Transaction handle. + * @return Error status. + * @retval EOK No error. + * @retval EBADMEM Invalid handle. + * @retval ENOENT Data buffer associated with transaction does not exist. + */ int usb_hcd_async_wait_for(usb_handle_t handle) { @@ -528,4 +581,5 @@ } +/** Send interrupt data to device. */ int usb_hcd_async_transfer_interrupt_out(int hcd_phone, usb_target_t target, @@ -540,4 +594,5 @@ } +/** Request interrupt data from device. */ int usb_hcd_async_transfer_interrupt_in(int hcd_phone, usb_target_t target, @@ -552,4 +607,5 @@ } +/** Start WRITE control transfer. */ int usb_hcd_async_transfer_control_write_setup(int hcd_phone, usb_target_t target, @@ -564,4 +620,5 @@ } +/** Send data during WRITE control transfer. */ int usb_hcd_async_transfer_control_write_data(int hcd_phone, usb_target_t target, @@ -576,4 +633,5 @@ } +/** Terminate WRITE control transfer. */ int usb_hcd_async_transfer_control_write_status(int hcd_phone, usb_target_t target, @@ -587,4 +645,5 @@ } +/** Start READ control transfer. */ int usb_hcd_async_transfer_control_read_setup(int hcd_phone, usb_target_t target, @@ -599,4 +658,5 @@ } +/** Request data during READ control transfer. */ int usb_hcd_async_transfer_control_read_data(int hcd_phone, usb_target_t target, @@ -611,4 +671,5 @@ } +/** Terminate READ control transfer. */ int usb_hcd_async_transfer_control_read_status(int hcd_phone, usb_target_t target, Index: uspace/lib/usb/hcd.h =================================================================== --- uspace/lib/usb/hcd.h (revision 56cb9bd7d68d8fd78536ef420007013f70c97153) +++ uspace/lib/usb/hcd.h (revision fa2a3611e963c611a00be931fc762129e542bea4) @@ -85,5 +85,55 @@ const char * usb_str_transaction_outcome(usb_transaction_outcome_t o); -/** IPC methods for HCD. */ +/** IPC methods for HCD. + * + * Notes for async methods: + * + * Methods for sending data to device (OUT transactions) + * - e.g. IPC_M_USB_HCD_INTERRUPT_OUT_ASYNC - + * always use the same semantics: + * - first, IPC call with given method is made + * - argument #1 is target address + * - argument #2 is target 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 + * transaction is scheduled by the HC and acknowledged by the device + * or immediatelly after error is detected + * - the answer carries only the error code + * + * Methods for retrieving data from device (IN transactions) + * - e.g. IPC_M_USB_HCD_INTERRUPT_IN_ASYNC - + * also use the same semantics: + * - first, IPC call with given method is made + * - argument #1 is target address + * - argument #2 is target endpoint + * - 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 ommitted. + * + * The mentioned data retrieval can be done any time after receiving EOK + * answer to IN method. + * This retrieval is done using the IPC_M_USB_HCD_GET_BUFFER_ASYNC where + * the first argument is buffer hash from call answer. + * This call must be immediatelly followed by data read-in and after the + * data are transferred, the initial call (IPC_M_USB_HCD_GET_BUFFER_ASYNC) + * 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 + * will be stored. These buffers must be already allocated and shall not be + * touch until the transaction is completed + * (e.g. not before calling usb_hcd_async_wait_for() with appropriate handle). + * OUT transactions buffers can be freed immediatelly after call is dispatched + * (i.e. after return from wrapping function). + * + * Async methods for retrieving data from device: + */ typedef enum { /** Send data over USB to a function. @@ -157,16 +207,57 @@ IPC_M_USB_HCD_CONTROL_READ_STATUS, + /* async methods */ + + /** Asks for data buffer. + * See explanation at usb_hcd_method_t. + */ IPC_M_USB_HCD_GET_BUFFER_ASYNC, + + + /** Send interrupt data to device. + * See explanation at usb_hcd_method_t (OUT transaction). + */ IPC_M_USB_HCD_INTERRUPT_OUT_ASYNC, + + /** Get interrupt data from device. + * See explanation at usb_hcd_method_t (IN transaction). + */ IPC_M_USB_HCD_INTERRUPT_IN_ASYNC, + + /** Start WRITE control transfer. + * See explanation at usb_hcd_method_t (OUT transaction). + */ IPC_M_USB_HCD_CONTROL_WRITE_SETUP_ASYNC, + + /** Send control-transfer data to device. + * See explanation at usb_hcd_method_t (OUT transaction). + */ IPC_M_USB_HCD_CONTROL_WRITE_DATA_ASYNC, + + /** Terminate WRITE control transfer. + * See explanation at usb_hcd_method_t (NO-DATA transaction). + */ IPC_M_USB_HCD_CONTROL_WRITE_STATUS_ASYNC, + + + /** Start READ control transfer. + * See explanation at usb_hcd_method_t (OUT transaction). + */ IPC_M_USB_HCD_CONTROL_READ_SETUP_ASYNC, + + /** Get control-transfer data from device. + * See explanation at usb_hcd_method_t (IN transaction). + */ IPC_M_USB_HCD_CONTROL_READ_DATA_ASYNC, + + /** Terminate READ control transfer. + * See explanation at usb_hcd_method_t (NO-DATA transaction). + */ IPC_M_USB_HCD_CONTROL_READ_STATUS_ASYNC, + + /* IPC_M_USB_HCD_ */ } usb_hcd_method_t;