rt-thread/bsp/synopsys/embarc/device/device_hal/inc/dev_gpio.h

/* ------------------------------------------
 * Copyright (c) 2016, Synopsys, Inc. All rights reserved.

 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:

 * 1) Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer.

 * 2) 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.

 * 3) Neither the name of the Synopsys, Inc., 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 HOLDER 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.
 *
 * \version 2016.05
 * \date 2014-06-17
 * \author Huaqi Fang(Huaqi.Fang@synopsys.com)
--------------------------------------------- */

/**
 * \defgroup	DEVICE_HAL_GPIO		GPIO Device HAL Interface
 * \ingroup	DEVICE_HAL_DEF
 * \brief	definitions for gpio device hardware layer (\ref dev_gpio.h)
 * \details	provide interfaces for gpio driver to implement
 *  Here is a diagram for the gpio interface.
 *
 *  \htmlonly
 *  <div class="imagebox">
 *      <div style="width: 600px">
 *          <img src="pic/dev_gpio_hal.jpg" alt="GPIO Device HAL Interface Diagram"/>
 *          <p>GPIO Device HAL Interface Diagram</p>
 *      </div>
 *  </div>
 *  \endhtmlonly
 *
 * @{
 *
 * \file
 * \brief	gpio device hardware layer definitions
 * \details	Provide common definitions for gpio device,
 * 	then the software developer can develop gpio driver
 * 	following these definitions, and the applications
 * 	can directly call this definition to realize functions
 *
 */

#ifndef _DEVICE_HAL_GPIO_H_
#define _DEVICE_HAL_GPIO_H_

#include "device/device_hal/inc/dev_common.h"

/**
 * \defgroup	DEVICE_HAL_GPIO_DEFDIR	GPIO Port Direction Definition
 * \ingroup	DEVICE_HAL_GPIO
 * \brief	Define macros to indicate gpio directions
 * @{
 */
/*
 * defines for gpio directions
 */
#define GPIO_DIR_INPUT				(0)		/*!< gpio works as input */
#define GPIO_DIR_OUTPUT				(1)		/*!< gpio works as output */
/** @} */

/**
 * \defgroup	DEVICE_HAL_GPIO_CTRLCMD		GPIO Device Control Commands
 * \ingroup	DEVICE_HAL_GPIO
 * \brief	Definitions for gpio control command, used in \ref dev_gpio::gpio_control "GPIO IO Control"
 * \details	These commands defined here can be used in user code directly.
 * - Parameters Usage
 *   - For passing parameters like integer, just use uint32_t/int32_t to directly pass values
 *   - For passing parameters for a structure, please use pointer to pass values
 *   - For getting some data, please use pointer to store the return data
 * - Common Return Values
 *   - \ref E_OK,	Control device successfully
 *   - \ref E_CLSED,	Device is not opened
 *   - \ref E_OBJ,	Device object is not valid or not exists
 *   - \ref E_PAR,	Parameter is not valid for current control command
 *   - \ref E_SYS,	Control device failed, due to hardware issues such as device is disabled
 *   - \ref E_NOSPT,	Control command is not supported or not valid
 * @{
 */
/**
 * Set the \ref dev_gpio_info::direction "direction" of masked bits of gpio port into \ref GPIO_DIR_INPUT "input"
 * - Param type : uint32_t
 * - Param usage : 1 in each bit will be masked.
 * - Return value explanation :
 */
#define GPIO_CMD_SET_BIT_DIR_INPUT			DEV_SET_SYSCMD(0)
/**
 * Set the \ref dev_gpio_info::direction "direction" of masked bits of gpio port into \ref GPIO_DIR_OUTPUT "output"
 * - Param type : uint32_t
 * - Param usage : 1 in each bit will be masked.
 * - Return value explanation :
 */
#define GPIO_CMD_SET_BIT_DIR_OUTPUT			DEV_SET_SYSCMD(1)
/**
 * Get \ref dev_gpio_info::direction "gpio port direction".
 * - Param type : uint32_t
 * - Param usage : 1 bit for 1 bit of gpio port, 0 for input, 1 for output
 * - Return value explanation :
 */
#define GPIO_CMD_GET_BIT_DIR				DEV_SET_SYSCMD(2)
/**
 * Set gpio interrupt configuration for each bit.
 * - Param type : \ref DEV_GPIO_INT_CFG *
 * - Param usage : store gpio interrupt configuration for each bit.
 * - Return value explanation :
 */
