fxusbdevice.hpp

Go to the documentation of this file.

/*++
 
Copyright (c) Microsoft Corporation
 
Module Name:
 
    FxUsbDevice.hpp
 
Abstract:
 
Author:
 
Environment:
 
    kernel mode only
 
Revision History:
 
--*/
 
#ifndef _FXUSBDEVICE_H_
#define _FXUSBDEVICE_H_
 
#include "fxusbrequestcontext.hpp"
 
typedef enum _FX_URB_TYPE : UCHAR {
    FxUrbTypeLegacy,
    FxUrbTypeUsbdAllocated
} FX_URB_TYPE;
 
struct FxUsbDeviceControlContext : public FxUsbRequestContext {
    FxUsbDeviceControlContext(
        __in FX_URB_TYPE FxUrbType
        );
 
    ~FxUsbDeviceControlContext(
        VOID
        );
 
    __checkReturn
    NTSTATUS
    AllocateUrb(
        __in USBD_HANDLE USBDHandle
        );
 
    virtual
    VOID
    Dispose(
        VOID
        );
 
    virtual
    VOID
    CopyParameters(
        __in FxRequestBase* Request
        );
 
    VOID
    StoreAndReferenceMemory(
        __in FxUsbDevice* Device,
        __in FxRequestBuffer* Buffer,
        __in PWDF_USB_CONTROL_SETUP_PACKET SetupPacket
        );
 
    virtual
    VOID
    ReleaseAndRestore(
        __in FxRequestBase* Request
        );
 
    USBD_STATUS
    GetUsbdStatus(
        VOID
        );
 
private:
    USBD_HANDLE m_USBDHandle;
 
public:
 
    _URB_CONTROL_TRANSFER m_UrbLegacy;
 
    //
    // m_Urb will either point to m_UrbLegacy or one allocated by USBD_UrbAllocate
    //
    _URB_CONTROL_TRANSFER* m_Urb;
 
    PMDL m_PartialMdl;
 
    BOOLEAN m_UnlockPages;
};
 
struct FxUsbDeviceStringContext : public FxUsbRequestContext {
    FxUsbDeviceStringContext(
        __in FX_URB_TYPE FxUrbType
        );
 
    ~FxUsbDeviceStringContext(
        VOID
        );
 
    __checkReturn
    NTSTATUS
    AllocateUrb(
        __in USBD_HANDLE USBDHandle
        );
 
    virtual
    VOID
    Dispose(
        VOID
        );
 
    virtual
    VOID
    CopyParameters(
        __in FxRequestBase* Request
        );
 
    VOID
    SetUrbInfo(
        __in  UCHAR StringIndex,
        __in  USHORT LangID
        );
 
    USBD_STATUS
    GetUsbdStatus(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    AllocateDescriptor(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals,
        __in size_t BufferSize
        );
 
private:
    USBD_HANDLE m_USBDHandle;
 
public:
 
    _URB_CONTROL_DESCRIPTOR_REQUEST m_UrbLegacy;
 
    //
    // m_Urb will either point to m_UrbLegacy or one allocated by USBD_UrbAllocate
    //
    _URB_CONTROL_DESCRIPTOR_REQUEST* m_Urb;
 
    PUSB_STRING_DESCRIPTOR m_StringDescriptor;
 
    ULONG m_StringDescriptorLength;
};
 
class FxUsbUrb : public FxMemoryBufferPreallocated {
public:
 
    FxUsbUrb(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals,
        __in USBD_HANDLE USBDHandle,
        __in_bcount(BufferSize) PVOID Buffer,
        __in size_t BufferSize
        );
 
protected:
 
    virtual
    BOOLEAN
    Dispose(
        VOID
        );
 
    ~FxUsbUrb();
 
private:
 
    USBD_HANDLE m_USBDHandle;
};
 
 
#define FX_USB_DEVICE_TAG   'sUfD'
 
class FxUsbDevice : public FxIoTarget {
public:
    friend FxUsbPipe;
    friend FxUsbInterface;
 
