source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/arduino/avr/firmwares/wifishield/wifiHD/src/SOFTWARE_FRAMEWORK/DRIVERS/GPIO/gpio.h @ 4837

Last change on this file since 4837 was 4837, checked in by daduve, 2 years ago

Adding new version

File size: 17.7 KB
Line 
1/* This header file is part of the ATMEL AVR-UC3-SoftwareFramework-1.7.0 Release */
2
3/*This file has been prepared for Doxygen automatic documentation generation.*/
4/*! \file *********************************************************************
5 *
6 * \brief GPIO header for AVR32 UC3.
7 *
8 * This file contains basic GPIO driver functions.
9 *
10 * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32
11 * - Supported devices:  All AVR32 devices with a GPIO module can be used.
12 * - AppNote:
13 *
14 * \author               Atmel Corporation: http://www.atmel.com \n
15 *                       Support and FAQ: http://support.atmel.no/
16 *
17 *****************************************************************************/
18
19/* Copyright (c) 2009 Atmel Corporation. All rights reserved.
20 *
21 * Redistribution and use in source and binary forms, with or without
22 * modification, are permitted provided that the following conditions are met:
23 *
24 * 1. Redistributions of source code must retain the above copyright notice, this
25 * list of conditions and the following disclaimer.
26 *
27 * 2. Redistributions in binary form must reproduce the above copyright notice,
28 * this list of conditions and the following disclaimer in the documentation
29 * and/or other materials provided with the distribution.
30 *
31 * 3. The name of Atmel may not be used to endorse or promote products derived
32 * from this software without specific prior written permission.
33 *
34 * 4. This software may only be redistributed and used in connection with an Atmel
35 * AVR product.
36 *
37 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
39 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
40 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
41 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
42 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
43 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
45 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
46 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
47 *
48 */
49
50#ifndef _GPIO_H_
51#define _GPIO_H_
52
53#include <avr32/io.h>
54#include "compiler.h"
55
56/*! \name Return Values of the GPIO API
57 */
58//! @{
59#define GPIO_SUCCESS            0 //!< Function successfully completed.
60#define GPIO_INVALID_ARGUMENT   1 //!< Input parameters are out of range.
61//! @}
62
63
64/*! \name Interrupt Trigger Modes
65 */
66//! @{
67#define GPIO_PIN_CHANGE         0 //!< Interrupt triggered upon pin change.
68#define GPIO_RISING_EDGE        1 //!< Interrupt triggered upon rising edge.
69#define GPIO_FALLING_EDGE       2 //!< Interrupt triggered upon falling edge.
70//! @}
71
72
73//! A type definition of pins and modules connectivity.
74typedef struct
75{
76  unsigned char pin;              //!< Module pin.
77  unsigned char function;         //!< Module function.
78} gpio_map_t[];
79
80
81/*! \name Peripheral Bus Interface
82 *
83 * Low-speed interface with a non-deterministic number of clock cycles per
84 * access.
85 *
86 * This interface operates with lower clock frequencies (fPB <= fCPU), and its
87 * timing is not deterministic since it needs to access a shared bus which may
88 * be heavily loaded.
89 *
90 * \note This interface is immediately available without initialization.
91 */
92//! @{
93
94/*! \brief Enables specific module modes for a set of pins.
95 *
96 * \param gpiomap The pin map.
97 * \param size The number of pins in \a gpiomap.
98 *
99 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
100 */
101extern int gpio_enable_module(const gpio_map_t gpiomap, unsigned int size);
102
103/*! \brief Enables a specific module mode for a pin.
104 *
105 * \param pin The pin number.\n
106 *            Refer to the product header file `uc3x.h' (where x is the part
107 *            number; e.g. x = a0512) for module pins. E.g., to enable a PWM
108 *            channel output, the pin number can be AVR32_PWM_3_PIN for PWM
109 *            channel 3.
110 * \param function The pin function.\n
111 *                 Refer to the product header file `uc3x.h' (where x is the
112 *                 part number; e.g. x = a0512) for module pin functions. E.g.,
113 *                 to enable a PWM channel output, the pin function can be
114 *                 AVR32_PWM_3_FUNCTION for PWM channel 3.
115 *
116 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
117 */
118extern int gpio_enable_module_pin(unsigned int pin, unsigned int function);
119
120/*! \brief Enables the GPIO mode of a set of pins.
121 *
122 * \param gpiomap The pin map.
123 * \param size The number of pins in \a gpiomap.
124 */
125extern void gpio_enable_gpio(const gpio_map_t gpiomap, unsigned int size);
126
127/*! \brief Enables the GPIO mode of a pin.
128 *
129 * \param pin The pin number.\n
130 *            Refer to the product header file `uc3x.h' (where x is the part
131 *            number; e.g. x = a0512) for pin definitions. E.g., to enable the
132 *            GPIO mode of PX21, AVR32_PIN_PX21 can be used. Module pins such as
133 *            AVR32_PWM_3_PIN for PWM channel 3 can also be used to release
134 *            module pins for GPIO.
135 */
136extern void gpio_enable_gpio_pin(unsigned int pin);
137
138// The open-drain mode is not synthesized on the current AVR32 products.
139// If one day some AVR32 products have this feature, the corresponding part
140// numbers should be listed in the #if below.
141// Note that other functions are available in this driver to use pins with open
142// drain in GPIO mode. The advantage of the open-drain mode functions over these
143// other functions is that they can be used not only in GPIO mode but also in
144// module mode.
145#if 0
146
147/*! \brief Enables the open-drain mode of a pin.
148 *
149 * \param pin The pin number.
150 */
151extern void gpio_enable_pin_open_drain(unsigned int pin);
152
153/*! \brief Disables the open-drain mode of a pin.
154 *
155 * \param pin The pin number.
156 */
157extern void gpio_disable_pin_open_drain(unsigned int pin);
158
159#endif
160
161/*! \brief Enables the pull-up resistor of a pin.
162 *
163 * \param pin The pin number.
164 */
165extern void gpio_enable_pin_pull_up(unsigned int pin);
166
167/*! \brief Disables the pull-up resistor of a pin.
168 *
169 * \param pin The pin number.
170 */
171extern void gpio_disable_pin_pull_up(unsigned int pin);
172
173#if defined(AVR32_GPIO_200_H_INCLUDED) || defined(AVR32_GPIO_210_H_INCLUDED) || defined(AVR32_GPIO_211_H_INCLUDED)
174// Added support of Pull-up Resistor, Pull-down Resistor and Buskeeper Control.
175
176/*! \brief Enables the pull-down resistor of a pin.
177 *
178 * \param pin The pin number.
179 */
180extern void gpio_enable_pin_pull_down(unsigned int pin);
181
182/*! \brief Disables the pull-down resistor of a pin.
183 *
184 * \param pin The pin number.
185 */
186extern void gpio_disable_pin_pull_down(unsigned int pin);
187
188/*! \brief Enables the buskeeper functionality on a pin.
189 *
190 * \param pin The pin number.
191 */
192extern void gpio_enable_pin_buskeeper(unsigned int pin);
193
194/*! \brief Disables the buskeeper functionality on a pin.
195 *
196 * \param pin The pin number.
197 */
198extern void gpio_disable_pin_buskeeper(unsigned int pin);
199
200#endif
201
202/*! \brief Returns the value of a pin.
203 *
204 * \param pin The pin number.
205 *
206 * \return The pin value.
207 */
208extern int gpio_get_pin_value(unsigned int pin);
209
210/*! \brief Returns the output value set for a GPIO pin.
211 *
212 * \param pin The pin number.
213 *
214 * \return The pin output value.
215 *
216 * \note This function must be used in conjunction with \ref gpio_set_gpio_pin,
217 *       \ref gpio_clr_gpio_pin and \ref gpio_tgl_gpio_pin.
218 */
219extern int gpio_get_gpio_pin_output_value(unsigned int pin);
220
221/*! \brief Returns the output value set for a GPIO pin using open drain.
222 *
223 * \param pin The pin number.
224 *
225 * \return The pin output value.
226 *
227 * \note This function must be used in conjunction with
228 *       \ref gpio_set_gpio_open_drain_pin, \ref gpio_clr_gpio_open_drain_pin
229 *       and \ref gpio_tgl_gpio_open_drain_pin.
230 */
231extern int gpio_get_gpio_open_drain_pin_output_value(unsigned int pin);
232
233/*! \brief Drives a GPIO pin to 1.
234 *
235 * \param pin The pin number.
236 */
237extern void gpio_set_gpio_pin(unsigned int pin);
238
239/*! \brief Drives a GPIO pin to 0.
240 *
241 * \param pin The pin number.
242 */
243extern void gpio_clr_gpio_pin(unsigned int pin);
244
245/*! \brief Toggles a GPIO pin.
246 *
247 * \param pin The pin number.
248 */
249extern void gpio_tgl_gpio_pin(unsigned int pin);
250
251/*! \brief Drives a GPIO pin to 1 using open drain.
252 *
253 * \param pin The pin number.
254 */
255extern void gpio_set_gpio_open_drain_pin(unsigned int pin);
256
257/*! \brief Drives a GPIO pin to 0 using open drain.
258 *
259 * \param pin The pin number.
260 */
261extern void gpio_clr_gpio_open_drain_pin(unsigned int pin);
262
263/*! \brief Toggles a GPIO pin using open drain.
264 *
265 * \param pin The pin number.
266 */
267extern void gpio_tgl_gpio_open_drain_pin(unsigned int pin);
268
269/*! \brief Enables the glitch filter of a pin.
270 *
271 * When the glitch filter is enabled, a glitch with duration of less than 1
272 * clock cycle is automatically rejected, while a pulse with duration of 2 clock
273 * cycles or more is accepted. For pulse durations between 1 clock cycle and 2
274 * clock cycles, the pulse may or may not be taken into account, depending on
275 * the precise timing of its occurrence. Thus for a pulse to be guaranteed
276 * visible it must exceed 2 clock cycles, whereas for a glitch to be reliably
277 * filtered out, its duration must not exceed 1 clock cycle. The filter
278 * introduces 2 clock cycles latency.
279 *
280 * \param pin The pin number.
281 */
282extern void gpio_enable_pin_glitch_filter(unsigned int pin);
283
284/*! \brief Disables the glitch filter of a pin.
285 *
286 * \param pin The pin number.
287 */
288extern void gpio_disable_pin_glitch_filter(unsigned int pin);
289
290/*! \brief Enables the interrupt of a pin with the specified settings.
291 *
292 * \param pin The pin number.
293 * \param mode The trigger mode (\ref GPIO_PIN_CHANGE, \ref GPIO_RISING_EDGE or
294 *             \ref GPIO_FALLING_EDGE).
295 *
296 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
297 */
298extern int gpio_enable_pin_interrupt(unsigned int pin, unsigned int mode);
299
300/*! \brief Disables the interrupt of a pin.
301 *
302 * \param pin The pin number.
303 */
304extern void gpio_disable_pin_interrupt(unsigned int pin);
305
306/*! \brief Gets the interrupt flag of a pin.
307 *
308 * \param pin The pin number.
309 *
310 * \return The pin interrupt flag.
311 */
312extern int gpio_get_pin_interrupt_flag(unsigned int pin);
313
314/*! \brief Clears the interrupt flag of a pin.
315 *
316 * \param pin The pin number.
317 */
318extern void gpio_clear_pin_interrupt_flag(unsigned int pin);
319
320//! @}
321
322
323#if (defined AVR32_GPIO_LOCAL_ADDRESS)
324/*! \name Local Bus Interface
325 *
326 * High-speed interface with only one clock cycle per access.
327 *
328 * This interface operates with high clock frequency (fCPU), and its timing is
329 * deterministic since it does not need to access a shared bus which may be
330 * heavily loaded.
331 *
332 * \warning To use this interface, the clock frequency of the peripheral bus on
333 *          which the GPIO peripheral is connected must be set to the CPU clock
334 *          frequency (fPB = fCPU).
335 *
336 * \note This interface has to be initialized in order to be available.
337 */
338//! @{
339
340/*! \brief Enables the local bus interface for GPIO.
341 *
342 * \note This function must have been called at least once before using other
343 *       functions in this interface.
344 */
345#if (defined __GNUC__)
346__attribute__((__always_inline__))
347#endif
348extern __inline__ void gpio_local_init(void)
349{
350  Set_system_register(AVR32_CPUCR,
351                      Get_system_register(AVR32_CPUCR) | AVR32_CPUCR_LOCEN_MASK);
352}
353
354/*! \brief Enables the output driver of a pin.
355 *
356 * \param pin The pin number.
357 *
358 * \note \ref gpio_local_init must have been called beforehand.
359 *
360 * \note This function does not enable the GPIO mode of the pin.
361 *       \ref gpio_enable_gpio_pin can be called for this purpose.
362 */
363#if (defined __GNUC__)
364__attribute__((__always_inline__))
365#endif
366extern __inline__ void gpio_local_enable_pin_output_driver(unsigned int pin)
367{
368  AVR32_GPIO_LOCAL.port[pin >> 5].oders = 1 << (pin & 0x1F);
369}
370
371/*! \brief Disables the output driver of a pin.
372 *
373 * \param pin The pin number.
374 *
375 * \note \ref gpio_local_init must have been called beforehand.
376 */
377#if (defined __GNUC__)
378__attribute__((__always_inline__))
379#endif
380extern __inline__ void gpio_local_disable_pin_output_driver(unsigned int pin)
381{
382  AVR32_GPIO_LOCAL.port[pin >> 5].oderc = 1 << (pin & 0x1F);
383}
384
385/*! \brief Returns the value of a pin.
386 *
387 * \param pin The pin number.
388 *
389 * \return The pin value.
390 *
391 * \note \ref gpio_local_init must have been called beforehand.
392 */
393#if (defined __GNUC__)
394__attribute__((__always_inline__))
395#endif
396extern __inline__ int gpio_local_get_pin_value(unsigned int pin)
397{
398  return (AVR32_GPIO_LOCAL.port[pin >> 5].pvr >> (pin & 0x1F)) & 1;
399}
400
401/*! \brief Drives a GPIO pin to 1.
402 *
403 * \param pin The pin number.
404 *
405 * \note \ref gpio_local_init must have been called beforehand.
406 *
407 * \note This function does not enable the GPIO mode of the pin nor its output
408 *       driver. \ref gpio_enable_gpio_pin and
409 *       \ref gpio_local_enable_pin_output_driver can be called for this
410 *       purpose.
411 */
412#if (defined __GNUC__)
413__attribute__((__always_inline__))
414#endif
415extern __inline__ void gpio_local_set_gpio_pin(unsigned int pin)
416{
417  AVR32_GPIO_LOCAL.port[pin >> 5].ovrs = 1 << (pin & 0x1F);
418}
419
420/*! \brief Drives a GPIO pin to 0.
421 *
422 * \param pin The pin number.
423 *
424 * \note \ref gpio_local_init must have been called beforehand.
425 *
426 * \note This function does not enable the GPIO mode of the pin nor its output
427 *       driver. \ref gpio_enable_gpio_pin and
428 *       \ref gpio_local_enable_pin_output_driver can be called for this
429 *       purpose.
430 */
431#if (defined __GNUC__)
432__attribute__((__always_inline__))
433#endif
434extern __inline__ void gpio_local_clr_gpio_pin(unsigned int pin)
435{
436  AVR32_GPIO_LOCAL.port[pin >> 5].ovrc = 1 << (pin & 0x1F);
437}
438
439/*! \brief Toggles a GPIO pin.
440 *
441 * \param pin The pin number.
442 *
443 * \note \ref gpio_local_init must have been called beforehand.
444 *
445 * \note This function does not enable the GPIO mode of the pin nor its output
446 *       driver. \ref gpio_enable_gpio_pin and
447 *       \ref gpio_local_enable_pin_output_driver can be called for this
448 *       purpose.
449 */
450#if (defined __GNUC__)
451__attribute__((__always_inline__))
452#endif
453extern __inline__ void gpio_local_tgl_gpio_pin(unsigned int pin)
454{
455  AVR32_GPIO_LOCAL.port[pin >> 5].ovrt = 1 << (pin & 0x1F);
456}
457
458/*! \brief Initializes the configuration of a GPIO pin so that it can be used
459 *         with GPIO open-drain functions.
460 *
461 * \note This function must have been called at least once before using
462 *       \ref gpio_local_set_gpio_open_drain_pin,
463 *       \ref gpio_local_clr_gpio_open_drain_pin or
464 *       \ref gpio_local_tgl_gpio_open_drain_pin.
465 */
466#if (defined __GNUC__)
467__attribute__((__always_inline__))
468#endif
469extern __inline__ void gpio_local_init_gpio_open_drain_pin(unsigned int pin)
470{
471  AVR32_GPIO_LOCAL.port[pin >> 5].ovrc = 1 << (pin & 0x1F);
472}
473
474/*! \brief Drives a GPIO pin to 1 using open drain.
475 *
476 * \param pin The pin number.
477 *
478 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must
479 *       have been called beforehand.
480 *
481 * \note This function does not enable the GPIO mode of the pin.
482 *       \ref gpio_enable_gpio_pin can be called for this purpose.
483 */
484#if (defined __GNUC__)
485__attribute__((__always_inline__))
486#endif
487extern __inline__ void gpio_local_set_gpio_open_drain_pin(unsigned int pin)
488{
489  AVR32_GPIO_LOCAL.port[pin >> 5].oderc = 1 << (pin & 0x1F);
490}
491
492/*! \brief Drives a GPIO pin to 0 using open drain.
493 *
494 * \param pin The pin number.
495 *
496 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must
497 *       have been called beforehand.
498 *
499 * \note This function does not enable the GPIO mode of the pin.
500 *       \ref gpio_enable_gpio_pin can be called for this purpose.
501 */
502#if (defined __GNUC__)
503__attribute__((__always_inline__))
504#endif
505extern __inline__ void gpio_local_clr_gpio_open_drain_pin(unsigned int pin)
506{
507  AVR32_GPIO_LOCAL.port[pin >> 5].oders = 1 << (pin & 0x1F);
508}
509
510/*! \brief Toggles a GPIO pin using open drain.
511 *
512 * \param pin The pin number.
513 *
514 * \note \ref gpio_local_init and \ref gpio_local_init_gpio_open_drain_pin must
515 *       have been called beforehand.
516 *
517 * \note This function does not enable the GPIO mode of the pin.
518 *       \ref gpio_enable_gpio_pin can be called for this purpose.
519 */
520#if (defined __GNUC__)
521__attribute__((__always_inline__))
522#endif
523extern __inline__ void gpio_local_tgl_gpio_open_drain_pin(unsigned int pin)
524{
525  AVR32_GPIO_LOCAL.port[pin >> 5].odert = 1 << (pin & 0x1F);
526}
527
528//! @}
529#endif // AVR32_GPIO_LOCAL_ADDRESS
530
531#if UC3L
532//! @{
533/*! \name Peripheral Event System support
534 *
535 * The GPIO can be programmed to output peripheral events whenever an interrupt
536 * condition is detected, such as pin value change, or only when a rising or
537 * falling edge is detected.
538 *
539 */
540
541/*! \brief Enables the peripheral event generation of a pin.
542 *
543 * \param pin The pin number.
544 *
545 */
546#if (defined __GNUC__)
547__attribute__((__always_inline__))
548#endif
549extern __inline__ void gpio_enable_pin_periph_event(unsigned int pin)
550{
551  AVR32_GPIO.port[pin >> 5].oderc = 1 << (pin & 0x1F); // The GPIO output driver is disabled for that pin.
552  AVR32_GPIO.port[pin >> 5].evers = 1 << (pin & 0x1F);
553}
554
555/*! \brief Disables the peripheral event generation of a pin.
556 *
557 * \param pin The pin number.
558 *
559 */
560#if (defined __GNUC__)
561__attribute__((__always_inline__))
562#endif
563extern __inline__ void gpio_disable_pin_periph_event(unsigned int pin)
564{
565  AVR32_GPIO.port[pin >> 5].everc = 1 << (pin & 0x1F);
566}
567
568/*! \brief Configure the peripheral event trigger mode of a pin
569 *
570 * \param pin The pin number.
571 * \param mode The trigger mode (\ref GPIO_PIN_CHANGE, \ref GPIO_RISING_EDGE or
572 *             \ref GPIO_FALLING_EDGE).
573 * \param use_igf use the Input Glitch Filter (TRUE) or not (FALSE).
574 *
575 * \return \ref GPIO_SUCCESS or \ref GPIO_INVALID_ARGUMENT.
576 */
577extern int gpio_configure_pin_periph_event_mode(unsigned int pin, unsigned int mode, unsigned int use_igf);
578
579//! @}
580#endif
581
582
583#endif  // _GPIO_H_
Note: See TracBrowser for help on using the repository browser.