sys/dev/usb/usb_core.h

   1 /* $FreeBSD$ */
   2 /*-
   3  * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24  * SUCH DAMAGE.
  25  */
  26
  27 /*
  28  * Including this file is mandatory for all USB related c-files in the kernel.
  29  */
  30
  31 #ifndef _USB_CORE_H_
  32 #define _USB_CORE_H_
  33
  34 /*
  35  * The following macro will tell if an USB transfer is currently
  36  * receiving or transferring data.
  37  */
  38 #define USB_GET_DATA_ISREAD(xfer) ((xfer)->flags_int.usb_mode == \
  39         USB_MODE_DEVICE ? (((xfer)->endpointno & UE_DIR_IN) ? 0 : 1) : \
  40         (((xfer)->endpointno & UE_DIR_IN) ? 1 : 0))
  41
  42 /* macros */
  43
  44 #define USB_BUS_LOCK(_b)                mtx_lock(&(_b)->bus_mtx)
  45 #define USB_BUS_UNLOCK(_b)              mtx_unlock(&(_b)->bus_mtx)
  46 #define USB_BUS_LOCK_ASSERT(_b, _t)     mtx_assert(&(_b)->bus_mtx, _t)
  47 #define USB_BUS_SPIN_LOCK(_b)           mtx_lock_spin(&(_b)->bus_spin_lock)
  48 #define USB_BUS_SPIN_UNLOCK(_b)         mtx_unlock_spin(&(_b)->bus_spin_lock)
  49 #define USB_BUS_SPIN_LOCK_ASSERT(_b, _t)        mtx_assert(&(_b)->bus_spin_lock, _t)
  50 #define USB_XFER_LOCK(_x)               mtx_lock((_x)->xroot->xfer_mtx)
  51 #define USB_XFER_UNLOCK(_x)             mtx_unlock((_x)->xroot->xfer_mtx)
  52 #define USB_XFER_LOCK_ASSERT(_x, _t)    mtx_assert((_x)->xroot->xfer_mtx, _t)
  53
  54 /* helper for converting pointers to integers */
  55 #define USB_P2U(ptr) \
  56   (((const uint8_t *)(ptr)) - ((const uint8_t *)0))
  57
  58 /* helper for computing offsets */
  59 #define USB_ADD_BYTES(ptr,size) \
  60   ((void *)(USB_P2U(ptr) + (size)))
  61
  62 /* debug macro */
  63 #define USB_ASSERT KASSERT
  64
  65 /* structure prototypes */
  66
  67 struct file;
  68 struct usb_bus;
  69 struct usb_device;
  70 struct usb_device_request;
  71 struct usb_page;
  72 struct usb_page_cache;
  73 struct usb_xfer;
  74 struct usb_xfer_root;
  75 struct usb_string_lang;
  76
  77 /* typedefs */
  78
  79 /* structures */
  80
  81 /*
  82  * The following structure defines a set of internal USB transfer
  83  * flags.
  84  */
  85 struct usb_xfer_flags_int {
  86
  87         enum usb_hc_mode usb_mode;      /* shadow copy of "udev->usb_mode" */
  88         uint16_t control_rem;           /* remainder in bytes */
  89
  90         uint8_t open:1;                 /* set if USB pipe has been opened */
  91         uint8_t transferring:1;         /* set if an USB transfer is in
  92                                          * progress */
  93         uint8_t did_dma_delay:1;        /* set if we waited for HW DMA */
  94         uint8_t did_close:1;            /* set if we closed the USB transfer */
  95         uint8_t draining:1;             /* set if we are draining an USB
  96                                          * transfer */
  97         uint8_t started:1;              /* keeps track of started or stopped */
  98         uint8_t bandwidth_reclaimed:1;
  99         uint8_t control_xfr:1;          /* set if control transfer */
 100         uint8_t control_hdr:1;          /* set if control header should be
 101                                          * sent */
 102         uint8_t control_act:1;          /* set if control transfer is active */
 103         uint8_t control_stall:1;        /* set if control transfer should be stalled */
 104         uint8_t control_did_data:1;     /* set if control DATA has been transferred */
 105
 106         uint8_t short_frames_ok:1;      /* filtered version */
 107         uint8_t short_xfer_ok:1;        /* filtered version */
 108 #if USB_HAVE_BUSDMA
 109         uint8_t bdma_enable:1;          /* filtered version (only set if
 110                                          * hardware supports DMA) */
 111         uint8_t bdma_no_post_sync:1;    /* set if the USB callback wrapper
 112                                          * should not do the BUS-DMA post sync
 113                                          * operation */
 114         uint8_t bdma_setup:1;           /* set if BUS-DMA has been setup */
 115 #endif
 116         uint8_t isochronous_xfr:1;      /* set if isochronous transfer */
 117         uint8_t curr_dma_set:1;         /* used by USB HC/DC driver */
 118         uint8_t can_cancel_immed:1;     /* set if USB transfer can be
 119                                          * cancelled immediately */
 120         uint8_t doing_callback:1;       /* set if executing the callback */
 121         uint8_t maxp_was_clamped:1;     /* set if the max packet size
 122                                          * was outside its allowed range */
 123 };
 124
 125 /*
 126  * The following structure defines an USB transfer.
 127  */
 128 struct usb_xfer {
 129         struct usb_callout timeout_handle;
 130         TAILQ_ENTRY(usb_xfer) wait_entry;       /* used at various places */
 131
 132         struct usb_page_cache *buf_fixup;       /* fixup buffer(s) */
 133         struct usb_xfer_queue *wait_queue;      /* pointer to queue that we
 134                                                  * are waiting on */
 135         struct usb_page *dma_page_ptr;
 136         struct usb_endpoint *endpoint;  /* our USB endpoint */
 137         struct usb_xfer_root *xroot;    /* used by HC driver */
 138         void   *qh_start[2];            /* used by HC driver */
 139         void   *td_start[2];            /* used by HC driver */
 140         void   *td_transfer_first;      /* used by HC driver */
 141         void   *td_transfer_last;       /* used by HC driver */
 142         void   *td_transfer_cache;      /* used by HC driver */
 143         void   *priv_sc;                /* device driver data pointer 1 */
 144         void   *priv_fifo;              /* device driver data pointer 2 */
 145         void   *local_buffer;
 146         usb_frlength_t *frlengths;
 147         struct usb_page_cache *frbuffers;
 148         usb_callback_t *callback;
 149
 150         usb_frlength_t max_hc_frame_size;
 151         usb_frlength_t max_data_length;
 152         usb_frlength_t sumlen;          /* sum of all lengths in bytes */
 153         usb_frlength_t actlen;          /* actual length in bytes */
 154         usb_timeout_t timeout;          /* milliseconds */
 155
 156         usb_frcount_t max_frame_count;  /* initial value of "nframes" after
 157                                          * setup */
 158         usb_frcount_t nframes;          /* number of USB frames to transfer */
 159         usb_frcount_t aframes;          /* actual number of USB frames
 160                                          * transferred */
 161         usb_stream_t stream_id;         /* USB3.0 specific field */
 162
 163         uint16_t max_packet_size;
 164         uint16_t max_frame_size;
 165         uint16_t qh_pos;
 166         uint16_t isoc_time_complete;    /* in ms */
 167         usb_timeout_t interval; /* milliseconds */
 168
 169         uint8_t address;                /* physical USB address */
 170         uint8_t endpointno;             /* physical USB endpoint */
 171         uint8_t max_packet_count;
 172         uint8_t usb_state;
 173         uint8_t fps_shift;              /* down shift of FPS, 0..3 */
 174
 175         usb_error_t error;
 176
 177         struct usb_xfer_flags flags;
 178         struct usb_xfer_flags_int flags_int;
 179 };
 180
 181 /* external variables */
 182
 183 extern struct mtx usb_ref_lock;
 184 extern const struct usb_string_lang usb_string_lang_en;
 185
 186 /* typedefs */
 187
 188 typedef struct malloc_type *usb_malloc_type;
 189
 190 /* prototypes */
 191
 192 #endif                                  /* _USB_CORE_H_ */