drivers/usb/nt4compat/usbdriver/usb.h

   1 #ifndef __USBD_H__
   2 #define __USBD_H__
   3 /*
   4  * Some USB bandwidth allocation constants.
   5  */
   6
   7 typedef unsigned long ULONG_PTR, *PULONG_PTR;
   8
   9 #define USB2_HOST_DELAY 5                       /* nsec, guess */
  10 #define BW_HOST_DELAY   1000L           /* nanoseconds */
  11 #define BW_HUB_LS_SETUP 333L            /* nanoseconds */
  12                         /* 4 full-speed bit times (est.) */
  13
  14 #define FRAME_TIME_BITS         12000L          /* frame = 1 millisecond */
  15 #define FRAME_TIME_MAX_BITS_ALLOC       (90L * FRAME_TIME_BITS / 100L)
  16 #define FRAME_TIME_USECS        1000L
  17 #define FRAME_TIME_MAX_USECS_ALLOC      (90L * FRAME_TIME_USECS / 100L)
  18
  19 #define bit_time(bytecount)  (7 * 8 * bytecount / 6)  /* with integer truncation */
  20                 /* Trying not to use worst-case bit-stuffing
  21                    of (7/6 * 8 * bytecount) = 9.33 * bytecount */
  22                 /* bytecount = data payload byte count */
  23
  24 #define ns_to_us(ns)    ((ns + 500L) / 1000L)
  25                         /* convert & round nanoseconds to microseconds */
  26
  27 #define usb_make_handle( dev_Id, if_iDx, endp_iDx) \
  28 ( ( DEV_HANDLE )( ( ( ( ( ULONG )dev_Id ) << 16 ) | ( ( ( ULONG )if_iDx ) << 8 ) ) | ( ( ULONG ) endp_iDx ) ) )
  29
  30 #define usb_make_ref( poinTER ) \
  31 ( poinTER ^ 0xffffffff )
  32
  33 #define ptr_from_ref uhci_make_ref
  34
  35 #define dev_id_from_handle( hanDLE ) ( ( ( ULONG ) ( hanDLE ) ) >> 16 )
  36 #define if_idx_from_handle( hanDLE ) ( ( ( ( ULONG ) ( hanDLE ) ) << 16 ) >> 24 )
  37 #define endp_idx_from_handle( hanDLE ) ( ( ( ULONG ) ( hanDLE ) ) & 0xff )
  38
  39 #define endp_from_handle( pDEV, hanDLE, peNDP ) \
  40 {\
  41     LONG if_idx, endp_idx;\
  42         BOOLEAN def_endp; \
  43     endp_idx = endp_idx_from_handle( hanDLE );\
  44     if_idx = if_idx_from_handle( hanDLE );\
  45     def_endp = ( ( hanDLE & 0xffff ) == 0xffff ); \
  46         if( def_endp ) \
  47                 peNDP = &pdev->default_endp; \
  48         else \
  49         { \
  50                 if( if_idx >= pdev->usb_config->if_count ) \
  51                         peNDP = NULL; \
  52                 else if( endp_idx >= pdev->usb_config->interf[ if_idx ].endp_count ) \
  53                         peNDP = NULL; \
  54                 else \
  55                         peNDP = &( pDEV )->usb_config->interf[ if_idx ].endp[ endp_idx ]; \
  56         } \
  57 }
  58
  59 #define endp_type( enDP ) \
  60 ( ( enDP->flags & USB_ENDP_FLAG_DEFAULT_ENDP ) \
  61   ? USB_ENDPOINT_XFER_CONTROL\
  62   : ( ( enDP )->pusb_endp_desc->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK ) )
  63
  64
  65 //init work data for urb
  66 #define urb_init( uRb ) \
  67 {\
  68         RtlZeroMemory( ( uRb ), sizeof( URB ) ); \
  69         InitializeListHead( &( uRb )->trasac_list ); \
  70 }
  71
  72 #define UsbBuildInterruptOrBulkTransferRequest(uRb, \
  73                                                endp_hanDle, \
  74                                                data_Buf, \
  75                                                data_sIze, \
  76                                                                                            completIon, \
  77                                                                                            contExt, \
  78                                                                                            refereNce ) \
  79 { \
  80         urb_init( ( uRb ) );\
  81         ( uRb )->endp_handle = endp_hanDle;\
  82         ( uRb )->data_buffer = data_Buf;\
  83         ( uRb )->data_length = data_sIze;\
  84         ( uRb )->completion = completIon;\
  85         ( uRb )->context = contExt; \
  86         ( uRb )->reference = refereNce; \
  87 }
  88
  89
  90
  91 #define UsbBuildGetDescriptorRequest(uRb, \
  92                                                                          endp_hAndle, \
  93                                      descriPtorType, \
  94                                      descriPtorIndex, \
  95                                      languaGeId, \
  96                                      data_bUffer, \
  97                                      data_sIze, \
  98                                                                          compleTion, \
  99                                                                          contexT, \
 100                                                                          refereNce ) \
 101 { \
 102         PUSB_CTRL_SETUP_PACKET pseTup;\
 103         pseTup = ( PUSB_CTRL_SETUP_PACKET )( uRb )->setup_packet;\
 104         urb_init( ( uRb ) );\
 105         ( uRb )->endp_handle = ( endp_hAndle );\
 106         ( uRb )->data_length = ( data_sIze ); \
 107         ( uRb )->data_buffer = ( ( PUCHAR )data_bUffer ); \
 108         ( uRb )->completion = ( compleTion );\
 109         ( uRb )->context = ( ( PVOID )contexT ); \
 110         ( uRb )->reference = ( ULONG )refereNce; \
 111         pseTup->wValue = ( ( descriPtorType ) << 8 )| ( descriPtorIndex ); \
 112         pseTup->wLength = ( data_sIze ); \
 113         pseTup->wIndex = ( languaGeId );\
 114     pseTup->bRequest = USB_REQ_GET_DESCRIPTOR;\
 115     pseTup->bmRequestType = 0x80;\
 116 }
 117
 118
 119
 120 #define UsbBuildGetStatusRequest(uRb, \
 121                                                                  endp_hanDle, \
 122                                  recipiEnt, \
 123                                  inDex, \
 124                                  transferBufFer, \
 125                                                              completIon, \
 126                                                              contExt, \
 127                                                              refereNce ) \
 128 { \
 129         PUSB_CTRL_SETUP_PACKET pseTup = ( PUSB_CTRL_SETUP_PACKET )( uRb )->setup_packet;\
 130         urb_init( ( uRb ) );\
 131         ( uRb )->endp_handle =  ( endp_hanDle ); \
 132         ( uRb )->data_buffer = ( transferBufFer ); \
 133         ( uRb )->data_length = sizeof(USHORT); \
 134     ( uRb )->compleiton = ( completIon );\
 135     ( uRb )->context = ( contExt );\
 136     ( uRb )->reference = ( refereNce );\
 137         pseTup->bmRequestType = ( 0x80 | recipiEnt );\
 138         pseTup->bRequest = USB_REQ_GET_STATUS;\
 139         pseTup->wIndex = ( index ); \
 140     pseTup->wValue = 0;\
 141         pseTup->wLength = sizeof( USHORT );\
 142 }
 143
 144
 145 #define UsbBuildFeatureRequest(uRb, \
 146                                                            endp_hanDle,\
 147                                recipiEnt, \
 148                                featureSelecTor, \
 149                                inDex, \
 150                                                            completIon, \
 151                                                            contExt, \
 152                                                            refereNce ) \
 153  { \
 154         PUSB_CTRL_SETUP_PACKET pseTup = ( PUSB_CTRL_SETUP_PACKET )( uRb )->setup_packet;\
 155         urb_init( ( uRb ) );\
 156         ( uRb )->endp_handle =  ( endp_hanDle ); \
 157         ( uRb )->data_buffer = NULL;\
 158         ( uRb )->data_length = ( 0 );\
 159         ( uRb )->completion = ( completIon );\
 160         ( uRb )->context = ( contExt ); \
 161         ( uRb )->reference = ( refereNce ); \
 162         pseTup->bmRequestType = recipiEnt; \
 163         pseTup->bRequest = USB_REQ_SET_FEATURE;\
 164         pseTup->wValue = ( featureSelecTor );\
 165         pseTup->wIndex = ( inDex );\
 166         pseTup->wLength = 0;\
 167 }
 168
 169 #define UsbBuildSelectConfigurationRequest(uRb, \
 170                                                                                    endp_hanDle,\
 171                                                                                    config_Val,\
 172                                                                                    completIon, \
 173                                                                                    contExt, \
 174                                                                                    refereNce ) \
 175  { \
 176         PUSB_CTRL_SETUP_PACKET pseTup = ( PUSB_CTRL_SETUP_PACKET )( uRb )->setup_packet;\
 177         urb_init( ( uRb ) );\
 178         ( uRb )->endp_handle =  ( endp_hanDle ); \
 179         ( uRb )->data_buffer = NULL;\
 180         ( uRb )->data_length = 0;\
 181         ( uRb )->completion = ( completIon );\
 182         ( uRb )->context = ( contExt ); \
 183         ( uRb )->reference = ( refereNce ); \
 184         pseTup->bmRequestType = 0;\
 185         pseTup->bRequest = USB_REQ_SET_CONFIGURATION;\
 186         pseTup->wValue = ( config_Val );\
 187         pseTup->wIndex = 0;\
 188         pseTup->wLength = 0;\
 189 }
 190
 191 #define UsbBuildSelectInterfaceRequest(uRb, \
 192                                                                    endp_hanDle,\
 193                                        if_Num, \
 194                                        alt_Num,\
 195                                                                            completIon, \
 196                                                                            contExt, \
 197                                                                            refereNce ) \
 198  { \
 199         PUSB_CTRL_SETUP_PACKET pseTup = ( PUSB_CTRL_SETUP_PACKET )( uRb )->setup_packet;\
 200         urb_init( ( uRb ) );\
 201         ( uRb )->endp_handle =  ( endp_hanDle ); \
 202         ( uRb )->data_buffer = NULL;\
 203         ( uRb )->data_length = 0;\
 204         ( uRb )->completion = ( completIon );\
 205         ( uRb )->context = ( contExt ); \
 206         ( uRb )->reference = ( refereNce ); \
 207         pseTup->bmRequestType = 1;\
 208         pseTup->bRequest = USB_REQ_SET_INERFACE;\
 209         pseTup->wValue = ( alt_Num );\
 210         pseTup->wIndex = ( if_Num );\
 211         pseTup->wLength = 0;\
 212 }
 213
 214
 215 #define UsbBuildVendorRequest(uRb, \
 216                                                           endp_hanDle,\
 217                               data_bufFer, \
 218                               data_sIze, \
 219                               request_tYpe, \
 220                               requEst, \
 221                               vaLue, \
 222                               inDex, \
 223                                                           completIon, \
 224                                                           contExt, \
 225                                                           refereNce ) \
 226  { \
 227         PUSB_CTRL_SETUP_PACKET pseTup = ( PUSB_CTRL_SETUP_PACKET )( uRb )->setup_packet;\
 228         urb_init( ( uRb ) );\
 229         ( uRb )->endp_handle =  ( endp_hanDle ); \
 230         ( uRb )->data_buffer = data_bufFer;\
 231         ( uRb )->data_length = data_sIze;\
 232         ( uRb )->completion = ( completIon );\
 233         ( uRb )->context = ( contExt ); \
 234         ( uRb )->reference = ( refereNce ); \
 235         pseTup->bmRequestType = request_tYpe;\
 236         pseTup->bRequest = requEst;\
 237         pseTup->wValue = vaLue;\
 238         pseTup->wIndex = inDex;\
 239         pseTup->wLength = ( USHORT )data_sIze;\
 240 }
 241
 242 #define UsbBuildResetPipeRequest(uRb, \
 243                                                                  dev_hanDle, \
 244                                                                  endp_aDdr, \
 245                                                                  completIon, \
 246                                                                  contExt, \
 247                                                                  refereNce ) \
 248 {\
 249         PUSB_CTRL_SETUP_PACKET pseTup = ( PUSB_CTRL_SETUP_PACKET )( uRb )->setup_packet;\
 250         urb_init( ( uRb ) );\
 251         ( uRb )->endp_handle =  ( dev_hanDle | 0xffff ); \
 252         ( uRb )->completion = ( completIon );\
 253         ( uRb )->context = ( contExt ); \
 254         ( uRb )->reference = ( refereNce ); \
 255         pseTup->bmRequestType = 0x02;\
 256         pseTup->bRequest = USB_REQ_CLEAR_FEATURE;\
 257         pseTup->wIndex = endp_aDdr;\
 258 }
 259
 260 // Forward structs declarations
 261 struct _URB;
 262 struct _HCD;
 263 struct _USB_DEV_MANAGER;
 264 struct _USB_DEV;
 265 struct _USB_ENDPOINT;
 266 struct _USB_EVENT;
 267 struct _USB_EVENT_POOL;
 268 struct _USB_DRIVER;
 269
 270 /* USB constants */
 271
 272 #define USB_SPEED_FULL                  0x00
 273 #define USB_SPEED_LOW                   0x01
 274 #define USB_SPEED_HIGH                  0x02
 275
 276 /*
 277  * Device and/or Interface Class codes
 278  */
 279 #define USB_CLASS_PER_INTERFACE 0       /* for DeviceClass */
 280 #define USB_CLASS_AUDIO                 1
 281 #define USB_CLASS_COMM                  2
 282 #define USB_CLASS_HID                   3
 283 #define USB_CLASS_PHYSICAL              5
 284 #define USB_CLASS_PRINTER               7
 285 #define USB_CLASS_MASS_STORAGE  8
 286 #define USB_CLASS_HUB                   9
 287 #define USB_CLASS_DATA                  10
 288 #define USB_CLASS_APP_SPEC              0xfe
 289 #define USB_CLASS_VENDOR_SPEC   0xff
 290
 291 /*
 292  * USB types
 293  */
 294 #define USB_TYPE_MASK                   (0x03 << 5)
 295 #define USB_TYPE_STANDARD               (0x00 << 5)
 296 #define USB_TYPE_CLASS                  (0x01 << 5)
 297 #define USB_TYPE_VENDOR                 (0x02 << 5)
 298 #define USB_TYPE_RESERVED               (0x03 << 5)
 299
 300 /*
 301  * USB recipients
 302  */
 303 #define USB_RECIP_MASK                  0x1f
 304 #define USB_RECIP_DEVICE                0x00
 305 #define USB_RECIP_INTERFACE             0x01
 306 #define USB_RECIP_ENDPOINT              0x02
 307 #define USB_RECIP_OTHER                 0x03
 308
 309 /*
 310  * USB directions
 311  */
 312 #define USB_DIR_OUT                     0
 313 #define USB_DIR_IN                      0x80
 314
 315 /*
 316  * Descriptor types
 317  */
 318 #define USB_DT_DEVICE                   0x01
 319 #define USB_DT_CONFIG                   0x02
 320 #define USB_DT_STRING                   0x03
 321 #define USB_DT_INTERFACE                0x04
 322 #define USB_DT_ENDPOINT                 0x05
 323
 324 #define USB_DT_HID                      (USB_TYPE_CLASS | 0x01)
 325 #define USB_DT_REPORT           (USB_TYPE_CLASS | 0x02)
 326 #define USB_DT_PHYSICAL         (USB_TYPE_CLASS | 0x03)
 327 #define USB_DT_HUB                      (USB_TYPE_CLASS | 0x09)
 328
 329 /*
 330  * Descriptor sizes per descriptor type
 331  */
 332 #define USB_DT_DEVICE_SIZE              18
 333 #define USB_DT_CONFIG_SIZE              9
 334 #define USB_DT_INTERFACE_SIZE           9
 335 #define USB_DT_ENDPOINT_SIZE            7
 336 #define USB_DT_ENDPOINT_AUDIO_SIZE      9       /* Audio extension */
 337 #define USB_DT_HUB_NONVAR_SIZE          7
 338 #define USB_DT_HID_SIZE                 9
 339
 340 /*
 341  * Endpoints
 342  */
 343 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
 344 #define USB_ENDPOINT_DIR_MASK           0x80
 345
 346 #define USB_ENDPOINT_XFERTYPE_MASK      0x03    /* in bmAttributes */
 347 #define USB_ENDPOINT_XFER_CONTROL       0
 348 #define USB_ENDPOINT_XFER_ISOC          1
 349 #define USB_ENDPOINT_XFER_BULK          2
 350 #define USB_ENDPOINT_XFER_INT           3
 351
 352 /*
 353  * USB Packet IDs (PIDs)
 354  */
 355 #define USB_PID_UNDEF_0                        0xf0
 356 #define USB_PID_OUT                            0xe1
 357 #define USB_PID_ACK                            0xd2
 358 #define USB_PID_DATA0                          0xc3
 359 #define USB_PID_PING                           0xb4     /* USB 2.0 */
 360 #define USB_PID_SOF                            0xa5
 361 #define USB_PID_NYET                           0x96     /* USB 2.0 */
 362 #define USB_PID_DATA2                          0x87     /* USB 2.0 */
 363 #define USB_PID_SPLIT                          0x78     /* USB 2.0 */
 364 #define USB_PID_IN                             0x69
 365 #define USB_PID_NAK                            0x5a
 366 #define USB_PID_DATA1                          0x4b
 367 #define USB_PID_PREAMBLE                       0x3c     /* Token mode */
 368 #define USB_PID_ERR                            0x3c     /* USB 2.0: handshake mode */
 369 #define USB_PID_SETUP                          0x2d
 370 #define USB_PID_STALL                          0x1e
 371 #define USB_PID_MDATA                          0x0f     /* USB 2.0 */
 372
 373 /*
 374  * Standard requests
 375  */
 376 #define USB_REQ_GET_STATUS                      0x00
 377 #define USB_REQ_CLEAR_FEATURE           0x01
 378 #define USB_REQ_SET_FEATURE                     0x03
 379 #define USB_REQ_SET_ADDRESS                     0x05
 380 #define USB_REQ_GET_DESCRIPTOR          0x06
 381 #define USB_REQ_SET_DESCRIPTOR          0x07
 382 #define USB_REQ_GET_CONFIGURATION       0x08
 383 #define USB_REQ_SET_CONFIGURATION       0x09
 384 #define USB_REQ_GET_INTERFACE           0x0A
 385 #define USB_REQ_SET_INTERFACE           0x0B
 386 #define USB_REQ_SYNCH_FRAME                     0x0C
 387
 388 /*
 389  * HID requests
 390  */
 391 #define USB_REQ_GET_REPORT                      0x01
 392 #define USB_REQ_GET_IDLE                        0x02
 393 #define USB_REQ_GET_PROTOCOL            0x03
 394 #define USB_REQ_SET_REPORT                      0x09
 395 #define USB_REQ_SET_IDLE                        0x0A
 396 #define USB_REQ_SET_PROTOCOL            0x0B
 397
 398 // HUB request
 399 #define HUB_REQ_GET_STATE                       0x02
 400
 401 // usb2.0 hub
 402 #define HUB_REQ_CLEAR_TT_BUFFER         0x08
 403
 404
 405 typedef LONG USBD_STATUS;
 406
 407 //
 408 // USBD status codes
 409 //
 410 //  Status values are 32 bit values layed out as follows:
 411 //
 412 //   3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
 413 //   1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
 414 //  +---+---------------------------+-------------------------------+
 415 //  | S |               Status Code                                 |
 416 //  +---+---------------------------+-------------------------------+
 417 //
 418 //  where
 419 //
 420 //      S - is the state code
 421 //
 422 //          00 - completed with success
 423 //          01 - request is pending
 424 //          10 - completed with error, endpoint not stalled
 425 //          11 - completed with error, endpoint stalled
 426 //
 427 //
 428 //      Code - is the status code
 429 //
 430
 431 //
 432 // Generic test for success on any status value (non-negative numbers
 433 // indicate success).
 434 //
 435
 436 #define usb_success(Status) ((USBD_STATUS)(Status) >= 0)
 437
 438 //
 439 // Generic test for pending status value.
 440 //
 441
 442 #define usb_pending(Status) ((ULONG)(Status) >> 30 == 1)
 443
 444 //
 445 // Generic test for error on any status value.
 446 //
 447
 448 #define usb_error(Status) ((USBD_STATUS)(Status) < 0)
 449
 450 //
 451 // Generic test for stall on any status value.
 452 //
 453
 454 #define usb_halted(Status) ((ULONG)(Status) >> 30 == 3)
 455
 456 //
 457 // Macro to check the status code only
 458 //
 459
 460 #define usb_status(Status) ((ULONG)(Status) & 0x0FFFFFFFL)
 461
 462
 463 #define USB_STATUS_SUCCESS                  ((USBD_STATUS)0x00000000L)
 464 #define USB_STATUS_PENDING                  ((USBD_STATUS)0x40000000L)
 465 #define USB_STATUS_HALTED                   ((USBD_STATUS)0xC0000000L)
 466 #define USB_STATUS_ERROR                    ((USBD_STATUS)0x80000000L)
 467
 468 //
 469 // HC status codes
 470 // Note: these status codes have both the error and the stall bit set.
 471 //
 472 #define USB_STATUS_CRC                      ((USBD_STATUS)0xC0000401L)
 473 #define USB_STATUS_BTSTUFF                  ((USBD_STATUS)0xC0000402L)
 474 #define USB_STATUS_DATA_TOGGLE_MISMATCH     ((USBD_STATUS)0xC0000403L)
 475 #define USB_STATUS_STALL_PID                ((USBD_STATUS)0xC0000404L)
 476 #define USB_STATUS_DEV_NOT_RESPONDING       ((USBD_STATUS)0xC0000405L)
 477 #define USB_STATUS_PID_CHECK_FAILURE        ((USBD_STATUS)0xC0000406L)
 478 #define USB_STATUS_UNEXPECTED_PID           ((USBD_STATUS)0xC0000407L)
 479 #define USB_STATUS_DATA_OVERRUN             ((USBD_STATUS)0xC0000408L)
 480 #define USB_STATUS_DATA_UNDERRUN            ((USBD_STATUS)0xC0000409L)
 481 #define USB_STATUS_RESERVED1                ((USBD_STATUS)0xC000040AL)
 482 #define USB_STATUS_RESERVED2                ((USBD_STATUS)0xC000040BL)
 483 #define USB_STATUS_BUFFER_OVERRUN           ((USBD_STATUS)0xC000040CL)
 484 #define USB_STATUS_BUFFER_UNDERRUN          ((USBD_STATUS)0xC000040DL)
 485 #define USB_STATUS_NOT_ACCESSED             ((USBD_STATUS)0xC000040FL)
 486 #define USB_STATUS_FIFO                     ((USBD_STATUS)0xC0000410L)
 487 #define USB_STATUS_BABBLE_DETECTED                      ((USBD_STATUS)0xC0000408L)
 488
 489 //
 490 // returned by HCD if a transfer is submitted to an endpoint that is
 491 // stalled
 492 //
 493 #define USB_STATUS_ENDPOINT_HALTED         ((USBD_STATUS)0xC0000430L)
 494
 495 //
 496 // Software status codes
 497 // Note: the following status codes have only the error bit set
 498 //
 499 #define USB_STATUS_NO_MEMORY                ((USBD_STATUS)0x80000100L)
 500 #define USB_STATUS_INVALID_URB_FUNCTION     ((USBD_STATUS)0x80000200L)
 501 #define USB_STATUS_INVALID_PARAMETER        ((USBD_STATUS)0x80000300L)
 502
 503 //
 504 // returned if client driver attempts to close an endpoint/interface
 505 // or configuration with outstanding transfers.
 506 //
 507 #define USB_STATUS_ERROR_BUSY               ((USBD_STATUS)0x80000400L)
 508 //
 509 // returned by USBD if it cannot complete a URB request, typically this
 510 // will be returned in the URB status field when the Irp is completed
 511 // with a more specific NT error code in the irp.status field.
 512 //
 513 #define USB_STATUS_REQUEST_FAILED           ((USBD_STATUS)0x80000500L)
 514
 515 #define USB_STATUS_INVALID_PIPE_HANDLE      ((USBD_STATUS)0x80000600L)
 516
 517 // returned when there is not enough bandwidth avialable
 518 // to open a requested endpoint
 519 #define USB_STATUS_NO_BANDWIDTH             ((USBD_STATUS)0x80000700L)
 520 //
 521 // generic HC error
 522 //
 523 #define USB_STATUS_INTERNAL_HC_ERROR        ((USBD_STATUS)0x80000800L)
 524 //
 525 // returned when a short packet terminates the transfer
 526 // ie USBD_SHORT_TRANSFER_OK bit not set
 527 //
 528 #define USB_STATUS_ERROR_SHORT_TRANSFER     ((USBD_STATUS)0x80000900L)
 529 //
 530 // returned if the requested start frame is not within
 531 // USBD_ISO_START_FRAME_RANGE of the current USB frame,
 532 // note that the stall bit is set
 533 //
 534 #define USB_STATUS_BAD_START_FRAME          ((USBD_STATUS)0xC0000A00L)
 535 //
 536 // returned by HCD if all packets in an iso transfer complete with an error
 537 //
 538 #define USB_STATUS_ISOCH_REQUEST_FAILED     ((USBD_STATUS)0xC0000B00L)
 539 //
 540 // returned by USBD if the frame length control for a given
 541 // HC is already taken by anothe driver
 542 //
 543 #define USB_STATUS_FRAME_CONTROL_OWNED      ((USBD_STATUS)0xC0000C00L)
 544 //
 545 // returned by USBD if the caller does not own frame length control and
 546 // attempts to release or modify the HC frame length
 547 //
 548 #define USB_STATUS_FRAME_CONTROL_NOT_OWNED  ((USBD_STATUS)0xC0000D00L)
 549
 550 //
 551 // set when a transfers is completed due to an AbortPipe request from
 552 // the client driver
 553 //
 554 // Note: no error or stall bit is set for these status codes
 555 //
 556 #define USB_STATUS_CANCELED                 ((USBD_STATUS)0x00010000L)
 557
 558 #define USB_STATUS_CANCELING                ((USBD_STATUS)0x00020000L)
 559
 560 // Device type           -- in the "User Defined" range."
 561 #define FILE_HCD_DEV_TYPE       45000
 562 #define FILE_UHCI_DEV_TYPE      ( FILE_HCD_DEV_TYPE + 1 )
 563 #define FILE_OHCI_DEV_TYPE      ( FILE_HCD_DEV_TYPE + 2 )
 564 #define FILE_EHCI_DEV_TYPE      ( FILE_HCD_DEV_TYPE + 3 )
 565 #define FILE_USB_DEV_TYPE       ( FILE_HCD_DEV_TYPE + 8 )
 566
 567 #define IOCTL_GET_DEV_COUNT             CTL_CODE( FILE_HCD_DEV_TYPE, 4093, METHOD_BUFFERED, FILE_ANY_ACCESS )
 568 //input_buffer and input_buffer_length is zero, output_buffer is to receive a dword value of the
 569 //dev count, output_buffer_length must be no less than sizeof( unsigned long ).
 570
 571 #define IOCTL_ENUM_DEVICES              CTL_CODE( FILE_HCD_DEV_TYPE, 4094, METHOD_BUFFERED, FILE_ANY_ACCESS )
 572 //input_buffer is a dword value to indicate the count of elements in the array
 573 //input_buffer_length is sizeof( unsigned long ), output_buffer is to receive a
 574 //structure ENUM_DEV_ARRAY where dev_count is the elements hold in this array.
 575
 576 #define IOCTL_GET_DEV_DESC              CTL_CODE( FILE_HCD_DEV_TYPE, 4095, METHOD_BUFFERED, FILE_ANY_ACCESS )
 577 //input_buffer is a structure GET_DEV_DESC_REQ, and the input_buffer_length is
 578 //no less than sizeof( input_buffer ), output_buffer is a buffer to receive the
 579 //requested dev's desc, and output_buffer_length specifies the length of the
 580 //buffer
 581
 582 #define IOCTL_SUBMIT_URB_RD             CTL_CODE( FILE_HCD_DEV_TYPE, 4096, METHOD_IN_DIRECT, FILE_ANY_ACCESS )
 583 #define IOCTL_SUBMIT_URB_WR     CTL_CODE( FILE_HCD_DEV_TYPE, 4097, METHOD_OUT_DIRECT, FILE_ANY_ACCESS )
 584 // if the major_function is IRP_MJ_DEVICE_CONTROL
 585 // input_buffer is a URB, and input_buffer_length is equal to or greater than
 586 // sizeof( URB ); the output_buffer is a buffer to receive data from or send data
 587 // to device. only the following urb fields can be accessed, others must be zeroed.
 588 //  DEV_HANDLE                  endp_handle;
 589 //      UCHAR                   setup_packet[8];        // for control pipe
 590 // the choosing of IOCTL_SUBMIT_URB_RD or IOCTL_SUBMIT_URB_WR should be determined
 591 // by the current URB, for example, a request string from device will use XXX_RD,
 592 // and a write to the bulk endpoint will use XXX_WR
 593 // if the major_function is IRP_MJ_INTERNAL_DEVICE_CONTROL
 594 // input_buffer is a URB, and input_buffer_length is equal to or greater than
 595 // sizeof( URB );
 596 // only the following urb fields can be accessed, others must be zeroed.
 597 //  DEV_HANDLE                  endp_handle;
 598 //      UCHAR                   setup_packet[8];        // for control pipe, or zeroed
 599 //      PUCHAR                          data_buffer;            // buffer for READ/WRITE
 600 //      ULONG                           data_length;            // buffer size in bytes
 601
 602 #define IOCTL_SUBMIT_URB_NOIO   CTL_CODE( FILE_HCD_DEV_TYPE, 4098, METHOD_BUFFERED,     FILE_ANY_ACCESS )
 603 // input_buffer is a URB, and input_buffer_length is equal to or greater than
 604 // sizeof( URB ); the output_buffer is null and no output_buffer_length,
 605 // only the following fields in urb can be accessed, others must be zeroed.
 606 //  DEV_HANDLE                  endp_handle;
 607 //      UCHAR                   setup_packet[8];        //for control pipe
 608 //      there is no difference between IRP_MJ_DEVICE_CONTROL and IRP_MJ_INTERNAL_DEVICE_CONTROL
 609 #define IOCTL_GET_DEV_HANDLE            CTL_CODE( FILE_HCD_DEV_TYPE, 4099, METHOD_BUFFERED, FILE_ANY_ACCESS )
 610 // input_buffer is null ,and input_buffer_length is zero.
 611 // output_buffer will hold the handle to this dev, output_buffer_length is 4
 612 // or bigger
 613
 614 typedef ULONG   DEV_HANDLE, ENDP_HANDLE, IF_HANDLE;
 615
 616 struct URB;
 617 #pragma pack( push, usb_align, 1 )
 618
 619 //structures for DeviceIoControl
 620 typedef struct _ENUM_DEV_ELEMENT
 621 {
 622         DEV_HANDLE      dev_handle;
 623         USHORT          product_id;
 624         USHORT          vendor_id;
 625         UCHAR           dev_addr;
 626
 627 } ENUM_DEV_ELEMENT, *PENUM_DEV_ELEMENT;
 628
 629 typedef struct _ENUM_DEV_ARRAY
 630 {
 631         UCHAR                           dev_count;
 632         ENUM_DEV_ELEMENT        dev_arr[ 1 ];
 633
 634 } ENUM_DEV_ARRAY, *PENUM_DEV_ARRAY;
 635
 636 typedef struct _GET_DEV_DESC_REQ
 637 {
 638         DEV_HANDLE dev_handle;
 639         UCHAR   desc_type;
 640         UCHAR   desc_idx;
 641
 642 } GET_DEV_DESC_REQ, *PGET_DEV_DESC_REQ;
 643
 644 //usb definitions
 645 typedef struct _USB_CTRL_SETUP_PACKET
 646 {
 647         UCHAR                           bmRequestType;
 648         UCHAR                           bRequest;
 649         USHORT                          wValue;
 650         USHORT                          wIndex;
 651         USHORT                          wLength;
 652
 653 }USB_CTRL_SETUP_PACKET, *PUSB_CTRL_SETUP_PACKET;
 654
 655 typedef struct _USB_STRING_DESCRIPTOR
 656 {
 657     UCHAR               bLength;
 658     UCHAR               bDescriptorType;
 659     USHORT              wData[1];
 660
 661 } USB_STRING_DESCRIPTOR, *PUSB_STRING_DESCRIPTOR;
 662
 663 typedef struct _USB_DESC_HEADER
 664 {
 665     UCHAR               bLength;
 666     UCHAR               bDescriptorType;
 667
 668 } USB_DESC_HEADER, *PUSB_DESC_HEADER;
 669
 670 typedef struct _USB_ENDPOINT_DESC
 671 {
 672     UCHAR                bLength;
 673     UCHAR                bDescriptorType;
 674     UCHAR                bEndpointAddress;
 675     UCHAR                bmAttributes;
 676     USHORT               wMaxPacketSize;
 677     UCHAR                bInterval;
 678
 679 } USB_ENDPOINT_DESC, *PUSB_ENDPOINT_DESC;
 680
 681 typedef struct _USB_INTERFACE_DESC
 682 {
 683     UCHAR               bLength;
 684     UCHAR               bDescriptorType;
 685     UCHAR               bInterfaceNumber;
 686     UCHAR               bAlternateSetting;
 687     UCHAR               bNumEndpoints;
 688     UCHAR               bInterfaceClass;
 689     UCHAR               bInterfaceSubClass;
 690     UCHAR               bInterfaceProtocol;
 691     UCHAR               iInterface;
 692
 693 } USB_INTERFACE_DESC, *PUSB_INTERFACE_DESC;
 694
 695 typedef struct _USB_CONFIGURATION_DESC
 696 {
 697     UCHAR               bLength;
 698     UCHAR               bDescriptorType;
 699     USHORT              wTotalLength;
 700     UCHAR               bNumInterfaces;
 701     UCHAR               bConfigurationValue;
 702     UCHAR               iConfiguration;
 703     UCHAR               bmAttributes;
 704     UCHAR               MaxPower;
 705
 706 } USB_CONFIGURATION_DESC, *PUSB_CONFIGURATION_DESC;
 707
 708 typedef struct _USB_DEVICE_DESC
 709 {
 710     UCHAR               bLength;
 711     UCHAR               bDescriptorType;
 712     USHORT              bcdUSB;
 713     UCHAR               bDeviceClass;
 714     UCHAR               bDeviceSubClass;
 715     UCHAR               bDeviceProtocol;
 716     UCHAR               bMaxPacketSize0;
 717     USHORT              idVendor;
 718     USHORT              idProduct;
 719     USHORT              bcdDevice;
 720     UCHAR               iManufacturer;
 721     UCHAR               iProduct;
 722     UCHAR               iSerialNumber;
 723     UCHAR               bNumConfigurations;
 724
 725 } USB_DEVICE_DESC, *PUSB_DEVICE_DESC;
 726
 727
 728 #define URB_FLAG_STATE_MASK             0x0f
 729 #define URB_FLAG_STATE_PENDING          0x00
 730 #define URB_FLAG_STATE_IN_PROCESS   0x01
 731 #define URB_FLAG_STATE_FINISHED     0x02
 732
 733 // USB2.0 state
 734 #define URB_FLAG_STATE_DOORBELL         0x03    // for async request removal
 735 #define URB_FLAG_STATE_WAIT_FRAME       0x04    // for sync request removal( for cancel only )
 736 #define URB_FLAG_STATE_ERROR            0x05
 737
 738 #define URB_FLAG_IN_SCHEDULE        0x10
 739 #define URB_FLAG_FORCE_CANCEL       0x20
 740 #define URB_FLAG_SHORT_PACKET       0x80000000
 741
 742 typedef struct _SPLIT_ISO_BUS_TIME
 743 {
 744         USHORT                          bus_time;
 745         USHORT                          start_uframe;
 746
 747 } SPLIT_ISO_BUS_TIME, *PSPLIT_ISO_BUS_TIME;
 748
 749 typedef struct _ISO_PACKET_DESC
 750 {
 751         LONG                            offset;
 752         LONG                            length;         // expected length
 753         LONG                            actual_length;
 754         LONG                            status;
 755         union
 756         {
 757                 LONG                            bus_time;   //opaque for client request of split iso, the bus_time is the start_uframe for each transaction
 758                 SPLIT_ISO_BUS_TIME      params;
 759         };
 760
 761 } ISO_PACKET_DESC, *PISO_PACKET_DESC;
 762
 763 #define CTRL_PARENT_URB_VALID   1
 764
 765 typedef void ( *PURBCOMPLETION )( struct _URB *purb, PVOID pcontext);
 766
 767 typedef struct _CTRL_REQ_STACK
 768 {
 769         PURBCOMPLETION          urb_completion; // the last step of the urb_completion is to call the
 770                                                                                 // the prevoius stack's callback if has, and the last
 771                                                                                 // one is purb->completion
 772         PVOID                           context;
 773         ULONG                           params[ 3 ];
 774
 775 } CTRL_REQ_STACK, *PCTRL_REQ_STACK;
 776
 777 #pragma pack( pop, usb_align )
 778
 779 typedef struct _URB_HS_PIPE_CONTENT
 780 {
 781         ULONG trans_type : 2;   // bit 0-1
 782         ULONG mult_count : 2;   // bit 2-3, used in high speed int and iso requests
 783         ULONG reserved : 1;             // bit 1
 784         ULONG speed_high : 1;   // bit 5
 785         ULONG speed_low : 1;    // bit 6
 786         ULONG trans_dir : 1;    // bit 7
 787         ULONG dev_addr : 7;             // bit 8-14
 788         ULONG endp_addr : 4;            // bit 15-18
 789         ULONG data_toggle : 1;  // bit 19
 790         ULONG max_packet_size : 4; // bit 20-23 log( max_packet_size )
 791         ULONG interval : 4;             // bit 24-27 the same definition in USB2.0, for high or full/low speed
 792         ULONG start_uframe : 3; // bit 28-30
 793         ULONG reserved1 : 1;    //
 794
 795 } URB_HS_PIPE_CONTENT, *PURB_HS_PIPE_CONTENT;
 796
 797 typedef struct _URB_HS_CONTEXT_CONTENT
 798 {
 799         ULONG hub_addr : 7;     // high speed hub addr for split transfer
 800         ULONG port_idx : 7;
 801         ULONG reserved : 18;
 802
 803 } URB_HS_CONTEXT_CONTENT, *PURB_HS_CONTEXT_CONTENT;
 804
 805 typedef struct _URB
 806 {
 807     LIST_ENTRY          urb_link;
 808     ULONG               flags;
 809         DEV_HANDLE                      endp_handle;
 810         LONG                            status;
 811                 //record info for isr use, similar to td.status
 812                 //int pipe has different content in the 8 msb
 813         //the eight bits contain interrupt interval.
 814         //and max packet length is encoded in 3 bits from 23-21
 815             //that means 2^(x) bytes in the packet.
 816         ULONG                           pipe;               // bit0-1: endp type, bit 6: ls or fs. bit 7: dir
 817
 818         union
 819         {
 820                 UCHAR                   setup_packet[8];        // for control
 821                 LONG                            params[ 2 ];            // params[ 0 ] is used in iso transfer as max_packet_size
 822         };
 823
 824     PUCHAR              data_buffer;            //user data
 825     LONG                data_length;            //user data length
 826
 827         struct _USB_DEV         *pdev;
 828     struct _USB_ENDPOINT *pendp;             //pipe for current transfer
 829
 830     PURBCOMPLETION      completion;
 831     PVOID               context;                //parameter of completion
 832
 833         PVOID                           urb_ext;                        //for high speed hcd use
 834     ULONG               hs_context;         //for high speed hcd use
 835
 836         PIRP                pirp;               //irp from client driver
 837         LONG                reference;          //for caller private use
 838
 839         LONG                    td_count;           //for any kinds of transfer
 840     LONG                rest_bytes;         //for split bulk transfer involving more than 1024 tds
 841         LONG                            bytes_to_transfer;
 842         LONG                    bytes_transfered;       //( bulk transfer )accumulate one split-transfer by xfered bytes of the executed transactions
 843         PLIST_ENTRY         last_finished_td;   //last inactive td useful for large amount transfer
 844     LIST_ENTRY          trasac_list;        //list of tds or qhs
 845
 846         union
 847         {
 848                 LONG                iso_start_frame;    // for high speed endp, this is uframe index, and not used for full/low speed endp, instead,
 849                                                                                                 // iso_packet_desc.param.start_uframe is used.
 850                 LONG                            int_start_frame;        // frame( ms ) index for high/full/low speed endp
 851                 struct
 852                 {
 853                         UCHAR                   ctrl_req_flags;
 854                         UCHAR                   ctrl_stack_count;
 855                         UCHAR                   ctrl_cur_stack;         // the receiver uses this by increment the stack pointer first. if the requester
 856                         UCHAR                   ctrl_reserved;          // send it down with ctrl_stack_count zero, that means the stack is not initialized,
 857                                                                                                 // and can be initialized by receiver to 1 and only 1.
 858                                                                                                 // If the initializer found the stack size won't meet the number down the drivers, it must
 859                                                                                                 // reallocate one urb with the required stack size. and store the previous urb in
 860                                                                                                 // ctrl_parent_urb
 861                 } ctrl_req_context;
 862         };
 863
 864         union
 865         {
 866                 LONG                            iso_frame_count;        // uframe for high speed and frame for full/low speed
 867                 struct _URB*            ctrl_parent_urb;
 868         };
 869
 870         union
 871         {
 872                 ISO_PACKET_DESC         iso_packet_desc[ 1 ];   //used to build up trasac_list for iso transfer and claim bandwidth
 873                 CTRL_REQ_STACK          ctrl_req_stack[ 1 ];
 874         };
 875
 876 } URB, *PURB;
 877
 878
 879 NTSTATUS
 880 usb_set_dev_ext(
 881 ULONG dev_ref,
 882 PVOID dev_ext,
 883 LONG size
 884 );
 885
 886 NTSTATUS
 887 usb_set_if_ext(
 888 ULONG dev_ref,
 889 ULONG if_ref,
 890 PVOID if_ext,
 891 LONG size
 892 );
 893
 894 PVOID
 895 usb_get_dev_ext(
 896 ULONG dev_ref
 897 );
 898
 899 PVOID
 900 usb_get_if_ext(
 901 ULONG dev_ref,
 902 ULONG if_ref
 903 );
 904
 905 NTSTATUS
 906 usb_claim_interface(
 907 ULONG dev_ref,
 908 ULONG if_ref,
 909 struct _USB_DRIVER *usb_drvr
 910 );
 911
 912 //return reference to the endp
 913 ULONG
 914 usb_get_endp(
 915 ULONG dev_ref,
 916 LONG endp_addr
 917 );
 918
 919 //return reference to the interface
 920 ULONG
 921 usb_get_interface(
 922 ULONG dev_ref,
 923 LONG if_idx
 924 );
 925
 926 NTSTATUS
 927 usb_set_configuration(
 928 ULONG dev_ref,
 929 LONG config_value
 930 );
 931
 932 // each call will return full size of the config desc and
 933 // its if, endp descs.
 934 // return value is the bytes actually returned.
 935 // if the return value is equal to wTotalLength, all the descs of the
 936 // configuration returned.
 937 NTSTATUS
 938 usb_get_config_desc(
 939 ULONG dev_ref,
 940 LONG config_idx,
 941 PCHAR buffer,
 942 PLONG psize
 943 );
 944
 945 NTSTATUS
 946 usb_submit_urb(
 947 struct _USB_DEV_MANAGER* dev_mgr,
 948 PURB purb
 949 );
 950
 951 NTSTATUS
 952 usb_cancel_urb(
 953 ULONG dev_ref,
 954 ULONG endp_ref,
 955 PURB purb
 956 );
 957
 958 void usb_fill_int_urb(PURB urb,
 959     struct _USB_DEV *dev,
 960     ULONG pipe,
 961     PVOID transfer_buffer,
 962     LONG buffer_length,
 963     PURBCOMPLETION complete,
 964     PVOID context,
 965     int interval);
 966
 967 LONG
 968 usb_calc_bus_time(
 969 LONG low_speed,
 970 LONG input_dir,
 971 LONG isoc,
 972 LONG bytecount
 973 );
 974
 975 //increment the dev->ref_count to lock the dev
 976 NTSTATUS
 977 usb_query_and_lock_dev(
 978 struct _USB_DEV_MANAGER* dev_mgr,
 979 DEV_HANDLE dev_handle,
 980 struct _USB_DEV** ppdev
 981 );
 982
 983 //decrement the dev->ref_count
 984 NTSTATUS
 985 usb_unlock_dev(
 986 struct _USB_DEV *dev
 987 );
 988
 989 NTSTATUS
 990 usb_reset_pipe(
 991 struct _USB_DEV *pdev,
 992 struct _USB_ENDPOINT *pendp,
 993 PURBCOMPLETION client_completion,
 994 PVOID param                     //parameter for client_completion
 995 );
 996
 997 VOID
 998 usb_reset_pipe_completion(
 999 PURB purb,
1000 PVOID pcontext
1001 );
1002
1003 PVOID
1004 usb_alloc_mem(
1005 POOL_TYPE pool_type,
1006 LONG size
1007 );
1008
1009 VOID
1010 usb_free_mem(
1011 PVOID pbuf
1012 );
1013
1014 PUSB_CONFIGURATION_DESC
1015 usb_find_config_desc_by_val(
1016 PUCHAR pbuf,
1017 LONG val,
1018 LONG cfg_count
1019 );
1020
1021 PUSB_CONFIGURATION_DESC
1022 usb_find_config_desc_by_idx(
1023 PUCHAR pbuf,
1024 LONG idx,
1025 LONG cfg_count
1026 );
1027
1028 BOOLEAN
1029 usb_skip_if_and_altif(
1030 PUCHAR* pdesc_BUF
1031 );
1032
1033 BOOLEAN
1034 usb_skip_one_config(
1035 PUCHAR* pconfig_desc_BUF
1036 );
1037
1038 VOID
1039 usb_wait_ms_dpc(
1040 ULONG ms
1041 );
1042
1043 VOID
1044 usb_wait_us_dpc(
1045 ULONG us
1046 );
1047
1048 BOOLEAN
1049 usb_query_clicks(
1050 PLARGE_INTEGER  clicks
1051 );
1052
1053 VOID
1054 usb_cal_cpu_freq();
1055
1056 NTSTATUS
1057 usb_reset_pipe_ex(
1058 struct _USB_DEV_MANAGER *dev_mgr,
1059 DEV_HANDLE endp_handle,
1060 PURBCOMPLETION reset_completion,
1061 PVOID param
1062 );
1063
1064 VOID
1065 usb_call_ctrl_completion(
1066 PURB purb
1067 );
1068
1069 BOOLEAN
1070 is_header_match(
1071 PUCHAR pbuf,
1072 ULONG type
1073 ); //used to check descriptor validity
1074 #endif