Creating the Hardware Control for Sensor#

You must create device drivers for the sensor in the camera module.

To implement a new sensor driver, first create an instance of struct DevBlkCDIDeviceDriver structure like this:

static DevBlkCDIDeviceDriver deviceDriver = {
    .deviceName = "mycamera Image Sensor",
    .regLength = 2,
    .dataLength = 2,
    .DriverCreate = DriverCreate,
    .DriverDestroy = DriverDestroy,
    .SetSensorControls = SetSensorControls,
    .ParseEmbedDataInfo = ParseEmbedDataInfo,
    .SetSensorCharMode = SetSensorCharMode,
    .GetSensorAttributes = GetSensorAttributes,
};

Then, create a function to return a pointer to the structure. The SIPL framework requires this function to get properties and function pointers from the driver. For example:

DevBlkCDIDeviceDriver *GetMycameraDriver(void)
{
    return &deviceDriver;
}

You must create an instance of DevBlkCDIDeviceDriver and initialize these elements of it. Some of them are function pointers, which require creating additional functions:

  • deviceName: A string that identifies your device.

  • regLength: Register address length in bytes for I2C access.

  • dataLength: Register data length in bytes for I2C access.

  • DriverCreate: A pointer to a function that performs tasks necessary to put the device in its default working state. Its signature must be:

static NvMediaStatus
DriverCreate(DevBlkCDIDevice *handle, void *clientContext);

The function performs these tasks, and may perform others:

* If no settings are provided, initializes them to default values.
* Allocates memory for the device context.
* Sets the sensor's default configuration: pixel format, register table, MIPI timing, frame rate, embedded data info, etc.
* Sets the number of active exposures for the default sensor mode.
* Sets the frame report size, if supported.

  • DriverDestroy: A pointer to a function that releases all the resources allocated when the driver was created. Its signature must be:

static NvMediaStatus
DriverDestroy(DevBlkCDIDevice *handle);

  • SetSensorControls: A pointer to a function that updates sensor exposure, gain, and white balance settings for each frame. The function must be defined if the sensor uses the NVIDIA ISP or you intend to test it with Camera IQ tools.

If the function is defined, its signature must be:

static NvMediaStatus
SetSensorControls(
    DevBlkCDIDevice *handle,
    const struct DevBlkCDISensorControl *sensorControl,
    const size_t sensrCtrlStructSize);

Controls for the SetSensorControls Function

Control

Definition

Required by Camera IQ Tools*

numSensorContexts

Number of active sensor contexts.

No

exposureControl

Sets sensor exposure values.

Yes

wbControl

Sets sensor white balance values. If not supported, sets each white balance value to 1.

Yes

frameReportControl

Sensor frame report values to be programmed to sensor, if supported by sensor.

No

*Controls listed as “Yes” must be implemented correctly to produce the best image quality.

If the camera sensor hardware supports group hold, use this feature when updating the exposure, gain, and white balance registers.

If your driver does not implement this function, DevBlkCDISetSensorControls() gets a “Not Supported” error.

  • ParseEmbedDataInfo: A pointer to a function that retrieves all available information from a captured frame. The function must be defined only if the sensor uses the NVIDIA ISP or you intend to test it with Camera IQ tools.

If the function is defined, its signature must be:

static NvMediaStatus
ParseEmbedDataInfo(
    DevBlkCDIDevice *handle,
    const struct DevBlkCDIEmbeddedDataChunk *embeddedTopDataChunk,
    const struct DevBlkCDIEmbeddedDataChunk *embeddedBotDataChunk,
    const size_t dataChunkStructSize,
    struct DevBlkCDIEmbeddedDataInfo *parsedInfo,
    const size_t parsedInfoStructSize);

Exposure Modes Properties Parsed by the ParseEmbedDataInfo Function

Property to be Parsed

Definition

Required by Camera IQ Tools*

numExposures

Number of exposures for the captured frame.

Yes

sensorExpInfo

Sensor exposure information for the captured frame.

Yes

sensorWBInfo

Sensor white balance information for the captured frame. If not supported by the sensor, returns 1 for white balance values.

Yes

sensorPWLInfo

Sensor PWL (Companding Piecewise Linear) information for the captured frame.

Yes †

sensorCRCInfo

Sensor CRC information for the captured frame.

Yes

sensorReportInfo

Frame report information for the captured frame.

No

sensorTempInfo

Sensor temperature information for the captured frame.

No

frameSeqNumInfo

Frame sequence number for the captured frame.

Yes

errorFlag

Holds information on errors present in the embedded data. The meaning of these values is determined by the driver.

No

*Properties listed as “Yes” must be implemented correctly to produce the best image quality.

†If the sensor supports PWL and is running in PWL mode.

You must return the proper value for each property, even if its value can be derived from another property.

