2 * Copyright (c) 2015-2016, Texas Instruments Incorporated
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 /** ============================================================================
37 * The GPIO header file should be included in an application as follows:
39 * #include <ti/drivers/GPIO.h>
43 * The GPIO module allows you to manage General Purpose I/O pins via simple
44 * and portable APIs. GPIO pin behavior is usually configured statically,
45 * but can also be configured or reconfigured at runtime.
47 * Because of its simplicity, the GPIO driver does not follow the model of
48 * other TI-RTOS drivers in which a driver application interface has
49 * separate device-specific implementations. This difference is most
50 * apparent in the GPIOxxx_Config structure, which does not require you to
51 * specify a particular function table or object.
54 * The following code example demonstrates how
55 * to configure a GPIO pin to generate an interrupt and how to toggle an
56 * an LED on and off within the registered interrupt callback function.
62 * // Driver Header file
63 * #include <ti/drivers/GPIO.h>
65 * // Example/Board Header file
70 * // Call GPIO driver init function
74 * GPIO_write(Board_GPIO_LED0, Board_GPIO_LED_ON);
76 * // install Button callback
77 * GPIO_setCallback(Board_GPIO_BUTTON0, gpioButtonFxn0);
79 * // Enable interrupts
80 * GPIO_enableInt(Board_GPIO_BUTTON0);
86 * // ======== gpioButtonFxn0 ========
87 * // Callback function for the GPIO interrupt on Board_GPIO_BUTTON0.
89 * void gpioButtonFxn0(unsigned int index)
92 * GPIO_toggle(Board_GPIO_LED0);
97 * Details for the example code above are described in the following
100 * ### GPIO Driver Configuration #
102 * In order to use the GPIO APIs, the application is required
103 * to provide 3 structures in the Board.c file:
104 * 1. An array of @ref GPIO_PinConfig elements that defines the
105 * initial configuration of each pin used by the application. A
106 * pin is referenced in the application by its corresponding index in this
107 * array. The pin type (that is, INPUT/OUTPUT), its initial state (that is
108 * OUTPUT_HIGH or LOW), interrupt behavior (RISING/FALLING edge, etc.), and
109 * device specific pin identification are configured in each element
110 * of this array (see @ref GPIO_PinConfigSettings).
111 * Below is an MSP432 device specific example of the GPIO_PinConfig array:
114 * // Array of Pin configurations
115 * // NOTE: The order of the pin configurations must coincide with what was
116 * // defined in MSP_EXP432P401R.h
117 * // NOTE: Pins not used for interrupts should be placed at the end of the
118 * // array. Callback entries can be omitted from callbacks array to
119 * // reduce memory usage.
121 * GPIO_PinConfig gpioPinConfigs[] = {
123 * // MSP_EXP432P401R_GPIO_S1
124 * GPIOMSP432_P1_1 | GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING,
125 * // MSP_EXP432P401R_GPIO_S2
126 * GPIOMSP432_P1_4 | GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING,
129 * // MSP_EXP432P401R_GPIO_LED1
130 * GPIOMSP432_P1_0 | GPIO_CFG_OUT_STD | GPIO_CFG_OUT_STR_HIGH | GPIO_CFG_OUT_LOW,
131 * // MSP_EXP432P401R_GPIO_LED_RED
132 * GPIOMSP432_P2_0 | GPIO_CFG_OUT_STD | GPIO_CFG_OUT_STR_HIGH | GPIO_CFG_OUT_LOW,
136 * 2. An array of @ref GPIO_CallbackFxn elements that is used to store
137 * callback function pointers for GPIO pins configured with interrupts.
138 * The indexes for these array elements correspond to the pins defined
139 * in the GPIO_pinConfig array. These function pointers can be defined
140 * statically by referencing the callback function name in the array
141 * element, or dynamically, by setting the array element to NULL and using
142 * GPIO_setCallback() at runtime to plug the callback entry.
143 * Pins not used for interrupts can be omitted from the callback array to
144 * reduce memory usage (if they are placed at the end of GPIO_pinConfig
145 * array). The callback function syntax should match the following:
147 * void (*GPIO_CallbackFxn)(unsigned int index);
149 * The index parameter is the same index that was passed to
150 * GPIO_setCallback(). This allows the same callback function to be used
151 * for multiple GPIO interrupts, by using the index to identify the GPIO
152 * that caused the interrupt.
153 * Keep in mind that the callback functions will be called in the context of
154 * an interrupt service routine and should be designed accordingly. When an
155 * interrupt is triggered, the interrupt status of all (interrupt enabled) pins
156 * on a port will be read, cleared, and the respective callbacks will be
157 * executed. Callbacks will be called in order from least significant bit to
158 * most significant bit.
159 * Below is an MSP432 device specific example of the GPIO_CallbackFxn array:
162 * // Array of callback function pointers
163 * // NOTE: The order of the pin configurations must coincide with what was
164 * // defined in MSP_EXP432P401R.h
165 * // NOTE: Pins not used for interrupts can be omitted from callbacks array
166 * // to reduce memory usage (if placed at end of gpioPinConfigs
169 * GPIO_CallbackFxn gpioCallbackFunctions[] = {
170 * // MSP_EXP432P401R_GPIO_S1
172 * // MSP_EXP432P401R_GPIO_S2
177 * 3. A device specific GPIOxxx_Config structure that tells the GPIO
178 * driver where the two aforementioned arrays are and the number of elements
179 * in each. The interrupt priority of all pins configured to generate
180 * interrupts is also specified here. Values for the interrupt priority are
181 * device-specific. You should be well-acquainted with the interrupt
182 * controller used in your device before setting this parameter to a
183 * non-default value. The sentinel value of (~0) (the default value) is
184 * used to indicate that the lowest possible priority should be used.
185 * Below is an MSP432 device specific example of a GPIOxxx_Config
189 * // MSP432 specific GPIOxxx_Config structure
191 * const GPIOMSP432_Config GPIOMSP432_config = {
192 * .pinConfigs = (GPIO_PinConfig *)gpioPinConfigs,
193 * .callbacks = (GPIO_CallbackFxn *)gpioCallbackFunctions,
194 * .numberOfPinConfigs = sizeof(gpioPinConfigs)/sizeof(GPIO_PinConfig),
195 * .numberOfCallbacks = sizeof(gpioCallbackFunctions)/sizeof(GPIO_CallbackFxn),
196 * .intPriority = (~0)
200 * ### Initializing the GPIO Driver #
202 * GPIO_init() must be called before any other GPIO APIs. This function
203 * configures each GPIO pin in the user-provided @ref GPIO_PinConfig
204 * array according to the defined settings. The user can also reconfigure
205 * a pin dynamically after GPIO_init() is called by using the
206 * GPIO_setConfig(), and GPIO_setCallback() APIs.
210 * Unlike most other TI-RTOS drivers, the GPIO driver has no generic function
211 * table with pointers to device-specific API implementations. All the generic
212 * GPIO APIs are implemented by the device-specific GPIO driver module.
213 * Additionally, there is no notion of an instance 'handle' with the GPIO driver.
214 * GPIO pins are referenced by their numeric index in the GPIO_PinConfig array.
215 * This design approach was used to enhance runtime and memory efficiency.
217 * ============================================================================
220 #ifndef ti_drivers_GPIO__include
221 #define ti_drivers_GPIO__include
230 * @name GPIO_STATUS_* macros are general status codes returned by GPIO driver APIs.
235 * @brief Common GPIO status code reservation offset.
237 * GPIO driver implementations should offset status codes with
238 * GPIO_STATUS_RESERVED growing negatively.
240 * Example implementation specific status codes:
242 * #define GPIOTXYZ_STATUS_ERROR1 GPIO_STATUS_RESERVED - 1
243 * #define GPIOTXYZ_STATUS_ERROR0 GPIO_STATUS_RESERVED - 0
244 * #define GPIOTXYZ_STATUS_ERROR2 GPIO_STATUS_RESERVED - 2
247 #define GPIO_STATUS_RESERVED (-32)
250 * @brief Successful status code returned by GPI_setConfig().
252 * GPI_setConfig() returns GPIO_STATUS_SUCCESS if the API was executed
255 #define GPIO_STATUS_SUCCESS (0)
258 * @brief Generic error status code returned by GPI_setConfig().
260 * GPI_setConfig() returns GPIO_STATUS_ERROR if the API was not executed
263 #define GPIO_STATUS_ERROR (-1)
267 * @brief GPIO pin configuration settings
269 * The upper 16 bits of the 32 bit PinConfig is reserved
270 * for pin configuration settings.
272 * The lower 16 bits are reserved for device-specific
273 * port/pin identifications
275 typedef uint32_t GPIO_PinConfig;
279 * Internally used configuration bit access macros.
281 #define GPIO_CFG_IO_MASK 0x00ff0000
282 #define GPIO_CFG_IO_LSB 16
283 #define GPIO_CFG_OUT_TYPE_MASK 0x00060000
284 #define GPIO_CFG_OUT_TYPE_LSB 17
285 #define GPIO_CFG_IN_TYPE_MASK 0x00060000
286 #define GPIO_CFG_IN_TYPE_LSB 17
287 #define GPIO_CFG_OUT_STRENGTH_MASK 0x00f00000
288 #define GPIO_CFG_OUT_STRENGTH_LSB 20
289 #define GPIO_CFG_INT_MASK 0x07000000
290 #define GPIO_CFG_INT_LSB 24
291 #define GPIO_CFG_OUT_BIT 19
295 * \defgroup GPIO_PinConfigSettings Macros used to configure GPIO pins
298 /** @name GPIO_PinConfig output pin configuration macros
301 #define GPIO_CFG_OUTPUT (((uint32_t) 0) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Pin is an output. */
302 #define GPIO_CFG_OUT_STD (((uint32_t) 0) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Output pin is actively driven high and low */
303 #define GPIO_CFG_OUT_OD_NOPULL (((uint32_t) 2) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Output pin is Open Drain */
304 #define GPIO_CFG_OUT_OD_PU (((uint32_t) 4) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Output pin is Open Drain w/ pull up */
305 #define GPIO_CFG_OUT_OD_PD (((uint32_t) 6) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Output pin is Open Drain w/ pull dn */
307 #define GPIO_CFG_OUT_STR_LOW (((uint32_t) 0) << GPIO_CFG_OUT_STRENGTH_LSB) /*!< @hideinitializer Set output pin strengh to low */
308 #define GPIO_CFG_OUT_STR_MED (((uint32_t) 1) << GPIO_CFG_OUT_STRENGTH_LSB) /*!< @hideinitializer Set output pin strengh to medium */
309 #define GPIO_CFG_OUT_STR_HIGH (((uint32_t) 2) << GPIO_CFG_OUT_STRENGTH_LSB) /*!< @hideinitializer Set output pin strengh to high */
311 #define GPIO_CFG_OUT_HIGH (((uint32_t) 1) << GPIO_CFG_OUT_BIT) /*!< @hideinitializer Set pin's output to 1. */
312 #define GPIO_CFG_OUT_LOW (((uint32_t) 0) << GPIO_CFG_OUT_BIT) /*!< @hideinitializer Set pin's output to 0. */
315 /** @name GPIO_PinConfig input pin configuration macros
318 #define GPIO_CFG_INPUT (((uint32_t) 1) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Pin is an input. */
319 #define GPIO_CFG_IN_NOPULL (((uint32_t) 1) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Input pin with no internal PU/PD */
320 #define GPIO_CFG_IN_PU (((uint32_t) 3) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Input pin with internal PU */
321 #define GPIO_CFG_IN_PD (((uint32_t) 5) << GPIO_CFG_IO_LSB) /*!< @hideinitializer Input pin with internal PD */
324 /** @name GPIO_PinConfig interrupt configuration macros
327 #define GPIO_CFG_IN_INT_NONE (((uint32_t) 0) << GPIO_CFG_INT_LSB) /*!< @hideinitializer No Interrupt */
328 #define GPIO_CFG_IN_INT_FALLING (((uint32_t) 1) << GPIO_CFG_INT_LSB) /*!< @hideinitializer Interrupt on falling edge */
329 #define GPIO_CFG_IN_INT_RISING (((uint32_t) 2) << GPIO_CFG_INT_LSB) /*!< @hideinitializer Interrupt on rising edge */
330 #define GPIO_CFG_IN_INT_BOTH_EDGES (((uint32_t) 3) << GPIO_CFG_INT_LSB) /*!< @hideinitializer Interrupt on both edges */
331 #define GPIO_CFG_IN_INT_LOW (((uint32_t) 4) << GPIO_CFG_INT_LSB) /*!< @hideinitializer Interrupt on low level */
332 #define GPIO_CFG_IN_INT_HIGH (((uint32_t) 5) << GPIO_CFG_INT_LSB) /*!< @hideinitializer Interrupt on high level */
335 /** @name Special GPIO_PinConfig configuration macros
340 * @brief 'Or' in this @ref GPIO_PinConfig definition to inform GPIO_setConfig()
341 * to only configure the interrupt attributes of a GPIO input pin.
343 #define GPIO_CFG_IN_INT_ONLY (((uint32_t) 1) << 27) /*!< @hideinitializer configure interrupt only */
346 * @brief Use this @ref GPIO_PinConfig definition to inform GPIO_init()
347 * NOT to configure the corresponding pin
349 #define GPIO_DO_NOT_CONFIG 0x40000000 /*!< @hideinitializer Do not configure this Pin */
352 /** @} end of GPIO_PinConfigSettings group */
355 * @brief GPIO callback function type
357 * @param index GPIO index. This is the same index that
358 * was passed to GPIO_setCallback(). This allows
359 * you to use the same callback function for multiple
360 * GPIO interrupts, by using the index to identify
361 * the GPIO that caused the interrupt.
363 typedef void (*GPIO_CallbackFxn)(uint_least8_t index);
366 * @brief Clear a GPIO pin interrupt flag
368 * Clears the GPIO interrupt for the specified index.
370 * Note: It is not necessary to call this API within a
371 * callback assigned to a pin.
373 * @param index GPIO index
375 extern void GPIO_clearInt(uint_least8_t index);
378 * @brief Disable a GPIO pin interrupt
380 * Disables interrupts for the specified GPIO index.
382 * @param index GPIO index
384 extern void GPIO_disableInt(uint_least8_t index);
387 * @brief Enable a GPIO pin interrupt
389 * Enables GPIO interrupts for the selected index to occur.
391 * Note: Prior to enabling a GPIO pin interrupt, make sure
392 * that a corresponding callback function has been provided.
393 * Use the GPIO_setCallback() API for this purpose at runtime.
394 * Alternatively, the callback function can be statically
395 * configured in the GPIO_CallbackFxn array provided.
397 * @param index GPIO index
399 extern void GPIO_enableInt(uint_least8_t index);
402 * @brief Get the current configuration for a gpio pin
404 * The pin configuration is provided in the static GPIO_PinConfig array,
405 * but can be changed with GPIO_setConfig(). GPIO_getConfig() gets the
406 * current pin configuration.
408 * @param index GPIO index
409 * @param pinConfig Location to store device specific pin
410 * configuration settings
412 extern void GPIO_getConfig(uint_least8_t index, GPIO_PinConfig *pinConfig);
415 * @brief Initializes the GPIO module
417 * The pins defined in the application-provided *GPIOXXX_config* structure
418 * are initialized accordingly.
420 * @pre The GPIO_config structure must exist and be persistent before this
421 * function can be called. This function must also be called before
422 * any other GPIO driver APIs.
424 extern void GPIO_init();
427 * @brief Reads the value of a GPIO pin
429 * The value returned will either be zero or one depending on the
432 * @param index GPIO index
434 * @return 0 or 1, depending on the state of the pin.
436 extern uint_fast8_t GPIO_read(uint_least8_t index);
439 * @brief Bind a callback function to a GPIO pin interrupt
441 * Associate a callback function with a particular GPIO pin interrupt.
443 * Callbacks can be changed at any time, making it easy to switch between
444 * efficient, state-specific interrupt handlers.
446 * Note: The callback function is called within the context of an interrupt
449 * Note: This API does not enable the GPIO pin interrupt.
450 * Use GPIO_enableInt() and GPIO_disableInt() to enable
451 * and disable the pin interrupt as necessary.
453 * Note: it is not necessary to call GPIO_clearInt() within a callback.
454 * That operation is performed internally before the callback is invoked.
456 * @param index GPIO index
457 * @param callback address of the callback function
459 extern void GPIO_setCallback(uint_least8_t index, GPIO_CallbackFxn callback);
462 * @brief Configure the gpio pin
464 * Dynamically configure a gpio pin to a device specific setting.
465 * For many applications, the pin configurations provided in the static
466 * GPIO_PinConfig array is sufficient.
468 * For input pins with interrupt configurations, a corresponding interrupt
469 * object will be created as needed.
471 * @param index GPIO index
472 * @param pinConfig device specific pin configuration settings
474 extern int_fast16_t GPIO_setConfig(uint_least8_t index,
475 GPIO_PinConfig pinConfig);
478 * @brief Toggles the current state of a GPIO
480 * @param index GPIO index
482 extern void GPIO_toggle(uint_least8_t index);
485 * @brief Writes the value to a GPIO pin
487 * @param index GPIO index
488 * @param value must be either 0 or 1
490 extern void GPIO_write(uint_least8_t index, unsigned int value);
496 #endif /* ti_drivers_GPIO__include */