/*

  tv_chipset_api.h

  Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). 

  All rights reserved.

  This program and the accompanying materials are made available 

  under the terms of the Eclipse Public License v1.0 which accompanies 

  this distribution, and is available at 

  http://www.eclipse.org/legal/epl-v10.html

  Initial Contributors:

  Nokia Corporation - initial contribution.

  Contributors:

*/

/**

  @mainpage

  @section intro_sec Introduction

  <p>This is the tv chipset driver API document.</p>

  <p>This API hides HW differencies from display (and other users) driver.

  API is not kept as binary compatible.</p>

  <p>Get API pointer:

  API pointer (API_POINTER) will be found from Interface Storage.

  CVBS is found with bus name DISP_BUS_CVBS and HDMI with DISP_BUS_HDMI</p>

  <p></p>

*/

/** @file

Declaration of TV chipset driver API

@publishedDeviceAbstraction

*/

#ifndef TV_CHIPSET_API_H

#define TV_CHIPSET_API_H

/*- Include Files  ----------------------------------------------------------*/

#include "display_chipset_os.h"  /* OS specific header file, typedef etc. */

#include "display_chipset_api.h" /* Fetch enumeration etc */

/*- Namespace ---------------------------------------------------------------*/

/*- Enumerations ------------------------------------------------------------*/

/** Pixel repetation bit masks for TSupportedHdmiDviMode::pixelRepeatBitMask */

const uint32 KPixelRepeatOnce    = 0;         /**< No repetation, pixel sent once */

const uint32 KPixelRepeat2Times  = ( 1 << 0 );

const uint32 KPixelRepeat3Times  = ( 1 << 1 );

const uint32 KPixelRepeat4Times  = ( 1 << 2 );

const uint32 KPixelRepeat5Times  = ( 1 << 3 );

const uint32 KPixelRepeat6Times  = ( 1 << 4 );

const uint32 KPixelRepeat7Times  = ( 1 << 5 );

const uint32 KPixelRepeat8Times  = ( 1 << 6 );

const uint32 KPixelRepeat9Times  = ( 1 << 7 );

const uint32 KPixelRepeat10Times = ( 1 << 8 );

typedef enum

    {

    /** CEA mode, TCeaFixedMode */

    DISP_CEA = 0x00,

    /** Dmt mode, TDmtFixedMode */

    DISP_DMT = 0x01,

    } DISPE_STANDARD_MODE_TYPE;

/** Television broadcast standard */

typedef enum

    {

    DISP_UNDEF_SYSTEM = 0x0, /**< Invalid */

    DISP_NTSCJ        = 0x1,

    DISP_NTSCM        = 0x2,

    DISP_NTSC443      = 0x3,

    DISP_SECAM        = 0x4,

    DISP_PAL60        = 0x5,

    DISP_PALB         = 0x6,

    DISP_PALD         = 0x7,

    DISP_PALG         = 0x8,

    DISP_PALH         = 0x9,

    DISP_PALI         = 0xA,

    DISP_PALM         = 0xB,

    DISP_PALN         = 0xC,

    DISP_PALNC        = 0xD,

    } DISPE_TV_STANDARD;

/** HDMI/DVI source type */

typedef enum

    {

    DISP_SRC_TYPE_UNKN       = 0x00, /**< Invalid */

    DISP_SRC_TYPE_DIG_STB    = 0x01,

    DISP_SRC_TYPE_DVD        = 0x02,

    DISP_SRC_TYPE_DVHS       = 0x03,

    DISP_SRC_TYPE_HDD_VIDEO  = 0x04,

    DISP_SRC_TYPE_DVC        = 0x05,

    DISP_SRC_TYPE_DSC        = 0x06,

    DISP_SRC_TYPE_VIDEO_CD   = 0x07,

    DISP_SRC_TYPE_GAME       = 0x08,

    DISP_SRC_TYPE_PC_GENERAL = 0x09,

    } DISPE_HDMI_SOURCE_TYPE;

/** Analog Protection System (APS) levels */

