payloads/libpayload/include/udc/udc.h

   1 /*
   2  *
   3  * Copyright (C) 2015 Google Inc.
   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  * 3. The name of the author may not be used to endorse or promote products
  14  *    derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26  * SUCH DAMAGE.
  27  */
  28
  29 #ifndef __UDC_H__
  30 #define __UDC_H__
  31
  32 #include <queue.h>
  33 #include <usb/usb.h>
  34
  35 struct usbdev_ctrl;
  36
  37 struct usbdev_interface {
  38         interface_descriptor_t descriptor;
  39         void (*init)(struct usbdev_ctrl *);
  40
  41         /**
  42          * handle_packet: called by the controller driver for incoming packets
  43          *
  44          * @param ep endpoint the packet is for
  45          *
  46          * @param in_dir 1, if it's an IN or INTR transfer.
  47          *               0 for OUT, SETUP is handled in handle_setup
  48          *
  49          * @param len Actual transfer length in bytes. Can differ from the
  50          *            scheduled length if the host requested a smaller
  51          *            transfer than we prepared for.
  52          */
  53         void (*handle_packet)(struct usbdev_ctrl *, int ep, int in_dir,
  54                 void *data, int len);
  55
  56         /**
  57          * handle_setup: called by the controller driver for setup packets
  58          *
  59          * @param ep endpoint the SETUP request came up on
  60          * @param dr SETUP request data
  61          */
  62         int (*handle_setup)(struct usbdev_ctrl *, int ep, dev_req_t *dr);
  63         endpoint_descriptor_t *eps;
  64 };
  65
  66 struct usbdev_configuration {
  67         configuration_descriptor_t descriptor;
  68         SLIST_ENTRY(usbdev_configuration) list;
  69         struct usbdev_interface interfaces[];
  70 };
  71
  72 SLIST_HEAD(configuration_list, usbdev_configuration);
  73
  74 struct usbdev_ctrl {
  75         /* private data */
  76         void *pdata;
  77
  78         int initialized;
  79         int remote_wakeup;
  80
  81         struct usbdev_configuration *current_config;
  82         struct usbdev_interface *current_iface;
  83         int current_config_id;
  84
  85         struct configuration_list configs;
  86         int config_count;
  87         device_descriptor_t device_descriptor;
  88
  89         int ep_halted[16][2];
  90         int ep_mps[16][2];
  91
  92         /** returns 0 if an error occurred */
  93         int (*poll)(struct usbdev_ctrl *);
  94
  95         /**
  96          * Add a gadget driver that exposes properties described in config.
  97          *
  98          * Each gadget driver is registered and exposed as separate USB
  99          * "configuration", so the host can choose between them.
 100          */
 101         void (*add_gadget)(struct usbdev_ctrl *,
 102                 struct usbdev_configuration *config);
 103
 104         /**
 105          * Add a set of strings to use for string descriptors.
 106          *
 107          * 's' must point to an array of strings of which the first
 108          * element is unused, with at most 255 elements.
 109          *
 110          * 'm' is the size of 'strings' (ie. the index of the last entry).
 111          *
 112          * 'l' is the USB language code, of which some are defined below,
 113          * eg. LANG_EN_US.
 114          *
 115          * For now, only one language is ever exposed: Calling add_strings overwrites
 116          * older configuration.
 117          */
 118         void (*add_strings)(unsigned short l, unsigned char m, const char **s);
 119
 120         /**
 121          * Add packet to process by the controller.
 122          * zlp: zero length packet, if such a termination is necessary
 123          * autofree: free data after use
 124          */
 125         void (*enqueue_packet)(struct usbdev_ctrl *this, int endpoint,
 126                 int in_dir, void *data, int len, int zlp, int autofree);
 127
 128         /**
 129          * Tell the hardware that it should listen to a new address
 130          */
 131         void (*set_address)(struct usbdev_ctrl *, int address);
 132
 133         void (*halt_ep)(struct usbdev_ctrl *this, int ep, int in_dir);
 134         void (*start_ep)(struct usbdev_ctrl *this,
 135                 int ep, int in_dir, int ep_type, int mps);
 136
 137         /**
 138          * Set or clear endpoint ep's STALL state
 139          */
 140         void (*stall)(struct usbdev_ctrl *, uint8_t ep, int in_dir, int set);
 141
 142         /**
 143          * Disable controller and deallocate data structures.
 144          */
 145         void (*force_shutdown)(struct usbdev_ctrl *this);
 146
 147         /**
 148          * Let queues run out, then disable controller and deallocate data
 149          * structures.
 150          */
 151         void (*shutdown)(struct usbdev_ctrl *this);
 152
 153         /**
 154          * Allocate n bytes for use as data
 155          */
 156         void *(*alloc_data)(size_t n);
 157         /**
 158          * Free memory object allocated with alloc_data()
 159          */
 160         void (*free_data)(void *);
 161 };
 162
 163 #define LANG_DE_DE 0x0407
 164 #define LANG_EN_US 0x0409
 165
 166 void udc_add_gadget(struct usbdev_ctrl *this,
 167         struct usbdev_configuration *config);
 168 void udc_add_strings(unsigned short id, unsigned char count,
 169         const char *strings[]);
 170 void udc_handle_setup(struct usbdev_ctrl *this, int ep, dev_req_t *dr);
 171
 172 #endif