Changeset fa2a361 in mainline


Ignore:
Timestamp:
2010-10-26T21:38:59Z (14 years ago)
Author:
Vojtech Horky <vojtechhorky@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
aab02fb
Parents:
56cb9bd
Message:

Add missing comments

Location:
uspace/lib/usb
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/usb/hcd.c

    r56cb9bd rfa2a361  
    4040#include <errno.h>
    4141
     42/** Information about pending transaction on HC. */
    4243typedef struct {
     44        /** Phone to host controller driver. */
    4345        int phone;
     46        /** Data buffer. */
    4447        void *buffer;
     48        /** Buffer size. */
    4549        size_t size;
     50        /** Storage for actual number of bytes transferred. */
    4651        size_t *size_transferred;
     52        /** Initial call replay data. */
    4753        ipc_call_t reply;
     54        /** Initial call identifier. */
    4855        aid_t request;
    4956} transfer_info_t;
    … …  
    355362 * =================
    356363 */
    357  
     364
     365/** Send data to HCD.
     366 *
     367 * @param phone Opened phone to HCD.
     368 * @param method Method used for calling.
     369 * @param target Target device.
     370 * @param buffer Data buffer (NULL to skip data transfer phase).
     371 * @param size Buffer size (must be zero when @p buffer is NULL).
     372 * @param handle Storage for transaction handle (cannot be NULL).
     373 * @return Error status.
     374 * @retval EINVAL Invalid parameter.
     375 * @retval ENOMEM Not enough memory to complete the operation.
     376 */
    358377static int async_send_buffer(int phone, int method,
    359378    usb_target_t target,
    … …  
    405424}
    406425
     426/** Prepare data retrieval.
     427 *
     428 * @param phone Opened phone to HCD.
     429 * @param method Method used for calling.
     430 * @param target Target device.
     431 * @param buffer Buffer where to store retrieved data
     432 *      (NULL to skip data transfer phase).
     433 * @param size Buffer size (must be zero when @p buffer is NULL).
     434 * @param actual_size Storage where actual number of bytes transferred will
     435 *      be stored.
     436 * @param handle Storage for transaction handle (cannot be NULL).
     437 * @return Error status.
     438 * @retval EINVAL Invalid parameter.
     439 * @retval ENOMEM Not enough memory to complete the operation.
     440 */
    407441static int async_recv_buffer(int phone, int method,
    408442    usb_target_t target,
    … …  
    444478}
    445479
     480/** Read buffer from HCD.
     481 *
     482 * @param phone Opened phone to HCD.
     483 * @param hash Buffer hash (obtained after completing IN transaction).
     484 * @param buffer Buffer where to store data data.
     485 * @param size Buffer size.
     486 * @param actual_size Storage where actual number of bytes transferred will
     487 *      be stored.
     488 * @return Error status.
     489 */
    446490static int read_buffer_in(int phone, ipcarg_t hash,
    447491    void *buffer, size_t size, size_t *actual_size)
    … …  
    475519}
    476520
    477 
     521/** Blocks caller until given USB transaction is finished.
     522 * After the transaction is finished, the user can access all output data
     523 * given to initial call function.
     524 *
     525 * @param handle Transaction handle.
     526 * @return Error status.
     527 * @retval EOK No error.
     528 * @retval EBADMEM Invalid handle.
     529 * @retval ENOENT Data buffer associated with transaction does not exist.
     530 */
    478531int usb_hcd_async_wait_for(usb_handle_t handle)
    479532{
    … …  
    528581}
    529582
     583/** Send interrupt data to device. */
    530584int usb_hcd_async_transfer_interrupt_out(int hcd_phone,
    531585    usb_target_t target,
    … …  
    540594}
    541595
     596/** Request interrupt data from device. */
    542597int usb_hcd_async_transfer_interrupt_in(int hcd_phone,
    543598    usb_target_t target,
    … …  
    552607}
    553608
     609/** Start WRITE control transfer. */
    554610int usb_hcd_async_transfer_control_write_setup(int hcd_phone,
    555611    usb_target_t target,
    … …  
    564620}
    565621
     622/** Send data during WRITE control transfer. */
    566623int usb_hcd_async_transfer_control_write_data(int hcd_phone,
    567624    usb_target_t target,
    … …  
    576633}
    577634
     635/** Terminate WRITE control transfer. */
    578636int usb_hcd_async_transfer_control_write_status(int hcd_phone,
    579637    usb_target_t target,
    … …  
    587645}
    588646
     647/** Start READ control transfer. */
    589648int usb_hcd_async_transfer_control_read_setup(int hcd_phone,
    590649    usb_target_t target,
    … …  
    599658}
    600659
     660/** Request data during READ control transfer. */
    601661int usb_hcd_async_transfer_control_read_data(int hcd_phone,
    602662    usb_target_t target,
    … …  
    611671}
    612672
     673/** Terminate READ control transfer. */
    613674int usb_hcd_async_transfer_control_read_status(int hcd_phone,
    614675    usb_target_t target,

  • 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.