source: rtems/bsps/include/bsp/gpio.h @ 2afb22b

5
Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on 12/23/17 at 07:18:56

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 31.2 KB
Line 
1/**
2 * @file gpio.h
3 *
4 * @ingroup rtems_gpio
5 *
6 * @brief RTEMS GPIO API definition.
7 */
8
9/*
10 *  Copyright (c) 2014-2015 Andre Marques <andre.lousa.marques at gmail.com>
11 *
12 *  The license and distribution terms for this file may be
13 *  found in the file LICENSE in this distribution or at
14 *  http://www.rtems.org/license/LICENSE.
15 */
16
17#ifndef LIBBSP_SHARED_GPIO_H
18#define LIBBSP_SHARED_GPIO_H
19
20#include <bsp.h>
21#include <rtems.h>
22
23#ifdef __cplusplus
24extern "C" {
25#endif /* __cplusplus */
26
27#if !defined(BSP_GPIO_PIN_COUNT) || !defined(BSP_GPIO_PINS_PER_BANK)
28  #error "BSP_GPIO_PIN_COUNT or BSP_GPIO_PINS_PER_BANK is not defined."
29#endif
30
31#if BSP_GPIO_PIN_COUNT <= 0 || BSP_GPIO_PINS_PER_BANK <= 0
32  #error "Invalid BSP_GPIO_PIN_COUNT or BSP_GPIO_PINS_PER_BANK."
33#endif
34
35#if BSP_GPIO_PINS_PER_BANK > 32
36  #error "Invalid BSP_GPIO_PINS_PER_BANK. Must be in the range of 1 to 32."
37#endif
38
39#define GPIO_LAST_BANK_PINS BSP_GPIO_PIN_COUNT % BSP_GPIO_PINS_PER_BANK
40
41#if GPIO_LAST_BANK_PINS > 0
42  #define GPIO_BANK_COUNT (BSP_GPIO_PIN_COUNT / BSP_GPIO_PINS_PER_BANK) + 1
43#else
44  #define GPIO_BANK_COUNT BSP_GPIO_PIN_COUNT / BSP_GPIO_PINS_PER_BANK
45  #undef GPIO_LAST_BANK_PINS
46  #define GPIO_LAST_BANK_PINS BSP_GPIO_PINS_PER_BANK
47#endif
48
49#if defined(BSP_GPIO_PINS_PER_SELECT_BANK) && BSP_GPIO_PINS_PER_SELECT_BANK > 32
50  #error "Invalid BSP_GPIO_PINS_PER_SELECT_BANK. Must under and including 32."
51#elif defined(BSP_GPIO_PINS_PER_SELECT_BANK) <= 32
52  #define GPIO_SELECT_BANK_COUNT \
53    BSP_GPIO_PINS_PER_BANK / BSP_GPIO_PINS_PER_SELECT_BANK
54#endif
55
56#define INTERRUPT_SERVER_PRIORITY 1
57#define INTERRUPT_SERVER_STACK_SIZE 2 * RTEMS_MINIMUM_STACK_SIZE
58#define INTERRUPT_SERVER_MODES RTEMS_TIMESLICE | RTEMS_PREEMPT
59#define INTERRUPT_SERVER_ATTRIBUTES RTEMS_DEFAULT_ATTRIBUTES
60
61#define GPIO_INPUT_ERROR ~0
62
63/**
64 * @name GPIO data structures
65 *
66 * @{
67 */
68
69/**
70 * @brief The set of possible configurations for a GPIO pull-up resistor.
71 *
72 * Enumerated type to define the possible pull-up resistor configurations
73 * for a GPIO pin.
74 */
75typedef enum
76{
77  PULL_UP = 1,
78  PULL_DOWN,
79  NO_PULL_RESISTOR
80} rtems_gpio_pull_mode;
81
82/**
83 * @brief The set of possible functions a pin can have.
84 *
85 * Enumerated type to define a pin function.
86 */
87typedef enum
88{
89  DIGITAL_INPUT = 0,
90  DIGITAL_OUTPUT,
91  BSP_SPECIFIC,
92  NOT_USED
93} rtems_gpio_function;
94
95/**
96 * @brief The set of possible interrupts a GPIO pin can generate.
97 *
98 * Enumerated type to define a GPIO pin interrupt.
99 */
100typedef enum
101{
102  FALLING_EDGE = 0,
103  RISING_EDGE,
104  LOW_LEVEL,
105  HIGH_LEVEL,
106  BOTH_EDGES,
107  BOTH_LEVELS,
108  NONE
109} rtems_gpio_interrupt;
110
111/**
112 * @brief The set of possible handled states an user-defined interrupt
113 *        handler can return.
114 *
115 * Enumerated type to define an interrupt handler handled state.
116 */
117typedef enum
118{
119  IRQ_HANDLED,
120  IRQ_NONE
121} rtems_gpio_irq_state;
122
123/**
124 * @brief The set of flags to specify an user-defined interrupt handler
125 *        uniqueness on a GPIO pin.
126 *
127 * Enumerated type to define an interrupt handler shared flag.
128 */
129typedef enum
130{
131  SHARED_HANDLER,
132  UNIQUE_HANDLER
133} rtems_gpio_handler_flag;
134
135/**
136 * @brief Object containing relevant information for assigning a BSP specific
137 *        function to a pin.
138 *
139 * Encapsulates relevant data for a BSP specific GPIO function.
140 */
141typedef struct
142{
143  /* The BSP defined function code. */
144  uint32_t io_function;
145
146  void *pin_data;
147} rtems_gpio_specific_data;
148
149/**
150 * @brief Object containing configuration information
151 *        regarding interrupts.
152 */
153typedef struct
154{
155  rtems_gpio_interrupt active_interrupt;
156
157  rtems_gpio_handler_flag handler_flag;
158
159  bool threaded_interrupts;
160
161  /* Interrupt handler function. */
162  rtems_gpio_irq_state (*handler) (void *arg);
163
164  /* Interrupt handler function arguments. */
165  void *arg;
166
167  /* Software switch debounce settings. It should contain the amount of clock
168   * ticks that must pass between interrupts to ensure that the interrupt
169   * was not caused by a switch bounce.
170   * If set to 0 this feature is disabled . */
171  uint32_t debounce_clock_tick_interval;
172} rtems_gpio_interrupt_configuration;
173
174/**
175 * @brief Object containing configuration information
176 *        to request/update a GPIO pin.
177 */
178typedef struct
179{
180  /* Processor pin number. */
181  uint32_t pin_number;
182  rtems_gpio_function function;
183
184  /* Pull resistor setting. */
185  rtems_gpio_pull_mode pull_mode;
186
187  /* If digital out pin, set to TRUE to set the pin to logical high,
188   * or FALSE for logical low. If not a digital out then this
189   * is ignored. */
190  bool output_enabled;
191
192  /* If true inverts digital in/out applicational logic. */
193  bool logic_invert;
194
195  /* Pin interrupt configuration. Should be NULL if not used. */
196  rtems_gpio_interrupt_configuration *interrupt;
197
198  /* Structure with BSP specific data, to use during the pin request.
199   * If function == BSP_SPECIFIC this should have a pointer to
200   * a rtems_gpio_specific_data structure.
201   *
202   * If not this field may be NULL. This is passed to the BSP function
203   * so any BSP specific data can be passed to it through this pointer. */
204  void *bsp_specific;
205} rtems_gpio_pin_conf;
206
207/**
208 * @brief Object containing configuration information
209 *        to assign GPIO functions to multiple pins
210 *        at the same time. To be used by BSP code only.
211 */
212typedef struct
213{
214  /* Global GPIO pin number. */
215  uint32_t pin_number;
216
217  /* RTEMS GPIO pin function code. */
218  rtems_gpio_function function;
219
220  /* BSP specific function code. Only used if function == BSP_SPECIFIC */
221  uint32_t io_function;
222
223  /* BSP specific data. */
224  void *bsp_specific;
225} rtems_gpio_multiple_pin_select;
226
227/**
228 * @brief Object containing configuration information
229 *        to request a GPIO pin group.
230 */
231typedef struct
232{
233  const rtems_gpio_pin_conf *digital_inputs;
234  uint32_t input_count;
235
236  const rtems_gpio_pin_conf *digital_outputs;
237  uint32_t output_count;
238
239  const rtems_gpio_pin_conf *bsp_specifics;
240  uint32_t bsp_specific_pin_count;
241} rtems_gpio_group_definition;
242
243/**
244 * @brief Opaque type for a GPIO pin group.
245 */
246typedef struct rtems_gpio_group rtems_gpio_group;
247
248/** @} */
249
250/**
251 * @name gpio Usage
252 *
253 * @{
254 */
255
256/**
257 * @brief Initializes the GPIO API.
258 *
259 * @retval RTEMS_SUCCESSFUL API successfully initialized.
260 * @retval * @see rtems_semaphore_create().
261 */
262extern rtems_status_code rtems_gpio_initialize(void);
263
264/**
265 * @brief Instantiates a GPIO pin group.
266 *        To define the group @see rtems_gpio_define_pin_group().
267 *
268 * @retval rtems_gpio_group pointer.
269 */
270extern rtems_gpio_group *rtems_gpio_create_pin_group(void);
271
272/**
273 * @brief Requests a GPIO pin group configuration.
274 *
275 * @param[in] group_definition rtems_gpio_group_definition structure filled with
276 *                             the group pins configurations.
277 * @param[out] group Reference to the created group.
278 *
279 * @retval RTEMS_SUCCESSFUL Pin group was configured successfully.
280 * @retval RTEMS_UNSATISFIED @var group_definition or @var group is NULL,
281 *                           the @var pins are not from the same bank,
282 *                           no pins were defined or could not satisfy at
283 *                           least one given configuration.
284 * @retval RTEMS_RESOURCE_IN_USE At least one pin is already being used.
285 * @retval * @see rtems_semaphore_create().
286 */
287extern rtems_status_code rtems_gpio_define_pin_group(
288  const rtems_gpio_group_definition *group_definition,
289  rtems_gpio_group *group
290);
291
292/**
293 * @brief Writes a value to the group's digital outputs. The pins order
294 *        is as defined in the group definition.
295 *
296 * @param[in] data Data to write/send.
297 * @param[in] group Reference to the group.
298 *
299 * @retval RTEMS_SUCCESSFUL Data successfully written.
300 * @retval RTEMS_NOT_DEFINED Group has no output pins.
301 * @retval RTEMS_UNSATISFIED Could not operate on at least one of the pins.
302 */
303extern rtems_status_code rtems_gpio_write_group(
304  uint32_t data,
305  rtems_gpio_group *group
306);
307
308/**
309 * @brief Reads the value/level of the group's digital inputs. The pins order
310 *        is as defined in the group definition.
311 *
312 * @param[in] group Reference to the group.
313 *
314 * @retval The function returns a 32-bit bitmask with the group's input pins
315 *         current logical values.
316 * @retval GPIO_INPUT_ERROR Group has no input pins.
317 */
318extern uint32_t rtems_gpio_read_group(rtems_gpio_group *group);
319
320/**
321 * @brief Performs a BSP specific operation on a group of pins. The pins order
322 *        is as defined in the group definition.
323 *
324 * @param[in] group Reference to the group.
325 * @param[in] arg Pointer to a BSP defined structure with BSP-specific
326 *                data. This field is handled by the BSP.
327 *
328 * @retval RTEMS_SUCCESSFUL Operation completed with success.
329 * @retval RTEMS_NOT_DEFINED Group has no BSP specific pins, or the BSP does not
330 *                           support BSP specific operations for groups.
331 * @retval RTEMS_UNSATISFIED Could not operate on at least one of the pins.
332 */
333extern rtems_status_code rtems_gpio_group_bsp_specific_operation(
334  rtems_gpio_group *group,
335  void *arg
336);
337
338/**
339 * @brief Requests a GPIO pin configuration.
340 *
341 * @param[in] conf rtems_gpio_pin_conf structure filled with the pin information
342 *                 and desired configurations.
343 *
344 * @retval RTEMS_SUCCESSFUL Pin was configured successfully.
345 * @retval RTEMS_UNSATISFIED Could not satisfy the given configuration.
346 */
347extern rtems_status_code rtems_gpio_request_configuration(
348  const rtems_gpio_pin_conf *conf
349);
350
351/**
352 * @brief Updates the current configuration of a GPIO pin .
353 *
354 * @param[in] conf rtems_gpio_pin_conf structure filled with the pin information
355 *                 and desired configurations.
356 *
357 * @retval RTEMS_SUCCESSFUL Pin configuration was updated successfully.
358 * @retval RTEMS_INVALID_ID Pin number is invalid.
359 * @retval RTEMS_NOT_CONFIGURED The pin is not being used.
360 * @retval RTEMS_UNSATISFIED Could not update the pin's configuration.
361 */
362extern rtems_status_code rtems_gpio_update_configuration(
363  const rtems_gpio_pin_conf *conf
364);
365
366/**
367 * @brief Sets multiple output GPIO pins with the logical high.
368 *
369 * @param[in] pin_numbers Array with the GPIO pin numbers to set.
370 * @param[in] count Number of GPIO pins to set.
371 *
372 * @retval RTEMS_SUCCESSFUL All pins were set successfully.
373 * @retval RTEMS_INVALID_ID At least one pin number is invalid.
374 * @retval RTEMS_NOT_CONFIGURED At least one of the received pins
375 *                              is not configured as a digital output.
376 * @retval RTEMS_UNSATISFIED Could not set the GPIO pins.
377 */
378extern rtems_status_code rtems_gpio_multi_set(
379  uint32_t *pin_numbers,
380  uint32_t pin_count
381);
382
383/**
384 * @brief Sets multiple output GPIO pins with the logical low.
385 *
386 * @param[in] pin_numbers Array with the GPIO pin numbers to clear.
387 * @param[in] count Number of GPIO pins to clear.
388 *
389 * @retval RTEMS_SUCCESSFUL All pins were cleared successfully.
390 * @retval RTEMS_INVALID_ID At least one pin number is invalid.
391 * @retval RTEMS_NOT_CONFIGURED At least one of the received pins
392 *                              is not configured as a digital output.
393 * @retval RTEMS_UNSATISFIED Could not clear the GPIO pins.
394 */
395extern rtems_status_code rtems_gpio_multi_clear(
396  uint32_t *pin_numbers,
397  uint32_t pin_count
398);
399
400/**
401 * @brief Returns the value (level) of multiple GPIO input pins.
402 *
403 * @param[in] pin_numbers Array with the GPIO pin numbers to read.
404 * @param[in] count Number of GPIO pins to read.
405 *
406 * @retval Bitmask with the values of the corresponding pins.
407 *         0 for logical low and 1 for logical high.
408 * @retval GPIO_INPUT_ERROR Could not read at least one pin level.
409 */
410extern uint32_t rtems_gpio_multi_read(
411  uint32_t *pin_numbers,
412  uint32_t pin_count
413);
414
415/**
416 * @brief Sets an output GPIO pin with the logical high.
417 *
418 * @param[in] pin_number GPIO pin number.
419 *
420 * @retval RTEMS_SUCCESSFUL Pin was set successfully.
421 * @retval RTEMS_INVALID_ID Pin number is invalid.
422 * @retval RTEMS_NOT_CONFIGURED The received pin is not configured
423 *                              as a digital output.
424 * @retval RTEMS_UNSATISFIED Could not set the GPIO pin.
425 */
426extern rtems_status_code rtems_gpio_set(uint32_t pin_number);
427
428/**
429 * @brief Sets an output GPIO pin with the logical low.
430 *
431 * @param[in] pin_number GPIO pin number.
432 *
433 * @retval RTEMS_SUCCESSFUL Pin was cleared successfully.
434 * @retval RTEMS_INVALID_ID Pin number is invalid.
435 * @retval RTEMS_NOT_CONFIGURED The received pin is not configured
436 *                              as a digital output.
437 * @retval RTEMS_UNSATISFIED Could not clear the GPIO pin.
438 */
439extern rtems_status_code rtems_gpio_clear(uint32_t pin_number);
440
441/**
442 * @brief Returns the value (level) of a GPIO input pin.
443 *
444 * @param[in] pin_number GPIO pin number.
445 *
446 * @retval The function returns 0 or 1 depending on the pin current
447 *         logical value.
448 * @retval -1 Pin number is invalid, or not a digital input pin.
449 */
450extern int rtems_gpio_get_value(uint32_t pin_number);
451
452/**
453 * @brief Requests multiple GPIO pin configurations. If the BSP provides
454 *        support for parallel selection each call to this function will
455 *        result in a single call to the GPIO hardware, else each pin
456 *        configuration will be done in individual and sequential calls.
457 *        All pins must belong to the same GPIO bank.
458 *
459 * @param[in] pins Array of rtems_gpio_pin_conf structures filled with the pins
460 *                 information and desired configurations. All pins must belong
461 *                 to the same GPIO bank.
462 * @param[in] pin_count Number of pin configurations in the @var pins array.
463 *
464 * @retval RTEMS_SUCCESSFUL All pins were configured successfully.
465 * @retval RTEMS_INVALID_ID At least one pin number in the @var pins array
466 *                          is invalid.
467 * @retval RTEMS_RESOURCE_IN_USE At least one pin is already being used.
468 * @retval RTEMS_UNSATISFIED Could not satisfy at least one given configuration.
469 */
470extern rtems_status_code rtems_gpio_multi_select(
471  const rtems_gpio_pin_conf *pins,
472  uint8_t pin_count
473);
474
475/**
476 * @brief Assigns a certain function to a GPIO pin.
477 *
478 * @param[in] pin_number GPIO pin number.
479 * @param[in] function The new function for the pin.
480 * @param[in] output_enabled If TRUE and @var function is DIGITAL_OUTPUT,
481 *                           then the pin is set with the logical high.
482 *                           Otherwise it is set with logical low.
483 * @param[in] logic_invert Reverses the digital I/O logic for DIGITAL_INPUT
484 *                         and DIGITAL_OUTPUT pins.
485 * @param[in] bsp_specific Pointer to a BSP defined structure with BSP-specific
486 *                         data. This field is handled by the BSP.
487 *
488 * @retval RTEMS_SUCCESSFUL Pin was configured successfully.
489 * @retval RTEMS_INVALID_ID Pin number is invalid.
490 * @retval RTEMS_RESOURCE_IN_USE The received pin is already being used.
491 * @retval RTEMS_UNSATISFIED Could not assign the GPIO function.
492 * @retval RTEMS_NOT_DEFINED GPIO function not defined, or NOT_USED.
493 */
494extern rtems_status_code rtems_gpio_request_pin(
495  uint32_t pin_number,
496  rtems_gpio_function function,
497  bool output_enable,
498  bool logic_invert,
499  void *bsp_specific
500);
501
502/**
503 * @brief Configures a single GPIO pin pull resistor.
504 *
505 * @param[in] pin_number GPIO pin number.
506 * @param[in] mode The pull resistor mode.
507 *
508 * @retval RTEMS_SUCCESSFUL Pull resistor successfully configured.
509 * @retval RTEMS_INVALID_ID Pin number is invalid.
510 * @retval RTEMS_UNSATISFIED Could not set the pull mode.
511 */
512extern rtems_status_code rtems_gpio_resistor_mode(
513  uint32_t pin_number,
514  rtems_gpio_pull_mode mode
515);
516
517/**
518 * @brief Releases a GPIO pin, making it available to be used again.
519 *
520 * @param[in] pin_number GPIO pin number.
521 *
522 * @retval RTEMS_SUCCESSFUL Pin successfully disabled.
523 * @retval RTEMS_INVALID_ID Pin number is invalid.
524 * @retval * Could not disable an active interrupt on this pin,
525 *           @see rtems_gpio_disable_interrupt().
526 */
527extern rtems_status_code rtems_gpio_release_pin(uint32_t pin_number);
528
529/**
530 * @brief Releases a GPIO pin, making it available to be used again.
531 *
532 * @param[in] conf GPIO pin configuration to be released.
533 *
534 * @retval RTEMS_SUCCESSFUL Pin successfully disabled.
535 * @retval RTEMS_UNSATISFIED Pin configuration is NULL.
536 * @retval * @see rtems_gpio_release_pin().
537 */
538extern rtems_status_code rtems_gpio_release_configuration(
539  const rtems_gpio_pin_conf *conf
540);
541
542/**
543 * @brief Releases multiple GPIO pins, making them available to be used again.
544 *
545 * @param[in] pins Array of rtems_gpio_pin_conf structures.
546 * @param[in] pin_count Number of pin configurations in the @var pins array.
547 *
548 * @retval RTEMS_SUCCESSFUL Pins successfully disabled.
549 * @retval RTEMS_UNSATISFIED @var pins array is NULL.
550 * @retval * @see rtems_gpio_release_pin().
551 */
552extern rtems_status_code rtems_gpio_release_multiple_pins(
553  const rtems_gpio_pin_conf *pins,
554  uint32_t pin_count
555);
556
557/**
558 * @brief Releases a GPIO pin group, making the pins used available to be
559 *        repurposed.
560 *
561 * @param[in] conf GPIO pin configuration to be released.
562 *
563 * @retval RTEMS_SUCCESSFUL Pins successfully disabled.
564 * @retval * @see rtems_gpio_release_pin(), @see rtems_semaphore_delete() or
565 *           @see rtems_semaphore_flush().
566 */
567extern rtems_status_code rtems_gpio_release_pin_group(
568  rtems_gpio_group *group
569);
570
571/**
572 * @brief Attaches a debouncing function to a given pin/switch.
573 *        Debouncing is done by requiring a certain number of clock ticks to
574 *        pass between interrupts. Any interrupt fired too close to the last
575 *        will be ignored as it is probably the result of an involuntary
576 *        switch/button bounce after being released.
577 *
578 * @param[in] pin_number GPIO pin number.
579 * @param[in] ticks Minimum number of clock ticks that must pass between
580 *                  interrupts so it can be considered a legitimate
581 *                  interrupt.
582 *
583 * @retval RTEMS_SUCCESSFUL Debounce function successfully attached to the pin.
584 * @retval RTEMS_INVALID_ID Pin number is invalid.
585 * @retval RTEMS_NOT_CONFIGURED The current pin is not configured as a digital
586 *                              input, hence it can not be connected to a switch,
587 *                              or interrupts are not enabled for this pin.
588 */
589extern rtems_status_code rtems_gpio_debounce_switch(
590  uint32_t pin_number,
591  int ticks
592);
593
594/**
595 * @brief Connects a new user-defined interrupt handler to a given pin.
596 *
597 * @param[in] pin_number GPIO pin number.
598 * @param[in] handler Pointer to a function that will be called every time
599 *                    the enabled interrupt for the given pin is generated.
600 *                    This function must return information about its
601 *                    handled/unhandled state.
602 * @param[in] arg Void pointer to the arguments of the user-defined handler.
603 *
604 * @retval RTEMS_SUCCESSFUL Handler successfully connected to this pin.
605 * @retval RTEMS_NO_MEMORY Could not connect more user-defined handlers to
606 *                         the given pin.
607 * @retval RTEMS_NOT_CONFIGURED The given pin has no interrupt configured.
608 * @retval RTEMS_INVALID_ID Pin number is invalid.
609 * @retval RTEMS_TOO_MANY The pin's current handler is set as unique.
610 * @retval RTEMS_RESOURCE_IN_USE The current user-defined handler for this pin
611 *                               is unique.
612 */
613extern rtems_status_code rtems_gpio_interrupt_handler_install(
614  uint32_t pin_number,
615  rtems_gpio_irq_state (*handler) (void *arg),
616  void *arg
617);
618
619/**
620 * @brief Enables interrupts to be generated on a given GPIO pin.
621 *        When fired that interrupt will call the given handler.
622 *
623 * @param[in] pin_number GPIO pin number.
624 * @param[in] interrupt Type of interrupt to enable for the pin.
625 * @param[in] flag Defines the uniqueness of the interrupt handler for the pin.
626 * @param[in] threaded_handling Defines if the handler should be called from a
627 *                              thread/task or from normal ISR contex.
628 * @param[in] handler Pointer to a function that will be called every time
629 *                    @var interrupt is generated. This function must return
630 *                    information about its handled/unhandled state.
631 * @param[in] arg Void pointer to the arguments of the user-defined handler.
632 *
633 * @retval RTEMS_SUCCESSFUL Interrupt successfully enabled for this pin.
634 * @retval RTEMS_UNSATISFIED Could not install the GPIO ISR, create/start
635 *                           the handler task, or enable the interrupt
636 *                           on the pin.
637 * @retval RTEMS_INVALID_ID Pin number is invalid.
638 * @retval RTEMS_NOT_CONFIGURED The received pin is not configured
639 *                              as a digital input, the pin is on a
640 *                              pin grouping.
641 * @retval RTEMS_RESOURCE_IN_USE The pin already has an enabled interrupt,
642 *                               or the handler threading policy does not match
643 *                               the bank's policy.
644 * @retval RTEMS_NO_MEMORY Could not store the pin's interrupt configuration.
645 */
646extern rtems_status_code rtems_gpio_enable_interrupt(
647  uint32_t pin_number,
648  rtems_gpio_interrupt interrupt,
649  rtems_gpio_handler_flag flag,
650  bool threaded_handling,
651  rtems_gpio_irq_state (*handler) (void *arg),
652  void *arg
653);
654
655/**
656 * @brief Disconnects an user-defined interrupt handler from the given pin.
657 *        If in the end there are no more user-defined handlers connected
658 *        to the pin, interrupts are disabled on the given pin.
659 *
660 * @param[in] pin_number GPIO pin number.
661 * @param[in] handler Pointer to the user-defined handler
662 * @param[in] arg Void pointer to the arguments of the user-defined handler.
663 *
664 * @retval RTEMS_SUCCESSFUL Handler successfully disconnected from this pin.
665 * @retval RTEMS_INVALID_ID Pin number is invalid.
666 * @retval RTEMS_NOT_CONFIGURED Pin has no active interrupts.
667 * @retval * @see rtems_gpio_disable_interrupt()
668 */
669extern rtems_status_code rtems_gpio_interrupt_handler_remove(
670  uint32_t pin_number,
671  rtems_gpio_irq_state (*handler) (void *arg),
672  void *arg
673);
674
675/**
676 * @brief Stops interrupts from being generated on a given GPIO pin
677 *        and removes the corresponding handler.
678 *
679 * @param[in] pin_number GPIO pin number.
680 *
681 * @retval RTEMS_SUCCESSFUL Interrupt successfully disabled for this pin.
682 * @retval RTEMS_INVALID_ID Pin number is invalid.
683 * @retval RTEMS_NOT_CONFIGURED Pin has no active interrupts.
684 * @retval RTEMS_UNSATISFIED Could not remove the current interrupt handler,
685 *                           could not recognize the current active interrupt
686 *                           on this pin or could not disable interrupts on
687 *                           this pin.
688 */
689extern rtems_status_code rtems_gpio_disable_interrupt(uint32_t pin_number);
690
691/**
692 * @brief Sets multiple output GPIO pins with the logical high.
693 *        This must be implemented by each BSP.
694 *
695 * @param[in] bank GPIO bank number.
696 * @param[in] bitmask Bitmask of GPIO pins to set in the given bank.
697 *
698 * @retval RTEMS_SUCCESSFUL All pins were set successfully.
699 * @retval RTEMS_UNSATISFIED Could not set at least one of the pins.
700 */
701extern rtems_status_code rtems_gpio_bsp_multi_set(
702  uint32_t bank,
703  uint32_t bitmask
704);
705
706/**
707 * @brief Sets multiple output GPIO pins with the logical low.
708 *        This must be implemented by each BSP.
709 *
710 * @param[in] bank GPIO bank number.
711 * @param[in] bitmask Bitmask of GPIO pins to clear in the given bank.
712 *
713 * @retval RTEMS_SUCCESSFUL All pins were cleared successfully.
714 * @retval RTEMS_UNSATISFIED Could not clear at least one of the pins.
715 */
716extern rtems_status_code rtems_gpio_bsp_multi_clear(
717  uint32_t bank,
718  uint32_t bitmask
719);
720
721/**
722 * @brief Returns the value (level) of multiple GPIO input pins.
723 *        This must be implemented by each BSP.
724 *
725 * @param[in] bank GPIO bank number.
726 * @param[in] bitmask Bitmask of GPIO pins to read in the given bank.
727 *
728 * @retval The function must return a bitmask with the values of the
729 *         corresponding pins. 0 for logical low and 1 for logical high.
730 * @retval GPIO_INPUT_ERROR Could not read at least one pin level.
731 */
732extern uint32_t rtems_gpio_bsp_multi_read(uint32_t bank, uint32_t bitmask);
733
734/**
735 * @brief Performs a BSP specific operation on a group of pins.
736 *        The implementation for this function may be omitted if the target
737 *        does not support the feature, by returning RTEMS_NOT_DEFINED.
738 *
739 * @param[in] bank GPIO bank number.
740 * @param[in] pins Array filled with BSP specific pin numbers. All pins belong
741 *                 to the same select bank.
742 * @param[in] pin_count Number of pin configurations in the @var pins array.
743 * @param[in] arg Pointer to a BSP defined structure with BSP-specific
744 *                data. This field is handled by the BSP.
745 *
746 * @retval RTEMS_SUCCESSFUL Operation completed with success.
747 * @retval RTEMS_NOT_DEFINED Group has no BSP specific pins, or the BSP does not
748 *                           support BSP specific operations for groups.
749 * @retval RTEMS_UNSATISFIED Could not operate on at least one of the pins.
750 */
751extern rtems_status_code rtems_gpio_bsp_specific_group_operation(
752  uint32_t bank,
753  uint32_t *pins,
754  uint32_t pin_count,
755  void *arg
756);
757
758/**
759 * @brief Assigns GPIO functions to all the given pins in a single register
760 *        operation.
761 *        The implementation for this function may be omitted if the target
762 *        does not support the feature, by returning RTEMS_NOT_DEFINED.
763 *
764 * @param[in] pins Array of rtems_gpio_multiple_pin_select structures filled
765 *                 with the pins desired functions. All pins belong to the
766 *                 same select bank.
767 * @param[in] pin_count Number of pin configurations in the @var pins array.
768 * @param[in] select_bank Select bank number of the received pins.
769 *
770 * @retval RTEMS_SUCCESSFUL Functions were assigned successfully.
771 * @retval RTEMS_NOT_DEFINED The BSP does not support multiple pin function
772 *                           assignment.
773 * @retval RTEMS_UNSATISFIED Could not assign the functions to the pins.
774 */
775extern rtems_status_code rtems_gpio_bsp_multi_select(
776  rtems_gpio_multiple_pin_select *pins,
777  uint32_t pin_count,
778  uint32_t select_bank
779);
780
781/**
782 * @brief Sets an output GPIO pin with the logical high.
783 *        This must be implemented by each BSP.
784 *
785 * @param[in] bank GPIO bank number.
786 * @param[in] pin GPIO pin number within the given bank.
787 *
788 * @retval RTEMS_SUCCESSFUL Pin was set successfully.
789 * @retval RTEMS_UNSATISFIED Could not set the given pin.
790 */
791extern rtems_status_code rtems_gpio_bsp_set(uint32_t bank, uint32_t pin);
792
793/**
794 * @brief Sets an output GPIO pin with the logical low.
795 *        This must be implemented by each BSP.
796 *
797 * @param[in] bank GPIO bank number.
798 * @param[in] pin GPIO pin number within the given bank.
799 *
800 * @retval RTEMS_SUCCESSFUL Pin was cleared successfully.
801 * @retval RTEMS_UNSATISFIED Could not clear the given pin.
802 */
803extern rtems_status_code rtems_gpio_bsp_clear(uint32_t bank, uint32_t pin);
804
805/**
806 * @brief Returns the value (level) of a GPIO input pin.
807 *        This must be implemented by each BSP.
808 *
809 * @param[in] bank GPIO bank number.
810 * @param[in] pin GPIO pin number within the given bank.
811 *
812 * @retval The function must return 0 if the pin level is a logical low,
813 *         or non zero if it has a logical high.
814 * @retval GPIO_INPUT_ERROR Could not read the pin level.
815 */
816extern uint32_t rtems_gpio_bsp_get_value(uint32_t bank, uint32_t pin);
817
818/**
819 * @brief Assigns the digital input function to the given pin.
820 *        This must be implemented by each BSP.
821 *
822 * @param[in] bank GPIO bank number.
823 * @param[in] pin GPIO pin number within the given bank.
824 * @param[in] bsp_specific Pointer to a BSP defined structure with BSP-specific
825 *                         data.
826 *
827 * @retval RTEMS_SUCCESSFUL Function was assigned successfully.
828 * @retval RTEMS_UNSATISFIED Could not assign the function to the pin.
829 */
830extern rtems_status_code rtems_gpio_bsp_select_input(
831  uint32_t bank,
832  uint32_t pin,
833  void *bsp_specific
834);
835
836/**
837 * @brief Assigns the digital output function to the given pin.
838 *        This must be implemented by each BSP.
839 *
840 * @param[in] bank GPIO bank number.
841 * @param[in] pin GPIO pin number within the given bank.
842 * @param[in] bsp_specific Pointer to a BSP defined structure with BSP-specific
843 *                         data.
844 *
845 * @retval RTEMS_SUCCESSFUL Function was assigned successfully.
846 * @retval RTEMS_UNSATISFIED Could not assign the function to the pin.
847 */
848extern rtems_status_code rtems_gpio_bsp_select_output(
849  uint32_t bank,
850  uint32_t pin,
851  void *bsp_specific
852);
853
854/**
855 * @brief Assigns a BSP specific function to the given pin.
856 *        This must be implemented by each BSP.
857 *
858 * @param[in] bank GPIO bank number.
859 * @param[in] pin GPIO pin number within the given bank.
860 * @param[in] function BSP defined GPIO function.
861 * @param[in] pin_data Pointer to a BSP defined structure with BSP-specific
862 *                     data.
863 *
864 * @retval RTEMS_SUCCESSFUL Function was assigned successfully.
865 * @retval RTEMS_UNSATISFIED Could not assign the function to the pin.
866 */
867extern rtems_status_code rtems_gpio_bsp_select_specific_io(
868  uint32_t bank,
869  uint32_t pin,
870  uint32_t function,
871  void *pin_data
872);
873
874/**
875 * @brief Configures a single GPIO pin pull resistor.
876 *        This must be implemented by each BSP.
877 *
878 * @param[in] bank GPIO bank number.
879 * @param[in] pin GPIO pin number within the given bank.
880 * @param[in] mode The pull resistor mode.
881 *
882 * @retval RTEMS_SUCCESSFUL Pull resistor successfully configured.
883 * @retval RTEMS_UNSATISFIED Could not set the pull mode.
884 */
885extern rtems_status_code rtems_gpio_bsp_set_resistor_mode(
886  uint32_t bank,
887  uint32_t pin,
888  rtems_gpio_pull_mode mode
889);
890
891/**
892 * @brief Reads and returns a vector/bank interrupt event line.
893 *        The bitmask should indicate with a 1 if the corresponding pin
894 *        as a pending interrupt, or 0 if otherwise. The function
895 *        should clear the interrupt event line before returning.
896 *        This must be implemented by each BSP.
897 *
898 * @param[in] vector GPIO vector/bank.
899 *
900 * @retval Bitmask (max 32-bit) representing a GPIO bank, where a bit set
901 *         indicates an active interrupt on that pin.
902 */
903extern uint32_t rtems_gpio_bsp_interrupt_line(rtems_vector_number vector);
904
905/**
906 * @brief Calculates a vector number for a given GPIO bank.
907 *        This must be implemented by each BSP.
908 *
909 * @param[in] bank GPIO bank number.
910 *
911 * @retval The corresponding rtems_vector_number.
912 */
913extern rtems_vector_number rtems_gpio_bsp_get_vector(uint32_t bank);
914
915/**
916 * @brief Enables interrupts to be generated on a given GPIO pin.
917 *        This must be implemented by each BSP.
918 *
919 * @param[in] bank GPIO bank number.
920 * @param[in] pin GPIO pin number within the given bank.
921 * @param[in] interrupt Type of interrupt to enable for the pin.
922 *
923 * @retval RTEMS_SUCCESSFUL Interrupt successfully enabled for this pin.
924 * @retval RTEMS_UNSATISFIED Could not enable the interrupt on the pin.
925 */
926extern rtems_status_code rtems_gpio_bsp_enable_interrupt(
927  uint32_t bank,
928  uint32_t pin,
929  rtems_gpio_interrupt interrupt
930);
931
932/**
933 * @brief Stops interrupts from being generated on a given GPIO pin.
934 *        This must be implemented by each BSP.
935 *
936 * @param[in] bank GPIO bank number.
937 * @param[in] pin GPIO pin number within the given bank.
938 * @param[in] active_interrupt Interrupt type currently active on this pin.
939 *
940 * @retval RTEMS_SUCCESSFUL Interrupt successfully disabled for this pin.
941 * @retval RTEMS_UNSATISFIED Could not disable interrupts on this pin.
942 */
943extern rtems_status_code rtems_gpio_bsp_disable_interrupt(
944  uint32_t bank,
945  uint32_t pin,
946  rtems_gpio_interrupt interrupt
947);
948
949/** @} */
950
951#ifdef __cplusplus
952}
953#endif /* __cplusplus */
954
955#endif /* LIBBSP_SHARED_GPIO_H */
Note: See TracBrowser for help on using the repository browser.