windows-nt/Source/XPSP1/NT/drivers/wdm/usb/usbd/usbd.h
2020-09-26 16:20:57 +08:00

658 lines
17 KiB
C

/*++
Copyright (c) 1995 Microsoft Corporation
Module Name:
USBD.H
Abstract:
This module contains the PRIVATE (driver-only) definitions for the
code that implements the usbd driver.
Environment:
Kernel & user mode
Revision History:
09-29-95 : created
--*/
#ifndef USBKDEXTS
#include "dbg.h"
#endif
#define NAME_MAX 64
#define USBD_TAG 0x44425355 /* "USBD" */
#if DBG
#define DEBUG_LOG
#endif
//enable pageable code
#ifndef PAGE_CODE
#define PAGE_CODE
#endif
#define _USBD_
//
// Constents used to format USB setup packets
// for the default pipe
//
//
// Values for the bmRequest field
//
#define USB_HOST_TO_DEVICE 0x00
#define USB_DEVICE_TO_HOST 0x80
#define USB_STANDARD_COMMAND 0x00
#define USB_CLASS_COMMAND 0x20
#define USB_VENDOR_COMMAND 0x40
#define USB_COMMAND_TO_DEVICE 0x00
#define USB_COMMAND_TO_INTERFACE 0x01
#define USB_COMMAND_TO_ENDPOINT 0x02
#define USB_COMMAND_TO_OTHER 0x03
#define USBD_TAG 0x44425355 //"USBD"
/* Registry Keys */
// **
// The following keys are specific to the instance of the
// host controller -- the keys are read from the software
// branch of the registry for the given PDO:
//
/* DWORD keys */
// This key enables a set of global hacks for early or broken USB
// devices -- the default value is OFF
#define SUPPORT_NON_COMP_KEY L"SupportNonComp"
// this key forces the stack in to daignotic mode
#define DAIGNOSTIC_MODE_KEY L"DiagnosticMode"
// enables specif USB device specific hacks to work around
// certain busted devices.
// see #define USBD_DEVHACK_
#define DEVICE_HACK_KEY L"DeviceHackFlags"
//**
// The following keys are global to the USB stack
// ie effect all HC controllers in the system:
//
// they are found in HKLM\System\CCS\Services\USB
// BINARY keys (1 byte)
// turns on hacks for the Toshiba Pseudo Hid device
#define LEGACY_TOSHIBA_USB_KEY L"LegacyToshibaUSB"
// forces 'fast-iso' on all ISO-out endpoints, this key
// is for test purposes only
#define FORCE_FAST_ISO_KEY L"ForceFastIso"
// forces double buffering for all bulk-in endpoints
// this key is for testing purposes only
#define FORCE_DOUBLE_BUFFER_KEY L"ForceDoubleBuffer"
/****/
//
// USB standard command values
// combines bmRequest and bRequest fields
// in the setup packet for standard control
// transfers
//
#define STANDARD_COMMAND_REQUEST_MASK 0xff00
#define STANDARD_COMMAND_GET_DESCRIPTOR ((USB_DEVICE_TO_HOST | \
USB_COMMAND_TO_DEVICE) | \
(USB_REQUEST_GET_DESCRIPTOR<<8))
#define STANDARD_COMMAND_SET_DESCRIPTOR ((USB_HOST_TO_DEVICE | \
USB_COMMAND_TO_DEVICE) | \
(USB_REQUEST_SET_DESCRIPTOR<<8))
#define STANDARD_COMMAND_GET_STATUS_ENDPOINT ((USB_DEVICE_TO_HOST | \
USB_COMMAND_TO_ENDPOINT) | \
(USB_REQUEST_GET_STATUS<<8))
#define STANDARD_COMMAND_GET_STATUS_INTERFACE ((USB_DEVICE_TO_HOST | \
USB_COMMAND_TO_INTERFACE) | \
(USB_REQUEST_GET_STATUS<<8))
#define STANDARD_COMMAND_GET_STATUS_DEVICE ((USB_DEVICE_TO_HOST | \
USB_COMMAND_TO_DEVICE) | \
(USB_REQUEST_GET_STATUS<<8))
#define STANDARD_COMMAND_SET_CONFIGURATION ((USB_HOST_TO_DEVICE | \
USB_COMMAND_TO_DEVICE) | \
(USB_REQUEST_SET_CONFIGURATION<<8))
#define STANDARD_COMMAND_SET_INTERFACE ((USB_HOST_TO_DEVICE | \
USB_COMMAND_TO_INTERFACE) | \
(USB_REQUEST_SET_INTERFACE<<8))
#define STANDARD_COMMAND_SET_ADDRESS ((USB_HOST_TO_DEVICE | \
USB_COMMAND_TO_DEVICE) | \
(USB_REQUEST_SET_ADDRESS<<8))
#define STANDARD_COMMAND_CLEAR_FEATURE_ENDPOINT ((USB_HOST_TO_DEVICE | \
USB_COMMAND_TO_ENDPOINT) | \
(USB_REQUEST_CLEAR_FEATURE<<8))
//
// USB class command macros
//
#define CLASS_COMMAND_GET_DESCRIPTOR ((USB_CLASS_COMMAND | \
USB_DEVICE_TO_HOST | \
USB_COMMAND_TO_DEVICE) | \
(USB_REQUEST_GET_DESCRIPTOR<<8))
#define CLASS_COMMAND_GET_STATUS_OTHER ((USB_CLASS_COMMAND | \
USB_DEVICE_TO_HOST | \
USB_COMMAND_TO_OTHER) | \
(USB_REQUEST_GET_STATUS<<8))
#define CLASS_COMMAND_SET_FEATURE_TO_OTHER ((USB_CLASS_COMMAND | \
USB_HOST_TO_DEVICE | \
USB_COMMAND_TO_OTHER) | \
(USB_REQUEST_SET_FEATURE<<8))
//
// Macros to set transfer direction flag
//
#define USBD_SET_TRANSFER_DIRECTION_IN(tf) ((tf) |= USBD_TRANSFER_DIRECTION_IN)
#define USBD_SET_TRANSFER_DIRECTION_OUT(tf) ((tf) &= ~USBD_TRANSFER_DIRECTION_IN)
//
// Flags for the URB header flags field used
// by USBD
//
#define USBD_REQUEST_IS_TRANSFER 0x00000001
#define USBD_REQUEST_MDL_ALLOCATED 0x00000002
#define USBD_REQUEST_USES_DEFAULT_PIPE 0x00000004
#define USBD_REQUEST_NO_DATA_PHASE 0x00000008
typedef struct _USB_STANDARD_SETUP_PACKET {
USHORT RequestCode;
USHORT wValue;
USHORT wIndex;
USHORT wLength;
} USB_STANDARD_SETUP_PACKET, *PUSB_STANDARD_SETUP_PACKET;
//
// information for each active pipe on a device
//
typedef struct _USBD_PIPE {
ULONG Sig;
USB_ENDPOINT_DESCRIPTOR EndpointDescriptor;
PVOID HcdEndpoint;
ULONG MaxTransferSize;
ULONG ScheduleOffset;
ULONG UsbdPipeFlags;
} USBD_PIPE, *PUSBD_PIPE;
//
// information for each active interface
// for a device
//
typedef struct _USBD_INTERFACE {
ULONG Sig;
BOOLEAN HasAlternateSettings;
UCHAR Pad[3];
USB_INTERFACE_DESCRIPTOR InterfaceDescriptor; // copy of interface descriptor
// copy of interfaceInformation structure, stores user parameters
// for interface in case of failure during alt-interface selection
PUSBD_INTERFACE_INFORMATION InterfaceInformation;
USBD_PIPE PipeHandle[0]; // array of pipe handle structures
} USBD_INTERFACE, *PUSBD_INTERFACE;
//
// informnation for the active configuration
// on a device
//
typedef struct _USBD_CONFIG {
ULONG Sig;
PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor;
PUSBD_INTERFACE InterfaceHandle[1]; // array of pointers to interface
} USBD_CONFIG, *PUSBD_CONFIG;
//
// instance information for a device
//
typedef struct _USBD_DEVICE_DATA {
ULONG Sig;
USHORT DeviceAddress; // address assigned to the device
UCHAR Pad[2];
PUSBD_CONFIG ConfigurationHandle;
// KTIMER TimeoutTimer;
// KDPC TimeoutDpc;
USBD_PIPE DefaultPipe;
USB_DEVICE_DESCRIPTOR DeviceDescriptor; // a copy of the USB device descriptor
USB_CONFIGURATION_DESCRIPTOR ConfigDescriptor;
BOOLEAN LowSpeed; // TRUE if the device is low speed
BOOLEAN AcceptingRequests;
} USBD_DEVICE_DATA, *PUSBD_DEVICE_DATA;
typedef struct _USBD_RH_DELAYED_SET_POWER_D0_WORK_ITEM {
WORK_QUEUE_ITEM WorkQueueItem;
struct _USBD_EXTENSION *DeviceExtension;
PDEVICE_OBJECT DeviceObject;
PIRP Irp;
} USBD_RH_DELAYED_SET_POWER_D0_WORK_ITEM, *PUSBD_RH_DELAYED_SET_POWER_D0_WORK_ITEM;
#define PIPE_CLOSED(ph) ((ph)->HcdEndpoint == NULL)
#define GET_DEVICE_EXTENSION(DeviceObject) (((PUSBD_EXTENSION)(DeviceObject->DeviceExtension))->TrueDeviceExtension)
//#define GET_DEVICE_EXTENSION(DeviceObject) ((PUSBD_EXTENSION)(DeviceObject->DeviceExtension))
#define HCD_DEVICE_OBJECT(DeviceObject) (DeviceObject)
#define DEVICE_FROM_DEVICEHANDLEROBJECT(UsbdDeviceHandle) (PUSBD_DEVICE_DATA) (UsbdDeviceHandle)
#define SET_USBD_ERROR(err) ((err) | USBD_STATUS_ERROR)
#define HC_URB(urb) ((PHCD_URB)(urb))
//
// we use a semaphore to serialize access to the configuration functions
// in USBD
//
#define InitializeUsbDeviceMutex(de) KeInitializeSemaphore(&(de)->UsbDeviceMutex, 1, 1);
#define USBD_WaitForUsbDeviceMutex(de) { USBD_KdPrint(3, ("'***WAIT dev mutex %x\n", &(de)->UsbDeviceMutex)); \
KeWaitForSingleObject(&(de)->UsbDeviceMutex, \
Executive,\
KernelMode, \
FALSE, \
NULL); \
}
#define USBD_ReleaseUsbDeviceMutex(de) { USBD_KdPrint(3, ("'***RELEASE dev mutex %x\n", &(de)->UsbDeviceMutex));\
KeReleaseSemaphore(&(de)->UsbDeviceMutex,\
LOW_REALTIME_PRIORITY,\
1,\
FALSE);\
}
//#if DBG
//VOID
//USBD_IoCompleteRequest(
// IN PIRP Irp,
// IN CCHAR PriorityBoost
// );
//#else
#define USBD_IoCompleteRequest(a, b) IoCompleteRequest(a, b)
//#endif
//
//Function Prototypes
//
#if DBG
VOID
USBD_Warning(
PUSBD_DEVICE_DATA DeviceData,
PUCHAR Message,
BOOLEAN DebugBreak
);
#else
#define USBD_Warning(x, y, z)
#endif
NTSTATUS
USBD_Internal_Device_Control(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PUSBD_EXTENSION DeviceExtension,
IN PBOOLEAN IrpIsPending
);
NTSTATUS
USBD_SendCommand(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN USHORT RequestCode,
IN USHORT WValue,
IN USHORT WIndex,
IN USHORT WLength,
IN PVOID Buffer,
IN ULONG BufferLength,
OUT PULONG BytesReturned,
OUT USBD_STATUS *UsbStatus
);
NTSTATUS
USBD_CreateDevice(
IN OUT PUSBD_DEVICE_DATA *DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN BOOLEAN DeviceIsLowSpeed,
IN ULONG MaxPacketSize_Endpoint0,
IN OUT PULONG NonCompliantDevice
);
NTSTATUS
USBD_InitializeDevice(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN OUT PUSB_DEVICE_DESCRIPTOR DeviceDescriptor,
IN ULONG DeviceDescriptorLength,
IN OUT PUSB_CONFIGURATION_DESCRIPTOR ConfigDescriptor,
IN ULONG ConfigDescriptorLength
);
NTSTATUS
USBD_ProcessURB(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PURB Urb,
OUT PBOOLEAN IrpIsPending
);
NTSTATUS
USBD_MapError_UrbToNT(
IN PURB Urb,
IN NTSTATUS NtStatus
);
NTSTATUS
USBD_Irp_Complete(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PVOID Context
);
USHORT
USBD_AllocateUsbAddress(
IN PDEVICE_OBJECT DeviceObject
);
NTSTATUS
USBD_OpenEndpoint(
IN PUSBD_DEVICE_DATA Device,
IN PDEVICE_OBJECT DeviceObject,
IN PUSBD_PIPE PipeHandle,
OUT USBD_STATUS *UsbStatus,
BOOLEAN IsDefaultPipe
);
NTSTATUS
USBD_GetDescriptor(
IN PUSBD_DEVICE_DATA Device,
IN PDEVICE_OBJECT DeviceObject,
OUT PUCHAR DescriptorBuffer,
IN USHORT DescriptorBufferLength,
IN USHORT DescriptorTypeAndIndex
);
NTSTATUS
USBD_CloseEndpoint(
IN PUSBD_DEVICE_DATA Device,
IN PDEVICE_OBJECT DeviceObject,
IN PUSBD_PIPE PipeHandle,
OUT USBD_STATUS *UsbStatus
);
NTSTATUS
USBD_PnP(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
);
VOID
USBD_LogInit(
);
NTSTATUS
USBD_SubmitSynchronousURB(
IN PURB Urb,
IN PDEVICE_OBJECT DeviceObject,
IN PUSBD_DEVICE_DATA DeviceData
);
NTSTATUS
USBD_EnumerateBUS(
IN PDEVICE_OBJECT DeviceObject,
IN PUCHAR DeviceEnumBuffer,
IN ULONG DeviceEnumBufferLength
);
NTSTATUS
USBD_InternalCloseConfiguration(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN OUT USBD_STATUS *UsbdStatus,
IN BOOLEAN AbortTransfers,
IN BOOLEAN KeepConfig
);
PUSB_INTERFACE_DESCRIPTOR
USBD_InternalParseConfigurationDescriptor(
IN PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
IN UCHAR InterfaceNumber,
IN UCHAR AlternateSetting,
PBOOLEAN HasAlternateSettings
);
NTSTATUS
USBD_GetPdoRegistryParameters (
IN PDEVICE_OBJECT PhysicalDeviceObject,
IN OUT PULONG ComplienceFlags,
IN OUT PULONG DiagnosticFlags,
IN OUT PULONG DeviceHackFlags
);
NTSTATUS
USBD_GetGlobalRegistryParameters (
IN PDEVICE_OBJECT PhysicalDeviceObject,
IN OUT PULONG ComplienceFlags,
IN OUT PULONG DiagnosticFlags,
IN OUT PULONG DeviceHackFlags
);
NTSTATUS
USBD_GetEndpointState(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN PUSBD_PIPE PipeHandle,
OUT USBD_STATUS *UsbStatus,
OUT PULONG EndpointState
);
VOID
USBD_SyncUrbTimeoutDPC(
IN PKDPC Dpc,
IN PVOID DeferredContext,
IN PVOID SystemArgument1,
IN PVOID SystemArgument2
);
VOID
USBD_FreeUsbAddress(
IN PDEVICE_OBJECT DeviceObject,
IN USHORT DeviceAddress
);
ULONG
USBD_InternalGetInterfaceLength(
IN PUSB_INTERFACE_DESCRIPTOR InterfaceDescriptor,
IN PUCHAR End
);
NTSTATUS
USBD_InitializeConfigurationHandle(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
IN ULONG NumberOfInterfaces,
IN OUT PUSBD_CONFIG *ConfigHandle
);
BOOLEAN
USBD_InternalInterfaceBusy(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN PUSBD_INTERFACE InterfaceHandle
);
NTSTATUS
USBD_InternalOpenInterface(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN PUSBD_CONFIG ConfigHandle,
IN OUT PUSBD_INTERFACE_INFORMATION InterfaceInformation,
IN OUT PUSBD_INTERFACE *InterfaceHandle,
IN BOOLEAN SendSetInterfaceCommand,
IN PBOOLEAN NoBandwidth
);
NTSTATUS
USBD_SelectConfiguration(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PURB Urb,
OUT PBOOLEAN IrpIsPending
);
NTSTATUS
USBD_SelectInterface(
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp,
IN PURB Urb,
OUT PBOOLEAN IrpIsPending
);
NTSTATUS
USBD_GetRegistryKeyValue(
IN HANDLE Handle,
IN PWCHAR KeyNameString,
IN ULONG KeyNameStringLength,
IN PVOID Data,
IN ULONG DataLength
);
NTSTATUS
USBD_InternalMakePdoName(
IN OUT PUNICODE_STRING PdoNameUnicodeString,
IN ULONG Index
);
NTSTATUS
USBD_SymbolicLink(
BOOLEAN CreateFlag,
PUSBD_EXTENSION DeviceExtension
);
NTSTATUS
USBD_PdoDispatch(
PDEVICE_OBJECT DeviceObject,
PIRP Irp,
PUSBD_EXTENSION DeviceExtension,
PBOOLEAN IrpNeedsCompletion
);
NTSTATUS
USBD_FdoDispatch(
PDEVICE_OBJECT DeviceObject,
PIRP Irp,
PUSBD_EXTENSION DeviceExtension,
PBOOLEAN IrpNeedsCompletion
);
NTSTATUS
USBD_DeferPoRequestCompletion(
IN PDEVICE_OBJECT DeviceObject,
IN UCHAR MinorFunction,
IN POWER_STATE DeviceState,
IN PVOID Context,
IN PIO_STATUS_BLOCK IoStatus
);
NTSTATUS
USBD_InternalRestoreConfiguration(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN PUSBD_CONFIG ConfigHandle
);
NTSTATUS
USBD_InternalCloseDefaultPipe(
IN PUSBD_DEVICE_DATA DeviceData,
IN PDEVICE_OBJECT DeviceObject,
IN OUT USBD_STATUS *UsbdStatus,
IN BOOLEAN AbortTransfers
);
NTSTATUS
USBD_GetHubName(
PUSBD_EXTENSION DeviceExtension,
PIRP Irp
);
NTSTATUS
USBD_SetRegistryKeyValue (
IN HANDLE Handle,
IN PUNICODE_STRING KeyNameUnicodeString,
IN PVOID Data,
IN ULONG DataLength,
IN ULONG KeyType
);
NTSTATUS
USBD_SetPdoRegistryParameter (
IN PDEVICE_OBJECT PhysicalDeviceObject,
IN PWCHAR KeyName,
IN ULONG KeyNameLength,
IN PVOID Data,
IN ULONG DataLength,
IN ULONG KeyType,
IN ULONG DevInstKeyType
);
NTSTATUS
USBD_SubmitWaitWakeIrpToHC(
IN PUSBD_EXTENSION DeviceExtension
);
BOOLEAN
USBD_ValidatePipe(
PUSBD_PIPE PipeHandle
);
VOID
USBD_CompleteIdleNotification(
IN PUSBD_EXTENSION DeviceExtension
);
NTSTATUS
USBD_FdoSetContentId(
IN PIRP irp,
IN PVOID pKsProperty,
IN PVOID pvData
);