tmbslhdmitx.h

HDMI NXP9983 chipset controller driver

    \param[in]  vFmtLength  Number of SVDs supported in buffer pEdidVFmts,
                            up to HDMI_TX_SVD_MAX_CNT
    \param[out] pVFmtsAvail Pointer to receive the number of SVDs available
    \param[out] pVidFlags   Ptr to the byte to receive Video Capability Flags
                            b7: underscan supported
                            b6: YCbCr 4:4:4 supported
                            b5: YCbCr 4:2:2 supported

    \return     The call result:
                - TM_OK: the call was successful
                - Else a problem has been detected:
                  - TMBSL_ERR_HDMI_BAD_PARAMETER: a parameter was out of range
                  - TMBSL_ERR_HDMI_BAD_UNIT_NUMBER: bad transmitter unit number
                  - TMBSL_ERR_HDMI_I2C_READ: failed when reading the I2C bus
                  - TMBSL_ERR_HDMI_INVALID_STATE: EDID checksum failure
                  - TMBSL_ERR_HDMI_NOT_INITIALIZED: transmitter not initialized
                  - TMBSL_ERR_HDMI_NULL_CONNECTION: HPD pin is inactive
    
    \note \verbatim
                Supported Short Video Descriptors array:
                    (HDMI_TX_SVD_NATIVE_MASK bit set to indicate native format)
                EdidVFmts[0]   EIA/CEA Short Video Descriptor 1, or 0
                ...
                EdidVFmts[n-1]  EIA/CEA Short Video Descriptor 32, or 0
                (Where n is the smaller of vFmtLength and pVFmtAvail)
    \endverbatim
    \sa         tmbslHdmiTxEdidGetBlockData
 */
tmErrorCode_t
tmbslHdmiTxEdidGetVideoCapabilities
(
    tmUnitSelect_t  txUnit,
    UInt8           *pEdidVFmts,
    UInt            vFmtLength,
    UInt            *pVFmtsAvail,
    UInt8           *pVidFlags
);

/*============================================================================*/
/**
 * \brief The tmbslHdmiTxEdidGetVideoPreferred() parameter type
 */
typedef struct _tmbslHdmiTxEdidDtd_t
{
    UInt16  uPixelClock;        /**< Pixel Clock/10,000         */
    UInt16  uHActivePixels;     /**< Horizontal Active Pixels   */
    UInt16  uHBlankPixels;      /**< Horizontal Blanking Pixels */
    UInt16  uVActiveLines;      /**< Vertical Active Lines      */
    UInt16  uVBlankLines;       /**< Vertical Blanking Lines    */
    UInt16  uHSyncOffset;       /**< Horizontal Sync Offset     */
    UInt16  uHSyncWidth;        /**< Horiz. Sync Pulse Width    */
    UInt16  uVSyncOffset;       /**< Vertical Sync Offset       */
    UInt16  uVSyncWidth;        /**< Vertical Sync Pulse Width  */
    UInt16  uHImageSize;        /**< Horizontal Image Size      */
    UInt16  uVImageSize;        /**< Vertical Image Size        */
    UInt16  uHBorderPixels;     /**< Horizontal Border          */
    UInt16  uVBorderPixels;     /**< Vertical Border            */
    UInt8   Flags;              /**< Interlace/sync info        */
} tmbslHdmiTxEdidDtd_t;

