Changeset 00aece0 in mainline for uspace/lib/drv/include/usbhc_iface.h


Ignore:
Timestamp:
2012-02-18T16:47:38Z (14 years ago)
Author:
Jakub Jermar <jakub@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
4449c6c
Parents:
bd5f3b7 (diff), f943dd3 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge mainline changes.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    rbd5f3b7 r00aece0  
    11/*
    22 * Copyright (c) 2010 Vojtech Horky
     3 * Copyright (c) 2011 Jan Vesely
    34 * All rights reserved.
    45 *
    … …  
    3132 * @{
    3233 */
     34
    3335/** @file
    3436 * @brief USB host controller interface definition.
    … …  
    4244#include <bool.h>
    4345
    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 
    126         /** Send interrupt data to device.
    127          * See explanation at usb_iface_funcs_t (OUT transaction).
    128          */
    129         IPC_M_USBHC_INTERRUPT_OUT,
    130 
    131         /** Get interrupt data from device.
    132          * See explanation at usb_iface_funcs_t (IN transaction).
    133          */
    134         IPC_M_USBHC_INTERRUPT_IN,
    135 
    136         /** Send bulk data to device.
    137          * See explanation at usb_iface_funcs_t (OUT transaction).
    138          */
    139         IPC_M_USBHC_BULK_OUT,
    140 
    141         /** Get bulk data from device.
    142          * See explanation at usb_iface_funcs_t (IN transaction).
    143          */
    144         IPC_M_USBHC_BULK_IN,
    145 
    146         /** Issue control WRITE transfer.
    147          * See explanation at usb_iface_funcs_t (OUT transaction) for
    148          * call parameters.
    149          * This call is immediately followed by two IPC data writes
    150          * from the caller (setup packet and actual data).
    151          */
    152         IPC_M_USBHC_CONTROL_WRITE,
    153 
    154         /** Issue control READ transfer.
    155          * See explanation at usb_iface_funcs_t (IN transaction) for
    156          * call parameters.
    157          * This call is immediately followed by IPC data write from the caller
    158          * (setup packet) and IPC data read (buffer that was read).
    159          */
    160         IPC_M_USBHC_CONTROL_READ,
    161 
    162         /** Register endpoint attributes at host controller.
    163          * This is used to reserve portion of USB bandwidth.
    164          * When speed is invalid, speed of the device is used.
    165          * Parameters:
    166          * - USB address + endpoint number
    167          *   - packed as ADDR << 16 + EP
    168          * - speed + transfer type + direction
    169          *   - packed as ( SPEED << 8 + TYPE ) << 8 + DIR
    170          * - maximum packet size + interval (in milliseconds)
    171          *   - packed as MPS << 16 + INT
    172          * Answer:
    173          * - EOK - reservation successful
    174          * - ELIMIT - not enough bandwidth to satisfy the request
    175          */
    176         IPC_M_USBHC_REGISTER_ENDPOINT,
    177 
    178         /** Revert endpoint registration.
    179          * Parameters:
    180          * - USB address
    181          * - endpoint number
    182          * - data direction
    183          * Answer:
    184          * - EOK - endpoint unregistered
    185          * - ENOENT - unknown endpoint
    186          */
    187         IPC_M_USBHC_UNREGISTER_ENDPOINT
    188 } usbhc_iface_funcs_t;
     46int usbhc_request_address(async_exch_t *, usb_address_t *, bool, usb_speed_t);
     47int usbhc_bind_address(async_exch_t *, usb_address_t, devman_handle_t);
     48int usbhc_get_handle(async_exch_t *, usb_address_t, devman_handle_t *);
     49int usbhc_release_address(async_exch_t *, usb_address_t);
     50int usbhc_register_endpoint(async_exch_t *, usb_address_t, usb_endpoint_t,
     51    usb_transfer_type_t, usb_direction_t, size_t, unsigned int);
     52int usbhc_unregister_endpoint(async_exch_t *, usb_address_t, usb_endpoint_t,
     53    usb_direction_t);
     54int usbhc_read(async_exch_t *, usb_address_t, usb_endpoint_t,
     55    uint64_t, void *, size_t, size_t *);
     56int usbhc_write(async_exch_t *, usb_address_t, usb_endpoint_t,
     57    uint64_t, const void *, size_t);
    18958
    19059/** Callback for outgoing transfer. */
    191 typedef void (*usbhc_iface_transfer_out_callback_t)(ddf_fun_t *,
    192     int, void *);
     60typedef void (*usbhc_iface_transfer_out_callback_t)(ddf_fun_t *, int, void *);
    19361
    19462/** Callback for incoming transfer. */
    … …  
    19664    int, size_t, void *);
    19765
    198 
    199 /** Out transfer processing function prototype. */
    200 typedef int (*usbhc_iface_transfer_out_t)(ddf_fun_t *, usb_target_t,
    201     void *, size_t,
    202     usbhc_iface_transfer_out_callback_t, void *);
    203 
    204 /** Setup transfer processing function prototype. @deprecated */
    205 typedef usbhc_iface_transfer_out_t usbhc_iface_transfer_setup_t;
    206 
    207 /** In transfer processing function prototype. */
    208 typedef int (*usbhc_iface_transfer_in_t)(ddf_fun_t *, usb_target_t,
    209     void *, size_t,
    210     usbhc_iface_transfer_in_callback_t, void *);
    211 
    21266/** USB host controller communication interface. */
    21367typedef struct {
    214         int (*request_address)(ddf_fun_t *, usb_speed_t, usb_address_t *);
     68        int (*request_address)(ddf_fun_t *, usb_address_t *, bool, usb_speed_t);
    21569        int (*bind_address)(ddf_fun_t *, usb_address_t, devman_handle_t);
    216         int (*find_by_address)(ddf_fun_t *, usb_address_t, devman_handle_t *);
     70        int (*get_handle)(ddf_fun_t *, usb_address_t,
     71            devman_handle_t *);
    21772        int (*release_address)(ddf_fun_t *, usb_address_t);
    21873
    21974        int (*register_endpoint)(ddf_fun_t *,
    220             usb_address_t, usb_speed_t, usb_endpoint_t,
     75            usb_address_t, usb_endpoint_t,
    22176            usb_transfer_type_t, usb_direction_t, size_t, unsigned int);
    22277        int (*unregister_endpoint)(ddf_fun_t *, usb_address_t, usb_endpoint_t,
    22378            usb_direction_t);
    22479
    225         usbhc_iface_transfer_out_t interrupt_out;
    226         usbhc_iface_transfer_in_t interrupt_in;
     80        int (*read)(ddf_fun_t *, usb_target_t, uint64_t, uint8_t *, size_t,
     81            usbhc_iface_transfer_in_callback_t, void *);
    22782
    228         usbhc_iface_transfer_out_t bulk_out;
    229         usbhc_iface_transfer_in_t bulk_in;
    230 
    231         int (*control_write)(ddf_fun_t *, usb_target_t,
    232             void *, size_t, void *, size_t,
    233             usbhc_iface_transfer_out_callback_t, void *);
    234 
    235         int (*control_read)(ddf_fun_t *, usb_target_t,
    236             void *, size_t, void *, size_t,
    237             usbhc_iface_transfer_in_callback_t, void *);
     83        int (*write)(ddf_fun_t *, usb_target_t, uint64_t, const uint8_t *,
     84            size_t, usbhc_iface_transfer_out_callback_t, void *);
    23885} usbhc_iface_t;
    23986
Note: See TracChangeset for help on using the changeset viewer.