/*
 * Copyright 2010 Trident Microsystems (Far East) Ltd. All rights reserved.
 * All prior copyright rights in this work and the accompanying software
 * products transferred to Trident Microsystems (Far East) Ltd. by written
 * agreement.
 */
/*****************************************************************************/
/* Copyright (c) 2010 NXP B.V.  All rights are reserved.                     */
/*                                                                           */
/* Redistribution and use in source and binary forms, with or without        */
/* modification, are permitted provided that the following conditions        */
/* are met:                                                                  */
/*                                                                           */
/* Redistributions of source code must retain the above copyright            */
/* notice, this list of conditions and the following disclaimer.             */
/*                                                                           */
/* Redistributions in binary form must reproduce the above copyright         */
/* notice, this list of conditions and the following disclaimer in the       */
/* documentation and/or other materials provided with the distribution.      */
/*                                                                           */
/* Neither the name of NXP nor the names of its                              */
/* contributors may be used to endorse or promote products derived from      */
/* this software without specific prior written permission.                  */
/*                                                                           */
/* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS       */
/* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT         */
/* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR     */
/* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT      */
/* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,     */
/* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT          */
/* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,     */
/* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY     */
/* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT       */
/* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE         */
/* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH          */
/* DAMAGE.                                                                   */
/*                                                                           */
/*****************************************************************************/
/**
 * \file          tmdlPio.h
 *
 * \version       7.12
 *
 * \date          %date_modified%
 *
 * \brief         This is the Pio Device Library header file. Pio device
 *                library structures, defines, and function prototypes are
 *                defined here.
 *
 * REFERENCE DOCUMENTS :
 *                DVP Device Library Architecture
 *                YODA devLib specification Rev 5.0
 *                DVP Operating System Abstraction Library (OSAL) specification
 *                SRS Devlib tmdclPio
 *                SDD DevLib tmdlPio
 *
 * Detailled description may be added here.
 *
 * \section info None
 *
 * \verbatim
   Date          Modified by CRPRNr  TASKNr  Maintenance description
   -------------|-----------|-------|-------|-----------------------------------
   <10-Nov-2002>|D. Boulet  |
   <23-May-2005>|M. Lajon   |2992   |6223   |differentiate PNX831x/PNX833x Pio
   <12-Jul-2006>|F. Triboix |       |566    |Added support for PNX8335
   <31-Oct-2006>|J. Scully  |       |858    |Add RC5
   <15-Nov-2006>|J. Scully  |       |1067   |Fixes for Task 858
   <23-Nov-2006>|M.Neill    |       |1122   |Fix type in tmdlPioCapabilities_t
   <20-Jan-2009>|batelaan   |       |       |Update file copyright/license text
   \endverbatim
 *
*/

#ifndef _TMDL_PIO_H_
#define _TMDL_PIO_H_
/*============================================================================*/
/*                       INCLUDE FILES                                        */
/*============================================================================*/

