/*  ============================================================================
 *   Copyright (c) Texas Instruments Inc 2002, 2003, 2004, 2005                 
 *                                                                              
 *   Use of this software is controlled by the terms and conditions found in the
 *   license agreement under which this software has been supplied.             
 *   ===========================================================================
 */ 

/** @mainpage GPIO CSL 3.x
 *
 * @section Introduction
 *
 * @subsection xxx Purpose and Scope
 * The purpose of this document is to identify a set of common CSL APIs for
 * the GPIO module across various devices. The CSL developer is expected to
 * refer to this document while designing APIs for these modules. Some of the
 * listed APIs may not be applicable to a given GPIO module. While other cases
 * this list of APIs may not be sufficient to cover all the features of a
 * particular GPIO Module.The CSL developer should use his discretion designing
 * new APIs or extending the existing ones to cover these.
 *
 * @subsection aaa Terms and Abbreviations
 *   -# CSL:  Chip Support Library
 *   -# API:  Application Programmer Interface
 *
 * @subsection References
 *    -# CSL-001-DES, CSL 3.x Design Specification DocumentVersion 1.02
 *
 */

/** \file  csl_gpio.h
    \brief GPIO functional layer API header file
    \internal
    PATH \\(CSLPATH)\\ipmodules\\gpio\\src    
    \date 11th June, 2004
    \author Pratheesh Gangadhar (pratheesh@ti.com)
*/

/* ============================================================================
 *  Revision History
 *  ===============
 *  22-Feb-2005 Nsr added control command CSL_GPIO_CMD_GET_BIT according to
 *                  TI issue PSG00000310.
 *  11-Oct-2004 Nsr removed the extern keyword before function declaration and
 *                 - Changed this file according to review.
 *  04-sep-2004 Nsr updated CSL_GpioObj and added CSL_GpioBaseAddress,
 *                  CSL_GpioParam, SL_GpioContext,  CSL_GpioConfig structures.
 *                 - Updated comments for H/W control cmd and status query
 *                   enums.
 *                 - Added prototypes for CSL_gpioGetBaseAdddress and
 *                   CSL_gpioHwSetupRaw.
 *                 - Changed prototypes of CSL_gpioInit, CSL_gpioOpen.
 *                 - Updated respective comments along with that of
 *                   CSL_gpioClose.
 *
 * ============================================================================
 */

#ifndef _CSL_GPIO_H_
#define _CSL_GPIO_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <soc.h>
#include <cslr.h>
#include <csl_error.h>
#include <csl_types.h>
#include <cslr_gpio.h>

/**
\defgroup CSL_GPIO_API GPIO
   \internal Based on <b>Imaging and Audio Group GPIO Detailed Design
                Specification Rev 1.00.w.02 </b>
*/
/**
\defgroup CSL_GPIO_DATASTRUCT Data Structures
\ingroup CSL_GPIO_API
*/
/**
\defgroup CSL_GPIO_DEFINE  Defines
\ingroup CSL_GPIO_API
*/
/**
\defgroup CSL_GPIO_ENUM  Enumerated Data Types
\ingroup CSL_GPIO_API
*/

/**
\defgroup CSL_GPIO_FUNCTION  Functions
\ingroup CSL_GPIO_API
*/

/** \defgroup CSL_GPIO_ERROR_DEFINE Error Code
*   \ingroup CSL_GPIO_DEFINE
*
*
* @{ */
#define CSL_EGPIO_INVPARAM CSL_EGPIO_FIRST
                       /**< Invalid argument */
/**
@} */

/*****************************************************************************\
          GPIO global typedef declarations
\*****************************************************************************/

/**
 *  \brief  Base-address of the Configuration registers of GPIO.
 */
typedef struct {
    /** Base-address of the configuration registers of the peripheral
     */
    CSL_GpioRegsOvly regs;
} CSL_GpioBaseAddress;

/**
 *  \brief GPIO specific parameters. Present implementation doesn't have
 *  any specific parameters.
 */
typedef struct {
    /** Bit mask to be used for module specific parameters.
     *  The below declaration is just a place-holder for future
     *  implementation.
     */
    CSL_BitMask16   flags;
} CSL_GpioParam;

/** \brief GPIO specific context information. Present implementation doesn't
 *  have any Context information.
 */