/**
    \brief      Get preferred video format from previously read EDID

    \param[in]  txUnit      Transmitter unit number
    \param[out] pEdidDTD    Pointer to the structure to receive the Detailed
                            Timing Descriptor parameters of the preferred video
                            format

    \return     The call result:
                - TM_OK: the call was successful
                - Else a problem has been detected:
                  - TMBSL_ERR_HDMI_BAD_PARAMETER: a parameter was out of range
                  - TMBSL_ERR_HDMI_BAD_UNIT_NUMBER: bad transmitter unit number
                  - TMBSL_ERR_HDMI_I2C_READ: failed when reading the I2C bus
                  - TMBSL_ERR_HDMI_INVALID_STATE: EDID checksum failure
                  - TMBSL_ERR_HDMI_NOT_INITIALIZED: transmitter not initialized
                  - TMBSL_ERR_HDMI_NULL_CONNECTION: HPD pin is inactive

    \note \verbatim      
                Detailed Timing Descriptor parameters output structure:
                UInt16 uPixelClock      Pixel Clock (MHz/10,000)
                UInt16 uHActivePixels   Horizontal Active Pixels
                UInt16 uHBlankPixels    Horizontal Blanking Pixels
                UInt16 uVActiveLines    Vertical Active Lines
                UInt16 uVBlankLines     Vertical Blanking Lines
                UInt16 uHSyncOffset     Horizontal Sync Offset (Pixels)
                UInt16 uHSyncWidth      Horizontal Sync Pulse Width (Pixels)
                UInt16 uVSyncOffset     Vertical Sync Offset (Lines)
                UInt16 uVSyncWidth      Vertical Sync Pulse Width (Lines)
                UInt16 uHImageSize      Horizontal Image Size (mm)
                UInt16 uVImageSize      Vertical Image Size (mm)
                UInt16 uHBorderPixels   Horizontal Border (Pixels)
                UInt16 uVborderPixels   Vertical Border (Pixels)
                UInt8 Flags             Interlace/sync info
    \endverbatim
    \sa         tmbslHdmiTxEdidGetBlockData
 */
tmErrorCode_t
tmbslHdmiTxEdidGetVideoPreferred
(
    tmUnitSelect_t          txUnit,
    tmbslHdmiTxEdidDtd_t    *pEdidDTD
);

/**
    \brief      Get detailed timing descriptor from previously read EDID

    \param[in]  txUnit      Transmitter unit number
    \param[out] pEdidDTD    Pointer to the array to receive the Detailed timing descriptor

    \param[in]  nb_size     Number of DTD supported in buffer pEdidDTD

    \param[out] pDTDAvail Pointer to receive the number of DTD available

    \return     The call result:
                - TM_OK: the call was successful
                - Else a problem has been detected:
                  - TMBSL_ERR_HDMI_BAD_PARAMETER: a parameter was out of range
                  - TMBSL_ERR_HDMI_BAD_UNIT_NUMBER: bad transmitter unit number
                  - TMBSL_ERR_HDMI_INVALID_STATE: EDID not read
                  - TMBSL_ERR_HDMI_NOT_INITIALIZED: transmitter not initialized
*/
tmErrorCode_t
tmbslHdmiTxEdidGetDetailedTimingDescriptors
(
    tmUnitSelect_t          txUnit,
    tmbslHdmiTxEdidDtd_t    *pEdidDTD,
    UInt8                   nb_size,
    UInt8                   *pDTDAvail
);



/*============================================================================*/
/**
 * tmbslHdmiTxHdcpCheck() parameter type
 */
/** HDCP check result */
typedef enum
{
    HDMITX_HDCP_CHECK_NOT_STARTED       = 0,    /**< Check not started */
    HDMITX_HDCP_CHECK_IN_PROGRESS       = 1,    /**< No failures, more to do */
    HDMITX_HDCP_CHECK_PASS              = 2,    /**< Final check has passed */
    HDMITX_HDCP_CHECK_FAIL_FIRST        = 3,    /**< First check failure code */
    HDMITX_HDCP_CHECK_FAIL_DRIVER_STATE = 3,    /**< Driver not AUTHENTICATED */
    HDMITX_HDCP_CHECK_FAIL_DEVICE_T0    = 4,    /**< A T0 interrupt occurred */
    HDMITX_HDCP_CHECK_FAIL_DEVICE_RI    = 5,    /**< Device RI changed */
    HDMITX_HDCP_CHECK_FAIL_DEVICE_FSM   = 6,    /**< Device FSM not 10h */
    HDMITX_HDCP_CHECK_NUM               = 7     /**< Number of check results */
}tmbslHdmiTxHdcpCheck_t;

