git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_ATSAM3X_Atmel_Studio/src/asf/sam/drivers/pio/pio.h

   1 /**\r
   2  * \file\r
   3  *\r
   4  * \brief Parallel Input/Output (PIO) Controller driver for SAM.\r
   5  *\r
   6  * Copyright (c) 2011 - 2012 Atmel Corporation. All rights reserved.\r
   7  *\r
   8  * \asf_license_start\r
   9  *\r
  10  * \page License\r
  11  *\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
  14  *\r
  15  * 1. Redistributions of source code must retain the above copyright notice,\r
  16  *    this list of conditions and the following disclaimer.\r
  17  *\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
  21  *\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
  24  *\r
  25  * 4. This software may only be redistributed and used in connection with an\r
  26  *    Atmel microcontroller product.\r
  27  *\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
  39  *\r
  40  * \asf_license_stop\r
  41  *\r
  42  */\r
  43 \r
  44 #ifndef PIO_H_INCLUDED\r
  45 #define PIO_H_INCLUDED\r
  46 \r
  47 #include "compiler.h"\r
  48 \r
  49 /// @cond 0\r
  50 /**INDENT-OFF**/\r
  51 #ifdef __cplusplus\r
  52 extern "C" {\r
  53 #endif\r
  54 /**INDENT-ON**/\r
  55 /// @endcond\r
  56 \r
  57 /* GPIO Support */\r
  58 #define PIO_TYPE_Pos                    27\r
  59 /* PIO Type Mask */\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
  77 \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
  85 #endif\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
  89 } pio_type_t;\r
  90 \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
  99 \r
 100 /*  The internal debouncing filter is active. */\r
 101 #define PIO_DEBOUNCE                (1u << 3)\r
 102 \r
 103 /*  Enable additional interrupt modes. */\r
 104 #define PIO_IT_AIME                 (1u << 4)\r
 105 \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
 110 \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
 119 \r
 120 /*\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
 123  *     - PIO_PULLUP\r
 124  *     - PIO_DEGLITCH\r
 125  *     - PIO_DEBOUNCE\r
 126  *     - PIO_OPENDRAIN\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
 131  */\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
 155 \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
 159 #endif\r
 160 \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
 165 \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
 169 #endif\r
 170 \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
 180 \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
 191 #endif\r
 192 \r
 193 /* GPIO Support */\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
 208 \r
 209 /**\r
 210  * \page sam_pio_quickstart Quick Start Guide for the SAM PIO driver\r
 211  *\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
 215  *\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
 218  *\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
 222  *\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
 227  *\r
 228  * \subsection sam_pio_quickstart_use_case_1_prereq Prerequisites\r
 229  *  - \ref group_pmc "Power Management Controller driver"\r
 230  *\r
 231  * \subsection sam_pio_quickstart_use_case_1_setup_steps Initialization code\r
 232  * Add to the application initialization code:\r
 233  * \code\r
 234  *    pmc_enable_periph_clk(ID_PIOA);\r
 235  *\r
 236  *    pio_set_output(PIOA, PIO_PA23, LOW, DISABLE, ENABLE);\r
 237  *    pio_set_input(PIOA, PIO_PA16, PIO_PULLUP);\r
 238  * \endcode\r
 239  *\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
 247  *\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
 250  *   \code\r
 251  *   if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))\r
 252  *       pio_clear(PIOA, PIO_PA23);\r
 253  *   else\r
 254  *       pio_set(PIOA, PIO_PA23);\r
 255  *   \endcode\r
 256  *\r
 257  * \subsection sam_pio_quickstart_use_case_1_example_workflow Workflow\r
 258  * -# We check the value of the pin:\r
 259  *     \code\r
 260  *     if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))\r
 261  *     \endcode\r
 262  * -# Then we set the new output value based on the read pin value:\r
 263  *     \code\r
 264  *         pio_clear(PIOA, PIO_PA23);\r
 265  *     else\r
 266  *         pio_set(PIOA, PIO_PA23);\r
 267  *     \endcode\r
 268  */\r
 269 \r
 270 /**\r
 271  * \page sam_pio_quickstart_use_case_2 Advanced use case - Interrupt driven edge detection\r
 272  *\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
 278  *\r
 279  * \subsection sam_pio_quickstart_use_case_2_prereq Prerequisites\r
 280  *  - \ref group_pmc "Power Management Controller driver"\r
 281  *\r
 282  * \subsection sam_pio_quickstart_use_case_2_setup_steps Initialization code\r
 283  * Add to the application initialization code:\r
 284  * \code\r
 285  * pmc_enable_periph_clk(ID_PIOA);\r
 286  *\r
 287  * pio_set_output(PIOA, PIO_PA23, LOW, DISABLE, ENABLE);\r
 288  * pio_set_input(PIOA, PIO_PA16, PIO_PULLUP);\r
 289  *\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
 292  *\r
 293  * NVIC_EnableIRQ(PIOA_IRQn);\r
 294  * \endcode\r
 295  *\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
 309  *\r
 310  * \subsection sam_pio_quickstart_use_case_2_example_code Example code\r
 311  * Add the following function to your application:\r
 312  * \code\r
 313  *    void pin_edge_handler(void)\r
 314  *    {\r
 315  *        if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))\r
 316  *            pio_clear(PIOA, PIO_PA23);\r
 317  *        else\r
 318  *            pio_set(PIOA, PIO_PA23);\r
 319  *    }\r
 320  * \endcode\r
 321  *\r
 322  * \subsection sam_pio_quickstart_use_case_2_example_workflow Workflow\r
 323  * -# We check the value of the pin:\r
 324  *     \code\r
 325  *     if (pio_get(PIOA, PIO_TYPE_PIO_INPUT, PIO_PA16))\r
 326  *     \endcode\r
 327  * -# Then we set the new output value based on the read pin value:\r
 328  *     \code\r
 329  *         pio_clear(PIOA, PIO_PA23);\r
 330  *     else\r
 331  *         pio_set(PIOA, PIO_PA23);\r
 332  *     \endcode\r
 333  */\r
 334 \r
 335 /// @cond 0\r
 336 /**INDENT-OFF**/\r
 337 #ifdef __cplusplus\r
 338 }\r
 339 #endif\r
 340 /**INDENT-ON**/\r
 341 /// @endcond\r
 342 \r
 343 #endif /* PIO_H_INCLUDED */\r