git.sur5r.net Git - freertos/blob - Demo/Common/drivers/Atmel/at91lib/peripherals/pio/pio.h

   1 /* ----------------------------------------------------------------------------\r
   2  *         ATMEL Microcontroller Software Support \r
   3  * ----------------------------------------------------------------------------\r
   4  * Copyright (c) 2008, Atmel Corporation\r
   5  *\r
   6  * All rights reserved.\r
   7  *\r
   8  * Redistribution and use in source and binary forms, with or without\r
   9  * modification, are permitted provided that the following conditions are met:\r
  10  *\r
  11  * - Redistributions of source code must retain the above copyright notice,\r
  12  * this list of conditions and the disclaimer below.\r
  13  *\r
  14  * Atmel's name may not be used to endorse or promote products derived from\r
  15  * this software without specific prior written permission.\r
  16  *\r
  17  * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR\r
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
  20  * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,\r
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\r
  22  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,\r
  23  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\r
  24  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\r
  25  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,\r
  26  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
  27  * ----------------------------------------------------------------------------\r
  28  */\r
  29 \r
  30 //------------------------------------------------------------------------------\r
  31 /// \dir\r
  32 /// !Purpose\r
  33 ///\r
  34 ///     Definition of methods and structures for using PIOs in a transparent\r
  35 ///     way. The main purpose is to allow portability between several boards.\r
  36 ///\r
  37 /// !Usage\r
  38 ///\r
  39 ///     -# To configure and use pins, see pio.h.\r
  40 ///     -# To enable and use interrupt generation on PIO status change, see\r
  41 ///      pio_it.h.\r
  42 //------------------------------------------------------------------------------\r
  43 \r
  44 //------------------------------------------------------------------------------\r
  45 /// \unit\r
  46 /// !Purpose\r
  47 /// \r
  48 /// Simple & portable usage of PIO pins.\r
  49 /// \r
  50 /// !Usage\r
  51 /// \r
  52 /// -# Define a constant pin description array such as the following one:\r
  53 ///    \code\r
  54 ///       const Pin at91board_dbgu[] = {\r
  55 ///            {AT91C_BASE_PIOA, (1 << 30), PIO_PERIPH_A, PIO_DEFAULT},\r
  56 ///            {AT91C_BASE_PIOA, (1 << 31), PIO_PERIPH_A, PIO_DEFAULT},\r
  57 ///        };\r
  58 ///    \endcode\r
  59 ///    Alternatively, constants defined in the piodefs.h header file of the\r
  60 ///    board module can be used:\r
  61 ///    \code\r
  62 ///    const Pin at91board_dbgu[] = {PINS_DBGU};\r
  63 ///    const Pin at91board_usart[] = {PIN_USART0_RXD, PIN_USART0_TXD};\r
  64 ///    \endcode\r
  65 ///    It is possible to group multiple pins if they share the same\r
  66 ///    attributes, to save memory. Here is the previous DBGU example\r
  67 ///    rewritten in such a way:\r
  68 ///    \code\r
  69 ///    const Pin at91board_dbgu[] = {\r
  70 ///         {AT91C_BASE_PIOA, 0xC0000000, PIO_PERIPH_A, PIO_DEFAULT}\r
  71 ///    };\r
  72 ///    \endcode\r
  73 /// -# For pins configured as inputs, the PIO controller must be enabled\r
  74 ///    in the PMC (*enabled by PIO_Configure at the moment*).\r
  75 /// -# Configure a pin array by calling PIO_Configure, using\r
  76 ///    the PIO_LISTSIZE macro to calculate the array size if needed. Do not\r
  77 ///    forget to check the return value for any error.\r
  78 /// -# Set and get the value of a pin using the PIO_Set, PIO_Clear and\r
  79 ///    PIO_Get methods.\r
  80 //------------------------------------------------------------------------------\r
  81  \r
  82 #ifndef PIO_H\r
  83 #define PIO_H\r
  84 \r
  85 //------------------------------------------------------------------------------\r
  86 //         Headers\r
  87 //------------------------------------------------------------------------------\r
  88 \r
  89 #include <board.h>\r
  90 \r
  91 //------------------------------------------------------------------------------\r
  92 //         Definitions\r
  93 //------------------------------------------------------------------------------\r
  94 //------------------------------------------------------------------------------\r
  95 /// \page "Pin types" \r
  96 /// This page lists the available types for a Pin instance (in its type field).\r
  97 /// !Types\r
  98 /// - PIO_PERIPH_A \r
  99 /// - PIO_PERIPH_B \r
 100 /// - PIO_INPUT \r
 101 /// - PIO_OUTPUT_0 \r
 102 /// - PIO_OUTPUT_1 \r
 103 \r
 104 /// The pin is controlled by the associated signal of peripheral A.\r
 105 #define PIO_PERIPH_A                0\r
 106 /// The pin is controlled by the associated signal of peripheral B.\r
 107 #define PIO_PERIPH_B                1\r
 108 /// The pin is an input.\r
 109 #define PIO_INPUT                   2\r
 110 /// The pin is an output and has a default level of 0.\r
 111 #define PIO_OUTPUT_0                3\r
 112 /// The pin is an output and has a default level of 1.\r
 113 #define PIO_OUTPUT_1                4\r
 114 //------------------------------------------------------------------------------\r
 115 \r
 116 //------------------------------------------------------------------------------\r
 117 /// \page "Pin attributes"\r
 118 /// This page lists the valid values for the attribute field of a Pin instance.\r
 119 /// !Attributes\r
 120 /// - PIO_DEFAULT\r
 121 /// - PIO_PULLUP\r
 122 /// - PIO_DEGLITCH\r
 123 /// - PIO_OPENDRAIN\r
 124 \r
 125 /// Default pin configuration (no attribute).\r
 126 #define PIO_DEFAULT                 (0 << 0)\r
 127 /// The internal pin pull-up is active.\r
 128 #define PIO_PULLUP                  (1 << 0)\r
 129 /// The internal glitch filter is active.\r
 130 #define PIO_DEGLITCH                (1 << 1)\r
 131 /// The pin is open-drain.\r
 132 #define PIO_OPENDRAIN               (1 << 2)\r
 133 //------------------------------------------------------------------------------\r
 134 \r
 135 /// Calculates the size of a Pin instances array. The array must be local (i.e.\r
 136 /// not a pointer), otherwise the computation will not be correct.\r
 137 #define PIO_LISTSIZE(list)    (sizeof(list) / sizeof(Pin))\r
 138 \r
 139 //------------------------------------------------------------------------------\r
 140 //         Types\r
 141 //------------------------------------------------------------------------------\r
 142 //------------------------------------------------------------------------------\r
 143 /// Describes the type and attribute of one PIO pin or a group of similar pins.\r
 144 typedef struct {\r
 145     /// Bitmask indicating which pin(s) to configure.\r
 146     unsigned int mask; \r
 147     /// Pointer to the PIO controller which has the pin(s).\r
 148     AT91S_PIO    *pio;\r
 149     /// Peripheral ID of the PIO controller which has the pin(s).\r
 150     unsigned char id;\r
 151     /// Pin type (see "Pin types").\r
 152     unsigned char type;\r
 153     /// Pin attribute (see "Pin attributes").\r
 154     unsigned char attribute;\r
 155 } Pin;\r
 156 //------------------------------------------------------------------------------\r
 157 \r
 158 //------------------------------------------------------------------------------\r
 159 //         Exported functions\r
 160 //------------------------------------------------------------------------------\r
 161 extern unsigned char PIO_Configure(const Pin *list, unsigned int size);\r
 162 extern void PIO_Set(const Pin *pin );\r
 163 extern void PIO_Clear(const Pin *pin);\r
 164 extern unsigned char PIO_Get(const Pin *pin);\r
 165 extern unsigned int PIO_GetISR(const Pin *pin);\r
 166 extern unsigned char PIO_GetOutputDataStatus(const Pin *pin);\r
 167 \r
 168 #endif //#ifndef PIO_H\r
 169 \r