[freertos] / Demo / AVR32_UC3A_GCC / Atmel_SW_Framework / DRIVERS / GPIO / gpio.h

/* This header file is part of the ATMEL AVR-UC3-SoftwareFramework-1.7.0 Release */\r

/*This file has been prepared for Doxygen automatic documentation generation.*/\r
/*! \file *********************************************************************\r
 *\r
 * \brief GPIO header for AVR32 UC3.\r
 *\r
 * This file contains basic GPIO driver functions.\r
 *\r
 * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32\r
 * - Supported devices:  All AVR32 devices with a GPIO module can be used.\r
 * - AppNote:\r
 *\r
 * \author               Atmel Corporation: http://www.atmel.com \n\r
 *                       Support and FAQ: http://support.atmel.no/\r
 *\r
 *****************************************************************************/\r
\r
/* Copyright (c) 2009 Atmel Corporation. All rights reserved.\r
 *\r
 * Redistribution and use in source and binary forms, with or without\r
 * modification, are permitted provided that the following conditions are met:\r
 *\r
 * 1. Redistributions of source code must retain the above copyright notice, this\r
 * list of conditions and the following disclaimer.\r
 *\r
 * 2. Redistributions in binary form must reproduce the above copyright notice,\r
 * this list of conditions and the following disclaimer in the documentation\r
 * and/or other materials provided with the distribution.\r
 *\r
 * 3. The name of Atmel may not be used to endorse or promote products derived\r
 * from this software without specific prior written permission.\r
 *\r
 * 4. This software may only be redistributed and used in connection with an Atmel\r
 * AVR product.\r
 *\r
 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED\r
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR\r
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\r
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\r
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND\r
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\r
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\r
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\r
 *\r
 */\r
\r
#ifndef _GPIO_H_\r
#define _GPIO_H_\r
\r
#include <avr32/io.h>\r
#include "compiler.h"\r
\r
/*! \name Return Values of the GPIO API\r
 */\r
//! @{\r
#define GPIO_SUCCESS            0 //!< Function successfully completed.\r
#define GPIO_INVALID_ARGUMENT   1 //!< Input parameters are out of range.\r
//! @}\r
\r
\r
/*! \name Interrupt Trigger Modes\r
 */\r
//! @{\r
#define GPIO_PIN_CHANGE         0 //!< Interrupt triggered upon pin change.\r
#define GPIO_RISING_EDGE        1 //!< Interrupt triggered upon rising edge.\r
#define GPIO_FALLING_EDGE       2 //!< Interrupt triggered upon falling edge.\r
//! @}\r
\r
\r
//! A type definition of pins and modules connectivity.\r
typedef struct\r
{\r
  unsigned char pin;              //!< Module pin.\r
  unsigned char function;         //!< Module function.\r
} gpio_map_t[];\r
\r
\r
/*! \name Peripheral Bus Interface\r
 *\r
 * Low-speed interface with a non-deterministic number of clock cycles per\r
 * access.\r
 *\r
 * This interface operates with lower clock frequencies (fPB <= fCPU), and its\r
 * timing is not deterministic since it needs to access a shared bus which may\r
 * be heavily loaded.\r
 *\r
 * \note This interface is immediately available without initialization.\r
 */\r
//! @{\r
\r
/*! \brief Enables specific module modes for a set of pins.\r
 *\r
 * \param gpiomap The pin map.\r
 * \param size The number of pins in \a gpiomap.\r
 *\r
 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.\r
 */\r
extern int gpio_enable_module(const gpio_map_t gpiomap, unsigned int size);\r
\r
/*! \brief Enables a specific module mode for a pin.\r
 *\r
 * \param pin The pin number.\n\r
 *            Refer to the product header file `uc3x.h' (where x is the part\r
 *            number; e.g. x = a0512) for module pins. E.g., to enable a PWM\r
 *            channel output, the pin number can be AVR32_PWM_3_PIN for PWM\r
 *            channel 3.\r
 * \param function The pin function.\n\r
 *                 Refer to the product header file `uc3x.h' (where x is the\r
 *                 part number; e.g. x = a0512) for module pin functions. E.g.,\r
 *                 to enable a PWM channel output, the pin function can be\r
 *                 AVR32_PWM_3_FUNCTION for PWM channel 3.\r
 *\r
 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.\r
 */\r
