nvmedia_isc.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2018, NVIDIA CORPORATION.  All rights reserved.  All
 * information contained herein is proprietary and confidential to NVIDIA
 * Corporation.  Any use, reproduction, or disclosure without the written
 * permission of NVIDIA Corporation is prohibited.
 */

#ifndef _NVMEDIA_ISC_H
#define _NVMEDIA_ISC_H

#ifdef __cplusplus
extern "C" {
#endif

#include "nvmedia_core.h"
#include "nvmedia_icp.h"

#define NVMEDIA_ISC_VERSION_MAJOR   2

#define NVMEDIA_ISC_VERSION_MINOR   4

#define NVMEDIA_ISC_SIMULATOR_ADDRESS   0xFF1

#define RDEV_CFG_I2C_BITS           8

#define RDEV_CFG_CSI_BITS           (RDEV_CFG_I2C_BITS + 8)

#define RDEV_CFG_SLV_BIT            (RDEV_CFG_CSI_BITS + 1)

#define ISC_RDEV_CFG(csi, i2c)   (((uint32_t)(csi) << RDEV_CFG_I2C_BITS) | (i2c))

#define ISC_RDEV_CFG_EX(csi, i2c, disPwrCtrl) \
         ((i2c & 0xffu) | \
          ((uint32_t)(csi & 0xffu) << RDEV_CFG_I2C_BITS) | \
          ((uint32_t)(disPwrCtrl & 1u) << RDEV_CFG_SLV_BIT))

#define ISC_SLV_RDEV_CFG(csi, i2c) \
        ((i2c) | ((uint32_t)(csi) << RDEV_CFG_I2C_BITS) | ((uint32_t)(1u) << RDEV_CFG_CSI_BITS))

#define ADV_CONFIG_INIT(cfg, ctx) \
        do { \
            memset(&cfg, 0, sizeof(cfg)); \
            cfg.clientContext = (void *)(ctx); \
        } while (0)

struct NvMediaISCExposureControl;

struct NvMediaISCWBGainControl;

struct NvMediaISCEmbeddedData;

struct NvMediaISCModuleConfig;

typedef void NvMediaISCDevice;

typedef void NvMediaISCDriverHandle;

typedef void NvMediaISCTransactionHandle;
typedef struct {
    NvMediaVersion libVersion;
} NvMediaISCVersionInfo;

NvMediaStatus
NvMediaISCGetVersionInfo(
    NvMediaISCVersionInfo *versionInfo
);

NvMediaStatus
NvMediaISCGetVersion(
    NvMediaVersion *version
);

typedef enum {
    NVMEDIA_ISC_I2C_BUS_0 = 0,
    NVMEDIA_ISC_I2C_BUS_1 = 1,
    NVMEDIA_ISC_I2C_BUS_2 = 2,
    NVMEDIA_ISC_I2C_BUS_3 = 3,
    NVMEDIA_ISC_I2C_BUS_4 = 4,
    NVMEDIA_ISC_I2C_BUS_5 = 5,
    NVMEDIA_ISC_I2C_BUS_6 = 6,
    NVMEDIA_ISC_I2C_BUS_7 = 7,
    NVMEDIA_ISC_I2C_BUS_8 = 8,
    NVMEDIA_ISC_I2C_BUS_9 = 9,
    NVMEDIA_ISC_I2C_BUS_10 = 10,
    NVMEDIA_ISC_I2C_BUS_11 = 11,
    NVMEDIA_ISC_I2C_SIMULATOR = 255,
} NvMediaISC_I2CPort;

typedef void NvMediaISCRootDevice;

NvMediaISCRootDevice *
NvMediaISCRootDeviceCreate(
    uint32_t portCfg
);

void
NvMediaISCRootDeviceDestroy(
    NvMediaISCRootDevice *device
);

typedef struct {
    NvMediaStatus (* Read)(
        NvMediaISCTransactionHandle *transaction,
        uint32_t deviceIndex,
        uint32_t regLength,
        uint8_t *regData,
        uint32_t dataLength,
        uint8_t *data);
    NvMediaStatus (* Write)(
        NvMediaISCTransactionHandle *transaction,
        uint32_t deviceIndex,
        uint32_t dataLength,
        const uint8_t *data);
    NvMediaStatus (* Wait)(
        NvMediaISCTransactionHandle *transaction,
        uint32_t microSecond);
} NvMediaISCSupportFunctions;

typedef enum {
    NVMEDIA_ISC_SENSOR_ATTR_FUSE_ID,
    NVMEDIA_ISC_SENSOR_ATTR_GAIN_MIN,
    NVMEDIA_ISC_SENSOR_ATTR_GAIN_MAX,
    NVMEDIA_ISC_SENSOR_ATTR_ET_MIN,
    NVMEDIA_ISC_SENSOR_ATTR_ET_MAX,
    NVMEDIA_ISC_SENSOR_ATTR_ET_FINE,
    NVMEDIA_ISC_SENSOR_ATTR_ET_STEP,
    NVMEDIA_ISC_SENSOR_ATTR_HDR_MAX,
    NVMEDIA_ISC_SENSOR_ATTR_GAIN_FACTOR,
    NVMEDIA_ISC_SENSOR_ATTR_QE_PIXEL_RATIO,
    NVMEDIA_ISC_SENSOR_ATTR_FRAME_RATE,
    NVMEDIA_ISC_SENSOR_ATTR_NUM_EXPOSURES,
} NvMediaISCSensorAttrType;


typedef enum {
    NVMEDIA_ISC_CHAR_ATTR_SINGLE_EXP,
} NvMediaISCSensorCharAttr;


typedef struct {
    char *deviceName;
    int32_t regLength;
    int32_t dataLength;
    NvMediaStatus (* DriverCreate)(
        NvMediaISCDriverHandle **handle,
        NvMediaISCSupportFunctions *supportFunctions,
        void *clientContext);
    NvMediaStatus (* DriverDestroy)(
        NvMediaISCDriverHandle *handle);
    NvMediaStatus (* CheckPresence)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction);
    NvMediaStatus (* CheckLink)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t linkIndex,
        uint32_t linkType);
    NvMediaStatus (* SetDefaults)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction);
    NvMediaStatus (* SetDeviceConfig)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t enumeratedDeviceConfig);
    NvMediaStatus (* ReadParameters)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t parameterType,
        uint32_t parameterSize,
        void *parameter);
    NvMediaStatus (* WriteParameters)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t parameterType,
        uint32_t parameterSize,
        void *parameter);
    NvMediaStatus (* ParseEmbeddedData)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t lineCount,
        uint32_t *lineLength,
        uint8_t *lineData[],
        struct NvMediaISCEmbeddedData *parsedInformation);
    NvMediaStatus (* GetSensorFrameId)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t lineCount,
        uint32_t *lineLength,
        uint8_t *lineData[],
        uint32_t *sensorFrameId);
    NvMediaStatus (* GetTemperature)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        float_t *temperature);
    NvMediaStatus (* SetExposure)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        struct NvMediaISCExposureControl *exposureControl);
    NvMediaStatus (* SetWBGain)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        struct NvMediaISCWBGainControl *wbControl);
    NvMediaStatus (* ReadRegister)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t deviceIndex,
        uint32_t registerNum,
        uint32_t dataLength,
        uint8_t *dataBuff);
    NvMediaStatus (* WriteRegister)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t deviceIndex,
        uint32_t registerNum,
        uint32_t dataLength,
        uint8_t *dataBuff);
    NvMediaStatus (* DumpRegisters)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction);
    NvMediaStatus (* GetErrorStatus)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t parameterSize,
        void *parameter);
    NvMediaStatus (* GetModuleConfig)(
        NvMediaISCDriverHandle *handle,
        struct NvMediaISCModuleConfig *moduleConfig);
    NvMediaStatus (* SetBracketedExposure)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t numExposureControls,
        struct NvMediaISCExposureControl *exposureControls);
    NvMediaStatus (* GetSensorAttr)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCSensorAttrType type,
        uint32_t size,
        void *attribute);
    NvMediaStatus (* SetCompandingCurve)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        uint32_t numPoints,
        NvMediaPoint *kneePoints);
    NvMediaStatus (* SetSensorCharAttr)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCTransactionHandle *transaction,
        NvMediaISCSensorCharAttr type,
        uint32_t size,
        void *attribute);
    NvMediaStatus (* GetSensorCharAttr)(
        NvMediaISCDriverHandle *handle,
        NvMediaISCSensorCharAttr type,
        uint32_t size,
        void *attribute);
} NvMediaISCDeviceDriver;

