4 * \brief Parallel Input/Output (PIO) Controller driver for SAM.
\r
6 * Copyright (c) 2011 - 2012 Atmel Corporation. All rights reserved.
\r
12 * Redistribution and use in source and binary forms, with or without
\r
13 * modification, are permitted provided that the following conditions are met:
\r
15 * 1. Redistributions of source code must retain the above copyright notice,
\r
16 * this list of conditions and the following disclaimer.
\r
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
\r
19 * this list of conditions and the following disclaimer in the documentation
\r
20 * and/or other materials provided with the distribution.
\r
22 * 3. The name of Atmel may not be used to endorse or promote products derived
\r
23 * from this software without specific prior written permission.
\r
25 * 4. This software may only be redistributed and used in connection with an
\r
26 * Atmel microcontroller product.
\r
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
\r
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
\r
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
\r
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
\r
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
\r
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
\r
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
\r
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
\r
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
\r
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
\r
38 * POSSIBILITY OF SUCH DAMAGE.
\r
44 #ifndef PIO_H_INCLUDED
\r
45 #define PIO_H_INCLUDED
\r
47 #include "compiler.h"
\r
58 #define PIO_TYPE_Pos 27
\r
60 #define PIO_TYPE_Msk (0xFu << PIO_TYPE_Pos)
\r
61 /* The pin is not a function pin. */
\r
62 #define PIO_TYPE_NOT_A_PIN (0x0u << PIO_TYPE_Pos)
\r
63 /* The pin is controlled by the peripheral A. */
\r
64 #define PIO_TYPE_PIO_PERIPH_A (0x1u << PIO_TYPE_Pos)
\r
65 /* The pin is controlled by the peripheral B. */
\r
66 #define PIO_TYPE_PIO_PERIPH_B (0x2u << PIO_TYPE_Pos)
\r
67 /* The pin is controlled by the peripheral C. */
\r
68 #define PIO_TYPE_PIO_PERIPH_C (0x3u << PIO_TYPE_Pos)
\r
69 /* The pin is controlled by the peripheral D. */
\r
70 #define PIO_TYPE_PIO_PERIPH_D (0x4u << PIO_TYPE_Pos)
\r
71 /* The pin is an input. */
\r
72 #define PIO_TYPE_PIO_INPUT (0x5u << PIO_TYPE_Pos)
\r
73 /* The pin is an output and has a default level of 0. */
\r
74 #define PIO_TYPE_PIO_OUTPUT_0 (0x6u << PIO_TYPE_Pos)
\r
75 /* The pin is an output and has a default level of 1. */
\r
76 #define PIO_TYPE_PIO_OUTPUT_1 (0x7u << PIO_TYPE_Pos)
\r
78 typedef enum _pio_type {
\r
79 PIO_NOT_A_PIN = PIO_TYPE_NOT_A_PIN,
\r
80 PIO_PERIPH_A = PIO_TYPE_PIO_PERIPH_A,
\r
81 PIO_PERIPH_B = PIO_TYPE_PIO_PERIPH_B,
\r
82 #if (SAM3S || SAM3N || SAM4S)
\r
83 PIO_PERIPH_C = PIO_TYPE_PIO_PERIPH_C,
\r
84 PIO_PERIPH_D = PIO_TYPE_PIO_PERIPH_D,
\r
86 PIO_INPUT = PIO_TYPE_PIO_INPUT,
\r
87 PIO_OUTPUT_0 = PIO_TYPE_PIO_OUTPUT_0,
\r
88 PIO_OUTPUT_1 = PIO_TYPE_PIO_OUTPUT_1
\r
91 /* Default pin configuration (no attribute). */
\r
92 #define PIO_DEFAULT (0u << 0)
\r
93 /* The internal pin pull-up is active. */
\r
94 #define PIO_PULLUP (1u << 0)
\r
95 /* The internal glitch filter is active. */
\r
96 #define PIO_DEGLITCH (1u << 1)
\r
97 /* The pin is open-drain. */
\r
98 #define PIO_OPENDRAIN (1u << 2)
\r
100 /* The internal debouncing filter is active. */
\r
101 #define PIO_DEBOUNCE (1u << 3)
\r
103 /* Enable additional interrupt modes. */
\r
104 #define PIO_IT_AIME (1u << 4)
\r
106 /* Interrupt High Level/Rising Edge detection is active. */
\r
107 #define PIO_IT_RE_OR_HL (1u << 5)
\r
108 /* Interrupt Edge detection is active. */
\r
109 #define PIO_IT_EDGE (1u << 6)
\r
111 /* Low level interrupt is active */
\r
112 #define PIO_IT_LOW_LEVEL (0 | 0 | PIO_IT_AIME)
\r
113 /* High level interrupt is active */
\r
114 #define PIO_IT_HIGH_LEVEL (PIO_IT_RE_OR_HL | 0 | PIO_IT_AIME)
\r
115 /* Falling edge interrupt is active */
\r
116 #define PIO_IT_FALL_EDGE (0 | PIO_IT_EDGE | PIO_IT_AIME)
\r
117 /* Rising edge interrupt is active */
\r
118 #define PIO_IT_RISE_EDGE (PIO_IT_RE_OR_HL | PIO_IT_EDGE | PIO_IT_AIME)
\r
121 * The #attribute# field is a bitmask that can either be set to PIO_DEFAULT,
\r
122 * or combine (using bitwise OR '|') any number of the following constants:
\r
127 * - PIO_IT_LOW_LEVEL
\r
128 * - PIO_IT_HIGH_LEVEL
\r
129 * - PIO_IT_FALL_EDGE
\r
130 * - PIO_IT_RISE_EDGE
\r
132 void pio_pull_up(Pio *p_pio, const uint32_t ul_mask,
\r
133 const uint32_t ul_pull_up_enable);
\r
134 void pio_set_debounce_filter(Pio *p_pio, const uint32_t ul_mask,
\r
135 const uint32_t ul_cut_off);
\r
136 void pio_set(Pio *p_pio, const uint32_t ul_mask);
\r
137 void pio_clear(Pio *p_pio, const uint32_t ul_mask);
\r
138 uint32_t pio_get(Pio *p_pio, const pio_type_t ul_type,
\r
139 const uint32_t ul_mask);
\r
140 void pio_set_peripheral(Pio *p_pio, const pio_type_t ul_type,
\r
141 const uint32_t ul_mask);
\r
142 void pio_set_input(Pio *p_pio, const uint32_t ul_mask,
\r
143 const uint32_t ul_attribute);
\r
144 void pio_set_output(Pio *p_pio, const uint32_t ul_mask,
\r
145 const uint32_t ul_default_level,
\r
146 const uint32_t ul_multidrive_enable,
\r
147 const uint32_t ul_pull_up_enable);
\r
148 uint32_t pio_configure(Pio *p_pio, const pio_type_t ul_type,
\r
149 const uint32_t ul_mask, const uint32_t ul_attribute);
\r
150 uint32_t pio_get_output_data_status(const Pio *p_pio,
\r
151 const uint32_t ul_mask);
\r
152 void pio_set_multi_driver(Pio *p_pio, const uint32_t ul_mask,
\r
153 const uint32_t ul_multi_driver_enable);
\r
154 uint32_t pio_get_multi_driver_status(const Pio *p_pio);
\r
156 #if (SAM3S || SAM3N || SAM4S)
\r
157 void pio_pull_down(Pio *p_pio, const uint32_t ul_mask,
\r
158 const uint32_t ul_pull_down_enable);
\r
161 void pio_enable_output_write(Pio *p_pio, const uint32_t ul_mask);
\r
162 void pio_disable_output_write(Pio *p_pio, const uint32_t ul_mask);
\r
163 uint32_t pio_get_output_write_status(const Pio *p_pio);
\r
164 void pio_sync_output_write(Pio *p_pio, const uint32_t ul_mask);
\r
166 #if (SAM3S || SAM3N || SAM4S)
\r
167 void pio_set_schmitt_trigger(Pio *p_pio, const uint32_t ul_mask);
\r
168 uint32_t pio_get_schmitt_trigger(const Pio *p_pio);
\r
171 void pio_configure_interrupt(Pio *p_pio, const uint32_t ul_mask, const uint32_t ul_attr);
\r
172 void pio_enable_interrupt(Pio *p_pio, const uint32_t ul_mask);
\r
173 void pio_disable_interrupt(Pio *p_pio, const uint32_t ul_mask);
\r
174 uint32_t pio_get_interrupt_status(const Pio *p_pio);
\r
175 uint32_t pio_get_interrupt_mask(const Pio *p_pio);
\r
176 void pio_set_additional_interrupt_mode(Pio *p_pio,
\r
177 const uint32_t ul_mask, const uint32_t ul_attribute);
\r
178 void pio_set_writeprotect(Pio *p_pio, const uint32_t ul_enable);
\r
179 uint32_t pio_get_writeprotect_status(const Pio *p_pio);
\r
181 #if (SAM3S || SAM4S)
\r
182 void pio_capture_set_mode(Pio *p_pio, uint32_t ul_mode);
\r
183 void pio_capture_enable(Pio *p_pio);
\r
184 void pio_capture_disable(Pio *p_pio);
\r
185 uint32_t pio_capture_read(const Pio *p_pio, uint32_t * pul_data);
\r
186 void pio_capture_enable_interrupt(Pio *p_pio, const uint32_t ul_mask);
\r
187 void pio_capture_disable_interrupt(Pio * p_pio, const uint32_t ul_mask);
\r
188 uint32_t pio_capture_get_interrupt_status(const Pio *p_pio);
\r
189 uint32_t pio_capture_get_interrupt_mask(const Pio *p_pio);
\r
190 Pdc *pio_capture_get_pdc_base(const Pio *p_pio);
\r
194 uint32_t pio_get_pin_value(uint32_t pin);
\r
195 void pio_set_pin_high(uint32_t pin);
\r
196 void pio_set_pin_low(uint32_t pin);
\r
197 void pio_toggle_pin(uint32_t pin);
\r
198 void pio_enable_pin_interrupt(uint32_t pin);
\r
199 void pio_disable_pin_interrupt(uint32_t pin);
\r
200 Pio *pio_get_pin_group(uint32_t pin);
\r
201 uint32_t pio_get_pin_group_id(uint32_t pin);
\r
202 uint32_t pio_get_pin_group_mask(uint32_t pin);
\r
203 uint32_t pio_configure_pin(uint32_t ul_pin, const uint32_t ul_flags);
\r
204 void pio_set_pin_group_high(Pio *p_pio, uint32_t ul_mask);
\r
205 void pio_set_pin_group_low(Pio *p_pio, uint32_t ul_mask);
\r
206 void pio_toggle_pin_group(Pio *p_pio, uint32_t ul_mask);
\r
207 uint32_t pio_configure_pin_group(Pio *p_pio, uint32_t ul_mask, const uint32_t ul_flags);
\r
210 * \page sam_pio_quickstart Quick Start Guide for the SAM PIO driver
\r
212 * This is the quick start guide for the \ref sam_drivers_pio_group "PIO Driver",
\r
213 * with step-by-step instructions on how to configure and use the driver for
\r
214 * specific use cases.
\r
216 * The section described below can be compiled into e.g. the main application
\r
217 * loop or any other function that will need to interface with the IO port.
\r
219 * \section sam_pio_usecases PIO use cases
\r
220 * - \ref sam_pio_quickstart_basic
\r
221 * - \ref sam_pio_quickstart_use_case_2
\r
223 * \section sam_pio_quickstart_basic Basic usage of the PIO driver
\r
224 * This section will present a basic use case for the PIO driver. This use case
\r
225 * will configure pin 23 on port A as output and pin 16 as an input with pullup,
\r
226 * and then toggle the output pin's value to match that of the input pin.
\r
228 * \subsection sam_pio_quickstart_use_case_1_prereq Prerequisites
\r
229 * - \ref group_pmc "Power Management Controller driver"
\r
231 * \subsection sam_pio_quickstart_use_case_1_setup_steps Initialization code
\r
232 * Add to the application initialization code:
\r
234 * pmc_enable_periph_clk(ID_PIOA);
\r
236 * pio_set_output(PIOA, PIO_PA23, LOW, DISABLE, ENABLE);
\r
237 * pio_set_input(PIOA, PIO_PA16, PIO_PULLUP);
\r
240 * \subsection sam_pio_quickstart_use_case_1_setup_steps_workflow Workflow
\r
241 * -# Enable the module clock to the PIOA peripheral:
\r
242 * \code pmc_enable_periph_clk(ID_PIOA); \endcode
\r
243 * -# Set pin 23 direction on PIOA as output, default low level:
\r
244 * \code pio_set_output(PIOA, PIO_PA23, LOW, DISABLE, ENABLE); \endcode
\r
245 * -# Set pin 16 direction on PIOA as input, with pullup:
\r
246 * \code pio_set_input(PIOA, PIO_PA16, PIO_PULLUP); \endcode
\r
248 * \subsection sam_pio_quickstart_use_case_1_example_code Example code
\r
249 * Set the state of output pin 23 to match input pin 16:
\r
251 * if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))
\r
252 * pio_clear(PIOA, PIO_PA23);
\r
254 * pio_set(PIOA, PIO_PA23);
\r
257 * \subsection sam_pio_quickstart_use_case_1_example_workflow Workflow
\r
258 * -# We check the value of the pin:
\r
260 * if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))
\r
262 * -# Then we set the new output value based on the read pin value:
\r
264 * pio_clear(PIOA, PIO_PA23);
\r
266 * pio_set(PIOA, PIO_PA23);
\r
271 * \page sam_pio_quickstart_use_case_2 Advanced use case - Interrupt driven edge detection
\r
273 * \section sam_pio_quickstart_use_case_2 Advanced Use Case 1
\r
274 * This section will present a more advanced use case for the PIO driver. This use case
\r
275 * will configure pin 23 on port A as output and pin 16 as an input with pullup,
\r
276 * and then toggle the output pin's value to match that of the input pin using the interrupt
\r
277 * controller within the device.
\r
279 * \subsection sam_pio_quickstart_use_case_2_prereq Prerequisites
\r
280 * - \ref group_pmc "Power Management Controller driver"
\r
282 * \subsection sam_pio_quickstart_use_case_2_setup_steps Initialization code
\r
283 * Add to the application initialization code:
\r
285 * pmc_enable_periph_clk(ID_PIOA);
\r
287 * pio_set_output(PIOA, PIO_PA23, LOW, DISABLE, ENABLE);
\r
288 * pio_set_input(PIOA, PIO_PA16, PIO_PULLUP);
\r
290 * pio_handler_set(PIOA, ID_PIOA, PIO_PA16, PIO_IT_EDGE, pin_edge_handler);
\r
291 * pio_enable_interrupt(PIOA, PIO_PA16);
\r
293 * NVIC_EnableIRQ(PIOA_IRQn);
\r
296 * \subsection sam_pio_quickstart_use_case_2_setup_steps_workflow Workflow
\r
297 * -# Enable the module clock to the PIOA peripheral:
\r
298 * \code pmc_enable_periph_clk(ID_PIOA); \endcode
\r
299 * -# Set pin 23 direction on PIOA as output, default low level:
\r
300 * \code pio_set_output(PIOA, PIO_PA23, LOW, DISABLE, ENABLE); \endcode
\r
301 * -# Set pin 16 direction on PIOA as input, with pullup:
\r
302 * \code pio_set_input(PIOA, PIO_PA16, PIO_PULLUP); \endcode
\r
303 * -# Configure the input pin 16 interrupt mode and handler:
\r
304 * \code pio_handler_set(PIOA, ID_PIOA, PIO_PA16, PIO_IT_EDGE, pin_edge_handler); \endcode
\r
305 * -# Enable the interrupt for the configured input pin:
\r
306 * \code pio_enable_interrupt(PIOA, PIO_PA16); \endcode
\r
307 * -# Enable interrupt handling from the PIOA module:
\r
308 * \code NVIC_EnableIRQ(PIOA_IRQn); \endcode
\r
310 * \subsection sam_pio_quickstart_use_case_2_example_code Example code
\r
311 * Add the following function to your application:
\r
313 * void pin_edge_handler(void)
\r
315 * if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))
\r
316 * pio_clear(PIOA, PIO_PA23);
\r
318 * pio_set(PIOA, PIO_PA23);
\r
322 * \subsection sam_pio_quickstart_use_case_2_example_workflow Workflow
\r
323 * -# We check the value of the pin:
\r
325 * if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))
\r
327 * -# Then we set the new output value based on the read pin value:
\r
329 * pio_clear(PIOA, PIO_PA23);
\r
331 * pio_set(PIOA, PIO_PA23);
\r
343 #endif /* PIO_H_INCLUDED */
\r