qemu/roms/ipxe/src/include/ipxe/usb.h

   1 #ifndef _IPXE_USB_H
   2 #define _IPXE_USB_H
   3
   4 /** @file
   5  *
   6  * Universal Serial Bus (USB)
   7  *
   8  */
   9
  10 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
  11
  12 #include <byteswap.h>
  13 #include <ipxe/list.h>
  14 #include <ipxe/device.h>
  15 #include <ipxe/process.h>
  16 #include <ipxe/iobuf.h>
  17 #include <ipxe/tables.h>
  18
  19 /** USB protocols */
  20 enum usb_protocol {
  21         /** USB 2.0 */
  22         USB_PROTO_2_0 = 0x0200,
  23         /** USB 3.0 */
  24         USB_PROTO_3_0 = 0x0300,
  25         /** USB 3.1 */
  26         USB_PROTO_3_1 = 0x0301,
  27 };
  28
  29 /** Define a USB speed
  30  *
  31  * @v mantissa          Mantissa
  32  * @v exponent          Exponent (in engineering terms: 1=k, 2=M, 3=G)
  33  * @ret speed           USB speed
  34  */
  35 #define USB_SPEED( mantissa, exponent ) ( (exponent << 16) | (mantissa) )
  36
  37 /** Extract USB speed mantissa */
  38 #define USB_SPEED_MANTISSA(speed) ( (speed) & 0xffff )
  39
  40 /** Extract USB speed exponent */
  41 #define USB_SPEED_EXPONENT(speed) ( ( (speed) >> 16 ) & 0x3 )
  42
  43 /** USB device speeds */
  44 enum usb_speed {
  45         /** Not connected */
  46         USB_SPEED_NONE = 0,
  47         /** Low speed (1.5Mbps) */
  48         USB_SPEED_LOW = USB_SPEED ( 1500, 1 ),
  49         /** Full speed (12Mbps) */
  50         USB_SPEED_FULL = USB_SPEED ( 12, 2 ),
  51         /** High speed (480Mbps) */
  52         USB_SPEED_HIGH = USB_SPEED ( 480, 2 ),
  53         /** Super speed (5Gbps) */
  54         USB_SPEED_SUPER = USB_SPEED ( 5, 3 ),
  55 };
  56
  57 /** USB packet IDs */
  58 enum usb_pid {
  59         /** IN PID */
  60         USB_PID_IN = 0x69,
  61         /** OUT PID */
  62         USB_PID_OUT = 0xe1,
  63         /** SETUP PID */
  64         USB_PID_SETUP = 0x2d,
  65 };
  66
  67 /** A USB setup data packet */
  68 struct usb_setup_packet {
  69         /** Request */
  70         uint16_t request;
  71         /** Value paramer */
  72         uint16_t value;
  73         /** Index parameter */
  74         uint16_t index;
  75         /** Length of data stage */
  76         uint16_t len;
  77 } __attribute__ (( packed ));
  78
  79 /** Data transfer is from host to device */
  80 #define USB_DIR_OUT ( 0 << 7 )
  81
  82 /** Data transfer is from device to host */
  83 #define USB_DIR_IN ( 1 << 7 )
  84
  85 /** Standard request type */
  86 #define USB_TYPE_STANDARD ( 0 << 5 )
  87
  88 /** Class-specific request type */
  89 #define USB_TYPE_CLASS ( 1 << 5 )
  90
  91 /** Vendor-specific request type */
  92 #define USB_TYPE_VENDOR ( 2 << 5 )
  93
  94 /** Request recipient is the device */
  95 #define USB_RECIP_DEVICE ( 0 << 0 )
  96
  97 /** Request recipient is an interface */
  98 #define USB_RECIP_INTERFACE ( 1 << 0 )
  99
 100 /** Request recipient is an endpoint */
 101 #define USB_RECIP_ENDPOINT ( 2 << 0 )
 102
 103 /** Construct USB request type */
 104 #define USB_REQUEST_TYPE(type) ( (type) << 8 )
 105
 106 /** Get status */
 107 #define USB_GET_STATUS ( USB_DIR_IN | USB_REQUEST_TYPE ( 0 ) )
 108
 109 /** Clear feature */
 110 #define USB_CLEAR_FEATURE ( USB_DIR_OUT | USB_REQUEST_TYPE ( 1 ) )
 111
 112 /** Set feature */
 113 #define USB_SET_FEATURE ( USB_DIR_OUT | USB_REQUEST_TYPE ( 3 ) )
 114
 115 /** Set address */
 116 #define USB_SET_ADDRESS ( USB_DIR_OUT | USB_REQUEST_TYPE ( 5 ) )
 117
 118 /** Get descriptor */
 119 #define USB_GET_DESCRIPTOR ( USB_DIR_IN | USB_REQUEST_TYPE ( 6 ) )
 120
 121 /** Set descriptor */
 122 #define USB_SET_DESCRIPTOR ( USB_DIR_OUT | USB_REQUEST_TYPE ( 7 ) )
 123
 124 /** Get configuration */
 125 #define USB_GET_CONFIGURATION ( USB_DIR_IN | USB_REQUEST_TYPE ( 8 ) )
 126
 127 /** Set configuration */
 128 #define USB_SET_CONFIGURATION ( USB_DIR_OUT | USB_REQUEST_TYPE ( 9 ) )
 129
 130 /** Get interface */
 131 #define USB_GET_INTERFACE \
 132         ( USB_DIR_IN | USB_RECIP_INTERFACE | USB_REQUEST_TYPE ( 10 ) )
 133
 134 /** Set interface */
 135 #define USB_SET_INTERFACE \
 136         ( USB_DIR_OUT | USB_RECIP_INTERFACE | USB_REQUEST_TYPE ( 11 ) )
 137
 138 /** Endpoint halt feature */
 139 #define USB_ENDPOINT_HALT 0
 140
 141 /** A USB class code tuple */
 142 struct usb_class {
 143         /** Class code */
 144         uint8_t class;
 145         /** Subclass code */
 146         uint8_t subclass;
 147         /** Protocol code */
 148         uint8_t protocol;
 149 } __attribute__ (( packed ));
 150
 151 /** Class code for USB hubs */
 152 #define USB_CLASS_HUB 9
 153
 154 /** A USB descriptor header */
 155 struct usb_descriptor_header {
 156         /** Length of descriptor */
 157         uint8_t len;
 158         /** Descriptor type */
 159         uint8_t type;
 160 } __attribute__ (( packed ));
 161
 162 /** A USB device descriptor */
 163 struct usb_device_descriptor {
 164         /** Descriptor header */
 165         struct usb_descriptor_header header;
 166         /** USB specification release number in BCD */
 167         uint16_t protocol;
 168         /** Device class */
 169         struct usb_class class;
 170         /** Maximum packet size for endpoint zero */
 171         uint8_t mtu;
 172         /** Vendor ID */
 173         uint16_t vendor;
 174         /** Product ID */
 175         uint16_t product;
 176         /** Device release number in BCD */
 177         uint16_t release;
 178         /** Manufacturer string */
 179         uint8_t manufacturer;
 180         /** Product string */
 181         uint8_t name;
 182         /** Serial number string */
 183         uint8_t serial;
 184         /** Number of possible configurations */
 185         uint8_t configurations;
 186 } __attribute__ (( packed ));
 187
 188 /** A USB device descriptor */
 189 #define USB_DEVICE_DESCRIPTOR 1
 190
 191 /** A USB configuration descriptor */
 192 struct usb_configuration_descriptor {
 193         /** Descriptor header */
 194         struct usb_descriptor_header header;
 195         /** Total length */
 196         uint16_t len;
 197         /** Number of interfaces */
 198         uint8_t interfaces;
 199         /** Configuration value */
 200         uint8_t config;
 201         /** Configuration string */
 202         uint8_t name;
 203         /** Attributes */
 204         uint8_t attributes;
 205         /** Maximum power consumption */
 206         uint8_t power;
 207 } __attribute__ (( packed ));
 208
 209 /** A USB configuration descriptor */
 210 #define USB_CONFIGURATION_DESCRIPTOR 2
 211
 212 /** A USB string descriptor */
 213 struct usb_string_descriptor {
 214         /** Descriptor header */
 215         struct usb_descriptor_header header;
 216         /** String */
 217         char string[0];
 218 } __attribute__ (( packed ));
 219
 220 /** A USB string descriptor */
 221 #define USB_STRING_DESCRIPTOR 3
 222
 223 /** A USB interface descriptor */
 224 struct usb_interface_descriptor {
 225         /** Descriptor header */
 226         struct usb_descriptor_header header;
 227         /** Interface number */
 228         uint8_t interface;
 229         /** Alternate setting */
 230         uint8_t alternate;
 231         /** Number of endpoints */
 232         uint8_t endpoints;
 233         /** Interface class */
 234         struct usb_class class;
 235         /** Interface name */
 236         uint8_t name;
 237 } __attribute__ (( packed ));
 238
 239 /** A USB interface descriptor */
 240 #define USB_INTERFACE_DESCRIPTOR 4
 241
 242 /** A USB endpoint descriptor */
 243 struct usb_endpoint_descriptor {
 244         /** Descriptor header */
 245         struct usb_descriptor_header header;
 246         /** Endpoint address */
 247         uint8_t endpoint;
 248         /** Attributes */
 249         uint8_t attributes;
 250         /** Maximum packet size and burst size */
 251         uint16_t sizes;
 252         /** Polling interval */
 253         uint8_t interval;
 254 } __attribute__ (( packed ));
 255
 256 /** A USB endpoint descriptor */
 257 #define USB_ENDPOINT_DESCRIPTOR 5
 258
 259 /** Endpoint attribute transfer type mask */
 260 #define USB_ENDPOINT_ATTR_TYPE_MASK 0x03
 261
 262 /** Endpoint periodic type */
 263 #define USB_ENDPOINT_ATTR_PERIODIC 0x01
 264
 265 /** Control endpoint transfer type */
 266 #define USB_ENDPOINT_ATTR_CONTROL 0x00
 267
 268 /** Bulk endpoint transfer type */
 269 #define USB_ENDPOINT_ATTR_BULK 0x02
 270
 271 /** Interrupt endpoint transfer type */
 272 #define USB_ENDPOINT_ATTR_INTERRUPT 0x03
 273
 274 /** Bulk OUT endpoint (internal) type */
 275 #define USB_BULK_OUT ( USB_ENDPOINT_ATTR_BULK | USB_DIR_OUT )
 276
 277 /** Bulk IN endpoint (internal) type */
 278 #define USB_BULK_IN ( USB_ENDPOINT_ATTR_BULK | USB_DIR_IN )
 279
 280 /** Interrupt IN endpoint (internal) type */
 281 #define USB_INTERRUPT_IN ( USB_ENDPOINT_ATTR_INTERRUPT | USB_DIR_IN )
 282
 283 /** Interrupt OUT endpoint (internal) type */
 284 #define USB_INTERRUPT_OUT ( USB_ENDPOINT_ATTR_INTERRUPT | USB_DIR_OUT )
 285
 286 /** USB endpoint MTU */
 287 #define USB_ENDPOINT_MTU(sizes) ( ( (sizes) >> 0 ) & 0x07ff )
 288
 289 /** USB endpoint maximum burst size */
 290 #define USB_ENDPOINT_BURST(sizes) ( ( (sizes) >> 11 ) & 0x0003 )
 291
 292 /** A USB endpoint companion descriptor */
 293 struct usb_endpoint_companion_descriptor {
 294         /** Descriptor header */
 295         struct usb_descriptor_header header;
 296         /** Maximum burst size */
 297         uint8_t burst;
 298         /** Extended attributes */
 299         uint8_t extended;
 300         /** Number of bytes per service interval */
 301         uint16_t periodic;
 302 } __attribute__ (( packed ));
 303
 304 /** A USB endpoint companion descriptor */
 305 #define USB_ENDPOINT_COMPANION_DESCRIPTOR 48
 306
 307 /** A USB interface association descriptor */
 308 struct usb_interface_association_descriptor {
 309         /** Descriptor header */
 310         struct usb_descriptor_header header;
 311         /** First interface number */
 312         uint8_t first;
 313         /** Interface count */
 314         uint8_t count;
 315         /** Association class */
 316         struct usb_class class;
 317         /** Association name */
 318         uint8_t name;
 319 } __attribute__ (( packed ));
 320
 321 /** A USB interface association descriptor */
 322 #define USB_INTERFACE_ASSOCIATION_DESCRIPTOR 11
 323
 324 /** A class-specific interface descriptor */
 325 #define USB_CS_INTERFACE_DESCRIPTOR 36
 326
 327 /** A class-specific endpoint descriptor */
 328 #define USB_CS_ENDPOINT_DESCRIPTOR 37
 329
 330 /**
 331  * Get next USB descriptor
 332  *
 333  * @v desc              USB descriptor header
 334  * @ret next            Next USB descriptor header
 335  */
 336 static inline __attribute__ (( always_inline )) struct usb_descriptor_header *
 337 usb_next_descriptor ( struct usb_descriptor_header *desc ) {
 338
 339         return ( ( ( void * ) desc ) + desc->len );
 340 }
 341
 342 /**
 343  * Check that descriptor lies within a configuration descriptor
 344  *
 345  * @v config            Configuration descriptor
 346  * @v desc              Descriptor header
 347  * @v is_within         Descriptor is within the configuration descriptor
 348  */
 349 static inline __attribute__ (( always_inline )) int
 350 usb_is_within_config ( struct usb_configuration_descriptor *config,
 351                        struct usb_descriptor_header *desc ) {
 352         struct usb_descriptor_header *end =
 353                 ( ( ( void * ) config ) + le16_to_cpu ( config->len ) );
 354
 355         /* Check that descriptor starts within the configuration
 356          * descriptor, and that the length does not exceed the
 357          * configuration descriptor.  This relies on the fact that
 358          * usb_next_descriptor() needs to access only the first byte
 359          * of the descriptor in order to determine the length.
 360          */
 361         return ( ( desc < end ) && ( usb_next_descriptor ( desc ) <= end ) );
 362 }
 363
 364 /** Iterate over all configuration descriptors */
 365 #define for_each_config_descriptor( desc, config )                         \
 366         for ( desc = container_of ( &(config)->header,                     \
 367                                     typeof ( *desc ), header ) ;           \
 368               usb_is_within_config ( (config), &desc->header ) ;           \
 369               desc = container_of ( usb_next_descriptor ( &desc->header ), \
 370                                     typeof ( *desc ), header ) )
 371
 372 /** Iterate over all configuration descriptors within an interface descriptor */
 373 #define for_each_interface_descriptor( desc, config, interface )           \
 374         for ( desc = container_of ( usb_next_descriptor ( &(interface)->   \
 375                                                           header ),        \
 376                                     typeof ( *desc ), header ) ;           \
 377               ( usb_is_within_config ( (config), &desc->header ) &&        \
 378                 ( desc->header.type != USB_INTERFACE_DESCRIPTOR ) ) ;      \
 379               desc = container_of ( usb_next_descriptor ( &desc->header ), \
 380                                     typeof ( *desc ), header ) )
 381
 382 /** A USB endpoint */
 383 struct usb_endpoint {
 384         /** USB device */
 385         struct usb_device *usb;
 386         /** Endpoint address */
 387         unsigned int address;
 388         /** Attributes */
 389         unsigned int attributes;
 390         /** Maximum transfer size */
 391         size_t mtu;
 392         /** Maximum burst size */
 393         unsigned int burst;
 394         /** Interval (in microframes) */
 395         unsigned int interval;
 396
 397         /** Endpoint is open */
 398         int open;
 399         /** Buffer fill level */
 400         unsigned int fill;
 401
 402         /** List of halted endpoints */
 403         struct list_head halted;
 404
 405         /** Host controller operations */
 406         struct usb_endpoint_host_operations *host;
 407         /** Host controller private data */
 408         void *priv;
 409         /** Driver operations */
 410         struct usb_endpoint_driver_operations *driver;
 411
 412         /** Recycled I/O buffer list */
 413         struct list_head recycled;
 414         /** Refill buffer length */
 415         size_t len;
 416         /** Maximum fill level */
 417         unsigned int max;
 418 };
 419
 420 /** USB endpoint host controller operations */
 421 struct usb_endpoint_host_operations {
 422         /** Open endpoint
 423          *
 424          * @v ep                USB endpoint
 425          * @ret rc              Return status code
 426          */
 427         int ( * open ) ( struct usb_endpoint *ep );
 428         /** Close endpoint
 429          *
 430          * @v ep                USB endpoint
 431          */
 432         void ( * close ) ( struct usb_endpoint *ep );
 433         /**
 434          * Reset endpoint
 435          *
 436          * @v ep                USB endpoint
 437          * @ret rc              Return status code
 438          */
 439         int ( * reset ) ( struct usb_endpoint *ep );
 440         /** Update MTU
 441          *
 442          * @v ep                USB endpoint
 443          * @ret rc              Return status code
 444          */
 445         int ( * mtu ) ( struct usb_endpoint *ep );
 446         /** Enqueue message transfer
 447          *
 448          * @v ep                USB endpoint
 449          * @v iobuf             I/O buffer
 450          * @ret rc              Return status code
 451          */
 452         int ( * message ) ( struct usb_endpoint *ep,
 453                             struct io_buffer *iobuf );
 454         /** Enqueue stream transfer
 455          *
 456          * @v ep                USB endpoint
 457          * @v iobuf             I/O buffer
 458          * @v terminate         Terminate using a short packet
 459          * @ret rc              Return status code
 460          */
 461         int ( * stream ) ( struct usb_endpoint *ep, struct io_buffer *iobuf,
 462                            int terminate );
 463 };
 464
 465 /** USB endpoint driver operations */
 466 struct usb_endpoint_driver_operations {
 467         /** Complete transfer
 468          *
 469          * @v ep                USB endpoint
 470          * @v iobuf             I/O buffer
 471          * @v rc                Completion status code
 472          */
 473         void ( * complete ) ( struct usb_endpoint *ep,
 474                               struct io_buffer *iobuf, int rc );
 475 };
 476
 477 /** Control endpoint address */
 478 #define USB_EP0_ADDRESS 0x00
 479
 480 /** Control endpoint attributes */
 481 #define USB_EP0_ATTRIBUTES 0x00
 482
 483 /** Calculate default MTU based on device speed
 484  *
 485  * @v speed             Device speed
 486  * @ret mtu             Default MTU
 487  */
 488 #define USB_EP0_DEFAULT_MTU(speed)                      \
 489         ( ( (speed) >= USB_SPEED_SUPER ) ? 512 :        \
 490           ( ( (speed) >= USB_SPEED_FULL ) ? 64 : 8 ) )
 491
 492 /** Control endpoint maximum burst size */
 493 #define USB_EP0_BURST 0
 494
 495 /** Control endpoint interval */
 496 #define USB_EP0_INTERVAL 0
 497
 498 /** Maximum endpoint number */
 499 #define USB_ENDPOINT_MAX 0x0f
 500
 501 /** Endpoint direction is in */
 502 #define USB_ENDPOINT_IN 0x80
 503
 504 /** Construct endpoint index from endpoint address */
 505 #define USB_ENDPOINT_IDX(address)                                       \
 506         ( ( (address) & USB_ENDPOINT_MAX ) |                            \
 507           ( ( (address) & USB_ENDPOINT_IN ) >> 3 ) )
 508
 509 /**
 510  * Initialise USB endpoint
 511  *
 512  * @v ep                USB endpoint
 513  * @v usb               USB device
 514  * @v driver            Driver operations
 515  */
 516 static inline __attribute__ (( always_inline )) void
 517 usb_endpoint_init ( struct usb_endpoint *ep, struct usb_device *usb,
 518                     struct usb_endpoint_driver_operations *driver ) {
 519
 520         ep->usb = usb;
 521         ep->driver = driver;
 522 }
 523
 524 /**
 525  * Describe USB endpoint
 526  *
 527  * @v ep                USB endpoint
 528  * @v address           Endpoint address
 529  * @v attributes        Attributes
 530  * @v mtu               Maximum packet size
 531  * @v burst             Maximum burst size
 532  * @v interval          Interval (in microframes)
 533  */
 534 static inline __attribute__ (( always_inline )) void
 535 usb_endpoint_describe ( struct usb_endpoint *ep, unsigned int address,
 536                         unsigned int attributes, size_t mtu,
 537                         unsigned int burst, unsigned int interval ) {
 538
 539         ep->address = address;
 540         ep->attributes = attributes;
 541         ep->mtu = mtu;
 542         ep->burst = burst;
 543         ep->interval = interval;
 544 }
 545
 546 /**
 547  * Set USB endpoint host controller private data
 548  *
 549  * @v ep                USB endpoint
 550  * @v priv              Host controller private data
 551  */
 552 static inline __attribute__ (( always_inline )) void
 553 usb_endpoint_set_hostdata ( struct usb_endpoint *ep, void *priv ) {
 554         ep->priv = priv;
 555 }
 556
 557 /**
 558  * Get USB endpoint host controller private data
 559  *
 560  * @v ep                USB endpoint
 561  * @ret priv            Host controller private data
 562  */
 563 static inline __attribute__ (( always_inline )) void *
 564 usb_endpoint_get_hostdata ( struct usb_endpoint *ep ) {
 565         return ep->priv;
 566 }
 567
 568 extern const char * usb_endpoint_name ( struct usb_endpoint *ep );
 569 extern int
 570 usb_endpoint_described ( struct usb_endpoint *ep,
 571                          struct usb_configuration_descriptor *config,
 572                          struct usb_interface_descriptor *interface,
 573                          unsigned int type, unsigned int index );
 574 extern int usb_endpoint_open ( struct usb_endpoint *ep );
 575 extern void usb_endpoint_close ( struct usb_endpoint *ep );
 576 extern int usb_message ( struct usb_endpoint *ep, unsigned int request,
 577                          unsigned int value, unsigned int index,
 578                          struct io_buffer *iobuf );
 579 extern int usb_stream ( struct usb_endpoint *ep, struct io_buffer *iobuf,
 580                         int terminate );
 581 extern void usb_complete_err ( struct usb_endpoint *ep,
 582                                struct io_buffer *iobuf, int rc );
 583
 584 /**
 585  * Initialise USB endpoint refill
 586  *
 587  * @v ep                USB endpoint
 588  * @v len               Refill buffer length (or zero to use endpoint's MTU)
 589  * @v max               Maximum fill level
 590  */
 591 static inline __attribute__ (( always_inline )) void
 592 usb_refill_init ( struct usb_endpoint *ep, size_t len, unsigned int max ) {
 593
 594         INIT_LIST_HEAD ( &ep->recycled );
 595         ep->len = len;
 596         ep->max = max;
 597 }
 598
 599 /**
 600  * Recycle I/O buffer
 601  *
 602  * @v ep                USB endpoint
 603  * @v iobuf             I/O buffer
 604  */
 605 static inline __attribute__ (( always_inline )) void
 606 usb_recycle ( struct usb_endpoint *ep, struct io_buffer *iobuf ) {
 607
 608         list_add_tail ( &iobuf->list, &ep->recycled );
 609 }
 610
 611 extern int usb_prefill ( struct usb_endpoint *ep );
 612 extern int usb_refill ( struct usb_endpoint *ep );
 613 extern void usb_flush ( struct usb_endpoint *ep );
 614
 615 /**
 616  * A USB function
 617  *
 618  * A USB function represents an association of interfaces within a USB
 619  * device.
 620  */
 621 struct usb_function {
 622         /** Name */
 623         const char *name;
 624         /** USB device */
 625         struct usb_device *usb;
 626         /** Class */
 627         struct usb_class class;
 628         /** Number of interfaces */
 629         unsigned int count;
 630         /** Generic device */
 631         struct device dev;
 632         /** List of functions within this USB device */
 633         struct list_head list;
 634
 635         /** Driver */
 636         struct usb_driver *driver;
 637         /** Driver private data */
 638         void *priv;
 639
 640         /** List of interface numbers
 641          *
 642          * This must be the last field within the structure.
 643          */
 644         uint8_t interface[0];
 645 };
 646
 647 /**
 648  * Set USB function driver private data
 649  *
 650  * @v func              USB function
 651  * @v priv              Driver private data
 652  */
 653 static inline __attribute__ (( always_inline )) void
 654 usb_func_set_drvdata ( struct usb_function *func, void *priv ) {
 655         func->priv = priv;
 656 }
 657
 658 /**
 659  * Get USB function driver private data
 660  *
 661  * @v function          USB function
 662  * @ret priv            Driver private data
 663  */
 664 static inline __attribute__ (( always_inline )) void *
 665 usb_func_get_drvdata ( struct usb_function *func ) {
 666         return func->priv;
 667 }
 668
 669 /** A USB device */
 670 struct usb_device {
 671         /** Name */
 672         char name[32];
 673         /** USB port */
 674         struct usb_port *port;
 675         /** List of devices on this bus */
 676         struct list_head list;
 677         /** Device address, if assigned */
 678         unsigned int address;
 679         /** Device descriptor */
 680         struct usb_device_descriptor device;
 681         /** List of functions */
 682         struct list_head functions;
 683
 684         /** Host controller operations */
 685         struct usb_device_host_operations *host;
 686         /** Host controller private data */
 687         void *priv;
 688
 689         /** Endpoint list */
 690         struct usb_endpoint *ep[32];
 691
 692         /** Control endpoint */
 693         struct usb_endpoint control;
 694         /** Completed control transfers */
 695         struct list_head complete;
 696 };
 697
 698 /** USB device host controller operations */
 699 struct usb_device_host_operations {
 700         /** Open device
 701          *
 702          * @v usb               USB device
 703          * @ret rc              Return status code
 704          */
 705         int ( * open ) ( struct usb_device *usb );
 706         /** Close device
 707          *
 708          * @v usb               USB device
 709          */
 710         void ( * close ) ( struct usb_device *usb );
 711         /** Assign device address
 712          *
 713          * @v usb               USB device
 714          * @ret rc              Return status code
 715          */
 716         int ( * address ) ( struct usb_device *usb );
 717 };
 718
 719 /**
 720  * Set USB device host controller private data
 721  *
 722  * @v usb               USB device
 723  * @v priv              Host controller private data
 724  */
 725 static inline __attribute__ (( always_inline )) void
 726 usb_set_hostdata ( struct usb_device *usb, void *priv ) {
 727         usb->priv = priv;
 728 }
 729
 730 /**
 731  * Get USB device host controller private data
 732  *
 733  * @v usb               USB device
 734  * @ret priv            Host controller private data
 735  */
 736 static inline __attribute__ (( always_inline )) void *
 737 usb_get_hostdata ( struct usb_device *usb ) {
 738         return usb->priv;
 739 }
 740
 741 /**
 742  * Get USB endpoint
 743  *
 744  * @v usb               USB device
 745  * @v address           Endpoint address
 746  * @ret ep              USB endpoint, or NULL if not opened
 747  */
 748 static inline struct usb_endpoint * usb_endpoint ( struct usb_device *usb,
 749                                                    unsigned int address ) {
 750
 751         return usb->ep[ USB_ENDPOINT_IDX ( address ) ];
 752 }
 753
 754 /** A USB port */
 755 struct usb_port {
 756         /** USB hub */
 757         struct usb_hub *hub;
 758         /** Port address */
 759         unsigned int address;
 760         /** Port protocol */
 761         unsigned int protocol;
 762         /** Port speed */
 763         unsigned int speed;
 764         /** Port disconnection has been detected
 765          *
 766          * This should be set whenever the underlying hardware reports
 767          * a connection status change.
 768          */
 769         int disconnected;
 770         /** Port has an attached device */
 771         int attached;
 772         /** Currently attached device (if in use)
 773          *
 774          * Note that this field will be NULL if the attached device
 775          * has been freed (e.g. because there were no drivers found).
 776          */
 777         struct usb_device *usb;
 778         /** List of changed ports */
 779         struct list_head changed;
 780 };
 781
 782 /** A USB hub */
 783 struct usb_hub {
 784         /** Name */
 785         const char *name;
 786         /** USB bus */
 787         struct usb_bus *bus;
 788         /** Underlying USB device, if any */
 789         struct usb_device *usb;
 790         /** Hub protocol */
 791         unsigned int protocol;
 792         /** Number of ports */
 793         unsigned int ports;
 794
 795         /** List of hubs */
 796         struct list_head list;
 797
 798         /** Host controller operations */
 799         struct usb_hub_host_operations *host;
 800         /** Driver operations */
 801         struct usb_hub_driver_operations *driver;
 802         /** Driver private data */
 803         void *priv;
 804
 805         /** Port list
 806          *
 807          * This must be the last field within the structure.
 808          */
 809         struct usb_port port[0];
 810 };
 811
 812 /** USB hub host controller operations */
 813 struct usb_hub_host_operations {
 814         /** Open hub
 815          *
 816          * @v hub               USB hub
 817          * @ret rc              Return status code
 818          */
 819         int ( * open ) ( struct usb_hub *hub );
 820         /** Close hub
 821          *
 822          * @v hub               USB hub
 823          */
 824         void ( * close ) ( struct usb_hub *hub );
 825 };
 826
 827 /** USB hub driver operations */
 828 struct usb_hub_driver_operations {
 829         /** Open hub
 830          *
 831          * @v hub               USB hub
 832          * @ret rc              Return status code
 833          */
 834         int ( * open ) ( struct usb_hub *hub );
 835         /** Close hub
 836          *
 837          * @v hub               USB hub
 838          */
 839         void ( * close ) ( struct usb_hub *hub );
 840         /** Enable port
 841          *
 842          * @v hub               USB hub
 843          * @v port              USB port
 844          * @ret rc              Return status code
 845          */
 846         int ( * enable ) ( struct usb_hub *hub, struct usb_port *port );
 847         /** Disable port
 848          *
 849          * @v hub               USB hub
 850          * @v port              USB port
 851          * @ret rc              Return status code
 852          */
 853         int ( * disable ) ( struct usb_hub *hub, struct usb_port *port );
 854         /** Update port speed
 855          *
 856          * @v hub               USB hub
 857          * @v port              USB port
 858          * @ret rc              Return status code
 859          */
 860         int ( * speed ) ( struct usb_hub *hub, struct usb_port *port );
 861         /** Clear transaction translator buffer
 862          *
 863          * @v hub               USB hub
 864          * @v port              USB port
 865          * @v ep                USB endpoint
 866          * @ret rc              Return status code
 867          */
 868         int ( * clear_tt ) ( struct usb_hub *hub, struct usb_port *port,
 869                              struct usb_endpoint *ep );
 870 };
 871
 872 /**
 873  * Set USB hub driver private data
 874  *
 875  * @v hub               USB hub
 876  * @v priv              Driver private data
 877  */
 878 static inline __attribute__ (( always_inline )) void
 879 usb_hub_set_drvdata ( struct usb_hub *hub, void *priv ) {
 880         hub->priv = priv;
 881 }
 882
 883 /**
 884  * Get USB hub driver private data
 885  *
 886  * @v hub               USB hub
 887  * @ret priv            Driver private data
 888  */
 889 static inline __attribute__ (( always_inline )) void *
 890 usb_hub_get_drvdata ( struct usb_hub *hub ) {
 891         return hub->priv;
 892 }
 893
 894 /**
 895  * Get USB port
 896  *
 897  * @v hub               USB hub
 898  * @v address           Port address
 899  * @ret port            USB port
 900  */
 901 static inline __attribute__ (( always_inline )) struct usb_port *
 902 usb_port ( struct usb_hub *hub, unsigned int address ) {
 903
 904         return &hub->port[ address - 1 ];
 905 }
 906
 907 /** A USB bus */
 908 struct usb_bus {
 909         /** Name */
 910         const char *name;
 911         /** Underlying hardware device */
 912         struct device *dev;
 913         /** Host controller operations set */
 914         struct usb_host_operations *op;
 915
 916         /** Largest transfer allowed on the bus */
 917         size_t mtu;
 918         /** Address in-use mask
 919          *
 920          * This is used only by buses which perform manual address
 921          * assignment.  USB allows for addresses in the range [1,127].
 922          * We use a simple bitmask which restricts us to the range
 923          * [1,64]; this is unlikely to be a problem in practice.  For
 924          * comparison: controllers which perform autonomous address
 925          * assignment (such as xHCI) typically allow for only 32
 926          * devices per bus anyway.
 927          */
 928         unsigned long long addresses;
 929
 930         /** Root hub */
 931         struct usb_hub *hub;
 932
 933         /** List of USB buses */
 934         struct list_head list;
 935         /** List of devices */
 936         struct list_head devices;
 937         /** List of hubs */
 938         struct list_head hubs;
 939
 940         /** Host controller operations */
 941         struct usb_bus_host_operations *host;
 942         /** Host controller private data */
 943         void *priv;
 944 };
 945
 946 /** USB bus host controller operations */
 947 struct usb_bus_host_operations {
 948         /** Open bus
 949          *
 950          * @v bus               USB bus
 951          * @ret rc              Return status code
 952          */
 953         int ( * open ) ( struct usb_bus *bus );
 954         /** Close bus
 955          *
 956          * @v bus               USB bus
 957          */
 958         void ( * close ) ( struct usb_bus *bus );
 959         /** Poll bus
 960          *
 961          * @v bus               USB bus
 962          */
 963         void ( * poll ) ( struct usb_bus *bus );
 964 };
 965
 966 /** USB host controller operations */
 967 struct usb_host_operations {
 968         /** Endpoint operations */
 969         struct usb_endpoint_host_operations endpoint;
 970         /** Device operations */
 971         struct usb_device_host_operations device;
 972         /** Bus operations */
 973         struct usb_bus_host_operations bus;
 974         /** Hub operations */
 975         struct usb_hub_host_operations hub;
 976         /** Root hub operations */
 977         struct usb_hub_driver_operations root;
 978 };
 979
 980 /**
 981  * Set USB bus host controller private data
 982  *
 983  * @v bus               USB bus
 984  * @v priv              Host controller private data
 985  */
 986 static inline __attribute__ (( always_inline )) void
 987 usb_bus_set_hostdata ( struct usb_bus *bus, void *priv ) {
 988         bus->priv = priv;
 989 }
 990
 991 /**
 992  * Get USB bus host controller private data
 993  *
 994  * @v bus               USB bus
 995  * @ret priv            Host controller private data
 996  */
 997 static inline __attribute__ (( always_inline )) void *
 998 usb_bus_get_hostdata ( struct usb_bus *bus ) {
 999         return bus->priv;
1000 }
1001
1002 /**
1003  * Poll USB bus
1004  *
1005  * @v bus               USB bus
1006  */
1007 static inline __attribute__ (( always_inline )) void
1008 usb_poll ( struct usb_bus *bus ) {
1009         bus->host->poll ( bus );
1010 }
1011
1012 /** Iterate over all USB buses */
1013 #define for_each_usb_bus( bus ) \
1014         list_for_each_entry ( (bus), &usb_buses, list )
1015
1016 /**
1017  * Complete transfer (without error)
1018  *
1019  * @v ep                USB endpoint
1020  * @v iobuf             I/O buffer
1021  */
1022 static inline __attribute__ (( always_inline )) void
1023 usb_complete ( struct usb_endpoint *ep, struct io_buffer *iobuf ) {
1024         usb_complete_err ( ep, iobuf, 0 );
1025 }
1026
1027 extern int usb_control ( struct usb_device *usb, unsigned int request,
1028                          unsigned int value, unsigned int index, void *data,
1029                          size_t len );
1030 extern int usb_get_string_descriptor ( struct usb_device *usb,
1031                                        unsigned int index,
1032                                        unsigned int language,
1033                                        char *buf, size_t len );
1034
1035 /**
1036  * Get status
1037  *
1038  * @v usb               USB device
1039  * @v type              Request type
1040  * @v index             Target index
1041  * @v data              Status to fill in
1042  * @v len               Length of status descriptor
1043  * @ret rc              Return status code
1044  */
1045 static inline __attribute__ (( always_inline )) int
1046 usb_get_status ( struct usb_device *usb, unsigned int type, unsigned int index,
1047                  void *data, size_t len ) {
1048
1049         return usb_control ( usb, ( USB_GET_STATUS | type ), 0, index,
1050                              data, len );
1051 }
1052
1053 /**
1054  * Clear feature
1055  *
1056  * @v usb               USB device
1057  * @v type              Request type
1058  * @v feature           Feature selector
1059  * @v index             Target index
1060  * @ret rc              Return status code
1061  */
1062 static inline __attribute__ (( always_inline )) int
1063 usb_clear_feature ( struct usb_device *usb, unsigned int type,
1064                     unsigned int feature, unsigned int index ) {
1065
1066         return usb_control ( usb, ( USB_CLEAR_FEATURE | type ),
1067                              feature, index, NULL, 0 );
1068 }
1069
1070 /**
1071  * Set feature
1072  *
1073  * @v usb               USB device
1074  * @v type              Request type
1075  * @v feature           Feature selector
1076  * @v index             Target index
1077  * @ret rc              Return status code
1078  */
1079 static inline __attribute__ (( always_inline )) int
1080 usb_set_feature ( struct usb_device *usb, unsigned int type,
1081                   unsigned int feature, unsigned int index ) {
1082
1083         return usb_control ( usb, ( USB_SET_FEATURE | type ),
1084                              feature, index, NULL, 0 );
1085 }
1086
1087 /**
1088  * Set address
1089  *
1090  * @v usb               USB device
1091  * @v address           Device address
1092  * @ret rc              Return status code
1093  */
1094 static inline __attribute__ (( always_inline )) int
1095 usb_set_address ( struct usb_device *usb, unsigned int address ) {
1096
1097         return usb_control ( usb, USB_SET_ADDRESS, address, 0, NULL, 0 );
1098 }
1099
1100 /**
1101  * Get USB descriptor
1102  *
1103  * @v usb               USB device
1104  * @v type              Request type
1105  * @v desc              Descriptor type
1106  * @v index             Descriptor index
1107  * @v language          Language ID (for string descriptors)
1108  * @v data              Descriptor to fill in
1109  * @v len               Maximum length of descriptor
1110  * @ret rc              Return status code
1111  */
1112 static inline __attribute__ (( always_inline )) int
1113 usb_get_descriptor ( struct usb_device *usb, unsigned int type,
1114                      unsigned int desc, unsigned int index,
1115                      unsigned int language, struct usb_descriptor_header *data,
1116                      size_t len ) {
1117
1118         return usb_control ( usb, ( USB_GET_DESCRIPTOR | type ),
1119                              ( ( desc << 8 ) | index ), language, data, len );
1120 }
1121
1122 /**
1123  * Get first part of USB device descriptor (up to and including MTU)
1124  *
1125  * @v usb               USB device
1126  * @v data              Device descriptor to (partially) fill in
1127  * @ret rc              Return status code
1128  */
1129 static inline __attribute__ (( always_inline )) int
1130 usb_get_mtu ( struct usb_device *usb, struct usb_device_descriptor *data ) {
1131
1132         return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
1133                                     &data->header,
1134                                     ( offsetof ( typeof ( *data ), mtu ) +
1135                                       sizeof ( data->mtu ) ) );
1136 }
1137
1138 /**
1139  * Get USB device descriptor
1140  *
1141  * @v usb               USB device
1142  * @v data              Device descriptor to fill in
1143  * @ret rc              Return status code
1144  */
1145 static inline __attribute__ (( always_inline )) int
1146 usb_get_device_descriptor ( struct usb_device *usb,
1147                             struct usb_device_descriptor *data ) {
1148
1149         return usb_get_descriptor ( usb, 0, USB_DEVICE_DESCRIPTOR, 0, 0,
1150                                     &data->header, sizeof ( *data ) );
1151 }
1152
1153 /**
1154  * Get USB configuration descriptor
1155  *
1156  * @v usb               USB device
1157  * @v index             Configuration index
1158  * @v data              Configuration descriptor to fill in
1159  * @ret rc              Return status code
1160  */
1161 static inline __attribute (( always_inline )) int
1162 usb_get_config_descriptor ( struct usb_device *usb, unsigned int index,
1163                             struct usb_configuration_descriptor *data,
1164                             size_t len ) {
1165
1166         return usb_get_descriptor ( usb, 0, USB_CONFIGURATION_DESCRIPTOR, index,
1167                                     0, &data->header, len );
1168 }
1169
1170 /**
1171  * Set USB configuration
1172  *
1173  * @v usb               USB device
1174  * @v index             Configuration index
1175  * @ret rc              Return status code
1176  */
1177 static inline __attribute__ (( always_inline )) int
1178 usb_set_configuration ( struct usb_device *usb, unsigned int index ) {
1179
1180         return usb_control ( usb, USB_SET_CONFIGURATION, index, 0, NULL, 0 );
1181 }
1182
1183 /**
1184  * Set USB interface alternate setting
1185  *
1186  * @v usb               USB device
1187  * @v interface         Interface number
1188  * @v alternate         Alternate setting
1189  * @ret rc              Return status code
1190  */
1191 static inline __attribute__ (( always_inline )) int
1192 usb_set_interface ( struct usb_device *usb, unsigned int interface,
1193                     unsigned int alternate ) {
1194
1195         return usb_control ( usb, USB_SET_INTERFACE, alternate, interface,
1196                              NULL, 0 );
1197 }
1198
1199 extern struct list_head usb_buses;
1200
1201 extern struct usb_interface_descriptor *
1202 usb_interface_descriptor ( struct usb_configuration_descriptor *config,
1203                            unsigned int interface, unsigned int alternate );
1204 extern struct usb_endpoint_descriptor *
1205 usb_endpoint_descriptor ( struct usb_configuration_descriptor *config,
1206                           struct usb_interface_descriptor *interface,
1207                           unsigned int type, unsigned int index );
1208 extern struct usb_endpoint_companion_descriptor *
1209 usb_endpoint_companion_descriptor ( struct usb_configuration_descriptor *config,
1210                                     struct usb_endpoint_descriptor *desc );
1211
1212 extern struct usb_hub * alloc_usb_hub ( struct usb_bus *bus,
1213                                         struct usb_device *usb,
1214                                         unsigned int ports,
1215                                         struct usb_hub_driver_operations *op );
1216 extern int register_usb_hub ( struct usb_hub *hub );
1217 extern void unregister_usb_hub ( struct usb_hub *hub );
1218 extern void free_usb_hub ( struct usb_hub *hub );
1219
1220 extern void usb_port_changed ( struct usb_port *port );
1221
1222 extern struct usb_bus * alloc_usb_bus ( struct device *dev,
1223                                         unsigned int ports, size_t mtu,
1224                                         struct usb_host_operations *op );
1225 extern int register_usb_bus ( struct usb_bus *bus );
1226 extern void unregister_usb_bus ( struct usb_bus *bus );
1227 extern void free_usb_bus ( struct usb_bus *bus );
1228 extern struct usb_bus * find_usb_bus_by_location ( unsigned int bus_type,
1229                                                    unsigned int location );
1230
1231 extern int usb_alloc_address ( struct usb_bus *bus );
1232 extern void usb_free_address ( struct usb_bus *bus, unsigned int address );
1233 extern unsigned int usb_route_string ( struct usb_device *usb );
1234 extern unsigned int usb_depth ( struct usb_device *usb );
1235 extern struct usb_port * usb_root_hub_port ( struct usb_device *usb );
1236 extern struct usb_port * usb_transaction_translator ( struct usb_device *usb );
1237
1238 /** Minimum reset time
1239  *
1240  * Section 7.1.7.5 of the USB2 specification states that root hub
1241  * ports should assert reset signalling for at least 50ms.
1242  */
1243 #define USB_RESET_DELAY_MS 50
1244
1245 /** Reset recovery time
1246  *
1247  * Section 9.2.6.2 of the USB2 specification states that the
1248  * "recovery" interval after a port reset is 10ms.
1249  */
1250 #define USB_RESET_RECOVER_DELAY_MS 10
1251
1252 /** Maximum time to wait for a control transaction to complete
1253  *
1254  * Section 9.2.6.1 of the USB2 specification states that the upper
1255  * limit for commands to be processed is 5 seconds.
1256  */
1257 #define USB_CONTROL_MAX_WAIT_MS 5000
1258
1259 /** Set address recovery time
1260  *
1261  * Section 9.2.6.3 of the USB2 specification states that devices are
1262  * allowed a 2ms recovery interval after receiving a new address.
1263  */
1264 #define USB_SET_ADDRESS_RECOVER_DELAY_MS 2
1265
1266 /** Time to wait for ports to stabilise
1267  *
1268  * Section 7.1.7.3 of the USB specification states that we must allow
1269  * 100ms for devices to signal attachment, and an additional 100ms for
1270  * connection debouncing.  (This delay is parallelised across all
1271  * ports on a hub; we do not delay separately for each port.)
1272  */
1273 #define USB_PORT_DELAY_MS 200
1274
1275 /** A USB device ID */
1276 struct usb_device_id {
1277         /** Name */
1278         const char *name;
1279         /** Vendor ID */
1280         uint16_t vendor;
1281         /** Product ID */
1282         uint16_t product;
1283         /** Class */
1284         struct usb_class class;
1285 };
1286
1287 /** Match-anything ID */
1288 #define USB_ANY_ID 0xffff
1289
1290 /** A USB driver */
1291 struct usb_driver {
1292         /** USB ID table */
1293         struct usb_device_id *ids;
1294         /** Number of entries in ID table */
1295         unsigned int id_count;
1296         /**
1297          * Probe device
1298          *
1299          * @v func              USB function
1300          * @v config            Configuration descriptor
1301          * @ret rc              Return status code
1302          */
1303         int ( * probe ) ( struct usb_function *func,
1304                           struct usb_configuration_descriptor *config );
1305         /**
1306          * Remove device
1307          *
1308          * @v func              USB function
1309          */
1310         void ( * remove ) ( struct usb_function *func );
1311 };
1312
1313 /** USB driver table */
1314 #define USB_DRIVERS __table ( struct usb_driver, "usb_drivers" )
1315
1316 /** Declare a USB driver */
1317 #define __usb_driver __table_entry ( USB_DRIVERS, 01 )
1318
1319 #endif /* _IPXE_USB_H */