1 /* This header file is part of the ATMEL AVR-UC3-SoftwareFramework-1.7.0 Release */
\r
3 /*This file has been prepared for Doxygen automatic documentation generation.*/
\r
4 /*! \file *********************************************************************
\r
6 * \brief GPIO header for AVR32 UC3.
\r
8 * This file contains basic GPIO driver functions.
\r
10 * - Compiler: IAR EWAVR32 and GNU GCC for AVR32
\r
11 * - Supported devices: All AVR32 devices with a GPIO module can be used.
\r
14 * \author Atmel Corporation: http://www.atmel.com \n
\r
15 * Support and FAQ: http://support.atmel.no/
\r
17 *****************************************************************************/
\r
19 /* Copyright (c) 2009 Atmel Corporation. All rights reserved.
\r
21 * Redistribution and use in source and binary forms, with or without
\r
22 * modification, are permitted provided that the following conditions are met:
\r
24 * 1. Redistributions of source code must retain the above copyright notice, this
\r
25 * list of conditions and the following disclaimer.
\r
27 * 2. Redistributions in binary form must reproduce the above copyright notice,
\r
28 * this list of conditions and the following disclaimer in the documentation
\r
29 * and/or other materials provided with the distribution.
\r
31 * 3. The name of Atmel may not be used to endorse or promote products derived
\r
32 * from this software without specific prior written permission.
\r
34 * 4. This software may only be redistributed and used in connection with an Atmel
\r
37 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
\r
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
\r
39 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
\r
40 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
\r
41 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
\r
42 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
\r
43 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
\r
44 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
\r
45 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
\r
46 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
\r
53 #include <avr32/io.h>
\r
54 #include "compiler.h"
\r
56 /*! \name Return Values of the GPIO API
\r
59 #define GPIO_SUCCESS 0 //!< Function successfully completed.
\r
60 #define GPIO_INVALID_ARGUMENT 1 //!< Input parameters are out of range.
\r
64 /*! \name Interrupt Trigger Modes
\r
67 #define GPIO_PIN_CHANGE 0 //!< Interrupt triggered upon pin change.
\r
68 #define GPIO_RISING_EDGE 1 //!< Interrupt triggered upon rising edge.
\r
69 #define GPIO_FALLING_EDGE 2 //!< Interrupt triggered upon falling edge.
\r
73 //! A type definition of pins and modules connectivity.
\r
76 unsigned char pin; //!< Module pin.
\r
77 unsigned char function; //!< Module function.
\r
81 /*! \name Peripheral Bus Interface
\r
83 * Low-speed interface with a non-deterministic number of clock cycles per
\r
86 * This interface operates with lower clock frequencies (fPB <= fCPU), and its
\r
87 * timing is not deterministic since it needs to access a shared bus which may
\r
88 * be heavily loaded.
\r
90 * \note This interface is immediately available without initialization.
\r
94 /*! \brief Enables specific module modes for a set of pins.
\r
96 * \param gpiomap The pin map.
\r
97 * \param size The number of pins in \a gpiomap.
\r
99 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
\r
101 extern int gpio_enable_module(const gpio_map_t gpiomap, unsigned int size);
\r
103 /*! \brief Enables a specific module mode for a pin.
\r
105 * \param pin The pin number.\n
\r
106 * Refer to the product header file `uc3x.h' (where x is the part
\r
107 * number; e.g. x = a0512) for module pins. E.g., to enable a PWM
\r
108 * channel output, the pin number can be AVR32_PWM_3_PIN for PWM
\r
110 * \param function The pin function.\n
\r
111 * Refer to the product header file `uc3x.h' (where x is the
\r
112 * part number; e.g. x = a0512) for module pin functions. E.g.,
\r
113 * to enable a PWM channel output, the pin function can be
\r
114 * AVR32_PWM_3_FUNCTION for PWM channel 3.
\r
116 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
\r
118 extern int gpio_enable_module_pin(unsigned int pin, unsigned int function);
\r
120 /*! \brief Enables the GPIO mode of a set of pins.
\r
122 * \param gpiomap The pin map.
\r
123 * \param size The number of pins in \a gpiomap.
\r
125 extern void gpio_enable_gpio(const gpio_map_t gpiomap, unsigned int size);
\r
127 /*! \brief Enables the GPIO mode of a pin.
\r
129 * \param pin The pin number.\n
\r
130 * Refer to the product header file `uc3x.h' (where x is the part
\r
131 * number; e.g. x = a0512) for pin definitions. E.g., to enable the
\r
132 * GPIO mode of PX21, AVR32_PIN_PX21 can be used. Module pins such as
\r
133 * AVR32_PWM_3_PIN for PWM channel 3 can also be used to release
\r
134 * module pins for GPIO.
\r
136 extern void gpio_enable_gpio_pin(unsigned int pin);
\r
138 // The open-drain mode is not synthesized on the current AVR32 products.
\r
139 // If one day some AVR32 products have this feature, the corresponding part
\r
140 // numbers should be listed in the #if below.
\r
141 // Note that other functions are available in this driver to use pins with open
\r
142 // drain in GPIO mode. The advantage of the open-drain mode functions over these
\r
143 // other functions is that they can be used not only in GPIO mode but also in
\r
147 /*! \brief Enables the open-drain mode of a pin.
\r
149 * \param pin The pin number.
\r
151 extern void gpio_enable_pin_open_drain(unsigned int pin);
\r
153 /*! \brief Disables the open-drain mode of a pin.
\r
155 * \param pin The pin number.
\r
157 extern void gpio_disable_pin_open_drain(unsigned int pin);
\r
161 /*! \brief Enables the pull-up resistor of a pin.
\r
163 * \param pin The pin number.
\r
165 extern void gpio_enable_pin_pull_up(unsigned int pin);
\r
167 /*! \brief Disables the pull-up resistor of a pin.
\r
169 * \param pin The pin number.
\r
171 extern void gpio_disable_pin_pull_up(unsigned int pin);
\r
173 #if defined(AVR32_GPIO_200_H_INCLUDED) || defined(AVR32_GPIO_210_H_INCLUDED) || defined(AVR32_GPIO_211_H_INCLUDED)
\r
174 // Added support of Pull-up Resistor, Pull-down Resistor and Buskeeper Control.
\r
176 /*! \brief Enables the pull-down resistor of a pin.
\r
178 * \param pin The pin number.
\r
180 extern void gpio_enable_pin_pull_down(unsigned int pin);
\r
182 /*! \brief Disables the pull-down resistor of a pin.
\r
184 * \param pin The pin number.
\r
186 extern void gpio_disable_pin_pull_down(unsigned int pin);
\r
188 /*! \brief Enables the buskeeper functionality on a pin.
\r
190 * \param pin The pin number.
\r
192 extern void gpio_enable_pin_buskeeper(unsigned int pin);
\r
194 /*! \brief Disables the buskeeper functionality on a pin.
\r
196 * \param pin The pin number.
\r
198 extern void gpio_disable_pin_buskeeper(unsigned int pin);
\r
202 /*! \brief Returns the value of a pin.
\r
204 * \param pin The pin number.
\r
206 * \return The pin value.
\r
208 extern int gpio_get_pin_value(unsigned int pin);
\r
210 /*! \brief Returns the output value set for a GPIO pin.
\r
212 * \param pin The pin number.
\r
214 * \return The pin output value.
\r
216 * \note This function must be used in conjunction with \ref gpio_set_gpio_pin,
\r
217 * \ref gpio_clr_gpio_pin and \ref gpio_tgl_gpio_pin.
\r
219 extern int gpio_get_gpio_pin_output_value(unsigned int pin);
\r
221 /*! \brief Returns the output value set for a GPIO pin using open drain.
\r
223 * \param pin The pin number.
\r
225 * \return The pin output value.
\r
227 * \note This function must be used in conjunction with
\r
228 * \ref gpio_set_gpio_open_drain_pin, \ref gpio_clr_gpio_open_drain_pin
\r
229 * and \ref gpio_tgl_gpio_open_drain_pin.
\r
231 extern int gpio_get_gpio_open_drain_pin_output_value(unsigned int pin);
\r
233 /*! \brief Drives a GPIO pin to 1.
\r
235 * \param pin The pin number.
\r
237 extern void gpio_set_gpio_pin(unsigned int pin);
\r
239 /*! \brief Drives a GPIO pin to 0.
\r
241 * \param pin The pin number.
\r
243 extern void gpio_clr_gpio_pin(unsigned int pin);
\r
245 /*! \brief Toggles a GPIO pin.
\r
247 * \param pin The pin number.
\r
249 extern void gpio_tgl_gpio_pin(unsigned int pin);
\r
251 /*! \brief Drives a GPIO pin to 1 using open drain.
\r
253 * \param pin The pin number.
\r
255 extern void gpio_set_gpio_open_drain_pin(unsigned int pin);
\r
257 /*! \brief Drives a GPIO pin to 0 using open drain.
\r
259 * \param pin The pin number.
\r
261 extern void gpio_clr_gpio_open_drain_pin(unsigned int pin);
\r
263 /*! \brief Toggles a GPIO pin using open drain.
\r
265 * \param pin The pin number.
\r
267 extern void gpio_tgl_gpio_open_drain_pin(unsigned int pin);
\r
269 /*! \brief Enables the glitch filter of a pin.
\r
271 * When the glitch filter is enabled, a glitch with duration of less than 1
\r
272 * clock cycle is automatically rejected, while a pulse with duration of 2 clock
\r
273 * cycles or more is accepted. For pulse durations between 1 clock cycle and 2
\r
274 * clock cycles, the pulse may or may not be taken into account, depending on
\r
275 * the precise timing of its occurrence. Thus for a pulse to be guaranteed
\r
276 * visible it must exceed 2 clock cycles, whereas for a glitch to be reliably
\r
277 * filtered out, its duration must not exceed 1 clock cycle. The filter
\r
278 * introduces 2 clock cycles latency.
\r
280 * \param pin The pin number.
\r
282 extern void gpio_enable_pin_glitch_filter(unsigned int pin);
\r
284 /*! \brief Disables the glitch filter of a pin.
\r
286 * \param pin The pin number.
\r
288 extern void gpio_disable_pin_glitch_filter(unsigned int pin);
\r
290 /*! \brief Enables the interrupt of a pin with the specified settings.
\r
292 * \param pin The pin number.
\r
293 * \param mode The trigger mode (\ref GPIO_PIN_CHANGE, \ref GPIO_RISING_EDGE or
\r
294 * \ref GPIO_FALLING_EDGE).
\r
296 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
\r
298 extern int gpio_enable_pin_interrupt(unsigned int pin, unsigned int mode);
\r
300 /*! \brief Disables the interrupt of a pin.
\r
302 * \param pin The pin number.
\r
304 extern void gpio_disable_pin_interrupt(unsigned int pin);
\r
306 /*! \brief Gets the interrupt flag of a pin.
\r
308 * \param pin The pin number.
\r
310 * \return The pin interrupt flag.
\r
312 extern int gpio_get_pin_interrupt_flag(unsigned int pin);
\r
314 /*! \brief Clears the interrupt flag of a pin.
\r
316 * \param pin The pin number.
\r
318 extern void gpio_clear_pin_interrupt_flag(unsigned int pin);
\r
323 #if (defined AVR32_GPIO_LOCAL_ADDRESS)
\r
324 /*! \name Local Bus Interface
\r
326 * High-speed interface with only one clock cycle per access.
\r
328 * This interface operates with high clock frequency (fCPU), and its timing is
\r
329 * deterministic since it does not need to access a shared bus which may be
\r
332 * \warning To use this interface, the clock frequency of the peripheral bus on
\r
333 * which the GPIO peripheral is connected must be set to the CPU clock
\r
334 * frequency (fPB = fCPU).
\r
336 * \note This interface has to be initialized in order to be available.
\r
340 /*! \brief Enables the local bus interface for GPIO.
\r
342 * \note This function must have been called at least once before using other
\r
343 * functions in this interface.
\r
345 #if (defined __GNUC__)
\r
346 __attribute__((__always_inline__))
\r
348 extern __inline__ void gpio_local_init(void)
\r
350 Set_system_register(AVR32_CPUCR,
\r
351 Get_system_register(AVR32_CPUCR) | AVR32_CPUCR_LOCEN_MASK);
\r
354 /*! \brief Enables the output driver of a pin.
\r
356 * \param pin The pin number.
\r
358 * \note \ref gpio_local_init must have been called beforehand.
\r
360 * \note This function does not enable the GPIO mode of the pin.
\r
361 * \ref gpio_enable_gpio_pin can be called for this purpose.
\r
363 #if (defined __GNUC__)
\r
364 __attribute__((__always_inline__))
\r
366 extern __inline__ void gpio_local_enable_pin_output_driver(unsigned int pin)
\r
368 AVR32_GPIO_LOCAL.port[pin >> 5].oders = 1 << (pin & 0x1F);
\r
371 /*! \brief Disables the output driver of a pin.
\r
373 * \param pin The pin number.
\r
375 * \note \ref gpio_local_init must have been called beforehand.
\r
377 #if (defined __GNUC__)
\r
378 __attribute__((__always_inline__))
\r
380 extern __inline__ void gpio_local_disable_pin_output_driver(unsigned int pin)
\r
382 AVR32_GPIO_LOCAL.port[pin >> 5].oderc = 1 << (pin & 0x1F);
\r
385 /*! \brief Returns the value of a pin.
\r
387 * \param pin The pin number.
\r
389 * \return The pin value.
\r
391 * \note \ref gpio_local_init must have been called beforehand.
\r
393 #if (defined __GNUC__)
\r
394 __attribute__((__always_inline__))
\r
396 extern __inline__ int gpio_local_get_pin_value(unsigned int pin)
\r
398 return (AVR32_GPIO_LOCAL.port[pin >> 5].pvr >> (pin & 0x1F)) & 1;
\r
401 /*! \brief Drives a GPIO pin to 1.
\r
403 * \param pin The pin number.
\r
405 * \note \ref gpio_local_init must have been called beforehand.
\r
407 * \note This function does not enable the GPIO mode of the pin nor its output
\r
408 * driver. \ref gpio_enable_gpio_pin and
\r
409 * \ref gpio_local_enable_pin_output_driver can be called for this
\r
412 #if (defined __GNUC__)
\r
413 __attribute__((__always_inline__))
\r
415 extern __inline__ void gpio_local_set_gpio_pin(unsigned int pin)
\r
417 AVR32_GPIO_LOCAL.port[pin >> 5].ovrs = 1 << (pin & 0x1F);
\r
420 /*! \brief Drives a GPIO pin to 0.
\r
422 * \param pin The pin number.
\r
424 * \note \ref gpio_local_init must have been called beforehand.
\r
426 * \note This function does not enable the GPIO mode of the pin nor its output
\r
427 * driver. \ref gpio_enable_gpio_pin and
\r
428 * \ref gpio_local_enable_pin_output_driver can be called for this
\r
431 #if (defined __GNUC__)
\r
432 __attribute__((__always_inline__))
\r
434 extern __inline__ void gpio_local_clr_gpio_pin(unsigned int pin)
\r
436 AVR32_GPIO_LOCAL.port[pin >> 5].ovrc = 1 << (pin & 0x1F);
\r
439 /*! \brief Toggles a GPIO pin.
\r
441 * \param pin The pin number.
\r
443 * \note \ref gpio_local_init must have been called beforehand.
\r
445 * \note This function does not enable the GPIO mode of the pin nor its output
\r
446 * driver. \ref gpio_enable_gpio_pin and
\r
447 * \ref gpio_local_enable_pin_output_driver can be called for this
\r
450 #if (defined __GNUC__)
\r
451 __attribute__((__always_inline__))
\r
453 extern __inline__ void gpio_local_tgl_gpio_pin(unsigned int pin)
\r
455 AVR32_GPIO_LOCAL.port[pin >> 5].ovrt = 1 << (pin & 0x1F);
\r
458 /*! \brief Initializes the configuration of a GPIO pin so that it can be used
\r
459 * with GPIO open-drain functions.
\r
461 * \note This function must have been called at least once before using
\r
462 * \ref gpio_local_set_gpio_open_drain_pin,
\r
463 * \ref gpio_local_clr_gpio_open_drain_pin or
\r
464 * \ref gpio_local_tgl_gpio_open_drain_pin.
\r
466 #if (defined __GNUC__)
\r
467 __attribute__((__always_inline__))
\r
469 extern __inline__ void gpio_local_init_gpio_open_drain_pin(unsigned int pin)
\r
471 AVR32_GPIO_LOCAL.port[pin >> 5].ovrc = 1 << (pin & 0x1F);
\r
474 /*! \brief Drives a GPIO pin to 1 using open drain.
\r
476 * \param pin The pin number.
\r
478 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must
\r
479 * have been called beforehand.
\r
481 * \note This function does not enable the GPIO mode of the pin.
\r
482 * \ref gpio_enable_gpio_pin can be called for this purpose.
\r
484 #if (defined __GNUC__)
\r
485 __attribute__((__always_inline__))
\r
487 extern __inline__ void gpio_local_set_gpio_open_drain_pin(unsigned int pin)
\r
489 AVR32_GPIO_LOCAL.port[pin >> 5].oderc = 1 << (pin & 0x1F);
\r
492 /*! \brief Drives a GPIO pin to 0 using open drain.
\r
494 * \param pin The pin number.
\r
496 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must
\r
497 * have been called beforehand.
\r
499 * \note This function does not enable the GPIO mode of the pin.
\r
500 * \ref gpio_enable_gpio_pin can be called for this purpose.
\r
502 #if (defined __GNUC__)
\r
503 __attribute__((__always_inline__))
\r
505 extern __inline__ void gpio_local_clr_gpio_open_drain_pin(unsigned int pin)
\r
507 AVR32_GPIO_LOCAL.port[pin >> 5].oders = 1 << (pin & 0x1F);
\r
510 /*! \brief Toggles a GPIO pin using open drain.
\r
512 * \param pin The pin number.
\r
514 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must
\r
515 * have been called beforehand.
\r
517 * \note This function does not enable the GPIO mode of the pin.
\r
518 * \ref gpio_enable_gpio_pin can be called for this purpose.
\r
520 #if (defined __GNUC__)
\r
521 __attribute__((__always_inline__))
\r
523 extern __inline__ void gpio_local_tgl_gpio_open_drain_pin(unsigned int pin)
\r
525 AVR32_GPIO_LOCAL.port[pin >> 5].odert = 1 << (pin & 0x1F);
\r
529 #endif // AVR32_GPIO_LOCAL_ADDRESS
\r
533 /*! \name Peripheral Event System support
\r
535 * The GPIO can be programmed to output peripheral events whenever an interrupt
\r
536 * condition is detected, such as pin value change, or only when a rising or
\r
537 * falling edge is detected.
\r
541 /*! \brief Enables the peripheral event generation of a pin.
\r
543 * \param pin The pin number.
\r
546 #if (defined __GNUC__)
\r
547 __attribute__((__always_inline__))
\r
549 extern __inline__ void gpio_enable_pin_periph_event(unsigned int pin)
\r
551 AVR32_GPIO.port[pin >> 5].oderc = 1 << (pin & 0x1F); // The GPIO output driver is disabled for that pin.
\r
552 AVR32_GPIO.port[pin >> 5].evers = 1 << (pin & 0x1F);
\r
555 /*! \brief Disables the peripheral event generation of a pin.
\r
557 * \param pin The pin number.
\r
560 #if (defined __GNUC__)
\r
561 __attribute__((__always_inline__))
\r
563 extern __inline__ void gpio_disable_pin_periph_event(unsigned int pin)
\r
565 AVR32_GPIO.port[pin >> 5].everc = 1 << (pin & 0x1F);
\r
568 /*! \brief Configure the peripheral event trigger mode of a pin
\r
570 * \param pin The pin number.
\r
571 * \param mode The trigger mode (\ref GPIO_PIN_CHANGE, \ref GPIO_RISING_EDGE or
\r
572 * \ref GPIO_FALLING_EDGE).
\r
573 * \param use_igf use the Input Glitch Filter (TRUE) or not (FALSE).
\r
575 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
\r
577 extern int gpio_configure_pin_periph_event_mode(unsigned int pin, unsigned int mode, unsigned int use_igf);
\r