typedef enum

    {

    DISP_ANALOG_PROTECTION_OFF     = 0,         /**< APS off */

    DISP_ANALOG_PROTECTION_AGC     = ( 1 << 0 ),/**< Automatic Gain Control */

    DISP_ANALOG_PROTECTION_AGC_2CS = ( 1 << 1 ),/**< Automatic Gain Control + 2-line Color Stripe */

    DISP_ANALOG_PROTECTION_AGC_4CS = ( 1 << 2 ),/**< Automatic Gain Control + 4-line Color Stripe */

    } DISPE_ANALOG_PROTECTION_LEVELS;

/** Copy Generation Management System - Analog (CGMS-A) levels.

    In conflict case, highest bit value will be taken in use.

    @see DISPE_CGMSA_CAPABILITIES */

typedef enum

    {

    DISP_CGMSA_COPY_FREELY  = 0x0,/**< Copying is allowed without restrictions */

    DISP_CGMSA_COPY_NO_MORE = 0x1,/**< Condition not to be used */

    DISP_CGMSA_COPY_ONCE    = 0x2,/**< One generation of copies is allowed */

    DISP_CGMSA_COPY_NEVER   = 0x3,/**< No copying is allowed */

    } DISPE_CGMSA_LEVELS;

/** Copy Generation Management System - Analog (CGMS-A) capabilities

    @see DISPE_CGMSA_LEVELS */

typedef enum

    {

    DISP_CGMSA_IEC_61880       = ( 1 << 0 ),/**< IEC 61880 */

    DISP_CGMSA_ETSI_EN_300_294 = ( 1 << 1 ),/**< ETSI EN 300 294 */

    DISP_CGMSA_CEA_608         = ( 1 << 2 ),/**< CEA 608 B */

    } DISPE_CGMSA_CAPABILITIES;

/** Type of executed selftest */

typedef enum

    {

    DISP_CONTROLLER = 0x0, /**< Tests tv controller hw (inside source device), e.g. host<->controller busses. */

    DISP_CONNECTOR  = 0x1, /**< Tests tv output connector, e.g. source<->HDMI-Tv */

    } DISPE_SELFTEST_TYPE;

/*- Data Structs ------------------------------------------------------------*/

/* CONTROL ->>>>>> */

/**

Current tv-out mode resolutions and aspect ratios

*/

typedef struct

    {

    /** Number of rows of frame (full rows) */

    uint32 linesPerFrame;

    /** Number of rows of field, interlaced. Same as linesPerFrame if progressive */

    uint32 linesPerField;

    /** Number of columns of frame */

    uint32 columns;

    /** Pixel aspect ratio = pixelAspectNumerator/pixelAspectDenominator */

    uint32 pixelAspectNumerator;

    /** @see pixelAspectNumerator */

    uint32 pixelAspectDenominator;

    } DISPS_TV_RESOLUTION;

/** The maximum length for the product name on TMDS bus */

const uint32 KProductNameSize = 8;

/** The maximum length for the product description on TMDS bus */

const uint32 KProductDescriptorsSize = 16;

/**

HDMI/DVI timings and settings. See detailed values of standard formats from OutputModes_X.xls

*/