typedef struct {
    /** Context information of GPIO.
     *  The below declaration is just a place-holder for future
     *  implementation.
     */
    Uint16  contextInfo;
} CSL_GpioContext;

/** @brief Bank Registers for Config Structure
 */
typedef struct  {
    /** GPIO Direction 2i and 2i+1 Register */
    volatile Uint32 DIR;
    /** GPIO Output Data 2i and 2i+1 Register */
    volatile Uint32 OUT_DATA;
    /** GPIO Set Data 2i and 2i+1 Register */
    volatile Uint32 SET_DATA;
    /** GPIO Clear Data 2i and 2i+1 Register */
    volatile Uint32 CLR_DATA;
    /** GPIO Set Rising Edge Interrupt 2i and 2i+1 Register */
    volatile Uint32 SET_RIS_TRIG;
    /** GPIO Clear Rising Edge Interrupt 2i and 2i+1 Register */
    volatile Uint32 CLR_RIS_TRIG;
    /** GPIO Set Falling Edge Interrupt 2i and 2i+1 Register */
    volatile Uint32 SET_FAL_TRIG;
    /** GPIO Clear Falling Edge Interrupt 2i and 2i+1 Register */
    volatile Uint32 CLR_FAL_TRIG;
    /** GPIO Interrupt Status 2i and 2i+1 Register */
    volatile Uint32 INTSTAT;
} CSL_GpioCfgBankRegs;

/**
 * @brief Config structure of GPIO. This is used to configure GPIO
 * using CSL_HwSetupRaw function
 */
typedef struct  {
    /** GPIO Interrupt Per-Bank Enable Register */
    volatile Uint32 BINTEN;
    /** Configuration structure registers for GPIO bank registers */
    CSL_GpioCfgBankRegs BANK[5];
} CSL_GpioCfg;

/** @brief Default Values for GPIO Config structure */
#define CSL_GPIO_CONFIG_DEFAULTS {      \
    CSL_GPIO_BINTEN_RESETVAL ,          \
    {                                   \
        CSL_GPIO_DIR_RESETVAL,          \
        CSL_GPIO_OUT_DATA_RESETVAL,     \
        CSL_GPIO_SET_DATA_RESETVAL,     \
        CSL_GPIO_CLR_DATA_RESETVAL,     \
        CSL_GPIO_SET_RIS_TRIG_RESETVAL, \
        CSL_GPIO_CLR_RIS_TRIG_RESETVAL, \
        CSL_GPIO_SET_FAL_TRIG_RESETVAL, \
        CSL_GPIO_CLR_FAL_TRIG_RESETVAL, \
        CSL_GPIO_INTSTAT_RESETVAL       \
    }                                   \
}

