flight/pios/inc/pios_usb_defs.h

   1 /**
   2  ****************************************************************************************
   3  * @addtogroup PIOS PIOS Core hardware abstraction layer
   4  * @{
   5  * @addtogroup PIOS_USB_DEFS USB standard types and definitions
   6  * @brief USB standard types and definitions
   7  * @{
   8  *
   9  * @file       pios_usb_defs.h
  10  * @author     The LibrePilot Project, http://www.librepilot.org Copyright (C) 2015-2016.
  11  *             The OpenPilot Team, http://www.openpilot.org Copyright (C) 2010.
  12  * @brief      USB Standard types and definitions
  13  * @see        The GNU Public License (GPL) Version 3
  14  *
  15  ***************************************************************************************/
  16 /*
  17  * This program is free software; you can redistribute it and/or modify
  18  * it under the terms of the GNU General Public License as published by
  19  * the Free Software Foundation; either version 3 of the License, or
  20  * (at your option) any later version.
  21  *
  22  * This program is distributed in the hope that it will be useful, but
  23  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  24  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  25  * for more details.
  26  *
  27  * You should have received a copy of the GNU General Public License along
  28  * with this program; if not, write to the Free Software Foundation, Inc.,
  29  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  30  */
  31
  32 #ifndef PIOS_USB_DEFS_H
  33 #define PIOS_USB_DEFS_H
  34
  35 #include <stdint.h> /* uint*_t */
  36
  37 enum usb_desc_types {
  38     USB_DESC_TYPE_DEVICE         = 0x01,
  39     USB_DESC_TYPE_CONFIGURATION  = 0x02,
  40     USB_DESC_TYPE_STRING         = 0x03,
  41     USB_DESC_TYPE_INTERFACE      = 0x04,
  42     USB_DESC_TYPE_ENDPOINT       = 0x05,
  43     USB_DESC_TYPE_IAD = 0x0B,
  44     USB_DESC_TYPE_HID = 0x21,
  45     USB_DESC_TYPE_REPORT         = 0x22,
  46     USB_DESC_TYPE_CLASS_SPECIFIC = 0x24,
  47 } __attribute__((packed));
  48
  49 enum usb_interface_class {
  50     USB_INTERFACE_CLASS_CDC  = 0x02,
  51     USB_INTERFACE_CLASS_HID  = 0x03,
  52     USB_INTERFACE_CLASS_DATA = 0x0A,
  53 } __attribute__((packed));
  54
  55 enum usb_cdc_desc_subtypes {
  56     USB_CDC_DESC_SUBTYPE_HEADER   = 0x00,
  57     USB_CDC_DESC_SUBTYPE_CALLMGMT = 0x01,
  58     USB_CDC_DESC_SUBTYPE_ABSTRACT_CTRL = 0x02,
  59     USB_CDC_DESC_SUBTYPE_UNION    = 0x06,
  60 } __attribute__((packed));
  61
  62 enum usb_ep_attr {
  63     USB_EP_ATTR_TT_CONTROL     = 0x00,
  64     USB_EP_ATTR_TT_ISOCHRONOUS = 0x01,
  65     USB_EP_ATTR_TT_BULK = 0x02,
  66     USB_EP_ATTR_TT_INTERRUPT   = 0x03,
  67 } __attribute__((packed));
  68
  69 /* Standard macros to convert from host endian to USB endian (ie. little endian) */
  70 #if __BIG_ENDIAN__
  71 #define htousbs(v) \
  72     ((uint16_t)( \
  73          ((((v) >> 0) & 0xFF) << 8) |    \
  74          ((((v) >> 8) & 0xFF) << 0)))
  75 #define htousbl(v) \
  76     ((uint32_t)( \
  77          ((((v) >> 0) & 0xFF) << 24) |  \
  78          ((((v) >> 8) & 0xFF) << 16) |  \
  79          ((((v) >> 16) & 0xFF) << 8) |  \
  80          ((((v) >> 24) & 0xFF) << 0)))
  81 #else
  82 #define htousbs(v)     (v)
  83 #define htousbl(v)     (v)
  84 #endif
  85
  86 #define usbstoh(v)     htousbs(v)
  87 #define usbltoh(v)     htousbl(v)
  88
  89 #define USB_EP_IN(ep)  ((uint8_t)(0x80 | ((ep) & 0xF)))
  90 #define USB_EP_OUT(ep) ((uint8_t)(0x00 | ((ep) & 0xF)))
  91
  92 #define HID_ITEM_TYPE_MAIN         0x0
  93 #define HID_ITEM_TYPE_GLOBAL       0x1
  94 #define HID_ITEM_TYPE_LOCAL        0x2
  95 #define HID_ITEM_TYPE_RSVD         0x3
  96
  97 #define HID_TAG_GLOBAL_USAGE_PAGE  0x0 /* 0b0000 */
  98 #define HID_TAG_GLOBAL_LOGICAL_MIN 0x1 /* 0b0001 */
  99 #define HID_TAG_GLOBAL_LOGICAL_MAX 0x2 /* 0b0010 */
 100 #define HID_TAG_GLOBAL_PHYS_MIN    0x3 /* 0b0011 */
 101 #define HID_TAG_GLOBAL_PHYS_MAX    0x4 /* 0b0100 */
 102 #define HID_TAG_GLOBAL_UNIT_EXP    0x5 /* 0b0101 */
 103 #define HID_TAG_GLOBAL_UNIT        0x6 /* 0b0110 */
 104 #define HID_TAG_GLOBAL_REPORT_SIZE 0x7 /* 0b0111 */
 105 #define HID_TAG_GLOBAL_REPORT_ID   0x8 /* 0b1000 */
 106 #define HID_TAG_GLOBAL_REPORT_CNT  0x9 /* 0b1001 */
 107 #define HID_TAG_GLOBAL_PUSH        0xA /* 0b1010 */
 108 #define HID_TAG_GLOBAL_POP         0xB /* 0b1011 */
 109
 110 #define HID_TAG_MAIN_INPUT         0x8 /* 0b1000 */
 111 #define HID_TAG_MAIN_OUTPUT        0x9 /* 0b1001 */
 112 #define HID_TAG_MAIN_COLLECTION    0xA /* 0b1010 */
 113 #define HID_TAG_MAIN_FEATURE       0xB /* 0b1011 */
 114 #define HID_TAG_MAIN_ENDCOLLECTION 0xC /* 0b1100 */
 115
 116 #define HID_TAG_LOCAL_USAGE        0x0 /* 0b0000 */
 117 #define HID_TAG_LOCAL_USAGE_MIN    0x1 /* 0b0001 */
 118 #define HID_TAG_LOCAL_USAGE_MAX    0x2 /* 0b0010 */
 119 #define HID_TAG_LOCAL_DESIG_INDEX  0x3 /* 0b0011 */
 120 #define HID_TAG_LOCAL_DESIG_MIN    0x4 /* 0b0100 */
 121 #define HID_TAG_LOCAL_DESIG_MAX    0x5 /* 0b0101 */
 122 /* There is no value defined for 0x6 */
 123 #define HID_TAG_LOCAL_STRING_INDEX 0x7 /* 0b0111 */
 124 #define HID_TAG_LOCAL_STRING_MIN   0x8 /* 0b1000 */
 125 #define HID_TAG_LOCAL_STRING_MAX   0x9 /* 0b1001 */
 126 #define HID_TAG_LOCAL_DELIMITER    0xA /* 0b1010 */
 127
 128 #define HID_TAG_RSVD               0xF /* 0b1111 */
 129
 130 #define HID_ITEM_SIZE_0            0
 131 #define HID_ITEM_SIZE_1            1
 132 #define HID_ITEM_SIZE_2            2
 133 #define HID_ITEM_SIZE_4            3       /* Yes, 4 bytes is represented with a size field = 3 */
 134
 135 #define HID_SHORT_ITEM(tag, type, size) \
 136     ( \
 137         (((tag) & 0xF) << 4) |        \
 138         (((type) & 0x3) << 2) |        \
 139         (((size) & 0x3) << 0))
 140
 141 /* Long items have a fixed prefix */
 142 #define HID_LONG_ITEM              HID_SHORT_ITEM(HID_TAG_RSVD, HID_ITEM_TYPE_RSVD, HID_ITEM_SIZE_2)
 143
 144 #define HID_MAIN_ITEM_0(tag)   HID_SHORT_ITEM((tag), HID_ITEM_TYPE_MAIN, HID_ITEM_SIZE_0)
 145 #define HID_MAIN_ITEM_1(tag)   HID_SHORT_ITEM((tag), HID_ITEM_TYPE_MAIN, HID_ITEM_SIZE_1)
 146 #define HID_MAIN_ITEM_2(tag)   HID_SHORT_ITEM((tag), HID_ITEM_TYPE_MAIN, HID_ITEM_SIZE_2)
 147 #define HID_MAIN_ITEM_4(tag)   HID_SHORT_ITEM((tag), HID_ITEM_TYPE_MAIN, HID_ITEM_SIZE_4)
 148
 149 #define HID_GLOBAL_ITEM_0(tag) HID_SHORT_ITEM((tag), HID_ITEM_TYPE_GLOBAL, HID_ITEM_SIZE_0)
 150 #define HID_GLOBAL_ITEM_1(tag) HID_SHORT_ITEM((tag), HID_ITEM_TYPE_GLOBAL, HID_ITEM_SIZE_1)
 151 #define HID_GLOBAL_ITEM_2(tag) HID_SHORT_ITEM((tag), HID_ITEM_TYPE_GLOBAL, HID_ITEM_SIZE_2)
 152 #define HID_GLOBAL_ITEM_4(tag) HID_SHORT_ITEM((tag), HID_ITEM_TYPE_GLOBAL, HID_ITEM_SIZE_4)
 153
 154 #define HID_LOCAL_ITEM_0(tag)  HID_SHORT_ITEM((tag), HID_ITEM_TYPE_LOCAL, HID_ITEM_SIZE_0)
 155 #define HID_LOCAL_ITEM_1(tag)  HID_SHORT_ITEM((tag), HID_ITEM_TYPE_LOCAL, HID_ITEM_SIZE_1)
 156 #define HID_LOCAL_ITEM_2(tag)  HID_SHORT_ITEM((tag), HID_ITEM_TYPE_LOCAL, HID_ITEM_SIZE_2)
 157 #define HID_LOCAL_ITEM_4(tag)  HID_SHORT_ITEM((tag), HID_ITEM_TYPE_LOCAL, HID_ITEM_SIZE_4)
 158
 159 struct usb_device_desc {
 160     uint8_t  bLength;
 161     uint8_t  bDescriptorType;
 162     uint16_t bcdUSB;
 163     uint8_t  bDeviceClass;
 164     uint8_t  bDeviceSubClass;
 165     uint8_t  bDeviceProtocol;
 166     uint8_t  bMaxPacketSize0;
 167     uint16_t idVendor;
 168     uint16_t idProduct;
 169     uint16_t bcdDevice;
 170     uint8_t  iManufacturer;
 171     uint8_t  iProduct;
 172     uint8_t  iSerialNumber;
 173     uint8_t  bNumConfigurations;
 174 } __attribute__((packed));
 175
 176 struct usb_configuration_desc {
 177     uint8_t  bLength;
 178     uint8_t  bDescriptorType;
 179     uint16_t wTotalLength;
 180     uint8_t  bNumInterfaces;
 181     uint8_t  bConfigurationValue;
 182     uint8_t  iConfiguration;
 183     uint8_t  bmAttributes;
 184     uint8_t  bMaxPower;
 185 } __attribute__((packed));
 186
 187 struct usb_interface_association_desc {
 188     uint8_t bLength;
 189     uint8_t bDescriptorType;
 190     uint8_t bFirstInterface;
 191     uint8_t bInterfaceCount;
 192     uint8_t bFunctionClass;
 193     uint8_t bFunctionSubClass;
 194     uint8_t bFunctionProtocol;
 195     uint8_t iInterface;
 196 } __attribute__((packed));
 197
 198 struct usb_interface_desc {
 199     uint8_t bLength;
 200     uint8_t bDescriptorType;
 201     uint8_t bInterfaceNumber;
 202     uint8_t bAlternateSetting;
 203     uint8_t bNumEndpoints;
 204     uint8_t bInterfaceClass;
 205     uint8_t bInterfaceSubClass;
 206     uint8_t nInterfaceProtocol;
 207     uint8_t iInterface;
 208 } __attribute__((packed));
 209
 210 struct usb_hid_desc {
 211     uint8_t  bLength;
 212     uint8_t  bDescriptorType;
 213     uint16_t bcdHID;
 214     uint8_t  bCountryCode;
 215     uint8_t  bNumDescriptors;
 216     uint8_t  bClassDescriptorType;
 217     uint16_t wItemLength;
 218 } __attribute__((packed));
 219
 220 struct usb_endpoint_desc {
 221     uint8_t  bLength;
 222     uint8_t  bDescriptorType;
 223     uint8_t  bEndpointAddress;
 224     uint8_t  bmAttributes;
 225     uint16_t wMaxPacketSize;
 226     uint8_t  bInterval;
 227 } __attribute__((packed));
 228
 229 struct usb_setup_request {
 230     uint8_t  bmRequestType;
 231     uint8_t  bRequest;
 232     uint16_t wValue;
 233     uint16_t wIndex;
 234     uint16_t wLength;
 235 } __attribute__((packed));
 236
 237 #define USB_REQ_TYPE_STANDARD       0x00
 238 #define USB_REQ_TYPE_CLASS          0x20
 239 #define USB_REQ_TYPE_VENDOR         0x40
 240 #define USB_REQ_TYPE_MASK           0x60
 241
 242 #define USB_REQ_RECIPIENT_DEVICE    0x00
 243 #define USB_REQ_RECIPIENT_INTERFACE 0x01
 244 #define USB_REQ_RECIPIENT_ENDPOINT  0x02
 245 #define USB_REQ_RECIPIENT_MASK      0x03
 246
 247 enum usb_standard_requests {
 248     USB_REQ_GET_STATUS        = 0x00,
 249     USB_REQ_CLEAR_FEATURE     = 0x01,
 250     /* what is 0x02? */
 251     USB_REQ_SET_FEATURE       = 0x03,
 252     /* what is 0x04? */
 253     USB_REQ_SET_ADDRESS       = 0x05,
 254     USB_REQ_GET_DESCRIPTOR    = 0x06,
 255     USB_REQ_SET_DESCRIPTOR    = 0x07,
 256     USB_REQ_GET_CONFIGURATION = 0x08,
 257     USB_REQ_SET_CONFIGURATION = 0x09,
 258     USB_REQ_GET_INTERFACE     = 0x0A,
 259     USB_REQ_SET_INTERFACE     = 0x0B,
 260     USB_REQ_SYNCH_FRAME       = 0x0C,
 261 };
 262
 263 enum usb_hid_requests {
 264     USB_HID_REQ_GET_REPORT   = 0x01,
 265     USB_HID_REQ_GET_IDLE     = 0x02,
 266     USB_HID_REQ_GET_PROTOCOL = 0x03,
 267     /* 0x04-0x08 Reserved */
 268     USB_HID_REQ_SET_REPORT   = 0x09,
 269     USB_HID_REQ_SET_IDLE     = 0x0A,
 270     USB_HID_REQ_SET_PROTOCOL = 0x0B,
 271 };
 272
 273 enum usb_cdc_requests {
 274     USB_CDC_REQ_SET_LINE_CODING = 0x20,
 275     USB_CDC_REQ_GET_LINE_CODING = 0x21,
 276
 277     USB_CDC_REQ_SET_CONTROL_LINE_STATE = 0x22,
 278 };
 279
 280 struct usb_cdc_header_func_desc {
 281     uint8_t  bLength;
 282     uint8_t  bDescriptorType;
 283     uint8_t  bDescriptorSubType;
 284     uint16_t bcdCDC;
 285 } __attribute__((packed));
 286
 287 struct usb_cdc_callmgmt_func_desc {
 288     uint8_t bLength;
 289     uint8_t bDescriptorType;
 290     uint8_t bDescriptorSubType;
 291     uint8_t bmCapabilities;
 292     uint8_t bDataInterface;
 293 } __attribute__((packed));
 294
 295 struct usb_cdc_acm_func_desc {
 296     uint8_t bLength;
 297     uint8_t bDescriptorType;
 298     uint8_t bDescriptorSubType;
 299     uint8_t bmCapabilities;
 300 } __attribute__((packed));
 301
 302 struct usb_cdc_union_func_desc {
 303     uint8_t bLength;
 304     uint8_t bDescriptorType;
 305     uint8_t bDescriptorSubType;
 306     uint8_t bMasterInterface;
 307     uint8_t bSlaveInterface;
 308 } __attribute__((packed));
 309
 310 #define USB_LANGID_ENGLISH_US 0x0409
 311
 312 struct usb_string_langid {
 313     uint8_t  bLength;
 314     uint8_t  bDescriptorType;
 315     uint16_t bLangID;
 316 } __attribute__((packed));
 317
 318 struct usb_cdc_line_coding {
 319     uint32_t dwDTERate;
 320     uint8_t  bCharFormat;
 321     uint8_t  bParityType;
 322     uint8_t  bDataBits;
 323 } __attribute__((packed));
 324
 325 enum usb_cdc_line_coding_stop {
 326     USB_CDC_LINE_CODING_STOP_1   = 0,
 327     USB_CDC_LINE_CODING_STOP_1_5 = 1,
 328     USB_CDC_LINE_CODING_STOP_2   = 2,
 329 } __attribute__((packed));
 330
 331 enum usb_cdc_line_coding_parity {
 332     USB_CDC_LINE_CODING_PARITY_NONE  = 0,
 333     USB_CDC_LINE_CODING_PARITY_ODD   = 1,
 334     USB_CDC_LINE_CODING_PARITY_EVEN  = 2,
 335     USB_CDC_LINE_CODING_PARITY_MARK  = 3,
 336     USB_CDC_LINE_CODING_PARITY_SPACE = 4,
 337 } __attribute__((packed));
 338
 339 struct usb_cdc_serial_state_report {
 340     uint8_t  bmRequestType;
 341     uint8_t  bNotification;
 342     uint16_t wValue;
 343     uint16_t wIndex;
 344     uint16_t wLength;
 345     uint16_t bmUartState;
 346 } __attribute__((packed));
 347
 348 enum usb_cdc_notification {
 349     USB_CDC_NOTIFICATION_SERIAL_STATE = 0x20,
 350 } __attribute__((packed));
 351
 352 /*
 353  * OpenPilot Specific USB Definitions
 354  */
 355
 356 #define USB_VENDOR_ID_OPENPILOT 0x20A0
 357
 358 enum usb_product_ids {
 359     USB_PRODUCT_ID_OPENPILOT_MAIN = 0x415A,
 360     USB_PRODUCT_ID_COPTERCONTROL  = 0x415B,
 361     USB_PRODUCT_ID_OPLINK = 0x415C,
 362     USB_PRODUCT_ID_CC3D = 0x415D,
 363     USB_PRODUCT_ID_REVOLUTION     = 0x415E,
 364     USB_PRODUCT_ID_SPARKY2 = 0x41D0, // was 0x415E during LP testing
 365     USB_PRODUCT_ID_OSD = 0x4194,
 366     USB_PRODUCT_ID_LIBREPILOT     = 0x4195,
 367 } __attribute__((packed));
 368
 369 enum usb_op_board_ids {
 370     USB_OP_BOARD_ID_OPENPILOT_MAIN = 1,
 371     /* Board ID 2 may be unused or AHRS */
 372     USB_OP_BOARD_ID_OPLINK = 3,
 373     USB_OP_BOARD_ID_COPTERCONTROL  = 4,
 374     USB_OP_BOARD_ID_REVOLUTION     = 5,
 375     USB_OP_BOARD_ID_SPARKY2       = 5,
 376     USB_OP_BOARD_ID_OSD           = 6,
 377     USB_OP_BOARD_ID_CCF3D         = 7,
 378     USB_OP_BOARD_ID_SPRACINGF3    = 8,
 379     USB_OP_BOARD_ID_SPRACINGF3EVO = 9,
 380     USB_OP_BOARD_ID_NUCLEOF303RE  = 10,
 381     USB_OP_BOARD_ID_PIKOBLX       = 11,
 382     USB_OP_BOARD_ID_TINYFISH      = 12,
 383 } __attribute__((packed));
 384
 385 enum usb_op_board_modes {
 386     USB_OP_BOARD_MODE_BL = 1,
 387     USB_OP_BOARD_MODE_FW = 2,
 388 } __attribute__((packed));
 389
 390 #define USB_OP_DEVICE_VER(board_id, board_mode) \
 391     ( \
 392         ((board_id & 0xFF) << 8) |     \
 393         ((board_mode & 0xFF) << 0))
 394
 395 #endif /* PIOS_USB_DEFS_H */