#define NVMEDIA_ISC_TIMEOUT_INFINITE  0xFFFFFFFF

typedef struct {
    void *clientContext;
} NvMediaISCAdvancedConfig;

NvMediaISCDevice *
NvMediaISCDeviceCreate(
    NvMediaISCRootDevice *rootDevice,
    uint32_t *deviceAddressList,
    uint32_t numDevices,
    NvMediaISCDeviceDriver *deviceDriver,
    NvMediaISCAdvancedConfig *advancedConfig
);

void
NvMediaISCDeviceDestroy(
    NvMediaISCDevice *device
);

NvMediaStatus
NvMediaISCCheckPresence(
    NvMediaISCDevice *device
);

NvMediaStatus
NvMediaISCCheckLink(
    NvMediaISCDevice *device,
    uint32_t instanceNumber,
    uint32_t link
);

NvMediaStatus
NvMediaISCSetDefaults(
    NvMediaISCDevice *device
);

NvMediaStatus
NvMediaISCSetDeviceConfig(
    NvMediaISCDevice *device,
    uint32_t enumeratedDeviceConfig
);

NvMediaStatus
NvMediaISCReadParameters(
    NvMediaISCDevice *device,
    uint32_t parameterType,
    uint32_t parameterSize,
    void *parameter
);

