#ifndef COMMON_INTERFACES_HPP
#define COMMON_INTERFACES_HPP
typedef struct _USB_ENDPOINT
{
USB_ENDPOINT_DESCRIPTOR EndPointDescriptor;
UCHAR HubAddress;
UCHAR HubPort;
UCHAR DataToggle;
} USB_ENDPOINT, *PUSB_ENDPOINT;
typedef struct _USB_INTERFACE
{
LIST_ENTRY ListEntry;
PUSB_INTERFACE_DESCRIPTOR InterfaceDescriptor;
USB_ENDPOINT EndPoints[1];
} USB_INTERFACE, *PUSB_INTERFACE;
typedef struct
{
PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor;
LIST_ENTRY InterfaceList;
}USB_CONFIGURATION, *PUSB_CONFIGURATION;
//---------------------------------------------------------------------------
//
// Object Hierarchy
// --------------------------------------------------------------------
// | IRootHCDController |
// | IHCDController Intel USB Universal Host Controller - 3A37 |
// | IHCDController - Intel USB Universal HostController - 3A38 |
// | IHCDController - Intel USB Universal HostController - 3A38 |
// |------------------------------------------------------------------|
//
//
// IHCDController Intel USB Universal Host Controller - 3A37
// IHubController
// IUSBHardwareDevice
// IDMAMemoryManager
// IUSBQueue <- interacts with -> IUSBRequest
//
//
// Each IHCDController creates an IUSBHardwareDevice class upon initialization. The
// IUSBHardwardeDevice class is used to abstract usb controller specifics. The IHubController
// manages all attached devices and handles hub control ioctl requests.
//
// Each IUSBHardwareDevice has one IDMAMemoryManager and one IUSBQueue. The IDMAMemoryManager
// is used to handle dma memory allocations. The IUSBQueue manages requests which are send to the
// usb hardware. See IUSBRequest class for details.
//
//=========================================================================================
//
// class IRootHCDController
//
// Description: This class serves as the root host controller. The host controller mantains
// a list of registered controllers and provides support functions for the host controllers
struct IHCDController;
DECLARE_INTERFACE_(IRootHCDController, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
//-----------------------------------------------------------------------------------------
//
// Initialize
//
// Description: This function initializes the root host controller. It allocates the resources
// required to manage the registered controllers
virtual NTSTATUS Initialize() = 0;
//-----------------------------------------------------------------------------------------
//
// RegisterHCD
//
// Description: this function registers a host controller with the root host controller
virtual NTSTATUS RegisterHCD(struct IHCDController * Controller) = 0;
//-----------------------------------------------------------------------------------------
//
// UnregisterHCD
//
// Description: this function unregistes a host controller
virtual NTSTATUS UnregisterHCD(struct IHCDController * Controller) = 0;
//-----------------------------------------------------------------------------------------
//
// GetControllerCount
//
// Description: returns the number of host controllers registered
virtual ULONG GetControllerCount() = 0;
};
typedef IRootHCDController *PROOTHDCCONTROLLER;
//=========================================================================================
//
// class IHCDController
//
// Description: This class is used to manage a single USB host controller
//
DECLARE_INTERFACE_(IHCDController, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
//-----------------------------------------------------------------------------------------
//
// Initialize
//
// Description: This function initializes the IHCDController implementation.
// It creates an IUSBHardwareDevice object and initializes it. It also registeres itself with
// the IRootHCDController
//
virtual NTSTATUS Initialize(IN PROOTHDCCONTROLLER RootHCDController,
IN PDRIVER_OBJECT DriverObject,
IN PDEVICE_OBJECT PhysicalDeviceObject) = 0;
};
typedef IHCDController *PHCDCONTROLLER;
//=========================================================================================
//
// class IUSBHardwareDevice
//
// Description: This class provides access to the usb hardware controller
//
struct IDMAMemoryManager;
struct IUSBQueue;
#define DEFINE_ABSTRACT_USBHARDWAREDEVICE() \
STDMETHOD_(NTSTATUS, Initialize)( THIS_ \
IN PDRIVER_OBJECT DriverObject, \
IN PDEVICE_OBJECT FunctionalDeviceObject, \
IN PDEVICE_OBJECT PhysicalDeviceObject, \
IN PDEVICE_OBJECT LowerDeviceObject) PURE; \
\
STDMETHOD_(NTSTATUS, PnpStart)( THIS_ \
IN PCM_RESOURCE_LIST RawResources, \
IN PCM_RESOURCE_LIST TranslatedResources) PURE; \
\
STDMETHOD_(NTSTATUS, PnpStop)( THIS) PURE; \
\
STDMETHOD_(NTSTATUS, GetDeviceDetails)( THIS_ \
OUT OPTIONAL PUSHORT VendorId, \
OUT OPTIONAL PUSHORT DeviceId, \
OUT OPTIONAL PULONG NumberOfPorts, \
OUT OPTIONAL PULONG Speed) PURE; \
\
STDMETHOD_(NTSTATUS, GetUSBQueue)( THIS_ \
OUT struct IUSBQueue **OutUsbQueue) PURE; \
\
STDMETHOD_(NTSTATUS, GetDMA)( THIS_ \
OUT struct IDMAMemoryManager **OutDMA) PURE; \
\
STDMETHOD_(NTSTATUS, ResetPort)( THIS_ \
IN ULONG PortNumber) PURE; \
\
STDMETHOD_(NTSTATUS, GetPortStatus)( THIS_ \
IN ULONG PortId, \
OUT USHORT *PortStatus, \
OUT USHORT *PortChange) PURE; \
\
STDMETHOD_(NTSTATUS, ClearPortStatus)( THIS_ \
IN ULONG PortId, \
IN ULONG Status) PURE; \
\
STDMETHOD_(NTSTATUS, SetPortFeature)( THIS_ \
IN ULONG PortId, \
IN ULONG Feature) PURE; \
\
STDMETHOD_(VOID, SetStatusChangeEndpointCallBack)( THIS_ \
IN PVOID CallBack, \
IN PVOID Context) PURE; \
\
STDMETHOD_(LPCSTR, GetUSBType)(THIS) PURE;
#define IMP_IUSBHARDWAREDEVICE \
STDMETHODIMP_(NTSTATUS) Initialize( \
IN PDRIVER_OBJECT DriverObject, \
IN PDEVICE_OBJECT FunctionalDeviceObject, \
IN PDEVICE_OBJECT PhysicalDeviceObject, \
IN PDEVICE_OBJECT LowerDeviceObject); \
\
STDMETHODIMP_(NTSTATUS) PnpStart( \
IN PCM_RESOURCE_LIST RawResources, \
IN PCM_RESOURCE_LIST TranslatedResources); \
\
STDMETHODIMP_(NTSTATUS) PnpStop(VOID); \
\
STDMETHODIMP_(NTSTATUS) GetDeviceDetails( \
OUT OPTIONAL PUSHORT VendorId, \
OUT OPTIONAL PUSHORT DeviceId, \
OUT OPTIONAL PULONG NumberOfPorts, \
OUT OPTIONAL PULONG Speed); \
\
STDMETHODIMP_(NTSTATUS) GetUSBQueue( \
OUT struct IUSBQueue **OutUsbQueue); \
\
STDMETHODIMP_(NTSTATUS) GetDMA( \
OUT struct IDMAMemoryManager **OutDMA); \
\
STDMETHODIMP_(NTSTATUS) ResetPort( \
IN ULONG PortNumber); \
\
STDMETHODIMP_(NTSTATUS) GetPortStatus( \
IN ULONG PortId, \
OUT USHORT *PortStatus, \
OUT USHORT *PortChange); \
\
STDMETHODIMP_(NTSTATUS) ClearPortStatus( \
IN ULONG PortId, \
IN ULONG Status); \
\
STDMETHODIMP_(NTSTATUS) SetPortFeature( \
IN ULONG PortId, \
IN ULONG Feature); \
\
STDMETHODIMP_(VOID) SetStatusChangeEndpointCallBack( \
IN PVOID CallBack, \
IN PVOID Context); \
\
STDMETHODIMP_(LPCSTR) GetUSBType();
DECLARE_INTERFACE_(IUSBHardwareDevice, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
DEFINE_ABSTRACT_USBHARDWAREDEVICE()
};
typedef IUSBHardwareDevice *PUSBHARDWAREDEVICE;
//=========================================================================================
//
// class IDMAMemoryManager
//
// Description: This class provides access to the dma buffer. It provides methods to
// allocate and free from the dma buffer
//
DECLARE_INTERFACE_(IDMAMemoryManager, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
//-----------------------------------------------------------------------------------------
//
// Initialize
//
// Description: initializes the memory manager
virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Device,
IN PKSPIN_LOCK Lock,
IN ULONG DmaBufferSize,
IN PVOID VirtualBase,
IN PHYSICAL_ADDRESS PhysicalAddress,
IN ULONG DefaultBlockSize) = 0;
//-----------------------------------------------------------------------------------------
//
// Allocate
//
// Description: allocates block of memory from allocator
virtual NTSTATUS Allocate(IN ULONG Size,
OUT PVOID *OutVirtualBase,
OUT PPHYSICAL_ADDRESS OutPhysicalAddress) = 0;
//-----------------------------------------------------------------------------------------
//
// Free
//
// Description: releases memory block
virtual NTSTATUS Release(IN PVOID VirtualBase,
IN ULONG Size) = 0;
};
typedef IDMAMemoryManager *PDMAMEMORYMANAGER;
//=========================================================================================
//
// class IUSBRequest
//
// Description: This class is used to issue request to usb controller. The class is
// initialized using InitializeXXX methods. You also need to call SetEndpoint to define the endpoint
// In addition you can call SetCompletionDetails if you need to wait for the end of
// the request or want to complete an irp. You call AddUSBRequest to add the request to the queue.
// Once the request is completed the CompletionCallback is invoked. The CompletionCallback
// will take care of any completion details which have been set. If the request is cancelled, the
// CancelCallback routine is invoked.
//
struct IUSBDevice;
#define DEFINE_ABSTRACT_USBREQUEST() \
STDMETHOD_(NTSTATUS, InitializeWithSetupPacket)( THIS_ \
IN PDMAMEMORYMANAGER DmaManager, \
IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket, \
IN struct IUSBDevice *Device, \
IN OPTIONAL struct _USB_ENDPOINT *EndpointDescriptor, \
IN OUT ULONG TransferBufferLength, \
IN OUT PMDL TransferBuffer) PURE; \
\
STDMETHOD_(NTSTATUS, InitializeWithIrp)( THIS_ \
IN PDMAMEMORYMANAGER DmaManager, \
IN struct IUSBDevice *Device, \
IN OUT PIRP Irp) PURE; \
\
STDMETHOD_(BOOLEAN, IsRequestComplete)( THIS) PURE; \
\
STDMETHOD_(ULONG, GetTransferType)( THIS) PURE; \
\
STDMETHOD_(VOID, GetResultStatus)( THIS_ \
OUT OPTIONAL NTSTATUS * NtStatusCode, \
OUT OPTIONAL PULONG UrbStatusCode) PURE;
#define IMP_IUSBREQUEST \
STDMETHODIMP_(NTSTATUS) InitializeWithSetupPacket( \
IN PDMAMEMORYMANAGER DmaManager, \
IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket, \
IN struct IUSBDevice *Device, \
IN OPTIONAL struct _USB_ENDPOINT *EndpointDescriptor, \
IN OUT ULONG TransferBufferLength, \
IN OUT PMDL TransferBuffer); \
\
STDMETHODIMP_(NTSTATUS) InitializeWithIrp( \
IN PDMAMEMORYMANAGER DmaManager, \
IN struct IUSBDevice *Device, \
IN OUT PIRP Irp); \
\
STDMETHODIMP_(BOOLEAN) IsRequestComplete(VOID); \
\
STDMETHODIMP_(ULONG) GetTransferType(VOID); \
\
STDMETHODIMP_(VOID) GetResultStatus( \
OUT OPTIONAL NTSTATUS * NtStatusCode, \
OUT OPTIONAL PULONG UrbStatusCode);
DECLARE_INTERFACE_(IUSBRequest, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
DEFINE_ABSTRACT_USBREQUEST()
};
typedef IUSBRequest *PUSBREQUEST;
//=========================================================================================
//
// class IUSBQueue
//
// Description: This class manages pending requests
//
#define DEFINE_ABSTRACT_USBQUEUE() \
STDMETHOD_(NTSTATUS, Initialize)( THIS_ \
IN PUSBHARDWAREDEVICE Hardware, \
IN PDMA_ADAPTER AdapterObject, \
IN PDMAMEMORYMANAGER MemManager, \
IN OPTIONAL PKSPIN_LOCK Lock) PURE; \
\
STDMETHOD_(NTSTATUS, AddUSBRequest)( THIS_ \
IN IUSBRequest * Request) PURE; \
\
STDMETHOD_(NTSTATUS, CreateUSBRequest)( THIS_ \
IN IUSBRequest **OutRequest) PURE; \
\
STDMETHOD_(NTSTATUS, AbortDevicePipe)( THIS_ \
IN UCHAR DeviceAddress, \
IN PUSB_ENDPOINT_DESCRIPTOR EndpointDescriptor) PURE;
#define IMP_IUSBQUEUE \
STDMETHODIMP_(NTSTATUS) Initialize( \
IN PUSBHARDWAREDEVICE Hardware, \
IN PDMA_ADAPTER AdapterObject, \
IN PDMAMEMORYMANAGER MemManager, \
IN OPTIONAL PKSPIN_LOCK Lock); \
\
STDMETHODIMP_(NTSTATUS) AddUSBRequest( \
IN IUSBRequest * Request); \
\
STDMETHODIMP_(NTSTATUS) CreateUSBRequest( \
OUT IUSBRequest **OutRequest); \
\
STDMETHODIMP_(NTSTATUS) AbortDevicePipe( \
IN UCHAR DeviceAddress, \
IN PUSB_ENDPOINT_DESCRIPTOR EndpointDescriptor);
DECLARE_INTERFACE_(IUSBQueue, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
DEFINE_ABSTRACT_USBQUEUE()
};
typedef IUSBQueue *PUSBQUEUE;
//=========================================================================================
//
// class IHubController
//
// Description: This class implements a hub controller
//
DECLARE_INTERFACE_(IHubController, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
//----------------------------------------------------------------------------------------
//
// Initialize
//
// Description: Initializes the hub controller
virtual NTSTATUS Initialize(IN PDRIVER_OBJECT DriverObject,
IN PHCDCONTROLLER Controller,
IN PUSBHARDWAREDEVICE Device,
IN BOOLEAN IsRootHubDevice,
IN ULONG DeviceAddress) = 0;
//----------------------------------------------------------------------------------------
//
// GetHubControllerDeviceObject
//
// Description: Returns the hub controller device object
virtual NTSTATUS GetHubControllerDeviceObject(PDEVICE_OBJECT * HubDeviceObject) = 0;
//----------------------------------------------------------------------------------------
//
// GetHubControllerSymbolicLink
//
// Description: Returns the symbolic link of the root hub
virtual NTSTATUS GetHubControllerSymbolicLink(ULONG BufferLength, PVOID Buffer, PULONG RequiredLength) = 0;
};
typedef IHubController *PHUBCONTROLLER;
//=========================================================================================
//
// class IDispatchIrp
//
// Description: This class is used to handle irp dispatch requests
//
DECLARE_INTERFACE_(IDispatchIrp, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
//-----------------------------------------------------------------------------------------
//
// HandlePnp
//
// Description: This function handles all pnp requests
virtual NTSTATUS HandlePnp(IN PDEVICE_OBJECT DeviceObject,
IN OUT PIRP Irp) = 0;
//-----------------------------------------------------------------------------------------
//
// HandlePower
//
// Description: This function handles all power pnp requests
//
virtual NTSTATUS HandlePower(IN PDEVICE_OBJECT DeviceObject,
IN OUT PIRP Irp) = 0;
//-----------------------------------------------------------------------------------------
//
// HandleDeviceControl
//
// Description: handles device io control requests
virtual NTSTATUS HandleDeviceControl(IN PDEVICE_OBJECT DeviceObject,
IN OUT PIRP Irp) = 0;
//-----------------------------------------------------------------------------------------
//
// HandleSystemControl
//
// Description: handles WMI system control requests
virtual NTSTATUS HandleSystemControl(IN PDEVICE_OBJECT DeviceObject,
IN OUT PIRP Irp) = 0;
};
typedef IDispatchIrp *PDISPATCHIRP;
//=========================================================================================
//
// class IUSBDevice
//
// Description: This class is used to abstract details of a usb device
//
DECLARE_INTERFACE_(IUSBDevice, IUnknown)
{
DEFINE_ABSTRACT_UNKNOWN()
//----------------------------------------------------------------------------------------
//
// Initialize
//
// Description: Initializes the usb device
virtual NTSTATUS Initialize(IN PHUBCONTROLLER HubController,
IN PUSBHARDWAREDEVICE Device,
IN PVOID Parent,
IN ULONG Port,
IN ULONG PortStatus) = 0;
//-----------------------------------------------------------------------------------------
//
// IsHub
//
// Description: returns true when device is a hub
virtual BOOLEAN IsHub() = 0;
//-----------------------------------------------------------------------------------------
//
// GetParent
//
// Description: gets the parent device of the this device
virtual NTSTATUS GetParent(PVOID * Parent) = 0;
//-----------------------------------------------------------------------------------------
//
// GetDeviceAddress
//
// Description: gets the device address of the this device
virtual UCHAR GetDeviceAddress() = 0;
//-----------------------------------------------------------------------------------------
//
// GetPort
//
// Description: gets the port to which this device is connected
virtual ULONG GetPort() = 0;
//-----------------------------------------------------------------------------------------
//
// GetSpeed
//
// Description: gets the speed of the device
virtual USB_DEVICE_SPEED GetSpeed() = 0;
//-----------------------------------------------------------------------------------------
//
// GetType
//
// Description: gets the type of the device, either 1.1 or 2.0 device
virtual USB_DEVICE_TYPE GetType() = 0;
//-----------------------------------------------------------------------------------------
//
// GetState
//
// Description: gets the device state
virtual ULONG GetState() = 0;
//-----------------------------------------------------------------------------------------
//
// SetDeviceHandleData
//
// Description: sets device handle data
virtual void SetDeviceHandleData(PVOID Data) = 0;
//-----------------------------------------------------------------------------------------
//
// SetDeviceAddress
//
// Description: sets device handle data
virtual NTSTATUS SetDeviceAddress(UCHAR DeviceAddress) = 0;
//-----------------------------------------------------------------------------------------
//
// GetDeviceDescriptor
//
// Description: sets device handle data
virtual void GetDeviceDescriptor(PUSB_DEVICE_DESCRIPTOR DeviceDescriptor) = 0;
//-----------------------------------------------------------------------------------------
//
// GetConfigurationValue
//
// Description: gets current selected configuration index
virtual UCHAR GetConfigurationValue() = 0;
//-----------------------------------------------------------------------------------------
//
// SubmitIrp
//
// Description: submits an irp containing an urb
virtual NTSTATUS SubmitIrp(PIRP Irp) = 0;
//-----------------------------------------------------------------------------------------
//
// GetConfigurationDescriptors
//
// Description: returns one or more configuration descriptors
virtual VOID GetConfigurationDescriptors(IN PUSB_CONFIGURATION_DESCRIPTOR ConfigDescriptorBuffer,
IN ULONG BufferLength,
OUT PULONG OutBufferLength) = 0;
//-----------------------------------------------------------------------------------------
//
// Description: returns length of configuration descriptors
//
virtual ULONG GetConfigurationDescriptorsLength() = 0;
//-----------------------------------------------------------------------------------------
//
// SubmitSetupPacket
//
// Description: submits an setup packet. The usb device will then create an usb request from it and submit it to the queue
virtual NTSTATUS SubmitSetupPacket(IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket,
IN OUT ULONG BufferLength,
OUT PVOID Buffer) = 0;
//-----------------------------------------------------------------------------------------
//
// SelectConfiguration
//
// Description: selects a configuration
virtual NTSTATUS SelectConfiguration(IN PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
IN PUSBD_INTERFACE_INFORMATION Interface,
OUT USBD_CONFIGURATION_HANDLE *ConfigurationHandle) = 0;
//-----------------------------------------------------------------------------------------
//
// SelectConfiguration
//
// Description: selects a interface of an configuration
virtual NTSTATUS SelectInterface(IN USBD_CONFIGURATION_HANDLE ConfigurationHandle,
IN OUT PUSBD_INTERFACE_INFORMATION Interface) = 0;
//-----------------------------------------------------------------------------------------
//
// AbortPipe
//
// Description: aborts all pending requests
virtual NTSTATUS AbortPipe(IN PUSB_ENDPOINT_DESCRIPTOR EndpointDescriptor) = 0;
//-----------------------------------------------------------------------------------------
//
// GetMaxPacketSize
//
// Description: aborts all pending requests
virtual UCHAR GetMaxPacketSize() = 0;
};
typedef IUSBDevice *PUSBDEVICE;
#endif