Fork us on GitHub Follow us on Facebook Follow us on Twitter

Changeset fa2a361 in mainline for uspace/lib/usb/hcd.h


Ignore:
Timestamp:
2010-10-26T21:38:59Z (10 years ago)
Author:
Vojtech Horky <vojtechhorky@…>
Branches:
master
Children:
aab02fb
Parents:
56cb9bd
Message:

Add missing comments

File:
1 edited

Legend:

Unmodified
Added
Removed
  • uspace/lib/usb/hcd.h

    r56cb9bd rfa2a361  
    8585const char * usb_str_transaction_outcome(usb_transaction_outcome_t o);
    8686
    87 /** IPC methods for HCD. */
     87/** IPC methods for HCD.
     88 *
     89 * Notes for async methods:
     90 *
     91 * Methods for sending data to device (OUT transactions)
     92 * - e.g. IPC_M_USB_HCD_INTERRUPT_OUT_ASYNC -
     93 * always use the same semantics:
     94 * - first, IPC call with given method is made
     95 *   - argument #1 is target address
     96 *   - argument #2 is target endpoint
     97 *   - argument #3 is buffer size
     98 * - this call is immediately followed by IPC data write (from caller)
     99 * - the initial call (and the whole transaction) is answer after the
     100 *   transaction is scheduled by the HC and acknowledged by the device
     101 *   or immediatelly after error is detected
     102 * - the answer carries only the error code
     103 *
     104 * Methods for retrieving data from device (IN transactions)
     105 * - e.g. IPC_M_USB_HCD_INTERRUPT_IN_ASYNC -
     106 * also use the same semantics:
     107 * - first, IPC call with given method is made
     108 *   - argument #1 is target address
     109 *   - argument #2 is target endpoint
     110 *   - argument #3 is buffer size
     111 * - the call is not answered until the device returns some data (or until
     112 *   error occurs)
     113 * - if the call is answered with EOK, first argument of the answer is buffer
     114 *   hash that could be used to retrieve the actual data
     115 *
     116 * Some special methods (NO-DATA transactions) do not send any data. These
     117 * might behave as both OUT or IN transactions because communication parts
     118 * where actual buffers are exchanged are ommitted.
     119 *
     120 * The mentioned data retrieval can be done any time after receiving EOK
     121 * answer to IN method.
     122 * This retrieval is done using the IPC_M_USB_HCD_GET_BUFFER_ASYNC where
     123 * the first argument is buffer hash from call answer.
     124 * This call must be immediatelly followed by data read-in and after the
     125 * data are transferred, the initial call (IPC_M_USB_HCD_GET_BUFFER_ASYNC)
     126 * is answered. Each buffer can be retrieved only once.
     127 *
     128 * For all these methods, wrap functions exists. Important rule: functions
     129 * for IN transactions have (as parameters) buffers where retrieved data
     130 * will be stored. These buffers must be already allocated and shall not be
     131 * touch until the transaction is completed
     132 * (e.g. not before calling usb_hcd_async_wait_for() with appropriate handle).
     133 * OUT transactions buffers can be freed immediatelly after call is dispatched
     134 * (i.e. after return from wrapping function).
     135 *
     136 * Async methods for retrieving data from device:
     137 */
    88138typedef enum {
    89139        /** Send data over USB to a function.
     
    157207        IPC_M_USB_HCD_CONTROL_READ_STATUS,
    158208       
     209        /* async methods */
     210       
     211        /** Asks for data buffer.
     212         * See explanation at usb_hcd_method_t.
     213         */
    159214        IPC_M_USB_HCD_GET_BUFFER_ASYNC,
    160215       
     216       
     217       
     218        /** Send interrupt data to device.
     219         * See explanation at usb_hcd_method_t (OUT transaction).
     220         */
    161221        IPC_M_USB_HCD_INTERRUPT_OUT_ASYNC,
     222       
     223        /** Get interrupt data from device.
     224         * See explanation at usb_hcd_method_t (IN transaction).
     225         */
    162226        IPC_M_USB_HCD_INTERRUPT_IN_ASYNC,
    163227       
     228       
     229        /** Start WRITE control transfer.
     230         * See explanation at usb_hcd_method_t (OUT transaction).
     231         */
    164232        IPC_M_USB_HCD_CONTROL_WRITE_SETUP_ASYNC,
     233       
     234        /** Send control-transfer data to device.
     235         * See explanation at usb_hcd_method_t (OUT transaction).
     236         */
    165237        IPC_M_USB_HCD_CONTROL_WRITE_DATA_ASYNC,
     238       
     239        /** Terminate WRITE control transfer.
     240         * See explanation at usb_hcd_method_t (NO-DATA transaction).
     241         */
    166242        IPC_M_USB_HCD_CONTROL_WRITE_STATUS_ASYNC,
    167243       
     244       
     245       
     246        /** Start READ control transfer.
     247         * See explanation at usb_hcd_method_t (OUT transaction).
     248         */
    168249        IPC_M_USB_HCD_CONTROL_READ_SETUP_ASYNC,
     250       
     251        /** Get control-transfer data from device.
     252         * See explanation at usb_hcd_method_t (IN transaction).
     253         */
    169254        IPC_M_USB_HCD_CONTROL_READ_DATA_ASYNC,
     255       
     256        /** Terminate READ control transfer.
     257         * See explanation at usb_hcd_method_t (NO-DATA transaction).
     258         */
    170259        IPC_M_USB_HCD_CONTROL_READ_STATUS_ASYNC,
     260       
     261       
    171262        /* IPC_M_USB_HCD_ */
    172263} usb_hcd_method_t;
Note: See TracChangeset for help on using the changeset viewer.