/*++ Copyright (c) 1997 Microsoft Corporation Module Name: USBCAMDI.H Abstract: interface definition for . Environment: Kernel & user mode Revision History: --*/ #ifndef __USBCAMDI_H__ #define __USBCAMDI_H__ // the purpose of this structure is to establish a connection between pipes discovered and // streams to be declared (video,still). the following structure will be be passed along with // USBD_PIPE_INFO structure in CamConfigEx to the cam driver. The Cam driver has to indicate // pipe stream asscociation by oring all the relevant streams associated with this particular // pipe. If there is more than one stream association, USBCAMD creates a virtual still pin, // and assumes the first stream is video followed by still stream. // The cam driver has to set the first field to USBCAMD_DONT_CARE_PIPE if a particular pipe should not be used by // usbcamd. For example, if you have an iso audio pipe, iso video pipe in a camera device that // supports stills and video .you should set the flag field in the first structure to // USBCAMD_DONT_CARE_PIPE, The second structure should be set as foolows: // {USBCAMD_VIDEO_STILL_STREAM,USBCAMD_MULTIPLEX_PIPE)}. // the assumption here is that cam has one config descr, and all alt.interfcaes have the same // number and types of pipes. // also, notice that the flags are mutually exclusive. // typedef struct _pipe_config_descriptor { CHAR StreamAssociation ; // video stream, still stream, or both UCHAR PipeConfigFlags; // USBCAMD_PIPECONFIG_* } USBCAMD_Pipe_Config_Descriptor, *PUSBCAMD_Pipe_Config_Descriptor; #define USBCAMD_DATA_PIPE 0x0001 // video or still data pipe #define USBCAMD_MULTIPLEX_PIPE 0x0002 // pipe used for both still & video #define USBCAMD_SYNC_PIPE 0x0004 // out-of-band signalling pipe. #define USBCAMD_DONT_CARE_PIPE 0x0008 // pipe is not to be used for streaming vidoe or still. #define USBCAMD_VIDEO_STREAM 0x1 #define USBCAMD_STILL_STREAM 0x2 #define USBCAMD_VIDEO_STILL_STREAM (USBCAMD_VIDEO_STREAM | USBCAMD_STILL_STREAM) // PacketFlag definitions for CamProcessUSBPacketEx // *** Notice *** : these flags are mutually exclusive. // current frame is unsalvageable, recycle the read IRP #define USBCAMD_PROCESSPACKETEX_DropFrame 0x0002 // following frame is still. #define USBCAMD_PROCESSPACKETEX_NextFrameIsStill 0x0004 // copy this frame to still pin. . #define USBCAMD_PROCESSPACKETEX_CurrentFrameIsStill 0x0008 // these flags are used in PipeStateFlag in usbcamd_setpipestate function. #define USBCAMD_STOP_STREAM 0x00000001 #define USBCAMD_START_STREAM 0x00000000 // // the following flags are passed to usbcamd in USBCAMD_InitializeNewInterface. // If Cam driver doesn't need to operate on the still image raw frame, then it should // set the second flag in order to elminate on ebuffer copy. Likewise for the video frame. // the associatedformat flag is set if the cam driver use the same format fro video and // virtual still pin. Once, this flag is set, USBCAMD will not allow virtual still pin to be // opened at different format than the video pin. USE this flag only when the virtual still // pin produces frames that have exact format as video frames. // EnableDeviceEvents will expose a deviceevents to stream class & DSHOW which will enable an STI // Monitor to lunch a still image app if still button is pressed on the camera. typedef enum { USBCAMD_CamControlFlag_NoVideoRawProcessing = 0x0001, USBCAMD_CamControlFlag_NoStillRawProcessing = 0x0002, USBCAMD_CamControlFlag_AssociatedFormat = 0x0004, USBCAMD_CamControlFlag_EnableDeviceEvents = 0x0008, } USBCAMD_CamControlFlags; // ------------------------------------------------------------------------ // The master list of all streams supported by this driver // ------------------------------------------------------------------------ typedef NTSTATUS (*PCOMMAND_COMPLETE_FUNCTION)( PVOID DeviceContext, PVOID CommandContext, NTSTATUS NtStatus ); typedef VOID (*PSTREAM_RECEIVE_PACKET) ( IN PVOID Srb, IN PVOID DeviceContext, IN PBOOLEAN Completed ); typedef NTSTATUS (*PCAM_INITIALIZE_ROUTINE)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext ); typedef NTSTATUS (*PCAM_CONFIGURE_ROUTINE)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PUSBD_INTERFACE_INFORMATION Interface, PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor, PLONG DataPipeIndex, PLONG SyncPipeIndex ); typedef NTSTATUS (*PCAM_CONFIGURE_ROUTINE_EX)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PUSBD_INTERFACE_INFORMATION Interface, PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor, ULONG PipeConfigListSize, PUSBCAMD_Pipe_Config_Descriptor PipeConfig, PUSB_DEVICE_DESCRIPTOR DeviceDescriptor ); typedef NTSTATUS (*PCAM_START_CAPTURE_ROUTINE)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext ); typedef NTSTATUS (*PCAM_START_CAPTURE_ROUTINE_EX)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, ULONG StreamNumber ); typedef NTSTATUS (*PCAM_ALLOCATE_BW_ROUTINE)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PULONG RawFrameLength, PVOID Format ); typedef NTSTATUS (*PCAM_ALLOCATE_BW_ROUTINE_EX)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PULONG RawFrameLength, PVOID Format, ULONG StreamNumber ); typedef NTSTATUS (*PCAM_FREE_BW_ROUTINE)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext ); typedef NTSTATUS (*PCAM_FREE_BW_ROUTINE_EX)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, ULONG STreamNumber ); typedef VOID (*PADAPTER_RECEIVE_PACKET_ROUTINE)( IN PHW_STREAM_REQUEST_BLOCK Srb ); typedef NTSTATUS (*PCAM_STOP_CAPTURE_ROUTINE)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext ); typedef NTSTATUS (*PCAM_STOP_CAPTURE_ROUTINE_EX)( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, ULONG StreamNumber ); typedef ULONG (*PCAM_PROCESS_PACKET_ROUTINE) ( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PVOID CurrentFrameContext, PUSBD_ISO_PACKET_DESCRIPTOR SyncPacket, PVOID SyncBuffer, PUSBD_ISO_PACKET_DESCRIPTOR DataPacket, PVOID DataBuffer, PBOOLEAN FrameComplete, PBOOLEAN NextFrameIsStill ); typedef ULONG (*PCAM_PROCESS_PACKET_ROUTINE_EX) ( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PVOID CurrentFrameContext, PUSBD_ISO_PACKET_DESCRIPTOR SyncPacket, PVOID SyncBuffer, PUSBD_ISO_PACKET_DESCRIPTOR DataPacket, PVOID DataBuffer, PBOOLEAN FrameComplete, PULONG PacketFlag, PULONG ValidDataOffset ); typedef VOID (*PCAM_NEW_FRAME_ROUTINE) ( PVOID DeviceContext, PVOID FrameContext ); typedef VOID (*PCAM_NEW_FRAME_ROUTINE_EX) ( PVOID DeviceContext, PVOID FrameContext, ULONG StreamNumber, PULONG FrameLength ); typedef NTSTATUS (*PCAM_PROCESS_RAW_FRAME_ROUTINE) ( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PVOID FrameContext, PVOID FrameBuffer, ULONG FrameLength, PVOID RawFrameBuffer, ULONG RawFrameLength, ULONG NumberOfPackets, PULONG BytesReturned ); typedef NTSTATUS (*PCAM_PROCESS_RAW_FRAME_ROUTINE_EX) ( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext, PVOID FrameContext, PVOID FrameBuffer, ULONG FrameLength, PVOID RawFrameBuffer, ULONG RawFrameLength, ULONG NumberOfPackets, PULONG BytesReturned, ULONG ActualRawFrameLength, ULONG StreamNumber ); typedef NTSTATUS (*PCAM_STATE_ROUTINE) ( PDEVICE_OBJECT BusDeviceObject, PVOID DeviceContext ); #ifdef DEBUG_LOG VOID USBCAMD_Debug_LogEntry( IN CHAR *Name, IN ULONG Info1, IN ULONG Info2, IN ULONG Info3 ); #define ILOGENTRY(sig, info1, info2, info3) \ USBCAMD_Debug_LogEntry(sig, (ULONG)info1, (ULONG)info2, (ULONG)info3) #else #define ILOGENTRY(sig, info1, info2, info3) #endif /* DEBUG_LOG */ typedef struct _USBCAMD_DEVICE_DATA { ULONG Sig; PCAM_INITIALIZE_ROUTINE CamInitialize; PCAM_INITIALIZE_ROUTINE CamUnInitialize; PCAM_PROCESS_PACKET_ROUTINE CamProcessUSBPacket; PCAM_NEW_FRAME_ROUTINE CamNewVideoFrame; PCAM_PROCESS_RAW_FRAME_ROUTINE CamProcessRawVideoFrame; PCAM_START_CAPTURE_ROUTINE CamStartCapture; PCAM_STOP_CAPTURE_ROUTINE CamStopCapture; PCAM_CONFIGURE_ROUTINE CamConfigure; PCAM_STATE_ROUTINE CamSaveState; PCAM_STATE_ROUTINE CamRestoreState; PCAM_ALLOCATE_BW_ROUTINE CamAllocateBandwidth; PCAM_FREE_BW_ROUTINE CamFreeBandwidth; } USBCAMD_DEVICE_DATA, *PUSBCAMD_DEVICE_DATA; typedef struct _USBCAMD_DEVICE_DATA2 { ULONG Sig; PCAM_INITIALIZE_ROUTINE CamInitialize; PCAM_INITIALIZE_ROUTINE CamUnInitialize; PCAM_PROCESS_PACKET_ROUTINE_EX CamProcessUSBPacketEx; PCAM_NEW_FRAME_ROUTINE_EX CamNewVideoFrameEx; PCAM_PROCESS_RAW_FRAME_ROUTINE_EX CamProcessRawVideoFrameEx; PCAM_START_CAPTURE_ROUTINE_EX CamStartCaptureEx; PCAM_STOP_CAPTURE_ROUTINE_EX CamStopCaptureEx; PCAM_CONFIGURE_ROUTINE_EX CamConfigureEx; PCAM_STATE_ROUTINE CamSaveState; PCAM_STATE_ROUTINE CamRestoreState; PCAM_ALLOCATE_BW_ROUTINE_EX CamAllocateBandwidthEx; PCAM_FREE_BW_ROUTINE_EX CamFreeBandwidthEx; } USBCAMD_DEVICE_DATA2, *PUSBCAMD_DEVICE_DATA2; // // USBCAMD services // /* This function is called from the "cam" driver DriverEntry routine to register the driver with USBCAMD. This effectively binds the two drivers together. Context1, Context2 - these are passed to the "cam" drivers DriverEntry and should simply be passed on DeviceContextSize - amount of memory needed for the "cam" driver's device specific context. FrameContextSize - size of an optional per video frame structure passed to NewVideoFrame and ProcessRawVideoFrame. */ ULONG USBCAMD_DriverEntry( PVOID Context1, PVOID Context2, ULONG DeviceContextSize, ULONG FrameContextSize, PADAPTER_RECEIVE_PACKET_ROUTINE ReceivePacket ); /* This function is called by the "cam" driver from the AdapterReceivePacket routine to allow USBCAMD to process an SRB. Srb - The srb passed to the "cam" driver's AdapterReceievPacket Routine. DeviceData - filled in USBCAMD_DEVICE_DATAx structure with entry points to the "cam" driver for iso stream processing. DeviceObject - this pointer will be filled in the device PDO, this is used by the "cam" driver for calls to the USB stack through IoCallDriver. NeedsCompletion - if this flag is true USBCAMD will process the SRB and complete it, otherwise USBCAMD will ignore the SRB and just return the DeveiceConext. Returns: Returns a pointer to the device specific context for this instance of the camera "DeviceContext". */ PVOID USBCAMD_AdapterReceivePacket( IN PHW_STREAM_REQUEST_BLOCK Srb, IN PUSBCAMD_DEVICE_DATA DeviceData, IN PDEVICE_OBJECT *DeviceObject, IN BOOLEAN NeedsCompletion ); /* This function is available to the "cam" driver to send vendor commands on the control pipe. This function may be called at IRQL >= PASSIVE_LEVEL. If the function is called at IRQL > PASSIVE_LEVEL the command will be deferred until passive level, once completed the callers CommandComplete function is called with a pointer to the CommandContext. DeviceContext - device specific context. Request - value for the bRequest field for the vendor command. Value - value for the wValue field of the vendor command. Index - value for the wIndex field of the vendor conmmand. Buffer - data buffer if the command has data, may be NULL. BufferLength - pointer length of Buffer in bytes, may be NULL if buffer is NULL GetData - flag indicating data direction, "GetData" indicates data is send device-to-host. CommandComplete - function called when command is completed. CommandContext - context passed to CommandComplete function Returns: Returns NTSTATUS code from command of STTAUS_PENDING if command is deferred. */ NTSTATUS USBCAMD_ControlVendorCommand( IN PVOID DeviceContext, IN UCHAR Request, IN USHORT Value, IN USHORT Index, IN PVOID Buffer, IN OUT PULONG BufferLength, IN BOOLEAN GetData, IN PCOMMAND_COMPLETE_FUNCTION CommandComplete, IN PVOID CommandContext ); /* This function is called by the "cam" driver to select an alternate interface, The RequestInterface structure is filled in with the information from the SELECT_INTERFACE request on successful completion. This function is typically called from the "cam" driver in response to a request to allocate or free bandwidth. DeviceContext - device specific context. RequestInterface - USBD_INTERFACE_INFORMATION structure for the appropriate interface to select. The same rules apply to this structure as for the SELECT_INTERFACE USBD request (see USBDI doc). Returns: Returns the status from the SELECT_INTERFACE request to USBD. */ NTSTATUS USBCAMD_SelectAlternateInterface( IN PVOID DeviceContext, IN OUT PUSBD_INTERFACE_INFORMATION RequestInterface ); /* Handy function to get a device instance specific registry key value */ NTSTATUS USBCAMD_GetRegistryKeyValue ( IN HANDLE Handle, IN PWCHAR KeyNameString, IN ULONG KeyNameStringLength, IN PVOID Data, IN ULONG DataLength ); // // These services are new. // /* This function is called from the "cam" driver upon recieving SRB_INITIALIZE_DEVICE to provid usbcamd with all the necessary info to configure the cam driver correctly with stream class and USB Bus drivers. DeviceContext - device specific context. DeviceData - filled in USBCAMD_DEVICE_DATAx structure with entry points to the "cam" driver . Version - USBCAMD version CamControlFlag - flags to control interaction with cam driver. */ ULONG USBCAMD_InitializeNewInterface( IN PVOID DeviceContext, IN PVOID DeviceData, IN ULONG Version, IN ULONG CamControlFlag ); // To access the new USBCAMD functionality in a CAM driver , the driver sends // the following IRP to itself once it received SRB_INITIALIZATION_COMPLETE. // MajorFunction = IRP_MJ_PNP; // MinorFunction = IRP_MN_QUERY_INTERFACE; // {2BCB75C0-B27F-11d1-BA41-00A0C90D2B05} DEFINE_GUID( GUID_USBCAMD_INTERFACE , 0x2bcb75c0, 0xb27f, 0x11d1, 0xba, 0x41, 0x0, 0xa0, 0xc9, 0xd, 0x2b, 0x5); //The QUERY_INTERFACE Irp will return an interface (set of function pointers) // of the type xxxxINTERFACE, defined below. This is essentially a table of // function pointers. typedef NTSTATUS (*PFNUSBCAMD_SetVideoFormat)( IN PVOID DeviceContext, IN IN PHW_STREAM_REQUEST_BLOCK pSrb ); typedef NTSTATUS (*PFNUSBCAMD_WaitOnDeviceEvent)( IN PVOID DeviceContext, IN ULONG PipeIndex, IN PVOID Buffer, IN ULONG BufferLength, IN PCOMMAND_COMPLETE_FUNCTION EventComplete, IN PVOID EventContext, IN BOOLEAN LoopBack ); // this function is callable at PASSIVE_LEVEL Only. typedef NTSTATUS (*PFNUSBCAMD_CancelBulkReadWrite)( IN PVOID DeviceContext, IN ULONG PipeIndex ); typedef NTSTATUS (*PFNUSBCAMD_SetIsoPipeState)( IN PVOID DeviceContext, IN ULONG PipeStateFlags ); typedef NTSTATUS (*PFNUSBCAMD_BulkReadWrite)( IN PVOID DeviceContext, IN USHORT PipeIndex, IN PVOID Buffer, IN ULONG BufferLength, IN PCOMMAND_COMPLETE_FUNCTION CommandComplete, IN PVOID CommandContext ); #define USBCAMD_VERSION_200 0x200 typedef struct { INTERFACE Interface; PFNUSBCAMD_WaitOnDeviceEvent USBCAMD_WaitOnDeviceEvent; PFNUSBCAMD_BulkReadWrite USBCAMD_BulkReadWrite; PFNUSBCAMD_SetVideoFormat USBCAMD_SetVideoFormat; PFNUSBCAMD_SetIsoPipeState USBCAMD_SetIsoPipeState; PFNUSBCAMD_CancelBulkReadWrite USBCAMD_CancelBulkReadWrite; } USBCAMD_INTERFACE, *PUSBCAMD_INTERFACE; #endif /* __USBCAMDI_H__ */