source: rtems/c/src/lib/libbsp/shared/include/gpio.h @ 5c337d7e

5
Last change on this file since 5c337d7e was 5c337d7e, checked in by Sudarshan Rajagopalan <sudarshan.rajagopalan@…>, on 10/21/15 at 15:33:44

Fixes GPIO APIs Naming Convention and Comments

Closes #2435.

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