/** @brief Default Values for MGPIO Config structure */
#define CSL_MGPIO_CONFIG_DEFAULTS {         \
    CSL_GPIO_BINTEN_RESETVAL ,              \
    {                                       \
        {                                   \
            CSL_GPIO_DIR_RESETVAL,          \
            CSL_GPIO_OUT_DATA_RESETVAL,     \
            CSL_GPIO_SET_DATA_RESETVAL,     \
            CSL_GPIO_CLR_DATA_RESETVAL,     \
            CSL_GPIO_SET_RIS_TRIG_RESETVAL, \
            CSL_GPIO_CLR_RIS_TRIG_RESETVAL, \
            CSL_GPIO_SET_FAL_TRIG_RESETVAL, \
            CSL_GPIO_CLR_FAL_TRIG_RESETVAL, \
            CSL_GPIO_INTSTAT_RESETVAL    }, \
                                            \
        {                                   \
            CSL_GPIO_DIR_RESETVAL,          \
            CSL_GPIO_OUT_DATA_RESETVAL,     \
            CSL_GPIO_SET_DATA_RESETVAL,     \
            CSL_GPIO_CLR_DATA_RESETVAL,     \
            CSL_GPIO_SET_RIS_TRIG_RESETVAL, \
            CSL_GPIO_CLR_RIS_TRIG_RESETVAL, \
            CSL_GPIO_SET_FAL_TRIG_RESETVAL, \
            CSL_GPIO_CLR_FAL_TRIG_RESETVAL, \
            CSL_GPIO_INTSTAT_RESETVAL    }, \
                                            \
        {                                   \
            CSL_GPIO_DIR_RESETVAL,          \
            CSL_GPIO_OUT_DATA_RESETVAL,     \
            CSL_GPIO_SET_DATA_RESETVAL,     \
            CSL_GPIO_CLR_DATA_RESETVAL,     \
            CSL_GPIO_SET_RIS_TRIG_RESETVAL, \
            CSL_GPIO_CLR_RIS_TRIG_RESETVAL, \
            CSL_GPIO_SET_FAL_TRIG_RESETVAL, \
            CSL_GPIO_CLR_FAL_TRIG_RESETVAL, \
            CSL_GPIO_INTSTAT_RESETVAL    }, \
                                            \
        {                                   \
            CSL_GPIO_DIR_RESETVAL,          \
            CSL_GPIO_OUT_DATA_RESETVAL,     \
            CSL_GPIO_SET_DATA_RESETVAL,     \
            CSL_GPIO_CLR_DATA_RESETVAL,     \
            CSL_GPIO_SET_RIS_TRIG_RESETVAL, \
            CSL_GPIO_CLR_RIS_TRIG_RESETVAL, \
            CSL_GPIO_SET_FAL_TRIG_RESETVAL, \
            CSL_GPIO_CLR_FAL_TRIG_RESETVAL, \
            CSL_GPIO_INTSTAT_RESETVAL    }, \
                                            \
        {                                   \
            CSL_GPIO_DIR_RESETVAL,          \
            CSL_GPIO_OUT_DATA_RESETVAL,     \
            CSL_GPIO_SET_DATA_RESETVAL,     \
            CSL_GPIO_CLR_DATA_RESETVAL,     \
            CSL_GPIO_SET_RIS_TRIG_RESETVAL, \
            CSL_GPIO_CLR_RIS_TRIG_RESETVAL, \
            CSL_GPIO_SET_FAL_TRIG_RESETVAL, \
            CSL_GPIO_CLR_FAL_TRIG_RESETVAL, \
            CSL_GPIO_INTSTAT_RESETVAL    }  \
    }                                       \
}

/**\defgroup CSL_GPIO_DIR_ENUM GPIO Pin Direction
*  \ingroup CSL_GPIO_ENUM
*
*
@{*/

/** \brief  Enums for configuring GPIO pin direction
*
*/
typedef enum {
    CSL_GPIO_DIR_OUTPUT,/**<<b>: Output pin</b>*/
    CSL_GPIO_DIR_INPUT  /**<<b>: Input pin</b>*/
} CSL_GpioDirection;

/**
@} */

/**\defgroup CSL_GPIO_EDGDET_ENUM GPIO Edge Detection
*  \ingroup CSL_GPIO_ENUM
*
*
@{*/

/** \brief  Enums for configuring GPIO pin edge detection
*
*/
typedef enum {
    CSL_GPIO_TRIG_CLEAR_EDGE,  /**<<b>: No edge detection </b>*/
    CSL_GPIO_TRIG_RISING_EDGE, /**<<b>: Rising edge detection </b>*/
    CSL_GPIO_TRIG_FALLING_EDGE,/**<<b>: Falling edge detection </b>*/
    CSL_GPIO_TRIG_DUAL_EDGE    /**<<b>: Dual edge detection </b>*/
} CSL_GpioTriggerType;
/**
@} */