#define GPIO_CMD_SET_BIT_INT_CFG			DEV_SET_SYSCMD(3)
/**
 * Get gpio interrupt configuration for each bit.
 * - Param type : \ref DEV_GPIO_INT_CFG *
 * - Param usage : First set int_bit_mask in DEV_GPIO_INT_CFG structure to
 * the mask of which bit of GPIO you want to get. And the interrupt configuration
 * will be stored in the structure DEV_GPIO_INT_CFG, each bit stand for each bit of port.
 * - Return value explanation :
 */
#define GPIO_CMD_GET_BIT_INT_CFG			DEV_SET_SYSCMD(4)
/**
 * Set gpio service routine for each bit.
 * - Param type : \ref DEV_GPIO_BIT_ISR *
 * - Param usage : store gpio handler information for each bit, int handler's param will be DEV_GPIO *.
 * - Return value explanation :
 */
#define GPIO_CMD_SET_BIT_ISR				DEV_SET_SYSCMD(5)
/**
 * Get gpio service routine for each bit.
 * - Param type : \ref DEV_GPIO_BIT_ISR *
 * - Param usage : By passing int_bit_ofs in DEV_GPIO_BIT_ISR,
 * it will return interrupt handler for this bit and store it in int_bit_handler.
 * - Return value explanation :
 */
#define GPIO_CMD_GET_BIT_ISR				DEV_SET_SYSCMD(6)
/**
 * Enable gpio interrupt of the masked bits.
 * - Param type : uint32_t
 * - Param usage : 1 in each bit will be masked.
 * - Return value explanation :
 */
#define GPIO_CMD_ENA_BIT_INT				DEV_SET_SYSCMD(7)
/**
 * Disable gpio interrupt of the masked bits.
 * - Param type : uint32_t
 * - Param usage : 1 in each bit will be masked.
 * - Return value explanation :
 */
#define GPIO_CMD_DIS_BIT_INT				DEV_SET_SYSCMD(8)
/**
 * Get \ref dev_gpio_info::method "gpio interrupt enable status".
 * - Param type : uint32_t *
 * - Param usage : 1 bit for 1 bit of gpio port, 0 for poll, 1 for interrupt
 * - Return value explanation :
 */
#define GPIO_CMD_GET_BIT_MTHD				DEV_SET_SYSCMD(9)
/* @} */

/**
 * \defgroup	DEVICE_HAL_GPIO_INT_CFG_SET	GPIO Device Int Configuration Settings
 * \ingroup	DEVICE_HAL_GPIO
 * \brief	definition of gpio interrupt type
 * @{
 */

/* GPIO Mask Defintions */
/** Mask none bits of the max 32bits */
#define GPIO_BITS_MASK_NONE			(0)
/** Mask all bits of the max 32bits */
#define GPIO_BITS_MASK_ALL			(0XFFFFFFFF)

/* GPIO Interrupt Type Related Definitions */

/** Level sensitive interrupt type for 1 bit */
#define GPIO_INT_LEVEL_TRIG			(0)
/** Edge sensitive interrupt type for 1 bit */
#define GPIO_INT_EDGE_TRIG			(1)
/** Level sensitive interrupt type for all 32 bits */
#define GPIO_INT_LEVEL_TRIG_ALL			(0)
/** Edge sensitive interrupt type for all 32 bits */
#define GPIO_INT_EDGE_TRIG_ALL			(0XFFFFFFFF)

/* For bit settings */
/** Set bit interrupt type of gpio into level sensitive */
#define GPIO_INT_BIT_LEVEL_TRIG(bit_ofs)	(GPIO_INT_LEVEL_TRIG<<(bit_ofs))
/** Set bit interrupt type of gpio into edge sensitive */
#define GPIO_INT_BIT_EDGE_TRIG(bit_ofs)		(GPIO_INT_EDGE_TRIG<<(bit_ofs))
/* For bits settings */
/** Set interrupt type of masked bits of gpio into level sensitive */
#define GPIO_INT_BITS_LEVEL_TRIG(bit_mask)	(GPIO_INT_LEVEL_TRIG_ALL&(bit_mask))
/** Set bit interrupt type of gpio into edge sensitive */
#define GPIO_INT_BITS_EDGE_TRIG(bit_mask)	(GPIO_INT_EDGE_TRIG_ALL&(bit_mask))

/* GPIO Interrupt Polarity Related Definitions */

