nvmedia_icp.h

Go to the documentation of this file.

/*
 * Copyright (c) 2014-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_ICP_H
#define _NVMEDIA_ICP_H

#ifdef __cplusplus
extern "C" {
#endif

#include "nvmedia_core.h"
#include "nvmedia_surface.h"
#include "nvmedia_image.h"

#define NVMEDIA_ICP_VERSION_MAJOR   4

#define NVMEDIA_ICP_VERSION_MINOR   7

#define NVMEDIA_IMAGE_CAPTURE_TIMEOUT_INFINITE  0xFFFFFFFF

#define NVMEDIA_ICP_MAX_VIRTUAL_GROUPS     4

#define NVMEDIA_ICP_MAX_VIRTUAL_CHANNELS   3

#define NVMEDIA_ICP_HANDLER(icpEx, groupIdx) (icpEx->icp[groupIdx].hIcp)

#define NVMEDIA_ICP_SETTINGS_HANDLER(icpSettingsEx, groupIdx, vcIdx) \
        (&icpSettingsEx.virtualGroups[groupIdx].virtualChannels[vcIdx].icpSettings)

#define NVMEDIA_ICP_ERROR(_type_, _error_, _value_, _desc_)   \
        NVMEDIA_ICP_##_type_##_ERROR_##_error_ = _value_,

typedef enum {
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_A,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_B,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_AB,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_C,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_D,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_CD,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_E,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_F,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_EF,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_G,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_H,
    NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_CSI_GH,
} NvMediaICPInterfaceType;

typedef enum {
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_YUV422,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_YUV422_10,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_YUV444,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RGB888,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW6,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW7,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW8,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW10,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW12,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW14,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW16,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW20,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_1,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_2,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_3,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_4,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_5,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_6,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_7,
    NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER_DEFINED_8
} NvMediaICPInputFormatType;

typedef struct {
    NvMediaICPInputFormatType inputFormatType;
    NvMediaBitsPerPixel bitsPerPixel;
} NvMediaICPInputFormat;

typedef enum {
    /* CSI is in Dphy mode */
    NVMEDIA_ICP_CSI_DPHY_MODE = 0,
    /* CSI is in CPHY mode */
    NVMEDIA_ICP_CSI_CPHY_MODE
} NvMediaICPCsiPhyMode;

typedef struct {
    NvMediaICPInterfaceType interfaceType;
    NvMediaICPInputFormat inputFormat;
    NvMediaSurfaceType surfaceType;
    uint16_t width;
    uint16_t height;
    uint16_t startX;
    uint16_t startY;
    uint16_t embeddedDataLines;
    uint32_t interfaceLanes;
    uint32_t pixelFrequency;
    uint32_t mipiSpeed;
    uint16_t thsSettle;
    NvMediaBool embeddedDataType;
    uint8_t tpgEnable;
    NvMediaICPCsiPhyMode phyMode;
} NvMediaICPSettings;

typedef struct {
    NvMediaICPInterfaceType interfaceType;
    uint32_t interfaceLanes;
    struct {
        struct {
            /* Holds the virtual Channel Index from CSI TX. */
            uint16_t virtualChannelIndex;
            /* Holds the image capture settings for CSI format. */
            NvMediaICPSettings icpSettings;
            /* Holds the clipping rectangle. */
            NvMediaRect clipRect;
        } virtualChannels[NVMEDIA_ICP_MAX_VIRTUAL_CHANNELS];
        uint16_t numVirtualChannels;
    } virtualGroups[NVMEDIA_ICP_MAX_VIRTUAL_GROUPS];
    uint16_t numVirtualGroups;
    NvMediaICPCsiPhyMode phyMode;
} NvMediaICPSettingsEx;

typedef void NvMediaICP;

typedef struct {
    /* Holds the number of virtual groups used. */
    uint16_t numVirtualGroups;
    struct {
        /* Holds the virtual Group Index. */
        uint16_t virtualGroupId;
        /* Holds the image capture handler. */
        NvMediaICP *hIcp;
    } icp[NVMEDIA_ICP_MAX_VIRTUAL_GROUPS];
} NvMediaICPEx;