/**
    \brief      Check the result of an HDCP encryption attempt, called at
                intervals (set by uTimeSinceLastCallMs) after tmbslHdmiTxHdcpRun

    \param[in]  txUnit                  Transmitter unit number
    \param[in]  uTimeSinceLastCallMs    Time in ms since this was last called
    \param[out] pResult                 The outcome of the check

    \return     The call result:
                - TM_OK: the call was successful
                - Else a problem has been detected:
                  - TMBSL_ERR_HDMI_BAD_UNIT_NUMBER: bad transmitter unit number
                  - TMBSL_ERR_HDMI_BAD_PARAMETER: a parameter was out of range
                  - TMBSL_ERR_HDMI_NOT_INITIALIZED: transmitter not initialized
                  - TMBSL_ERR_HDMI_I2C_READ: failed when reading the I2C bus
                  - TMBSL_ERR_HDMI_I2C_WRITE: failed when writing the I2C bus
                  - TMBSL_ERR_HDMI_NOT_SUPPORTED: device does not support HDCP
 */
tmErrorCode_t
tmbslHdmiTxHdcpCheck
(
    tmUnitSelect_t	        txUnit,
    UInt16                  uTimeSinceLastCallMs,
    tmbslHdmiTxHdcpCheck_t  *pResult
);

/*============================================================================*/
/**
 * tmbslHdmiTxHdcpConfigure() parameter type
 */
/** HDCP DDC slave addresses */
enum _tmbslHdmiTxHdcpSlaveAddress
{
    HDMITX_HDCP_SLAVE_PRIMARY    = 0x74,
    HDMITX_HDCP_SLAVE_SECONDARY  = 0x76
};

/** HDCP transmitter modes */
typedef enum
{
    HDMITX_HDCP_TXMODE_NOT_SET   = 0,
    HDMITX_HDCP_TXMODE_REPEATER  = 1,
    HDMITX_HDCP_TXMODE_TOP_LEVEL = 2,
    HDMITX_HDCP_TXMODE_MAX       = 2
}tmbslHdmiTxHdcpTxMode_t;

/** HDCP option flags */
typedef enum
{
    HDMITX_HDCP_OPTION_FORCE_PJ_IGNORED = 0x01,/* Not set: obey PJ result     */
    HDMITX_HDCP_OPTION_FORCE_SLOW_DDC   = 0x02,/* Not set: obey BCAPS setting */
    HDMITX_HDCP_OPTION_FORCE_NO_1_1     = 0x04,/* Not set: obey BCAPS setting */
    HDMITX_HDCP_OPTION_FORCE_REPEATER   = 0x08,/* Not set: obey BCAPS setting */
    HDMITX_HDCP_OPTION_FORCE_NO_REPEATER= 0x10,/* Not set: obey BCAPS setting */
    HDMITX_HDCP_OPTION_FORCE_V_EQU_VBAR = 0x20,/* Not set: obey V=V' result   */
    HDMITX_HDCP_OPTION_FORCE_VSLOW_DDC  = 0x40,/* Set: 50kHz DDC */
    HDMITX_HDCP_OPTION_DEFAULT          = 0x00,/* All the above Not Set vals */
    HDMITX_HDCP_OPTION_MASK             = 0x7F,/* Only these bits are allowed */
    HDMITX_HDCP_OPTION_MASK_BAD         = 0x80 /* These bits are not allowed  */
}tmbslHdmiTxHdcpOptions_t;

