TI-RTOS for SimpleLink Wireless MCUs  2.14.03.28
PIN.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
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.
15  *
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.
19  *
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.
31  */
32 
33 /*!*****************************************************************************
34  * @file PIN.h
35  * @brief Generic PIN & GPIO driver
36  *
37  * To use the PIN driver ensure that the correct TI-RTOS driver library for your
38  * device is linked in and include this header file:
39  * @code
40  * #include <ti/drivers/PIN.h>
41  * @endcode
42  *
43  * In order to use device-specific functionality or to use the size/speed-
44  * optimized versions of some of the PIN driver functions that circumvent error
45  * and resource checking, link in the correct TI-RTOS driver library for your
46  * device and include the device-specific PIN driver header file (which in turn
47  * includes PIN.h). As an example for the CC26xx family of devices:
48  * @code
49  * #include <ti/drivers/pin/PINCC26xx.h>
50  * @endcode
51  *
52  * # Overview #
53  * The PIN driver allows clients (applications or other drivers) to allocate
54  * and control the I/O pins on the device. The pins can either be software-
55  * controlled general-purpose I/O (GPIO) or connected to hardware peripherals.
56  * Furthermore, the PIN driver allows clients to configure interrupt
57  * functionality on the pins to receive callbacks (and potentially wake up from
58  * the standby or idle power modes) on configurable signal edges.
59  *
60  * Most other drivers rely on functionality in the PIN driver.
61  *
62  * ## Structure ##
63  * In order to provide a generic driver interface, this file (PIN.h) only
64  * defines the API and some common data types and macros of the driver. A PIN
65  * client (application or driver) can in most cases only use the generic PIN
66  * API, however, for more advanced usage where device-specific pin
67  * configuration is used or device-specific PIN driver API extensions are
68  * used must use the device-specific PIN driver API.
69  *
70  * The device-independent API is implemented as function calls with pin
71  * access control based on the PIN client handle. For time-critical
72  * applications the device-specific API can be used directly, as these
73  * API functions are implemented as inlined functions without access control.
74  *
75  * ## Functionality ##
76  * The PIN module provides the following functionality:
77  * - Initialize I/O pins upon boot to a default configuration (possibly
78  * user-generated)
79  * - Provides atomic manipulation of I/O pin hardware registers to allow safe
80  * simultaneous use of I/O pin resources
81  * - I/O pin allocation
82  * - A set of pins can be allocated receiving a pin set handle.
83  * Typically each peripheral driver will allocate a set of pins and an
84  * application must allocate the pins it uses too
85  * - When a pin set is deallocated all the pins in it revert to the state
86  * they were initialized to at boot
87  * - General-purpose I/O (GPIO) services
88  * - Read input buffer value
89  * - Read and set output buffer value
90  * - Read and set output buffer enable
91  * - Access as single pin or port (muliple pins simultaneously)
92  * - Protect pin manipulation
93  * - Pins in an allocated set can only be manipulated using the corresponding
94  * handle.
95  * - No handle is needed to read input and output buffer values
96  * - I/O buffer/driver control
97  * - Input mode (detached, hysteresis, pull-up, pull-down)
98  * - Output mode (tristated, push-pull, open drain, open source)
99  * - Output driver strength control
100  * - Output driver slew rate control
101  * - I/O source/target selection (device-specific driver only)
102  * - Map pin to GPIO, peripheral or HW observation signal
103  * - Configuration of I/O interrupt and wakeup from standby
104  * - Interrupt configuration: signal edge to interrupt on, interrupt mask,
105  * callback function registration
106  * - Pins that have enabled interrupts will also wake up the device from low-
107  * power modes like standby and idle upon events
108  * - Provides data types and enums/defines for use in pin configurations
109  * definitions in board files, drivers and applications
110  *
111  * ## Pin Allocation ##
112  * The purpose of being able to allocate pins to a pin set is to:
113  * - Manage pin resources
114  * - Give exclusive, protected access to these pins
115  * - Establish a driver state in connection with these pins that allow
116  * functionality such as I/O interrupt callback and I/O port operations
117  * in a safe manner
118  *
119  * | API function | Description |
120  * |--------------------|------------------------------------------------------|
121  * | PIN_open() | Allocate pins to a set, returns handle |
122  * | PIN_add() | Add pin to pin set for open PIN handle |
123  * | PIN_remove() | Removes pin from pin set foropen PIN handle |
124  * | PIN_close() | Deallocate pin set, revert to original GPIO state |
125  *
126  * ## GPIO ##
127  * Pins that are to be used as software-controlled general-purpose I/O (GPIO)
128  * need to be allocated in the same manner as for pins that will be mapped to
129  * hardware peripheral ports. A pin set requested with a PIN_open() call may
130  * contain a mix of pins to be used for GPIO and hardware-mapped pins.
131  *
132  * When a pin is deallocated using PIN_close() it reverts to the GPIO
133  * configuration it was given in the initial call to PIN_init().
134  *
135  * | API function | Description |
136  * |----------------------|---------------------------------------------------|
137  * | PIN_init() | Initialize I/O pins to a safe GPIO state |
138  * | PIN_open() | Allocate pins to a set, returns handle |
139  * | PIN_close() | Deallocate pin set, revert to original GPIO state |
140  * | PIN_setConfig() | Sets parts of or complete pin configuration |
141  * | PIN_getConfig() | Returns pin configuration |
142  * | PIN_setOutputEnable()| Control output enable of GPIO pin |
143  * | PIN_getInputValue() | Read input value on pin |
144  * | PIN_setOutputValue() | Set output value of GPIO pin |
145  * | PIN_getOutputValue() | Get current output value of GPIO pin |
146  *
147  * ## GPIO Ports ##
148  * Sometimes it is necessary to be able to read from, write to or control
149  * multiple pins simultaneously (in time). The PIN driver allows a set of
150  * allocated pins, if they reside on the same GPIO port in the underlying
151  * hardware, to be manipulated simultaneously.
152  *
153  * | API function | Description |
154  * |--------------------------|---------------------------------------------------|
155  * | PIN_open() | Allocate pins to a set, returns handle |
156  * | PIN_close() | Deallocate pin set, revert to original GPIO state |
157  * | PIN_getPortMask() | Returns bitmask for allocated pins in GPIO port |
158  * | PIN_getPortInputValue() | Returns input value of whole GPIO port |
159  * | PIN_setPortOutputValue() | Sets output value of whole GPIO port (masked) |
160  * | PIN_getPortOutputValue() | Get current output value of whole GPIO port |
161  * | PIN_getPortOutputValue() | Sets output value of whole GPIO port (masked) |
162  * | PIN_setPortOutputEnable()| Sets output enable of whole GPIO port (masked) |
163  *
164  * ## I/O Pin Configuration ##
165  * Different devices provide different levels of configurability of I/O pins.
166  * The PIN driver provides a fairly extensive set of @ref PIN_GENERIC_FLAGS
167  * "generic IO configuration options" that are device-independent, all of which
168  * might not be supported by the underlying device-specific PIN driver and
169  * hardware. Likewise, the underlying device-specific PIN driver and hardware
170  * might support additional configuration options not covered by the generic
171  * options.
172  *
173  * To allow both independence from and flexibility to use features on the target
174  * device, the #PIN_Config entries used by the PIN driver allows use of either
175  * a set of @ref PIN_GENERIC_FLAGS "generic PIN configuration options" or a
176  * device-specific set of PIN configuration options defined in the underlying
177  * device-specific PIN driver (e.g. PINCC26XX.h)
178  *
179  * ### Mapping to GPIO or Peripheral ###
180  * Since the amount of flexibilty in which peripherals can be mapped to which
181  * pins and the manner in which this needs to be set up is highly
182  * device-specific, functions for configuring this is not part of the generic
183  * PIN driver API but is left to be implemented by device-specific PIN drivers.
184  * See the releavant device-specific PIN driver (e.g. PINCC26XX.h) for details.
185  *
186  * ### Input Mode ###
187  * The input mode of a pin controls:
188  * - Input buffer enable
189  * - Pull-ups or pull-downs
190  * - Hysteresis of input buffer
191  * - Inversion of logical input level
192  * - Potentially, device-specific options
193  * The input mode is set initially with PIN_init() or at a later stage with
194  * PIN_setConfig() and a bitmask with the relevant options
195  *
196  * | API function | Description |
197  * |------------------|-------------------------------------------------------|
198  * | PIN_init() | Initialize IOs to a safe GPIO state |
199  * | PIN_getConfig() | Returns pin configuration |
200  * | PIN_setConfig() | Sets parts of or complete pin configuration |
201  *
202  * ### Output Mode ###
203  * The output mode of a pin controls:
204  * - Output buffer enable
205  * - Output driver mode (push-pull, open-drain, open-source)
206  * - Output driver slew control
207  * - Output driver current (drive strength)
208  * - Inversion of logical output level
209  * - Potentially, device-specific options
210  *
211  * | API function | Description |
212  * |----------------------|---------------------------------------------------|
213  * | PIN_init() | Initialize IOs to a safe GPIO state |
214  * | PIN_setOutputEnable()| Control output enable of GPIO pins |
215  * | PIN_getConfig() | Returns pin configuration |
216  * | PIN_setConfig() | Sets parts of or complete pin configuration |
217  *
218  * ### Pin Interrupt and Pin Wakeup ###
219  * Pin interrupts are used to process asynchronous signal edge events on pins
220  * and potentially wake the device up from low power sleep modes. To use pin
221  * interrupts the relevant pins must be allocated and a interrupt callback
222  * registered by the client.
223  *
224  * | API function | Description |
225  * |---------------------|----------------------------------------------------|
226  * | PIN_init() | Initialize IOs to a safe GPIO state |
227  * | PIN_getConfig() | Returns pin configuration |
228  * | PIN_setConfig() | Sets parts of or complete pin configuration |
229  * | PIN_setInterrupt() | Control interrupt enable and edge for pin |
230  * | PIN_registerIntCb() | Register callback function for a set of pins |
231  * | PIN_setUserArg() | Sets a user argument associated with the handle |
232  * | PIN_getUserArg() | Gets a user argument associated with the handle |
233  *
234  * ## PIN Data Types ##
235  * The PIN driver defines the following data types:
236  * - #PIN_Id: identifies a pin in arguments or lists
237  * - #PIN_Config: provides I/O configuration options for a pin and also embeds
238  * a #PIN_Id identifier. See @ref PIN_GENERIC_FLAGS "available flags/fields"
239  *
240  * ## PIN Config Flags/Fields and Bitmasks ##
241  * The PIN driver uses the #PIN_Config data type many places and it merits some
242  * additional attention. A #PIN_Config value consists of a collection of flags
243  * and fields that define how an I/O pin and its attached GPIO interface should
244  * behave electrically and logically. In addition a #PIN_Config value also
245  * embeds a #PIN_Id pin ID, identifying which pin it refers to.
246  *
247  * A #PIN_Config value can use one of two mutually exclusive sets of flags and
248  * fields: @ref PIN_GENERIC_FLAGS "device-independent options" defined in
249  * PIN.h or device-dependent options defined in the device-specific
250  * implementation of the PIN driver interface. Any function that uses
251  * #PIN_Config will accept both option types, just not at the same time.
252  * PIN_getConfig() always returns device-independent options, an additional
253  * device-specific version (e.g. PINCC26XX_getConfig()) might return
254  * device-specific options.
255  *
256  * The bitmask argument for PIN_setConfig() decides which of the options the
257  * call should affect. All other options are kept at their current values in
258  * hardware. Thus PIN_setConfig(hPins, PIN_BM_PULLING, PIN_BM_PULLUP) will only
259  * change the pullup/pulldown configuration of the pin, leaving everything
260  * else, such as for instance output enable, input hysteresis or output value,
261  * untouched. For #PIN_Config lists (as supplied to PIN_init() for instance)
262  * there is no mask, so all options will affect the pin.
263  *
264  * Some of the options affect the pin regardless of whether it is mapped to
265  * a hardware peripheral or GPIO and some options only take effect when it is
266  * mapped to GPIO. These latter options have \_GPIO_ in their names.
267  *
268  * The default value for a flag/field is indicated with a star (*) in the
269  * description of the options and will be applied if any explicit value is
270  * not supplied for a flag/field that is masked.
271  *
272  * The available options can be grouped into categories as follows:
273  *
274  * ### Input Mode Options ###
275  * | Option | Option bitmask | HW/GPIO | Description |
276  * |--------------------|-----------------------|---------|--------------------------------|
277  * |#PIN_INPUT_EN (*) |#PIN_BM_INPUT_EN | Both | Enable pin input buffer |
278  * |#PIN_INPUT_DIS |#PIN_BM_INPUT_EN | Both | Disable pin input buffer |
279  * |#PIN_HYSTERESIS |#PIN_BM_HYSTERESIS | Both | Enable hysteresis on input |
280  * |#PIN_NOPULL (*) |#PIN_BM_PULLING | Both | No pullup/pulldown |
281  * |#PIN_PULLUP |#PIN_BM_PULLING | Both | Enable pullup |
282  * |#PIN_PULLDOWN |#PIN_BM_PULLING | Both | Enable pulldown |
283  * | |#PIN_BM_INPUT_MODE | | Mask for all input mode options|
284  *
285  * ### Output Mode Options ###
286  * | Option | Option bitmask | HW/GPIO | Description |
287  * |------------------------|------------------------|---------|----------------------------------|
288  * |#PIN_GPIO_OUTPUT_DIS (*)|#PIN_BM_GPIO_OUTPUT_EN | GPIO | Disable GPIO output buffer |
289  * |#PIN_GPIO_OUTPUT_EN |#PIN_BM_GPIO_OUTPUT_EN | GPIO | Enable GPIO output buffer |
290  * |#PIN_GPIO_LOW (*) |#PIN_BM_GPIO_OUTPUT_VAL | GPIO | Output 0 when GPIO |
291  * |#PIN_GPIO_HIGH |#PIN_BM_GPIO_OUTPUT_VAL | GPIO | Output 1 when GPIO |
292  * |#PIN_PUSHPULL (*) |#PIN_BM_OUTPUT_BUF | Both | Use push-pull output buffer |
293  * |#PIN_OPENDRAIN |#PIN_BM_OUTPUT_BUF | Both | Use open drain output buffer |
294  * |#PIN_OPENSOURCE |#PIN_BM_OUTPUT_BUF | Both | Use open source output buffer |
295  * |#PIN_SLEWCTRL |#PIN_BM_SLEWCTRL | Both | Enable output buffer slew control|
296  * |#PIN_DRVSTR_MIN (*) |#PIN_BM_DRVSTR | Both | Output buffer uses min drive |
297  * |#PIN_DRVSTR_MED |#PIN_BM_DRVSTR | Both | Output buffer uses medium drive |
298  * |#PIN_DRVSTR_MAX |#PIN_BM_DRVSTR | Both | Output buffer uses max drive |
299  * | |#PIN_BM_OUTPUT_MODE | | Mask for all output mode options |
300  *
301  * ### Misc Options ###
302  * | Option | Option bitmask | HW/GPIO | Description |
303  * |-------------------|------------------|---------|----------------------------------|
304  * |#PIN_INV_INOUT |#PIN_BM_INV_INOUT | Both | Invert input/output |
305  * |#PIN_IRQ_DIS (*) |#PIN_BM_IRQ | Both | Disable pin interrupts |
306  * |#PIN_IRQ_NEGEDGE |#PIN_BM_IRQ | Both | Pin interrupts on negative edges |
307  * |#PIN_IRQ_POSEDGE |#PIN_BM_IRQ | Both | Pin interrupts on negative edges |
308  * |#PIN_IRQ_BOTHEDGES |#PIN_BM_IRQ | Both | Pin interrupts on both edges |
309  * | |#PIN_BM_ALL | | Mask for *all* options |
310  *
311  * ## Initialization ##
312  * The PIN driver must be initialized before any other drivers are initialized.
313  * In order for IO pins to get a safe value as soon as possible PIN_init()
314  * should be called as early as possible in the boot sequence. Typically,
315  * PIN_init() is called at the start of main() before TI-RTOS is started with
316  * BIOS_start().
317  *
318  * PIN_init() takes as an argument a #PIN_Config list containing default pin
319  * configurations. Typically the #PIN_Config list defined in the board files
320  * is used:
321  * @code
322  * PIN_init(BoardGpioInitTable);
323  * @endcode
324  * It is possible, however, to use another #PIN_Config list if desired.
325  *
326  * ## Power Management Interaction ##
327  * No specific interaction with power management module, as PIN is independent
328  * of power mode.
329  *
330  * ## Functionality Not Supported ##
331  * There is no known unsupported functionality.
332  *
333  * ## Instrumentation ##
334  * The pin driver does not use any of the instrumentation facilities.
335  *
336  * # Usage Examples #
337  *
338  * ## Initialization and Pin Allocation ##
339  * Example that illustrates when and how to call PIN_init(), PIN_open(), PIN_add(), PIN_close()
340  * @code
341  * // Default pin configuration. Typically resides in Board.c file.
342  * // IOs not mentioned here configured to default: input/output/pull disabled
343  * PIN_Config BoardGpioInitTable[] = {
344  * // DIO11: LED A (initially off)
345  * PIN_ID(11) | PIN_GPIO_OUTPUT_EN | PIN_GPIO_LOW | PIN_PUSHPULL | PIN_DRVSTR_MAX,
346  * // DIO10: LED B (initially off)
347  * PIN_ID(10) | PIN_GPIO_OUTPUT_EN | PIN_GPIO_LOW | PIN_PUSHPULL | PIN_DRVSTR_MAX,
348  * // DIO23: BUTTON A (ensure pull-up as button A is also used by other ICs)
349  * PIN_ID(23) | PIN_INPUT_EN | PIN_PULLUP | PIN_HYSTERESIS,
350  * // DIO3: LCD controller reset line (make sure LCD is in reset)
351  * PIN_ID(3) | PIN_GPIO_OUTPUT_EN | PIN_GPIO_LOW | PIN_PUSHPULL,
352  * // Terminate list
353  * PIN_TERMINATE
354  * };
355  *
356  * Task_Struct taskStart;
357  * uint8_t taskStartStack[512];
358  *
359  * // PIN_init() should be called as early as possible in boot
360  * void main() {
361  * // Default initialization of IO
362  * PIN_init(BoardGpioInitTable);
363  *
364  * // Configure startup task
365  * Task_Params taskParams;
366  * Task_Params_init(&taskParams);
367  * taskParams.stack = taskStartStack;
368  * taskParams.stackSize = sizeof(taskStartStack);
369  * Task_construct(&taskStart, taskStartFxn, &taskParams, NULL);
370  *
371  * // Start kernel (never returns)
372  * BIOS_start();
373  * }
374  *
375  * // Human user interface PIN state/handle
376  * PIN_State hStateHui;
377  * #define HUI_LED_A PIN_ID(11)
378  * #define HUI_LED_B PIN_ID(10)
379  * #define HUI_LED_C PIN_ID(9)
380  * #define HUI_BUTTON_A PIN_ID(23)
381  * #define HUI_BUTTON_B PIN_ID(24)
382  *
383  * static void taskStartFxn(UArg a0, UArg a1) {
384  * // Define pins used by Human user interface and initial configuration
385  * const PIN_Config aPinListHui[] = {
386  * HUI_LED_A | PIN_GPIO_OUTPUT_EN | PIN_GPIO_LOW | PIN_PUSHPULL | PIN_DRVSTR_MAX,
387  * HUI_LED_B | PIN_GPIO_OUTPUT_EN | PIN_GPIO_LOW | PIN_PUSHPULL | PIN_DRVSTR_MAX,
388  * HUI_BUTTON_A | PIN_INPUT_EN | PIN_PULLUP | PIN_HYSTERESIS,
389  * HUI_BUTTON_B | PIN_INPUT_EN | PIN_PULLUP | PIN_HYSTERESIS,
390  * PIN_TERMINATE
391  * };
392  *
393  * // Get handle to this collection of pins
394  * if (!PIN_open(&hStateHui, aPinListHui)) {
395  * // Handle allocation error
396  * }
397  *
398  * // ...
399  *
400  * // We can also add (and remove) pins to a set at run time
401  * PIN_Status status = PIN_add(
402  * &hStateHui,
403  * HUI_LED_C | PIN_GPIO_OUTPUT_EN | PIN_GPIO_LOW | PIN_PUSHPULL | PIN_DRVSTR_MAX,
404  * );
405  * if (status != PIN_SUCCESS) {
406  * // Handling allocation error is especially important with PIN_add()
407  * }
408  *
409  * // ...
410  * huiDoSomething();
411  *
412  * // Before ending task, make sure to deallocate pins. They will return
413  * // to the default configurations provided in PIN_init()
414  * PIN_close(&hStateHui);
415  * }
416  * @endcode
417  *
418  * ## Application use of GPIO ##
419  * An example of using GPIO that builds on the previous example. Illustrates how
420  * to read input values, set output values and control output enable
421  * @code
422  * void huiDoSomething() {
423  * // Running lights on LEDs A-B-C (left to right). Button A causes left
424  * // movement, button B causes right movement, both simultaneously aborts
425  * // and disables LED output drivers
426  *
427  * // LED initial state (A off, B off, C on). Only our outputs are affected
428  * PIN_setPortOutputValue(&hStateHui, (1<<HUI_LED_C));
429  *
430  * int32_t moveDir = -1; // <0: left, 0: stop, >0 right
431  * while (moveDir) {
432  * // Update LEDs
433  * if (moveDir<0) {
434  * // Left movement
435  * uint32_t t = PIN_getOutputValue(HUI_LED_A);
436  * PIN_setOutputValue(&hStateHui, HUI_LED_A, PIN_getOutputValue(HUI_LED_B));
437  * PIN_setOutputValue(&hStateHui, HUI_LED_B, PIN_getOutputValue(HUI_LED_C));
438  * PIN_setOutputValue(&hStateHui, HUI_LED_C, t);
439  * } else {
440  * // Right movement
441  * uint32_t t = PIN_getOutputValue(HUI_LED_C);
442  * PIN_setOutputValue(&hStateHui, HUI_LED_C, PIN_getOutputValue(HUI_LED_B));
443  * PIN_setOutputValue(&hStateHui, HUI_LED_B, PIN_getOutputValue(HUI_LED_A));
444  * PIN_setOutputValue(&hStateHui, HUI_LED_A, t);
445  * }
446  *
447  * // Sleep for 333 ms
448  * Task_sleep(333000/10);
449  *
450  * // Read input from both buttons simultaneously
451  * uint32_t buttons = PIN_getPortInputValue(&hStateHui);
452  * if (buttons&(1<<HUI_BUTTON_A) == 0) {
453  * moveDir = -1;
454  * } else if (buttons&(1<<HUI_BUTTON_A) == 0) {
455  * moveDir = 1;
456  * } else if (buttons&((1<<HUI_BUTTON_A)|(1<<HUI_BUTTON_A))) {
457  * moveDir = 0;
458  * }
459  * }
460  * // Disable output enable for all pins (only our pins affected)
461  * PIN_setPortOutputEnable(&hStateHui, 0);
462  * }
463  * @endcode
464  *
465  * ## Pin Interrupt ##
466  * An example that handles pin inputs in the GPIO example above using PIN interrupts
467  * instead:
468  * @code
469  * // volatile variable used to communicate between callback and task
470  * static volatile int32_t moveDir = -1; // <0: left, 0: stop, >0 right
471  *
472  * // Pin interrupt callback
473  * void huiPinIntCb(PIN_Handle handle, PIN_Id pinId) {
474  * // Ignore pinId and read input from both buttons simultaneously
475  * uint32_t buttons = PIN_getPortInputValue(&hStateHui);
476  * if (buttons&(1<<HUI_BUTTON_A) == 0) {
477  * moveDir = -1;
478  * } else if (buttons&(1<<HUI_BUTTON_A) == 0) {
479  * moveDir = 1;
480  * } else if (buttons&((1<<HUI_BUTTON_A)|(1<<HUI_BUTTON_A))) {
481  * moveDir = 0;
482  * }
483  * }
484  *
485  * void huiDoSomething() {
486  * // Running lights on LEDs A-B-C (left to right). Button A causes left
487  * // movement, button B causes right movement, both simultaneously aborts
488  * // and disables LED output drivers
489  *
490  * // LED initial state (A off, B off, C on). Only our outputs are affected
491  * PIN_setPortOutputValue(&hStateHui, (1<<HUI_LED_C));
492  * moveDir = -1; // <0: left, 0: stop, >0 right
493  *
494  * // Setup pin interrupts and register callback
495  * PIN_registerIntCb(&hStateHui, huiPinIntCb);
496  * PIN_setInterrupt(&hStateHui, HUI_BUTTON_A | PIN_IRQ_NEGEDGE);
497  * PIN_setInterrupt(&hStateHui, HUI_BUTTON_B | PIN_IRQ_NEGEDGE);
498  *
499  * while (moveDir) {
500  * // Update LEDs
501  * if (moveDir<0) {
502  * // Left movement
503  * uint32_t t = PIN_getOutputValue(HUI_LED_A);
504  * PIN_setOutputValue(&hStateHui, HUI_LED_A, PIN_getOutputValue(HUI_LED_B));
505  * PIN_setOutputValue(&hStateHui, HUI_LED_B, PIN_getOutputValue(HUI_LED_C));
506  * PIN_setOutputValue(&hStateHui, HUI_LED_C, t);
507  * } else {
508  * // Right movement
509  * uint32_t t = PIN_getOutputValue(HUI_LED_C);
510  * PIN_setOutputValue(&hStateHui, HUI_LED_C, PIN_getOutputValue(HUI_LED_B));
511  * PIN_setOutputValue(&hStateHui, HUI_LED_B, PIN_getOutputValue(HUI_LED_A));
512  * PIN_setOutputValue(&hStateHui, HUI_LED_A, t);
513  * }
514  *
515  * // Sleep for 333 ms (we will likely go into standby)
516  * Task_sleep(333000/10);
517  * }
518  * // Disable output enable for all pins (only our pins affected)
519  * PIN_setPortOutputEnable(&hStateHui, 0);
520  * // Disable pin interrupts
521  * PIN_setInterrupt(&hStateHui, HUI_BUTTON_A | PIN_IRQ_DIS);
522  * PIN_setInterrupt(&hStateHui, HUI_BUTTON_B | PIN_IRQ_DIS);
523  * }
524  * @endcode
525  *
526  *******************************************************************************
527  */
528 
529 #ifndef ti_drivers_PIN__include
530 #define ti_drivers_PIN__include
531 #ifdef __cplusplus
532 extern "C" {
533 #endif
534 
535 #include <xdc/std.h>
536 #include <stdint.h>
537 #include <stdbool.h>
538 #include <stddef.h>
539 #include <inc/hw_types.h>
540 
541 typedef unsigned int uint_t;
542 typedef int int_t;
543 
544 
556 typedef uint8_t PIN_Id;
557 
559 #define PIN_UNASSIGNED 0xFF
560 #define PIN_TERMINATE 0xFE
562 
576 typedef uint32_t PIN_Config;
577 
588 #define PIN_ID(x) ((x)&0xFF)
589 
590 
607 #define PIN_GEN (((uint32_t)1)<<31)
608 
609 #define PIN_INPUT_EN (PIN_GEN|(0<<29))
610 #define PIN_INPUT_DIS (PIN_GEN|(1<<29))
611 #define PIN_HYSTERESIS (PIN_GEN|(1<<30))
612 #define PIN_NOPULL (PIN_GEN|(0<<13))
613 #define PIN_PULLUP (PIN_GEN|(1<<13))
614 #define PIN_PULLDOWN (PIN_GEN|(2<<13))
615 #define PIN_BM_INPUT_EN (1<<29)
616 #define PIN_BM_HYSTERESIS (1<<30)
617 #define PIN_BM_PULLING (0x3<<13)
618 
619 #define PIN_BM_INPUT_MODE (PIN_BM_INPUT_EN|PIN_BM_HYSTERESIS|PIN_BM_PULLING)
621 
622 #define PIN_GPIO_OUTPUT_DIS (PIN_GEN|(0<<23))
623 #define PIN_GPIO_OUTPUT_EN (PIN_GEN|(1<<23))
624 #define PIN_GPIO_LOW (PIN_GEN|(0<<22))
625 #define PIN_GPIO_HIGH (PIN_GEN|(1<<22))
626 #define PIN_PUSHPULL (PIN_GEN|(0<<25))
627 #define PIN_OPENDRAIN (PIN_GEN|(2<<25))
628 #define PIN_OPENSOURCE (PIN_GEN|(3<<25))
629 #define PIN_SLEWCTRL (PIN_GEN|(1<<12))
630 #define PIN_DRVSTR_MIN (PIN_GEN|(0x0<<8))
631 #define PIN_DRVSTR_MED (PIN_GEN|(0x4<<8))
632 #define PIN_DRVSTR_MAX (PIN_GEN|(0x8<<8))
633 #define PIN_BM_GPIO_OUTPUT_EN (1<<23)
634 #define PIN_BM_GPIO_OUTPUT_VAL (1<<22)
635 #define PIN_BM_OUTPUT_BUF (0x3<<25)
636 #define PIN_BM_SLEWCTRL (0x1<<12)
637 #define PIN_BM_DRVSTR (0xF<<8)
638 
639 #define PIN_BM_OUTPUT_MODE (PIN_BM_GPIO_OUTPUT_VAL|PIN_BM_GPIO_OUTPUT_EN| \
641  PIN_BM_OUTPUT_BUF|PIN_BM_SLEWCTRL|PIN_BM_DRVSTR)
642 
643 #define PIN_INV_INOUT (PIN_GEN|(1<<24))
644 #define PIN_BM_INV_INOUT (1<<24)
645 
646 #define PIN_IRQ_DIS (PIN_GEN|(0x0<<16))
647 #define PIN_IRQ_NEGEDGE (PIN_GEN|(0x5<<16))
648 #define PIN_IRQ_POSEDGE (PIN_GEN|(0x6<<16))
649 #define PIN_IRQ_BOTHEDGES (PIN_GEN|(0x7<<16))
650 #define PIN_BM_IRQ (0x7<<16)
651 
652 #define PIN_BM_ALL (PIN_BM_INPUT_MODE|PIN_BM_OUTPUT_MODE|PIN_BM_INV_INOUT|PIN_BM_IRQ)
654 
664 typedef struct PIN_State_s PIN_State;
665 
666 
670 typedef PIN_State* PIN_Handle;
671 
672 
682 typedef void (*PIN_IntCb)(PIN_Handle handle, PIN_Id pinId);
683 
684 
687 struct PIN_State_s {
689  uint_t bmPort;
690  UArg userArg;
691  // TODO: add driver-specific field for extensions?
692 };
693 
695 typedef enum {
699  PIN_UNSUPPORTED = 3
700 } PIN_Status;
701 
702 
717 extern PIN_Status PIN_init(const PIN_Config aPinCfg[]);
718 
719 
735 extern PIN_Handle PIN_open(PIN_State* pState, const PIN_Config aPinList[]);
736 
737 
746 extern PIN_Status PIN_add(PIN_Handle handle, PIN_Config pinCfg);
747 
748 
757 extern PIN_Status PIN_remove(PIN_Handle handle, PIN_Id pinId);
758 
759 
767 extern void PIN_close(PIN_Handle handle);
768 
769 
777 __STATIC_INLINE void PIN_setUserArg(PIN_Handle handle, UArg arg) {
778  if (handle) {
779  handle->userArg = arg;
780  }
781 }
782 
783 
791 __STATIC_INLINE UArg PIN_getUserArg(PIN_Handle handle) {
792  return handle->userArg;
793 }
794 
795 
814 extern uint_t PIN_getInputValue(PIN_Id pinId);
815 
816 
833 extern PIN_Status PIN_setOutputEnable(PIN_Handle handle, PIN_Id pinId, bool bOutEn);
834 
835 
849 extern PIN_Status PIN_setOutputValue(PIN_Handle handle, PIN_Id pinId, uint_t val);
850 
851 
864 extern uint_t PIN_getOutputValue(PIN_Id pinId);
865 
866 
884 extern PIN_Status PIN_setInterrupt(PIN_Handle handle, PIN_Config pinCfg);
885 
886 
897 extern PIN_Status PIN_clrPendInterrupt(PIN_Handle handle, PIN_Id pinId);
898 
899 
920 extern PIN_Status PIN_registerIntCb(PIN_Handle handle, PIN_IntCb pCb);
921 
922 
923 
942 extern PIN_Config PIN_getConfig(PIN_Id pinId);
943 
944 
958 extern PIN_Status PIN_setConfig(PIN_Handle handle, PIN_Config bmMask, PIN_Config pinCfg);
959 
960 
983 extern uint_t PIN_getPortMask(PIN_Handle handle);
984 
985 
995 extern uint_t PIN_getPortInputValue(PIN_Handle handle);
996 
997 
1008 extern uint_t PIN_getPortOutputValue(PIN_Handle handle);
1009 
1010 
1027 extern PIN_Status PIN_setPortOutputValue(PIN_Handle handle, uint_t bmOutVal);
1028 
1029 
1047 extern PIN_Status PIN_setPortOutputEnable(PIN_Handle handle, uint_t bmOutEn);
1048 
1049 
1053 #ifdef __cplusplus
1054 }
1055 #endif
1056 #endif /* ti_drivers_PIN__include */
PIN_Status PIN_setPortOutputValue(PIN_Handle handle, uint_t bmOutVal)
Simultaneous write output buffer values of all allocated pins in GPIO port.
uint_t bmPort
Bitmask for pins allocated in port.
Definition: PIN.h:688
uint8_t PIN_Id
Pin identifier data type.
Definition: PIN.h:556
uint_t PIN_getPortOutputValue(PIN_Handle handle)
Returns value of whole GPIO port's output buffers.
PIN_Status PIN_setInterrupt(PIN_Handle handle, PIN_Config pinCfg)
Control interrupt enable and edge for pin.
Operation not supported.
Definition: PIN.h:698
uint_t PIN_getPortMask(PIN_Handle handle)
Returns bitmask indicating pins allocated to client in GPIO port.
unsigned int uint_t
Definition: PIN.h:541
__STATIC_INLINE UArg PIN_getUserArg(PIN_Handle handle)
Gets a user argument associated with the handle.
Definition: PIN.h:790
PIN_Status PIN_setConfig(PIN_Handle handle, PIN_Config bmMask, PIN_Config pinCfg)
Sets complete pin configuration.
PIN_IntCb pCbFunc
Pointer to interrupt callback function.
Definition: PIN.h:687
__STATIC_INLINE void PIN_setUserArg(PIN_Handle handle, UArg arg)
Sets a user argument associated with the handle.
Definition: PIN.h:776
PIN_Handle PIN_open(PIN_State *pState, const PIN_Config aPinList[])
Allocate one or more pins for a driver or an application.
PIN_Status PIN_add(PIN_Handle handle, PIN_Config pinCfg)
Add pin to pin set for open PIN handle.
PIN_Status PIN_init(const PIN_Config aPinCfg[])
PIN module initialization.
UArg userArg
User argument for whole handle.
Definition: PIN.h:689
void(* PIN_IntCb)(PIN_Handle handle, PIN_Id pinId)
I/O Interrupt callback function pointer type One PIN Interrupt callback can be registered by each PIN...
Definition: PIN.h:681
int int_t
Definition: PIN.h:542
PIN_Config PIN_getConfig(PIN_Id pinId)
Returns pin configuration.
uint_t PIN_getInputValue(PIN_Id pinId)
Get pin input value (0/1)
uint_t PIN_getPortInputValue(PIN_Handle handle)
Read input value of whole GPIO port.
PIN_Status PIN_registerIntCb(PIN_Handle handle, PIN_IntCb pCb)
Register callback function for a set of pins.
PIN_State * PIN_Handle
A handle that is returned from a PIN_open() call Used for further PIN client interaction with the PIN...
Definition: PIN.h:669
PIN_Status PIN_remove(PIN_Handle handle, PIN_Id pinId)
Removes pin from pin set foropen PIN handle.
PIN_Status PIN_setPortOutputEnable(PIN_Handle handle, uint_t bmOutEn)
Set output enable for all pins allocated to client in GPIO port.
PIN_Status PIN_setOutputValue(PIN_Handle handle, PIN_Id pinId, uint_t val)
Control output value for GPIO pin.
underlying data structure for type PIN_State
Definition: PIN.h:686
PIN_Status
Return value for many functions in the PIN driver interface.
Definition: PIN.h:694
Operation succeeded.
Definition: PIN.h:695
void PIN_close(PIN_Handle handle)
Deallocate all pins previously allocated with a call to PIN_open().
uint_t PIN_getOutputValue(PIN_Id pinId)
Get value of GPIO pin output buffer.
PIN_Status PIN_setOutputEnable(PIN_Handle handle, PIN_Id pinId, bool bOutEn)
Control output enable for GPIO pin.
PIN_Status PIN_clrPendInterrupt(PIN_Handle handle, PIN_Id pinId)
Clear pending interrupt for pin, if any.
Operation failed, client does not have access to pin.
Definition: PIN.h:697
Operation failed, some pin already allocated.
Definition: PIN.h:696
uint32_t PIN_Config
Pin configuration data type with embedded pin identifier.
Definition: PIN.h:576
Copyright 2015, Texas Instruments Incorporated