windows-nt/Source/XPSP1/NT/drivers/wdm/usb/hcd/inc/usbhcdi.h

2409 lines
58 KiB
C
Raw Normal View History

2020-09-26 03:20:57 -05:00
/*++
Copyright (c) 1999 Microsoft Corporation
Module Name:
usb_hcdi.h
Abstract:
Environment:
Kernel & user mode
Revision History:
6-20-99 : created
--*/
#ifndef __USB_HCDI_H__
#define __USB_HCDI_H__
/*
Power management rules for USB host controllers transitioning from
USB suspend to USB working. This is what we expect for
S3->S0
S1->S0
1. The controller must not reset the USB bus or cause a disconnect or power
loss on any of the root USB ports.
2. The system BIOS must not enable any type of legacy USB BIOS or otherwise
enable the host controller to a run state.
3. If a PCI reset occurs in addition to rule 1 the BIOS must restore all
host registers to their state prior to entering low power. Root ports
should NOT indicate connect or enable status changes.
4. The controller hardware must be in a functional state -- capable of
driving resume and entering the run state without requiring a global
hardware reset that otherwise would result in a USB bus reset driven on
the root ports.
*/
#define USB_BAD_PTR ((PVOID) (-1))
/* status code returned by core functions */
typedef enum _USB_MINIPORT_STATUS {
USBMP_STATUS_SUCCESS = 0,
USBMP_STATUS_BUSY,
USBMP_STATUS_NO_RESOURCES,
USBMP_STATUS_NO_BANDWIDTH,
USBMP_STATUS_INIT_FAILURE,
USBMP_STATUS_FAILURE,
USBMP_STATUS_NOT_SUPPORTED,
USBMP_STATUS_HARDWARE_FAILURE,
USBMP_STATUS_NTERRCODE_NOT_MAPPFED,
} USB_MINIPORT_STATUS;
/* define a test guids for the miniport pass-thru interface */
/* {53D3650A-A4E7-4b0f-BC1D-B76DEB40FA1E}*/
DEFINE_GUID(MINIPORT_PASSTHRU_TEST_GUID,
0x53d3650a, 0xa4e7, 0x4b0f, 0xbc, 0x1d, 0xb7, 0x6d, 0xeb, 0x40, 0xfa, 0x1e);
/* {386289AA-02EC-486e-925E-838931877F4B}*/
DEFINE_GUID(MINIPORT_PASSTHRU_TEST_BADGUID,
0x386289aa, 0x2ec, 0x486e, 0x92, 0x5e, 0x83, 0x89, 0x31, 0x87, 0x7f, 0x4b);
// {386289AA-02EC-486e-925E-838931877F4B}
#define TEST_FLAG(var, flag) (((var) & (flag)) ? TRUE : FALSE)
#define CLEAR_FLAG(var, flag) ((var) &= ~(flag))
#define SET_FLAG(var, flag) ((var) |= (flag))
/*
Definition for the 32 bit physical address
that controller hardware understands.
If a miniport HW structure only supports 32 bit
physical addresses then this type is used to
indicate it.
*/
typedef ULONG HW_32BIT_PHYSICAL_ADDRESS;
typedef HW_32BIT_PHYSICAL_ADDRESS *PHW_32BIT_PHYSICAL_ADDRESS;
typedef PHYSICAL_ADDRESS HW_64BIT_PHYSICAL_ADDRESS;
typedef struct _MP_HW_PHYSICAL_ADDRESS {
union {
HW_32BIT_PHYSICAL_ADDRESS Hw32;
HW_64BIT_PHYSICAL_ADDRESS Hw64;
};
} MP_HW_PHYSICAL_ADDRESS, *PMP_HW_PHYSICAL_ADDRESS;
C_ASSERT((sizeof(MP_HW_PHYSICAL_ADDRESS) == 8));
/*
This structure is used for pointers embedded in
HW structures by the miniport. They is always sized
for 64 bit to limit 32/64 bit porting problems.
*/
typedef struct _MP_HW_POINTER {
PVOID Pointer;
#ifndef _WIN64
ULONG PadTo8;
#endif
} MP_HW_POINTER, *PMP_HW_POINTER;
C_ASSERT((sizeof(MP_HW_POINTER) == 8));
typedef struct _MP_HW_LIST_ENTRY {
LIST_ENTRY List;
#ifndef _WIN64
ULONG PadTo16[2];
#endif
} MP_HW_LIST_ENTRY, *PMP_HW_LIST_ENTRY;
C_ASSERT((sizeof(MP_HW_LIST_ENTRY) == 16));
#define PENDPOINT_DATA PVOID
#define PDEVICE_DATA PVOID
#define PTRANSFER_CONTEXT PVOID
/*
we redifine the USBDI HCD AREA for the miniport model
*/
struct _USBPORT_DATA {
PVOID HcdTransferContext;
PVOID UrbSig;
PVOID Reserved7[6];
};
#ifdef _WIN64
#define URB_SIG ((PVOID) 0xDEADF00DDEADF00D)
#else
#define URB_SIG ((PVOID) 0xDEADF00D)
#endif
//C_ASSERT(sizeof(struct _URB_HCD_AREA) == sizeof(struct _USBPORT_DATA))
#define IN_TRANSFER(tp) (((tp)->TransferFlags & \
USBD_TRANSFER_DIRECTION_IN) ? TRUE : FALSE)
#define SHORT_TRANSFER_OK(tp) (((tp)->TransferFlags & \
USBD_SHORT_TRANSFER_OK) ? TRUE : FALSE)
/*
Common transfer request parameter definition, all transfer
requests passed to the miniport will be mapped to this
format. The miniport will/can use this structure to
reference fields that are common to all transfers
as well as fields specific to isochronous and
control transfers.
*/
#define MPTX_SPLIT_TRANSFER 0x00000001
typedef struct _TRANSFER_PARAMETERS {
/* identical to URB field */
ULONG TransferFlags;
/* identical to URB field */
ULONG TransferBufferLength;
/* uniquely identifies a transfer set */
ULONG SequenceNumber;
/* miniport special handling requirements */
ULONG MiniportFlags;
/* USB frame this transfer completed in */
ULONG FrameCompleted;
/* setup packet for control transfers */
UCHAR SetupPacket[8];
} TRANSFER_PARAMETERS, *PTRANSFER_PARAMETERS;
typedef struct _MINIPORT_ISO_PACKET {
/*
length of this packet
*/
ULONG Length;
/*
bytes transferred this packet
*/
ULONG LengthTransferred;
/*
virtual frame to transmit this packet
*/
ULONG FrameNumber;
ULONG MicroFrameNumber;
/*
completion code for this packet
*/
USBD_STATUS UsbdStatus;
ULONG BufferPointerCount;
/* support up to 2 sg entries per packet */
/* max packet size for a USB 1.1 frame is ~1024 bytes*/
ULONG BufferPointer0Length;
MP_HW_PHYSICAL_ADDRESS BufferPointer0;
ULONG BufferPointer1Length;
MP_HW_PHYSICAL_ADDRESS BufferPointer1;
} MINIPORT_ISO_PACKET, *PMINIPORT_ISO_PACKET;
typedef struct _MINIPORT_ISO_TRANSFER {
ULONG Sig;
ULONG PacketCount;
PUCHAR SystemAddress;
MINIPORT_ISO_PACKET Packets[1];
} MINIPORT_ISO_TRANSFER, *PMINIPORT_ISO_TRANSFER;
/*
These structures are used to pass IoMapped transfer
buffers to the miniport
*/
//
// Page size and shift value used by the OHCI, EHCI and UHCI
// controller usb controllers use a defined
//
// this must always be 4k -- it is defined by the controller HW
#define USB_PAGE_SIZE 0x00001000
#define USB_PAGE_SHIFT 12L
typedef struct _TRANSFER_SG_ENTRY32 {
MP_HW_PHYSICAL_ADDRESS LogicalAddress;
PUCHAR SystemAddress;
ULONG Length;
ULONG StartOffset;
} TRANSFER_SG_ENTRY32, *PTRANSFER_SG_ENTRY32;
#define USBMP_SGFLAG_SINGLE_PHYSICAL_PAGE 0x00000001
typedef struct _TRANSFER_SG_LIST {
ULONG SgFlags;
PUCHAR MdlVirtualAddress;
PUCHAR MdlSystemAddress;
ULONG SgCount;
TRANSFER_SG_ENTRY32 SgEntry[1];
} TRANSFER_SG_LIST, *PTRANSFER_SG_LIST;
/**************************************************************
**************************************************************
USBPORT Interface Services
NOTES:
- these functions are callable at raised IRQL
***************************************************************
***************************************************************/
#define USBPRTFN __stdcall
/*
VOID
USBPORTSVC_InvalidateEndpoint(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData
);
*/
typedef VOID
(USBPRTFN *PPORTFN_INVALIDATE_ENDPOINT) (
PDEVICE_DATA,
PENDPOINT_DATA
);
/*
PUCHAR
USBPORTSVC_MapHwPhysicalToVirtual(
HW_32BIT_PHYSICAL_ADDRESS HwPhysicalAddress,
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData
)
maps a physical address from the miniport to
a virtual address
*/
typedef PUCHAR
(USBPRTFN *PPORTFN_PHYS_TO_VIRTUAL) (
HW_32BIT_PHYSICAL_ADDRESS,
PDEVICE_DATA,
PENDPOINT_DATA
);
/*
VOID
USBPORTSVC_CompleteTransfer(
PDEVICE_DATA DeviceData
PDEVICE_DATA EndpointData,
PTRANSFER_PARAMETERS TransferParameters,
USBD_STATUS UsbdStatus,
ULONG BytesTransferred
);
Called by miniport to complete an async transfer request
*/
typedef VOID
(USBPRTFN *PPORTFN_COMPLETE_TRANSFER) (
PDEVICE_DATA,
PENDPOINT_DATA,
PTRANSFER_PARAMETERS,
USBD_STATUS,
ULONG
);
/*
VOID
USBPORTSVC_CompleteIsoTransfer(
PDEVICE_DATA DeviceData
PDEVICE_DATA EndpointData,
PTRANSFER_PARAMETERS TransferParameters,
PMINIPORT_ISO_TRANSFER IsoTransfer
);
Called by miniport to complete an iso transfer request
*/
typedef VOID
(USBPRTFN *PPORTFN_COMPLETE_ISO_TRANSFER) (
PDEVICE_DATA,
PENDPOINT_DATA,
PTRANSFER_PARAMETERS,
PMINIPORT_ISO_TRANSFER
);
/* ROOT HUB functions */
/*
VOID
USBPORTSVC_InvalidateRootHub(
PDEVICE_DATA DeviceData
);
Called by the miniport to indicate the root hub
needs attention
*/
typedef VOID
(USBPRTFN *PPORTFN_INVALIDATE_ROOTHUB) (
PDEVICE_DATA
);
/* Debug functions */
/*
VOID
USBPORTSVC_DbgPrint(
PDEVICE_DATA DeviceData,
ULONG Level,
PCH Format,
PVOID Arg0,
PVOID Arg1,
PVOID Arg2,
PVOID Arg3,
PVOID Arg4,
PVOID Arg5
);
Called by miniport to print a message to the debugger
the message is printed if the var USBPORT_DEBUG_TRACE_LEVEL
is >= level.
*/
typedef VOID
(USBPRTFN *PPORTFN_DBGPRINT) (
PDEVICE_DATA,
ULONG,
PCH,
int,
int,
int,
int,
int,
int
);
/*
VOID
USBPORTSVC_TestDebugBreak(
PDEVICE_DATA DeviceData
);
Triggers a break in the debugger in the registry key
debugbreakOn is set. These breakpoins are useful for
debugging hardware/client software problems
*/
typedef VOID
(USBPRTFN *PPORTFN_TEST_DEBUG_BREAK) (
PDEVICE_DATA
);
/*
VOID
USBPORTSVC_AssertFailure(
PDEVICE_DATA DeviceData
PVOID FailedAssertion,
PVOID FileName,
ULONG LineNumber,
PCHAR Message
);
*/
typedef VOID
(USBPRTFN *PPORTFN_ASSERT_FAILURE) (
PDEVICE_DATA,
PVOID,
PVOID,
ULONG,
PCHAR
);
/*
VOID
USBPORTSVC_LogEntry(
PDEVICE_DATA DeviceData,
);
*/
/* Miniport LOG MASKS */
#define G 0x10000001 /* always log */
typedef VOID
(USBPRTFN *PPORTFN_LOGENTRY) (
PDEVICE_DATA,
ULONG,
ULONG,
ULONG_PTR,
ULONG_PTR,
ULONG_PTR
);
/* other functions */
/*
USB_MINIPORT_STATUS
USBPORTSVC_ReadWriteConfigSpace(
PDEVICE_DATA DeviceData,
BOOLEAN Read,
PVOID Buffer,
ULONG Offset,
ULONG Length
)
reads a registry key value from the branch associated
with the PDO for the host controller.
this API reads from either the software or hardware
branch
this function cannot be called at raised IRQL
*/
typedef USB_MINIPORT_STATUS
(USBPRTFN *PPORTFN_READWRITE_CONFIG_SPACE) (
PDEVICE_DATA,
BOOLEAN,
PVOID,
ULONG,
ULONG
);
/*
VOID
USBPORTSVC_Wait(
PDEVICE_DATA DeviceData,
ULONG MillisecondsToWait
)
Execute a syncronous wait for a specified number of
milliseconds
*/
typedef VOID
(USBPRTFN *PPORTFN_WAIT) (
PDEVICE_DATA,
ULONG
);
/*
VOID
USBPORTSVC_BugCheck(
PDEVICE_DATA DeviceData
)
*/
typedef VOID
(USBPRTFN *PPORTFN_BUGCHECK) (
PDEVICE_DATA
);
/*
VOID
USBPORTSVC_NotifyDoubleBuffer(
PDEVICE_DATA DeviceData
PTRANSFER_PARAMETERS TransferParameters,
PVOID SystemAddress,
ULONG Length
)
*/
typedef VOID
(USBPRTFN *PPORTFN_NOTIFY_DOUBLE_BUFFER) (
PDEVICE_DATA,
PTRANSFER_PARAMETERS,
PVOID,
ULONG
);
/*
USB_MINIPORT_STATUS
USBPORTSVC_GetMiniportRegistryKeyValue(
PDEVICE_DATA DeviceData,
BOOLEAN SoftwareBranch,
PWCHAR KeyNameString,
ULONG KeyNameStringLength,
PVOID Data,
ULONG DataLength
)
reads a registry key value from the branch associated
with the PDO for the host controller.
this API reads from either the software or hardware
branch
this function cannot be called at raised IRQL
*/
typedef USB_MINIPORT_STATUS
(USBPRTFN *PPORTFN_GET_MINIPORT_REGESTRY_KEY_VALUE) (
PDEVICE_DATA,
BOOLEAN,
PWCHAR,
ULONG,
PVOID,
ULONG
);
/*
VOID
USBPORTSVC_RequestAsyncCallback(
PDEVICE_DATA DeviceData,
ULONG MilliSecondInterval,
PVOID Context,
ULONG ContextLength,
PMPFN_MINIPORT_CALLBACK Callback
)
request an async callback when the millisecond interval
has elapsed.
The context field is copied ant the miniport is called back
with the copy so it is safe for the miniport to use a stack
variable as context.
*/
/*++
CallBack Definition for async notifiaction service
--*/
typedef VOID
(__stdcall *PMINIPORT_CALLBACK) (
PDEVICE_DATA,
PVOID
);
typedef VOID
(USBPRTFN *PPORTFN_REQUEST_ASYNC_CALLBACK) (
PDEVICE_DATA,
ULONG,
PVOID,
ULONG,
PMINIPORT_CALLBACK
);
/*
VOID
USBPORTSVC_InvalidateController(
PDEVICE_DATA DeviceData,
USB_CONTROLLER_STATE ControllerState
)
*/
typedef enum _USB_CONTROLLER_STATE {
UsbMpControllerPowerFault,
UsbMpControllerNeedsHwReset,
UsbMpControllerRemoved,
UsbMpSimulateInterrupt
} USB_CONTROLLER_STATE;
typedef VOID
(__stdcall *PPORTFN_INVALIDATE_CONTROLLER) (
PDEVICE_DATA,
USB_CONTROLLER_STATE
);
/**************************************************************
**************************************************************
USB MINIPORT interface functions
prototypes for functions called by the USB port driver
(usbport)
***************************************************************
***************************************************************/
#define USBMPFN __stdcall
/***************************************************************
CORE Functions
The following core functions are serialized as a group they
are assocaited with processing data transfers on the bus
MINIPORT_SubmitTransfer
MINIPORT_SubmitIsoTransfer
MINIPORT_AbortTransfer
MINIPORT_OpenEndpoint
MINIPORT_RebalanceEndpoint
MINIPORT_QueryEndpointRequirements
MINIPORT_CloseEndpoint
MINIPORT_SetEndpointState
MINIPORT_GetEndpointState
MINIPORT_PokeEndpoint
MINIPORT_PollEndpoint
MINIPORT_Get32bitFrameNumber
MINIPORT_InterruptNextSOF
MINIPORT_PollController
****************************************************************/
/*++
MINIPORT_SubmitTransfer
program a USB transfer, iso, bulk, interrupt or control to the hardware.
if no resources are avaiable then return USBMP_STATUS_BUSY.
if the transfer is successfully queued to the HW then return
USBMP_STATUS_SUCCESS
NOTES:
-At the time this routine is called the transfer buffer has been
mapped (ie no need to call IoMapTransfer).
URB_FUNCTION_CONTROL_TRANSFER
URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER
IRQL = DISPATCH_LEVEL
USB_MINIPORT_STATUS
MINIPORT_SubmitTransfer(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData,
PTRANSFER_PARAMETERS TransferParameters,
PTRANSFER_CONTEXT TransferContext,
PTRANSFER_SG_LIST TransferSGList
);
--*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_SUBMIT_TRANSFER) (
PDEVICE_DATA,
PENDPOINT_DATA,
PTRANSFER_PARAMETERS,
PTRANSFER_CONTEXT,
PTRANSFER_SG_LIST
);
/*++
MINIPORT_SubmitTransfer
program a USB transfer, iso, bulk, interrupt or control to the hardware.
if no resources are avaiable then return USBMP_STATUS_BUSY.
if the transfer is successfully queued to the HW then return
USBMP_STATUS_SUCCESS
NOTES:
-At the time this routine is called the transfer buffer has been
mapped (ie no need to call IoMapTransfer).
IRQL = DISPATCH_LEVEL
USB_MINIPORT_STATUS
MINIPORT_SubmitIsoTransfer(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData,
PTRANSFER_PARAMETERS TransferParameters,
PTRANSFER_CONTEXT TransferContext,
PMINIPORT_ISO_TRANSFER IsoTransfer
);
--*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_SUBMIT_ISO_TRANSFER) (
PDEVICE_DATA,
PENDPOINT_DATA,
PTRANSFER_PARAMETERS,
PTRANSFER_CONTEXT,
PMINIPORT_ISO_TRANSFER
);
/*++
MINIPORT_AbortTransfer
abort a specfic transfer that has been started, this will only be
called if the endpoint is in the ENDPOINT_PAUSED state.
this call is NOT failable and the HW must have no reference to
the transfer on return.
The miniport does not indicate completion.
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_AbortTransfer(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData,
PTRANSFER_CONTEXT TransferContext,
PULONG BytesTransferred
);
--*/
typedef VOID
(USBMPFN *PMPFN_ABORT_TRANSFER) (
PDEVICE_DATA,
PENDPOINT_DATA,
PTRANSFER_CONTEXT,
PULONG
);
/*++
MINIPORT_OpenEndpoint
open an endpoint.
PENDPOINT_DATA is the minport private endpoint
context
PENDPOINT_PARAMETERS describes the endpoint to open
for the miniport -- this information is READ_ONLY
on return the endpoint should be in the PAUSE state
IRQL = DISPATCH_LEVEL
USB_MINIPORT_STATUS
MINIPORT_OpenEndpoint(
PDEVICE_DATA DeviceData,
PENDPOINT_PARAMETERS EndpointParameters,
PENDPOINT_DATA EndpointData
);
--*/
typedef enum _ENDPOINT_TRANSFER_TYPE {
Isochronous = 0,
Control,
Bulk,
Interrupt
} ENDPOINT_TRANSFER_TYPE;
typedef enum _ENDPOINT_TRANSFER_DIRECTION {
In = 0,
Out
} ENDPOINT_TRANSFER_DIRECTION;
typedef enum _DEVICE_SPEED {
LowSpeed = 0,
FullSpeed,
HighSpeed
} DEVICE_SPEED;
/* these values are input by the port driver */
/*
Bandwidth Mamagement:
All bandwidth allocation is managed by the port driver. The
bandwidth consumed by an endpoint is passed to the miniport
but this is purely informational.
Load balancing for interrupt endpoints is handled by passing
the miniport the appropriate schedule offset for an interrupt
endpoint.
interrupt endpoints may occupy different locations in the
schedule dpeneding on the period. The consume bandwidth only
for locations they occupy. This is the 'ScheduleOffset'.
USBPORT will choose an appropriate schedule offset and pass this
to the miniport for the open.
period offsets
1 0
2 0,1
4 0,..3
8 0,..7
16 0,..15
32 0,..31
*/
typedef struct _ENDPOINT_PARAMETERS {
USHORT DeviceAddress;
USHORT EndpointAddress;
USHORT MaxPacketSize;
// adjusted interrupt period
// will be one of : 128, 64, 32, 16, 8, 4, 2, 1
UCHAR Period;
UCHAR MaxPeriod;
// bandwidth required in bits/ms
// ie the reserved bw that this endpont will
// consume
DEVICE_SPEED DeviceSpeed;
ULONG Bandwidth;
ULONG ScheduleOffset;
ENDPOINT_TRANSFER_TYPE TransferType;
ENDPOINT_TRANSFER_DIRECTION TransferDirection;
PUCHAR CommonBufferVa;
HW_32BIT_PHYSICAL_ADDRESS CommonBufferPhys;
ULONG CommonBufferBytes;
// endpoint parm flags
ULONG EndpointFlags;
ULONG MaxTransferSize;
// usb 2.0 parameters
// device address of the hub (TT) for this ep
USHORT TtDeviceAddress;
// port number (really TT number) of the TT for
// this device
USHORT TtPortNumber;
UCHAR InterruptScheduleMask;
UCHAR SplitCompletionMask;
UCHAR TransactionsPerMicroframe;
UCHAR Pad;
USHORT MuxPacketSize;
ULONG Ordinal;
} ENDPOINT_PARAMETERS, *PENDPOINT_PARAMETERS;
/* these are returned by the miniport */
typedef struct _ENDPOINT_REQUIREMENTS {
/* size of the common buffer the
miniport will need to service
this endpoint */
ULONG MinCommonBufferBytes;
/*
the largest single transfer this endpoint
can handle. If a client driver passes
down a larger transfer usbport will break
it in to multiple requests.
MinCommonBufferBytes/sizeof(TD) should be
enough TDs to statify at least one request
of MaximumTransferSize.
Ideally it should be able to handle two -- this
will ensure that the bus does not go idle.
*/
ULONG MaximumTransferSize;
} ENDPOINT_REQUIREMENTS, *PENDPOINT_REQUIREMENTS;
// **
// EP_PARM_FLAG_
// Enpoint Parameter flags, describe required endpoint
// behaviors including possible optimaizations
//#define EP_PARM_FLAG_ 0x00000002
//
// EP_PARM_FLAG_NOHALT - the endpoint should not halt on the
// host side as a result of a bus error
//
#define EP_PARM_FLAG_NOHALT 0x00000004
// optimization flags
#define EP_PARM_ISO_BUFFERING 0x00000008
//
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_OPEN_ENDPOINT) (
PDEVICE_DATA,
PENDPOINT_PARAMETERS,
PENDPOINT_DATA
);
/*++
MINIPORT_PokeEndpoint
poke an endpoint.
use to change the address of an endpoint without
removing it from the schedule.
**This API is used exclusively to change the endpoint
address.
PENDPOINT_DATA is the minport private endpoint
context
PENDPOINT_PARAMETERS describes the endpoint to open
for the miniport -- this information is READ_ONLY
IRQL = DISPATCH_LEVEL
USB_MINIPORT_STATUS
MINIPORT_PokeEndpoint(
PDEVICE_DATA DeviceData,
PENDPOINT_PARAMETERS EndpointParameters,
PENDPOINT_DATA EndpointData
);
--*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_POKE_ENDPOINT) (
PDEVICE_DATA,
PENDPOINT_PARAMETERS,
PENDPOINT_DATA
);
/*++
MINIPORT_RebalanceEndpoint
PENDPOINT_DATA is the minport private endpoint
context
PENDPOINT_PARAMETERS describes the endpoint to open
for the miniport -- this information is READ_ONLY
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_RebalanceEndpoint(
PDEVICE_DATA DeviceData,
PENDPOINT_PARAMETERS EndpointParameters,
PENDPOINT_DATA EndpointData
);
--*/
typedef VOID
(USBMPFN *PMPFN_REBALANCE_ENDPOINT) (
PDEVICE_DATA,
PENDPOINT_PARAMETERS,
PENDPOINT_DATA
);
/*++
MINIPORT_QueryEndpointRequirements
PENDPOINT_DATA is the minport private endpoint
context
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_QueryEndpointRequirements(
PDEVICE_DATA DeviceData,
PENDPOINT_PARAMETERS EndpointParameters,
PENDPOINT_REQUIREMENTS EndpointRequirements
);
Notes on Maximum Transfer Sizes:
Control:
The miniport can assume that no Control transfer buffer passed to
it will be larger than EndpointParameters.MAXTRANSFERSIZE. The miniport
should request enough locked memory (common buffer) to support at least
one control transfer.
TBD - The miniport may optionally request that the controller transfer
be limmited to a smaller value by setting
EndpointRequirements.MAXTRANSFERSIZE. In this case the miniport must
support fragmented control tranfsers.
EndpointParameters.MAXTRANSFERSIZE can never be larger than 64k by spec.
Interrupt:
The miniport can indicate the max transfer size for each interrupt
transfer it can handle in EndpointRequirements.MAXTRANSFERSIZE.
Assume that no transfer buffer will be larger than the this size.
EndpointParameters.MAXTRANSFERSIZE is the default value. The miniport
should allocate resources to handle at least two transfers of this size.
Bulk:
The miniport can indicate the max transfer size for each bulk transfer
it can handle in EndpointRequirements.MAXTRANSFERSIZE. No transfer will
be passed in larger than this value. The miniport must request enough
resources to program at least two transfers of this size into the hardware.
MAXTRANSFERSIZE must be at least 4k.
EndpointParameters.MAXTRANSFERSIZE is the default value.
Basic Iso:
Miniport may specify an EndpointRequirements.MAXTRANSFERSIZE size
but it must also be able to always handle at least two transfers of
MAX_ISO_PACKETS_PER_TRANSFER.
--*/
/*
Historical Note:
The orignal USBD driver shipped in Win98 thru Win2k limits iso requests
to 255 packets so we are safe to set this limit at 256.
This is 256ms for full speed and 32 ms for High speed on the hardware
per request which is plenty.
*/
#define MAX_ISO_PACKETS_PER_TRANSFER 256
typedef VOID
(USBMPFN *PMPFN_QENDPOINT_REQUIREMENTS) (
PDEVICE_DATA,
PENDPOINT_PARAMETERS,
PENDPOINT_REQUIREMENTS
);
/*++
MINIPORT_PollEndpoint
Poll the endpoint for done transfers or other changes
PENDPOINT_DATA is the minport private endpoint
context
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_PollEndpoint(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData
);
--*/
typedef VOID
(USBMPFN *PMPFN_POLL_ENDPOINT) (
PDEVICE_DATA,
PENDPOINT_DATA
);
/*
MINIPORT_CloseEndpoint
close an endpoint, PENDPOINT_DATA is the minport private endpoint
context
free any resources allocated for the endpoint other than BW
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_CloseEndpoint(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData
);
*/
typedef VOID
(USBMPFN *PMPFN_CLOSE_ENDPOINT) (
PDEVICE_DATA,
PENDPOINT_DATA
);
/*
MINIPORT_SetEndpointState
Set an endpoint to one of our defined transfer states, the endpoint
need not be in the state when the miniport returns.
There is an assumption here that the enpoint will reach the
desired state on the next SOF, the port will keep track of
this and assume that the state transition has occurred after
one ms frame has passed.
These are software state, changes can only be intiated by a
request thru the MINIPORT_SetEndpointState function. endpoints
cannot transition on their own.
ENDPOINT_IDLE
The endpoint has no active transfer, set this endpoint to a
state that generates minimal activity on the contoller (ie
remove it from the schedule,set skip bit etc)
ENDPOINT_PAUSE
temporarily stop any bus activity associated with the endpoint,
this is a prelude to receiving an abortTransfer.
ENDPOINT_ACTIVE
enable processing of the enpoint -- ie it is in the schedule and
ready for action
ENDPOINT_REMOVE
the endpoint has been removed from the HW schedule
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_SetEndpointState(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData
MP_ENDPOINT_STATE
);
MP_ENDPOINT_STATE
MINIPORT_GetEndpointState(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndpointData
);
*/
typedef enum _MP_ENDPOINT_STATE {
ENDPOINT_TRANSITION = 0,
ENDPOINT_IDLE,
ENDPOINT_PAUSE,
ENDPOINT_ACTIVE,
ENDPOINT_REMOVE,
ENDPOINT_CLOSED
} MP_ENDPOINT_STATE;
typedef VOID
(USBMPFN *PMPFN_SET_ENDPOINT_STATE) (
PDEVICE_DATA,
PENDPOINT_DATA,
MP_ENDPOINT_STATE
);
typedef MP_ENDPOINT_STATE
(USBMPFN *PMPFN_GET_ENDPOINT_STATE) (
PDEVICE_DATA,
PENDPOINT_DATA
);
/*++
MINIPORT_SetEndpointDataToggle
resets the data toggle for an endpoint
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_SetEndpointDataToggle(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndointData,
ULONG Toggle
);
--*/
typedef VOID
(USBMPFN *PMPFN_SET_ENDPOINT_DATA_TOGGLE) (
PDEVICE_DATA,
PENDPOINT_DATA,
ULONG
);
/*++
MINIPORT_GetEndpointStatus
returns the status of an endpoint ie HALTED
the status of the endpoint is controlled by the HW.
IRQL = DISPATCH_LEVEL
MP_ENDPOINT_STATUS
MINIPORT_GetEndpointStatus(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndointData
);
VOID
MINIPORT_SetEndpointStatus(
PDEVICE_DATA DeviceData,
PENDPOINT_DATA EndointData,
MP_ENDPOINT_STATUS EpStatus
);
--*/
typedef enum _MP_ENDPOINT_STATUS {
ENDPOINT_STATUS_RUN = 0,
ENDPOINT_STATUS_HALT
} MP_ENDPOINT_STATUS;
typedef MP_ENDPOINT_STATUS
(USBMPFN *PMPFN_GET_ENDPOINT_STATUS) (
PDEVICE_DATA,
PENDPOINT_DATA
);
typedef VOID
(USBMPFN *PMPFN_SET_ENDPOINT_STATUS) (
PDEVICE_DATA,
PENDPOINT_DATA,
MP_ENDPOINT_STATUS
);
/*++
MINIPORT_Get32BitFrameNumber
returns the 32 bit frame number maintained by the HCD
IRQL = DISPATCH_LEVEL
ULONG
MINIPORT_Get32BitFrameNumber(
PDEVICE_DATA DeviceData
);
--*/
typedef ULONG
(USBMPFN *PMPFN_GET_32BIT_FRAME_NUMBER) (
PDEVICE_DATA
);
/*++
MINIPORT_InterruptNextSOF
requests an interrupt at the next SOF interval
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_InterruptNextSOF(
PDEVICE_DATA DeviceData
);
--*/
typedef VOID
(USBMPFN *PMPFN_INTERRUPT_NEXT_SOF) (
PDEVICE_DATA
);
/*
MINIPORT_PollController
Optional Poll routine for miniport this function will
be called at the MiniportPollInterval specficeid in
the registration packet.
Specifying a vlue of zero disables polling of the
controller.
IRQL = ANY
VOID
MINIPORT_PollController (
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_POLL_CONTROLLER) (
PDEVICE_DATA
);
/***************************************************************
PNP/POWER Functions
The following core pnp functions are serialized as a group
****************************************************************/
/*
MINIPORT_CheckController
Entry point called by usbport periodically to check the hardware
state, this function is not serialized. Typically this is used to
detect surprise removal of the hardware.
IRQL = ANY
VOID
MINIPORT_CheckController(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_CHECK_CONTROLLER) (
PDEVICE_DATA
);
/*
MINIPORT_StartController
Initialize Hardware, allocate memory etc.
on return (STATUS_SUCCESS) the device is considered started and
powered and must handle ALL CORE functions.
the miniport should disable any BIOS if present
the last thing the driver should do before returning is enable
interrupt generation by the controller
HcParameters are filled in by the miniport
IRQL = PASSIVE_LEVEL
USB_MINIPORT_STATUS
MINIPORT_StartController(
PDEVICE_DATA DeviceData,
PHC_RESOURCES HcResources
);
*/
typedef struct _HC_RESOURCES {
/* values for Flags field */
#define HCR_IO_REGS 0x0000001
#define HCR_IRQ 0x0000002
#define HCR_MEM_REGS 0x0000004
ULONG Flags;
USB_CONTROLLER_FLAVOR ControllerFlavor;
/* interrupt */
ULONG InterruptVector;
KIRQL InterruptLevel;
KAFFINITY Affinity;
BOOLEAN ShareIRQ;
KINTERRUPT_MODE InterruptMode;
PKINTERRUPT InterruptObject;
/* io ports */
/* memory mapped */
PVOID DeviceRegisters;
ULONG DeviceRegistersLength;
PUCHAR CommonBufferVa;
HW_32BIT_PHYSICAL_ADDRESS CommonBufferPhys;
/* BIOS detected
filled in by miniport
*/
BOOLEAN DetectedLegacyBIOS;
BOOLEAN Restart;
} HC_RESOURCES, *PHC_RESOURCES;
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_START_CONTROLLER) (
PDEVICE_DATA,
PHC_RESOURCES
);
/*
MINIPORT_StopController
disconnect interrupt, free memory etc.
on return (non Failable) the device is considered stopped and
powered down and will no longer receicve calls to CORE functions.
NOTES:
- The miniport will only receive a stop request if it was
successfuly started.
- Miniport should disable all interrupts from the hardware.
- if Hardware Present is FALSE the miniport should not access
memory registers or ioports.
IRQL = PASSIVE_LEVEL
VOID
MINIPORT StopController(
PDEVICE_DATA DeviceData,
BOOLEAN HardwarePresent
);
*/
typedef VOID
(USBMPFN *PMPFN_STOP_CONTROLLER) (
PDEVICE_DATA,
BOOLEAN
);
/*
MINIPORT_ResetController
Reset the host controller hardware
This function is serialized with the ISR and DPC and holds
the core function lock in order to provide a safe environment
or the miniport to reset the host hardware.
VOID
MINIPORT ResetController(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_RESET_CONTROLLER) (
PDEVICE_DATA
);
/*
MINIPORT_SuspendController
IRQL = PASSIVE_LEVEL
VOID
MINIPORT SuspendController(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_SUSPEND_CONTROLLER) (
PDEVICE_DATA
);
/*
MINIPORT_ResumeController
Attempts to resume HC HW from the suspend state. The miniport
may fail this in the event the controller has been hosed by the
BIOS. In that even the port driver may attempt to power cycle.
IRQL = PASSIVE_LEVEL
VOID
MINIPORT ResumeController(
PDEVICE_DATA DeviceData
);
*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_RESUME_CONTROLLER) (
PDEVICE_DATA
);
/*
MINIPORT_FlushInterrupts
Flush Interrupts on the USB the controller HW
IRQL = PASSIVE_LEVEL
VOID
MINIPORT FlushInterrupts(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_FLUSH_INTERRUPTS) (
PDEVICE_DATA
);
/*
MINIPORT_TakePortControl
Pre start controller initialization
IRQL = PASSIVE_LEVEL
VOID
MINIPORT_TakePortControl(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_TAKE_PORT_CONTROL) (
PDEVICE_DATA
);
/*
MINIPORT_EnableInterrupts
Enable Interrupts by the USB the controller HW
IRQL = PASSIVE_LEVEL
VOID
MINIPORT EnableInterrupts(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_ENABLE_INTERRUPTS) (
PDEVICE_DATA
);
/*
MINIPORT_DisableInterrupts
Disable Interrupts by the USB the controller HW
On return from this function the controller is expected to
not generate ANY interrupts.
Also the controller should ack all interrupts since on return
from this routine the ISR & ISRDPC will no longer be called.
IRQL = This function is synchronized with the ISR
VOID
MINIPORT DisableInterrupts(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_DISABLE_INTERRUPTS) (
PDEVICE_DATA
);
/***************************************************************
ROOT HUB Functions
MINIPORT_RH_GetRootHubData
MINIPORT_RH_DisableIrq
MINIPORT_RH_EnableIrq
MINIPORT_RH_GetStatus
MINIPORT_RH_GetPortStatus
MINIPORT_RH_GetHubStatus
Port Functions, all use PMPFN_RH_PORT_FUNCTION
MINIPORT_RH_SetFeaturePortReset
MINIPORT_RH_SetFeaturePortSuspend
MINIPORT_RH_SetFeaturePortPower
MINIPORT_RH_SetFeaturePortEnable
MINIPORT_RH_ClearFeaturePortEnable
MINIPORT_RH_ClearFeaturePortSuspend
MINIPORT_RH_ClearFeaturePortPower
MINIPORT_RH_ClearFeaturePortConnectChange
MINIPORT_RH_ClearFeaturePortResetChange
MINIPORT_RH_ClearFeaturePortEnableChange
MINIPORT_RH_ClearFeaturePortSuspendChange
MINIPORT_RH_ClearFeaturePortOvercurrentChange
****************************************************************/
/*
root hub port status data as defined in the Hub Class
section of the CORE (USB 1.1) spec.
*/
typedef struct _RH_PORT_STATUS {
union {
struct {
/* Status bits 0.. 15 */
ULONG Connected:1;
ULONG Enabled:1;
ULONG Suspended:1;
ULONG OverCurrent:1;
ULONG Reset:1;
ULONG Reserved0:3;
ULONG PowerOn:1;
ULONG LowSpeed:1;
ULONG HighSpeed:1;
ULONG Reserved1:4;
/* borrowed from reserved bits to indicate
port disposition */
ULONG OwnedByCC:1;
/* Change bits 16..31 */
ULONG ConnectChange:1;
ULONG EnableChange:1;
ULONG SuspendChange:1;
ULONG OverCurrentChange:1;
ULONG ResetChange:1;
ULONG Reserved2:11;
};
ULONG ul;
};
} RH_PORT_STATUS, *PRH_PORT_STATUS;
C_ASSERT(sizeof(RH_PORT_STATUS) == sizeof(ULONG));
typedef struct _RH_HUB_STATUS {
/* Status bits 0.. 15 */
union {
struct {
ULONG LocalPowerLost:1;
ULONG OverCurrent:1;
ULONG Reserved:14;
/* Change bits 16..31 */
ULONG LocalPowerChange:1;
ULONG OverCurrentChange:1;
ULONG Reserved2:14;
};
ULONG ul;
};
} RH_HUB_STATUS, *PRH_HUB_STATUS;
C_ASSERT(sizeof(RH_HUB_STATUS) == sizeof(ULONG));
/*
Hub Charateristics as defined
in 11.11.2 of the USB core spec.
*/
/* PowerSwitchType */
#define USBPORT_RH_POWER_SWITCH_GANG 0
#define USBPORT_RH_POWER_SWITCH_PORT 1
typedef union _RH_HUB_CHARATERISTICS {
USHORT us;
struct {
/*
00 = Gang switched
01 = port power switched
1x = 1.0 hubs with no power
switching
*/
USHORT PowerSwitchType:2; /* 0-1 */
USHORT CompoundDevice:1; /* 2 */
USHORT OverCurrentProtection:2; /* 3-4 */
USHORT Reserved:11; /* 5-15 */
};
} RH_HUB_CHARATERISTICS, *PRH_HUB_CHARATERISTICS;
C_ASSERT(sizeof(RH_HUB_CHARATERISTICS) == sizeof(USHORT));
typedef struct _ROOTHUB_DATA {
ULONG NumberOfPorts; // number of ports on this hub
RH_HUB_CHARATERISTICS HubCharacteristics;
USHORT pad;
ULONG PowerOnToPowerGood; // port power on till power good in 2ms
ULONG HubControlCurrent; // max current in mA
} ROOTHUB_DATA, *PROOTHUB_DATA;
/*
MINIPORT_RH_GetRootHubData
get information about the root hub, port
driver uses this information to emulate
the root hub for the miniport
IRQL = PASSIVE_LEVEL
VOID
MINIPORT_RH_GetRootHubData(
PDEVICE_DATA DeviceData,
PROOTHUB_DATA HubData
);
*/
typedef VOID
(USBMPFN *PMPFN_RH_GET_ROOTHUB_DATA) (
PDEVICE_DATA,
PROOTHUB_DATA
);
/*
MINIPORT_RH_GetStatus
Used to support the GET_STATUS command sent to the root hub device.
may return with the following bits set in Status
USB_GETSTATUS_SELF_POWERED 0x01
USB_GETSTATUS_REMOTE_WAKEUP_ENABLED 0x02
are we self powered?
are we a remote wakeup source?
see section 9.4.5 USB 1.1 spec
IRQL = PASSIVE_LEVEL
USB_MINIPORT_STATUS
MINIPORT_RH_GetStatus(
PDEVICE_DATA DeviceData
PUSHORT Status
);
*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_RH_GET_STATUS) (
PDEVICE_DATA,
PUSHORT
);
/*
MINIPORT_RH_DisableIrq (OPTIONAL)
If the comntroller is capable of generating interrupts
on root hub status changes then it must provide this
service to disable/enable the feature.
IRQL = DPC_LEVEL
VOID
MINIPORT_RH_DisableIrq(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_RH_DISABLE_IRQ) (
PDEVICE_DATA
);
/*
MINIPORT_RH_EnableIrq (OPTIONAL)
IRQL = DPC_LEVEL
VOID
MINIPORT_RH_EnableIrq(
PDEVICE_DATA DeviceData
);
*/
typedef VOID
(USBMPFN *PMPFN_RH_ENABLE_IRQ) (
PDEVICE_DATA
);
/*
MINIPORT_RH_GetPortStatus
Used to support the GET_STATUS hub class command sent
to the root hub interface for a port.
PortNumber = 1,2, etc
see section 11.16.2.5 of USB 1.1 spec
IRQL = PASSIVE_LEVEL
USB_MINIPORT_STATUS
MINIPORT_RH_GetPortStatus(
PDEVICE_DATA DeviceData,
USHORT PortNumber,
PRH_PORT_STATUS PortStatus
);
*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_RH_GET_PORT_STATUS) (
PDEVICE_DATA,
USHORT,
PRH_PORT_STATUS
);
/*
MINIPORT_RH_GetHubStatus
Used to support the GET_STATUS hub class command sent
to the root hub interface for a hub.
IRQL = PASSIVE_LEVEL
USB_MINIPORT_STATUS
MINIPORT_RH_GetHubStatus(
PDEVICE_DATA DeviceData,
PRH_HUB_STATUS HubStatus
);
*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_RH_GET_HUB_STATUS) (
PDEVICE_DATA,
PRH_HUB_STATUS
);
/*
MINIPORT_RH_PORT_FUNCTION
format for root hub services that act on ports.
PortNumber = 1,2, etc
IRQL = PASSIVE_LEVEL
USB_MINIPORT_STATUS
MINIPORT_RH_PORT_FUNCTION(
PDEVICE_DATA DeviceData,
USHORT PortNumber
);
The following services use the MINIPORT_RH_PORT_FUNCTION
format
MINIPORT_RH_SetFeaturePortReset
MINIPORT_RH_SetFeaturePortPower
MINIPORT_RH_SetFeaturePortEnable
MINIPORT_RH_SetFeaturePortSuspend
MINIPORT_RH_ClearFeaturePortEnable
MINIPORT_RH_ClearFeaturePortPower
MINIPORT_RH_ClearFeaturePortEnableChange
MINIPORT_RH_ClearFeaturePortConnectChange
MINIPORT_RH_ClearFeaturePortResetChange
*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_RH_PORT_FUNCTION) (
PDEVICE_DATA,
USHORT
);
/***************************************************************
INTERRUPT Functions
these functions are not serialized
****************************************************************/
/*
MINIPORT_InterruptService
IRQL = ANY
BOOLEAN
MINIPORT_InterruptService (
PDEVICE_DATA DeviceData
);
*/
typedef BOOLEAN
(USBMPFN *PMPFN_INTERRUPT_SERVICE) (
PDEVICE_DATA
);
/*
MINIPORT_InterruptDpc
Called by port in response to an interrupt generated by the HW.
This function is not serialize with other core functions since
which allow it to call services in USBPORT that result in
immediate calls to core functions.
The port driver passes a flag to indicate if interrupts need
to be re-enabled on completion of this routine. This is to handle
the rare case where interrupts have been disabled just after the
ISR has queued a DPC.
IRQL = DISPATCH_LEVEL
VOID
MINIPORT_InterruptDpc (
PDEVICE_DATA DeviceData
BOOLEAN EnableInterrupts
);
*/
typedef VOID
(USBMPFN *PMPFN_INTERRUPT_DPC) (
PDEVICE_DATA,
BOOLEAN
);
/***************************************************************
DEBUG/TEST Functions
****************************************************************/
/*
MINIPORT_SendOnePacket
IRQL = ANY
used to support the single-step debug application. This api is
OPTIONAL
VOID
MINIPORT_SendOnePacket (
PDEVICE_DATA DeviceData,
PPACKET_PARAMETERS PacketParameters,
PUCHAR PacketData,
PULONG PacketLength,
PUCHAR WorkspaceVirtualAddress,
HW_32BIT_PHYSICAL_ADDRESS WorkspacePhysicalAddress,
ULONG WorkspaceLength,
PUSBD_STATUS UsbdStatus
);
*/
typedef enum _SS_PACKET_TYPE {
ss_Setup = 0,
ss_In,
ss_Out,
ss_Iso_In,
ss_Iso_Out
} SS_PACKET_TYPE;
typedef enum _SS_PACKET_SPEED {
ss_Low = 0,
ss_Full,
ss_High
} SS_PACKET_SPEED;
typedef enum _SS_PACKET_DATA_TOGGLE {
ss_Toggle0 = 0,
ss_Toggle1
} SS_PACKET_DATA_TOGGLE;
typedef struct _MP_PACKET_PARAMETERS {
UCHAR DeviceAddress;
UCHAR EndpointAddress;
USHORT MaximumPacketSize;
USHORT ErrorCount;
USHORT Pad;
SS_PACKET_TYPE Type;
SS_PACKET_SPEED Speed;
SS_PACKET_DATA_TOGGLE Toggle;
/* 2.0 hubs */
USHORT HubDeviceAddress;
USHORT PortTTNumber;
} MP_PACKET_PARAMETERS, *PMP_PACKET_PARAMETERS;
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_SEND_ONE_PACKET) (
PDEVICE_DATA,
PMP_PACKET_PARAMETERS,
PUCHAR,
PULONG,
PUCHAR,
HW_32BIT_PHYSICAL_ADDRESS,
ULONG,
USBD_STATUS *
);
/***************************************************************
API Functions
These are called at IRQL passive_level
****************************************************************/
/*
MINIPORT_PassThru
IRQL = PASSIVE_LEVEL
USB_MINIPORT_STATUS
MINIPORT_PassThru (
PDEVICE_DATA DeviceData,
GUID *FunctionGuid,
ULONG ParameterLength,
PVOID Parameters
);
*/
typedef USB_MINIPORT_STATUS
(USBMPFN *PMPFN_PASS_THRU) (
PDEVICE_DATA,
GUID *,
ULONG,
PVOID
);
/***************************************************************
***************************************************************
REGISTRATION PACKET
***************************************************************
****************************************************************/
/* HCI Hardware Types */
typedef enum _USB_HCI_TYPE {
USB_UNKNOWN_HCI = 0,
USB_OHCI,
USB_UHCI,
USB_EHCI
} USB_HCI_TYPE;
/* Miniport Option Flags */
/* resources required by miniport */
#define USB_MINIPORT_OPT_NEED_IRQ 0x00000001
#define USB_MINIPORT_OPT_NEED_IOPORT 0x00000002
#define USB_MINIPORT_OPT_NEED_MEMORY 0x00000004
/* USB version */
#define USB_MINIPORT_OPT_USB11 0x00000008
#define USB_MINIPORT_OPT_USB20 0x00000010
/* support selective suspend */
#define USB_MINIPORT_OPT_NO_SS 0x00000020
/* disables synchronization of the ISRDPC and the
MP_DisableInterrupts function. usbed by UHCI
to clear/ set PIRQD in config space. */
#define USB_MINIPORT_OPT_NO_IRQ_SYNC 0x00000040
/* indicates controller poll routine should be called
this will always be at least ounce evert 500ms
*/
#define USB_MINIPORT_OPT_POLL_CONTROLLER 0x00000080
/* for bridge drivers with no hw resources */
#define USB_MINIPORT_OPT_NO_PNP_RESOURCES 0x00000100
/* poll whe HW suspended */
#define USB_MINIPORT_OPT_POLL_IN_SUSPEND 0x00000200
#define USB_MINIPORT_HCI_VERSION USB_MINIPORT_HCI_VERSION_1
#define USB_MINIPORT_HCI_VERSION_1 100
#define USB_MINIPORT_HCI_VERSION_2 200
/*
Bus Bandwidth defined by spec
*/
#define USB_11_BUS_BANDWIDTH 12000
#define USB_20_BUS_BANDWIDTH 400000
#define USB_HCI_MN 0x10000001
/* version shipped with XP 2600 this must remaon unchanged */
typedef struct _USBPORT_REGISTRATION_PACKET_V1 {
/* begin version (1) interface definition */
/* Host Controller HCI Type */
USB_HCI_TYPE HciType;
/* registration parameters */
ULONG OptionFlags;
/*
Total bus bandwidth avaibale in MBits
*/
ULONG BusBandwidth;
LONG Reserved;
ULONG DeviceDataSize;
ULONG EndpointDataSize;
ULONG TransferContextSize;
/* 7 char ASCII NULL terminated name */
UCHAR Name[8];
/*
Amount of global common buffer needed
this memory is passed to the miniport on
a start and freed on a stop
*/
ULONG CommonBufferBytes;
/* miniport Functions */
PMPFN_OPEN_ENDPOINT MINIPORT_OpenEndpoint;
PMPFN_POKE_ENDPOINT MINIPORT_PokeEndpoint;
PMPFN_QENDPOINT_REQUIREMENTS MINIPORT_QueryEndpointRequirements;
PMPFN_CLOSE_ENDPOINT MINIPORT_CloseEndpoint;
PMPFN_START_CONTROLLER MINIPORT_StartController;
PMPFN_STOP_CONTROLLER MINIPORT_StopController;
PMPFN_SUSPEND_CONTROLLER MINIPORT_SuspendController;
PMPFN_RESUME_CONTROLLER MINIPORT_ResumeController;
PMPFN_INTERRUPT_SERVICE MINIPORT_InterruptService;
PMPFN_INTERRUPT_DPC MINIPORT_InterruptDpc;
PMPFN_SUBMIT_TRANSFER MINIPORT_SubmitTransfer;
PMPFN_SUBMIT_ISO_TRANSFER MINIPORT_SubmitIsoTransfer;
PMPFN_ABORT_TRANSFER MINIPORT_AbortTransfer;
PMPFN_GET_ENDPOINT_STATE MINIPORT_GetEndpointState;
PMPFN_SET_ENDPOINT_STATE MINIPORT_SetEndpointState;
PMPFN_POLL_ENDPOINT MINIPORT_PollEndpoint;
PMPFN_CHECK_CONTROLLER MINIPORT_CheckController;
PMPFN_GET_32BIT_FRAME_NUMBER MINIPORT_Get32BitFrameNumber;
PMPFN_INTERRUPT_NEXT_SOF MINIPORT_InterruptNextSOF;
PMPFN_ENABLE_INTERRUPTS MINIPORT_EnableInterrupts;
PMPFN_DISABLE_INTERRUPTS MINIPORT_DisableInterrupts;
PMPFN_POLL_CONTROLLER MINIPORT_PollController;
PMPFN_SET_ENDPOINT_DATA_TOGGLE MINIPORT_SetEndpointDataToggle;
PMPFN_GET_ENDPOINT_STATUS MINIPORT_GetEndpointStatus;
PMPFN_SET_ENDPOINT_STATUS MINIPORT_SetEndpointStatus;
PMPFN_RESET_CONTROLLER MINIPORT_ResetController;
/* root hub functions */
PMPFN_RH_GET_ROOTHUB_DATA MINIPORT_RH_GetRootHubData;
PMPFN_RH_GET_STATUS MINIPORT_RH_GetStatus;
PMPFN_RH_GET_PORT_STATUS MINIPORT_RH_GetPortStatus;
PMPFN_RH_GET_HUB_STATUS MINIPORT_RH_GetHubStatus;
/* root hub port functions */
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortReset;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortPower;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortEnable;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortSuspend;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortEnable;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortPower;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortSuspend;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortEnableChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortConnectChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortResetChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortSuspendChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortOvercurrentChange;
/* optional root hub functions */
PMPFN_RH_DISABLE_IRQ MINIPORT_RH_DisableIrq;
PMPFN_RH_ENABLE_IRQ MINIPORT_RH_EnableIrq;
/* OPTIONAL DEBUG SERVICES
Miniport should return USBMP_STATUS_NOT_SUPPORTED for the
services not supported.
*/
PMPFN_SEND_ONE_PACKET MINIPORT_StartSendOnePacket;
PMPFN_SEND_ONE_PACKET MINIPORT_EndSendOnePacket;
/* PASS-THRU API function
*/
PMPFN_PASS_THRU MINIPORT_PassThru;
/* interface Services */
PPORTFN_DBGPRINT USBPORTSVC_DbgPrint;
PPORTFN_TEST_DEBUG_BREAK USBPORTSVC_TestDebugBreak;
PPORTFN_ASSERT_FAILURE USBPORTSVC_AssertFailure;
PPORTFN_GET_MINIPORT_REGESTRY_KEY_VALUE USBPORTSVC_GetMiniportRegistryKeyValue;
PPORTFN_INVALIDATE_ROOTHUB USBPORTSVC_InvalidateRootHub;
PPORTFN_INVALIDATE_ENDPOINT USBPORTSVC_InvalidateEndpoint;
PPORTFN_COMPLETE_TRANSFER USBPORTSVC_CompleteTransfer;
PPORTFN_COMPLETE_ISO_TRANSFER USBPORTSVC_CompleteIsoTransfer;
PPORTFN_LOGENTRY USBPORTSVC_LogEntry;
PPORTFN_PHYS_TO_VIRTUAL USBPORTSVC_MapHwPhysicalToVirtual;
PPORTFN_REQUEST_ASYNC_CALLBACK USBPORTSVC_RequestAsyncCallback;
PPORTFN_READWRITE_CONFIG_SPACE USBPORTSVC_ReadWriteConfigSpace;
PPORTFN_WAIT USBPORTSVC_Wait;
PPORTFN_INVALIDATE_CONTROLLER USBPORTSVC_InvalidateController;
PPORTFN_BUGCHECK USBPORTSVC_BugCheck;
PPORTFN_NOTIFY_DOUBLE_BUFFER USBPORTSVC_NotifyDoubleBuffer;
PMPFN_REBALANCE_ENDPOINT MINIPORT_RebalanceEndpoint;
PMPFN_FLUSH_INTERRUPTS MINIPORT_FlushInterrupts;
} USBPORT_REGISTRATION_PACKET_V1, *PUSBPORT_REGISTRATION_PACKET_V1;
/*
Miniport version 2 (current) api packet
*/
typedef struct _USBPORT_REGISTRATION_PACKET {
/* begin version (1) interface definition */
/* Host Controller HCI Type */
USB_HCI_TYPE HciType;
/* registration parameters */
ULONG OptionFlags;
/*
Total bus bandwidth avaibale in MBits
*/
ULONG BusBandwidth;
LONG Reserved;
ULONG DeviceDataSize;
ULONG EndpointDataSize;
ULONG TransferContextSize;
/* 7 char ASCII NULL terminated name */
UCHAR Name[8];
/*
Amount of global common buffer needed
this memory is passed to the miniport on
a start and freed on a stop
*/
ULONG CommonBufferBytes;
/* miniport Functions */
PMPFN_OPEN_ENDPOINT MINIPORT_OpenEndpoint;
PMPFN_POKE_ENDPOINT MINIPORT_PokeEndpoint;
PMPFN_QENDPOINT_REQUIREMENTS MINIPORT_QueryEndpointRequirements;
PMPFN_CLOSE_ENDPOINT MINIPORT_CloseEndpoint;
PMPFN_START_CONTROLLER MINIPORT_StartController;
PMPFN_STOP_CONTROLLER MINIPORT_StopController;
PMPFN_SUSPEND_CONTROLLER MINIPORT_SuspendController;
PMPFN_RESUME_CONTROLLER MINIPORT_ResumeController;
PMPFN_INTERRUPT_SERVICE MINIPORT_InterruptService;
PMPFN_INTERRUPT_DPC MINIPORT_InterruptDpc;
PMPFN_SUBMIT_TRANSFER MINIPORT_SubmitTransfer;
PMPFN_SUBMIT_ISO_TRANSFER MINIPORT_SubmitIsoTransfer;
PMPFN_ABORT_TRANSFER MINIPORT_AbortTransfer;
PMPFN_GET_ENDPOINT_STATE MINIPORT_GetEndpointState;
PMPFN_SET_ENDPOINT_STATE MINIPORT_SetEndpointState;
PMPFN_POLL_ENDPOINT MINIPORT_PollEndpoint;
PMPFN_CHECK_CONTROLLER MINIPORT_CheckController;
PMPFN_GET_32BIT_FRAME_NUMBER MINIPORT_Get32BitFrameNumber;
PMPFN_INTERRUPT_NEXT_SOF MINIPORT_InterruptNextSOF;
PMPFN_ENABLE_INTERRUPTS MINIPORT_EnableInterrupts;
PMPFN_DISABLE_INTERRUPTS MINIPORT_DisableInterrupts;
PMPFN_POLL_CONTROLLER MINIPORT_PollController;
PMPFN_SET_ENDPOINT_DATA_TOGGLE MINIPORT_SetEndpointDataToggle;
PMPFN_GET_ENDPOINT_STATUS MINIPORT_GetEndpointStatus;
PMPFN_SET_ENDPOINT_STATUS MINIPORT_SetEndpointStatus;
PMPFN_RESET_CONTROLLER MINIPORT_ResetController;
/* root hub functions */
PMPFN_RH_GET_ROOTHUB_DATA MINIPORT_RH_GetRootHubData;
PMPFN_RH_GET_STATUS MINIPORT_RH_GetStatus;
PMPFN_RH_GET_PORT_STATUS MINIPORT_RH_GetPortStatus;
PMPFN_RH_GET_HUB_STATUS MINIPORT_RH_GetHubStatus;
/* root hub port functions */
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortReset;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortPower;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortEnable;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_SetFeaturePortSuspend;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortEnable;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortPower;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortSuspend;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortEnableChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortConnectChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortResetChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortSuspendChange;
PMPFN_RH_PORT_FUNCTION MINIPORT_RH_ClearFeaturePortOvercurrentChange;
/* optional root hub functions */
PMPFN_RH_DISABLE_IRQ MINIPORT_RH_DisableIrq;
PMPFN_RH_ENABLE_IRQ MINIPORT_RH_EnableIrq;
/* OPTIONAL DEBUG SERVICES
Miniport should return USBMP_STATUS_NOT_SUPPORTED for the
services not supported.
*/
PMPFN_SEND_ONE_PACKET MINIPORT_StartSendOnePacket;
PMPFN_SEND_ONE_PACKET MINIPORT_EndSendOnePacket;
/* PASS-THRU API function
*/
PMPFN_PASS_THRU MINIPORT_PassThru;
/* interface Services */
PPORTFN_DBGPRINT USBPORTSVC_DbgPrint;
PPORTFN_TEST_DEBUG_BREAK USBPORTSVC_TestDebugBreak;
PPORTFN_ASSERT_FAILURE USBPORTSVC_AssertFailure;
PPORTFN_GET_MINIPORT_REGESTRY_KEY_VALUE USBPORTSVC_GetMiniportRegistryKeyValue;
PPORTFN_INVALIDATE_ROOTHUB USBPORTSVC_InvalidateRootHub;
PPORTFN_INVALIDATE_ENDPOINT USBPORTSVC_InvalidateEndpoint;
PPORTFN_COMPLETE_TRANSFER USBPORTSVC_CompleteTransfer;
PPORTFN_COMPLETE_ISO_TRANSFER USBPORTSVC_CompleteIsoTransfer;
PPORTFN_LOGENTRY USBPORTSVC_LogEntry;
PPORTFN_PHYS_TO_VIRTUAL USBPORTSVC_MapHwPhysicalToVirtual;
PPORTFN_REQUEST_ASYNC_CALLBACK USBPORTSVC_RequestAsyncCallback;
PPORTFN_READWRITE_CONFIG_SPACE USBPORTSVC_ReadWriteConfigSpace;
PPORTFN_WAIT USBPORTSVC_Wait;
PPORTFN_INVALIDATE_CONTROLLER USBPORTSVC_InvalidateController;
PPORTFN_BUGCHECK USBPORTSVC_BugCheck;
PPORTFN_NOTIFY_DOUBLE_BUFFER USBPORTSVC_NotifyDoubleBuffer;
PMPFN_REBALANCE_ENDPOINT MINIPORT_RebalanceEndpoint;
PMPFN_FLUSH_INTERRUPTS MINIPORT_FlushInterrupts;
/* end version (1) definition */
/* begin version (2) definition */
PMPFN_RH_PORT_FUNCTION MINIPORT_Chirp_RH_Port;
PMPFN_TAKE_PORT_CONTROL MINIPORT_TakePortControl;
PVOID pad2;
PVOID pad3;
/* end version (2) definition */
} USBPORT_REGISTRATION_PACKET, *PUSBPORT_REGISTRATION_PACKET;
/**************************************************************
**************************************************************
USBPORT DLL Services
***************************************************************
***************************************************************/
#ifndef USBPORT
DECLSPEC_IMPORT
NTSTATUS
USBPORT_RegisterUSBPortDriver(
PDRIVER_OBJECT DriverObject,
ULONG MiniportHciVersion,
PUSBPORT_REGISTRATION_PACKET RegistrationPacket
);
DECLSPEC_IMPORT
ULONG
USBPORT_GetHciMn(
);
#endif
/* miniport must define these */
#undef PDEVICE_DATA
#undef PTRANSFER_CONTEXT
#undef PENDPOINT_DATA
#endif /* __USB_HCDI_H__ */