tmbslhdmitx.h

HDMI NXP9983 chipset controller driver

                - 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 to the I2C bus
                  - TMBSL_ERR_HDMI_OPERATION_NOT_PERMITTED: in DVI mode

    \note       Use tmbslHdmiTxAudioOutSetChanStatus to set all other CS bytes
                This function only sets the mapping for Audio Port 0.

 */
tmErrorCode_t
tmbslHdmiTxAudioOutSetChanStatusMapping
(
    tmUnitSelect_t  txUnit,
    UInt8           sourceLeft,
    UInt8           channelLeft,
    UInt8           sourceRight,
    UInt8           channelRight
);


/*============================================================================*/
/**
 * tmbslHdmiTxAudioOutSetMute() parameter type
 */
typedef enum
{
    HDMITX_AMUTE_OFF       = 0,    /**< Mute off */
    HDMITX_AMUTE_ON        = 1,    /**< Mute on  */
    HDMITX_AMUTE_INVALID   = 2     /**< Invalid  */
} tmbslHdmiTxaMute_t;

/**
    \brief      Mute or un-mute the audio output by controlling the audio FIFO,
                in HDMI mode only

    \param[in]  txUnit      Transmitter unit number
    \param[in]  aMute       Audio mute: On, 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 to the I2C bus
                  - TMBSL_ERR_HDMI_OPERATION_NOT_PERMITTED: in DVI mode

    \note       tmbslHdmiTxPktSetGeneralCntrl must be used to control the audio
                mute in outgoing data island packets

 */
tmErrorCode_t
tmbslHdmiTxAudioOutSetMute
(
    tmUnitSelect_t      txUnit,
    tmbslHdmiTxaMute_t aMute
);


/*============================================================================*/
/**
    \brief      Disable an HDMI Transmitter output and destroy its driver 
                instance

    \param[in]  txUnit Transmitter unit number

    \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_NOT_INITIALIZED: the unit is not initialized
                  - TMBSL_ERR_HDMI_I2C_WRITE: failed when writing to the I2C bus
 */
tmErrorCode_t 
tmbslHdmiTxDeinit
(
    tmUnitSelect_t      txUnit
);


/*============================================================================*/
/**
 * \brief The tmbslHdmiTxEdidGetAudioCapabilities() parameter type
 */
typedef struct _tmbslHdmiTxEdidSad_t
{
    UInt8   ModeChans;  /* Bits[6:3]: EIA/CEA861 mode; Bits[2:0]: channels */
    UInt8   Freqs;      /* Bits for each supported frequency */
    UInt8   Byte3;      /* EIA/CEA861B p83: data depending on audio mode */
}tmbslHdmiTxEdidSad_t;

/** Number of 3 byte Short Audio Descriptors stored in pEdidAFmts */
#define HDMI_TX_SAD_MAX_CNT     10

/**
    \brief      Get supported audio format(s) from previously read EDID

    \param[in]  txUnit      Transmitter unit number
    \param[out] pEdidAFmts  Pointer to the array of structures to receive the 
                            supported Short Audio Descriptors
    \param[in]  aFmtLength  Number of SADs supported in buffer pEdidAFmts,
                            up to HDMI_TX_SAD_MAX_CNT
    \param[out] pAFmtsAvail Pointer to receive the number of SADs available
    \param[out] pAudioFlags Pointer to the byte to receive the Audio Capability
                            Flags

    \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 Audio Descriptors array:
                EdidAFmts[0].ModeChans      SAD 1  - Mode byte
                EdidAFmts[0].Freqs	        SAD 1  - Frequencies byte
                EdidAFmts[0].Byte3          SAD 1  - Byte 3
                ...
                EdidAFmts[n-1].ModeChans    SAD n  - Mode byte
                EdidAFmts[n-1].Freqs	    SAD n  - Frequencies byte
                EdidAFmts[n-1].Byte3        SAD n  - Byte 3
                (Where n is the smaller of aFmtLength and pAFmtAvail)
    \endverbatim
 */
tmErrorCode_t
tmbslHdmiTxEdidGetAudioCapabilities
(
    tmUnitSelect_t          txUnit,
    tmbslHdmiTxEdidSad_t    *pEdidAFmts,
    UInt                    aFmtLength,
    UInt                    *pAFmtsAvail,
    UInt8                   *pAudioFlags
);

/*============================================================================*/
/**
    \brief      Get the EDID block count

    \param[in]  txUnit              Transmitter unit number
    \param[out] puEdidBlockCount    Pointer to data byte in which to return the
                                    block count

    \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
 */
