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 typedef IHCDController *PHCDCONTROLLER;
 109
 110
 111 //=========================================================================================
 112 //
 113 // class IUSBHardwareDevice
 114 //
 115 // Description: This class provides access to the usb hardware controller
 116 //
 117
 118 struct IDMAMemoryManager;
 119 struct IUSBQueue;
 120
 121 DECLARE_INTERFACE_(IUSBHardwareDevice, IUnknown)
 122 {
 123     DEFINE_ABSTRACT_UNKNOWN()
 124
 125 //-----------------------------------------------------------------------------------------
 126 //
 127 // Initialize
 128 //
 129 // Description: Initializes the usb device controller
 130
 131     virtual NTSTATUS Initialize(PDRIVER_OBJECT DriverObject,
 132                                 PDEVICE_OBJECT FunctionalDeviceObject,
 133                                 PDEVICE_OBJECT PhysicalDeviceObject,
 134                                 PDEVICE_OBJECT LowerDeviceObject) = 0;
 135
 136 //-----------------------------------------------------------------------------------------
 137 //
 138 // PnpStart
 139 //
 140 // Description: handles pnp start request from device. It registeres the interrupt,
 141 // sets up the ports and prepares the device. It then starts the controller
 142
 143    virtual NTSTATUS PnpStart(PCM_RESOURCE_LIST RawResources,
 144                              PCM_RESOURCE_LIST TranslatedResources) = 0;
 145
 146 //-----------------------------------------------------------------------------------------
 147 //
 148 // PnpStop
 149 //
 150 // Description: handles pnp stop request from device. It unregisteres the interrupt, releases ports and dma object.
 151
 152     virtual NTSTATUS PnpStop(void) = 0;
 153
 154 //-----------------------------------------------------------------------------------------
 155 //
 156 // GetDeviceDetails
 157 //
 158 // Description: returns the device details such as vendor id, device id, number of ports and speed
 159
 160     virtual NTSTATUS GetDeviceDetails(OUT OPTIONAL PULONG VendorId,
 161                                       OUT OPTIONAL PULONG DeviceId,
 162                                       OUT OPTIONAL PULONG NumberOfPorts,
 163                                       OUT OPTIONAL PULONG Speed) = 0;
 164
 165 //-----------------------------------------------------------------------------------------
 166 //
 167 // GetDmaMemoryManager
 168 //
 169 // Description: returns interface to DMAMemoryManager
 170 // Interface is reference counted, you need to call Release method when you are done with it
 171 // Do not call Initialize on IDMAMemoryManager, the object is already initialized
 172
 173     virtual NTSTATUS GetDmaMemoryManager(OUT struct IDMAMemoryManager **OutMemoryManager) = 0;
 174
 175 //-----------------------------------------------------------------------------------------
 176 //
 177 // GetUSBQueue
 178 //
 179 // Description: returns interface to internal IUSBQueue
 180 // Interface is reference counted, you need to call release method when you are done with it
 181 // Do not call Initialize on IUSBQueue, the object is already initialized
 182
 183     virtual NTSTATUS GetUSBQueue(OUT struct IUSBQueue **OutUsbQueue) = 0;
 184
 185 //-----------------------------------------------------------------------------------------
 186 //
 187 // ResetController()
 188 //
 189 // Description: this function resets the controller
 190 // Returns STATUS_SUCCESS when the controller was successfully reset
 191
 192    virtual NTSTATUS ResetController() = 0;
 193
 194 //-----------------------------------------------------------------------------------------
 195 //
 196 // ResetPort
 197 //
 198 // Description: this functions resets the port on the controller
 199 //
 200
 201     virtual NTSTATUS ResetPort(ULONG PortNumber) = 0;
 202
 203 //-----------------------------------------------------------------------------------------
 204 //
 205 // AcquireDeviceLock
 206 //
 207 // Description: acquires the device lock
 208
 209     virtual KIRQL AcquireDeviceLock(void) = 0;
 210
 211 //-----------------------------------------------------------------------------------------
 212 //
 213 // ReleaseLock
 214 //
 215 // Description: releases the device lock
 216
 217     virtual void ReleaseDeviceLock(KIRQL OldLevel) = 0;
 218 };
 219
 220 typedef IUSBHardwareDevice *PUSBHARDWAREDEVICE;
 221
 222
 223 //=========================================================================================
 224 //
 225 // class IDMAMemoryManager
 226 //
 227 // Description: This class provides access to the dma buffer. It provides methods to
 228 // allocate and free from the dma buffer
 229 //
 230
 231 DECLARE_INTERFACE_(IDMAMemoryManager, IUnknown)
 232 {
 233     DEFINE_ABSTRACT_UNKNOWN()
 234
 235 //-----------------------------------------------------------------------------------------
 236 //
 237 // Initialize
 238 //
 239 // Description: initializes the memory manager
 240
 241     virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Device,
 242                                 IN PKSPIN_LOCK Lock,
 243                                 IN ULONG DmaBufferSize,
 244                                 IN PVOID VirtualBase,
 245                                 IN PHYSICAL_ADDRESS PhysicalAddress,
 246                                 IN ULONG DefaultBlockSize) = 0;
 247
 248 //-----------------------------------------------------------------------------------------
 249 //
 250 // Allocate
 251 //
 252 // Description: allocates block of memory from allocator
 253
 254     virtual NTSTATUS Allocate(IN ULONG Size,
 255                               OUT PVOID *OutVirtualBase,
 256                               OUT PPHYSICAL_ADDRESS *OutPhysicalAddress) = 0;
 257
 258
 259 //-----------------------------------------------------------------------------------------
 260 //
 261 // Free
 262 //
 263 // Description: releases memory block
 264
 265     virtual NTSTATUS Release(IN PVOID VirtualBase,
 266                              IN ULONG Size) = 0;
 267
 268 };
 269
 270 typedef IDMAMemoryManager *PDMAMEMORYMANAGER;
 271
 272
 273 //=========================================================================================
 274 //
 275 // class IUSBRequest
 276 //
 277 // Description: This class is used to issue request to usb controller. The class is
 278 // initialized using InitializeXXX methods. You also need to call SetEndpoint to define the endpoint
 279 // In addition you can call SetCompletionDetails if you need to wait for the end of
 280 // the request or want to complete an irp. You call AddUSBRequest to add the request to the queue.
 281 // Once the request is completed the CompletionCallback is invoked. The CompletionCallback
 282 // will take care of any completion details which have been set. If the request is cancelled, the
 283 // CancelCallback routine is invoked.
 284 //
 285
 286 DECLARE_INTERFACE_(IUSBRequest, IUnknown)
 287 {
 288     DEFINE_ABSTRACT_UNKNOWN()
 289
 290 //-----------------------------------------------------------------------------------------
 291 //
 292 // InitializeWithSetupPacket
 293 //
 294 // Description: initializes the request packet with an setup packet
 295 // If there is a TransferBuffer, the TransferBufferLength contains the length of the buffer
 296
 297
 298     virtual NTSTATUS InitializeWithSetupPacket(IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket,
 299                                                IN ULONG TransferBufferLength,
 300                                                IN PVOID TransferBuffer) = 0;
 301
 302 //
 303 //TODO: find required parameters for different packet types
 304 //
 305
 306
 307 //-----------------------------------------------------------------------------------------
 308 //
 309 // SetEndPoint
 310 //
 311 // Description: sets the endpoint of the request.
 312
 313     virtual NTSTATUS SetEndPoint(PUSB_ENDPOINT_DESCRIPTOR EndPoint);
 314
 315 //-----------------------------------------------------------------------------------------
 316 //
 317 // SetCompletionDetails
 318 //
 319 // Description: sets up how the request should be completed
 320 // If an irp is passed, then it is completed with status code of the
 321 // CompletionCallback or CancelCallback
 322 // If an event is passed, then the event is signaled
 323
 324     virtual NTSTATUS SetCompletionDetails(IN OPTIONAL PIRP Irp,
 325                                           IN OPTIONAL PKEVENT Event) = 0;
 326
 327 //-----------------------------------------------------------------------------------------
 328 //
 329 // CompletionCallback
 330 //
 331 // Description: called when request has been completed. It is called when
 332 // IUSBQueue completes the request
 333
 334     virtual VOID CompletionCallback(IN NTSTATUS NtStatusCode,
 335                                     IN ULONG UrbStatusCode) = 0;
 336
 337 //-----------------------------------------------------------------------------------------
 338 //
 339 // CancelCallback
 340 //
 341 // Description: called when request is cancelled. Called by IUSBQueue
 342
 343     virtual VOID CancelCallback(IN NTSTATUS NtStatusCode) = 0;
 344
 345 };
 346
 347 //=========================================================================================
 348 //
 349 // class IUSBQueue
 350 //
 351 // Description: This class manages pending requests
 352 //
 353
 354 DECLARE_INTERFACE_(IUSBQueue, IUnknown)
 355 {
 356     DEFINE_ABSTRACT_UNKNOWN()
 357
 358 //-----------------------------------------------------------------------------------------
 359 //
 360 // Initialize
 361 //
 362 // Description: initializes the object
 363
 364     virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Hardware,
 365                                 IN OPTIONAL PKSPIN_LOCK Lock,
 366                                 IN PDMAMEMORYMANAGER MemoryManager) = 0;
 367
 368 //-----------------------------------------------------------------------------------------
 369 //
 370 // GetPendingRequestCount
 371 //
 372 // Description: returns the number of pending requests
 373
 374     virtual ULONG GetPendingRequestCount() = 0;
 375
 376 //-----------------------------------------------------------------------------------------
 377 //
 378 // AddUSBRequest
 379 //
 380 // Description: adds an usb request to the queue.
 381 // Returns status success when successful
 382
 383     virtual NTSTATUS AddUSBRequest(IUSBRequest * Request) = 0;
 384
 385 //-----------------------------------------------------------------------------------------
 386 //
 387 // CancelRequests()
 388 //
 389 // Description: cancels all requests
 390
 391     virtual NTSTATUS CancelRequests() = 0;
 392
 393 //-----------------------------------------------------------------------------------------
 394 //
 395 // CreateUSBRequest
 396 //
 397 // Description: creates an usb request
 398
 399     virtual NTSTATUS CreateUSBRequest(IUSBRequest **OutRequest) = 0;
 400 };
 401
 402 //=========================================================================================
 403 //
 404 // class IHubController
 405 //
 406 // Description: This class implements a hub controller
 407 //
 408
 409 DECLARE_INTERFACE_(IHubController, IUnknown)
 410 {
 411     DEFINE_ABSTRACT_UNKNOWN()
 412
 413 //----------------------------------------------------------------------------------------
 414 //
 415 // Initialize
 416 //
 417 // Description: Initializes the hub controller
 418
 419     virtual NTSTATUS Initialize(IN PDRIVER_OBJECT DriverObject,
 420                                 IN PHCDCONTROLLER Controller,
 421                                 IN PUSBHARDWAREDEVICE Device,
 422                                 IN BOOLEAN IsRootHubDevice,
 423                                 IN ULONG DeviceAddress) = 0;
 424
 425 //----------------------------------------------------------------------------------------
 426 //
 427 // GetHubControllerDeviceObject
 428 //
 429 // Description: Returns the hub controller device object
 430
 431     virtual NTSTATUS GetHubControllerDeviceObject(PDEVICE_OBJECT * HubDeviceObject) = 0;
 432
 433 };
 434
 435 typedef IHubController *PHUBCONTROLLER;
 436
 437 //=========================================================================================
 438 //
 439 // class IDispatchIrp
 440 //
 441 // Description: This class is used to handle irp dispatch requests
 442 //
 443
 444 DECLARE_INTERFACE_(IDispatchIrp, IUnknown)
 445 {
 446     DEFINE_ABSTRACT_UNKNOWN()
 447
 448 //-----------------------------------------------------------------------------------------
 449 //
 450 // HandlePnp
 451 //
 452 // Description: This function handles all pnp requests
 453
 454     virtual NTSTATUS HandlePnp(IN PDEVICE_OBJECT DeviceObject,
 455                                IN OUT PIRP Irp) = 0;
 456
 457 //-----------------------------------------------------------------------------------------
 458 //
 459 // HandlePower
 460 //
 461 // Description: This function handles all power pnp requests
 462 //
 463     virtual NTSTATUS HandlePower(IN PDEVICE_OBJECT DeviceObject,
 464                                  IN OUT PIRP Irp) = 0;
 465
 466 //-----------------------------------------------------------------------------------------
 467 //
 468 // HandleDeviceControl
 469 //
 470 // Description: handles device io control requests
 471
 472     virtual NTSTATUS HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject,
 473                                          IN OUT PIRP Irp) = 0;
 474 };
 475
 476 typedef IDispatchIrp *PDISPATCHIRP;
 477
 478 #endif