/** GPIO Interrupt polarity type enum */
typedef enum gpio_int_polarity {
	/* Polarity for 1 bit */
	GPIO_INT_ACTIVE_LOW   = 0, /*!< Active low for level-sensitive interrupt for 1 bit */
	GPIO_INT_FALLING_EDGE = 0, /*!< Falling-edge for edge-sensitive interrupt for 1 bit */
	GPIO_INT_ACTIVE_HIGH =  1, /*!< Active high for level-sensitive interrupt for 1 bit */
	GPIO_INI_RISING_EDGE = 1, /*!< Rising-edge for edge-sensitive interrupt for 1 bit */
	/* Polartiy for all 32 bits */
	GPIO_INT_ACTIVE_LOW_ALL   = 0, /*!< Active low for level-sensitive interrupt for all bits */
	GPIO_INT_FALLING_EDGE_ALL = 0, /*!< Falling-edge for edge-sensitive interrupt for all bits */
	GPIO_INT_ACTIVE_HIGH_ALL =  0XFFFFFFFF, /*!< Active high for level-sensitive interrupt for all bits */
	GPIO_INI_RISING_EDGE_ALL = 0XFFFFFFFF /*!< Rising-edge for edge-sensitive interrupt for all bits */
} GPIO_INT_POLARITY;

/* For bit settings */
/** Set bit polarity of gpio into active low */
#define GPIO_INT_BIT_POL_ACT_LOW(bit_ofs)	(GPIO_INT_ACTIVE_LOW<<(bit_ofs))
/** Set bit polarity of gpio into active high */
#define GPIO_INT_BIT_POL_ACT_HIGH(bit_ofs)	(GPIO_INT_ACTIVE_HIGH<<(bit_ofs))
/** Set bit polarity of gpio into falling edge */
#define GPIO_INT_BIT_POL_FALL_EDGE(bit_ofs)	(GPIO_INT_FALLING_EDGE<<(bit_ofs))
/** Set bit polarity of gpio into rising edge */
#define GPIO_INT_BIT_POL_RISE_EDGE(bit_ofs)	(GPIO_INI_RISING_EDGE<<(bit_ofs))

/* For bits settings */
/** Set polarity of masked bits of gpio into active low */
#define GPIO_INT_BITS_POL_ACT_LOW(bit_mask)	(GPIO_INT_ACTIVE_LOW_ALL&(bit_mask))
/** Set polarity of masked bits of gpio into active high */
#define GPIO_INT_BITS_POL_ACT_HIGH(bit_mask)	(GPIO_INT_ACTIVE_HIGH_ALL&(bit_mask))
/** Set polarity of masked bits of gpio into falling edge */
#define GPIO_INT_BITS_POL_FALL_EDGE(bit_mask)	(GPIO_INT_FALLING_EDGE_ALL&(bit_mask))
/** Set polarity of masked bits of gpio into rising edge */
#define GPIO_INT_BITS_POL_RISE_EDGE(bit_mask)	(GPIO_INI_RISING_EDGE_ALL&(bit_mask))

/* GPIO Interrupt Debounce Related Definitions */

/* For bit settings */
/** Disable debounce circuitry for 1 bit */
#define GPIO_INT_NO_DEBOUNCE			(0)
/** Enable debounce circuitry for 1 bit */
#define GPIO_INT_DEBOUNCE			(1)

/* For bits settings */
/** Disable debounce circuitry for all bits */
#define GPIO_INT_NO_DEBOUNCE_ALL		(0)
/** Enable debounce circuitry for all bits */
#define GPIO_INT_DEBOUNCE_ALL			(0XFFFFFFFF)

/* For bit settings */
/** Set bit interrupt debounce of gpio into enabled */
#define GPIO_INT_BIT_ENA_DEBOUNCE(bit_ofs)	(GPIO_INT_DEBOUNCE<<(bit_ofs))
/** Set bit interrupt debounce of gpio into disabled */
#define GPIO_INT_BIT_DIS_DEBOUNCE(bit_ofs)	(GPIO_INT_NO_DEBOUNCE<<(bit_ofs))
/* For bits settings */
/** Set bit interrupt debounce of gpio into enabled */
#define GPIO_INT_BITS_ENA_DEBOUNCE(bit_mask)	(GPIO_INT_DEBOUNCE_ALL&(bit_mask))
/** Set bit interrupt debounce of gpio into disabled */
#define GPIO_INT_BITS_DIS_DEBOUNCE(bit_mask)	(GPIO_INT_NO_DEBOUNCE_ALL&(bit_mask))