/**
    \brief      Configure various HDCP parameters

    \param[in]  txUnit          Transmitter unit number
    \param[in]  slaveAddress    DDC I2C slave address
    \param[in]  txMode          Mode of our transmitter device
    \param[in]  options         Options flags to control behaviour of HDCP
    \param[in]  uCheckIntervalMs HDCP check interval in milliseconds
    \param[in]  uChecksToDo     Number of HDCP checks to do after HDCP starts
                                A value of 2 or more is valid for checking
                                May be set to 0 to disabling checking

    \return     The call result:
                - TM_OK: the call was successful
                - Else a problem has been detected:
                  - TMBSL_ERR_HDMI_BAD_UNIT_NUMBER: bad transmitter unit number
                  - TMBSL_ERR_HDMI_BAD_PARAMETER: a parameter was out of range
                  - TMBSL_ERR_HDMI_NOT_INITIALIZED: transmitter not initialized
                  - TMBSL_ERR_HDMI_I2C_READ: failed when reading the I2C bus
                  - TMBSL_ERR_HDMI_I2C_WRITE: failed when writing the I2C bus
                  - TMBSL_ERR_HDMI_NOT_SUPPORTED: device does not support HDCP

    \note       Must be called before all other HDCP APIs
 */
tmErrorCode_t
tmbslHdmiTxHdcpConfigure
(
    tmUnitSelect_t	         txUnit,
    UInt8                    slaveAddress,
    tmbslHdmiTxHdcpTxMode_t  txMode,
    tmbslHdmiTxHdcpOptions_t options,
    UInt16                   uCheckIntervalMs,
    UInt8                    uChecksToDo
);

/*============================================================================*/
/**
 * tmbslHdmiTxHdcpDownloadKeys() parameter type
 */
/** HDCP decryption mode */
typedef enum
{
    HDMITX_HDCP_DECRYPT_DISABLE  = 0,
    HDMITX_HDCP_DECRYPT_ENABLE   = 1,
    HDMITX_HDCP_DECRYPT_MAX      = 1
}tmbslHdmiTxDecrypt_t;

/**
    \brief      Download keys and AKSV data from OTP memory to the device

    \param[in]  txUnit          Transmitter unit number
    \param[in]  seed            Seed value
    \param[in]  keyDecryption   State of key decryption 0 to 1 (disabled, enabled)

    \return     The call result:
                - TM_OK: the call was successful
                - Else a problem has been detected:
                  - TMBSL_ERR_HDMI_BAD_UNIT_NUMBER: bad transmitter unit number
                  - TMBSL_ERR_HDMI_BAD_PARAMETER: a parameter was out of range
                  - TMBSL_ERR_HDMI_NOT_INITIALIZED: transmitter not initialized
                  - TMBSL_ERR_HDMI_I2C_READ: failed when reading the I2C bus
                  - TMBSL_ERR_HDMI_I2C_WRITE: failed when writing the I2C bus
                  - TMBSL_ERR_HDMI_NOT_SUPPORTED: device does not support HDCP
 */
tmErrorCode_t
tmbslHdmiTxHdcpDownloadKeys
(
    tmUnitSelect_t	        txUnit,
    UInt16                  seed,
    tmbslHdmiTxDecrypt_t    keyDecryption
);

/*============================================================================*/
/**
    \brief      Switch HDCP encryption on or off without disturbing Infoframes
                (Not normally used)

    \param[in]  txUnit  Transmitter unit number
    \param[in]  bOn     Encryption state: 1=on, 0=off

    \return     The call result:
                - TM_OK: the call was successful
                - Else a problem has been detected:
                  - TMBSL_ERR_HDMI_BAD_UNIT_NUMBER: bad transmitter unit number
                  - TMBSL_ERR_HDMI_BAD_PARAMETER: a parameter was out of range
                  - TMBSL_ERR_HDMI_NOT_INITIALIZED: transmitter not initialized
                  - TMBSL_ERR_HDMI_I2C_WRITE: failed when writing the I2C bus
                  - TMBSL_ERR_HDMI_NOT_SUPPORTED: device does not support HDCP
*/
tmErrorCode_t
tmbslHdmiTxHdcpEncryptionOn
(
    tmUnitSelect_t	txUnit,
    Bool            bOn
);

/*======================================