reactos/drivers/usb/usbehci_new/interfaces.h

#ifndef INTERFACES_HPP
#define INTERFACES_HPP

//---------------------------------------------------------------------------
//
//          Object Hierachy
//       --------------------------------------------------------------------
//       |  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;

DECLARE_INTERFACE_(IUSBHardwareDevice, IUnknown)
{
    DEFINE_ABSTRACT_UNKNOWN()

//-----------------------------------------------------------------------------------------
//
// Initialize
//
// Description: Initializes the usb device controller

    virtual NTSTATUS Initialize(PDRIVER_OBJECT DriverObject,
                                PDEVICE_OBJECT FunctionalDeviceObject,
                                PDEVICE_OBJECT PhysicalDeviceObject,
                                PDEVICE_OBJECT LowerDeviceObject) = 0;

//-----------------------------------------------------------------------------------------
//
// PnpStart
//
// Description: handles pnp start request from device. It registeres the interrupt, 
// sets up the ports and prepares the device. It then starts the controller

   virtual NTSTATUS PnpStart(PCM_RESOURCE_LIST RawResources,
                             PCM_RESOURCE_LIST TranslatedResources) = 0;

//-----------------------------------------------------------------------------------------
//
// PnpStop
//
// Description: handles pnp stop request from device. It unregisteres the interrupt, releases ports and dma object.

    virtual NTSTATUS PnpStop(void) = 0;

//-----------------------------------------------------------------------------------------
//
// GetDeviceDetails
//
// Description: returns the device details such as vendor id, device id, number of ports and speed

    virtual NTSTATUS GetDeviceDetails(OUT OPTIONAL PUSHORT VendorId,
                                      OUT OPTIONAL PUSHORT DeviceId,
                                      OUT OPTIONAL PULONG NumberOfPorts,
                                      OUT OPTIONAL PULONG Speed) = 0;

//-----------------------------------------------------------------------------------------
//
// GetUSBQueue
//
// Description: returns interface to internal IUSBQueue
// Interface is reference counted, you need to call release method when you are done with it
// Do not call Initialize on IUSBQueue, the object is already initialized

    virtual NTSTATUS GetUSBQueue(OUT struct IUSBQueue **OutUsbQueue) = 0;

//-----------------------------------------------------------------------------------------
//
// ResetController()
//
// Description: this function resets the controller
// Returns STATUS_SUCCESS when the controller was successfully reset

   virtual NTSTATUS ResetController() = 0;

//-----------------------------------------------------------------------------------------
//
// StartController
//
// Description: this functions starts controller allowing interrupts for device connects/removal, and execution of
// Periodic and Asynchronous Schedules. 
//

    virtual NTSTATUS StartController() = 0;

//-----------------------------------------------------------------------------------------
//
// StopController
//
// Description: this functions stops controller disabling interrupts for device connects/removal, and execution of
// Periodic and Asynchronous Schedules. 
//

    virtual NTSTATUS StopController() = 0;

//-----------------------------------------------------------------------------------------
//
// ResetPort
//
// Description: this functions resets the port on the controller
//

    virtual NTSTATUS ResetPort(ULONG PortNumber) = 0;
    
//-----------------------------------------------------------------------------------------
//
// SetAsyncListRegister
//
// Description: this functions sets the register to a address that is the physical address of a QueueHead.
// This is the location at which the controller will start executing the Asynchronous Schedule.
//
// FIXME: This is only available for USB 2.0
    virtual VOID SetAsyncListRegister(ULONG PhysicalAddress) = 0;

//-----------------------------------------------------------------------------------------
//
// SetPeriodicListRegister
//
// Description: this functions sets the register to a address that is the physical address of a ???.
// This is the location at which the controller will start executing the Periodic Schedule.
//
    virtual VOID SetPeriodicListRegister(ULONG PhysicalAddress) = 0;

//-----------------------------------------------------------------------------------------
//
// AcquireDeviceLock
//
// Description: acquires the device lock

    virtual KIRQL AcquireDeviceLock(void) = 0;

//-----------------------------------------------------------------------------------------
//
// ReleaseLock
//
// Description: releases the device lock

    virtual void ReleaseDeviceLock(KIRQL OldLevel) = 0;
};

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 _QUEUE_HEAD;

