sys/compat/linuxkpi/common/include/linux/usb.h

   1 /* $FreeBSD$ */
   2 /*-
   3  * Copyright (c) 2007 Luigi Rizzo - Universita` di Pisa. All rights reserved.
   4  * Copyright (c) 2007 Hans Petter Selasky. All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25  * SUCH DAMAGE.
  26  */
  27
  28 #ifndef _USB_COMPAT_LINUX_H
  29 #define _USB_COMPAT_LINUX_H
  30
  31 #include <sys/types.h>
  32 #include <sys/param.h>
  33 #include <sys/proc.h>
  34 #include <sys/condvar.h>
  35
  36 #include <dev/usb/usb.h>
  37 #include <dev/usb/usbdi.h>
  38 #include <dev/usb/usbdi_util.h>
  39
  40 struct usb_device;
  41 struct usb_interface;
  42 struct usb_driver;
  43 struct urb;
  44
  45 typedef void *pm_message_t;
  46 typedef void (usb_complete_t)(struct urb *);
  47
  48 #define USB_MAX_FULL_SPEED_ISOC_FRAMES (60 * 1)
  49 #define USB_MAX_HIGH_SPEED_ISOC_FRAMES (60 * 8)
  50
  51 #define USB_DEVICE_ID_MATCH_DEVICE \
  52         (USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
  53
  54 #define USB_DEVICE(vend,prod) \
  55         .match_flags = USB_DEVICE_ID_MATCH_DEVICE, .idVendor = (vend), \
  56         .idProduct = (prod)
  57
  58 /* The "usb_driver" structure holds the Linux USB device driver
  59  * callbacks, and a pointer to device ID's which this entry should
  60  * match against. Usually this entry is exposed to the USB emulation
  61  * layer using the "USB_DRIVER_EXPORT()" macro, which is defined
  62  * below.
  63  */
  64 struct usb_driver {
  65         const char *name;
  66
  67         int     (*probe) (struct usb_interface *intf,
  68                 const   struct usb_device_id *id);
  69
  70         void    (*disconnect) (struct usb_interface *intf);
  71
  72         int     (*ioctl) (struct usb_interface *intf, unsigned int code,
  73                 void  *buf);
  74
  75         int     (*suspend) (struct usb_interface *intf, pm_message_t message);
  76         int     (*resume) (struct usb_interface *intf);
  77
  78         const struct usb_device_id *id_table;
  79
  80         void    (*shutdown) (struct usb_interface *intf);
  81
  82         LIST_ENTRY(usb_driver) linux_driver_list;
  83 };
  84
  85 #define USB_DRIVER_EXPORT(id,p_usb_drv) \
  86   SYSINIT(id,SI_SUB_KLD,SI_ORDER_FIRST,usb_linux_register,p_usb_drv); \
  87   SYSUNINIT(id,SI_SUB_KLD,SI_ORDER_ANY,usb_linux_deregister,p_usb_drv)
  88
  89 #define USB_DT_ENDPOINT_SIZE            7
  90 #define USB_DT_ENDPOINT_AUDIO_SIZE      9
  91
  92 /*
  93  * Endpoints
  94  */
  95 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
  96 #define USB_ENDPOINT_DIR_MASK           0x80
  97
  98 #define USB_ENDPOINT_XFERTYPE_MASK      0x03    /* in bmAttributes */
  99 #define USB_ENDPOINT_XFER_CONTROL       0
 100 #define USB_ENDPOINT_XFER_ISOC          1
 101 #define USB_ENDPOINT_XFER_BULK          2
 102 #define USB_ENDPOINT_XFER_INT           3
 103 #define USB_ENDPOINT_MAX_ADJUSTABLE     0x80
 104
 105 /* CONTROL REQUEST SUPPORT */
 106
 107 /*
 108  * Definition of direction mask for
 109  * "bEndpointAddress" and "bmRequestType":
 110  */
 111 #define USB_DIR_MASK                    0x80
 112 #define USB_DIR_OUT                     0x00    /* write to USB device */
 113 #define USB_DIR_IN                      0x80    /* read from USB device */
 114
 115 /*
 116  * Definition of type mask for
 117  * "bmRequestType":
 118  */
 119 #define USB_TYPE_MASK                   (0x03 << 5)
 120 #define USB_TYPE_STANDARD               (0x00 << 5)
 121 #define USB_TYPE_CLASS                  (0x01 << 5)
 122 #define USB_TYPE_VENDOR                 (0x02 << 5)
 123 #define USB_TYPE_RESERVED               (0x03 << 5)
 124
 125 /*
 126  * Definition of receiver mask for
 127  * "bmRequestType":
 128  */
 129 #define USB_RECIP_MASK                  0x1f
 130 #define USB_RECIP_DEVICE                0x00
 131 #define USB_RECIP_INTERFACE             0x01
 132 #define USB_RECIP_ENDPOINT              0x02
 133 #define USB_RECIP_OTHER                 0x03
 134
 135 /*
 136  * Definition of standard request values for
 137  * "bRequest":
 138  */
 139 #define USB_REQ_GET_STATUS              0x00
 140 #define USB_REQ_CLEAR_FEATURE           0x01
 141 #define USB_REQ_SET_FEATURE             0x03
 142 #define USB_REQ_SET_ADDRESS             0x05
 143 #define USB_REQ_GET_DESCRIPTOR          0x06
 144 #define USB_REQ_SET_DESCRIPTOR          0x07
 145 #define USB_REQ_GET_CONFIGURATION       0x08
 146 #define USB_REQ_SET_CONFIGURATION       0x09
 147 #define USB_REQ_GET_INTERFACE           0x0A
 148 #define USB_REQ_SET_INTERFACE           0x0B
 149 #define USB_REQ_SYNCH_FRAME             0x0C
 150
 151 #define USB_REQ_SET_ENCRYPTION          0x0D    /* Wireless USB */
 152 #define USB_REQ_GET_ENCRYPTION          0x0E
 153 #define USB_REQ_SET_HANDSHAKE           0x0F
 154 #define USB_REQ_GET_HANDSHAKE           0x10
 155 #define USB_REQ_SET_CONNECTION          0x11
 156 #define USB_REQ_SET_SECURITY_DATA       0x12
 157 #define USB_REQ_GET_SECURITY_DATA       0x13
 158 #define USB_REQ_SET_WUSB_DATA           0x14
 159 #define USB_REQ_LOOPBACK_DATA_WRITE     0x15
 160 #define USB_REQ_LOOPBACK_DATA_READ      0x16
 161 #define USB_REQ_SET_INTERFACE_DS        0x17
 162
 163 /*
 164  * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
 165  * are read as a bit array returned by USB_REQ_GET_STATUS.  (So there
 166  * are at most sixteen features of each type.)
 167  */
 168 #define USB_DEVICE_SELF_POWERED         0       /* (read only) */
 169 #define USB_DEVICE_REMOTE_WAKEUP        1       /* dev may initiate wakeup */
 170 #define USB_DEVICE_TEST_MODE            2       /* (wired high speed only) */
 171 #define USB_DEVICE_BATTERY              2       /* (wireless) */
 172 #define USB_DEVICE_B_HNP_ENABLE         3       /* (otg) dev may initiate HNP */
 173 #define USB_DEVICE_WUSB_DEVICE          3       /* (wireless) */
 174 #define USB_DEVICE_A_HNP_SUPPORT        4       /* (otg) RH port supports HNP */
 175 #define USB_DEVICE_A_ALT_HNP_SUPPORT    5       /* (otg) other RH port does */
 176 #define USB_DEVICE_DEBUG_MODE           6       /* (special devices only) */
 177
 178 #define USB_ENDPOINT_HALT               0       /* IN/OUT will STALL */
 179
 180 #define PIPE_ISOCHRONOUS                0x01    /* UE_ISOCHRONOUS */
 181 #define PIPE_INTERRUPT                  0x03    /* UE_INTERRUPT */
 182 #define PIPE_CONTROL                    0x00    /* UE_CONTROL */
 183 #define PIPE_BULK                       0x02    /* UE_BULK */
 184
 185 /* Whenever Linux references an USB endpoint:
 186  * a) to initialize "urb->endpoint"
 187  * b) second argument passed to "usb_control_msg()"
 188  *
 189  * Then it uses one of the following macros. The "endpoint" argument
 190  * is the physical endpoint value masked by 0xF. The "dev" argument
 191  * is a pointer to "struct usb_device".
 192  */
 193 #define usb_sndctrlpipe(dev,endpoint) \
 194   usb_find_host_endpoint(dev, PIPE_CONTROL, (endpoint) | USB_DIR_OUT)
 195
 196 #define usb_rcvctrlpipe(dev,endpoint) \
 197   usb_find_host_endpoint(dev, PIPE_CONTROL, (endpoint) | USB_DIR_IN)
 198
 199 #define usb_sndisocpipe(dev,endpoint) \
 200   usb_find_host_endpoint(dev, PIPE_ISOCHRONOUS, (endpoint) | USB_DIR_OUT)
 201
 202 #define usb_rcvisocpipe(dev,endpoint) \
 203   usb_find_host_endpoint(dev, PIPE_ISOCHRONOUS, (endpoint) | USB_DIR_IN)
 204
 205 #define usb_sndbulkpipe(dev,endpoint) \
 206   usb_find_host_endpoint(dev, PIPE_BULK, (endpoint) | USB_DIR_OUT)
 207
 208 #define usb_rcvbulkpipe(dev,endpoint) \
 209   usb_find_host_endpoint(dev, PIPE_BULK, (endpoint) | USB_DIR_IN)
 210
 211 #define usb_sndintpipe(dev,endpoint) \
 212   usb_find_host_endpoint(dev, PIPE_INTERRUPT, (endpoint) | USB_DIR_OUT)
 213
 214 #define usb_rcvintpipe(dev,endpoint) \
 215   usb_find_host_endpoint(dev, PIPE_INTERRUPT, (endpoint) | USB_DIR_IN)
 216
 217 /*
 218  * The following structure is used to extend "struct urb" when we are
 219  * dealing with an isochronous endpoint. It contains information about
 220  * the data offset and data length of an isochronous packet.
 221  * The "actual_length" field is updated before the "complete"
 222  * callback in the "urb" structure is called.
 223  */
 224 struct usb_iso_packet_descriptor {
 225         uint32_t offset;                /* depreciated buffer offset (the
 226                                          * packets are usually back to back) */
 227         uint16_t length;                /* expected length */
 228         uint16_t actual_length;
 229          int16_t status;                /* transfer status */
 230 };
 231
 232 /*
 233  * The following structure holds various information about an USB
 234  * transfer. This structure is used for all kinds of USB transfers.
 235  *
 236  * URB is short for USB Request Block.
 237  */
 238 struct urb {
 239         TAILQ_ENTRY(urb) bsd_urb_list;
 240         struct cv cv_wait;
 241
 242         struct usb_device *dev;         /* (in) pointer to associated device */
 243         struct usb_host_endpoint *endpoint;     /* (in) pipe pointer */
 244         uint8_t *setup_packet;          /* (in) setup packet (control only) */
 245         uint8_t *bsd_data_ptr;
 246         void   *transfer_buffer;        /* (in) associated data buffer */
 247         void   *context;                /* (in) context for completion */
 248         usb_complete_t *complete;       /* (in) completion routine */
 249
 250         usb_size_t transfer_buffer_length;/* (in) data buffer length */
 251         usb_size_t bsd_length_rem;
 252         usb_size_t actual_length;       /* (return) actual transfer length */
 253         usb_timeout_t timeout;          /* FreeBSD specific */
 254
 255         uint16_t transfer_flags;        /* (in) */
 256 #define URB_SHORT_NOT_OK        0x0001  /* report short transfers like errors */
 257 #define URB_ISO_ASAP            0x0002  /* ignore "start_frame" field */
 258 #define URB_ZERO_PACKET         0x0004  /* the USB transfer ends with a short
 259                                          * packet */
 260 #define URB_NO_TRANSFER_DMA_MAP 0x0008  /* "transfer_dma" is valid on submit */
 261 #define URB_WAIT_WAKEUP         0x0010  /* custom flags */
 262 #define URB_IS_SLEEPING         0x0020  /* custom flags */
 263
 264         usb_frcount_t start_frame;      /* (modify) start frame (ISO) */
 265         usb_frcount_t number_of_packets;        /* (in) number of ISO packets */
 266         uint16_t interval;              /* (modify) transfer interval
 267                                          * (INT/ISO) */
 268         uint16_t error_count;           /* (return) number of ISO errors */
 269         int16_t status;                 /* (return) status */
 270
 271         uint8_t setup_dma;              /* (in) not used on FreeBSD */
 272         uint8_t transfer_dma;           /* (in) not used on FreeBSD */
 273         uint8_t bsd_isread;
 274         uint8_t kill_count;             /* FreeBSD specific */
 275
 276         struct usb_iso_packet_descriptor iso_frame_desc[];      /* (in) ISO ONLY */
 277 };
 278
 279 /* various prototypes */
 280
 281 int     usb_submit_urb(struct urb *urb, uint16_t mem_flags);
 282 int     usb_unlink_urb(struct urb *urb);
 283 int     usb_clear_halt(struct usb_device *dev, struct usb_host_endpoint *uhe);
 284 int     usb_control_msg(struct usb_device *dev, struct usb_host_endpoint *ep,
 285             uint8_t request, uint8_t requesttype, uint16_t value,
 286             uint16_t index, void *data, uint16_t size, usb_timeout_t timeout);
 287 int     usb_set_interface(struct usb_device *dev, uint8_t ifnum,
 288             uint8_t alternate);
 289 int     usb_setup_endpoint(struct usb_device *dev,
 290             struct usb_host_endpoint *uhe, usb_frlength_t bufsize);
 291
 292 struct usb_host_endpoint *usb_find_host_endpoint(struct usb_device *dev,
 293             uint8_t type, uint8_t ep);
 294 struct urb *usb_alloc_urb(uint16_t iso_packets, uint16_t mem_flags);
 295 struct usb_host_interface *usb_altnum_to_altsetting(
 296             const struct usb_interface *intf, uint8_t alt_index);
 297 struct usb_interface *usb_ifnum_to_if(struct usb_device *dev, uint8_t iface_no);
 298
 299 void   *usb_buffer_alloc(struct usb_device *dev, usb_size_t size,
 300             uint16_t mem_flags, uint8_t *dma_addr);
 301 void   *usbd_get_intfdata(struct usb_interface *intf);
 302
 303 void    usb_buffer_free(struct usb_device *dev, usb_size_t size, void *addr, uint8_t dma_addr);
 304 void    usb_free_urb(struct urb *urb);
 305 void    usb_init_urb(struct urb *urb);
 306 void    usb_kill_urb(struct urb *urb);
 307 void    usb_set_intfdata(struct usb_interface *intf, void *data);
 308 void    usb_linux_register(void *arg);
 309 void    usb_linux_deregister(void *arg);
 310
 311 void    usb_fill_bulk_urb(struct urb *, struct usb_device *,
 312             struct usb_host_endpoint *, void *, int, usb_complete_t, void *);
 313 int     usb_bulk_msg(struct usb_device *, struct usb_host_endpoint *,
 314             void *, int, uint16_t *, usb_timeout_t);
 315
 316 #define interface_to_usbdev(intf) (intf)->linux_udev
 317 #define interface_to_bsddev(intf) (intf)->linux_udev
 318
 319 #endif                                  /* _USB_COMPAT_LINUX_H */