/*++

Copyright (c) Microsoft Corporation. All rights reserved.

Module Name:

    UcxController.h

Abstract:

    UCX Controller object types and methods.

Environment:

    Kernel-mode only.

--*/

//
// NOTE: This header is generated by stubwork.  Please make any 
//       modifications to the corresponding template files 
//       (.x or .y) and use stubwork to regenerate the header
//

#ifndef _UCXCONTROLLER_H_
#define _UCXCONTROLLER_H_

#ifndef WDF_EXTERN_C
  #ifdef __cplusplus
    #define WDF_EXTERN_C       extern "C"
    #define WDF_EXTERN_C_START extern "C" {
    #define WDF_EXTERN_C_END   }
  #else
    #define WDF_EXTERN_C
    #define WDF_EXTERN_C_START
    #define WDF_EXTERN_C_END
  #endif
#endif

WDF_EXTERN_C_START



typedef enum _UCX_CONTROLLER_PARENT_BUS_TYPE {
    UcxControllerParentBusTypeCustom = 0,
    UcxControllerParentBusTypePci,
    UcxControllerParentBusTypeAcpi,
    UcxControllerParentBusTypeMaUsb,
} UCX_CONTROLLER_PARENT_BUS_TYPE;

typedef enum _UCX_CONTROLLER_STATE {
    UcxControllerStateLost = 0,
    UcxControllerStatePreserved,
} UCX_CONTROLLER_STATE;



//
// This is a private capability exposed by the host controller to be
// queried by UCX.  If supported by the host controller this capability
// indicates that a Clear TT Buffer request should be issued to a TT hub
// if a transfer is canceled on a control or bulk endpoint on a low
// speed or full speed device downstream of the TT hub.
//
DEFINE_GUID(GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL,
    0x09b76d52, 0x0a6d, 0x4e4f, 0xa9, 0x11, 0xd0, 0x36, 0xd1, 0x92, 0x94, 0x97);

typedef
_Function_class_(EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY)
_IRQL_requires_same_
_Must_inspect_result_
NTSTATUS
EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY(
    __in
    UCXCONTROLLER   UcxController,
    __in
    PGUID           CapabilityType,
    __in
    ULONG           OutputBufferLength,
    __out_bcount_opt(OutputBufferLength)
    PVOID           OutputBuffer,
    __out
    PULONG          ResultLength
    );

typedef EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY *PFN_UCX_CONTROLLER_QUERY_USB_CAPABILITY;

typedef
_Function_class_(EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER)
_IRQL_requires_same_
_Must_inspect_result_
NTSTATUS
EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER(
    __in
    UCXCONTROLLER   UcxController,
    __out
    PULONG          FrameNumber
    );

typedef EVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER *PFN_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER;

typedef struct _UCXUSBDEVICE_INFO *PUCXUSBDEVICE_INFO;

typedef
_Function_class_(EVT_UCX_CONTROLLER_USBDEVICE_ADD)
_IRQL_requires_same_
__drv_requiresIRQL(PASSIVE_LEVEL)
_Must_inspect_result_
NTSTATUS
EVT_UCX_CONTROLLER_USBDEVICE_ADD(
    __in
    UCXCONTROLLER       UcxController,
    __in
    PUCXUSBDEVICE_INFO  UcxUsbDeviceInfo,
    __in
    PUCXUSBDEVICE_INIT  UsbDeviceInit
    );

typedef EVT_UCX_CONTROLLER_USBDEVICE_ADD *PFN_UCX_CONTROLLER_USBDEVICE_ADD;

typedef
_Function_class_(EVT_UCX_CONTROLLER_RESET)
_IRQL_requires_same_
__drv_requiresIRQL(PASSIVE_LEVEL)
VOID
EVT_UCX_CONTROLLER_RESET(
    __in
    UCXCONTROLLER   UcxController
    );

typedef EVT_UCX_CONTROLLER_RESET *PFN_UCX_CONTROLLER_RESET;


#define MAX_VENDOR_ID_STRING_LENGTH             5
#define MAX_DEVICE_ID_STRING_LENGTH             5
#define MAX_REVISION_ID_STRING_LENGTH           5
#define MAX_GENERIC_USB_CONTROLLER_NAME_SIZE    40

typedef struct _UCX_CONTROLLER_PCI_INFORMATION {
    ULONG   VendorId;
    ULONG   DeviceId;
    USHORT  RevisionId;
    ULONG   BusNumber;
    ULONG   DeviceNumber;
    ULONG   FunctionNumber;
} UCX_CONTROLLER_PCI_INFORMATION, *PUCX_CONTROLLER_PCI_INFORMATION;

