git.sur5r.net Git - freertos/blob - Demo/AVR32_UC3/DRIVERS/GPIO/gpio.h

   1 /*This file has been prepared for Doxygen automatic documentation generation.*/\r
   2 /*! \file *********************************************************************\r
   3  *\r
   4  * \brief GPIO header for AVR32 UC3.\r
   5  *\r
   6  * This file contains basic GPIO driver functions.\r
   7  *\r
   8  * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32\r
   9  * - Supported devices:  All AVR32 devices with a GPIO module can be used.\r
  10  * - AppNote:\r
  11  *\r
  12  * \author               Atmel Corporation: http://www.atmel.com \n\r
  13  *                       Support and FAQ: http://support.atmel.no/\r
  14  *\r
  15  *****************************************************************************/\r
  16 \r
  17 /* Copyright (c) 2007, Atmel Corporation All rights reserved.\r
  18  *\r
  19  * Redistribution and use in source and binary forms, with or without\r
  20  * modification, are permitted provided that the following conditions are met:\r
  21  *\r
  22  * 1. Redistributions of source code must retain the above copyright notice,\r
  23  * this list of conditions and the following disclaimer.\r
  24  *\r
  25  * 2. Redistributions in binary form must reproduce the above copyright notice,\r
  26  * this list of conditions and the following disclaimer in the documentation\r
  27  * and/or other materials provided with the distribution.\r
  28  *\r
  29  * 3. The name of ATMEL may not be used to endorse or promote products derived\r
  30  * from this software without specific prior written permission.\r
  31  *\r
  32  * THIS SOFTWARE IS PROVIDED BY ATMEL ``AS IS'' AND ANY EXPRESS OR IMPLIED\r
  33  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  34  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY AND\r
  35  * SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT,\r
  36  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\r
  37  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\r
  38  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND\r
  39  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\r
  40  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF\r
  41  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
  42  */\r
  43 \r
  44 \r
  45 #ifndef _GPIO_H_\r
  46 #define _GPIO_H_\r
  47 \r
  48 #include <avr32/io.h>\r
  49 \r
  50 \r
  51 /*! \name Return Values of the GPIO API\r
  52  */\r
  53 //! @{\r
  54 #define GPIO_SUCCESS            0 //!< Function successfully completed.\r
  55 #define GPIO_INVALID_ARGUMENT   1 //!< Input parameters are out of range.\r
  56 //! @}\r
  57 \r
  58 \r
  59 /*! \name Interrupt Trigger Modes\r
  60  */\r
  61 //! @{\r
  62 #define GPIO_PIN_CHANGE         0 //!< Interrupt triggered upon pin change.\r
  63 #define GPIO_RISING_EDGE        1 //!< Interrupt triggered upon rising edge.\r
  64 #define GPIO_FALLING_EDGE       2 //!< Interrupt triggered upon falling edge.\r
  65 //! @}\r
  66 \r
  67 \r
  68 //! A type definition of pins and modules connectivity.\r
  69 typedef struct\r
  70 {\r
  71   unsigned char pin;              //!< Module pin.\r
  72   unsigned char function;         //!< Module function.\r
  73 } gpio_map_t[];\r
  74 \r
  75 \r
  76 /*! \brief Enables specific module modes for a set of pins.\r
  77  *\r
  78  * \param gpiomap The pin map.\r
  79  * \param size The number of pins in \a gpiomap.\r
  80  *\r
  81  * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.\r
  82  */\r
  83 extern int gpio_enable_module(const gpio_map_t gpiomap, unsigned int size);\r
  84 \r
  85 /*! \brief Enables a specific module mode for a pin.\r
  86  *\r
  87  * \param pin The pin number.\n\r
  88  *            Refer to the product header file `uc3x.h' (where x is the part\r
  89  *            number; e.g. x = a0512) for module pins. E.g., to enable a PWM\r
  90  *            channel output, the pin number can be AVR32_PWM_PWM_3_PIN for PWM\r
  91  *            channel 3.\r
  92  * \param function The pin function.\n\r
  93  *                 Refer to the product header file `uc3x.h' (where x is the\r
  94  *                 part number; e.g. x = a0512) for module pin functions. E.g.,\r
  95  *                 to enable a PWM channel output, the pin function can be\r
  96  *                 AVR32_PWM_PWM_3_FUNCTION for PWM channel 3.\r
  97  *\r
  98  * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.\r
  99  */\r
 100 extern int gpio_enable_module_pin(unsigned int pin, unsigned int function);\r
 101 \r
 102 /*! \brief Enables the GPIO mode of a set of pins.\r
 103  *\r
 104  * \param gpiomap The pin map.\r
 105  * \param size The number of pins in \a gpiomap.\r
 106  */\r
 107 extern void gpio_enable_gpio(const gpio_map_t gpiomap, unsigned int size);\r
 108 \r
 109 /*! \brief Enables the GPIO mode of a pin.\r
 110  *\r
 111  * \param pin The pin number.\n\r
 112  *            Refer to the product header file `uc3x.h' (where x is the part\r
 113  *            number; e.g. x = a0512) for pin definitions. E.g., to enable the\r
 114  *            GPIO mode of PX21, AVR32_PIN_PX21 can be used. Module pins such as\r
 115  *            AVR32_PWM_PWM_3_PIN for PWM channel 3 can also be used to release\r
 116  *            module pins for GPIO.\r
 117  */\r
 118 extern void gpio_enable_gpio_pin(unsigned int pin);\r
 119 \r
 120 /*! \brief Enables the open-drain mode of a pin.\r
 121  *\r
 122  * \param pin The pin number.\r
 123  */\r
 124 extern void gpio_enable_pin_open_drain(unsigned int pin);\r
 125 \r
 126 /*! \brief Disables the open-drain mode of a pin.\r
 127  *\r
 128  * \param pin The pin number.\r
 129  */\r
 130 extern void gpio_disable_pin_open_drain(unsigned int pin);\r
 131 \r
 132 /*! \brief Enables the pull-up resistor of a pin.\r
 133  *\r
 134  * \param pin The pin number.\r
 135  */\r
 136 extern void gpio_enable_pin_pull_up(unsigned int pin);\r
 137 \r
 138 /*! \brief Disables the pull-up resistor of a pin.\r
 139  *\r
 140  * \param pin The pin number.\r
 141  */\r
 142 extern void gpio_disable_pin_pull_up(unsigned int pin);\r
 143 \r
 144 /*! \brief Returns the value of a pin.\r
 145  *\r
 146  * \param pin The pin number.\r
 147  *\r
 148  * \return The pin value.\r
 149  */\r
 150 extern int gpio_get_pin_value(unsigned int pin);\r
 151 \r
 152 /*! \brief Returns the output value set for a GPIO pin.\r
 153  *\r
 154  * \param pin The pin number.\r
 155  *\r
 156  * \return The pin output value.\r
 157  */\r
 158 extern int gpio_get_gpio_pin_output_value(unsigned int pin);\r
 159 \r
 160 /*! \brief Drives a GPIO pin to 1.\r
 161  *\r
 162  * \param pin The pin number.\r
 163  */\r
 164 extern void gpio_set_gpio_pin(unsigned int pin);\r
 165 \r
 166 /*! \brief Drives a GPIO pin to 0.\r
 167  *\r
 168  * \param pin The pin number.\r
 169  */\r
 170 extern void gpio_clr_gpio_pin(unsigned int pin);\r
 171 \r
 172 /*! \brief Toggles a GPIO pin.\r
 173  *\r
 174  * \param pin The pin number.\r
 175  */\r
 176 extern void gpio_tgl_gpio_pin(unsigned int pin);\r
 177 \r
 178 /*! \brief Enables the glitch filter of a pin.\r
 179  *\r
 180  * When the glitch filter is enabled, a glitch with duration of less than 1\r
 181  * clock cycle is automatically rejected, while a pulse with duration of 2 clock\r
 182  * cycles or more is accepted. For pulse durations between 1 clock cycle and 2\r
 183  * clock cycles, the pulse may or may not be taken into account, depending on\r
 184  * the precise timing of its occurrence. Thus for a pulse to be guaranteed\r
 185  * visible it must exceed 2 clock cycles, whereas for a glitch to be reliably\r
 186  * filtered out, its duration must not exceed 1 clock cycle. The filter\r
 187  * introduces 2 clock cycles latency.\r
 188  *\r
 189  * \param pin The pin number.\r
 190  */\r
 191 extern void gpio_enable_pin_glitch_filter(unsigned int pin);\r
 192 \r
 193 /*! \brief Disables the glitch filter of a pin.\r
 194  *\r
 195  * \param pin The pin number.\r
 196  */\r
 197 extern void gpio_disable_pin_glitch_filter(unsigned int pin);\r
 198 \r
 199 /*! \brief Enables the interrupt of a pin with the specified settings.\r
 200  *\r
 201  * \param pin The pin number.\r
 202  * \param mode The trigger mode (\ref GPIO_PIN_CHANGE, \ref GPIO_RISING_EDGE or\r
 203  *             \ref GPIO_FALLING_EDGE).\r
 204  *\r
 205  * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.\r
 206  */\r
 207 extern int gpio_enable_pin_interrupt(unsigned int pin, unsigned int mode);\r
 208 \r
 209 /*! \brief Disables the interrupt of a pin.\r
 210  *\r
 211  * \param pin The pin number.\r
 212  */\r
 213 extern void gpio_disable_pin_interrupt(unsigned int pin);\r
 214 \r
 215 /*! \brief Gets the interrupt flag of a pin.\r
 216  *\r
 217  * \param pin The pin number.\r
 218  *\r
 219  * \return The pin interrupt flag.\r
 220  */\r
 221 extern int gpio_get_pin_interrupt_flag(unsigned int pin);\r
 222 \r
 223 /*! \brief Clears the interrupt flag of a pin.\r
 224  *\r
 225  * \param pin The pin number.\r
 226  */\r
 227 extern void gpio_clear_pin_interrupt_flag(unsigned int pin);\r
 228 \r
 229 \r
 230 #endif  // _GPIO_H_\r