USBCAMD2 Minidriver Operation

2021-12-15

A USBCAMD2 camera minidriver generally operates as follows:

The camera minidriver calls USBCAMD_DriverEntry from its DriverEntry routine. When the minidriver calls USBCAMD_DriverEntry, it passes to USBCAMD2 the minidriver's AdapterReceivePacket callback function. USBCAMD2 then registers the minidriver with the stream.sys class driver.
The camera minidriver can then receive various stream request blocks (SRBs) in its AdapterReceivePacket callback function to handle, including:
The camera minidriver determines how it must process each SRB. The minidriver can call routines in the USBCAMD2 minidriver library to assist with processing SRBs. These routines typically begin with the USBCAMD_ prefix.

For example, to specify the camera minidriver's other callback functions with USBCAMD2, the camera minidriver specifies their entry points in a USBCAMD_DEVICE_DATA2 structure. The minidriver then calls USBCAMD_InitializeNewInterface to pass the initialized USBCAMD_DEVICE_DATA2 structure to USBCAMD2. USBCAMD2 then calls the minidriver's callback functions when necessary.

Note

The USBCAMD_DEVICE_DATA structure is supported in USBCAMD2 only for purposes of backward compatibility.

The minidriver must call USBCAMD_AdapterReceivePacket to send any SRBs it does not handle to USBCAMD2 to process.

USBCAMD Library Callback Functions describe the callback functions that the minidriver implements and whether they are optional or required.

The following list of procedures illustrates the general flow of processing for SRBs sent to the camera minidriver:

Minidriver's SRB_INITIALIZE_DEVICE handler

Component	Action
Camera minidriver	Initialize USBCAMD2 by calling USBCAMD_InitializeNewInterface, indicating video or still raw processing requirements in kernel mode, such as enabling device events.
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	Acquire USB device and configuration descriptors.
USBCAMD2	Call the minidriver's CamConfigureEx callback function.
Camera minidriver	Complete the configuration. Choose an alternate setting and maximum transfer size. Fill in the array of USBCAMD_Pipe_Config_Descriptor structures.
USBCAMD2	Parse the array of USBCAMD_Pipe_Config_Descriptor structures.
USBCAMD2	Call the minidriver's CamInitialize callback function.
Camera minidriver	Complete the initialization. Set the device power and activate the default setting on the camera.
USBCAMD2	Provide the number of streams and stream descriptor size to the stream.sys class driver.

Minidriver's SRB_GET_STREAM_INFO handler

Component	Action
Camera minidriver	Provide the HW_STREAM_INFORMATION stream information structure to the stream.sys class driver.
Camera minidriver	Fill in the pointer to the array of device property sets in stream.sys class driver's HW_STREAM_HEADER structure.
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	Fill in the number of pins in the stream header.
USBCAMD2	Expose the device event table, if any.
USBCAMD2	Fix entry values in the stream information table. Set category name (capture or still).
USBCAMD2	Fill in the pointer to the stream property array.

Minidriver's SRB_INITIALIZATION_COMPLETE handler

Component	Action
Camera minidriver	Acquire GUID_USBCAMD_INTERFACE for USBCAMD2 using IRP_MJ_PNP and IRP_MN_QUERY_INTERFACE.

Minidriver's SRB_GET_DEVICE_PROPERTY handler

Component	Action
Camera minidriver	Get the properties that the camera minidriver handles, such as PROPSETID_VIDCAP_VIDEOPROCAMP, PROPSETID_VIDCAP_CAMERACONTROL, and PROPSETID_VIDCAP_VIDEOCONTROL, as well as any other custom property sets.

Minidriver's SRB_SET_DEVICE_PROPERTY handler

Component	Action
Camera minidriver	Set the properties the camera minidriver handles by acquiring the parameters of PROPSETID_VIDCAP_VIDEOPROCAMP, PROPSETID_VIDCAP_CAMERACONTROL, and PROPSETID_VIDCAP_VIDEOCONTROL, and any other custom property sets.

Minidriver's SRB_GET_DATA_INTERSECTION handler