tmErrorCode_t
tmbslHdmiTxEdidGetBlockCount
(
    tmUnitSelect_t  txUnit,
    UInt8           *puEdidBlockCount
);

/*============================================================================*/
/**
 * tmbslHdmiTxEdidGetBlockData() parameter types
 */
/** An enum to represent the current EDID status */
enum _tmbslHdmiTxEdidSta_t
{
    HDMITX_EDID_READ                = 0,    /* All blocks read OK */
    HDMITX_EDID_READ_INCOMPLETE     = 1,    /* All blocks read OK but buffer too
                                               small to return all of them */
    HDMITX_EDID_ERROR               = 2,    /* Block 0 OK, checksum error in one
                                               or more other blocks */
    HDMITX_EDID_ERROR_INCOMPLETE    = 3,    /* Block 0 OK, checksum error in one
                                               or more other blocks and buffer
                                               too small to return all of them*/
    HDMITX_EDID_NOT_READ            = 4     /* EDID not read or checksum error
                                               in block 0 */
};
 
/**
    \brief      Get raw EDID blocks from the sink device via DDC

    \param[in]  txUnit      Transmitter unit number
    \param[out] pRawEdid    Pointer to a buffer supplied by the caller to accept
                            the raw EDID data
    \param[in]  numBlocks   Number of blocks to read
    \param[in]  lenRawEdid  Length in bytes of the supplied buffer
    \param[out] pEdidStatus Pointer to status value E_EDID_READ or E_EDID_ERROR
                            valid only when the return value is TM_OK

    \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       NA

    \sa         tmbslHdmiTxEdidGetVideoPreferred, 
                tmbslHdmiTxEdidGetVideoCapabilities
 */
tmErrorCode_t
tmbslHdmiTxEdidGetBlockData
(
    tmUnitSelect_t          txUnit,
    UInt8                   *pRawEdid, 
    Int                     numBlocks,
    Int                     lenRawEdid,
    UInt8                   *pEdidStatus
);

/*============================================================================*/
/**
 * tmbslHdmiTxEdidGetSinkType() parameter types
 */
/** Sink device type */
typedef enum
{
    HDMITX_SINK_DVI                = 0,    /**< DVI  */
    HDMITX_SINK_HDMI               = 1,    /**< HDMI */
    HDMITX_SINK_EDID               = 2,    /**< As currently defined in EDID */
    HDMITX_SINK_INVALID            = 3     /**< Invalid   */
} tmbslHdmiTxSinkType_t;

/**
    \brief      Get Sink Type by analysis of EDID content

    \param[in]  txUnit      Transmitter unit number
    \param[out] pSinkType   Pointer to returned Sink Type: DVI or HDMI

    \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
    
    \sa         tmbslHdmiTxEdidGetBlockData
 */
tmErrorCode_t
tmbslHdmiTxEdidGetSinkType
(
    tmUnitSelect_t              txUnit,
    tmbslHdmiTxSinkType_t      *pSinkType 
);

/*============================================================================*/
/**
    \brief      Get Source Physical Address by analysis of EDID content

    \param[in]  txUnit          Transmitter unit number
    \param[out] pSourceAddress  Pointer to returned Source Physical Address (ABCDh)

    \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
    
    \sa         tmbslHdmiTxEdidGetBlockData
 */
tmErrorCode_t
tmbslHdmiTxEdidGetSourceAddress
(
    tmUnitSelect_t  txUnit,
    UInt16          *pSourceAddress 
);

/*============================================================================*/
/**
 *  tmbslHdmiTxEdidGetVideoCapabilities() parameter types
 */
/** Number of 1 byte Short Video Descriptors stored in pEdidVFmts */
#define HDMI_TX_SVD_MAX_CNT     30

/** Flag set in Short Video Descriptor to indicate native format */
#define HDMI_TX_SVD_NATIVE_MASK 0x80
#define HDMI_TX_SVD_NATIVE_NOT  0x7F

/** Video capability flags */
enum _tmbslHdmiTxVidCap_t
{
    HDMITX_VIDCAP_UNDERSCAN   = 0x80,   /**< Underscan supported */
    HDMITX_VIDCAP_YUV444      = 0x40,   /**< YCbCr 4:4:4 supported */
    HDMITX_VIDCAP_YUV422      = 0x20,   /**< YCbCr 4:2:2 supported */
    HDMITX_VIDCAP_UNUSED      = 0x1F    /**< Unused flags */
};

/**
    \brief      Get supported video format(s) from previously read EDID

    \param[in]  txUnit      Transmitter unit number
    \param[out] pEdidVFmts  Pointer to the array to receive the supported Short
                            Video Descriptors