2 #ifndef COMMON_INTERFACES_HPP
3 #define COMMON_INTERFACES_HPP
5 typedef struct _USB_ENDPOINT
7 USB_ENDPOINT_DESCRIPTOR EndPointDescriptor
;
11 } USB_ENDPOINT
, *PUSB_ENDPOINT
;
13 typedef struct _USB_INTERFACE
16 PUSB_INTERFACE_DESCRIPTOR InterfaceDescriptor
;
17 USB_ENDPOINT EndPoints
[1];
18 } USB_INTERFACE
, *PUSB_INTERFACE
;
22 PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor
;
23 LIST_ENTRY InterfaceList
;
24 }USB_CONFIGURATION
, *PUSB_CONFIGURATION
;
26 //---------------------------------------------------------------------------
29 // --------------------------------------------------------------------
30 // | IRootHCDController |
31 // | IHCDController Intel USB Universal Host Controller - 3A37 |
32 // | IHCDController - Intel USB Universal HostController - 3A38 |
33 // | IHCDController - Intel USB Universal HostController - 3A38 |
34 // |------------------------------------------------------------------|
37 // IHCDController Intel USB Universal Host Controller - 3A37
41 // IUSBQueue <- interacts with -> IUSBRequest
44 // Each IHCDController creates an IUSBHardwareDevice class upon initialization. The
45 // IUSBHardwardeDevice class is used to abstract usb controller specifics. The IHubController
46 // manages all attached devices and handles hub control ioctl requests.
48 // Each IUSBHardwareDevice has one IDMAMemoryManager and one IUSBQueue. The IDMAMemoryManager
49 // is used to handle dma memory allocations. The IUSBQueue manages requests which are send to the
50 // usb hardware. See IUSBRequest class for details.
54 //=========================================================================================
56 // class IRootHCDController
58 // Description: This class serves as the root host controller. The host controller mantains
59 // a list of registered controllers and provides support functions for the host controllers
61 struct IHCDController
;
63 DECLARE_INTERFACE_(IRootHCDController
, IUnknown
)
65 DEFINE_ABSTRACT_UNKNOWN()
67 //-----------------------------------------------------------------------------------------
71 // Description: This function initializes the root host controller. It allocates the resources
72 // required to manage the registered controllers
74 virtual NTSTATUS
Initialize() = 0;
76 //-----------------------------------------------------------------------------------------
80 // Description: this function registers a host controller with the root host controller
82 virtual NTSTATUS
RegisterHCD(struct IHCDController
* Controller
) = 0;
84 //-----------------------------------------------------------------------------------------
88 // Description: this function unregistes a host controller
90 virtual NTSTATUS
UnregisterHCD(struct IHCDController
* Controller
) = 0;
92 //-----------------------------------------------------------------------------------------
96 // Description: returns the number of host controllers registered
98 virtual ULONG
GetControllerCount() = 0;
102 typedef IRootHCDController
*PROOTHDCCONTROLLER
;
104 //=========================================================================================
106 // class IHCDController
108 // Description: This class is used to manage a single USB host controller
111 DECLARE_INTERFACE_(IHCDController
, IUnknown
)
113 DEFINE_ABSTRACT_UNKNOWN()
115 //-----------------------------------------------------------------------------------------
119 // Description: This function initializes the IHCDController implementation.
120 // It creates an IUSBHardwareDevice object and initializes it. It also registeres itself with
121 // the IRootHCDController
123 virtual NTSTATUS
Initialize(IN PROOTHDCCONTROLLER RootHCDController
,
124 IN PDRIVER_OBJECT DriverObject
,
125 IN PDEVICE_OBJECT PhysicalDeviceObject
) = 0;
129 typedef IHCDController
*PHCDCONTROLLER
;
132 //=========================================================================================
134 // class IUSBHardwareDevice
136 // Description: This class provides access to the usb hardware controller
139 struct IDMAMemoryManager
;
142 #define DEFINE_ABSTRACT_USBHARDWAREDEVICE() \
143 STDMETHOD_(NTSTATUS, Initialize)( THIS_ \
144 IN PDRIVER_OBJECT DriverObject, \
145 IN PDEVICE_OBJECT FunctionalDeviceObject, \
146 IN PDEVICE_OBJECT PhysicalDeviceObject, \
147 IN PDEVICE_OBJECT LowerDeviceObject) PURE; \
149 STDMETHOD_(NTSTATUS, PnpStart)( THIS_ \
150 IN PCM_RESOURCE_LIST RawResources, \
151 IN PCM_RESOURCE_LIST TranslatedResources) PURE; \
153 STDMETHOD_(NTSTATUS, PnpStop)( THIS) PURE; \
155 STDMETHOD_(NTSTATUS, GetDeviceDetails)( THIS_ \
156 OUT OPTIONAL PUSHORT VendorId, \
157 OUT OPTIONAL PUSHORT DeviceId, \
158 OUT OPTIONAL PULONG NumberOfPorts, \
159 OUT OPTIONAL PULONG Speed) PURE; \
161 STDMETHOD_(NTSTATUS, GetUSBQueue)( THIS_ \
162 OUT struct IUSBQueue **OutUsbQueue) PURE; \
164 STDMETHOD_(NTSTATUS, GetDMA)( THIS_ \
165 OUT struct IDMAMemoryManager **OutDMA) PURE; \
167 STDMETHOD_(NTSTATUS, ResetPort)( THIS_ \
168 IN ULONG PortNumber) PURE; \
170 STDMETHOD_(NTSTATUS, GetPortStatus)( THIS_ \
172 OUT USHORT *PortStatus, \
173 OUT USHORT *PortChange) PURE; \
175 STDMETHOD_(NTSTATUS, ClearPortStatus)( THIS_ \
177 IN ULONG Status) PURE; \
179 STDMETHOD_(NTSTATUS, SetPortFeature)( THIS_ \
181 IN ULONG Feature) PURE; \
183 STDMETHOD_(VOID, SetStatusChangeEndpointCallBack)( THIS_ \
185 IN PVOID Context) PURE; \
187 STDMETHOD_(LPCSTR, GetUSBType)(THIS) PURE;
190 #define IMP_IUSBHARDWAREDEVICE \
191 STDMETHODIMP_(NTSTATUS) Initialize( \
192 IN PDRIVER_OBJECT DriverObject, \
193 IN PDEVICE_OBJECT FunctionalDeviceObject, \
194 IN PDEVICE_OBJECT PhysicalDeviceObject, \
195 IN PDEVICE_OBJECT LowerDeviceObject); \
197 STDMETHODIMP_(NTSTATUS) PnpStart( \
198 IN PCM_RESOURCE_LIST RawResources, \
199 IN PCM_RESOURCE_LIST TranslatedResources); \
201 STDMETHODIMP_(NTSTATUS) PnpStop(VOID); \
203 STDMETHODIMP_(NTSTATUS) GetDeviceDetails( \
204 OUT OPTIONAL PUSHORT VendorId, \
205 OUT OPTIONAL PUSHORT DeviceId, \
206 OUT OPTIONAL PULONG NumberOfPorts, \
207 OUT OPTIONAL PULONG Speed); \
209 STDMETHODIMP_(NTSTATUS) GetUSBQueue( \
210 OUT struct IUSBQueue **OutUsbQueue); \
212 STDMETHODIMP_(NTSTATUS) GetDMA( \
213 OUT struct IDMAMemoryManager **OutDMA); \
215 STDMETHODIMP_(NTSTATUS) ResetPort( \
216 IN ULONG PortNumber); \
218 STDMETHODIMP_(NTSTATUS) GetPortStatus( \
220 OUT USHORT *PortStatus, \
221 OUT USHORT *PortChange); \
223 STDMETHODIMP_(NTSTATUS) ClearPortStatus( \
227 STDMETHODIMP_(NTSTATUS) SetPortFeature( \
231 STDMETHODIMP_(VOID) SetStatusChangeEndpointCallBack( \
235 STDMETHODIMP_(LPCSTR) GetUSBType();
237 DECLARE_INTERFACE_(IUSBHardwareDevice
, IUnknown
)
239 DEFINE_ABSTRACT_UNKNOWN()
240 DEFINE_ABSTRACT_USBHARDWAREDEVICE()
243 typedef IUSBHardwareDevice
*PUSBHARDWAREDEVICE
;
246 //=========================================================================================
248 // class IDMAMemoryManager
250 // Description: This class provides access to the dma buffer. It provides methods to
251 // allocate and free from the dma buffer
254 DECLARE_INTERFACE_(IDMAMemoryManager
, IUnknown
)
256 DEFINE_ABSTRACT_UNKNOWN()
258 //-----------------------------------------------------------------------------------------
262 // Description: initializes the memory manager
264 virtual NTSTATUS
Initialize(IN PUSBHARDWAREDEVICE Device
,
266 IN ULONG DmaBufferSize
,
267 IN PVOID VirtualBase
,
268 IN PHYSICAL_ADDRESS PhysicalAddress
,
269 IN ULONG DefaultBlockSize
) = 0;
271 //-----------------------------------------------------------------------------------------
275 // Description: allocates block of memory from allocator
277 virtual NTSTATUS
Allocate(IN ULONG Size
,
278 OUT PVOID
*OutVirtualBase
,
279 OUT PPHYSICAL_ADDRESS OutPhysicalAddress
) = 0;
282 //-----------------------------------------------------------------------------------------
286 // Description: releases memory block
288 virtual NTSTATUS
Release(IN PVOID VirtualBase
,
293 typedef IDMAMemoryManager
*PDMAMEMORYMANAGER
;
296 //=========================================================================================
300 // Description: This class is used to issue request to usb controller. The class is
301 // initialized using InitializeXXX methods. You also need to call SetEndpoint to define the endpoint
302 // In addition you can call SetCompletionDetails if you need to wait for the end of
303 // the request or want to complete an irp. You call AddUSBRequest to add the request to the queue.
304 // Once the request is completed the CompletionCallback is invoked. The CompletionCallback
305 // will take care of any completion details which have been set. If the request is cancelled, the
306 // CancelCallback routine is invoked.
311 #define DEFINE_ABSTRACT_USBREQUEST() \
312 STDMETHOD_(NTSTATUS, InitializeWithSetupPacket)( THIS_ \
313 IN PDMAMEMORYMANAGER DmaManager, \
314 IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket, \
315 IN struct IUSBDevice *Device, \
316 IN OPTIONAL struct _USB_ENDPOINT *EndpointDescriptor, \
317 IN OUT ULONG TransferBufferLength, \
318 IN OUT PMDL TransferBuffer) PURE; \
320 STDMETHOD_(NTSTATUS, InitializeWithIrp)( THIS_ \
321 IN PDMAMEMORYMANAGER DmaManager, \
322 IN struct IUSBDevice *Device, \
323 IN OUT PIRP Irp) PURE; \
325 STDMETHOD_(BOOLEAN, IsRequestComplete)( THIS) PURE; \
327 STDMETHOD_(ULONG, GetTransferType)( THIS) PURE; \
329 STDMETHOD_(VOID, GetResultStatus)( THIS_ \
330 OUT OPTIONAL NTSTATUS * NtStatusCode, \
331 OUT OPTIONAL PULONG UrbStatusCode) PURE;
333 #define IMP_IUSBREQUEST \
334 STDMETHODIMP_(NTSTATUS) InitializeWithSetupPacket( \
335 IN PDMAMEMORYMANAGER DmaManager, \
336 IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket, \
337 IN struct IUSBDevice *Device, \
338 IN OPTIONAL struct _USB_ENDPOINT *EndpointDescriptor, \
339 IN OUT ULONG TransferBufferLength, \
340 IN OUT PMDL TransferBuffer); \
342 STDMETHODIMP_(NTSTATUS) InitializeWithIrp( \
343 IN PDMAMEMORYMANAGER DmaManager, \
344 IN struct IUSBDevice *Device, \
347 STDMETHODIMP_(BOOLEAN) IsRequestComplete(VOID); \
349 STDMETHODIMP_(ULONG) GetTransferType(VOID); \
351 STDMETHODIMP_(VOID) GetResultStatus( \
352 OUT OPTIONAL NTSTATUS * NtStatusCode, \
353 OUT OPTIONAL PULONG UrbStatusCode);
355 DECLARE_INTERFACE_(IUSBRequest
, IUnknown
)
357 DEFINE_ABSTRACT_UNKNOWN()
358 DEFINE_ABSTRACT_USBREQUEST()
362 typedef IUSBRequest
*PUSBREQUEST
;
364 //=========================================================================================
368 // Description: This class manages pending requests
371 #define DEFINE_ABSTRACT_USBQUEUE() \
372 STDMETHOD_(NTSTATUS, Initialize)( THIS_ \
373 IN PUSBHARDWAREDEVICE Hardware, \
374 IN PDMA_ADAPTER AdapterObject, \
375 IN PDMAMEMORYMANAGER MemManager, \
376 IN OPTIONAL PKSPIN_LOCK Lock) PURE; \
378 STDMETHOD_(NTSTATUS, AddUSBRequest)( THIS_ \
379 IN IUSBRequest * Request) PURE; \
381 STDMETHOD_(NTSTATUS, CreateUSBRequest)( THIS_ \
382 IN IUSBRequest **OutRequest) PURE; \
384 STDMETHOD_(NTSTATUS, AbortDevicePipe)( THIS_ \
385 IN UCHAR DeviceAddress, \
386 IN PUSB_ENDPOINT_DESCRIPTOR EndpointDescriptor) PURE;
388 #define IMP_IUSBQUEUE \
389 STDMETHODIMP_(NTSTATUS) Initialize( \
390 IN PUSBHARDWAREDEVICE Hardware, \
391 IN PDMA_ADAPTER AdapterObject, \
392 IN PDMAMEMORYMANAGER MemManager, \
393 IN OPTIONAL PKSPIN_LOCK Lock); \
395 STDMETHODIMP_(NTSTATUS) AddUSBRequest( \
396 IN IUSBRequest * Request); \
398 STDMETHODIMP_(NTSTATUS) CreateUSBRequest( \
399 OUT IUSBRequest **OutRequest); \
401 STDMETHODIMP_(NTSTATUS) AbortDevicePipe( \
402 IN UCHAR DeviceAddress, \
403 IN PUSB_ENDPOINT_DESCRIPTOR EndpointDescriptor);
405 DECLARE_INTERFACE_(IUSBQueue
, IUnknown
)
407 DEFINE_ABSTRACT_UNKNOWN()
408 DEFINE_ABSTRACT_USBQUEUE()
411 typedef IUSBQueue
*PUSBQUEUE
;
413 //=========================================================================================
415 // class IHubController
417 // Description: This class implements a hub controller
420 DECLARE_INTERFACE_(IHubController
, IUnknown
)
422 DEFINE_ABSTRACT_UNKNOWN()
424 //----------------------------------------------------------------------------------------
428 // Description: Initializes the hub controller
430 virtual NTSTATUS
Initialize(IN PDRIVER_OBJECT DriverObject
,
431 IN PHCDCONTROLLER Controller
,
432 IN PUSBHARDWAREDEVICE Device
,
433 IN BOOLEAN IsRootHubDevice
,
434 IN ULONG DeviceAddress
) = 0;
436 //----------------------------------------------------------------------------------------
438 // GetHubControllerDeviceObject
440 // Description: Returns the hub controller device object
442 virtual NTSTATUS
GetHubControllerDeviceObject(PDEVICE_OBJECT
* HubDeviceObject
) = 0;
444 //----------------------------------------------------------------------------------------
446 // GetHubControllerSymbolicLink
448 // Description: Returns the symbolic link of the root hub
450 virtual NTSTATUS
GetHubControllerSymbolicLink(ULONG BufferLength
, PVOID Buffer
, PULONG RequiredLength
) = 0;
455 typedef IHubController
*PHUBCONTROLLER
;
457 //=========================================================================================
459 // class IDispatchIrp
461 // Description: This class is used to handle irp dispatch requests
464 DECLARE_INTERFACE_(IDispatchIrp
, IUnknown
)
466 DEFINE_ABSTRACT_UNKNOWN()
468 //-----------------------------------------------------------------------------------------
472 // Description: This function handles all pnp requests
474 virtual NTSTATUS
HandlePnp(IN PDEVICE_OBJECT DeviceObject
,
475 IN OUT PIRP Irp
) = 0;
477 //-----------------------------------------------------------------------------------------
481 // Description: This function handles all power pnp requests
483 virtual NTSTATUS
HandlePower(IN PDEVICE_OBJECT DeviceObject
,
484 IN OUT PIRP Irp
) = 0;
486 //-----------------------------------------------------------------------------------------
488 // HandleDeviceControl
490 // Description: handles device io control requests
492 virtual NTSTATUS
HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject
,
493 IN OUT PIRP Irp
) = 0;
495 //-----------------------------------------------------------------------------------------
497 // HandleSystemControl
499 // Description: handles WMI system control requests
501 virtual NTSTATUS
HandleSystemControl(IN PDEVICE_OBJECT DeviceObject
,
502 IN OUT PIRP Irp
) = 0;
505 typedef IDispatchIrp
*PDISPATCHIRP
;
507 //=========================================================================================
511 // Description: This class is used to abstract details of a usb device
514 DECLARE_INTERFACE_(IUSBDevice
, IUnknown
)
516 DEFINE_ABSTRACT_UNKNOWN()
518 //----------------------------------------------------------------------------------------
522 // Description: Initializes the usb device
524 virtual NTSTATUS
Initialize(IN PHUBCONTROLLER HubController
,
525 IN PUSBHARDWAREDEVICE Device
,
528 IN ULONG PortStatus
) = 0;
530 //-----------------------------------------------------------------------------------------
534 // Description: returns true when device is a hub
536 virtual BOOLEAN
IsHub() = 0;
538 //-----------------------------------------------------------------------------------------
542 // Description: gets the parent device of the this device
544 virtual NTSTATUS
GetParent(PVOID
* Parent
) = 0;
546 //-----------------------------------------------------------------------------------------
550 // Description: gets the device address of the this device
552 virtual UCHAR
GetDeviceAddress() = 0;
555 //-----------------------------------------------------------------------------------------
559 // Description: gets the port to which this device is connected
561 virtual ULONG
GetPort() = 0;
563 //-----------------------------------------------------------------------------------------
567 // Description: gets the speed of the device
569 virtual USB_DEVICE_SPEED
GetSpeed() = 0;
571 //-----------------------------------------------------------------------------------------
575 // Description: gets the type of the device, either 1.1 or 2.0 device
577 virtual USB_DEVICE_TYPE
GetType() = 0;
579 //-----------------------------------------------------------------------------------------
583 // Description: gets the device state
585 virtual ULONG
GetState() = 0;
587 //-----------------------------------------------------------------------------------------
589 // SetDeviceHandleData
591 // Description: sets device handle data
593 virtual void SetDeviceHandleData(PVOID Data
) = 0;
595 //-----------------------------------------------------------------------------------------
599 // Description: sets device handle data
601 virtual NTSTATUS
SetDeviceAddress(UCHAR DeviceAddress
) = 0;
603 //-----------------------------------------------------------------------------------------
605 // GetDeviceDescriptor
607 // Description: sets device handle data
609 virtual void GetDeviceDescriptor(PUSB_DEVICE_DESCRIPTOR DeviceDescriptor
) = 0;
611 //-----------------------------------------------------------------------------------------
613 // GetConfigurationValue
615 // Description: gets current selected configuration index
617 virtual UCHAR
GetConfigurationValue() = 0;
619 //-----------------------------------------------------------------------------------------
623 // Description: submits an irp containing an urb
625 virtual NTSTATUS
SubmitIrp(PIRP Irp
) = 0;
627 //-----------------------------------------------------------------------------------------
629 // GetConfigurationDescriptors
631 // Description: returns one or more configuration descriptors
633 virtual VOID
GetConfigurationDescriptors(IN PUSB_CONFIGURATION_DESCRIPTOR ConfigDescriptorBuffer
,
634 IN ULONG BufferLength
,
635 OUT PULONG OutBufferLength
) = 0;
637 //-----------------------------------------------------------------------------------------
639 // Description: returns length of configuration descriptors
641 virtual ULONG
GetConfigurationDescriptorsLength() = 0;
643 //-----------------------------------------------------------------------------------------
647 // Description: submits an setup packet. The usb device will then create an usb request from it and submit it to the queue
649 virtual NTSTATUS
SubmitSetupPacket(IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket
,
650 IN OUT ULONG BufferLength
,
651 OUT PVOID Buffer
) = 0;
653 //-----------------------------------------------------------------------------------------
655 // SelectConfiguration
657 // Description: selects a configuration
659 virtual NTSTATUS
SelectConfiguration(IN PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor
,
660 IN PUSBD_INTERFACE_INFORMATION Interface
,
661 OUT USBD_CONFIGURATION_HANDLE
*ConfigurationHandle
) = 0;
663 //-----------------------------------------------------------------------------------------
665 // SelectConfiguration
667 // Description: selects a interface of an configuration
669 virtual NTSTATUS
SelectInterface(IN USBD_CONFIGURATION_HANDLE ConfigurationHandle
,
670 IN OUT PUSBD_INTERFACE_INFORMATION Interface
) = 0;
672 //-----------------------------------------------------------------------------------------
676 // Description: aborts all pending requsts
678 virtual NTSTATUS
AbortPipe(IN PUSB_ENDPOINT_DESCRIPTOR EndpointDescriptor
) = 0;
680 //-----------------------------------------------------------------------------------------
684 // Description: aborts all pending requsts
686 virtual UCHAR
GetMaxPacketSize() = 0;
689 typedef IUSBDevice
*PUSBDEVICE
;