/**\defgroup CSL_GPIO_CONTROLCMD_ENUM  Control Commands
*  \ingroup CSL_GPIO_CONTROL_API
@{*/
/** \brief Enumeration for control commands passed to \a CSL_gpioHwControl()
*
* This is the set of commands that are passed to the \a CSL_gpioHwControl()
* with an optional argument type-casted to \a void* .
* The arguments to be passed with each enumeration (if any) are specified
* next to the enumeration
*/
typedef enum {
    /**
     * @brief Enables interrupt on specified bank
     * @param ( CSL_GpioBankNum )
     */
    CSL_GPIO_CMD_BANK_INT_ENABLE       = 1,

    /**
     * @brief Disables interrupt on specified bank
     * @param ( CSL_GpioBankNum )
     */
    CSL_GPIO_CMD_BANK_INT_DISABLE      = 2,

    /**
     * @brief Configures GPIO pin direction and edge detection properties
     * @param ( CSL_GpioConfig )
     */
    CSL_GPIO_CMD_CONFIG_BIT            = 3,

    /**
     * @brief Changes output state of GPIO pin to logic-1
     * @param ( CSL_GpioPinNum )
     */
    CSL_GPIO_CMD_SET_BIT               = 4,

    /**
     * @brief Changes output state of GPIO pin to logic-0
     * @param ( CSL_GpioPinNum )
     */
    CSL_GPIO_CMD_CLEAR_BIT             = 5,

    /**
     * @brief Gets the interrupt status of individual pins on
     *        banks 2*i and 2*i+1.
     *        The "data" field act as output parameter reporting
     *        the interrupt status of the GPIO pins on the banks.
     * @param ( CSL_GpioBankData )
     */
    CSL_GPIO_CMD_GET_INTSTATUS         = 6,

    /**
     * @brief Gets the state of input pins on banks 2*i and 2*i+1
     *        The "data" field act as output parameter reporting
     *        the input state of the GPIO pins on the banks.
     * @param ( CSL_GpioBankData )
     */
    CSL_GPIO_CMD_GET_INPUTBIT          = 7,

    /**
     * @brief Gets the state of output pins on banks 2*i and 2*i+1.
     *        The "data" field act as output parameter reporting the
     *        output drive state of the GPIO pins on the banks
     * @param ( CSL_GpioBankData )
     */
     CSL_GPIO_CMD_GET_OUTDRVSTATE      = 8,

     /**
     * @brief Gets the state of input pin on banks 2*i and 2*i+1
     * @param ( CSL_GpiopPinNum )
     */
     CSL_GPIO_CMD_GET_BIT              = 9

} CSL_GpioHwControlCmd;
/**
@} */


/**\defgroup CSL_GPIO_QUERYCMD_ENUM Query Commands
*  \ingroup CSL_GPIO_QUERY_API
* @{ */

/** \brief Enumeration for queries passed to \a CSL_GpioGetHwStatus()
*
* This is used to get the status of different operations.The arguments
* to be passed with each enumeration if any are specified next to
* the enumeration */
typedef enum {

    /**
     * @brief Queries GPIO peripheral id
     * @param ( Uint32* )
     */
    CSL_GPIO_QUERY_PID         = 1,

    /**
     * @brief Queries GPIO bank interrupt enable status
     * @param (CSL_BitMask32*)
     */
    CSL_GPIO_QUERY_BINTEN_STAT = 2
} CSL_GpioHwStatusQuery;
/**
@} */


/**
\addtogroup CSL_GPIO_DATASTRUCT
@{
*/

/** \brief Input parameters for configuring a GPIO pin
 *  This is used to configure the direction and edge detection
 */
typedef struct {
    CSL_GpioPinNum pinNum; /**< Pin number for GPIO bank */
    CSL_GpioDirection direction; /**< Direction for GPIO Pin */
    CSL_GpioTriggerType trigger; /**< GPIO pin edge detection */
} CSL_GpioConfig;

/**
@} */

/**
\addtogroup CSL_GPIO_DATASTRUCT
@{
*/

/**
   \brief Generic argument to get the pin information on banks 2*index and
          2*index+1
*
*  Used in CSL_gpioHwControl, designed this way to reduce the number of
*  register reads by a higher layer function
*/
typedef struct {
    Uint32         index; /**< bank select*/
    CSL_BitMask32  data;/**< desired information on the pins*/
} CSL_GpioBankData;
/**
@} */

/**
\addtogroup CSL_GPIO_DATASTRUCT
@{
*/

/**
   \brief Input parameters for setting up GPIO during startup
*
*  This is just a placeholder as GPIO is a simple module, which doesn't
*  require any setup
*/
typedef struct {
    /** The extendSetup is just a place-holder for future
     *  implementation.
     */
    void *extendSetup;
} CSL_GpioHwSetup;
/**
@} */

/**
\addtogroup CSL_GPIO_DATASTRUCT
@{
*/

/** \brief This object contains the reference to the instance of GPIO
*          opened using the @a CSL_gpioOpen()
*
* The pointer to this is passed to all GPIO CSL APIs
* This structure has the fields required to configure GPIO for any test
* case/application. It should be initialized as per requirements of a
* test case/application and passed on to the setup function
*/
typedef struct CSL_GpioObj {
    CSL_GpioRegsOvly regs;/**< This is a pointer to the registers of the