    FxUsbDevice(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals
        );
 
    _Must_inspect_result_
    NTSTATUS
    InitDevice(
        __in ULONG USBDClientContractVersionForWdfClient
        );
 
    _Must_inspect_result_
    NTSTATUS
    GetConfigDescriptor(
        __out PVOID ConfigDescriptor,
        __inout PUSHORT ConfigDescriptorLength
        );
 
    _Must_inspect_result_
    NTSTATUS
    GetString(
        __in_ecount(*NumCharacters) PUSHORT String,
        __in PUSHORT NumCharacters,
        __in UCHAR StringIndex,
        __in_opt USHORT LangID,
        __in_opt WDFREQUEST Request = NULL,
        __in_opt PWDF_REQUEST_SEND_OPTIONS Options = NULL
        );
 
    __inline
    VOID
    CopyDeviceDescriptor(
        __out PUSB_DEVICE_DESCRIPTOR UsbDeviceDescriptor
        )
    {
        RtlCopyMemory(UsbDeviceDescriptor,
                      &m_DeviceDescriptor,
                      sizeof(m_DeviceDescriptor));
    }
 
    VOID
    GetInformation(
        __out PWDF_USB_DEVICE_INFORMATION Information
        );
 
    __inline
    USBD_CONFIGURATION_HANDLE
    GetConfigHandle(
        VOID
        )
    {
        return m_ConfigHandle;
    }
 
    _Must_inspect_result_
    __inline
    NTSTATUS
    GetCurrentFrameNumber(
        __in PULONG Current
        )
    {
        if (m_QueryBusTime != NULL) {
            return m_QueryBusTime(m_BusInterfaceContext, Current);
        }
        else {
            return STATUS_UNSUCCESSFUL;
        }
    }
 
    _Must_inspect_result_
    NTSTATUS
    SelectConfigAuto(
        __in PWDF_OBJECT_ATTRIBUTES PipeAttributes
        );
 
    _Must_inspect_result_
    NTSTATUS
    SelectConfigInterfaces(
        __in PWDF_OBJECT_ATTRIBUTES PipesAttributes,
        __in PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
        __in_ecount(NumInterfaces)PUSB_INTERFACE_DESCRIPTOR* InterfaceDescriptors,
        __in ULONG NumInterfaces
        );
 
    _Must_inspect_result_
    NTSTATUS
    SelectConfig(
        __in PWDF_OBJECT_ATTRIBUTES PipesAttributes,
        __in PURB Urb,
        __in FX_URB_TYPE FxUrbType,
        __out_opt PUCHAR NumConfiguredInterfaces
        );
 