typedef enum {
    /* Unrecognized or no errors */
    NVMEDIA_ICP_ERROR(CAPTURE, NONE,              0x0000, "Either no error occurred or error could not be translated")

    /* CSI mux frame errors */
    NVMEDIA_ICP_ERROR(CSI, FS_FAULT,              0x0001, "A frame start occurred before previous frame end")
    NVMEDIA_ICP_ERROR(CSI, FE_CSI_FAULT,          0x0002, "A NVCSI fault received at frame end")
    NVMEDIA_ICP_ERROR(CSI, FE_FRAMEID_FAULT,      0x0003, "Frame ID for FE packet does not match that of FS packet")
    NVMEDIA_ICP_ERROR(CSI, FE_FORCED_FAULT,       0x0004, "A frame end was injected by the CSI hardware")
    NVMEDIA_ICP_ERROR(CSI, PXL_ENABLE_FAULT ,     0x0005, "An illegal pixel encoding has been detected")

    /* VI channel sel errors */
    NVMEDIA_ICP_ERROR(VI, SHORT_FRAME,            0x0010, "FE packet arrived before the normal number of pixels has appeared ")
    NVMEDIA_ICP_ERROR(VI, FAULT_FE,               0x0011, "Data specific fault occurred on a channel")

    /* VI channel sel faults */
    NVMEDIA_ICP_ERROR(VI, PXL_MISSING_LE,         0x0100, "Two LS packets were detected without a LE packet between them")
    NVMEDIA_ICP_ERROR(VI, PXL_RUNAWAY,            0x0101, "More lines were received than expected")
    NVMEDIA_ICP_ERROR(VI, PXL_SPURIOUS,           0x0102, "A pixel data packet was received without a LS packet first")
    NVMEDIA_ICP_ERROR(VI, PXL_LONG_LINE,          0x0103, "More pixels were received than expected in a line")
    NVMEDIA_ICP_ERROR(VI, PXL_SHORT_LINE,         0x0104, "Fewer pixels were received than expected in a line")
    NVMEDIA_ICP_ERROR(VI, EMB_MISSING_LE,         0x0105, "Two LS packets were detected without a LE packet between them in emb data")
    NVMEDIA_ICP_ERROR(VI, EMB_RUNAWAY,            0x0106, "More lines were received than expected in emb data")
    NVMEDIA_ICP_ERROR(VI, EMB_SPURIOUS,           0x0107, "A pixel data packet was received without a LS packet first in emb data")
    NVMEDIA_ICP_ERROR(VI, EMB_LONG_LINE,          0x0108, "More pixels were received than expected in a line in emb data")
    NVMEDIA_ICP_ERROR(VI, EMB_INFRINGE,           0x0109, "Embedded data was received on a frame where no embedded data was expected")
    NVMEDIA_ICP_ERROR(VI, DTYPE_MISMATCH,         0x010A, "The pixel datatype changed in the middle of the line")
} NvMediaICPErrorStatus;

typedef struct {
    /* Holds the CSI stream index. */
    uint32_t csiStreamId;
    /* Holds the CSI frame index generated by CSI Tx */
    uint32_t csiFrameId;
    /* Holds the virtual channel index. */
    uint32_t virtualChannelId;
    /* Holds the CSI error status. */
    NvMediaICPErrorStatus errorStatus;
} NvMediaICPErrorInfo;

NvMediaStatus
NvMediaICPGetVersion(
    NvMediaVersion *version
);

NvMediaICPEx *
NvMediaICPCreateEx(
    NvMediaICPSettingsEx *settings
);

void
NvMediaICPDestroyEx(
    NvMediaICPEx *icpEx
);

NvMediaStatus
NvMediaICPFeedFrame(
    NvMediaICP   *icp,
    NvMediaImage *image,
    uint32_t millisecondTimeout
);

NvMediaStatus
NvMediaICPFeedImageGroup(
    NvMediaICP   *icp,
    NvMediaImageGroup *imageGrp,
    unsigned int millisecondTimeout
);

NvMediaStatus
NvMediaICPStop(
    NvMediaICP *icp
);

NvMediaStatus
NvMediaICPResume(
    NvMediaICP *icp);

NvMediaStatus
NvMediaICPGetFrameEx(
    NvMediaICP *icp,
    uint32_t millisecondTimeout,
    NvMediaImage **image
);

NvMediaStatus
NvMediaICPGetImageGroup(
    NvMediaICP *icp,
    uint32_t millisecondTimeout,
    NvMediaImageGroup **imageGrp
);

