5 //---------------------------------------------------------------------------
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 // |------------------------------------------------------------------|
16 // IHCDController Intel USB Universal Host Controller - 3A37
20 // IUSBQueue <- interacts with -> IUSBRequest
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.
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.
33 //=========================================================================================
35 // class IRootHCDController
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
40 struct IHCDController
;
42 DECLARE_INTERFACE_(IRootHCDController
, IUnknown
)
44 DEFINE_ABSTRACT_UNKNOWN()
46 //-----------------------------------------------------------------------------------------
50 // Description: This function initializes the root host controller. It allocates the resources
51 // required to manage the registered controllers
53 virtual NTSTATUS
Initialize() = 0;
55 //-----------------------------------------------------------------------------------------
59 // Description: this function registers a host controller with the root host controller
61 virtual NTSTATUS
RegisterHCD(struct IHCDController
* Controller
) = 0;
63 //-----------------------------------------------------------------------------------------
67 // Description: this function unregistes a host controller
69 virtual NTSTATUS
UnregisterHCD(struct IHCDController
* Controller
) = 0;
71 //-----------------------------------------------------------------------------------------
75 // Description: returns the number of host controllers registered
77 virtual ULONG
GetControllerCount() = 0;
81 typedef IRootHCDController
*PROOTHDCCONTROLLER
;
83 //=========================================================================================
85 // class IHCDController
87 // Description: This class is used to manage a single USB host controller
90 DECLARE_INTERFACE_(IHCDController
, IUnknown
)
92 DEFINE_ABSTRACT_UNKNOWN()
94 //-----------------------------------------------------------------------------------------
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
102 virtual NTSTATUS
Initialize(IN PROOTHDCCONTROLLER RootHCDController
,
103 IN PDRIVER_OBJECT DriverObject
,
104 IN PDEVICE_OBJECT PhysicalDeviceObject
) = 0;
106 //-----------------------------------------------------------------------------------------
110 // Description: This function handles all pnp requests
112 virtual NTSTATUS
HandlePnp(IN PDEVICE_OBJECT DeviceObject
,
113 IN OUT PIRP Irp
) = 0;
115 //-----------------------------------------------------------------------------------------
119 // Description: This function handles all power pnp requests
121 virtual NTSTATUS
HandlePower(IN PDEVICE_OBJECT DeviceObject
,
122 IN OUT PIRP Irp
) = 0;
124 //-----------------------------------------------------------------------------------------
126 // HandleDeviceControl
128 // Description: handles device io control requests
130 virtual NTSTATUS
HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject
,
131 IN OUT PIRP Irp
) = 0;
135 typedef IHCDController
*PHCDCONTROLLER
;
138 //=========================================================================================
140 // class IUSBHardwareDevice
142 // Description: This class provides access to the usb hardware controller
145 struct IDMAMemoryManager
;
148 DECLARE_INTERFACE_(IUSBHardwareDevice
, IUnknown
)
150 DEFINE_ABSTRACT_UNKNOWN()
152 //-----------------------------------------------------------------------------------------
156 // Description: Initializes the usb device controller
158 virtual NTSTATUS
Initialize(PDRIVER_OBJECT DriverObject
,
159 PDEVICE_OBJECT FunctionalDeviceObject
,
160 PDEVICE_OBJECT PhysicalDeviceObject
,
161 PDEVICE_OBJECT LowerDeviceObject
) = 0;
163 //-----------------------------------------------------------------------------------------
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
170 virtual NTSTATUS
PnpStart(PCM_RESOURCE_LIST RawResources
,
171 PCM_RESOURCE_LIST TranslatedResources
) = 0;
173 //-----------------------------------------------------------------------------------------
177 // Description: handles pnp stop request from device. It unregisteres the interrupt, releases ports and dma object.
179 virtual NTSTATUS
PnpStop(void) = 0;
181 //-----------------------------------------------------------------------------------------
185 // Description: handles power requests
187 virtual NTSTATUS
HandlePower(PIRP Irp
) = 0;
189 //-----------------------------------------------------------------------------------------
193 // Description: returns the device details such as vendor id, device id, number of ports and speed
195 virtual NTSTATUS
GetDeviceDetails(OUT OPTIONAL PULONG VendorId
,
196 OUT OPTIONAL PULONG DeviceId
,
197 OUT OPTIONAL PULONG NumberOfPorts
,
198 OUT OPTIONAL PULONG Speed
) = 0;
200 //-----------------------------------------------------------------------------------------
202 // GetDmaMemoryManager
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
208 virtual NTSTATUS
GetDmaMemoryManager(OUT
struct IDMAMemoryManager
**OutMemoryManager
) = 0;
210 //-----------------------------------------------------------------------------------------
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
218 virtual NTSTATUS
GetUSBQueue(OUT
struct IUSBQueue
**OutUsbQueue
) = 0;
220 //-----------------------------------------------------------------------------------------
224 // Description: this function resets the controller
225 // Returns STATUS_SUCCESS when the controller was successfully reset
227 virtual NTSTATUS
ResetController() = 0;
229 //-----------------------------------------------------------------------------------------
233 // Description: this functions resets the port on the controller
236 virtual NTSTATUS
ResetPort(ULONG PortNumber
) = 0;
238 //-----------------------------------------------------------------------------------------
242 // Description: acquires the device lock
244 virtual KIRQL
AcquireDeviceLock(void) = 0;
246 //-----------------------------------------------------------------------------------------
250 // Description: releases the device lock
252 virtual void ReleaseDeviceLock(KIRQL OldLevel
) = 0;
255 typedef IUSBHardwareDevice
*PUSBHARDWAREDEVICE
;
258 //=========================================================================================
260 // class IDMAMemoryManager
262 // Description: This class provides access to the dma buffer. It provides methods to
263 // allocate and free from the dma buffer
266 DECLARE_INTERFACE_(IDMAMemoryManager
, IUnknown
)
268 DEFINE_ABSTRACT_UNKNOWN()
270 //-----------------------------------------------------------------------------------------
274 // Description: initializes the memory manager
276 virtual NTSTATUS
Initialize(IN PUSBHARDWAREDEVICE Device
,
278 IN ULONG DmaBufferSize
,
279 IN PVOID VirtualBase
,
280 IN PHYSICAL_ADDRESS PhysicalAddress
,
281 IN ULONG DefaultBlockSize
) = 0;
283 //-----------------------------------------------------------------------------------------
287 // Description: allocates block of memory from allocator
289 virtual NTSTATUS
Allocate(IN ULONG Size
,
290 OUT PVOID
*OutVirtualBase
,
291 OUT PPHYSICAL_ADDRESS
*OutPhysicalAddress
) = 0;
294 //-----------------------------------------------------------------------------------------
298 // Description: releases memory block
300 virtual NTSTATUS
Release(IN PVOID VirtualBase
,
305 typedef IDMAMemoryManager
*PDMAMEMORYMANAGER
;
308 //=========================================================================================
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.
321 DECLARE_INTERFACE_(IUSBRequest
, IUnknown
)
323 DEFINE_ABSTRACT_UNKNOWN()
325 //-----------------------------------------------------------------------------------------
327 // InitializeWithSetupPacket
329 // Description: initializes the request packet with an setup packet
330 // If there is a TransferBuffer, the TransferBufferLength contains the length of the buffer
333 virtual NTSTATUS
InitializeWithSetupPacket(IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket
,
334 IN ULONG TransferBufferLength
,
335 IN PVOID TransferBuffer
) = 0;
338 //TODO: find required parameters for different packet types
342 //-----------------------------------------------------------------------------------------
346 // Description: sets the endpoint of the request.
348 virtual NTSTATUS
SetEndPoint(PUSB_ENDPOINT_DESCRIPTOR EndPoint
);
350 //-----------------------------------------------------------------------------------------
352 // SetCompletionDetails
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
359 virtual NTSTATUS
SetCompletionDetails(IN OPTIONAL PIRP Irp
,
360 IN OPTIONAL PKEVENT Event
) = 0;
362 //-----------------------------------------------------------------------------------------
364 // CompletionCallback
366 // Description: called when request has been completed. It is called when
367 // IUSBQueue completes the request
369 virtual VOID
CompletionCallback(IN NTSTATUS NtStatusCode
,
370 IN ULONG UrbStatusCode
) = 0;
372 //-----------------------------------------------------------------------------------------
376 // Description: called when request is cancelled. Called by IUSBQueue
378 virtual VOID
CancelCallback(IN NTSTATUS NtStatusCode
) = 0;
382 //=========================================================================================
386 // Description: This class manages pending requests
389 DECLARE_INTERFACE_(IUSBQueue
, IUnknown
)
391 DEFINE_ABSTRACT_UNKNOWN()
393 //-----------------------------------------------------------------------------------------
397 // Description: initializes the object
399 virtual NTSTATUS
Initialize(IN PUSBHARDWAREDEVICE Hardware
,
400 IN OPTIONAL PKSPIN_LOCK Lock
,
401 IN PDMAMEMORYMANAGER MemoryManager
) = 0;
403 //-----------------------------------------------------------------------------------------
405 // GetPendingRequestCount
407 // Description: returns the number of pending requests
409 virtual ULONG
GetPendingRequestCount() = 0;
411 //-----------------------------------------------------------------------------------------
415 // Description: adds an usb request to the queue.
416 // Returns status success when successful
418 virtual NTSTATUS
AddUSBRequest(IUSBRequest
* Request
) = 0;
420 //-----------------------------------------------------------------------------------------
424 // Description: cancels all requests
426 virtual NTSTATUS
CancelRequests() = 0;
428 //-----------------------------------------------------------------------------------------
432 // Description: creates an usb request
434 virtual NTSTATUS
CreateUSBRequest(IUSBRequest
**OutRequest
) = 0;
437 //=========================================================================================
439 // class IHubController
441 // Description: This class implements a hub controller
444 DECLARE_INTERFACE_(IHubController
, IUnknown
)
446 DEFINE_ABSTRACT_UNKNOWN()
448 //----------------------------------------------------------------------------------------
452 // Description: Initializes the hub controller
454 virtual NTSTATUS
Initialize(IN PHCDCONTROLLER Controller
,
455 IN PUSBHARDWAREDEVICE Device
,
456 IN BOOLEAN IsRootHubDevice
,
457 IN ULONG DeviceAddress
);
459 //-----------------------------------------------------------------------------------------
463 // Description: This function handles all pnp requests
465 virtual NTSTATUS
HandlePnp(IN PDEVICE_OBJECT DeviceObject
,
466 IN OUT PIRP Irp
) = 0;
468 //-----------------------------------------------------------------------------------------
472 // Description: This function handles all power pnp requests
474 virtual NTSTATUS
HandlePower(IN PDEVICE_OBJECT DeviceObject
,
475 IN OUT PIRP Irp
) = 0;
477 //-----------------------------------------------------------------------------------------
479 // HandleDeviceControl
481 // Description: handles device io control requests
483 virtual NTSTATUS
HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject
,
484 IN OUT PIRP Irp
) = 0;
487 typedef IHubController
*PHUBCONTROLLER
;