NvMediaStatus
NvMediaISCWriteParameters(
    NvMediaISCDevice *device,
    uint32_t parameterType,
    uint32_t parameterSize,
    void *parameter
);

NvMediaStatus
NvMediaISCParseEmbeddedData(
    NvMediaISCDevice *device,
    uint32_t lineCount,
    uint32_t *lineLength,
    uint8_t *lineData[],
    struct NvMediaISCEmbeddedData *parsedInformation
);

NvMediaStatus
NvMediaISCGetSensorFrameId(
    NvMediaISCDevice *device,
    uint32_t lineCount,
    uint32_t *lineLength,
    uint8_t *lineData[],
    uint32_t *sensorFrameId
);

NvMediaStatus
NvMediaISCGetTemperature(
    NvMediaISCDevice *device,
    float_t *temperature
);

typedef enum {
    NVMEDIA_ISC_EXPOSURE_MODE_LONG,
    NVMEDIA_ISC_EXPOSURE_MODE_SHORT,
    NVMEDIA_ISC_EXPOSURE_MODE_VERY_SHORT,
    NVMEDIA_ISC_EXPOSURE_MODE_MAX
} NvMediaISCExposureMode;

typedef struct NvMediaISCExposureControl {
    struct {
        float_t value;
        NvMediaBool valid;
    } exposureTime[NVMEDIA_ISC_EXPOSURE_MODE_MAX];
    struct {
        float_t value;
        NvMediaBool valid;
    } sensorGain[NVMEDIA_ISC_EXPOSURE_MODE_MAX];
    uint8_t sensorFrameId;
} NvMediaISCExposureControl;

typedef struct NvMediaISCWBGainControl {
    struct {
        float_t value[4];
        NvMediaBool valid;
    } wbGain[NVMEDIA_ISC_EXPOSURE_MODE_MAX];
} NvMediaISCWBGainControl;