typedef struct

    {

    /** @see ceaModeSetInsteadOfDmtMode. This is 0 if no any fixed modes set. */

    uint32 fixedMode;

    /** True=fixedMode is CEA mode. False=fixedMode is DMT mode. @see fixedMode */

    uint32 ceaModeSetInsteadOfDmtMode;

    /** True when HDCP is enabled on source output. False when HDCP disabled. @see dispCopyProtectionStatus()*/

    bool8 enableHdcp;

    /** Tv physical size in millimetres. Can be 0 if tvPhysicalImageAspectRatioNumerator is used. */

    uint32 tvPhysicalImageWidthMm;

    /** @see tvPhysicalImageWidthMm */

    uint32 tvPhysicalImageHeightMm;

    /** Tv physical aspect ratio. Can be NULL if tvPhysicalImageWidthMm is defined. Read from EDID.

        AR=tvPhysicalImageAspectRatioNumerator/tvPhysicalImageAspectRatioDenominator */

    uint16 tvPhysicalImageAspectRatioNumerator;

    /** @see tvPhysicalImageAspectRatioNumerator */

    uint16 tvPhysicalImageAspectRatioDenominator;

    /** Pixel clock. With CEA mode 1 and 59.94Hz this is 25175KHz */

    uint32 pixelClockKHz;

    /** Horizontal image width (resolution, columns).

        With CEA mode 1 this is 640 */

    uint16 horizontalActivePixels;

    /** Horizontal blanking time in pixels. Total HTime=horizontalActivePixels+horizontalBlankingPixels.

        With CEA mode 1 this is 160. Presented always as in CEA-model. */

    uint16 horizontalBlankingPixels;

    /** Vertical image height (resolution, lines). With CEA mode 1 this is 480 */

    uint16 verticalActiveLines;

    /** Vertical blanking time in lines. Total VTime=verticalActiveLines+verticalBlankingLines.

        With CEA mode 1 this is 45 */

    uint16 verticalBlankingLines;

    /** Horizontal pulse frontporch in pixels. With CEA mode 1 this is 16 */

    uint16 horizontalSyncOffsetPixels;

    /** Horizontal pulse duration in pixels. With CEA mode 1 this is 96 */

    uint16 horizontalSyncPulseWidthPixels;

    /** Horizontal border (decreases addressable area). With CEA mode 1 this is 0. */

    uint16 horizontalBorderPixels;

    /** Vertical pulse frontporch in lines. Fixed point with 10x, 1=10. 1.5=15.

        With CEA mode 1 this is 100 (actual value = 10).

        Presented always as CEA-model handle porches. For example E1024x768i87HzRB this is 00 */

    uint16 verticalSyncOffsetLinesField1;

    /** Vertical pulse duration in lines. With CEA mode 1 this is 2.

        With E1024x768i87HzRB this is 4. */

    uint16 verticalSyncPulseWidthLinesField1;

    /** Vertical border (decreases addressable area). With CEA mode 1 this is 0. */

    uint16 verticalBorderLinesField1;

    /** @see verticalSyncOffsetLinesField1. With progressive mode, this is unused.

        With E1024x768i87HzRB this is 10 (value 1). */

    uint16 verticalSyncOffsetLinesField2;

    /** @see verticalSyncPulseWidthLinesField1. With progressive mode, this is unused.

        With E1024x768i87HzRB this is 4. */

    uint16 verticalSyncPulseWidthLinesField2;

    /** @see verticalBorderLinesField1. With progressive mode, this is unused. */

    uint16 verticalBorderLinesField2;

    /** Left border (decreases addressable area). With CEA mode 1 this is 0. */

    uint16 leftBorderPixels;

    /** Right border (decreases addressable area). With CEA mode 1 this is 0. */

    uint16 rightBorderPixels;

    /** Horizontal sync polarity, false=Negative, true=Positive.

        With CEA mode 1 this is false. */

    bool8 horizontalSyncPolarity;

    /** Vertical sync polarity, false=Negative, true=Positive.

        With CEA mode 1 this is false. */

    bool8 verticalSyncPolarity;

    /** Wanted pixel repeat, can be used if mode supports.

        Otherwise horisontal resolution can be increased also.

        0 when repeat is disabled. With CEA mode 1 this is 0. */

    uint8 pixelRepeat;

    /** True if overscan is enabled (if Tv supports underscan). False otherwise */

    bool8 underscanEnabled;

    /** Pixel aspect ratio (PAR) numerator. PAR=pixelAspectRatioNumerator/pixelAspectRatioDenominator.

        With CEA mode 1 PAR=1/1. */

    uint8 pixelAspectRatioNumerator;

    /** @see pixelAspectRatioNumerator */

    uint8 pixelAspectRatioDenominator;

    /** True=HDMI, False=DVI. */

    bool8 hdmiConnector;

    /** Tv color coordinates (read from EDID) */

    DISPS_COLOR_COORDINATES tvColorCoordinates;

    /** HDMI version what Tv supports. Version combination is tvHdmiVersion.tvHdmiRevision.

        Zeroes if DVI. */

    uint8 tvHdmiVersion;

    /** @see tvHdmiVersion */

    uint8 tvHdmiRevision;

    /** Product name which to be sent to Tv in "Source Product Infoframe".

        Cell 0 contains first letter. All unused characters should be Null. */

    uint8 productName[ KProductNameSize ];

    /** Product Description which to be sent to Tv in "Source Product Infoframe".

        Cell 0 contains first letter. All unused characters should be Null. */

    uint8 productDescription[ KProductDescriptorsSize ];

    /** Source type which to be sent to Tv in "Source Product Infoframe". */

    DISPE_HDMI_SOURCE_TYPE sourceType;

    } DISPS_HDMI_SETTINGS;