NvMediaStatus
NvMediaICPReleaseFrame(
    NvMediaICP *icp,
    NvMediaImage **image
);

NvMediaStatus
NvMediaICPReleaseImageGroup(
    NvMediaICP *icp,
    NvMediaImageGroup **imageGrp
);

NvMediaStatus
NvMediaICPGetErrorInfo(
    NvMediaICP *icp,
    NvMediaICPErrorInfo *icpErrorInfo
);

/*
 * \defgroup history_nvmedia_icp History
 * Provides change history for the NvMedia ICP API.
 *
 * \section history_nvmedia_icp Version History
 *
 * <b> Version 2.0 </b> April 4, 2016
 * - Initial release
 *
 * <b> Version 2.1 </b> May 11, 2016
 * - Added \ref NvMediaICPCheckVersion API
 *
 * <b> Version 2.2 </b> August 17, 2016
 * - Added \ref NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_UYVY image capture input
 * format type
 *
 * <b> Version 2.3 </b> August 31, 2016
 * - Added option for enabling embeddedDataType in \ref NvMediaICPSettings
 *
 * <b> Version 2.4 </b> Jan 23, 2017
 * - Added \ref NvMediaICPErrorInfo and \ref NvMediaICPGetErrorInfo
 *
 * <b> Version 2.5 </b> March 16, 2017
 * - Added \ref NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_USER ,
 * \ref NvMediaICPUserFormatType and option for enabling userFormatType in
 * \ref NvMediaICPInputFormat
 *
 * <b> Version 3.0 </b> April 19, 2017
 * Updated to use stdint.h instead of "unsigned int",
 *   "int", "unsigned short" and "char".
 * NvMediaICPCreate and NvMediaICPDestroy are now deprecated.
 * NvMediaICPGetFrame is now deprecated.
 * NvMediaICPInterfaceFormat is now deprecated, it will be always CSI.
 *
 * <b> Version 3.1 </b> May 12, 2017
 * - Added \ref NvMediaICPGetVersion API to get the version of NvMedia ICP library
 * - NvMediaICPCheckVersion is deprecated. Use NvMediaICPGetVersion() instead
 *
 * <b> Version 3.2 </b> May 19, 2017
 * Removed \ref NvMediaICPSurfaceFormatType
 * NvMediaICPSettings now takes NvMediaSurfaceType to indicate capture surface format
 * Removed NVMEDIA_IMAGE_CAPTURE_CSI_INTERFACE_TYPE_TPG0
 * Combined NvMediaICPUserFormatType with NvMediaICPInputFormatType
 * Removed NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_YUV420
 *   from \ref NvMediaICPInputFormatType
 * Added RAW6/RAW7/RAW8/RAW10/RAW12/RAW14 in NvMediaICPInputFormatType
 * Removed pixelOrder from \ref NvMediaICPInputFormat
 * Added tpgEnagle in \ref NvMediaICPSettings
 *
 * <b> Version 4.2 </b> June 12, 2017
 * Added virtualGroupIndex inside \ref NvMediaICPSettingsEx
 * Renamed virtualChannel to virtualGroup inside \ref NvMediaICPEx
 * Added \ref NvMediaICPFeedImageGroup and \ref NvMediaICPGetImageGroup APIs
 *
 * <b> Version 4.3 </b> October 5, 2017
 * - Added \ref NvMediaICPResume API
 *
 * <b> Version 4.4 </b> October 11, 2017
 * Changed the prototypes for \ref NvMediaICPGetImageGroup and
 * \ref NvMediaICPReleaseImageGroup to accept double pointer to imageGrp
 *
 * <b> Version 4.5 </b> November 10, 2017
 * Added YUV422_10, RAW16, RAW20 support in \ref NvMediaICPInputFormatType
 * \ref NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_YUV422_10,
 * \ref NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW16,
 * \ref NVMEDIA_IMAGE_CAPTURE_INPUT_FORMAT_TYPE_RAW20
 *
 * <b> Version 4.6 </b> November 18, 2017
 * Added additional CSI interfaces, CSI phy mode parameter to \ref NvMediaICPSettingsEX
 *
 * <b> Version 4.7 </b> March 16, 2018
 * Added mipiSpeed in \ref NvMediaICPSettings
 *
 */
#ifdef __cplusplus
};     /* extern "C" */
#endif

#endif /* _NVMEDIA_ICP_H */