typedef struct {
    uint32_t baseRegAddress;
    uint32_t size;
    uint32_t bufferSize;
    uint8_t *data;
} NvMediaISCEmbeddedDataBuffer;

typedef struct NvMediaISCEmbeddedData {
    NvMediaISCEmbeddedDataBuffer top;
    NvMediaISCEmbeddedDataBuffer bottom;
    NvMediaISCExposureControl exposureControl;
    NvMediaISCWBGainControl wbControl;
    uint32_t frameSequenceNumber;
} NvMediaISCEmbeddedData;

NvMediaStatus
NvMediaISCSetExposure(
    NvMediaISCDevice *device,
    NvMediaISCExposureControl *exposureControl
);

NvMediaStatus
NvMediaISCSetWBGain(
    NvMediaISCDevice *device,
    NvMediaISCWBGainControl *wbControl
);

NvMediaStatus
NvMediaISCReadRegister(
    NvMediaISCDevice *device,
    uint32_t deviceIndex,
    uint32_t registerAddress,
    uint32_t dataByteNumber,
    uint8_t *dataBuffer
);

NvMediaStatus
NvMediaISCWriteRegister(
    NvMediaISCDevice *device,
    uint32_t deviceIndex,
    uint32_t registerAddress,
    uint32_t dataByteNumber,
    uint8_t *dataBuffer
);

NvMediaStatus
NvMediaISCDumpRegisters(
    NvMediaISCDevice *device
);

NvMediaStatus
NvMediaISCGetErrorStatus(
    NvMediaISCDevice *device,
    uint32_t parameterSize,
    void *parameter
);

NvMediaStatus
NvMediaISCRootDeviceRegisterCallback(
    NvMediaISCRootDevice *device,
    int32_t sigNum,
    void (*cbFunc)(void *),
    void *context
);

typedef enum {
    NVMEDIA_ISC_PWR_AGGREGATOR,
    NVMEDIA_ISC_PWR_LINK_0,
    NVMEDIA_ISC_PWR_LINK_1,
    NVMEDIA_ISC_PWR_LINK_2,
    NVMEDIA_ISC_PWR_LINK_3,
} NvMediaISCPowerItems;

NvMediaStatus
NvMediaISCRootDevicePowerControl(
    NvMediaISCRootDevice *device,
    NvMediaISCPowerItems  powerItem,
    NvMediaBool powerOn
);

NvMediaStatus
NvMediaISCGetSensorAttr(
    NvMediaISCDevice *device,
    NvMediaISCSensorAttrType type,
    uint32_t size,
    void *attribute
);

typedef struct NvMediaISCModuleConfig {
    char cameraModuleCfgName[128];
    const char *cameraModuleConfigPass1;
    const char *cameraModuleConfigPass2;
} NvMediaISCModuleConfig;

NvMediaStatus
NvMediaISCGetModuleConfig(
    NvMediaISCDevice *device,
    NvMediaISCModuleConfig *moduleConfig
);

NvMediaStatus
NvMediaISCSetBracketedExposure(
    NvMediaISCDevice *device,
    uint32_t numExposureControls,
    NvMediaISCExposureControl *exposureControls
);

NvMediaStatus
NvMediaISCSetCompandingCurve(
    NvMediaISCDevice *device,
    uint32_t numPoints,
    NvMediaPoint *kneePoints
);

NvMediaStatus
NvMediaISCRootDeviceGetPowerStatus(
    NvMediaISCRootDevice *device,
    NvMediaISCPowerItems  powerItem,
    NvMediaBool *powerStatus
);

NvMediaStatus
NvMediaISCRootDeviceEnableSync(
    NvMediaISCRootDevice *device,
    NvMediaBool enable
);

NvMediaStatus
NvMediaISCRootDeviceSetSyncConfig(
    NvMediaISCRootDevice *device,
    float_t freq,
    float_t dutyRatio
);