/**

Configure object for analogue TV-Out, such as CVBS

*/

typedef struct

    {

    /** Analogue signal type */

    DISPE_TV_STANDARD tvSystem;

    /** Set analog protection system */

    DISPE_ANALOG_PROTECTION_LEVELS analogProtection;

    /** Set CGMS-A level */

    DISPE_CGMSA_LEVELS cgmsaLevel;

    } DISPS_ANALOGUE_SETTINGS;

/**

Configure object for TV-Out. Has all common between CVBS and HDMI and connector specific structs.

@code

__________________________ __________________________

|                        | |                        |

|   DISPS_HDMI_SETTINGS  | |DISPS_ANALOGUE_SETTINGS |

|                        | |                        |

¯¯¯¯¯¯¯¯¯¯¯¯|¯¯¯¯¯¯¯¯¯¯¯¯¯ ¯¯¯¯¯¯¯¯¯¯¯¯|¯¯¯¯¯¯¯¯¯¯¯¯¯

            `--------------------------´

             ____________|_____________

             |                        |

             |DISPS_TV_CONFIG_SETTINGS|

             |                        |

             ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

@endcode

*/

typedef struct

    {

    /** True=Interlaced scanning, False=Progressive scanning. */

    bool8 interlaced;

    /** Tv aspect ratio = imageRatioNumerator/imageRatioDenominator */

    uint8 imageRatioNumerator;

    /** @see imageRatioNumerator */

    uint8 imageRatioDenominator;

    /** True=flicker filter is enabled. False=disabled */

    bool8 flickerFilter;

    /** True=autodetect. False=cable is detected outside of this driver.

        Even True is set, Tv-out will not be enabled automatically, just cable detected. */

    bool8 autoDetection;

    /** Overscan in pixels. Set Left Top corner point. Zero when Tv supports overscan (0=underscan enabled)

        This should be "point" to active image area. Cannot point out of active image area.

        Cannot across with rightBottomCorner. And this allows overscan and position tuning. */

    uint16 leftTopCornerX;

    uint16 leftTopCornerY;

    /** Overscan in pixels. Set Right Bottom corner point. @see leftTopCornerX

        If driver supports centralizing only, then this has to be same as leftTopCornerX. */

    uint16 rightBottomCornerX;

    uint16 rightBottomCornerY;

    /** Settings for HDMI, used when DISPS_TV_CAPABILITIES::hdmiSettingsNeeded is true */

    DISPS_HDMI_SETTINGS hdmiSettings;

    /** Settings for analog Tv, used when DISPS_TV_CAPABILITIES::hdmiSettingsNeeded is false */

    DISPS_ANALOGUE_SETTINGS analogueSettings;

    /** Parameter which will be given in callbacks (DISPT_READY_CB). This-pointer for example. */

    void* cbParameter;

    /** Tv updating method. True when dispTvFlush() is used,

        False when Tv gets updating with other method (platform) */

    bool8 setBufferForTvInUsed;

    } DISPS_TV_CONFIG_SETTINGS;

/* <<<<<<- CONTROL */

/* CAPABILITY ->>>>>> */

/**

One mode struct for making capability query of own HW (phone capabilities).

*/

