Changeset 02fc5c4 in mainline for uspace/lib/drv/include/usbhc_iface.h


Ignore:
Timestamp:
2011-11-25T17:41:23Z (12 years ago)
Author:
Jan Vesely <jano.vesely@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
095bddfc
Parents:
56bdd9a4
Message:

usbhc: Export IPC wrapper instead of IPC call numbers.

Hide IPC protocol in one file, instead of multiple client implementations.
Rename 'find_by_address' ⇒ 'get_handle'

File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/drv/include/usbhc_iface.h

    r56bdd9a4 r02fc5c4  
    4242#include <bool.h>
    4343
    44 
    45 /** IPC methods for communication with HC through DDF interface.
    46  *
    47  * Notes for async methods:
    48  *
    49  * Methods for sending data to device (OUT transactions)
    50  * - e.g. IPC_M_USBHC_INTERRUPT_OUT -
    51  * always use the same semantics:
    52  * - first, IPC call with given method is made
    53  *   - argument #1 is target address
    54  *   - argument #2 is target endpoint
    55  *   - argument #3 is max packet size of the endpoint
    56  * - this call is immediately followed by IPC data write (from caller)
    57  * - the initial call (and the whole transaction) is answer after the
    58  *   transaction is scheduled by the HC and acknowledged by the device
    59  *   or immediately after error is detected
    60  * - the answer carries only the error code
    61  *
    62  * Methods for retrieving data from device (IN transactions)
    63  * - e.g. IPC_M_USBHC_INTERRUPT_IN -
    64  * also use the same semantics:
    65  * - first, IPC call with given method is made
    66  *   - argument #1 is target address
    67  *   - argument #2 is target endpoint
    68  * - this call is immediately followed by IPC data read (async version)
    69  * - the call is not answered until the device returns some data (or until
    70  *   error occurs)
    71  *
    72  * Some special methods (NO-DATA transactions) do not send any data. These
    73  * might behave as both OUT or IN transactions because communication parts
    74  * where actual buffers are exchanged are omitted.
    75  **
    76  * For all these methods, wrap functions exists. Important rule: functions
    77  * for IN transactions have (as parameters) buffers where retrieved data
    78  * will be stored. These buffers must be already allocated and shall not be
    79  * touch until the transaction is completed
    80  * (e.g. not before calling usb_wait_for() with appropriate handle).
    81  * OUT transactions buffers can be freed immediately after call is dispatched
    82  * (i.e. after return from wrapping function).
    83  *
    84  */
    85 typedef enum {
    86         /** Asks for address assignment by host controller.
    87          * Answer:
    88          * - ELIMIT - host controller run out of address
    89          * - EOK - address assigned
    90          * Answer arguments:
    91          * - assigned address
    92          *
    93          * The address must be released by via IPC_M_USBHC_RELEASE_ADDRESS.
    94          */
    95         IPC_M_USBHC_REQUEST_ADDRESS,
    96 
    97         /** Bind USB address with devman handle.
    98          * Parameters:
    99          * - USB address
    100          * - devman handle
    101          * Answer:
    102          * - EOK - address binded
    103          * - ENOENT - address is not in use
    104          */
    105         IPC_M_USBHC_BIND_ADDRESS,
    106 
    107         /** Get handle binded with given USB address.
    108          * Parameters
    109          * - USB address
    110          * Answer:
    111          * - EOK - address binded, first parameter is the devman handle
    112          * - ENOENT - address is not in use at the moment
    113          */
    114         IPC_M_USBHC_GET_HANDLE_BY_ADDRESS,
    115 
    116         /** Release address in use.
    117          * Arguments:
    118          * - address to be released
    119          * Answer:
    120          * - ENOENT - address not in use
    121          * - EPERM - trying to release default USB address
    122          */
    123         IPC_M_USBHC_RELEASE_ADDRESS,
    124 
    125         /** Register endpoint attributes at host controller.
    126          * This is used to reserve portion of USB bandwidth.
    127          * When speed is invalid, speed of the device is used.
    128          * Parameters:
    129          * - USB address + endpoint number
    130          *   - packed as ADDR << 16 + EP
    131          * - speed + transfer type + direction
    132          *   - packed as ( SPEED << 8 + TYPE ) << 8 + DIR
    133          * - maximum packet size + interval (in milliseconds)
    134          *   - packed as MPS << 16 + INT
    135          * Answer:
    136          * - EOK - reservation successful
    137          * - ELIMIT - not enough bandwidth to satisfy the request
    138          */
    139         IPC_M_USBHC_REGISTER_ENDPOINT,
    140 
    141         /** Revert endpoint registration.
    142          * Parameters:
    143          * - USB address
    144          * - endpoint number
    145          * - data direction
    146          * Answer:
    147          * - EOK - endpoint unregistered
    148          * - ENOENT - unknown endpoint
    149          */
    150         IPC_M_USBHC_UNREGISTER_ENDPOINT,
    151 
    152         /** Get data from device.
    153          * See explanation at usb_iface_funcs_t (IN transaction).
    154          */
    155         IPC_M_USBHC_READ,
    156 
    157         /** Send data to device.
    158          * See explanation at usb_iface_funcs_t (OUT transaction).
    159          */
    160         IPC_M_USBHC_WRITE,
    161 } usbhc_iface_funcs_t;
     44int usbhc_request_address(async_exch_t *, usb_address_t *, bool, usb_speed_t);
     45int usbhc_bind_address(async_exch_t *, usb_address_t, devman_handle_t);
     46int usbhc_get_handle(async_exch_t *, usb_address_t, devman_handle_t *);
     47int usbhc_release_address(async_exch_t *, usb_address_t);
     48int usbhc_register_endpoint(async_exch_t *, usb_address_t,  usb_endpoint_t,
     49    usb_transfer_type_t, usb_direction_t, size_t, unsigned int);
     50int usbhc_unregister_endpoint(async_exch_t *, usb_address_t, usb_endpoint_t,
     51    usb_direction_t);
     52int usbhc_read(async_exch_t *, usb_address_t, usb_endpoint_t,
     53    uint64_t, void *, size_t, size_t *);
     54int usbhc_write(async_exch_t *, usb_address_t, usb_endpoint_t,
     55    uint64_t, const void *, size_t);
    16256
    16357/** Callback for outgoing transfer. */
    … …  
    17266        int (*request_address)(ddf_fun_t *, usb_address_t *, bool, usb_speed_t);
    17367        int (*bind_address)(ddf_fun_t *, usb_address_t, devman_handle_t);
    174         int (*find_by_address)(ddf_fun_t *, usb_address_t, devman_handle_t *);
     68        int (*get_handle)(ddf_fun_t *, usb_address_t,
     69            devman_handle_t *);
    17570        int (*release_address)(ddf_fun_t *, usb_address_t);
    17671
Note: See TracChangeset for help on using the changeset viewer.