include/grub/usb.h

   1 /*
   2  *  GRUB  --  GRand Unified Bootloader
   3  *  Copyright (C) 2008  Free Software Foundation, Inc.
   4  *
   5  *  GRUB is free software: you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation, either version 3 of the License, or
   8  *  (at your option) any later version.
   9  *
  10  *  GRUB is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  *  GNU General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with GRUB.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef GRUB_USB_H
  20 #define GRUB_USB_H      1
  21
  22 #include <grub/err.h>
  23 #include <grub/usbdesc.h>
  24 #include <grub/usbtrans.h>
  25
  26 typedef struct grub_usb_device *grub_usb_device_t;
  27 typedef struct grub_usb_controller *grub_usb_controller_t;
  28 typedef struct grub_usb_controller_dev *grub_usb_controller_dev_t;
  29
  30 typedef enum
  31   {
  32     GRUB_USB_ERR_NONE,
  33     GRUB_USB_ERR_WAIT,
  34     GRUB_USB_ERR_INTERNAL,
  35     GRUB_USB_ERR_STALL,
  36     GRUB_USB_ERR_DATA,
  37     GRUB_USB_ERR_NAK,
  38     GRUB_USB_ERR_BABBLE,
  39     GRUB_USB_ERR_TIMEOUT,
  40     GRUB_USB_ERR_BITSTUFF,
  41     GRUB_USB_ERR_UNRECOVERABLE,
  42     GRUB_USB_ERR_BADDEVICE
  43   } grub_usb_err_t;
  44
  45 typedef enum
  46   {
  47     GRUB_USB_SPEED_NONE,
  48     GRUB_USB_SPEED_LOW,
  49     GRUB_USB_SPEED_FULL,
  50     GRUB_USB_SPEED_HIGH
  51   } grub_usb_speed_t;
  52
  53 typedef int (*grub_usb_iterate_hook_t) (grub_usb_device_t dev, void *data);
  54 typedef int (*grub_usb_controller_iterate_hook_t) (grub_usb_controller_t dev,
  55                                                    void *data);
  56
  57 /* Call HOOK with each device, until HOOK returns non-zero.  */
  58 int grub_usb_iterate (grub_usb_iterate_hook_t hook, void *hook_data);
  59
  60 grub_usb_err_t grub_usb_device_initialize (grub_usb_device_t dev);
  61
  62 grub_usb_err_t grub_usb_get_descriptor (grub_usb_device_t dev,
  63                                         grub_uint8_t type, grub_uint8_t index,
  64                                         grub_size_t size, char *data);
  65
  66 grub_usb_err_t grub_usb_clear_halt (grub_usb_device_t dev, int endpoint);
  67
  68
  69 grub_usb_err_t grub_usb_set_configuration (grub_usb_device_t dev,
  70                                            int configuration);
  71
  72 void grub_usb_controller_dev_register (grub_usb_controller_dev_t usb);
  73
  74 void grub_usb_controller_dev_unregister (grub_usb_controller_dev_t usb);
  75
  76 int grub_usb_controller_iterate (grub_usb_controller_iterate_hook_t hook,
  77                                  void *hook_data);
  78
  79
  80 grub_usb_err_t grub_usb_control_msg (grub_usb_device_t dev, grub_uint8_t reqtype,
  81                                      grub_uint8_t request, grub_uint16_t value,
  82                                      grub_uint16_t index, grub_size_t size,
  83                                      char *data);
  84
  85 grub_usb_err_t
  86 grub_usb_bulk_read (grub_usb_device_t dev,
  87                     struct grub_usb_desc_endp *endpoint,
  88                     grub_size_t size, char *data);
  89 grub_usb_err_t
  90 grub_usb_bulk_write (grub_usb_device_t dev,
  91                      struct grub_usb_desc_endp *endpoint,
  92                      grub_size_t size, char *data);
  93
  94 grub_usb_err_t
  95 grub_usb_root_hub (grub_usb_controller_t controller);
  96
  97 \f
  98
  99 /* XXX: All handled by libusb for now.  */
 100 struct grub_usb_controller_dev
 101 {
 102   /* The device name.  */
 103   const char *name;
 104
 105   int (*iterate) (grub_usb_controller_iterate_hook_t hook, void *hook_data);
 106
 107   grub_usb_err_t (*setup_transfer) (grub_usb_controller_t dev,
 108                                     grub_usb_transfer_t transfer);
 109
 110   grub_usb_err_t (*check_transfer) (grub_usb_controller_t dev,
 111                                     grub_usb_transfer_t transfer,
 112                                     grub_size_t *actual);
 113
 114   grub_usb_err_t (*cancel_transfer) (grub_usb_controller_t dev,
 115                                      grub_usb_transfer_t transfer);
 116
 117   int (*hubports) (grub_usb_controller_t dev);
 118
 119   grub_usb_err_t (*portstatus) (grub_usb_controller_t dev, unsigned int port,
 120                                 unsigned int enable);
 121
 122   grub_usb_speed_t (*detect_dev) (grub_usb_controller_t dev, int port, int *changed);
 123
 124   /* Per controller flag - port reset pending, don't do another reset */
 125   grub_uint64_t pending_reset;
 126
 127   /* Max. number of transfer descriptors used per one bulk transfer */
 128   /* The reason is to prevent "exhausting" of TD by large bulk */
 129   /* transfer - number of TD is limited in USB host driver */
 130   /* Value is calculated/estimated in driver - some TDs should be */
 131   /* reserved for posible concurrent control or "interrupt" transfers */
 132   grub_size_t max_bulk_tds;
 133
 134   /* The next host controller.  */
 135   struct grub_usb_controller_dev *next;
 136 };
 137
 138 struct grub_usb_controller
 139 {
 140   /* The underlying USB Host Controller device.  */
 141   grub_usb_controller_dev_t dev;
 142
 143   /* Data used by the USB Host Controller Driver.  */
 144   void *data;
 145 };
 146 \f
 147
 148 struct grub_usb_interface
 149 {
 150   struct grub_usb_desc_if *descif;
 151
 152   struct grub_usb_desc_endp *descendp;
 153
 154   /* A driver is handling this interface. Do we need to support multiple drivers
 155      for single interface?
 156    */
 157   int attached;
 158
 159   void (*detach_hook) (struct grub_usb_device *dev, int config, int interface);
 160
 161   void *detach_data;
 162 };
 163
 164 struct grub_usb_configuration
 165 {
 166   /* Configuration descriptors .  */
 167   struct grub_usb_desc_config *descconf;
 168
 169   /* Interfaces associated to this configuration.  */
 170   struct grub_usb_interface interf[32];
 171 };
 172
 173 struct grub_usb_hub_port
 174 {
 175   grub_uint64_t soft_limit_time;
 176   grub_uint64_t hard_limit_time;
 177   enum {
 178     PORT_STATE_NORMAL = 0,
 179     PORT_STATE_WAITING_FOR_STABLE_POWER = 1,
 180     PORT_STATE_FAILED_DEVICE = 2,
 181     PORT_STATE_STABLE_POWER = 3,
 182   } state;
 183 };
 184
 185 struct grub_usb_device
 186 {
 187   /* The device descriptor of this device.  */
 188   struct grub_usb_desc_device descdev;
 189
 190   /* The controller the device is connected to.  */
 191   struct grub_usb_controller controller;
 192
 193   /* Device configurations (after opening the device).  */
 194   struct grub_usb_configuration config[8];
 195
 196   /* Device address.  */
 197   int addr;
 198
 199   /* Device speed.  */
 200   grub_usb_speed_t speed;
 201
 202   /* All descriptors are read if this is set to 1.  */
 203   int initialized;
 204
 205   /* Data toggle values (used for bulk transfers only).  */
 206   int toggle[256];
 207
 208   /* Used by libusb wrapper.  Schedulded for removal. */
 209   void *data;
 210
 211   /* Hub information.  */
 212
 213   /* Array of children for a hub.  */
 214   grub_usb_device_t *children;
 215
 216   /* Number of hub ports.  */
 217   unsigned nports;
 218
 219   struct grub_usb_hub_port *ports;
 220
 221   grub_usb_transfer_t hub_transfer;
 222
 223   grub_uint32_t statuschange;
 224
 225   struct grub_usb_desc_endp *hub_endpoint;
 226
 227   /* EHCI Split Transfer information */
 228   int split_hubport;
 229
 230   int split_hubaddr;
 231 };
 232
 233 \f
 234
 235 typedef enum grub_usb_ep_type
 236   {
 237     GRUB_USB_EP_CONTROL,
 238     GRUB_USB_EP_ISOCHRONOUS,
 239     GRUB_USB_EP_BULK,
 240     GRUB_USB_EP_INTERRUPT
 241   } grub_usb_ep_type_t;
 242
 243 static inline enum grub_usb_ep_type
 244 grub_usb_get_ep_type (struct grub_usb_desc_endp *ep)
 245 {
 246   return ep->attrib & 3;
 247 }
 248
 249 typedef enum
 250   {
 251     GRUB_USB_CLASS_NOTHERE,
 252     GRUB_USB_CLASS_AUDIO,
 253     GRUB_USB_CLASS_COMMUNICATION,
 254     GRUB_USB_CLASS_HID,
 255     GRUB_USB_CLASS_XXX,
 256     GRUB_USB_CLASS_PHYSICAL,
 257     GRUB_USB_CLASS_IMAGE,
 258     GRUB_USB_CLASS_PRINTER,
 259     GRUB_USB_CLASS_MASS_STORAGE,
 260     GRUB_USB_CLASS_HUB,
 261     GRUB_USB_CLASS_DATA_INTERFACE,
 262     GRUB_USB_CLASS_SMART_CARD,
 263     GRUB_USB_CLASS_CONTENT_SECURITY,
 264     GRUB_USB_CLASS_VIDEO
 265   } grub_usb_classes_t;
 266
 267 typedef enum
 268   {
 269     GRUB_USBMS_SUBCLASS_BULK = 0x06,
 270         /* Experimental support for non-pure SCSI devices */
 271     GRUB_USBMS_SUBCLASS_RBC = 0x01,
 272     GRUB_USBMS_SUBCLASS_MMC2 = 0x02,
 273     GRUB_USBMS_SUBCLASS_UFI = 0x04,
 274     GRUB_USBMS_SUBCLASS_SFF8070 = 0x05
 275   } grub_usbms_subclass_t;
 276
 277 typedef enum
 278   {
 279     GRUB_USBMS_PROTOCOL_BULK = 0x50,
 280     /* Experimental support for Control/Bulk/Interrupt (CBI) devices */
 281     GRUB_USBMS_PROTOCOL_CBI = 0x00, /* CBI with interrupt */
 282     GRUB_USBMS_PROTOCOL_CB = 0x01  /* CBI wthout interrupt */
 283   } grub_usbms_protocol_t;
 284
 285 static inline struct grub_usb_desc_if *
 286 grub_usb_get_config_interface (struct grub_usb_desc_config *config)
 287 {
 288   struct grub_usb_desc_if *interf;
 289
 290   interf = (struct grub_usb_desc_if *) (sizeof (*config) + (char *) config);
 291   return interf;
 292 }
 293
 294 typedef int (*grub_usb_attach_hook_class) (grub_usb_device_t usbdev,
 295                                            int configno, int interfno);
 296
 297 struct grub_usb_attach_desc
 298 {
 299   struct grub_usb_attach_desc *next;
 300   struct grub_usb_attach_desc **prev;
 301   int class;
 302   grub_usb_attach_hook_class hook;
 303 };
 304
 305 void grub_usb_register_attach_hook_class (struct grub_usb_attach_desc *desc);
 306 void grub_usb_unregister_attach_hook_class (struct grub_usb_attach_desc *desc);
 307
 308 void grub_usb_poll_devices (int wait_for_completion);
 309
 310 void grub_usb_device_attach (grub_usb_device_t dev);
 311 grub_usb_err_t
 312 grub_usb_bulk_read_extended (grub_usb_device_t dev,
 313                              struct grub_usb_desc_endp *endpoint,
 314                              grub_size_t size, char *data,
 315                              int timeout, grub_size_t *actual);
 316 grub_usb_transfer_t
 317 grub_usb_bulk_read_background (grub_usb_device_t dev,
 318                                struct grub_usb_desc_endp *endpoint,
 319                                grub_size_t size, void *data);
 320 grub_usb_err_t
 321 grub_usb_check_transfer (grub_usb_transfer_t trans, grub_size_t *actual);
 322 void
 323 grub_usb_cancel_transfer (grub_usb_transfer_t trans);
 324
 325 #endif /* GRUB_USB_H */