typedef struct _UCX_CONTROLLER_ACPI_INFORMATION {
    CHAR    VendorId[MAX_VENDOR_ID_STRING_LENGTH];
    CHAR    DeviceId[MAX_DEVICE_ID_STRING_LENGTH];
    CHAR    RevisionId[MAX_REVISION_ID_STRING_LENGTH];
} UCX_CONTROLLER_ACPI_INFORMATION, *PUCX_CONTROLLER_ACPI_INFORMATION;

typedef struct _UCX_CONTROLLER_CONFIG {
    //
    // Size in bytes of this structure
    //
    ULONG                                           Size;
    ULONG                                           NumberOfPresentedDeviceMgmtEvtCallbacks;
    PFN_UCX_CONTROLLER_QUERY_USB_CAPABILITY        EvtControllerQueryUsbCapability;
    HANDLE                                          Reserved1;
    PFN_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER     EvtControllerGetCurrentFrameNumber;
    PFN_UCX_CONTROLLER_USBDEVICE_ADD               EvtControllerUsbDeviceAdd;
    PFN_UCX_CONTROLLER_RESET                       EvtControllerReset;
    HANDLE                                          Reserved2;
    HANDLE                                          Reserved3;
    HANDLE                                          Reserved4;

    UCX_CONTROLLER_PARENT_BUS_TYPE                  ParentBusType;
    UCX_CONTROLLER_PCI_INFORMATION                  PciDeviceInfo;
    UCX_CONTROLLER_ACPI_INFORMATION                 AcpiDeviceInfo;

    //
    // Due to compat with GUID_USB_WMI_NODE_INFO we cannot use WCHAR.
    //
    UCHAR                                           DeviceDescription[MAX_GENERIC_USB_CONTROLLER_NAME_SIZE];

    //
    // The following may be used as ID strings.
    //
    UNICODE_STRING                                 ManufacturerNameString;
    UNICODE_STRING                                 ModelNameString;
    UNICODE_STRING                                 ModelNumberString;

} UCX_CONTROLLER_CONFIG, *PUCX_CONTROLLER_CONFIG;

__drv_at(Config->Size, __drv_out (__range(!=,0)))
__drv_at(Config->EvtControllerQueryUsbCapability, __drv_out  (__null))
__drv_at(Config->EvtControllerGetCurrentFrameNumber, __drv_out  (__null))
__drv_at(Config->EvtControllerUsbDeviceAdd, __drv_out  (__null))
__drv_at(Config->EvtControllerReset, __drv_out  (__null))
__drv_at(Config->Reserved1, __drv_out  (__null))
__drv_at(Config->Reserved2, __drv_out  (__null))
__drv_at(Config->Reserved3, __drv_out  (__null))
__drv_at(Config->Reserved4, __drv_out  (__null))
VOID
FORCEINLINE
UCX_CONTROLLER_CONFIG_INIT(
    __out
        PUCX_CONTROLLER_CONFIG  Config,
    __in
        LPCSTR                  DeviceDescription
    )
{
    RtlZeroMemory(Config, sizeof(UCX_CONTROLLER_CONFIG));
    Config->Size = sizeof(UCX_CONTROLLER_CONFIG);
    Config->NumberOfPresentedDeviceMgmtEvtCallbacks = (ULONG)-1;
    Config->ParentBusType = UcxControllerParentBusTypeCustom;

    Config->AcpiDeviceInfo.VendorId[0]      = ANSI_NULL;
    Config->AcpiDeviceInfo.DeviceId[0]      = ANSI_NULL;
    Config->AcpiDeviceInfo.RevisionId[0]    = ANSI_NULL;
    Config->PciDeviceInfo.VendorId          = LONG_MAX;
    Config->PciDeviceInfo.DeviceId          = LONG_MAX;
    Config->PciDeviceInfo.RevisionId        = 0;
    Config->PciDeviceInfo.BusNumber         = 0;
    Config->PciDeviceInfo.DeviceNumber      = 0;
    Config->PciDeviceInfo.FunctionNumber    = 0;

    (VOID) RtlStringCbCopyA((LPSTR)Config->DeviceDescription,
                            sizeof(Config->DeviceDescription),
                            DeviceDescription);

    __assume(Config->EvtControllerQueryUsbCapability == NULL);
    __assume(Config->EvtControllerGetCurrentFrameNumber == NULL);
    __assume(Config->EvtControllerUsbDeviceAdd == NULL);
    __assume(Config->EvtControllerReset == NULL);
    __assume(Config->Reserved1 == NULL);
    __assume(Config->Reserved2 == NULL);
    __assume(Config->Reserved3 == NULL);
    __assume(Config->Reserved4 == NULL);
}