/** GPIO interrupt configuration */
typedef struct dev_gpio_int_cfg {
	uint32_t int_bit_mask;		/*!< interrupt bit mask for gpio */
	uint32_t int_bit_type;		/*!< \ref GPIO_INT_LEVEL_TRIG "level sensitive" or \ref GPIO_INT_EDGE_TRIG "edge sensitive" for each gpio bit */
	uint32_t int_bit_polarity;	/*!< active high or low, refer to \ref GPIO_INT_POLARITY for each gpio bit */
	uint32_t int_bit_debounce;	/*!< \ref GPIO_INT_DEBOUNCE "enable" or \ref GPIO_INT_NO_DEBOUNCE "disable" debounce logic for each gpio bit */
} DEV_GPIO_INT_CFG, * DEV_GPIO_INT_CFG_PTR;

/** Default interrupt configuration for all gpio bits */
static const DEV_GPIO_INT_CFG gpio_int_cfg_default = \
	{GPIO_BITS_MASK_ALL, GPIO_INT_LEVEL_TRIG_ALL, \
		GPIO_INT_ACTIVE_LOW_ALL, GPIO_INT_NO_DEBOUNCE_ALL};

/** GPIO interrupt handler or Interrupt Service Routine(ISR) */
typedef void (*DEV_GPIO_HANDLER) (void *ptr);

/** interrupt handler for each port bit */
typedef struct dev_gpio_bit_isr {
	uint32_t int_bit_ofs;			/*!< int bit offset */
	DEV_GPIO_HANDLER int_bit_handler;	/*!< interrupt handler */
} DEV_GPIO_BIT_ISR, * DEV_GPIO_BIT_ISR_PTR;
/* @} */

/**
 * \defgroup	DEVICE_HAL_GPIO_DEVSTRUCT	GPIO Device Interface Definition
 * \ingroup	DEVICE_HAL_GPIO
 * \brief	contains definitions of gpio device structure.
 * \details	This structure will be used in user implemented code, which was called
 *     \ref DEVICE_IMPL "Device Driver Implement Layer" for gpio to use in implementation code.
 *     Application developer should use the GPIO API provided here to access to GPIO devices.
 *     BSP developer should follow the API definition to implement GPIO device drivers.
 * @{
 */
/**
 * \brief	gpio information struct definition
 * \details	informations about gpio open count, working status
 * 	gpio registers and control block, gpio io direction and interrupt/poll for each bit of gpio
 * \note	Only available for gpio with max 32bits
 */
typedef struct dev_gpio_info {
	void *gpio_ctrl;	/*!< gpio control related pointer, implemented by bsp developer, and this should be set during gpio object implementation */
	uint32_t opn_cnt;	/*!< gpio open count, open it will increase 1, close it will decrease 1, 0 for close, >0 for open */
	uint32_t direction;	/*!< each bit direction of this GPIO, default all \ref GPIO_DIR_INPUT "input" for first open */
	uint32_t method;	/*!< int/poll method for each bit of GPIO, 0 for poll, 1 for interrupt, default all \ref DEV_POLL_METHOD "poll" for first open */
	void * extra;		/*!< a extra pointer to get hook to applications which should not used by bsp developer,
					this should be NULL for first open and you can \ref DEV_GPIO_INFO_SET_EXTRA_OBJECT "set"
					or \ref DEV_GPIO_INFO_GET_EXTRA_OBJECT "get" the extra information pointer */
} DEV_GPIO_INFO, * DEV_GPIO_INFO_PTR;
/** Set extra information pointer of gpio info */
#define DEV_GPIO_INFO_SET_EXTRA_OBJECT(gpio_info_ptr, extra_info)	(gpio_info_ptr)->extra = (void *)(extra_info)
/** Get extra information pointer of gpio info */
#define DEV_GPIO_INFO_GET_EXTRA_OBJECT(gpio_info_ptr)			((gpio_info_ptr)->extra)

/** Method of all gpio bits set to poll */
#define DEV_GPIO_BITS_MTHD_POLL			(0)
/** Method of all gpio bits set to interrupt */
#define DEV_GPIO_BITS_MTHD_INTERRUPT		(0xFFFFFFFF)
/** Default method of all gpio bits should be poll for first open */
#define DEV_GPIO_BITS_MTHD_DEFAULT		(DEV_GPIO_BITS_MTHD_POLL)

/**
 * \brief	gpio device interface definition
 * \details	define gpio device interface, like gpio information structure,
 * 	fuctions to open/close/control gpio, write or read data via gpio
 * \note	all this details are implemented by user in user porting code
 */