Component	Action
Camera minidriver	Return a KSDATAFORMAT structure from a KSDATARANGE structure.
Camera minidriver	Check that the frame rate requested (VideoInfoHeader.AvgTimePerFrame) is within the upper and lower limits for the video format requested. If it exceeds the limits, the minidriver should correct the following values in pSrb->CommandData.IntersectInfo->Datarange: VideoInfoHeader.AvgTimePerFrame, VideoInfoHeader.dwBitRate.

Minidriver's SRB_OPEN_STREAM handler

Component	Action
Camera minidriver	Verify the video format.
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	Save the video format accepted by the camera minidriver.
USBCAMD2	Call the minidriver's CamAllocateBandwidthEx callback function to allocate bandwidth based on video-format data and get the maximum buffer size for the video format.
Camera minidriver	Calculate the isochronous channel's maximum packet size that satisfies the requested frame rate and output windows size.
Camera minidriver	Choose the closest alternate setting by calling USBCAMD_SelectAlternateInterface. The minidriver should provide USBCAMD2 with the maximum possible frame size that can be produced by the camera.
Camera minidriver	Set the hardware scaling on the camera. Set the camera controls to the stored values in the registry, or to the default setting if the first time.
Camera minidriver	Ensure that the frame rate (VideoInfoHeader.AvgTimePerFrame) falls within the limits for the video format, and correct it if it does not.
USBCAMD2	Call the minidriver's CamStartCaptureEx callback function.
Camera minidriver	Set the hardware to capture mode.
USBCAMD2	Initialize isochronous or bulk transfer.

Minidriver's SRB_CLOSE_STREAM handler

Component	Action
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	Cancel pending IRPs submitted to USBCAMD2. Return any pending data SRBs to the stream.sys class driver.
USBCAMD2	Call the minidriver's CamStopCaptureEx callback function.
Camera minidriver	Send a stop-capture command to the camera.
USBCAMD2	Call the minidriver's CamFreeBandwidthEx callback function to free isochronous bus bandwidth, if applicable.
Camera minidriver	Select an idle alternate setting.
USBCAMD2	Free resources associated with USB pipes.

Minidriver's SRB_UNINITIALIZE_DEVICE handler

Component	Action
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	If any streams are still open, close them by calling the minidriver's CamStopCaptureEx and CamFreeBandwidthEx callback functions for each stream.
USBCAMD2	Call the minidriver's CamUnInitialize callback function.
Camera minidriver	Clean up and free resources.

Minidriver's SRB_SURPRISE_REMOVAL handler

Component	Action
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	Cancel pending data SRBs and return the SRBs with STATUS_CANCELLED.
USBCAMD2	Call the minidriver's CamStopCaptureEx and CamFreeBandwidthEx callback functions on all opened streams.
USBCAMD2	Return STATUS_CANCELLED on any read/write SRBs that come down after SRB_SURPRISE_REMOVAL.

Minidriver's SRB_SET_DATA_FORMAT handler

Component	Action
Camera minidriver	Verify the new video format.
Camera minidriver	Call USBCAMD_SetVideoFormat.
USBCAMD2	Save the new format with the associated stream extension.

Minidriver's SRB_CHANGE_POWER_STATE from Power ON to Power OFF handler

Component	Action
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	Stop streaming on isochronous pipe if applicable, or cancel pending bulk or interrupt transfers.
USBCAMD2	Call the minidriver's CamStopCaptureEx callback function.
Camera minidriver	Send stop capture command to hardware.

Minidriver's SRB_CHANGE_POWER_STATE from Power OFF to Power ON handler

Component	Action
Camera minidriver	Call USBCAMD_AdapterReceivePacket.
USBCAMD2	Restart streaming on isochronous pipe if applicable, or resubmit bulk or interrupt transfer to USB class.
Camera minidriver	Restore camera settings and camera power consumption to normal levels.
USBCAMD2	Call the minidriver's CamStopCaptureEx callback function.
USBCAMD2	Call the minidriver's CamStartCaptureEx callback function.

Share via