extern int gpio_enable_module_pin(unsigned int pin, unsigned int function);\r
\r
/*! \brief Enables the GPIO mode of a set of pins.\r
 *\r
 * \param gpiomap The pin map.\r
 * \param size The number of pins in \a gpiomap.\r
 */\r
extern void gpio_enable_gpio(const gpio_map_t gpiomap, unsigned int size);\r
\r
/*! \brief Enables the GPIO mode of a pin.\r
 *\r
 * \param pin The pin number.\n\r
 *            Refer to the product header file `uc3x.h' (where x is the part\r
 *            number; e.g. x = a0512) for pin definitions. E.g., to enable the\r
 *            GPIO mode of PX21, AVR32_PIN_PX21 can be used. Module pins such as\r
 *            AVR32_PWM_3_PIN for PWM channel 3 can also be used to release\r
 *            module pins for GPIO.\r
 */\r
extern void gpio_enable_gpio_pin(unsigned int pin);\r
\r
// The open-drain mode is not synthesized on the current AVR32 products.\r
// If one day some AVR32 products have this feature, the corresponding part\r
// numbers should be listed in the #if below.\r
// Note that other functions are available in this driver to use pins with open\r
// drain in GPIO mode. The advantage of the open-drain mode functions over these\r
// other functions is that they can be used not only in GPIO mode but also in\r
// module mode.\r
#if 0\r
\r
/*! \brief Enables the open-drain mode of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_enable_pin_open_drain(unsigned int pin);\r
\r
/*! \brief Disables the open-drain mode of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_disable_pin_open_drain(unsigned int pin);\r
\r
#endif\r
\r
/*! \brief Enables the pull-up resistor of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_enable_pin_pull_up(unsigned int pin);\r
\r
/*! \brief Disables the pull-up resistor of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_disable_pin_pull_up(unsigned int pin);\r
\r
#if defined(AVR32_GPIO_200_H_INCLUDED) || defined(AVR32_GPIO_210_H_INCLUDED) || defined(AVR32_GPIO_211_H_INCLUDED)\r
// Added support of Pull-up Resistor, Pull-down Resistor and Buskeeper Control.\r
\r
/*! \brief Enables the pull-down resistor of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_enable_pin_pull_down(unsigned int pin);\r
\r
/*! \brief Disables the pull-down resistor of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_disable_pin_pull_down(unsigned int pin);\r
\r
/*! \brief Enables the buskeeper functionality on a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_enable_pin_buskeeper(unsigned int pin);\r
\r
/*! \brief Disables the buskeeper functionality on a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_disable_pin_buskeeper(unsigned int pin);\r
\r
#endif\r
\r
/*! \brief Returns the value of a pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \return The pin value.\r
 */\r
extern int gpio_get_pin_value(unsigned int pin);\r
\r
/*! \brief Returns the output value set for a GPIO pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \return The pin output value.\r
 *\r
 * \note This function must be used in conjunction with \ref gpio_set_gpio_pin,\r
 *       \ref gpio_clr_gpio_pin and \ref gpio_tgl_gpio_pin.\r
 */\r
extern int gpio_get_gpio_pin_output_value(unsigned int pin);\r
\r
/*! \brief Returns the output value set for a GPIO pin using open drain.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \return The pin output value.\r
 *\r
 * \note This function must be used in conjunction with\r
 *       \ref gpio_set_gpio_open_drain_pin, \ref gpio_clr_gpio_open_drain_pin\r
 *       and \ref gpio_tgl_gpio_open_drain_pin.\r
 */\r