If this function is not implemented in your driver, NvMediaISCParseEmbedDataInfo() returns a “Not Supported” error.

  • SetSensorCharMode: A pointer to a function that puts the sensor in characterization mode until the mode is changed. Called by Camera IQ tools. The function must be defined if you intend to test the sensor with Camera IQ tools.

If the function is defined, its signature must be:

static NvMediaStatus
SetSensorCharMode (
    DevBlkCDIDevice *handle,
    uint8_t expNo);

* expNo is the number of exposures to be made in characterization mode.
* The driver must perform the following tasks to enable the image quality tools to control the gain and exposure settings manually.
  * Disable on-chip AE feature (if applied)
  * Disable sensor compression/companding feature (if applied)
  * Disable HDR mode and sensor to SDR mode
  * Set white balance gain to 1.0

The driver also must set the following variables in the device context:

* `charModeEnabled to NVMEDIA_TRUE;`
* `charModeExpNo to expNo`
* `numActiveExposures to 1`

If this function is not implemented in your driver, DevBlkCDISetSensorCharMode() returns a “Not Supported” error.

  • GetSensorAttributes: A pointer to a function that retrieves all sensor attributes. The function must be defined if the sensor uses the NVIDIA ISP or you intend to test it with Camera IQ tools.

If the function is defined, its signature must be:

static NvMediaStatus
GetSensorAttributes(
    DevBlkCDIDevice *handle,
    struct DevBlkCDISensorAttributes *sensorAttr,
    const size_t sensorAttrStructSize)

Attributes Returned by the GetSensorAttributes Function

Attribute

Definition

Required by Camera IQ Tools*

sensorName

A character array holding the sensor name.

Yes

sensorCFA

Sensor color format. Must be one of the color format variants:

NVM_SURF_ATTR_COMPONENT_ORDER_<cfmt>

Where <cfmt> is a color format, one of: RGGB, BGGR, GRBG, GBRG, RCCB, BCCR, CRBC, CBRC, RCCC, CCCR, CRCC, CCRC, or CCCC.

Yes

sensorFuseId

A character array holding the sensor fuse ID. If this field is not supported, the whole array is set to 0x00.

No

numActiveExposures

Number of active exposures. Range is 1 to DEVBLK_CDI_MAX_EXPOSURES.

Yes

sensorExpRange

Array of sensor exposure ranges for active exposures. If exposure change is not allowed, set both minimum and maximum to default values.

Up to DEVBLK_CDI_MAX_EXPOSURES ranges.

Yes

sensorGainRange

Array of sensor gain ranges for active exposures. If gain change is not allowed, set both minimum and maximum gain to default values.

Up to DEVBLK_CDI_MAX_EXPOSURES ranges.

Yes

sensorWhiteBalanceRange

Array of sensor white balance ranges for active exposures.

If white balance does not change, set white balance minimum and maximum to 1.

Up to DEVBLK_CDI_MAX_EXPOSURES ranges.

Yes

sensorGainFactor

Array of additional sensor gain factors between active exposures. Usually, each element is set to 1. If this field is not supported, the array is set to 0.

The array has DEVBLK_CDI_MAX_EXPOSURES elements, allowing the attributes to define that number of factors.

No

numFrameReportBytes

Number of frame report bytes supported by the sensor. If this field is not supported, set to 0.

No

*Attributes listed as “Yes” must be implemented correctly to produce the best image quality.

If this function is not implemented in your driver, DevBlkCDIetSensorAttributes() returns a “Not Supported” error.

There are some optional hardware control functions that you can implement if your camera device driver needs them:

  • For drivers that need to be safety certified, use DevBlkCDII2CPgmrReadUint8(), DevBlkCDII2CPgmrReadUint16(), DevBlkCDII2CPgmrWriteUint8(), and DevBlkCDII2CPgmrWriteUint16()functions to read and write I2C register data. For details for these functions, refer to the SIPL Device Block I2C Programmer section in the Camera Device Interface (CDI) chapter.

  • ReadParameters() and WriteParameters(): Retrieves and configures device parameters.

  • SetDeviceConfig(): Performs certain operations on the device, such as enable/disable a specific mode, enable/disable the test pattern generator (TPG), and disable embedded data.

  • CheckPresence(): Ensures that the driver’s device is presented on the system.

You must create SIPL device block device drivers for the sensor and EEPROM in the camera module. Place the source and header files in the camera device driver directory and run the Makefile to compile them into the camera device driver.

A camera device driver must be entirely self-contained, so if two camera device drivers use the same sensor, each camera device driver must have its own copy of the sensor device driver.

You can use the OV2311 sensor driver as an example for developing your own driver. Its source file is at:

drive-linux/samples/nvmedia/nvsipl/devblk/cameramodule/
MAX96712cameramodule/ov2311/cdi_ov2311.c