typedef struct

    {

    /** Standard CEA or DMT mode number. @see standardModeType */

    uint8 standardMode;

    /** Type of DISPE_STANDARD_MODE_TYPE. DISP_CEA if standardMode is CEA mode, DISP_DMT when DMT mode. */

    uint8 standardModeType;

    /** @see lowerRefreshRateSupported. If this is True (1), then higher frequency is supported. */

    bool8 higherRefreshRateSupported;

    /** If mode has two refresh rates. If is True (1), then lower frequency is supported.

        If mode has only one refresh rate, then this has to be True (1).

        E.g. CEA mode 1: 640x480p @59.94/60Hz, so this defines is 59.94Hz supported (lower) or not.

        Don't care if mode has only one refresh rate (e.g. CEA 17 720x576p @50Hz)

        lowerRefreshRateSupported  = 1 = Lower refresrate supported (e.g. 59.94Hz).

        higherRefreshRateSupported = 1 = Higher refreshrate supported (e.g. 60Hz) */

    bool8 lowerRefreshRateSupported;

    /** Bit mask of supported pixel repetation. 0=no repetation=KPixelSentOnce. */

    uint16 pixelRepeatBitMask;

    } DISPS_SUPPORTED_HDMI_MODE;

/**

Struct for own TV HW capabilities query.

*/

typedef struct

    {

    /** Own source HW supports HDCP (or compatible) */

    bool8 hdcpSupported;

    /** Own source HW supported APS levels. (bit mask) */

    DISPE_ANALOG_PROTECTION_LEVELS analogProtectionLevels;

    /** Supported CGMS-A WSS bits */

    DISPE_CGMSA_CAPABILITIES supportedCgmsa;

    /** Number of supported modes what to be called with dispGetSupportedHdmiMode */

    uint8 numberOfHdmiModes;

    /** HDMI version what (own) Hw supports. Version combination is sourceHdmiVersion.sourceHdmiRevision. */

    uint8 sourceHdmiVersion;

    /** @see sourceHdmiVersion */

    uint8 sourceHdmiRevision;

    /** True when DISPS_TV_CONFIG_SETTINGS::hdmiSettings is needed to be filled */

    bool8 hdmiSettingsNeeded;

    /** True when dispSetHdcpKey-call is needed. @see dispSetHdcpKey */

    bool8 hdcpKeysNeeded;

    /* CONTENT UPDATE -> */

    /** This tells to tv-out-driver client, is the sent buffer free after DISPT_READY_CB

        or is that buffer that buffer where tv-out gets updating all the time. Normally

        if tv-out-hw is external, and tv-buffer will be sent over some bus, this method returns

        False. Otherwise, when DMA reads all the time given buffer, and tv-out gets refresh

        directly from that buffer, then this returns True. */

    bool8 requiresFrameBuffer;

    /** This is true when pixel data to be updated with dispTvFlush().

        If this is false, then Tv-out HW can transfer/refresh Tv-out signal itself,

        without dispTvFlush() */

    bool8 contentUpdateNeeded;

    /** How many backbuffers Tv-out driver has. 0 when none */

    uint8 numberOfBackBuffers;

    /** Minimum scaling factor. E.g. if 1/2x is min, then this is 200 (100 / scalingMinDenominator). 1x = 100. 0xFFFF = infinity */

    uint16 scalingMinDenominator;

    /** Maximum scaling factor. E.g. if 2.5x is max, then this is 250 (scalingMaxNumerator / 100). 1x = 100. 0xFFFF = infinity */

    uint16 scalingMaxNumerator;

    /** True when position of Tv-out cannot be change, image is always centralized.

        False when position can be changed. @see rightBottomCorner */

    bool8 centralizingOnly;

    /** Supported color space conversions from sRGB to DISPE_COLOR_SPACE (bit mask) */

    DISPE_COLOR_SPACE supportedColorSpaceConversion;

    /** True when brightness tuning is supported */

    bool8 supportsBrightnessControl;

    /** True when contrast tuning is supported */

    bool8 supportsContrastControl;

    /** True when gamma tuning is supported */

    bool8 supportsGammaControl;

    /** True when (at least one layer) dithering is supported */

    bool8 supportsDithering;

    /** Rotation represents supported rotation capablities of HW. */

    DISPE_ROTATION rotations;

    /** True if HW can rotate each layer separately. False if only whole view can be rotated.

        (Hopefully will not be needed in NGA) */

    bool8 separateRotationPerLayer;

    /** All the possible colorkey modes supported by the interface */

    DISPE_COLORKEYMODE colorKeyModes;

    /** How many layers supported, at least 1 */

    uint8 layers;

    /** True when per layer alpha supported */

    bool8 perLayerAlpha;

    /** Color buffer formats natively supported by HW */

    DISPE_COLOR_FORMAT pixelFormats;

    /** Bit mask for features, which works with 24bpp aligned color mode */

    DISPE_FEATURE packedPixelsSupported;

    /** True if DMA buffers must be physically linear */

    bool8 requiresPhysicallyLinearBuffer;

    } DISPS_TV_CAPABILITIES;