VOID
FORCEINLINE
UCX_CONTROLLER_CONFIG_SET_PCI_INFO(
    __in
        PUCX_CONTROLLER_CONFIG  Config,
    __in
        ULONG                   VendorId,
    __in
        ULONG                   DeviceId,
    __in
        USHORT                  RevisionId,
    __in
        ULONG                   BusNumber,
    __in
        ULONG                   DeviceNumber,
    __in
        ULONG                   FunctionNumber
    )
{
    Config->ParentBusType = UcxControllerParentBusTypePci;

    Config->PciDeviceInfo.VendorId          = VendorId;
    Config->PciDeviceInfo.DeviceId          = DeviceId;
    Config->PciDeviceInfo.RevisionId        = RevisionId;
    Config->PciDeviceInfo.BusNumber         = BusNumber;
    Config->PciDeviceInfo.DeviceNumber      = DeviceNumber;
    Config->PciDeviceInfo.FunctionNumber    = FunctionNumber;
}

VOID
FORCEINLINE
UCX_CONTROLLER_CONFIG_SET_ACPI_INFO(
    __in
        PUCX_CONTROLLER_CONFIG  Config,
    __in_ecount(MAX_VENDOR_ID_STRING_LENGTH)
        PSTR                    VendorId,
    __in_ecount(MAX_DEVICE_ID_STRING_LENGTH)
        PSTR                    DeviceId,
    __in_ecount(MAX_REVISION_ID_STRING_LENGTH)
        PSTR                    RevisionId
    )
{
    Config->ParentBusType = UcxControllerParentBusTypeAcpi;

    RtlStringCchCopyA(Config->AcpiDeviceInfo.VendorId, MAX_VENDOR_ID_STRING_LENGTH, VendorId);
    RtlStringCchCopyA(Config->AcpiDeviceInfo.DeviceId, MAX_DEVICE_ID_STRING_LENGTH, DeviceId);
    RtlStringCchCopyA(Config->AcpiDeviceInfo.RevisionId, MAX_REVISION_ID_STRING_LENGTH, RevisionId);
}

typedef struct _UCX_CONTROLLER_RESET_COMPLETE_INFO {
    ULONG                 Size;
    UCX_CONTROLLER_STATE  UcxControllerState;
    BOOLEAN               UcxCoordinated;
} UCX_CONTROLLER_RESET_COMPLETE_INFO, *PUCX_CONTROLLER_RESET_COMPLETE_INFO;

FORCEINLINE
VOID
UCX_CONTROLLER_RESET_COMPLETE_INFO_INIT(
    __out
        PUCX_CONTROLLER_RESET_COMPLETE_INFO UcxControllerResetCompleteInfo,
    __in
        UCX_CONTROLLER_STATE                UcxControllerState,
    __in
        BOOLEAN                             UcxCoordinated
    )
{
    RtlZeroMemory(UcxControllerResetCompleteInfo, sizeof(UCX_CONTROLLER_RESET_COMPLETE_INFO));
    UcxControllerResetCompleteInfo->Size = sizeof(UCX_CONTROLLER_RESET_COMPLETE_INFO);
    UcxControllerResetCompleteInfo->UcxControllerState = UcxControllerState;
    UcxControllerResetCompleteInfo->UcxCoordinated = UcxCoordinated;
}

//
// In an earlier version of this header, the function pointers for the callbacks used to be prefixed
// with "PEVT" instead of the standard "PFN". Typedef those old names so that existing clients that
// may be using the old names continue to compile with the new header.
//

typedef PFN_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER PEVT_UCX_CONTROLLER_GET_CURRENT_FRAMENUMBER;
typedef PFN_UCX_CONTROLLER_QUERY_USB_CAPABILITY PEVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY;
typedef PFN_UCX_CONTROLLER_RESET PEVT_UCX_CONTROLLER_RESET;
typedef PFN_UCX_CONTROLLER_USBDEVICE_ADD PEVT_UCX_CONTROLLER_USBDEVICE_ADD;

//
// UCX Function: UcxIoDeviceControl
//
typedef
_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
BOOLEAN
(*PFN_UCXIODEVICECONTROL)(
    _In_
    PUCX_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Device,
    __in
    WDFREQUEST Request,
    __in
    size_t OutputBufferLength,
    __in
    size_t InputBufferLength,
    __in
    ULONG IoControlCode
    );

_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
BOOLEAN
FORCEINLINE
UcxIoDeviceControl(
    __in
    WDFDEVICE Device,
    __in
    WDFREQUEST Request,
    __in
    size_t OutputBufferLength,
    __in
    size_t InputBufferLength,
    __in
    ULONG IoControlCode
    )
{
    return ((PFN_UCXIODEVICECONTROL) UcxFunctions[UcxIoDeviceControlTableIndex])(UcxDriverGlobals, Device, Request, OutputBufferLength, InputBufferLength, IoControlCode);
}

