/*
  ddc_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.
  DDC is found from interface storage with bus name DISP_BUS_DDC.</p>
  <p></p>

*/
/** @file

Declaration of TV chipset driver API

@publishedDeviceAbstraction
*/

#ifndef DDC_CHIPSET_API_H
#define DDC_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 ------------------------------------------------------------*/

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

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

/** One DDC segment size. See that EDID block size is just 128 bytes,
    so base-EDID read might contain one EDID extension */
const uint32 KSegmentSize = 256;

/** One data block */
typedef uint8 DISPA_DDC_DATA_BLOCK[ KSegmentSize ];

/** API version number. @see dispDdcApiVersion().
    1:  First version */
const uint32 KApiDdcVersionNumber = 1;

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

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

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

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

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

/* VERSION -> */

/** Gets implemented chipset API version. Verify the return value to KApiDdcVersionNumber.
    @param  api  API interface pointer, fetched from dispGetInterface()
    @see KApiDdcVersionNumber
    @return Implemented Tv chipset API version, KApiDdcVersionNumber (should match to client version) */
inline uint32 dispDdcApiVersion(API_POINTER api);

/* <- VERSION */


/* ACCESS -> */

/** Starts DDC read from wanted port.

    Method reads one DISPA_DDC_DATA_BLOCK, and it size is double of one EDID block,
    so the first EDID read might get base-EDID and first extension, if exists.
    With variable size of DisplayID, method reads anyway whole size of DISPA_DDC_DATA_BLOCK,
    even DisplayID section is smaller.

    @param  api               API interface pointer, fetched from dispGetInterface()
    @param  ddcPortAddress    DDC port which needs to be read
    @param  blockNumber       Datablock which needs to be read (parameter maps to segment-register 0x60)
    @param  dataBlock         Method fills this with read values. Ensure that this data exists all the time,
                              be careful if local variable.
    @param  callbackWhenRead  Will be called when ready, if no errors, then aDataBlock contains read values.
                              Call with NULL-callback cancels all read operations
                              (and ddc-driver calls pending callbacks).
    @return an error code */
inline DISPE_ERROR dispDdcRead(API_POINTER api, uint8 ddcPortAddress, uint32 blockNumber, DISPA_DDC_DATA_BLOCK* dataBlock, DISPT_READY_CB callbackWhenRead);

/* <- ACCESS */

/*- Inline Functions --------------------------------------------------------*/

#include "ddc_chipset_api.inl"

#endif /* DDC_CHIPSET_API_H */

/* End of File */