typedef struct dev_gpio {
	DEV_GPIO_INFO gpio_info;		/*!< gpio device information */
	int32_t (*gpio_open) (uint32_t dir);	/*!< open gpio device with pre-defined gpio direction */
	int32_t (*gpio_close) (void);		/*!< close gpio device */
	int32_t (*gpio_control) (uint32_t ctrl_cmd, void *param);	/*!< control gpio device */
	int32_t (*gpio_write) (uint32_t val, uint32_t mask);	/*!< write gpio device with val, only write the masked bits */
	int32_t (*gpio_read) (uint32_t *val, uint32_t mask);	/*!< read gpio device val, only read the masked bits */
} DEV_GPIO, * DEV_GPIO_PTR;

/**
 * \fn		int32_t (* dev_gpio::gpio_open) (uint32_t dir)
 * \details	Open a gpio device with pre-defined io direction.
 * \param[in]	dir	gpio direction for each bit
 * \retval	E_OK	Open successfully without any issues
 * \retval	E_OPNED	If device was opened before with different parameters,
 *			then just increase the \ref dev_gpio_info::opn_cnt "opn_cnt" and return \ref E_OPNED
 * \retval	E_OBJ	Device object is not valid
 * \retval	E_PAR	Parameter is not valid
 * \retval	E_NOSPT	Open settings are not supported
 */

/**
 * \fn		int32_t (* dev_gpio::gpio_close) (void)
 * \details	Close an gpio device, just decrease the \ref dev_gpio_info::opn_cnt "opn_cnt",
 *      if \ref dev_gpio_info::opn_cnt "opn_cnt" equals 0, then close the device
 * \retval	E_OK	Close successfully without any issues(including scenario that device is already closed)
 * \retval	E_OPNED	Device is still opened, the device \ref dev_gpio_info::opn_cnt "opn_cnt" decreased by 1
 * \retval	E_OBJ	Device object is not valid
 */

/**
 * \fn		int32_t (* dev_gpio::gpio_control) (uint32_t ctrl_cmd, void *param)
 * \details	Control an gpio device by \ref ctrl_cmd, with passed \ref param.
 * 	you can control gpio device using predefined gpio control commands defined using \ref DEV_SET_SYSCMD
 * 	(which must be implemented by bsp developer), such as \ref GPIO_CMD_SET_BIT_DIR_INPUT
 * 	"change masked gpio direction to input", and \ref DEVICE_HAL_GPIO_CTRLCMD "more".
 * 	And you can also control gpio device using your own specified commands defined using \ref DEV_SET_USRCMD,
 * 	but these specified commands should be defined in your own gpio device driver implementation.
 * \param[in]		ctrl_cmd	\ref DEVICE_HAL_GPIO_CTRLCMD "control command", to change or get some thing related to gpio
 * \param[in,out]	param		parameters that maybe argument of the command, or return values of the command
 * \retval	E_OK	Control device successfully
 * \retval	E_CLSED	Device is not opened
 * \retval	E_OBJ	Device object is not valid or not exists
 * \retval	E_PAR	Parameter is not valid for current control command
 * \retval	E_SYS	Control device failed, due to hardware issues
 * \retval	E_CTX	Control device failed, due to different reasons like in transfer state
 * \retval	E_NOSPT	Control command is not supported or not valid, such as interrupt is not supported
 */

/**
 * \fn		int32_t (* dev_gpio::gpio_write) (uint32_t val, uint32_t mask)
 * \details	Write gpio with \ref val, and only change the masked bits of gpio.
 * \param[in]	val	the data that need to write to gpio
 * \param[in]	mask	gpio bit mask
 * \retval	E_OK	Write gpio with specified value successfully
 * \retval	E_OBJ	Device object is not valid or not exists
 * \retval	E_PAR	Parameter is not valid
 */

/**
 * \fn		int32_t (* dev_gpio::gpio_read) (uint32_t *val, uint32_t mask)
 * \details	Read the masked gpio value
 * \param[out]	val	pointer to data need to read from gpio
 * \param[in]	mask	gpio bit mask
 * \retval	E_OK	Read gpio data successfully
 * \retval	E_OBJ	Device object is not valid or not exists
 * \retval	E_PAR	Parameter is not valid
 */

/** @} */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \brief	get an \ref dev_gpio "gpio device" by gpio device id.
 * 	For how to use gpio device hal refer to \ref dev_gpio "Functions in gpio device structure"
 * \param[in]	gpio_id	id of gpio, defined by user
 * \retval	!NULL	pointer to an \ref dev_gpio "gpio device structure"
 * \retval	NULL	failed to find the gpio device by \ref gpio_id
 * \note	need to implemented by user in user code
 */
extern DEV_GPIO_PTR gpio_get_dev(int32_t gpio_id);

#ifdef __cplusplus
}
#endif

/** @} */
#endif /* _DEVICE_HAL_GPIO_H_ */