#ifdef __cplusplus
extern "C"
{
#endif

#include <tmHalDefs.h>

/*============================================================================*/
/*                       MACRO DEFINITION                                     */
/*============================================================================*/

/* Error codes */
/******************************************************************************/
/* Name       : TMDL_ERR_PIO_BASE                                              */
/**Description: based standard error mask for PIO component                    */
/*=============================================================================*/
#define TMDL_ERR_PIO_BASE (CID_COMP_GPIO | CID_LAYER_DEVLIB)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_COMP                                              */
/**Description: based specific error mask for PIO component                    */
/*=============================================================================*/
#define TMDL_ERR_PIO_COMP (CID_COMP_GPIO|CID_LAYER_DEVLIB|TM_ERR_COMP_UNIQUE_START)

/* Standard error */
/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_COMPATIBILITY                                     */
/**Description: HWAPI and DEVLIB are not compatible                            */
/*=============================================================================*/
#define TMDL_ERR_PIO_COMPATIBILITY   (TMDL_ERR_PIO_BASE+TM_ERR_COMPATIBILITY)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_MAJOR_VERSION                                     */
/**Description: SW Major Version error                                         */
/*=============================================================================*/
#define TMDL_ERR_PIO_MAJOR_VERSION   (TMDL_ERR_PIO_BASE+TM_ERR_MAJOR_VERSION)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_BAD_INSTANCE                                      */
/**Description:  Bad input instance value                                      */
/*=============================================================================*/
#define TMDL_ERR_PIO_BAD_INSTANCE    (TMDL_ERR_PIO_BASE+TM_ERR_BAD_INSTANCE)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_BAD_UNIT_NUM                                      */
/**Description: Invalid device unit number                                     */
/*=============================================================================*/
#define TMDL_ERR_PIO_BAD_UNIT_NUM    (TMDL_ERR_PIO_BASE+TM_ERR_BAD_UNIT_NUMBER)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_BAD_PARAMETER                                     */
/**Description: Invalid input parameter                                        */
/*=============================================================================*/
#define TMDL_ERR_PIO_BAD_PARAMETER   (TMDL_ERR_PIO_BASE+TM_ERR_BAD_PARAMETER)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_NO_RESOURCES                                      */
/**Description: Resource is not available                                      */
/*=============================================================================*/
#define TMDL_ERR_PIO_NO_RESOURCES    (TMDL_ERR_PIO_BASE+TM_ERR_NO_RESOURCES)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_NOT_SUPPORTED                                     */
/**Description: Function is not supported                                      */
/*=============================================================================*/
#define TMDL_ERR_PIO_NOT_SUPPORTED   (TMDL_ERR_PIO_BASE+TM_ERR_NOT_SUPPORTED)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_NULL_PARAMETER                                    */
/**Description: pointer parameter is NULL                                      */
/*=============================================================================*/
#define TMDL_ERR_PIO_NULL_PARAMETER    (TMDL_ERR_PIO_BASE+TM_ERR_NULL_PARAMETER)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_INVALID_COMMAND                                   */
/**Description: Invalid command/request                                        */
/*=============================================================================*/
#define TMDL_ERR_PIO_INVALID_COMMAND (TMDL_ERR_PIO_BASE+TM_ERR_INVALID_COMMAND)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_NO_INSTANCES                                      */
/**Description: No instances available                                         */
/*=============================================================================*/
#define TMDL_ERR_PIO_NO_INSTANCES    (TMDL_ERR_PIO_BASE+TM_ERR_NO_INSTANCES)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_BAD_MODULE_ID                                     */
/**Description: SW - HW module ID error                                        */
/*=============================================================================*/
#define TMDL_ERR_PIO_BAD_MODULE_ID (TMDL_ERR_PIO_BASE+TM_ERR_BAD_MODULE_ID)

/*=============================================================================*/
/* Name       : TMDL_ERR_PIO_BAD_MODULE_ID                                     */
/**Description: Instance is already in use                                     */
/*=============================================================================*/
#define TMDL_ERR_PIO_INSTANCE_IN_USE (TMDL_ERR_PIO_BASE+TM_ERR_INSTANCE_IN_USE)

/*=============================================================================*/
/* Name       : DATA_NOT_INITIALIZED                                           */
/**Description: Instance Setup has not be done                                 */
/*=============================================================================*/
#define DATA_NOT_INITIALIZED (TMDL_ERR_PIO_BASE+TM_ERR_NOT_INITIALIZED)

/*=============================================================================*/
/* Name       : TMDL_PIO_SUPPORTED_INSTANCES                                   */
/**Description: Number instance is unlimited                                   */
/*=============================================================================*/
#define TMDL_PIO_SUPPORTED_INSTANCES    -1

/* PIO events*/
/*=============================================================================*/
/* Name       : TMDL_PIO_NO_EVENT                                              */
/**Description: no pin selected                                                */
/*=============================================================================*/
#define TMDL_PIO_NO_EVENT           0x0000

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN0_EVENT                                            */
/**Description: event occured or is selected on pin 0                          */
/*=============================================================================*/
#define TMDL_PIO_PIN0_EVENT         0x0001

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN1_EVENT                                            */
/**Description: event occured or is selected on pin 1                          */
/*=============================================================================*/
#define TMDL_PIO_PIN1_EVENT         0x0002

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN2_EVENT                                            */
/**Description: event occured or is selected on pin 2                          */
/*=============================================================================*/
#define TMDL_PIO_PIN2_EVENT         0x0004

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN3_EVENT                                            */
/**Description: event occured or is selected on pin 3                          */
/*=============================================================================*/
#define TMDL_PIO_PIN3_EVENT         0x0008

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN4_EVENT                                            */
/**Description: event occured or is selected on pin 4                          */
/*=============================================================================*/
#define TMDL_PIO_PIN4_EVENT         0x0010

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN5_EVENT                                            */
/**Description: event occured or is selected on pin 5                          */
/*=============================================================================*/
#define TMDL_PIO_PIN5_EVENT         0x0020

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN6_EVENT                                            */
/**Description: event occured or is selected on pin 6                          */
/*=============================================================================*/
#define TMDL_PIO_PIN6_EVENT         0x0040

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN7_EVENT                                            */
/**Description: event occured or is selected on pin 7                          */
/*=============================================================================*/
#define TMDL_PIO_PIN7_EVENT         0x0080

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN8_EVENT                                            */
/**Description: event occured or is selected on pin 8                          */
/*=============================================================================*/
#define TMDL_PIO_PIN8_EVENT         0x0100

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN9_EVENT                                            */
/**Description: event occured or is selected on pin 9                          */
/*=============================================================================*/
#define TMDL_PIO_PIN9_EVENT         0x0200

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN10_EVENT                                           */
/**Description: event occured or is selected on pin 10                         */
/*=============================================================================*/
#define TMDL_PIO_PIN10_EVENT        0x0400

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN11_EVENT                                           */
/**Description: event occured or is selected on pin 11                         */
/*=============================================================================*/
#define TMDL_PIO_PIN11_EVENT        0x0800

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN12_EVENT                                           */
/**Description: event occured or is selected on pin 12                         */
/*=============================================================================*/
#define TMDL_PIO_PIN12_EVENT        0x1000

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN13_EVENT                                           */
/**Description: event occured or is selected on pin 13                         */
/*=============================================================================*/
#define TMDL_PIO_PIN13_EVENT        0x2000

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN14_EVENT                                           */
/**Description: event occured or is selected on pin 14                         */
/*=============================================================================*/
#define TMDL_PIO_PIN14_EVENT        0x4000

/*=============================================================================*/
/* Name       : TMDL_PIO_PIN15_EVENT                                           */
/**Description: event occured or is selected on pin 15                         */
/*=============================================================================*/
#define TMDL_PIO_PIN15_EVENT        0x8000

/*============================================================================*/
/*                       ENUM OR TYPE DEFINITION                              */
/*============================================================================*/

/******************************************************************************/
/**
 * \brief This type is a bitmask of pins selection. "0" means that the
 *        corresponding pin is not selected, "1" means that the corresponding
 *        pin is selected.
 *        The first pin starts at bit 0. Pins that support interrupts/debouncing
 *        start at this bit as well.
 */
/******************************************************************************/
#ifdef TMFL_IC_PNX8335
typedef unsigned long long tmdlPioLines_t, *ptmdlPioLines_t;
#else
typedef UInt32 tmdlPioLines_t, *ptmdlPioLines_t;
#endif

/******************************************************************************/
/**
 * \brief This enum describes the debouncing rate values
 *        tmdlPioDebounceRate1 to tmdlPioDebounceRate8 are for the PIO [7:0]
 *        tmdlPioDebounceRate9 to tmdlPioDebounceRate16 are for the PIO [15:8]
 *
 * \sa    tmdlPioSetDebounce, tmdlPioGetDebounce, tmdlPioSetDebounce_t
 */
/******************************************************************************/

typedef enum
{ /* Corresponding to the value in Debouncing register */
   tmdlPioDebounceRate1 = 0,/**< 1.23 ms */
   tmdlPioDebounceRate2,    /**< 2.47 ms */
   tmdlPioDebounceRate3,    /**< 4.93 ms */
   tmdlPioDebounceRate4,    /**< 9.87 ms */
   tmdlPioDebounceRate5,    /**< 19.75 ms */
   tmdlPioDebounceRate6,    /**< 39.5 ms */
   tmdlPioDebounceRate7,    /**< 79 ms */
   tmdlPioDebounceRate8,    /**< 158 ms */
   tmdlPioDebounceRate9,    /**< 3.88 us */
   tmdlPioDebounceRate10,   /**< 7.79 us */
   tmdlPioDebounceRate11,   /**< 15.53 us */
   tmdlPioDebounceRate12,   /**< 31.03 us */
   tmdlPioDebounceRate13,   /**< 62.33 us */
   tmdlPioDebounceRate14,   /**< 124.79 us */
   tmdlPioDebounceRate15,   /**< 249.61 us */
   tmdlPioDebounceRate16    /**< 499.37 us */
} tmdlPioDebounceRate_t;

/******************************************************************************/
/**
 * \brief This enum describes the interupt type
 *
 * \sa    tmdlPioSetIntType, tmdlPioGetIntType
 */
/******************************************************************************/
typedef enum
{
   tmdlPioIntTypeNoInt      = 0, /**< no interupt generated on the input pin */
   tmdlPioIntTypeLo         = 1, /**< low level interupt generated on the input pin */
   tmdlPioIntTypeHi         = 2, /**< high level interupt generated on the input pin */
   tmdlPioIntTypeFall       = 5, /**< falling edge interupt generated on the input pin */
   tmdlPioIntTypeRise       = 6, /**< rising edge interupt generated on the input pin */
   tmdlPioIntTypeRiseorFall = 7  /**< falling and rising interupt generated on the input pin */
} tmdlPioIntType_t;

/******************************************************************************/
/**
 * \brief This enum describes the pio enable/disable interrupt
 *        or debounce mode
 *
 * \sa    tmdlPioSetIntType, tmdlPioGetIntType,
 *        tmdlPioSetDebounce, tmdlPioGetDebounce
 */
/******************************************************************************/
typedef enum
{
   tmdlPioSwitchOff = 0,  /**< Pin disabled  */
   tmdlPioSwitchOn        /**< Pin enabled  */
} tmdlPioSwitch_t;

/******************************************************************************/
/**
 * \brief This enum describes the Different commands used in InstanceConfig
 *
 * \sa tmdlPioInstanceConfig
 */
/******************************************************************************/
typedef enum
{
   tmdlPioCmdSetMode = 0,  /**< process tmdlPioSetMode Specific API */
   tmdlPioCmdGetMode,      /**< process tmdlPioGetMode Specific API */
   tmdlPioCmdSetType,      /**< process tmdlPioSetType Specific API */
   tmdlPioCmdGetType,      /**< process tmdlPioGetType Specific API */
   tmdlPioCmdSetDebounce,  /**< process tmdlPioSetDebounce Specific API */
   tmdlPioCmdGetDebounce   /**< process  tmdlPioGetDebounce Specific API */
} tmdlPioIcfgCmd_t;

/******************************************************************************/
/**
 * \brief This structure is used to get the capabilities of the unit
 *
 * \sa    tmdlPioGetCapabilities
 */
/******************************************************************************/
typedef struct  _tmdlPioCapabilities_t
{
   tmSWVersion_t   version;               /** PIO DevLib software version   */
   Int32           numSupportedInstances; /** PIO instances supported count */
   tmdlPioLines_t  numLine;               /** Number of Pio pins            */
   tmdlPioLines_t  numIntLine;            /** Number of Interrupt Pio pins  */
} tmdlPioCapabilities_t, *ptmdlPioCapabilities_t;

/******************************************************************************/
/**
 * \brief This structure is used to Set the Pio Input Output bidir mode
  *       it is used in InstanceConfig
 *
 * \sa tmdlPioInstanceConfig
 */
/******************************************************************************/
typedef struct _tmdlPioSetModeMask_t
{
   tmdlPioLines_t    lineSelInput;  /**< Lines selected for Input PIO pin      */
   tmdlPioLines_t    lineSelOutput; /**< Lines selected for Output PIO pin     */
   tmdlPioLines_t    lineSelPeriph; /**< Lines selected for Peripheral PIO pin */
} tmdlPioSetModeMask_t, *ptmdlPioSetModeMask_t;

/******************************************************************************/
/**
 * \brief This structure is used to Set the debounce rate
 *        it is used in InstanceConfig
 *
 * \sa tmdlPioInstanceConfig
 */
/******************************************************************************/
typedef struct  _tmdlPioSetDebounce_t
{
   tmdlPioLines_t          lineSelect; /**< Lines selected                     */
   tmdlPioSwitch_t         onoff;      /**< enable / disable the debounce rate */
   tmdlPioDebounceRate_t   dbtime;     /**< debounce rate value                */
   UInt32                  sample;     /**< sample for [15:8] is a number
                                             between 0 and 0xFF, for [7:0] is 3*/
} tmdlPioSetDebounce_t, *ptmdlPioSetDebounce_t;


/******************************************************************************/
/**
 * \brief This structure is used to Set the Interrupt type
 *        it is used in InstanceConfig
 *
 * \sa tmdlPioInstanceConfig
 */
/******************************************************************************/
typedef struct  _tmdlPioSetIntType_t
{
   tmdlPioLines_t           lineSelect; /**< Lines selected                     */
   tmdlPioSwitch_t          onoff;      /**< enable / disable the debounce rate */
   tmdlPioIntType_t         intType;    /**< Interrupt type value               */
} tmdlPioSetIntType_t, *ptmdlPioSetIntType_t;

/******************************************************************************/
/**
 * \brief This structure is PIO Pin Instance Setup
 *
 * \sa    tmdlPioGetInstanceSetup, tmdlPioInstanceSetup
 */
/******************************************************************************/
typedef struct  _tmdlPioInstanceSetup_t
{
   tmdlPioLines_t    lineSelect; /**< Lines selected for all API */
} tmdlPioInstanceSetup_t, *ptmdlPioInstanceSetup_t;


/******************************************************************************/
/** \brief  This function describes the callback function prototype.
 *          This function pointer is passed in as a tmdlPioRegisterCallback
 *          function parameter. The function gets called when the specified PIO
 *          events enabled by tmdlPioSetEventMask occur.
 *
 *  \param  events : rised event value
 *  \param  pData : pointer to data to retrieve informations
 *  \param  userData : rised event value
 *
 *  \return None
 *
 *  \sa     tmdlPioRegisterCallback
 */
/******************************************************************************/
//typedef Void (*ptmdlCallback_t)(UInt32 events,  Void * pData, UInt32 userData);

/*============================================================================*/
/*                       EXTERN DATA DEFINITION                               */
/*============================================================================*/

/*============================================================================*/
/*                       EXTERN FUNCTION PROTOTYPES                           */
/*============================================================================*/

/******************************************************************************/
/** \brief  This function returns the number of PIO units in the system.
 *
 *  \param  pioUnitCount : (Out) the number of PIO units
 *
 *  \return The error code.
 *          - TM_OK                      : success
 *          - TMDL_ERR_PIO_BAD_UNIT_NUM : the compatibility number is not valid
 *           in case of the PIO unit was not previously initialized
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetNumberOfUnits (
    pUInt32 pioUnitCount
    );

/******************************************************************************/
/** \brief  This function returns the PIO device library software interface
 *          version. It must be called before calling any other PIO device
 *          library functions to ensure that the software interface present
 *          is the expected version. Upon successful return, if the caller
 *          detects an unexpected PIO DevLib SW version, the caller should
 *          display an error message (as appropriate) and exit without
 *          using any PIO DevLib functions..
 *
 *  \param  pioVersionInfo : (Out) the PIO instance number
 *
 *  \return The error code.
 *          - TM_OK                      : success
 *          - TMDL_ERR_PIO_COMPATIBILITY : the compatibility number is not valid
 *          - TMDL_ERR_PIO_MAJOR_VERSION : the major version is not valid
 *
 *  \note   Compatibility Number : Starts from 1. Whenever the API is not
 *          backward compatible with the previous version, then the
 *          compatibility number is incremented.
 *          Major Version Number : Starts from 1. Whenever any exported
 *          software interface change is made, whether the changes are
 *          backward compatible or not, the number is incremented. It
 *          is reset to 1 when compatibility number is changed
 *          Minor Version Number : Starts from 0. Any changes to the
 *          software module will cause this number to be incremented.
 *          This number is reset to 0 whenever compatibility number
 *          or major version number is changed.
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetSWVersion(
    ptmSWVersion_t pioVersionInfo
    );

/******************************************************************************/
/** \brief  This function returns returns the capabilities of PIO device.
 *
 *  \param  ppioCaps : (Out) the capabilities of PIO Unit 0
 *
 *  \return The error code.
 *          - TM_OK                       : success
 *          - TMHW_ERR_PIO_BAD_UNIT_NUMBER: the compatibility number is not valid
 *          - TMHW_ERR_PIO_NOT_INITIALIZED : in case of the PIO unit was not
 *                                           previously initialized
 *
 *  \note   This function returns the PIO DL interface compatibility
 *          number, major version, and minor version.  It is called to
 *          validate the PIO DL interface compatibility and version
 *          information before the interface is used.  If the caller of
 *          this function detects a mismatch with it's expected interface
 *          compatibility number or major version number, it should not
 *          use the interface as functions and/or parameters are likely
 *          to have changed (the reason for the version number changes).
 *
 *  \sa     See defintion of the structure tmdlPioCapabilities_t for more
 *          details.
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetCapabilities (
    const tmdlPioCapabilities_t (**ppioCaps)
    );

/******************************************************************************/
/**
 *  \fn     tmErrorCode_t tmdlPioOpen(tmInstance_t *pioInstance);
 *  \brief  This function opens \a the PIO unit 0 for access. If the function
 *          returns successfully, a PIO instance is returned via the PIO
 *          instance pointer. The PIO instance returned from this function
 *          will have to be passed in as a parameter in subsequent device
 *          library function calls. Use the tmdlPioClose() function to close
 *          the PIO instance and free system resources after all PIO instance
 *          accesses have been completed.
 *
 *  \param  pioInstance : (Out) the returned PIO instance
 *
 *  \return The error code.
 *          - TM_OK                       : success
 *          - TMDL_ERR_PIO_NO_INSTANCES   : can not open an instance
 *
 *  \note   Opens PIO accesses and initializes system services
 *          used by the driver
 *          The initial state will be:
 *          All PIO lines are in IO mode and configured to be input.
 *          Interrupt types and debounce modes of PIO lines 0-7 are
 *          determined by the configuration in tmdlPioCfg.h.
 *
 *  \sa     tmdlPioCfg.h.
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioOpen(
    tmInstance_t *pioInstance
    );

/******************************************************************************/
/** \brief  This function closes the specified PIO instance created by the
 *          tmdlPioOpen() function. Any active Pio software or hardware
 *          operation will be cancelled and Pio instance interrupts will
 *          be disabled. After the Pio instance is closed, the instance
 *          number is no longer valid and cannot be used for device library
 *          function calls.
 *
 *  \param  kInstance : (In) the PIO instance to close
 *
 *  \return The error code.
 *          - TM_OK                       : success
 *          - TMDL_ERR_PIO_BAD_INSTANCE   : the specified PIO unit is not valid
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioClose(
    tmInstance_t  kInstance
    );

/******************************************************************************/
/** \brief  This function retrieves the current PIO instance setup
 *          parameters. The returned structure may be used to
 *          configure the instance by changing the values in the structure
 *          and setting the structure using tmdlPioInstanceSetup() function.
 *
 *  \param  kInstance : (In)  the Pio instance to setup
 *  \param  pioSetup  : (Out) the retrived instance configuration
 *
 *  \return The error code.
 *          - TM_OK                       : success
 *          - TMDL_ERR_PIO_BAD_INSTANCE   : instance is not used
 *
 *  \note   tmdlPioOpen must have been called before.
 *
 *  \sa tmdlPioInstanceSetup_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetInstanceSetup(
    tmInstance_t            kInstance,
    ptmdlPioInstanceSetup_t *pioSetup
    );

/******************************************************************************/
/** \brief  This function sets up the PIO instance configuration. The function
 *          must be called after the tmdlPioOpen() but before any other
 *          control/configuration functions are called.
 *          This function may be called multiple times for the same
 *          instance.
 *
 *  \param  kInstance : (In) the PIO instance to setup
 *  \param  pkSetup   : (In) the instance configuration to set
 *
 *  \param  kInstance : (In) the instance memory handle of PIO Device
 *          pkSetup   : (Out) the default Instance Setup.
 *
 *  \return The error code.
 *          - TM_OK                       : success
 *          - TMDL_ERR_PIO_BAD_INSTANCE   : instance is not used
 *          - TMDL_ERR_PIO_NO_RESOURCES   : selcted pio lines are used
 *                                          in another instance
 *          - TMDL_ERR_PIO_BAD_PARAMETER  : bad pio line selected
 *
 *  \note   tmdlPioOpen must have been called before.
 *
 *  \sa tmdlPioInstanceSetup_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioInstanceSetup(
    tmInstance_t            kInstance,
    ptmdlPioInstanceSetup_t pkSetup
    );

/******************************************************************************/
/** \brief  This function configures the PIO instance based on the specific
 *          Pio configuration command and the associated data structures.
 *
 *  \param  kInstance   : (In) the instance memory handle of PIO Device
 *  \param  kIcfgCmd    : (In) the command to launch the pio specifique
 *                             functions tmdlPioIcfgCmd_t
 *  \param  pioIcfgData : (Out) structure pointer according the function to call
 *                              ptmdlPioSetModeMask_t
 *                              ptmdlPioSetIntType_t
 *                              ptmdlPioSetDebounce_t
 *
 *  \return The error code.
 *          - TM_OK                       : success
 *          - TMDL_ERR_PIO_BAD_INSTANCE   : instance is not used
 *          - TMDL_ERR_PIO_NO_RESOURCES   : selected pio lines are used
 *                                          in another instance
 *          - TMDL_ERR_PIO_BAD_PARAMETER  : bad pio line selected
 *
 *  \note   Should only be called after Open (tmdlPioOpen) and InstanceSetup
 *          (tmdlPioInstanceSetup) have been done.
 *
 *  \sa     tmdlPioIcfgCmd_t
 *          ptmdlPioSetModeMask_t
 *          ptmdlPioSetIntType_t
 *          ptmdlPioSetDebounce_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioInstanceConfig(
    tmInstance_t             kInstance,
    UInt32                   kIcfgCmd,
    pVoid                    pioIcfgData
    );

/******************************************************************************/
/** \brief  This function gets the PIO instance power state (Power On and
 *          Standby only).
 *
 *  \param  kInstance     : (In)  the Pio instance to setup
 *  \param  pioPowerState : (Out) the returned power state
 *                                (PowerOn or PowerStandby)
 *
 *  \return The error code.
 *          - TMDL_ERR_PIO_NOT_SUPPORTED
 *
 *  \note   Power state cannot be got for the PIO. Hence GetPowerState
 *          always returns TMDL_ERR_PIO_NOT_SUPPORTEFD
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetPowerState(
    tmInstance_t    kInstance,
    ptmPowerState_t pioPowerState
    );


/******************************************************************************/
/** \brief  This function sets the PIO instance power state (Power On and
 *          Standby only).
 *
 *  \param  kInstance   : (In) the PIO instance to setup
 *  \param  kPowerState : (In) the power state(PowerOn or PowerStandby)
 *
 *  \return The error code.
 *          - TMDL_ERR_PIO_NOT_SUPPORTED
 *
 *  \note   Power state cannot be set for the PIO. Hence GetPowerState
 *          always returns TMDL_ERR_PIO_NOT_SUPPORTEFD
 */
/******************************************************************************/

tmErrorCode_t
tmdlPioSetPowerState(
    tmInstance_t    kInstance,
    tmPowerState_t  kPowerState
    );

/******************************************************************************/
/** \brief  This function installs a callback function.
 *          The function installed must be provided by the application.
 *          When an event occurs and the event has been enabled, the callback
 *          function is called back with the occurring event as parameter.
 *          By default, the events are disabled.
 *
 *  \param  kInstance    : (In) the Pio instance to setup
 *  \param  pkCallBack   : (In) a pointer to the callback function to install
 *  \param  kUserData    : (In) a data word that contains informations passed
 *                         as parameter of the callback function.
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified Pio instance is unvalid
 *
 *  \note   tmdlPioOpen and tmdlPioInstanceSetup must have been called before.
 *
 *  \sa     ptmdlCallback_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioRegisterCallback(
    tmInstance_t       kInstance,
    ptmdlCallback_t    pkCallBack,
    UInt32             kUserData
    );

/******************************************************************************/
/** \brief  This function allows the caller to select which PIO event to notify
 *          It is a bitwise OR of the events which cause the callback
 *          function installed with tmdlPioRegisterCallback to be called.
 *
 *  \param  kInstance  : (In) the Pio instance to setup
 *  \param  kEventMask : (In) the bitwise OR of the Pio event to notify
 *
 *  \return The error code.
 *           - TM_OK                   : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   tmdlPioOpen and tmdlPioInstanceSetup must have been called before.
 *
 *  \sa     TMDL_PIO_PIN0_EVENT
 *          TMDL_PIO_PIN1_EVENT
 *          TMDL_PIO_PIN2_EVENT
 *          TMDL_PIO_PIN3_EVENT
 *          TMDL_PIO_PIN4_EVENT
 *          TMDL_PIO_PIN5_EVENT
 *          TMDL_PIO_PIN6_EVENT
 *          TMDL_PIO_PIN7_EVENT
 *          TMDL_PIO_PIN8_EVENT
 *          TMDL_PIO_PIN9_EVENT
 *          TMDL_PIO_PIN10_EVENT
 *          TMDL_PIO_PIN11_EVENT
 *          TMDL_PIO_PIN12_EVENT
 *          TMDL_PIO_PIN13_EVENT
 *          TMDL_PIO_PIN14_EVENT
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioSetEventMask(
    tmInstance_t  kInstance,
    UInt32        kEventMask
    );

/*-----------------------------------------------------------------------------
 *  Specific PIO DL API:
 *-----------------------------------------------------------------------------*/

/******************************************************************************/
/** \brief  This specifique function set IO mode (input output) or peripheral
 *          mode for PIO line.
 *
 *  \param  kInstance      : (In) the Pio instance to setup
 *  \param  kLineSelInput  : (In) the line to set as input
 *  \param  kLineSelOutput : (In) the line to set as output
 *  \param  kLineSelPeriph : (In) the line to set as peripheral
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   Should be called through tmdlInstance config with
 *          ptmdlPioSetModeMask_t structure pointer as pioIcfgData pointer.
 *          Only PIO lines > 15 can be in I/O or peripheral mode.
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioSetMode(
    tmInstance_t   kInstance,
    tmdlPioLines_t kLineSelInput,
    tmdlPioLines_t kLineSelOutput,
    tmdlPioLines_t kLineSelPeriph
    );

/******************************************************************************/
/** \brief  This specifique function gets IO mode (input output) or peripheral
 *          mode for PIO line.
 *
 *  \param  kInstance        : (In) the Pio instance to setup
 *  \param  pioLineSelInput  : (Out) the line set as input
 *  \param  pioLineSelOutput : (Out) the line set as output
 *  \param  pioLineSelPeriph : (Out) the line set as peripheral
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   Should be called through tmdlInstance config with
 *          ptmdlPioSetModeMask_t structure pointer as pioIcfgData pointer.
 *
 *  \sa     tmdlPioSetModeMask_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetMode(
    tmInstance_t    kInstance,
    ptmdlPioLines_t pioLineSelInput,
    ptmdlPioLines_t pioLineSelOutput,
    ptmdlPioLines_t pioLineSelPeriph
    );

/******************************************************************************/
/** \brief  This specifique function sets the interrupt type and interrupt
 *          enable/disable setting. The line must be input, and interrupt type
 *          has been set.
 *
 *  \param  kInstance   : (In) the Pio instance to setup
 *  \param  kLineSelect : (In) the line to set
 *  \param  kOnoff      : (In) the selected line to enable/disable
 *  \param  kIntType    : (In) the interrupt type to set (falling/rising)
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   Should be called through tmdlInstance config with
 *          ptmdlPioSetIntType_t structure pointer as pioIcfgData pointer.
 *
 *  \sa     tmdlPioSetIntType_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioSetIntType(
    tmInstance_t     kInstance,
    tmdlPioLines_t   kLineSelect,
    tmdlPioSwitch_t  kOnoff,
    tmdlPioIntType_t kIntType
    );

/******************************************************************************/
/** \brief  This specifique function gets the interrupt type and interrupt
 *          enable/disable setting. The line must be input, and interrupt type
 *          has been set.
 *
 *  \param  kInstance     : (In) the Pio instance to setup
 *  \param  kLineSelect   : (In) the line to set
 *  \param  pioOnoff      : (Out) the selected line to enable/disable
 *  \param  pioIntType    : (Out) the interrupt type to set (falling/rising)
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   Should be called through tmdlInstance config with
 *          ptmdlPioSetIntType_t structure pointer as pioIcfgData pointer.
 *
 *  \sa     tmdlPioSetIntType_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetIntType(
    tmInstance_t     kInstance,
    tmdlPioLines_t   kLineSelect,
    tmdlPioSwitch_t  *pioOnoff,
    tmdlPioIntType_t *pioIntType
    );

/******************************************************************************/
/** \brief  This specifique function et the debounce for the lines specified
 *          by lineSelect .
 *
 *  \param  kInstance     : (In) the Pio instance to setup
 *  \param  kLineSelect   : (In) Line to set the debounce
 *  \param  kOnoff        : (In) enable/disable the debounce on selected line
 *  \param  kDbtime       : (In) the corresponding debounce flag rate
 *  \param  kSample       : (In) the sample number
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   Should be called through tmdlInstance config with
 *          ptmdlPioSetDebounce_t structure pointer as pioIcfgData pointer.
 *
 *  \verbatim
 *          debounce rate is for lines [7:0]
 *          flag       debounce rate
 *          0            66666
 *          1           133333
 *          2           266666
 *          3           533333
 *          4          1066666
 *          5          2133333
 *          6          4266666
 *          7          8533333
 *
 *          debounce rate is for lines [8:15]
 *          flag       debounce rate
 *          0            210
 *          1            421
 *          2            839
 *          3           1679
 *          4           3366
 *          5           6739
 *          6          13479
 *          7          26966
 *
 *          sample is 3 for lines [7:0]
 *          sample is a number between (0, 0xFF) for lines [15:8]
 *
 *          onoff must be on to enable the debounce \endverbatim
 *
 *          The applied time is calculated as T = (1/freq)*debounce_rate*sample
 *          where the freq is:
 *                           - Pnx8310 : 54 Mhz
 *                           - Pnx8330 : 60 Mhz
 *
 *  \sa     tmdlPioSetDebounce_t, tmdlPioDebounceRate_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioSetDebounce(
    tmInstance_t          kInstance,
    tmdlPioLines_t        kLineSelect,
    tmdlPioSwitch_t       kOnoff,
    tmdlPioDebounceRate_t kDbtime,
    UInt32                kSample
    );

/******************************************************************************/
/** \brief  This specifique function et the debounce for the lines specified
 *          by lineSelect .
 *
 *  \param  kInstance     : (In) the Pio instance to setup
 *  \param  kLineSelect   : (In) Line to get the debounce
 *  \param  pioOnoff      : (Out) enabled/disabled the debounce on selected line
 *  \param  pioDbtime     : (Out) the corresponding debounce flag rate
 *  \param  pioSample     : (Out) the sample number always 3 for pio[0:7]
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   Should be called through tmdlInstance config with
 *          ptmdlPioSetDebounce_t structure pointer as pioIcfgData pointer.
 *
 *  \verbatim
 *          debounce rate is for lines [7:0]
 *          flag       debounce rate
 *          0            66666
 *          1           133333
 *          2           266666
 *          3           533333
 *          4          1066666
 *          5          2133333
 *          6          4266666
 *          7          8533333
 *
 *          debounce rate is for lines [8:15]
 *          flag       debounce rate
 *          0            210
 *          1            421
 *          2            839
 *          3           1679
 *          4           3366
 *          5           6739
 *          6          13479
 *          7          26966
 *
 *          sample is 3 for lines [7:0]
 *          sample is a number between (0, 0xFF) for lines [15:8]
 *
 *          onoff must be on to enable the debounce \endverbatim
 *
 *          The applied time is calculated as T = (1/freq)*debounce_rate*sample
 *          where the freq is:
 *                           - Pnx8310 : 54 Mhz
 *                           - Pnx8330 : 60 Mhz
 *
 *  \sa     tmdlPioSetDebounce_t, tmdlPioDebounceRate_t
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioGetDebounce(
    tmInstance_t          kInstance,
    tmdlPioLines_t        kLineSelect,
    tmdlPioSwitch_t       *pioOnoff,
    tmdlPioDebounceRate_t *pioDbtime,
    UInt32                *pioSample
    );

/******************************************************************************/
/** \brief  This specifique function write the bit pattern to the mask specified
 *          range of lines output configured.
 *
 *  \param  kInstance     : (In) the Pio instance to setup
 *  \param  kLineSelect   : (In) the output line to set
 *  \param  kBitpattern   : (In) patern to write
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   The pattern is right-aligned to the LSB of bitpattern.
 *          It is assumed that these lines have been programmed to be output
 *          i/o lines previously.
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioWrite(
    tmInstance_t   kInstance,
    tmdlPioLines_t kLineSelect,
    tmdlPioLines_t kBitpattern
);

/******************************************************************************/
/** \brief  This specifique function write the bit pattern to the mask specified
 *          range of lines intput configured.
 *
 *  \param  kInstance       : (In) the Pio instance to setup
 *  \param  kLineSelect     : (In) the input line to set
 *  \param  pioBitPattern   : (Out) patern to read
 *
 *  \return The error code.
 *           - TM_OK                     : success
 *           - TMDL_ERR_PIO_BAD_INSTANCE : the specified instance is not valid
 *           - TMDL_ERR_PIO_NO_RESOURCES : error at OS level
 *
 *  \note   The pattern is right-aligned to the LSB of *pBitpattern.
 *          It is assumed that these lines have been programmed to be input
 *          i/o lines previously.
 */
/******************************************************************************/
tmErrorCode_t
tmdlPioRead(
    tmInstance_t   kInstance,
    tmdlPioLines_t kLineSelect,
    tmdlPioLines_t *pioBitPattern
    );

#ifdef __cplusplus
}
#endif

#endif /* _TMDL_PIO_H_ */