extern int gpio_get_gpio_open_drain_pin_output_value(unsigned int pin);\r
\r
/*! \brief Drives a GPIO pin to 1.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_set_gpio_pin(unsigned int pin);\r
\r
/*! \brief Drives a GPIO pin to 0.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_clr_gpio_pin(unsigned int pin);\r
\r
/*! \brief Toggles a GPIO pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_tgl_gpio_pin(unsigned int pin);\r
\r
/*! \brief Drives a GPIO pin to 1 using open drain.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_set_gpio_open_drain_pin(unsigned int pin);\r
\r
/*! \brief Drives a GPIO pin to 0 using open drain.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_clr_gpio_open_drain_pin(unsigned int pin);\r
\r
/*! \brief Toggles a GPIO pin using open drain.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_tgl_gpio_open_drain_pin(unsigned int pin);\r
\r
/*! \brief Enables the glitch filter of a pin.\r
 *\r
 * When the glitch filter is enabled, a glitch with duration of less than 1\r
 * clock cycle is automatically rejected, while a pulse with duration of 2 clock\r
 * cycles or more is accepted. For pulse durations between 1 clock cycle and 2\r
 * clock cycles, the pulse may or may not be taken into account, depending on\r
 * the precise timing of its occurrence. Thus for a pulse to be guaranteed\r
 * visible it must exceed 2 clock cycles, whereas for a glitch to be reliably\r
 * filtered out, its duration must not exceed 1 clock cycle. The filter\r
 * introduces 2 clock cycles latency.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_enable_pin_glitch_filter(unsigned int pin);\r
\r
/*! \brief Disables the glitch filter of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_disable_pin_glitch_filter(unsigned int pin);\r
\r
/*! \brief Enables the interrupt of a pin with the specified settings.\r
 *\r
 * \param pin The pin number.\r
 * \param mode The trigger mode (\ref GPIO_PIN_CHANGE, \ref GPIO_RISING_EDGE or\r
 *             \ref GPIO_FALLING_EDGE).\r
 *\r
 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.\r
 */\r
extern int gpio_enable_pin_interrupt(unsigned int pin, unsigned int mode);\r
\r
/*! \brief Disables the interrupt of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_disable_pin_interrupt(unsigned int pin);\r
\r
/*! \brief Gets the interrupt flag of a pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \return The pin interrupt flag.\r
 */\r
extern int gpio_get_pin_interrupt_flag(unsigned int pin);\r
\r
/*! \brief Clears the interrupt flag of a pin.\r
 *\r
 * \param pin The pin number.\r
 */\r
extern void gpio_clear_pin_interrupt_flag(unsigned int pin);\r
\r
//! @}\r
\r
\r
#if (defined AVR32_GPIO_LOCAL_ADDRESS)\r
/*! \name Local Bus Interface\r
 *\r
 * High-speed interface with only one clock cycle per access.\r
 *\r
 * This interface operates with high clock frequency (fCPU), and its timing is\r
 * deterministic since it does not need to access a shared bus which may be\r
 * heavily loaded.\r
 *\r
 * \warning To use this interface, the clock frequency of the peripheral bus on\r
 *          which the GPIO peripheral is connected must be set to the CPU clock\r
 *          frequency (fPB = fCPU).\r
 *\r
 * \note This interface has to be initialized in order to be available.\r
 */\r
