1 /** 2 * \file 3 * 4 * \brief SAM GPIO Driver for SAMB11 5 * 6 * Copyright (C) 2015-2016 Atmel Corporation. All rights reserved. 7 * 8 * \asf_license_start 9 * 10 * \page License 11 * 12 * Redistribution and use in source and binary forms, with or without 13 * modification, are permitted provided that the following conditions are met: 14 * 15 * 1. Redistributions of source code must retain the above copyright notice, 16 * this list of conditions and the following disclaimer. 17 * 18 * 2. Redistributions in binary form must reproduce the above copyright notice, 19 * this list of conditions and the following disclaimer in the documentation 20 * and/or other materials provided with the distribution. 21 * 22 * 3. The name of Atmel may not be used to endorse or promote products derived 23 * from this software without specific prior written permission. 24 * 25 * 4. This software may only be redistributed and used in connection with an 26 * Atmel microcontroller product. 27 * 28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 38 * POSSIBILITY OF SUCH DAMAGE. 39 * 40 * \asf_license_stop 41 * 42 */ 43 /* 44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a> 45 */ 46 #ifndef GPIO_H_INCLUDED 47 #define GPIO_H_INCLUDED 48 49 /** 50 * \defgroup asfdoc_samb_gpio_group SAM GPIO Driver (GPIO) 51 * 52 * This driver for Atmel® | SMART SAM devices provides an interface for the 53 * configuration and management of the device's General Purpose Input/Output 54 * (GPIO) pin functionality, for manual pin state reading and writing. 55 * 56 * The following peripherals are used by this module: 57 * - GPIO (GPIO Management) 58 * 59 * The following devices can use this module: 60 * - Atmel | SMART SAM B11 61 * 62 * The outline of this documentation is as follows: 63 * - \ref asfdoc_samb_gpio_prerequisites 64 * - \ref asfdoc_samb_gpio_module_overview 65 * - \ref asfdoc_samb_gpio_special_considerations 66 * - \ref asfdoc_samb_gpio_extra_info 67 * - \ref asfdoc_samb_gpio_examples 68 * - \ref asfdoc_samb_gpio_api_overview 69 * 70 * 71 * \section asfdoc_samb_gpio_prerequisites Prerequisites 72 * 73 * There are no prerequisites for this module. 74 * 75 * 76 * \section asfdoc_samb_gpio_module_overview Module Overview 77 * 78 * The device GPIO module provides an interface between the user application 79 * logic and external hardware peripherals, when general pin state manipulation 80 * is required. This driver provides an easy-to-use interface to the physical 81 * pin input samplers and output drivers, so that pins can be read from or 82 * written to for general purpose external hardware control. 83 * 84 * There are the different peripheral functions that are Software selectable 85 * on a per pin basis. This allows for maximum flexibility of mapping desired 86 * interfaces on GPIO pins. MUX1 option allows for any MEGAMUX option to be 87 * assigned to a GPIO. 88 * 89 * An example is to illustrate the available options for pin LP_GPIO_3, depending 90 * on the pin-MUX option selected: 91 * - MUX0: the pin will function as bit 3 of the GPIO bus and is controlled by 92 * the GPIO controller in the ARM subsystem 93 * - MUX1: any option from the MEGAMUX table can be selected, for example it 94 * can be a quad_dec, pwm, or any of the other functions listed in the 95 * MEGAMUX table 96 * - MUX2: the pin will function as UART1 TXD; this can be also achieved with 97 * the MUX1 option via MEGAMUX, but the MUX2 option allows a shortcut 98 * for the recommended pinout 99 * - MUX3: this option is not used and thus defaults to the GPIO option (same 100 * as MUX0) 101 * - MUX4: the pin will function as SPI1 MOSI (this option is not available 102 * through MEGAMUX) 103 * - MUX5: the pin will function as SPI0 MOSI (this option is not available 104 * through MEGAMUX) 105 * - MUX6: the pin will function as SPI FLASH SCK (this option is not available 106 * through MEGAMUX) 107 * - MUX7: the pin will function as bit 3 of the test output bus, giving access 108 * to various debug signals 109 * 110 * \section asfdoc_samb_gpio_special_considerations Special Considerations 111 * 112 * There are no special considerations for this module. 113 * 114 * \section asfdoc_samb_gpio_extra_info Extra Information 115 * 116 * For extra information, see \ref asfdoc_samb_gpio_extra. This includes: 117 * - \ref asfdoc_samb_gpio_extra_acronyms 118 * - \ref asfdoc_samb_gpio_extra_dependencies 119 * - \ref asfdoc_samb_gpio_extra_errata 120 * - \ref asfdoc_samb_gpio_extra_history 121 * 122 * 123 * \section asfdoc_samb_gpio_examples Examples 124 * 125 * For a list of examples related to this driver, see 126 * \ref asfdoc_samb_gpio_exqsg. 127 * 128 * 129 * \section asfdoc_samb_gpio_api_overview API Overview 130 * @{ 131 */ 132 133 #include <compiler.h> 134 #include <system_sam_b.h> 135 136 #ifdef __cplusplus 137 extern "C" { 138 #endif 139 140 /** 141 * \brief GPIO pin direction configuration enum. 142 * 143 * Enum for the possible pin direction settings of the gpio pin configuration 144 * structure, to indicate the direction the pin should use. 145 */ 146 enum gpio_pin_dir { 147 /** The pin's input buffer should be enabled, so that the pin state can 148 * be read. */ 149 GPIO_PIN_DIR_INPUT, 150 /** The pin's output buffer should be enabled, so that the pin state can 151 * be set. */ 152 GPIO_PIN_DIR_OUTPUT, 153 }; 154 155 /** 156 * \brief GPIO pin input pull configuration enum. 157 * 158 * Enum for the possible pin pull settings of the GPIO pin configuration 159 * structure, to indicate the type of logic level pull the pin should use. 160 */ 161 enum gpio_pin_pull { 162 /** No logical pull should be applied to the pin */ 163 GPIO_PIN_PULL_NONE, 164 /** Pin should be pulled up when idle */ 165 GPIO_PIN_PULL_UP , 166 /** Pin should be pulled down when idle */ 167 GPIO_PIN_PULL_DOWN, 168 }; 169 170 /** 171 * \brief GPIO pinmux selection enum. 172 * 173 * Enum for the pinmux settings of the GPIO pin configuration. 174 */ 175 enum gpio_pinmux_sel { 176 /** PINMUX selection 0 */ 177 GPIO_PINMUX_SEL_0 = 0, 178 /** PINMUX selection 1 */ 179 GPIO_PINMUX_SEL_1, 180 /** PINMUX selection 2 */ 181 GPIO_PINMUX_SEL_2, 182 /** PINMUX selection 3 */ 183 GPIO_PINMUX_SEL_3, 184 /** PINMUX selection 4 */ 185 GPIO_PINMUX_SEL_4, 186 /** PINMUX selection 5 */ 187 GPIO_PINMUX_SEL_5, 188 /** PINMUX selection 6 */ 189 GPIO_PINMUX_SEL_6, 190 /** PINMUX selection 7 */ 191 GPIO_PINMUX_SEL_7, 192 }; 193 194 /** 195 * \brief GPIO module instance 196 * 197 * Forward Declaration for the device instance. 198 */ 199 struct gpio_module; 200 201 /** 202 * \brief GPIO callback type 203 * 204 * Type of the callback functions. 205 */ 206 typedef void (*gpio_callback_t)(void); 207 208 /** 209 * \brief GPIO Callback enum 210 * 211 * Callbacks for the GPIO driver. 212 */ 213 enum gpio_callback { 214 /** Callback for low level */ 215 GPIO_CALLBACK_LOW, 216 /** Callback for high level */ 217 GPIO_CALLBACK_HIGH, 218 /** Callback for rising edge */ 219 GPIO_CALLBACK_RISING, 220 /** Callback for falling edge */ 221 GPIO_CALLBACK_FALLING, 222 /** Number of available callbacks */ 223 GPIO_CALLBACK_N, 224 }; 225 226 /** 227 * \brief GPIO pin configuration structure. 228 * 229 * Configuration structure for a GPIO pin instance. This structure should be 230 * initialized by the \ref GPIO_get_config_defaults() function before being 231 * modified by the user application. 232 */ 233 struct gpio_config { 234 /** GPIO buffer input/output direction */ 235 enum gpio_pin_dir direction; 236 237 /** GPIO pull-up/pull-down for input pins */ 238 enum gpio_pin_pull input_pull; 239 240 /** Enable lowest possible powerstate on the pin 241 * 242 * \note All other configurations will be ignored, the pin will be disabled 243 */ 244 bool powersave; 245 /** Enable AON_GPIOs to wakeup MCU from ULP mode 246 * 247 * \note Only AON_GPIO_0, AON_GPIO_1, and AON_GPIO_2 could enable this feature 248 */ 249 bool aon_wakeup; 250 }; 251 252 /** 253 * \brief GPIO driver software device instance structure. 254 * 255 * GPIO driver software instance structure, used to retain software 256 * state information of an associated hardware module instance. 257 * 258 * \note The fields of this structure should not be altered by the user 259 * application; they are reserved for module-internal use only. 260 */ 261 struct gpio_module { 262 #if !defined(__DOXYGEN__) 263 /** Pointer to the hardware instance */ 264 Gpio *hw; 265 /** Array to store callback function pointers in */ 266 gpio_callback_t callback[16]; 267 /** Bit mask for callbacks registered */ 268 uint16_t callback_reg_mask; 269 /** Bit mask for callbacks enabled */ 270 uint16_t callback_enable_mask; 271 #endif 272 }; 273 274 /** \name Configuration and initialization 275 * @{ 276 */ 277 278 void gpio_get_config_defaults(struct gpio_config *const config); 279 enum status_code gpio_pin_set_config(const uint8_t gpio_pin, 280 const struct gpio_config *config); 281 282 /** @} */ 283 284 /** \name State reading/writing (logical pin orientated) 285 * @{ 286 */ 287 288 bool gpio_pin_get_input_level(const uint8_t gpio_pin); 289 bool gpio_pin_get_output_level(const uint8_t gpio_pin); 290 void gpio_pin_set_output_level(const uint8_t gpio_pin, const bool level); 291 void gpio_pin_toggle_output_level(const uint8_t gpio_pin); 292 /** @} */ 293 294 /** \name PINMUX selection configuration 295 * @{ 296 */ 297 void gpio_pinmux_cofiguration(const uint8_t gpio_pin, uint16_t pinmux_sel); 298 /** @}*/ 299 300 /** \name GPIO callback config 301 * @{ 302 */ 303 void gpio_register_callback(uint8_t gpio_pin, gpio_callback_t callback_func, 304 enum gpio_callback callback_type); 305 void gpio_unregister_callback(uint8_t gpio_pin, 306 enum gpio_callback callback_type); 307 void gpio_enable_callback(uint8_t gpio_pin); 308 void gpio_disable_callback(uint8_t gpio_pin); 309 void gpio_init(void); 310 /** @}*/ 311 312 /** @}*/ 313 314 #ifdef __cplusplus 315 } 316 #endif 317 318 319 /** 320 * \page asfdoc_samb_gpio_extra Extra Information for GPIO Driver 321 * 322 * \section asfdoc_samb_gpio_extra_acronyms Acronyms 323 * Below is a table listing the acronyms used in this module, along with their 324 * intended meanings. 325 * 326 * <table> 327 * <tr> 328 * <th>Acronym</th> 329 * <th>Description</th> 330 * </tr> 331 * <tr> 332 * <td>GPIO</td> 333 * <td>General Purpose Input/Output</td> 334 * </tr> 335 * </table> 336 * 337 * 338 * \section asfdoc_samb_gpio_extra_dependencies Dependencies 339 * There are no dependencies related to this driver. 340 * 341 * 342 * \section asfdoc_samb_gpio_extra_errata Errata 343 * There are no errata related to this driver. 344 * 345 * 346 * \section asfdoc_samb_gpio_extra_history Module History 347 * An overview of the module history is presented in the table below, with 348 * details on the enhancements and fixes made to the module since its first 349 * release. The current version of this corresponds to the newest version in 350 * the table. 351 * 352 * <table> 353 * <tr> 354 * <th>Changelog</th> 355 * </tr> 356 * <tr> 357 * <td>Initial Release</td> 358 * </tr> 359 * </table> 360 */ 361 362 /** 363 * \page asfdoc_samb_gpio_exqsg Examples for GPIO Driver 364 * 365 * This is a list of the available Quick Start guides (QSGs) and example 366 * applications for \ref asfdoc_samb_gpio_group. QSGs are simple examples with 367 * step-by-step instructions to configure and use this driver in a selection of 368 * use cases. Note that QSGs can be compiled as a standalone application or be 369 * added to the user application. 370 * 371 * - \subpage asfdoc_samb_gpio_basic_use_case 372 * 373 * \page asfdoc_samb_gpio_document_revision_history Document Revision History 374 * 375 * <table> 376 * <tr> 377 * <th>Doc. Rev.</td> 378 * <th>Date</td> 379 * <th>Comments</td> 380 * </tr> 381 * <tr> 382 * <td>A</td> 383 * <td>09/2015</td> 384 * <td>Initial release</td> 385 * </tr> 386 * </table> 387 */ 388 389 #endif 390