usb_hcd.h 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129
  1. /* USB host controller driver (HCD) interface.
  2. *
  3. * usb.c drives enumeration, bus scans and the transfer consumers (USB mouse
  4. * + keyboard, USB Ethernet) through this vtable; uhci.c/ohci.c/ehci.c/xhci.c
  5. * each implement it for their controller type. One "controller instance" is
  6. * one PCI function (MCP79 exposes four OHCI ones, for example). A machine
  7. * with EHCI and UHCI/OHCI companions drives all of them: high-speed devices
  8. * enumerate on EHCI, the rest on the companions. */
  9. #ifndef USB_HCD_H
  10. #define USB_HCD_H
  11. #define USB_HCD_MAX_CTRL 4
  12. /* Interrupt-IN endpoints serviced concurrently; usbhid manages which
  13. slot carries which device (mice + keyboards, composite devices). */
  14. #define USB_HCD_INT_SLOTS 6
  15. /* One interface of one device, filled in during a scan and passed to the
  16. * scan probe. ep_addr is 0 when the interface has no interrupt-IN endpoint. */
  17. struct usb_iface_info {
  18. unsigned int ctrl; /* controller instance index */
  19. unsigned int addr; /* device address on that controller's bus */
  20. unsigned int mps; /* device EP0 max packet size */
  21. int low_speed;
  22. unsigned int port; /* root port the device hangs off (0xFF: behind a hub) */
  23. unsigned int route; /* xHCI route string (0 = directly on the root port) */
  24. unsigned int vendor, product;
  25. unsigned int cls, subcls, proto; /* interface class/subclass/protocol */
  26. unsigned int iface_num;
  27. unsigned int config_value;
  28. unsigned int ep_addr; /* endpoint address byte (0x81 = EP1 IN) */
  29. unsigned int ep_mps;
  30. unsigned int ep_interval;
  31. };
  32. /* Called once per interface during a scan; return 1 when claimed. */
  33. typedef int (*usb_probe_fn)(const struct usb_iface_info *info);
  34. struct usb_hcd_ops {
  35. const char *name;
  36. /* Find + reset the controller(s). Returns the number of instances
  37. * found (0 = none). Idempotent: only brings hardware up on the
  38. * first successful call. */
  39. int (*init)(void);
  40. unsigned int (*count)(void);
  41. /* PCI location and register base of one instance (for the `lsusb`
  42. * header). *mmio is 1 for a memory-mapped register block. */
  43. void (*info)(unsigned int ctrl, unsigned int *bus, unsigned int *dev,
  44. unsigned int *func, unsigned int *base, int *mmio);
  45. /* Control transfer on endpoint 0. Returns bytes transferred
  46. * (>= 0) or -1. mps = EP0 max packet size (used to split the data
  47. * stage). dir_in: 1 = IN data stage, 0 = OUT or no data stage. */
  48. int (*control_transfer)(unsigned int ctrl, unsigned int addr,
  49. unsigned int mps, int low_speed,
  50. const unsigned char *setup, unsigned char *data,
  51. unsigned int len, int dir_in);
  52. /* Root hub ports of one instance. Port numbers are 0-based. */
  53. unsigned int (*port_count)(unsigned int ctrl);
  54. int (*port_connected)(unsigned int ctrl, unsigned int port);
  55. int (*port_low_speed)(unsigned int ctrl, unsigned int port);
  56. int (*port_reset)(unsigned int ctrl, unsigned int port);
  57. /* Returns 1 (and clears the hardware latch) when a connection change
  58. * was detected since the last call. */
  59. int (*port_take_change)(unsigned int ctrl, unsigned int port);
  60. /* Interrupt-IN endpoints (one slot per HID device; see
  61. * USB_HCD_INT_SLOTS). The transfer stays armed in the schedule;
  62. * the controller retries NAKs itself. poll: > 0 report bytes
  63. * (auto re-armed), 0 nothing yet, -1 error (still armed, toggle
  64. * preserved; the caller may count errors and re-init). mps is the
  65. * endpoint's wMaxPacketSize; len is the report buffer size (up to
  66. * USB_INT_MAX, so multi-packet HID reports fit). */
  67. #define USB_INT_MAX 32
  68. int (*int_in_start)(unsigned int ctrl, unsigned int slot,
  69. unsigned int addr, unsigned int ep,
  70. unsigned int mps, unsigned int len, int low_speed);
  71. int (*int_in_poll)(unsigned int slot, unsigned char *buf,
  72. unsigned int len);
  73. void (*int_in_stop)(unsigned int slot);
  74. /* Bulk transfers (USB Ethernet / mass storage). bulk_in is
  75. * start-or-poll: the first call arms the transfer and returns 0;
  76. * later calls return the completed length, 0 while it is still in
  77. * progress, or -1. The transfer is armed with exactly that call's
  78. * length, so a device that ends an exact multiple of the max packet
  79. * size without a zero-length packet still completes; the next call
  80. * after a completion arms a new transfer with its own length. The
  81. * delivered chunk is copied into the caller's buffer before the
  82. * return. May be NULL. */
  83. int (*bulk_out)(unsigned int ctrl, unsigned int addr,
  84. unsigned int ep, unsigned int mps,
  85. const unsigned char *buf, unsigned int len);
  86. int (*bulk_in)(unsigned int ctrl, unsigned int addr,
  87. unsigned int ep, unsigned int mps,
  88. unsigned char *buf, unsigned int len);
  89. /* Abort a bulk transfer and reset the host-side endpoint state
  90. * (data toggle, armed qTD/ring), so the next bulk_in/out starts
  91. * clean after a timeout or a BOT reset. May be NULL. */
  92. void (*bulk_reset)(unsigned int ctrl, unsigned int addr,
  93. unsigned int ep, int dir_in);
  94. /* Optional: print raw root-port status during `lsusb` (print mode
  95. * only). Used by EHCI to show PORTSC while debugging routing. */
  96. void (*print_ports)(unsigned int ctrl);
  97. /* Optional: record the root port, route string, parent hub address
  98. * and device speed for the next address assignment. xHCI needs the
  99. * route string to reach a device behind a hub, the parent hub's slot
  100. * id as the TT hub for a low/full-speed device, and the device's own
  101. * speed (the root port runs at the hub's upstream speed). speed_hint
  102. * is 0 for a root-port device (use the port speed), 1 low, 2 full,
  103. * 3 high; USB2 HCDs ignore it. parent_addr is 0 for a root-port
  104. * device. */
  105. void (*set_route)(unsigned int ctrl, unsigned int port,
  106. unsigned int route, unsigned int parent_addr,
  107. unsigned int speed_hint);
  108. };
  109. extern const struct usb_hcd_ops usb_uhci_ops;
  110. extern const struct usb_hcd_ops usb_ohci_ops;
  111. extern const struct usb_hcd_ops usb_ehci_ops;
  112. extern const struct usb_hcd_ops usb_xhci_ops;
  113. #endif