    _Must_inspect_result_
    NTSTATUS
    Deconfig(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    SelectInterfaceByInterface(
        __in PWDF_OBJECT_ATTRIBUTES PipesAttributes,
        __in PUSB_INTERFACE_DESCRIPTOR InterfaceDescriptor
        );
 
    _Must_inspect_result_
    NTSTATUS
    SelectInterface(
        __in PWDF_OBJECT_ATTRIBUTES PipesAttributes,
        __in PURB Urb
        );
 
    UCHAR
    GetNumInterfaces(
        VOID
        )
    {
        return m_NumInterfaces;
    }
 
    UCHAR
    GetInterfaceNumEndpoints(
        __in UCHAR InterfaceNumber
        );
 
    WDFUSBPIPE
    GetInterfacePipeReferenced(
        __in UCHAR InterfaceNumber,
        __in UCHAR EndpointNumber
        );
 
    _Must_inspect_result_
    NTSTATUS
    FormatStringRequest(
        __in FxRequestBase* Request,
        __in FxRequestBuffer *RequestBuffer,
        __in  UCHAR StringIndex,
        __in  USHORT LangID
        );
 
    _Must_inspect_result_
    NTSTATUS
    FormatControlRequest(
        __in FxRequestBase* Request,
        __in PWDF_USB_CONTROL_SETUP_PACKET Packet,
        __in FxRequestBuffer *RequestBuffer
        );
 
    _Must_inspect_result_
    NTSTATUS
    IsConnected(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    Reset(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    CyclePort(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    FormatCycleRequest(
        __in FxRequestBase* Request
        );
 
    BOOLEAN
    OnUSBD(
        VOID
        )
    {
        return m_OnUSBD;
    }
 
    USBD_PIPE_HANDLE
    GetControlPipeHandle(
        VOID
        )
    {
        return m_ControlPipe;
    }
 
    _Must_inspect_result_
    NTSTATUS
    CreateInterfaces(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    SelectConfigSingle(
        __in PWDF_OBJECT_ATTRIBUTES PipeAttributes,
        __in PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
        );
 
    _Must_inspect_result_
    NTSTATUS
    SelectConfigMulti(
        __in PWDF_OBJECT_ATTRIBUTES PipeAttributes,
        __in PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
        );
 
    _Must_inspect_result_
    NTSTATUS
    SelectConfigDescriptor(
        __in PWDF_OBJECT_ATTRIBUTES PipeAttributes,
        __in PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
        );
 
    FxUsbInterface *
    GetInterfaceFromIndex(
        __in UCHAR InterfaceIndex
        );
 
    BOOLEAN
    HasMismatchedInterfacesInConfigDescriptor(
        VOID
        )
    {
        return m_MismatchedInterfacesInConfigDescriptor;
    }
 
    VOID
    CancelSentIo(
        VOID
        );
 
    BOOLEAN
    IsEnabled(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    QueryUsbCapability(
        __in
        CONST GUID* CapabilityType,
        __in
        ULONG CapabilityBufferLength,
        __drv_when(CapabilityBufferLength == 0, __out_opt)
        __drv_when(CapabilityBufferLength != 0 && ResultLength == NULL, __out_bcount(CapabilityBufferLength))
        __drv_when(CapabilityBufferLength != 0 && ResultLength != NULL, __out_bcount_part_opt(CapabilityBufferLength, *ResultLength))
        PVOID CapabilityBuffer,
        __out_opt
        __drv_when(ResultLength != NULL,__deref_out_range(<=,CapabilityBufferLength))
        PULONG ResultLength
        );
 
    __checkReturn
    NTSTATUS
    CreateUrb(
        __in_opt
        PWDF_OBJECT_ATTRIBUTES Attributes,
        __out
        WDFMEMORY* UrbMemory,
        __deref_opt_out_bcount(sizeof(URB))
        PURB* Urb
        );
 
#ifdef _MSC_VER
#pragma warning(disable:28285)
#endif
    __checkReturn
    NTSTATUS
    CreateIsochUrb(
        __in_opt
        PWDF_OBJECT_ATTRIBUTES Attributes,
        __in
        ULONG NumberOfIsochPackets,
        __out
        WDFMEMORY* UrbMemory,
        __deref_opt_out_bcount(GET_ISOCH_URB_SIZE(NumberOfIsochPackets))
        PURB* Urb
        );
 
    USBD_HANDLE
    GetUSBDHandle(
        VOID
        )
    {
        return m_USBDHandle;
    }
 
    FX_URB_TYPE
    GetUrbType(
        VOID
        )
    {
        return m_UrbType;
    }
 
    FX_URB_TYPE
    GetFxUrbTypeForRequest(
        __in FxRequestBase* Request
        );
 
    BOOLEAN
    IsObjectDisposedOnRemove(
        __in FxObject* Object
        );
 
protected:
    ~FxUsbDevice(
        VOID
        );
 
    VOID
    RemoveDeletedInterface(
        __in FxUsbInterface* Interface
        );
 
    //
    // FxIoTarget overrides
    //
    virtual
    _Must_inspect_result_
    NTSTATUS
    Start(
        VOID
        );
 
    virtual
    VOID
    Stop(
        __in WDF_IO_TARGET_SENT_IO_ACTION Action
        );
 
    virtual
    VOID
    Purge(
        __in WDF_IO_TARGET_PURGE_IO_ACTION Action
        );
    // end FxIoTarget overrides
 
    VOID
    PipesGotoRemoveState(
        __in BOOLEAN ForceRemovePipes
        );
 
    static
    VOID
    _CleanupPipesRequests(
        __in PLIST_ENTRY PendHead,
        __in PSINGLE_LIST_ENTRY SentHead
        );
 
    FxUsbInterface *
    GetInterfaceFromNumber(
        __in UCHAR InterfaceNumber
        );
 
    _Must_inspect_result_
    NTSTATUS
    GetInterfaceNumberFromInterface(
        __in WDFUSBINTERFACE UsbInterface,
        __out PUCHAR InterfaceNumber
        );
 
    VOID
    CleanupInterfacePipesAndDelete(
        __in FxUsbInterface * UsbInterface
        );
 
    _Acquires_lock_(_Global_critical_region_)
    VOID
    AcquireInterfaceIterationLock(
        VOID
        )
    {
        m_InterfaceIterationLock.AcquireLock(GetDriverGlobals());
    }
 
    _Releases_lock_(_Global_critical_region_)
    VOID
    ReleaseInterfaceIterationLock(
        VOID
        )
    {
        m_InterfaceIterationLock.ReleaseLock(GetDriverGlobals());
    }
 
    ULONG
    GetDefaultMaxTransferSize(
        VOID
        );
 
    VOID
    FormatInterfaceSelectSettingUrb(
        __in PURB Urb,
        __in USHORT NumEndpoints,
        __in UCHAR InterfaceNumber,
        __in UCHAR SettingNumber
        );
 
    virtual
    BOOLEAN
    Dispose(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    GetPortStatus(
        __out PULONG PortStatus
        );
 
#if (FX_CORE_MODE == FX_CORE_USER_MODE)
    _Must_inspect_result_
    NTSTATUS
    FxUsbDevice::SendSyncRequest(
        __in FxSyncRequest* Request,
        __in ULONGLONG Time
        );
 
    _Must_inspect_result_
    NTSTATUS
    SendSyncUmUrb(
        __inout PUMURB Urb,
        __in ULONGLONG Time,
        __in_opt WDFREQUEST Request = NULL,
        __in_opt PWDF_REQUEST_SEND_OPTIONS Options = NULL
        );
#endif
 
protected:
    USBD_HANDLE m_USBDHandle;
 
    USBD_PIPE_HANDLE m_ControlPipe;
 
    FxUsbInterface ** m_Interfaces;
 
    USBD_CONFIGURATION_HANDLE m_ConfigHandle;
 
    USB_DEVICE_DESCRIPTOR m_DeviceDescriptor;
 
    PUSB_CONFIGURATION_DESCRIPTOR m_ConfigDescriptor;
 
    USBD_VERSION_INFORMATION m_UsbdVersionInformation;
 
    PUSB_BUSIFFN_QUERY_BUS_TIME m_QueryBusTime;
 
    PVOID m_BusInterfaceContext;
 
    PINTERFACE_DEREFERENCE m_BusInterfaceDereference;
 
    FxWaitLockInternal m_InterfaceIterationLock;
 
    ULONG m_HcdPortCapabilities;
 
    ULONG m_Traits;
 
    BOOLEAN m_OnUSBD;
 
    UCHAR m_NumInterfaces;
 
    BOOLEAN m_MismatchedInterfacesInConfigDescriptor;
 
    FX_URB_TYPE m_UrbType;
 
#if (FX_CORE_MODE == FX_CORE_USER_MODE)
private:
    //
    // Used to format the IWudfIrp for user-mode requests
    //
    IWudfFile* m_pHostTargetFile;
 
    //
    // Handle to the default USB interface exposed by WinUsb
    //
    WINUSB_INTERFACE_HANDLE m_WinUsbHandle;
#endif
};
 
#endif // _FXUSBDEVICE_H_