//
// UCX Function: UcxControllerCreate
//
typedef
_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
__drv_at(Config->Size, __range(!=,0))
__drv_at(Config->EvtControllerUsbDeviceAdd, __notnull)
WDFAPI
NTSTATUS
(*PFN_UCXCONTROLLERCREATE)(
    _In_
    PUCX_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Device,
    __in
    PUCX_CONTROLLER_CONFIG Config,
    __in_opt
    PWDF_OBJECT_ATTRIBUTES Attributes,
    __out
    UCXCONTROLLER* Controller
    );

_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
__drv_at(Config->Size, __range(!=,0))
__drv_at(Config->EvtControllerUsbDeviceAdd, __notnull)
NTSTATUS
FORCEINLINE
UcxControllerCreate(
    __in
    WDFDEVICE Device,
    __in
    PUCX_CONTROLLER_CONFIG Config,
    __in_opt
    PWDF_OBJECT_ATTRIBUTES Attributes,
    __out
    UCXCONTROLLER* Controller
    )
{
    return ((PFN_UCXCONTROLLERCREATE) UcxFunctions[UcxControllerCreateTableIndex])(UcxDriverGlobals, Device, Config, Attributes, Controller);
}

//
// UCX Function: UcxControllerNeedsReset
//
typedef
__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
(*PFN_UCXCONTROLLERNEEDSRESET)(
    _In_
    PUCX_DRIVER_GLOBALS DriverGlobals,
    __in
    UCXCONTROLLER Controller
    );

__drv_maxIRQL(DISPATCH_LEVEL)
VOID
FORCEINLINE
UcxControllerNeedsReset(
    __in
    UCXCONTROLLER Controller
    )
{
    ((PFN_UCXCONTROLLERNEEDSRESET) UcxFunctions[UcxControllerNeedsResetTableIndex])(UcxDriverGlobals, Controller);
}

//
// UCX Function: UcxControllerResetComplete
//
typedef
__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
(*PFN_UCXCONTROLLERRESETCOMPLETE)(
    _In_
    PUCX_DRIVER_GLOBALS DriverGlobals,
    __in
    UCXCONTROLLER Controller,
    __in
    PUCX_CONTROLLER_RESET_COMPLETE_INFO UcxControllerResetCompleteInfo
    );

__drv_maxIRQL(DISPATCH_LEVEL)
VOID
FORCEINLINE
UcxControllerResetComplete(
    __in
    UCXCONTROLLER Controller,
    __in
    PUCX_CONTROLLER_RESET_COMPLETE_INFO UcxControllerResetCompleteInfo
    )
{
    ((PFN_UCXCONTROLLERRESETCOMPLETE) UcxFunctions[UcxControllerResetCompleteTableIndex])(UcxDriverGlobals, Controller, UcxControllerResetCompleteInfo);
}

//
// UCX Function: UcxControllerSetFailed
//
typedef
__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
(*PFN_UCXCONTROLLERSETFAILED)(
    _In_
    PUCX_DRIVER_GLOBALS DriverGlobals,
    __in
    UCXCONTROLLER Controller
    );

__drv_maxIRQL(DISPATCH_LEVEL)
VOID
FORCEINLINE
UcxControllerSetFailed(
    __in
    UCXCONTROLLER Controller
    )
{
    ((PFN_UCXCONTROLLERSETFAILED) UcxFunctions[UcxControllerSetFailedTableIndex])(UcxDriverGlobals, Controller);
}

//
// UCX Function: UcxControllerSetIdStrings
//
typedef
__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
NTSTATUS
(*PFN_UCXCONTROLLERSETIDSTRINGS)(
    _In_
    PUCX_DRIVER_GLOBALS DriverGlobals,
    __in
    UCXCONTROLLER Controller,
    __in
    PUNICODE_STRING ManufacturerNameString,
    __in
    PUNICODE_STRING ModelNameString,
    __in
    PUNICODE_STRING ModelNumberString
    );

__drv_maxIRQL(DISPATCH_LEVEL)
NTSTATUS
FORCEINLINE
UcxControllerSetIdStrings(
    __in
    UCXCONTROLLER Controller,
    __in
    PUNICODE_STRING ManufacturerNameString,
    __in
    PUNICODE_STRING ModelNameString,
    __in
    PUNICODE_STRING ModelNumberString
    )
{
    return ((PFN_UCXCONTROLLERSETIDSTRINGS) UcxFunctions[UcxControllerSetIdStringsTableIndex])(UcxDriverGlobals, Controller, ManufacturerNameString, ModelNameString, ModelNumberString);
}



WDF_EXTERN_C_END

#endif // _UCXCONTROLLER_H_