Bootloader/usb.h

   1 /* Copyright (c) 2011,2012 Simon Schubert <2@0x2c.org>.
   2  * Modifications by Jacob Alexander 2014 <haata@kiibohd.com>
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #ifndef __USB_H
  19 #define __USB_H
  20
  21 // ----- Compiler Includes -----
  22
  23 #include <sys/types.h>
  24
  25
  26
  27 // ----- Local Includes -----
  28
  29 #include "mchck.h"
  30 #include "usb-common.h"
  31
  32
  33
  34 // ----- Defines -----
  35
  36 #define USB_CTRL_REQ_DIR_SHIFT 0
  37 #define USB_CTRL_REQ_TYPE_SHIFT 1
  38 #define USB_CTRL_REQ_RECP_SHIFT 3
  39 #define USB_CTRL_REQ_CODE_SHIFT 8
  40 #define USB_CTRL_REQ(req_inout, req_type, req_code)                     \
  41         (uint16_t)                                                      \
  42         ((USB_CTRL_REQ_##req_inout << USB_CTRL_REQ_DIR_SHIFT)           \
  43          |(USB_CTRL_REQ_##req_type << USB_CTRL_REQ_TYPE_SHIFT)          \
  44          |(USB_CTRL_REQ_##req_code << USB_CTRL_REQ_CODE_SHIFT))
  45
  46
  47
  48 // ----- Macros -----
  49
  50 #define USB_DESC_STRING(s)                                      \
  51         (const void *)&(const struct {                          \
  52                         struct usb_desc_string_t dsc;           \
  53                         char16_t str[sizeof(s) / 2 - 1];        \
  54         }) {{                                           \
  55                         .bLength = sizeof(struct usb_desc_string_t) +   \
  56                                 sizeof(s) - 2,                  \
  57                         .bDescriptorType = USB_DESC_STRING,     \
  58                         },                                      \
  59                         s                                       \
  60         }
  61 #define USB_DESC_STRING_LANG_ENUS USB_DESC_STRING(u"\x0409")
  62 #define USB_DESC_STRING_SERIALNO ((const void *)1)
  63
  64 #define USB_FUNCTION_IFACE(iface, iface_off, tx_ep_off, rx_ep_off)      \
  65         ((iface_off) + (iface))
  66 #define USB_FUNCTION_TX_EP(ep, iface_off, tx_ep_off, rx_ep_off) \
  67         ((tx_ep_off) + (ep))
  68 #define USB_FUNCTION_RX_EP(ep, iface_off, tx_ep_off, rx_ep_off) \
  69         ((rx_ep_off) + (ep))
  70
  71
  72 #define USB__INCREMENT(i, _0) (i + 1)
  73 #define USB__COUNT_IFACE_EP(i, e)                       \
  74         __DEFER(USB__COUNT_IFACE_EP_)(__EXPAND i, e)
  75 #define USB__COUNT_IFACE_EP_(iface, tx_ep, rx_ep, func)   \
  76         (iface + USB_FUNCTION_ ## func ## _IFACE_COUNT,   \
  77          tx_ep + USB_FUNCTION_ ## func ## _TX_EP_COUNT,   \
  78          rx_ep + USB_FUNCTION_ ## func ## _RX_EP_COUNT)
  79 #define USB__GET_FUNCTION_IFACE_COUNT(iter, func)       \
  80         USB_FUNCTION_ ## func ## _IFACE_COUNT +
  81
  82 #define USB__DEFINE_FUNCTION_DESC(iter, func)                           \
  83         USB_FUNCTION_DESC_ ## func ## _DECL __CAT(__usb_func_desc, __COUNTER__);
  84 #define USB__INIT_FUNCTION_DESC(iter, func)     \
  85         USB_FUNCTION_DESC_ ## func iter,
  86
  87 #define USB__DEFINE_CONFIG_DESC(confignum, name, ...)                   \
  88         &((const struct name {                                          \
  89                 struct usb_desc_config_t config;                        \
  90                 __REPEAT_INNER(, __EAT, USB__DEFINE_FUNCTION_DESC, __VA_ARGS__) \
  91         }){                                                             \
  92                 .config = {                                             \
  93                         .bLength = sizeof(struct usb_desc_config_t),    \
  94                         .bDescriptorType = USB_DESC_CONFIG,             \
  95                         .wTotalLength = sizeof(struct name),            \
  96                         .bNumInterfaces = __REPEAT_INNER(, __EAT, USB__GET_FUNCTION_IFACE_COUNT, __VA_ARGS__) 0, \
  97                         .bConfigurationValue = confignum,               \
  98                         .iConfiguration = 0,                            \
  99                         .one = 1,                                       \
 100                         .bMaxPower = 50                                 \
 101                 },                                                      \
 102                 __REPEAT_INNER((0, 0, 0), USB__COUNT_IFACE_EP, USB__INIT_FUNCTION_DESC, __VA_ARGS__) \
 103         }).config
 104
 105
 106 #define USB__DEFINE_CONFIG(iter, args)                          \
 107         __DEFER(USB__DEFINE_CONFIG_)(iter, __EXPAND args)
 108
 109 #define USB__DEFINE_CONFIG_(confignum, initfun, ...)                    \
 110         &(const struct usbd_config){                                    \
 111                 .init = initfun,                                        \
 112                 .desc = USB__DEFINE_CONFIG_DESC(                        \
 113                         confignum,                                      \
 114                         __CAT(__usb_desc, __COUNTER__),                 \
 115                         __VA_ARGS__)                                    \
 116         },
 117
 118 #define USB_INIT_DEVICE(vid, pid, manuf, product, ...)                  \
 119         {                                                               \
 120                 .dev_desc = &(const struct usb_desc_dev_t){             \
 121                         .bLength = sizeof(struct usb_desc_dev_t),       \
 122                         .bDescriptorType = USB_DESC_DEV,                \
 123                         .bcdUSB = { .maj = 2 },                         \
 124                         .bDeviceClass = USB_DEV_CLASS_SEE_IFACE,        \
 125                         .bDeviceSubClass = USB_DEV_SUBCLASS_SEE_IFACE,  \
 126                         .bDeviceProtocol = USB_DEV_PROTO_SEE_IFACE,     \
 127                         .bMaxPacketSize0 = EP0_BUFSIZE,                 \
 128                         .idVendor = vid,                                \
 129                         .idProduct = pid,                               \
 130                         .bcdDevice = { .raw = 0 },                      \
 131                         .iManufacturer = 1,                             \
 132                         .iProduct = 2,                                  \
 133                         .iSerialNumber = 3,                             \
 134                         .bNumConfigurations = __PP_NARG(__VA_ARGS__),   \
 135                 },                                                      \
 136                 .string_descs = (const struct usb_desc_string_t * const []){ \
 137                         USB_DESC_STRING_LANG_ENUS,                      \
 138                         USB_DESC_STRING(manuf),                         \
 139                         USB_DESC_STRING(product),                       \
 140                         USB_DESC_STRING_SERIALNO,                       \
 141                         NULL                                            \
 142                 },                                                      \
 143                 .configs = {                                            \
 144                         __REPEAT(1, USB__INCREMENT, USB__DEFINE_CONFIG, __VA_ARGS__) \
 145                         NULL                                            \
 146                 }                                                       \
 147         }
 148
 149
 150
 151 // ----- Structs & Enumerations -----
 152
 153 /**
 154  * Note: bitfields ahead.
 155  * GCC fills the fields lsb-to-msb on little endian.
 156  */
 157
 158 /**
 159  * USB descriptors
 160  */
 161
 162 enum usb_desc_type {
 163         USB_DESC_DEV = 1,
 164         USB_DESC_CONFIG = 2,
 165         USB_DESC_STRING = 3,
 166         USB_DESC_IFACE = 4,
 167         USB_DESC_EP = 5,
 168         USB_DESC_DEVQUAL = 6,
 169         USB_DESC_OTHERSPEED = 7,
 170         USB_DESC_POWER = 8
 171 };
 172
 173 struct usb_desc_type_t {
 174         UNION_STRUCT_START(8);
 175         enum usb_desc_type id : 5;
 176         enum usb_desc_type_type {
 177                 USB_DESC_TYPE_STD = 0,
 178                 USB_DESC_TYPE_CLASS = 1,
 179                 USB_DESC_TYPE_VENDOR = 2
 180         } type_type : 2;
 181         uint8_t _rsvd0 : 1;
 182         UNION_STRUCT_END;
 183 };
 184 CTASSERT_SIZE_BYTE(struct usb_desc_type_t, 1);
 185
 186 enum usb_dev_class {
 187         USB_DEV_CLASS_SEE_IFACE = 0,
 188         USB_DEV_CLASS_APP = 0xfe,
 189         USB_DEV_CLASS_VENDOR = 0xff
 190 };
 191
 192 enum usb_dev_subclass {
 193         USB_DEV_SUBCLASS_SEE_IFACE = 0,
 194         USB_DEV_SUBCLASS_VENDOR = 0xff
 195 };
 196
 197 enum usb_dev_proto {
 198         USB_DEV_PROTO_SEE_IFACE = 0,
 199         USB_DEV_PROTO_VENDOR = 0xff
 200 };
 201
 202 struct usb_bcd_t {
 203         UNION_STRUCT_START(16);
 204         struct {
 205                 uint8_t sub : 4;
 206                 uint8_t min : 4;
 207                 uint16_t maj : 8;
 208         };
 209         UNION_STRUCT_END;
 210 };
 211 CTASSERT_SIZE_BYTE(struct usb_bcd_t, 2);
 212
 213 struct usb_desc_generic_t {
 214         uint8_t bLength;
 215         struct usb_desc_type_t bDescriptorType;
 216         uint8_t data[];
 217 };
 218 CTASSERT_SIZE_BYTE(struct usb_desc_generic_t, 2);
 219
 220 struct usb_desc_dev_t {
 221         uint8_t bLength;
 222         enum usb_desc_type bDescriptorType : 8; /* = USB_DESC_DEV */
 223         struct usb_bcd_t bcdUSB;             /* = 0x0200 */
 224         enum usb_dev_class bDeviceClass : 8;
 225         enum usb_dev_subclass bDeviceSubClass : 8;
 226         enum usb_dev_proto bDeviceProtocol : 8;
 227         uint8_t bMaxPacketSize0;
 228         uint16_t idVendor;
 229         uint16_t idProduct;
 230         struct usb_bcd_t bcdDevice;
 231         uint8_t iManufacturer;
 232         uint8_t iProduct;
 233         uint8_t iSerialNumber;
 234         uint8_t bNumConfigurations;
 235 };
 236 CTASSERT_SIZE_BYTE(struct usb_desc_dev_t, 18);
 237
 238 struct usb_desc_ep_t {
 239         uint8_t bLength;
 240         enum usb_desc_type bDescriptorType : 8; /* = USB_DESC_EP */
 241         union {
 242                 struct {
 243                         uint8_t ep_num : 4;
 244                         uint8_t _rsvd0 : 3;
 245                         uint8_t in : 1;
 246                 };
 247                 uint8_t bEndpointAddress;
 248         };
 249         struct {
 250                 enum usb_ep_type {
 251                         USB_EP_CONTROL = 0,
 252                         USB_EP_ISO = 1,
 253                         USB_EP_BULK = 2,
 254                         USB_EP_INTR = 3
 255                 } type : 2;
 256                 enum usb_ep_iso_synctype {
 257                         USB_EP_ISO_NOSYNC = 0,
 258                         USB_EP_ISO_ASYNC = 1,
 259                         USB_EP_ISO_ADAPTIVE = 2,
 260                         USB_EP_ISO_SYNC = 3
 261                 } sync_type : 2;
 262                 enum usb_ep_iso_usagetype {
 263                         USB_EP_ISO_DATA = 0,
 264                         USB_EP_ISO_FEEDBACK = 1,
 265                         USB_EP_ISO_IMPLICIT = 2
 266                 } usage_type : 2;
 267                 uint8_t _rsvd1 : 2;
 268         };
 269         struct {
 270                 uint16_t wMaxPacketSize : 11;
 271                 uint16_t _rsvd2 : 5;
 272         };
 273         uint8_t bInterval;
 274 } __packed;
 275 CTASSERT_SIZE_BYTE(struct usb_desc_ep_t, 7);
 276
 277 struct usb_desc_iface_t {
 278         uint8_t bLength;
 279         enum usb_desc_type bDescriptorType : 8; /* = USB_DESC_IFACE */
 280         uint8_t bInterfaceNumber;
 281         uint8_t bAlternateSetting;
 282         uint8_t bNumEndpoints;
 283         enum usb_dev_class bInterfaceClass : 8;
 284         enum usb_dev_subclass bInterfaceSubClass: 8;
 285         enum usb_dev_proto bInterfaceProtocol : 8;
 286         uint8_t iInterface;
 287 };
 288 CTASSERT_SIZE_BYTE(struct usb_desc_iface_t, 9);
 289
 290 struct usb_desc_config_t {
 291         uint8_t bLength;
 292         enum usb_desc_type bDescriptorType : 8; /* = USB_DESC_CONFIG */
 293         uint16_t wTotalLength;       /* size of config, iface, ep */
 294         uint8_t bNumInterfaces;
 295         uint8_t bConfigurationValue;
 296         uint8_t iConfiguration;
 297         struct {
 298                 uint8_t _rsvd0 : 5;
 299                 uint8_t remote_wakeup : 1;
 300                 uint8_t self_powered : 1;
 301                 uint8_t one : 1; /* = 1 for historical reasons */
 302         };
 303         uint8_t bMaxPower;      /* units of 2mA */
 304 } __packed;
 305 CTASSERT_SIZE_BYTE(struct usb_desc_config_t, 9);
 306
 307 struct usb_desc_string_t {
 308         uint8_t bLength;
 309         enum usb_desc_type bDescriptorType : 8; /* = USB_DESC_STRING */
 310         const char16_t bString[];
 311 };
 312 CTASSERT_SIZE_BYTE(struct usb_desc_string_t, 2);
 313
 314 struct usb_ctrl_req_t {
 315         union /* reqtype and request & u16 */ {
 316                 struct /* reqtype and request */ {
 317                         union /* reqtype in bitfield & u8 */ {
 318                                 struct /* reqtype */ {
 319                                         enum usb_ctrl_req_recp {
 320                                                 USB_CTRL_REQ_DEV = 0,
 321                                                 USB_CTRL_REQ_IFACE = 1,
 322                                                 USB_CTRL_REQ_EP = 2,
 323                                                 USB_CTRL_REQ_OTHER = 3
 324                                         } recp : 5;
 325                                         enum usb_ctrl_req_type {
 326                                                 USB_CTRL_REQ_STD = 0,
 327                                                 USB_CTRL_REQ_CLASS = 1,
 328                                                 USB_CTRL_REQ_VENDOR = 2
 329                                         } type : 2;
 330                                         enum usb_ctrl_req_dir {
 331                                                 USB_CTRL_REQ_OUT = 0,
 332                                                 USB_CTRL_REQ_IN = 1
 333                                         } in : 1;
 334                                 };
 335                                 uint8_t bmRequestType;
 336                         }; /* union */
 337                         enum usb_ctrl_req_code {
 338                                 USB_CTRL_REQ_GET_STATUS = 0,
 339                                 USB_CTRL_REQ_CLEAR_FEATURE = 1,
 340                                 USB_CTRL_REQ_SET_FEATURE = 3,
 341                                 USB_CTRL_REQ_SET_ADDRESS = 5,
 342                                 USB_CTRL_REQ_GET_DESCRIPTOR = 6,
 343                                 USB_CTRL_REQ_SET_DESCRIPTOR = 7,
 344                                 USB_CTRL_REQ_GET_CONFIGURATION = 8,
 345                                 USB_CTRL_REQ_SET_CONFIGURATION = 9,
 346                                 USB_CTRL_REQ_GET_INTERFACE = 10,
 347                                 USB_CTRL_REQ_SET_INTERFACE = 11,
 348                                 USB_CTRL_REQ_SYNC_FRAME = 12
 349                         } bRequest : 8;
 350                 }; /* struct */
 351                 uint16_t type_and_req;
 352         }; /* union */
 353         union {
 354                 uint16_t wValue;
 355                 struct {
 356                         uint8_t wValueLow;
 357                         uint8_t wValueHigh;
 358                 };
 359         };
 360         uint16_t wIndex;
 361         uint16_t wLength;
 362 };
 363 CTASSERT_SIZE_BYTE(struct usb_ctrl_req_t, 8);
 364
 365 /**
 366  * status replies for GET_STATUS.
 367  */
 368
 369 struct usb_ctrl_req_status_dev_t {
 370         uint16_t self_powered : 1;
 371         uint16_t remote_wakeup : 1;
 372         uint16_t _rsvd : 14;
 373 };
 374 CTASSERT_SIZE_BIT(struct usb_ctrl_req_status_dev_t, 16);
 375
 376 struct usb_ctrl_req_status_iface_t {
 377         uint16_t _rsvd;
 378 };
 379 CTASSERT_SIZE_BIT(struct usb_ctrl_req_status_iface_t, 16);
 380
 381 struct usb_ctrl_req_status_ep_t {
 382         uint16_t halt : 1;
 383         uint16_t _rsvd : 15;
 384 };
 385 CTASSERT_SIZE_BIT(struct usb_ctrl_req_status_ep_t, 16);
 386
 387 /**
 388  * Descriptor type (in req->value) for GET_DESCRIPTOR.
 389  */
 390 struct usb_ctrl_req_desc_t {
 391         uint8_t idx;
 392         enum usb_desc_type type : 8;
 393 };
 394 CTASSERT_SIZE_BIT(struct usb_ctrl_req_desc_t, 16);
 395
 396 /**
 397  * Feature selector (in req->value) for CLEAR_FEATURE.
 398  */
 399 enum usb_ctrl_req_feature {
 400         USB_CTRL_REQ_FEAT_EP_HALT = 0,
 401         USB_CTRL_REQ_FEAT_DEV_REMOTE_WKUP = 1,
 402         USB_CTRL_REQ_FEAT_TEST_MODE = 2
 403 };
 404
 405
 406 struct usb_xfer_info;
 407 typedef void (*ep_callback_t)(void *buf, ssize_t len, void *data);
 408
 409 /**
 410  * (Artificial) function.  Aggregates one or more interfaces.
 411  */
 412 struct usbd_function {
 413         int (*configure)(int orig_iface, int iface, int altsetting, void *data);
 414         int (*control)(struct usb_ctrl_req_t *, void *);
 415         int interface_count;
 416         int ep_rx_count;
 417         int ep_tx_count;
 418 };
 419
 420 struct usbd_function_ctx_header {
 421         struct usbd_function_ctx_header *next;
 422         const struct usbd_function *function;
 423         int interface_offset;
 424         int ep_rx_offset;
 425         int ep_tx_offset;
 426 };
 427
 428
 429 typedef void (usbd_init_fun_t)(int);
 430 typedef void (usbd_suspend_resume_fun_t)(void);
 431
 432 /**
 433  * Configuration.  Contains one or more functions which all will be
 434  * active concurrently.
 435  */
 436 struct usbd_config {
 437         usbd_init_fun_t *init;
 438         usbd_suspend_resume_fun_t *suspend;
 439         usbd_suspend_resume_fun_t *resume;
 440         /**
 441          * We will not set a config for now, because there is not much to
 442          * configure, except for power
 443          *
 444          * const struct usb_desc_config_t *config_desc;
 445          */
 446         const struct usb_desc_config_t *desc;
 447         const struct usbd_function *function[];
 448 };
 449
 450
 451 /**
 452  * Device.  Contains one or more configurations, out of which only one
 453  * is active at a time.
 454  */
 455 struct usbd_device {
 456         const struct usb_desc_dev_t *dev_desc;
 457         const struct usb_desc_string_t * const *string_descs;
 458         const struct usbd_config *configs[];
 459 };
 460
 461
 462
 463 /* Provided by MD code */
 464 struct usbd_ep_pipe_state_t;
 465
 466
 467
 468 // ----- Functions -----
 469
 470 void *usb_get_xfer_data(struct usb_xfer_info *);
 471 enum usb_tok_pid usb_get_xfer_pid(struct usb_xfer_info *);
 472 int usb_get_xfer_ep(struct usb_xfer_info *);
 473 enum usb_ep_dir usb_get_xfer_dir(struct usb_xfer_info *);
 474 void usb_enable_xfers(void);
 475 void usb_set_addr(int);
 476 void usb_ep_stall(int);
 477 size_t usb_ep_get_transfer_size(struct usbd_ep_pipe_state_t *);
 478 void usb_queue_next(struct usbd_ep_pipe_state_t *, void *, size_t);
 479 void usb_pipe_stall(struct usbd_ep_pipe_state_t *);
 480 void usb_pipe_unstall(struct usbd_ep_pipe_state_t *);
 481 void usb_pipe_enable(struct usbd_ep_pipe_state_t *s);
 482 void usb_pipe_disable(struct usbd_ep_pipe_state_t *s);
 483 #ifdef VUSB
 484 void vusb_main_loop(void);
 485 #else
 486 void usb_poll(void);
 487 #endif
 488 int usb_tx_serialno(size_t reqlen);
 489
 490 /* Provided by MI code */
 491 void usb_init(const struct usbd_device *);
 492 void usb_attach_function(const struct usbd_function *function, struct usbd_function_ctx_header *ctx);
 493 void usb_handle_transaction(struct usb_xfer_info *);
 494 void usb_setup_control(void);
 495 void usb_handle_control_status_cb(ep_callback_t cb);
 496 void usb_handle_control_status(int);
 497 struct usbd_ep_pipe_state_t *usb_init_ep(struct usbd_function_ctx_header *ctx, int ep, enum usb_ep_dir dir, size_t size);
 498 int usb_rx(struct usbd_ep_pipe_state_t *, void *, size_t, ep_callback_t, void *);
 499 int usb_tx(struct usbd_ep_pipe_state_t *, const void *, size_t, size_t, ep_callback_t, void *);
 500
 501 int usb_ep0_rx(void *, size_t, ep_callback_t, void *);
 502 void *usb_ep0_tx_inplace_prepare(size_t len);
 503 int usb_ep0_tx(void *buf, size_t len, size_t reqlen, ep_callback_t cb, void *cb_data);
 504 int usb_ep0_tx_cp(const void *, size_t, size_t, ep_callback_t, void *);
 505
 506
 507
 508 // ----- DFU USB Additional Includes -----
 509
 510 #include "dfu.h"
 511
 512 #endif
 513