//! @{\r
\r
/*! \brief Enables the local bus interface for GPIO.\r
 *\r
 * \note This function must have been called at least once before using other\r
 *       functions in this interface.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_init(void)\r
{\r
  Set_system_register(AVR32_CPUCR,\r
                      Get_system_register(AVR32_CPUCR) | AVR32_CPUCR_LOCEN_MASK);\r
}\r
\r
/*! \brief Enables the output driver of a pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init must have been called beforehand.\r
 *\r
 * \note This function does not enable the GPIO mode of the pin.\r
 *       \ref gpio_enable_gpio_pin can be called for this purpose.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_enable_pin_output_driver(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].oders = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Disables the output driver of a pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init must have been called beforehand.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_disable_pin_output_driver(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].oderc = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Returns the value of a pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \return The pin value.\r
 *\r
 * \note \ref gpio_local_init must have been called beforehand.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ int gpio_local_get_pin_value(unsigned int pin)\r
{\r
  return (AVR32_GPIO_LOCAL.port[pin >> 5].pvr >> (pin & 0x1F)) & 1;\r
}\r
\r
/*! \brief Drives a GPIO pin to 1.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init must have been called beforehand.\r
 *\r
 * \note This function does not enable the GPIO mode of the pin nor its output\r
 *       driver. \ref gpio_enable_gpio_pin and\r
 *       \ref gpio_local_enable_pin_output_driver can be called for this\r
 *       purpose.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_set_gpio_pin(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].ovrs = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Drives a GPIO pin to 0.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init must have been called beforehand.\r
 *\r
 * \note This function does not enable the GPIO mode of the pin nor its output\r
 *       driver. \ref gpio_enable_gpio_pin and\r
 *       \ref gpio_local_enable_pin_output_driver can be called for this\r
 *       purpose.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_clr_gpio_pin(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].ovrc = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Toggles a GPIO pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init must have been called beforehand.\r
 *\r
 * \note This function does not enable the GPIO mode of the pin nor its output\r
 *       driver. \ref gpio_enable_gpio_pin and\r
 *       \ref gpio_local_enable_pin_output_driver can be called for this\r
 *       purpose.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_tgl_gpio_pin(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].ovrt = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Initializes the configuration of a GPIO pin so that it can be used\r
 *         with GPIO open-drain functions.\r
 *\r
 * \note This function must have been called at least once before using\r
 *       \ref gpio_local_set_gpio_open_drain_pin,\r
 *       \ref gpio_local_clr_gpio_open_drain_pin or\r
 *       \ref gpio_local_tgl_gpio_open_drain_pin.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_init_gpio_open_drain_pin(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].ovrc = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Drives a GPIO pin to 1 using open drain.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must\r
 *       have been called beforehand.\r
 *\r
 * \note This function does not enable the GPIO mode of the pin.\r
 *       \ref gpio_enable_gpio_pin can be called for this purpose.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_set_gpio_open_drain_pin(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].oderc = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Drives a GPIO pin to 0 using open drain.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must\r
 *       have been called beforehand.\r
 *\r
 * \note This function does not enable the GPIO mode of the pin.\r
 *       \ref gpio_enable_gpio_pin can be called for this purpose.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_clr_gpio_open_drain_pin(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].oders = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Toggles a GPIO pin using open drain.\r
 *\r
 * \param pin The pin number.\r
 *\r
 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must\r
 *       have been called beforehand.\r
 *\r
 * \note This function does not enable the GPIO mode of the pin.\r
 *       \ref gpio_enable_gpio_pin can be called for this purpose.\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_local_tgl_gpio_open_drain_pin(unsigned int pin)\r
{\r
  AVR32_GPIO_LOCAL.port[pin >> 5].odert = 1 << (pin & 0x1F);\r
}\r
\r
//! @}\r
#endif // AVR32_GPIO_LOCAL_ADDRESS\r
\r
#if UC3L\r
//! @{\r
/*! \name Peripheral Event System support\r
 *\r
 * The GPIO can be programmed to output peripheral events whenever an interrupt\r
 * condition is detected, such as pin value change, or only when a rising or\r
 * falling edge is detected.\r
 *\r
 */\r
\r
/*! \brief Enables the peripheral event generation of a pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_enable_pin_periph_event(unsigned int pin)\r
{\r
  AVR32_GPIO.port[pin >> 5].oderc = 1 << (pin & 0x1F); // The GPIO output driver is disabled for that pin.\r
  AVR32_GPIO.port[pin >> 5].evers = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Disables the peripheral event generation of a pin.\r
 *\r
 * \param pin The pin number.\r
 *\r
 */\r
#if (defined __GNUC__)\r
__attribute__((__always_inline__))\r
#endif\r
extern __inline__ void gpio_disable_pin_periph_event(unsigned int pin)\r
{\r
  AVR32_GPIO.port[pin >> 5].everc = 1 << (pin & 0x1F);\r
}\r
\r
/*! \brief Configure the peripheral event trigger mode of a pin\r
 *\r
 * \param pin The pin number.\r
 * \param mode The trigger mode (\ref GPIO_PIN_CHANGE, \ref GPIO_RISING_EDGE or\r
 *             \ref GPIO_FALLING_EDGE).\r
 * \param use_igf use the Input Glitch Filter (TRUE) or not (FALSE).\r
 *\r
 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.\r
 */\r
extern int gpio_configure_pin_periph_event_mode(unsigned int pin, unsigned int mode, unsigned int use_igf);\r
\r
//! @}\r
#endif\r
\r
\r
#endif  // _GPIO_H_\r