drivers/usb/usbehci_new/interfaces.h

   1
   2 #ifndef INTERFACES_HPP
   3 #define INTERFACES_HPP
   4
   5 //---------------------------------------------------------------------------
   6 //
   7 //          Object Hierachy
   8 //       --------------------------------------------------------------------
   9 //       |  IRootHCDController                                              |
  10 //       |    IHCDController Intel USB Universal Host Controller - 3A37     |
  11 //       |    IHCDController - Intel USB Universal HostController - 3A38    |
  12 //       |    IHCDController - Intel USB Universal HostController - 3A38    |
  13 //       |------------------------------------------------------------------|
  14 //
  15 //
  16 //       IHCDController Intel USB Universal Host Controller - 3A37
  17 //         IHubController
  18 //         IUSBHardwareDevice
  19 //           IDMAMemoryManager
  20 //           IUSBQueue  <-      interacts with -> IUSBRequest
  21 //
  22 //
  23 //  Each IHCDController creates an IUSBHardwareDevice class upon initialization. The
  24 //  IUSBHardwardeDevice class is used to abstract usb controller specifics. The IHubController
  25 //  manages all attached devices and handles hub control ioctl requests.
  26 //
  27 //  Each IUSBHardwareDevice has one IDMAMemoryManager and one IUSBQueue. The IDMAMemoryManager
  28 //  is used to handle dma memory allocations. The IUSBQueue manages requests which are send to the
  29 //  usb hardware. See IUSBRequest class for details.
  30 //
  31
  32
  33 //=========================================================================================
  34 //
  35 // class IRootHCDController
  36 //
  37 // Description: This class serves as the root host controller. The host controller mantains
  38 // a list of registered controllers and provides support functions for the host controllers
  39
  40 struct IHCDController;
  41
  42 DECLARE_INTERFACE_(IRootHCDController, IUnknown)
  43 {
  44     DEFINE_ABSTRACT_UNKNOWN()
  45
  46 //-----------------------------------------------------------------------------------------
  47 //
  48 // Initialize
  49 //
  50 // Description: This function initializes the root host controller. It allocates the resources
  51 // required to manage the registered controllers
  52
  53     virtual NTSTATUS Initialize() = 0;
  54
  55 //-----------------------------------------------------------------------------------------
  56 //
  57 // RegisterHCD
  58 //
  59 // Description: this function registers a host controller with the root host controller
  60
  61     virtual NTSTATUS RegisterHCD(struct IHCDController * Controller) = 0;
  62
  63 //-----------------------------------------------------------------------------------------
  64 //
  65 // UnregisterHCD
  66 //
  67 // Description: this function unregistes a host controller
  68
  69     virtual NTSTATUS UnregisterHCD(struct IHCDController * Controller) = 0;
  70
  71 //-----------------------------------------------------------------------------------------
  72 //
  73 // GetControllerCount
  74 //
  75 // Description: returns the number of host controllers registered
  76
  77     virtual ULONG GetControllerCount() = 0;
  78
  79 };
  80
  81 typedef IRootHCDController *PROOTHDCCONTROLLER;
  82
  83 //=========================================================================================
  84 //
  85 // class IHCDController
  86 //
  87 // Description: This class is used to manage a single USB host controller
  88 //
  89
  90 DECLARE_INTERFACE_(IHCDController, IUnknown)
  91 {
  92     DEFINE_ABSTRACT_UNKNOWN()
  93
  94 //-----------------------------------------------------------------------------------------
  95 //
  96 // Initialize
  97 //
  98 // Description: This function initializes the IHCDController implementation.
  99 // It creates an IUSBHardwareDevice object and initializes it. It also registeres itself with
 100 // the IRootHCDController
 101 //
 102     virtual NTSTATUS Initialize(IN PROOTHDCCONTROLLER RootHCDController,
 103                                 IN PDRIVER_OBJECT DriverObject,
 104                                 IN PDEVICE_OBJECT PhysicalDeviceObject) = 0;
 105
 106 //-----------------------------------------------------------------------------------------
 107 //
 108 // HandlePnp
 109 //
 110 // Description: This function handles all pnp requests
 111
 112     virtual NTSTATUS HandlePnp(IN PDEVICE_OBJECT DeviceObject,
 113                                IN OUT PIRP Irp) = 0;
 114
 115 //-----------------------------------------------------------------------------------------
 116 //
 117 // HandlePower
 118 //
 119 // Description: This function handles all power pnp requests
 120 //
 121     virtual NTSTATUS HandlePower(IN PDEVICE_OBJECT DeviceObject,
 122                                  IN OUT PIRP Irp) = 0;
 123
 124 //-----------------------------------------------------------------------------------------
 125 //
 126 // HandleDeviceControl
 127 //
 128 // Description: handles device io control requests
 129
 130     virtual NTSTATUS HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject,
 131                                          IN OUT PIRP Irp) = 0;
 132
 133 };
 134
 135 typedef IHCDController *PHCDCONTROLLER;
 136
 137
 138 //=========================================================================================
 139 //
 140 // class IUSBHardwareDevice
 141 //
 142 // Description: This class provides access to the usb hardware controller
 143 //
 144
 145 struct IDMAMemoryManager;
 146 struct IUSBQueue;
 147
 148 DECLARE_INTERFACE_(IUSBHardwareDevice, IUnknown)
 149 {
 150     DEFINE_ABSTRACT_UNKNOWN()
 151
 152 //-----------------------------------------------------------------------------------------
 153 //
 154 // Initialize
 155 //
 156 // Description: Initializes the usb device controller
 157
 158     virtual NTSTATUS Initialize(PDRIVER_OBJECT DriverObject,
 159                                 PDEVICE_OBJECT FunctionalDeviceObject,
 160                                 PDEVICE_OBJECT PhysicalDeviceObject,
 161                                 PDEVICE_OBJECT LowerDeviceObject) = 0;
 162
 163 //-----------------------------------------------------------------------------------------
 164 //
 165 // PnpStart
 166 //
 167 // Description: handles pnp start request from device. It registeres the interrupt,
 168 // sets up the ports and prepares the device. It then starts the controller
 169
 170    virtual NTSTATUS PnpStart(PCM_RESOURCE_LIST RawResources,
 171                              PCM_RESOURCE_LIST TranslatedResources) = 0;
 172
 173 //-----------------------------------------------------------------------------------------
 174 //
 175 // PnpStop
 176 //
 177 // Description: handles pnp stop request from device. It unregisteres the interrupt, releases ports and dma object.
 178
 179     virtual NTSTATUS PnpStop(void) = 0;
 180
 181 //-----------------------------------------------------------------------------------------
 182 //
 183 // HandlePower
 184 //
 185 // Description: handles power requests
 186
 187     virtual NTSTATUS HandlePower(PIRP Irp) = 0;
 188
 189 //-----------------------------------------------------------------------------------------
 190 //
 191 // GetDeviceDetails
 192 //
 193 // Description: returns the device details such as vendor id, device id, number of ports and speed
 194
 195     virtual NTSTATUS GetDeviceDetails(OUT OPTIONAL PULONG VendorId,
 196                                       OUT OPTIONAL PULONG DeviceId,
 197                                       OUT OPTIONAL PULONG NumberOfPorts,
 198                                       OUT OPTIONAL PULONG Speed) = 0;
 199
 200 //-----------------------------------------------------------------------------------------
 201 //
 202 // GetDmaMemoryManager
 203 //
 204 // Description: returns interface to DMAMemoryManager
 205 // Interface is reference counted, you need to call Release method when you are done with it
 206 // Do not call Initialize on IDMAMemoryManager, the object is already initialized
 207
 208     virtual NTSTATUS GetDmaMemoryManager(OUT struct IDMAMemoryManager **OutMemoryManager) = 0;
 209
 210 //-----------------------------------------------------------------------------------------
 211 //
 212 // GetUSBQueue
 213 //
 214 // Description: returns interface to internal IUSBQueue
 215 // Interface is reference counted, you need to call release method when you are done with it
 216 // Do not call Initialize on IUSBQueue, the object is already initialized
 217
 218     virtual NTSTATUS GetUSBQueue(OUT struct IUSBQueue **OutUsbQueue) = 0;
 219
 220 //-----------------------------------------------------------------------------------------
 221 //
 222 // ResetController()
 223 //
 224 // Description: this function resets the controller
 225 // Returns STATUS_SUCCESS when the controller was successfully reset
 226
 227    virtual NTSTATUS ResetController() = 0;
 228
 229 //-----------------------------------------------------------------------------------------
 230 //
 231 // ResetPort
 232 //
 233 // Description: this functions resets the port on the controller
 234 //
 235
 236     virtual NTSTATUS ResetPort(ULONG PortNumber) = 0;
 237
 238 //-----------------------------------------------------------------------------------------
 239 //
 240 // AcquireDeviceLock
 241 //
 242 // Description: acquires the device lock
 243
 244     virtual KIRQL AcquireDeviceLock(void) = 0;
 245
 246 //-----------------------------------------------------------------------------------------
 247 //
 248 // ReleaseLock
 249 //
 250 // Description: releases the device lock
 251
 252     virtual void ReleaseDeviceLock(KIRQL OldLevel) = 0;
 253 };
 254
 255 typedef IUSBHardwareDevice *PUSBHARDWAREDEVICE;
 256
 257
 258 //=========================================================================================
 259 //
 260 // class IDMAMemoryManager
 261 //
 262 // Description: This class provides access to the dma buffer. It provides methods to
 263 // allocate and free from the dma buffer
 264 //
 265
 266 DECLARE_INTERFACE_(IDMAMemoryManager, IUnknown)
 267 {
 268     DEFINE_ABSTRACT_UNKNOWN()
 269
 270 //-----------------------------------------------------------------------------------------
 271 //
 272 // Initialize
 273 //
 274 // Description: initializes the memory manager
 275
 276     virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Device,
 277                                 IN PKSPIN_LOCK Lock,
 278                                 IN ULONG DmaBufferSize,
 279                                 IN PVOID VirtualBase,
 280                                 IN PHYSICAL_ADDRESS PhysicalAddress,
 281                                 IN ULONG DefaultBlockSize) = 0;
 282
 283 //-----------------------------------------------------------------------------------------
 284 //
 285 // Allocate
 286 //
 287 // Description: allocates block of memory from allocator
 288
 289     virtual NTSTATUS Allocate(IN ULONG Size,
 290                               OUT PVOID *OutVirtualBase,
 291                               OUT PPHYSICAL_ADDRESS *OutPhysicalAddress) = 0;
 292
 293
 294 //-----------------------------------------------------------------------------------------
 295 //
 296 // Free
 297 //
 298 // Description: releases memory block
 299
 300     virtual NTSTATUS Release(IN PVOID VirtualBase,
 301                              IN ULONG Size) = 0;
 302
 303 };
 304
 305 typedef IDMAMemoryManager *PDMAMEMORYMANAGER;
 306
 307
 308 //=========================================================================================
 309 //
 310 // class IUSBRequest
 311 //
 312 // Description: This class is used to issue request to usb controller. The class is
 313 // initialized using InitializeXXX methods. You also need to call SetEndpoint to define the endpoint
 314 // In addition you can call SetCompletionDetails if you need to wait for the end of
 315 // the request or want to complete an irp. You call AddUSBRequest to add the request to the queue.
 316 // Once the request is completed the CompletionCallback is invoked. The CompletionCallback
 317 // will take care of any completion details which have been set. If the request is cancelled, the
 318 // CancelCallback routine is invoked.
 319 //
 320
 321 DECLARE_INTERFACE_(IUSBRequest, IUnknown)
 322 {
 323     DEFINE_ABSTRACT_UNKNOWN()
 324
 325 //-----------------------------------------------------------------------------------------
 326 //
 327 // InitializeWithSetupPacket
 328 //
 329 // Description: initializes the request packet with an setup packet
 330 // If there is a TransferBuffer, the TransferBufferLength contains the length of the buffer
 331
 332
 333     virtual NTSTATUS InitializeWithSetupPacket(IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket,
 334                                                IN ULONG TransferBufferLength,
 335                                                IN PVOID TransferBuffer) = 0;
 336
 337 //
 338 //TODO: find required parameters for different packet types
 339 //
 340
 341
 342 //-----------------------------------------------------------------------------------------
 343 //
 344 // SetEndPoint
 345 //
 346 // Description: sets the endpoint of the request.
 347
 348     virtual NTSTATUS SetEndPoint(PUSB_ENDPOINT_DESCRIPTOR EndPoint);
 349
 350 //-----------------------------------------------------------------------------------------
 351 //
 352 // SetCompletionDetails
 353 //
 354 // Description: sets up how the request should be completed
 355 // If an irp is passed, then it is completed with status code of the
 356 // CompletionCallback or CancelCallback
 357 // If an event is passed, then the event is signaled
 358
 359     virtual NTSTATUS SetCompletionDetails(IN OPTIONAL PIRP Irp,
 360                                           IN OPTIONAL PKEVENT Event) = 0;
 361
 362 //-----------------------------------------------------------------------------------------
 363 //
 364 // CompletionCallback
 365 //
 366 // Description: called when request has been completed. It is called when
 367 // IUSBQueue completes the request
 368
 369     virtual VOID CompletionCallback(IN NTSTATUS NtStatusCode,
 370                                     IN ULONG UrbStatusCode) = 0;
 371
 372 //-----------------------------------------------------------------------------------------
 373 //
 374 // CancelCallback
 375 //
 376 // Description: called when request is cancelled. Called by IUSBQueue
 377
 378     virtual VOID CancelCallback(IN NTSTATUS NtStatusCode) = 0;
 379
 380 };
 381
 382 //=========================================================================================
 383 //
 384 // class IUSBQueue
 385 //
 386 // Description: This class manages pending requests
 387 //
 388
 389 DECLARE_INTERFACE_(IUSBQueue, IUnknown)
 390 {
 391     DEFINE_ABSTRACT_UNKNOWN()
 392
 393 //-----------------------------------------------------------------------------------------
 394 //
 395 // Initialize
 396 //
 397 // Description: initializes the object
 398
 399     virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Hardware,
 400                                 IN OPTIONAL PKSPIN_LOCK Lock,
 401                                 IN PDMAMEMORYMANAGER MemoryManager) = 0;
 402
 403 //-----------------------------------------------------------------------------------------
 404 //
 405 // GetPendingRequestCount
 406 //
 407 // Description: returns the number of pending requests
 408
 409     virtual ULONG GetPendingRequestCount() = 0;
 410
 411 //-----------------------------------------------------------------------------------------
 412 //
 413 // AddUSBRequest
 414 //
 415 // Description: adds an usb request to the queue.
 416 // Returns status success when successful
 417
 418     virtual NTSTATUS AddUSBRequest(IUSBRequest * Request) = 0;
 419
 420 //-----------------------------------------------------------------------------------------
 421 //
 422 // CancelRequests()
 423 //
 424 // Description: cancels all requests
 425
 426     virtual NTSTATUS CancelRequests() = 0;
 427
 428 //-----------------------------------------------------------------------------------------
 429 //
 430 // CreateUSBRequest
 431 //
 432 // Description: creates an usb request
 433
 434     virtual NTSTATUS CreateUSBRequest(IUSBRequest **OutRequest) = 0;
 435 };
 436
 437 //=========================================================================================
 438 //
 439 // class IHubController
 440 //
 441 // Description: This class implements a hub controller
 442 //
 443
 444 DECLARE_INTERFACE_(IHubController, IUnknown)
 445 {
 446     DEFINE_ABSTRACT_UNKNOWN()
 447
 448 //----------------------------------------------------------------------------------------
 449 //
 450 // Initialize
 451 //
 452 // Description: Initializes the hub controller
 453
 454     virtual NTSTATUS Initialize(IN PHCDCONTROLLER Controller,
 455                                 IN PUSBHARDWAREDEVICE Device,
 456                                 IN BOOLEAN IsRootHubDevice,
 457                                 IN ULONG DeviceAddress);
 458
 459 //-----------------------------------------------------------------------------------------
 460 //
 461 // HandlePnp
 462 //
 463 // Description: This function handles all pnp requests
 464
 465     virtual NTSTATUS HandlePnp(IN PDEVICE_OBJECT DeviceObject,
 466                                IN OUT PIRP Irp) = 0;
 467
 468 //-----------------------------------------------------------------------------------------
 469 //
 470 // HandlePower
 471 //
 472 // Description: This function handles all power pnp requests
 473 //
 474     virtual NTSTATUS HandlePower(IN PDEVICE_OBJECT DeviceObject,
 475                                  IN OUT PIRP Irp) = 0;
 476
 477 //-----------------------------------------------------------------------------------------
 478 //
 479 // HandleDeviceControl
 480 //
 481 // Description: handles device io control requests
 482
 483     virtual NTSTATUS HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject,
 484                                          IN OUT PIRP Irp) = 0;
 485 };
 486
 487 typedef IHubController *PHUBCONTROLLER;
 488
 489
 490 #endif