DECLARE_INTERFACE_(IUSBRequest, IUnknown)
{
    DEFINE_ABSTRACT_UNKNOWN()

//-----------------------------------------------------------------------------------------
//
// InitializeWithSetupPacket
//
// Description: initializes the request packet with an setup packet
// If there is a TransferBuffer, the TransferBufferLength contains the length of the buffer


    virtual NTSTATUS InitializeWithSetupPacket(IN PDMAMEMORYMANAGER DmaManager,
                                               IN PUSB_DEFAULT_PIPE_SETUP_PACKET SetupPacket,
                                               IN OUT ULONG TransferBufferLength,
                                               IN OUT PMDL TransferBuffer) = 0;

//-----------------------------------------------------------------------------------------
//
// InitializeWithIrp
//
// Description: initializes the request with an IRP
// The irp contains an URB block which contains all necessary information

    virtual NTSTATUS InitializeWithIrp(IN PDMAMEMORYMANAGER DmaManager, 
                                       IN OUT PIRP Irp);

//-----------------------------------------------------------------------------------------
//
// SetCompletionEvent
//
// Description: sets up completion event which is signaled when the
// request is completed or cancelled

    virtual NTSTATUS SetCompletionEvent(IN PKEVENT Event) = 0;

//-----------------------------------------------------------------------------------------
//
// CompletionCallback
//
// Description: called when request has been completed. It is called when
// IUSBQueue completes the request

    virtual VOID CompletionCallback(IN NTSTATUS NtStatusCode,
                                   IN ULONG UrbStatusCode) = 0;

//-----------------------------------------------------------------------------------------
//
// CancelCallback
//
// Description: called when request is cancelled. Called by IUSBQueue

    virtual VOID CancelCallback(IN NTSTATUS NtStatusCode) = 0;

//-----------------------------------------------------------------------------------------
//
//  GetQueueHead
//
// Description: returns an initialized queue head with contains the all transfer descriptors

    virtual NTSTATUS GetQueueHead(struct _QUEUE_HEAD ** OutHead) = 0;

//-----------------------------------------------------------------------------------------
//
//  IsRequestComplete
//
// Description: returns true when the request has been completed
// Should be called after the CompletionCallback has been invoked

    virtual BOOLEAN IsRequestComplete() = 0;

//-----------------------------------------------------------------------------------------
//
// GetTransferType
//
// Description: returns the type of the request: control, bulk, iso, interrupt

    virtual ULONG GetTransferType() = 0;

};

typedef IUSBRequest *PUSBREQUEST;

//=========================================================================================
//
// class IUSBQueue
//
// Description: This class manages pending requests
// 

DECLARE_INTERFACE_(IUSBQueue, IUnknown)
{
    DEFINE_ABSTRACT_UNKNOWN()

//-----------------------------------------------------------------------------------------
//
// Initialize
//
// Description: initializes the object

    virtual NTSTATUS Initialize(IN PUSBHARDWAREDEVICE Hardware,
                                PDMA_ADAPTER AdapterObject,
                                IN OPTIONAL PKSPIN_LOCK Lock) = 0;

//-----------------------------------------------------------------------------------------
//
// GetPendingRequestCount
//
// Description: returns the number of pending requests

    virtual ULONG GetPendingRequestCount() = 0;

//-----------------------------------------------------------------------------------------
//
// AddUSBRequest
//
// Description: adds an usb request to the queue. 
// Returns status success when successful

    virtual NTSTATUS AddUSBRequest(IUSBRequest * Request) = 0;
    virtual NTSTATUS AddUSBRequest(PURB Urb) = 0;
//-----------------------------------------------------------------------------------------
//
// CancelRequests()
//
// Description: cancels all requests

    virtual NTSTATUS CancelRequests() = 0;

//-----------------------------------------------------------------------------------------
//
// CreateUSBRequest
//
// Description: creates an usb request

    virtual NTSTATUS CreateUSBRequest(IUSBRequest **OutRequest) = 0;
};

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;
};

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 ULONG 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(ULONG 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;

//-----------------------------------------------------------------------------------------
//
// SubmitUrb
//
// Description: submits an urb

    virtual NTSTATUS SubmitUrb(PURB Urb) = 0;

};

typedef IUSBDevice *PUSBDEVICE;

#endif