/* <<<<<<- CAPABILITY */

/* TESTS ->>>>>> */

/**

Struct for output signal test

*/

typedef struct

    {

    /** Output color in RGB888 format */

    uint32 outColorRgb888;

    /** True when amplifier is disabled even Tv-out is ON */

    bool8 amplifierDisabled;

    } DISPS_TV_OUT_TEST_COLOR;

/* <<<<<<- TESTS */

/*- Constants ---------------------------------------------------------------*/

/** API version number. @see dispTvApiVersion().

    2:  Aspect ratio with enum/denom. SRM + HDCP structs and hdcpKeysNeeded.

    1:  First version */

const uint32 KTvApiVersionNumber = 2;

/** Chipset driver calls this, when something is executed.

    Callback must not be called in the API user thread context.

    @param  error       An error code

    @param  parameter   Given parameter (@see DISPS_TV_CONFIG_SETTINGS::cbParameter)

    @param  status      Listener status

    @param  isrContext  True when callback is called in interrupt context */

typedef void (*DISPF_LISTENER_CB)(DISPE_ERROR error, void* parameter, uint32 status, bool8 isrContext);

/*- Macros ------------------------------------------------------------------*/

/*- External Data -----------------------------------------------------------*/

/*- Variables ---------------------------------------------------------------*/

/*- Forward Declarations ----------------------------------------------------*/

/*- Functional Prototypes ---------------------------------------------------*/

/* VERSION -> */

/** Gets implemented chipset API version. Verify the return value to KTvApiVersionNumber.

    @param  api  API interface pointer, fetched from dispGetInterface()

    @see KTvApiVersionNumber

    @return Implemented Tv chipset API version, KTvApiVersionNumber (should match to client version) */

inline uint32 dispTvApiVersion(API_POINTER api);

/* <- VERSION */

/* CAPABILITY -> */

/** Returns Tv-out HW capabilities for caller.

    @param  api             API interface pointer, fetched from dispGetInterface()

    @param  tvCapabilities  Capability struct filled for caller

    @return an error code */

inline DISPE_ERROR dispGetTvCapabilities(API_POINTER api, DISPS_TV_CAPABILITIES* tvCapabilities);

/** Reads supported modes of HDMI hardware

    @see DISPS_TV_CAPABILITIES::numberOfHdmiModes

    @param  api               API interface pointer, fetched from dispGetInterface()

    @param  capabilityNumber  Mode number, begins from 0, up to dispGetTvCapabilities.

    @param  readMode          Method fills these for caller

    @return an error code */

inline DISPE_ERROR dispGetSupportedHdmiMode(API_POINTER api, uint32 capabilityNumber, DISPS_SUPPORTED_HDMI_MODE* readMode);

/* <- CAPABILITY */

/* CONTROL -> */

/** Before Tv-out using, dispSetTvConfig() must be called during boot and always

    when user is changed configurations.

    Fill correct values to DISPS_TV_CONFIG_SETTINGS object and give it by parameter.

    If driver can set settings without dispDisableTvOut()/dispEnableTvOut() it does that.