NvMediaStatus
NvMediaISCRootDeviceGetSyncConfig(
    NvMediaISCRootDevice *device,
    float_t *freq,
    float_t *dutyRatio
);

NvMediaStatus
NvMediaISCSetCharacterizationAttr(
    NvMediaISCDevice *device,
    NvMediaISCSensorCharAttr type,
    uint32_t size,
    void *attribute
);


NvMediaStatus
NvMediaISCGetCharacterizationAttr(
    NvMediaISCDevice *device,
    NvMediaISCSensorCharAttr type,
    uint32_t size,
    void *attribute
);

/*
 * \defgroup history_isc History
 * Provides change history for the NvMedia Image Sensor Control API.
 *
 * \section history_isc Version History
 *
 * <b> Version 1.0 </b> April 1, 2014
 * - Initial release
 *
 * <b> Version 1.1 </b> April 3, 2015
 * - Add mode in \ref NvMediaISCEmbeddedData
 *
 * <b> Version 1.2 </b> April 16, 2015
 * - Add new port config macro \ref ISC_ROOT_DEVICE_CFG
 * - The \a advancedConfig attribute is being used in \ref NvMediaISCDeviceCreate
 * - Add new callback function \ref NvMediaISCRootDeviceRegisterCallback to handle device errors
 *
 * <b> Version 1.3 </b> April 24, 2015
 * - Moved the \a regLength and \a dataLength attributes from \ref NvMediaISCAdvancedConfig
 *   in \ref NvMediaISCDeviceDriver.
 * - Add macro \ref ADV_CONFIG_INIT
 *
 * <b> Version 1.4 </b> April 28, 2015
 * - Add hdrRatio in \ref NvMediaISCExposureControl structure
 * - Add conversionGain in \ref NvMediaISCEmbeddedData structure
 *
 * <b> Version 1.5 </b> July 13, 2015
 * - Add exposureMidpointTime in \ref NvMediaISCEmbeddedData structure
 * - Add NVMEDIA_ISC_I2C_SIMULATOR in \ref NVMEDIA_ISC_I2C_SIMULATOR
 * - Add new function \ref NvMediaISCRootDevicePowerControl and \ref NvMediaISCPowerItems
 * - Modify the input paramater cbFunc of NvMediaISCRootDeviceRegisterCallback
 * - Add function \ref NvMediaISCGetErrorStatus to get error information from device
 * - Add \ref NvMediaISCSensorProperties structure
 * - Add \ref NvMediaISCGetSensorProperties to get sensor properties
 *
 * <b> Version 1.6 </b> September 9, 2015
 * - Add SensorMode in \ref NvMediaISCExposureControl structure
 *
 * <b> Version 1.7 </b> September 21, 2015
 * - Increase I2C ports to support 12 I2C busses
 *
 * <b> Version 1.8 </b> December 09, 2015
 * - Add channelGainRatio for sensors which only allow same or fixed ratio gain in exposure channels
 *
 * <b> Version 1.9 </b> January 22, 2016
 * - Add NvMediaISCRootDeviceGetPowerStatus function
 *
 * <b> Version 1.10 </b> May 5, 2016
 * - Add NvMediaISCModuleConfig structure and NvMediaISCGetModuleConfig function.
 *
 * <b> Version 1.11 </b> May 11, 2016
 * - Add \ref NvMediaISCCheckVersion API
 *
 * <b> Version 1.12 </b> June 7, 2016
 * - Add NVMEDIA_ISC_SIMULATOR_ADDRESS to use for ISC simulator devices
 *
 * <b> Version 1.13 </b> June 20, 2016
 * - Add frameSequenceNumber in \ref NvMediaISCEmbeddedData
 *
 * <b> Version 1.14 </b> July 6, 2016
 * - Add ISC_ROOT_DEVICE_CFG_EX macro
 *
 * <b> Version 1.15 </b> July 8, 2016
 * - Add \ref NvMediaISCSetBracketedExposure new API for settings bracketed exposure
 *
 * <b> Version 1.16 </b> Oct 10, 2016
 * - Add sensor attribbutes \ref NvMediaISCSensorAttrType & new API \ref NvMediaISCGetSensorAttr
 *
 * <b> Version 1.17 </b> November 21, 2016
 * - Add \ref NvMediaISCRootDeviceEnableSync new API for enabling/disabling PWM
 * - Add \ref NvMediaISCRootDeviceSetSyncConfig new API for setting PWM's frequency and duty
 * - Add \ref NvMediaISCRootDeviceGetSyncConfig new API for getting PWM's frequency and duty
 *
 * <b> Version 1.18 </b> Jan 5, 2017
 * - Add \ref NvMediaISCSetCompandingCurve API for setting companding curve
 *
 * <b> Version 1.19 </b> Jan 27, 2017
 * - Add \ref Add const modifier to data parameter in NvmediaISCSupportFuntion Write.
 *
 * <b> Version 2.00 </b> April 19, 2017
 * - Deprecated NvMediaISCDeviceType and EnableLink from \ref NvMediaISCDeviceDriver.
 * - Updated to use stdint.h
 * - Replaced float with float_t
 * - Removed unused input param from NvMediaISCRootDeviceCreate
 * - Deprecated queueElementsNumber and queueElementSize from \ref NvMediaISCRootDeviceCreate
 * - Deprecated unused or not supported APIs as below list.
 *     NvMediaISCRootDeviceDoTransaction
 *     NvMediaISCRootDeviceSync
 *     NvMediaISCUpdateDeviceAddress
 *     NvMediaISCSetDeviceLinkMode
 *     NvMediaISCGetLinkStatus
 *     NvMediaISCSetPriority
 * - NvMediaISCGetLinkStatus is replaced by \ref NvMediaISCCheckLink
 * - Updated NvMediaISCCheckLink to have one more argument to specify which link
 *   to enable as optional.
 * - Renamed ISC_ROOT_DEVICE_CFG_EX to ISC_SLV_RDEV_CFG
 * - Renamed ISC_ROOT_DEVICE_CFG to ISC_RDEV_CFG
 * - Deprecated parentDevice, instanceNumber from NvMediaISCDeviceCreate
 * - Deprecated NvMediaISCGetSensorProperties, repleaced by \ref NvMediaISCGetSensorAttr
 *
 * <b> Version 2.1 </b> May 12, 2017
 * - Added \ref NvMediaISCGetVersion API to get the version of NvMedia ISC library
 * - NvMediaISCCheckVersion is deprecated. Use NvMediaISCGetVersion() instead
 *
 * <b> Version 2.2 </b> May 23, 2017
 * - Deprecated NvMediaISCSensorMode
 * - Deprecated mode & exposureMidpointTime from \ref NvMediaISCEmbeddedData
 * - Deprecated sensorMode & hdrRatio from \ref NvMediaISCExposureControl
 * - Replaced exposure in \ref NvMediaISCEmbeddedData with \ref NvMediaISCExposureControl
 * - Replaced wbGains in \ref NvMediaISCEmbeddedData with \ref NvMediaISCWBGainControl
 *
 * <b> Version 2.3 </b> May 26, 2017
 * - Add device list for ISC handle creation
 *
 * <b> Version 2.4 </b> Feb 26, 2018
 * - Add ISC_RDEV_CFG_EX to have an option to disable power control in \ref NvMediaISCRootDeviceCreate
 *
 * <b> Version 2.5 </b> April 30, 2018
 * - Add sensor characterization attributes \ref NvMediaISCSensorCharAttr
 * - Add new APIs \ref NvMediaISCSetCharacterizationAttr \ref NvMediaISCGetCharacterizationAttr
 *
 */

#ifdef __cplusplus
};     /* extern "C" */
#endif

#endif /* _NVMEDIA_ISC_H */