summaryrefslogtreecommitdiffstats
path: root/bsps/include/bsp/gpio.h
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2017-12-23 18:18:56 +1100
committerSebastian Huber <sebastian.huber@embedded-brains.de>2018-01-25 08:45:26 +0100
commit2afb22b7e1ebcbe40373ff7e0efae7d207c655a9 (patch)
tree44759efe9374f13200a97e96d91bd9a2b7e5ce2a /bsps/include/bsp/gpio.h
parentMAINTAINERS: Add myself to Write After Approval. (diff)
downloadrtems-2afb22b7e1ebcbe40373ff7e0efae7d207c655a9.tar.bz2
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.
Diffstat (limited to 'bsps/include/bsp/gpio.h')
-rw-r--r--bsps/include/bsp/gpio.h955
1 files changed, 955 insertions, 0 deletions
diff --git a/bsps/include/bsp/gpio.h b/bsps/include/bsp/gpio.h
new file mode 100644
index 0000000000..64a877ae7a
--- /dev/null
+++ b/bsps/include/bsp/gpio.h
@@ -0,0 +1,955 @@
+/**
+ * @file gpio.h
+ *
+ * @ingroup rtems_gpio
+ *
+ * @brief RTEMS GPIO API definition.
+ */
+
+/*
+ * Copyright (c) 2014-2015 Andre Marques <andre.lousa.marques at gmail.com>
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.org/license/LICENSE.
+ */
+
+#ifndef LIBBSP_SHARED_GPIO_H
+#define LIBBSP_SHARED_GPIO_H
+
+#include <bsp.h>
+#include <rtems.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+#if !defined(BSP_GPIO_PIN_COUNT) || !defined(BSP_GPIO_PINS_PER_BANK)
+ #error "BSP_GPIO_PIN_COUNT or BSP_GPIO_PINS_PER_BANK is not defined."
+#endif
+
+#if BSP_GPIO_PIN_COUNT <= 0 || BSP_GPIO_PINS_PER_BANK <= 0
+ #error "Invalid BSP_GPIO_PIN_COUNT or BSP_GPIO_PINS_PER_BANK."
+#endif
+
+#if BSP_GPIO_PINS_PER_BANK > 32
+ #error "Invalid BSP_GPIO_PINS_PER_BANK. Must be in the range of 1 to 32."
+#endif
+
+#define GPIO_LAST_BANK_PINS BSP_GPIO_PIN_COUNT % BSP_GPIO_PINS_PER_BANK
+
+#if GPIO_LAST_BANK_PINS > 0
+ #define GPIO_BANK_COUNT (BSP_GPIO_PIN_COUNT / BSP_GPIO_PINS_PER_BANK) + 1
+#else
+ #define GPIO_BANK_COUNT BSP_GPIO_PIN_COUNT / BSP_GPIO_PINS_PER_BANK
+ #undef GPIO_LAST_BANK_PINS
+ #define GPIO_LAST_BANK_PINS BSP_GPIO_PINS_PER_BANK
+#endif
+
+#if defined(BSP_GPIO_PINS_PER_SELECT_BANK) && BSP_GPIO_PINS_PER_SELECT_BANK > 32
+ #error "Invalid BSP_GPIO_PINS_PER_SELECT_BANK. Must under and including 32."
+#elif defined(BSP_GPIO_PINS_PER_SELECT_BANK) <= 32
+ #define GPIO_SELECT_BANK_COUNT \
+ BSP_GPIO_PINS_PER_BANK / BSP_GPIO_PINS_PER_SELECT_BANK
+#endif
+
+#define INTERRUPT_SERVER_PRIORITY 1
+#define INTERRUPT_SERVER_STACK_SIZE 2 * RTEMS_MINIMUM_STACK_SIZE
+#define INTERRUPT_SERVER_MODES RTEMS_TIMESLICE | RTEMS_PREEMPT
+#define INTERRUPT_SERVER_ATTRIBUTES RTEMS_DEFAULT_ATTRIBUTES
+
+#define GPIO_INPUT_ERROR ~0
+
+/**
+ * @name GPIO data structures
+ *
+ * @{
+ */
+
+/**
+ * @brief The set of possible configurations for a GPIO pull-up resistor.
+ *
+ * Enumerated type to define the possible pull-up resistor configurations
+ * for a GPIO pin.
+ */
+typedef enum
+{
+ PULL_UP = 1,
+ PULL_DOWN,
+ NO_PULL_RESISTOR
+} rtems_gpio_pull_mode;
+
+/**
+ * @brief The set of possible functions a pin can have.
+ *
+ * Enumerated type to define a pin function.
+ */
+typedef enum
+{
+ DIGITAL_INPUT = 0,
+ DIGITAL_OUTPUT,
+ BSP_SPECIFIC,
+ NOT_USED
+} rtems_gpio_function;
+
+/**
+ * @brief The set of possible interrupts a GPIO pin can generate.
+ *
+ * Enumerated type to define a GPIO pin interrupt.
+ */
+typedef enum
+{
+ FALLING_EDGE = 0,
+ RISING_EDGE,
+ LOW_LEVEL,
+ HIGH_LEVEL,
+ BOTH_EDGES,
+ BOTH_LEVELS,
+ NONE
+} rtems_gpio_interrupt;
+
+/**
+ * @brief The set of possible handled states an user-defined interrupt
+ * handler can return.
+ *
+ * Enumerated type to define an interrupt handler handled state.
+ */
+typedef enum
+{
+ IRQ_HANDLED,
+ IRQ_NONE
+} rtems_gpio_irq_state;
+
+/**
+ * @brief The set of flags to specify an user-defined interrupt handler
+ * uniqueness on a GPIO pin.
+ *
+ * Enumerated type to define an interrupt handler shared flag.
+ */
+typedef enum
+{
+ SHARED_HANDLER,
+ UNIQUE_HANDLER
+} rtems_gpio_handler_flag;
+
+/**
+ * @brief Object containing relevant information for assigning a BSP specific
+ * function to a pin.
+ *
+ * Encapsulates relevant data for a BSP specific GPIO function.
+ */
+typedef struct
+{
+ /* The BSP defined function code. */
+ uint32_t io_function;
+
+ void *pin_data;
+} rtems_gpio_specific_data;
+
+/**
+ * @brief Object containing configuration information
+ * regarding interrupts.
+ */
+typedef struct
+{
+ rtems_gpio_interrupt active_interrupt;
+
+ rtems_gpio_handler_flag handler_flag;
+
+ bool threaded_interrupts;
+
+ /* Interrupt handler function. */
+ rtems_gpio_irq_state (*handler) (void *arg);
+
+ /* Interrupt handler function arguments. */
+ void *arg;
+
+ /* Software switch debounce settings. It should contain the amount of clock
+ * ticks that must pass between interrupts to ensure that the interrupt
+ * was not caused by a switch bounce.
+ * If set to 0 this feature is disabled . */
+ uint32_t debounce_clock_tick_interval;
+} rtems_gpio_interrupt_configuration;
+
+/**
+ * @brief Object containing configuration information
+ * to request/update a GPIO pin.
+ */
+typedef struct
+{
+ /* Processor pin number. */
+ uint32_t pin_number;
+ rtems_gpio_function function;
+
+ /* Pull resistor setting. */
+ rtems_gpio_pull_mode pull_mode;
+
+ /* If digital out pin, set to TRUE to set the pin to logical high,
+ * or FALSE for logical low. If not a digital out then this
+ * is ignored. */
+ bool output_enabled;
+
+ /* If true inverts digital in/out applicational logic. */
+ bool logic_invert;
+
+ /* Pin interrupt configuration. Should be NULL if not used. */
+ rtems_gpio_interrupt_configuration *interrupt;
+
+ /* Structure with BSP specific data, to use during the pin request.
+ * If function == BSP_SPECIFIC this should have a pointer to
+ * a rtems_gpio_specific_data structure.
+ *
+ * If not this field may be NULL. This is passed to the BSP function
+ * so any BSP specific data can be passed to it through this pointer. */
+ void *bsp_specific;
+} rtems_gpio_pin_conf;
+
+/**
+ * @brief Object containing configuration information
+ * to assign GPIO functions to multiple pins
+ * at the same time. To be used by BSP code only.
+ */
+typedef struct
+{
+ /* Global GPIO pin number. */
+ uint32_t pin_number;
+
+ /* RTEMS GPIO pin function code. */
+ rtems_gpio_function function;
+
+ /* BSP specific function code. Only used if function == BSP_SPECIFIC */
+ uint32_t io_function;
+
+ /* BSP specific data. */
+ void *bsp_specific;
+} rtems_gpio_multiple_pin_select;
+
+/**
+ * @brief Object containing configuration information
+ * to request a GPIO pin group.
+ */
+typedef struct
+{
+ const rtems_gpio_pin_conf *digital_inputs;
+ uint32_t input_count;
+
+ const rtems_gpio_pin_conf *digital_outputs;
+ uint32_t output_count;
+
+ const rtems_gpio_pin_conf *bsp_specifics;
+ uint32_t bsp_specific_pin_count;
+} rtems_gpio_group_definition;
+
+/**
+ * @brief Opaque type for a GPIO pin group.
+ */
+typedef struct rtems_gpio_group rtems_gpio_group;
+
+/** @} */
+
+/**
+ * @name gpio Usage
+ *
+ * @{
+ */
+
+/**
+ * @brief Initializes the GPIO API.
+ *
+ * @retval RTEMS_SUCCESSFUL API successfully initialized.
+ * @retval * @see rtems_semaphore_create().
+ */
+extern rtems_status_code rtems_gpio_initialize(void);
+
+/**
+ * @brief Instantiates a GPIO pin group.
+ * To define the group @see rtems_gpio_define_pin_group().
+ *
+ * @retval rtems_gpio_group pointer.
+ */
+extern rtems_gpio_group *rtems_gpio_create_pin_group(void);
+
+/**
+ * @brief Requests a GPIO pin group configuration.
+ *
+ * @param[in] group_definition rtems_gpio_group_definition structure filled with
+ * the group pins configurations.
+ * @param[out] group Reference to the created group.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin group was configured successfully.
+ * @retval RTEMS_UNSATISFIED @var group_definition or @var group is NULL,
+ * the @var pins are not from the same bank,
+ * no pins were defined or could not satisfy at
+ * least one given configuration.
+ * @retval RTEMS_RESOURCE_IN_USE At least one pin is already being used.
+ * @retval * @see rtems_semaphore_create().
+ */
+extern rtems_status_code rtems_gpio_define_pin_group(
+ const rtems_gpio_group_definition *group_definition,
+ rtems_gpio_group *group
+);
+
+/**
+ * @brief Writes a value to the group's digital outputs. The pins order
+ * is as defined in the group definition.
+ *
+ * @param[in] data Data to write/send.
+ * @param[in] group Reference to the group.
+ *
+ * @retval RTEMS_SUCCESSFUL Data successfully written.
+ * @retval RTEMS_NOT_DEFINED Group has no output pins.
+ * @retval RTEMS_UNSATISFIED Could not operate on at least one of the pins.
+ */
+extern rtems_status_code rtems_gpio_write_group(
+ uint32_t data,
+ rtems_gpio_group *group
+);
+
+/**
+ * @brief Reads the value/level of the group's digital inputs. The pins order
+ * is as defined in the group definition.
+ *
+ * @param[in] group Reference to the group.
+ *
+ * @retval The function returns a 32-bit bitmask with the group's input pins
+ * current logical values.
+ * @retval GPIO_INPUT_ERROR Group has no input pins.
+ */
+extern uint32_t rtems_gpio_read_group(rtems_gpio_group *group);
+
+/**
+ * @brief Performs a BSP specific operation on a group of pins. The pins order
+ * is as defined in the group definition.
+ *
+ * @param[in] group Reference to the group.
+ * @param[in] arg Pointer to a BSP defined structure with BSP-specific
+ * data. This field is handled by the BSP.
+ *
+ * @retval RTEMS_SUCCESSFUL Operation completed with success.
+ * @retval RTEMS_NOT_DEFINED Group has no BSP specific pins, or the BSP does not
+ * support BSP specific operations for groups.
+ * @retval RTEMS_UNSATISFIED Could not operate on at least one of the pins.
+ */
+extern rtems_status_code rtems_gpio_group_bsp_specific_operation(
+ rtems_gpio_group *group,
+ void *arg
+);
+
+/**
+ * @brief Requests a GPIO pin configuration.
+ *
+ * @param[in] conf rtems_gpio_pin_conf structure filled with the pin information
+ * and desired configurations.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin was configured successfully.
+ * @retval RTEMS_UNSATISFIED Could not satisfy the given configuration.
+ */
+extern rtems_status_code rtems_gpio_request_configuration(
+ const rtems_gpio_pin_conf *conf
+);
+
+/**
+ * @brief Updates the current configuration of a GPIO pin .
+ *
+ * @param[in] conf rtems_gpio_pin_conf structure filled with the pin information
+ * and desired configurations.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin configuration was updated successfully.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED The pin is not being used.
+ * @retval RTEMS_UNSATISFIED Could not update the pin's configuration.
+ */
+extern rtems_status_code rtems_gpio_update_configuration(
+ const rtems_gpio_pin_conf *conf
+);
+
+/**
+ * @brief Sets multiple output GPIO pins with the logical high.
+ *
+ * @param[in] pin_numbers Array with the GPIO pin numbers to set.
+ * @param[in] count Number of GPIO pins to set.
+ *
+ * @retval RTEMS_SUCCESSFUL All pins were set successfully.
+ * @retval RTEMS_INVALID_ID At least one pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED At least one of the received pins
+ * is not configured as a digital output.
+ * @retval RTEMS_UNSATISFIED Could not set the GPIO pins.
+ */
+extern rtems_status_code rtems_gpio_multi_set(
+ uint32_t *pin_numbers,
+ uint32_t pin_count
+);
+
+/**
+ * @brief Sets multiple output GPIO pins with the logical low.
+ *
+ * @param[in] pin_numbers Array with the GPIO pin numbers to clear.
+ * @param[in] count Number of GPIO pins to clear.
+ *
+ * @retval RTEMS_SUCCESSFUL All pins were cleared successfully.
+ * @retval RTEMS_INVALID_ID At least one pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED At least one of the received pins
+ * is not configured as a digital output.
+ * @retval RTEMS_UNSATISFIED Could not clear the GPIO pins.
+ */
+extern rtems_status_code rtems_gpio_multi_clear(
+ uint32_t *pin_numbers,
+ uint32_t pin_count
+);
+
+/**
+ * @brief Returns the value (level) of multiple GPIO input pins.
+ *
+ * @param[in] pin_numbers Array with the GPIO pin numbers to read.
+ * @param[in] count Number of GPIO pins to read.
+ *
+ * @retval Bitmask with the values of the corresponding pins.
+ * 0 for logical low and 1 for logical high.
+ * @retval GPIO_INPUT_ERROR Could not read at least one pin level.
+ */
+extern uint32_t rtems_gpio_multi_read(
+ uint32_t *pin_numbers,
+ uint32_t pin_count
+);
+
+/**
+ * @brief Sets an output GPIO pin with the logical high.
+ *
+ * @param[in] pin_number GPIO pin number.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin was set successfully.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED The received pin is not configured
+ * as a digital output.
+ * @retval RTEMS_UNSATISFIED Could not set the GPIO pin.
+ */
+extern rtems_status_code rtems_gpio_set(uint32_t pin_number);
+
+/**
+ * @brief Sets an output GPIO pin with the logical low.
+ *
+ * @param[in] pin_number GPIO pin number.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin was cleared successfully.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED The received pin is not configured
+ * as a digital output.
+ * @retval RTEMS_UNSATISFIED Could not clear the GPIO pin.
+ */
+extern rtems_status_code rtems_gpio_clear(uint32_t pin_number);
+
+/**
+ * @brief Returns the value (level) of a GPIO input pin.
+ *
+ * @param[in] pin_number GPIO pin number.
+ *
+ * @retval The function returns 0 or 1 depending on the pin current
+ * logical value.
+ * @retval -1 Pin number is invalid, or not a digital input pin.
+ */
+extern int rtems_gpio_get_value(uint32_t pin_number);
+
+/**
+ * @brief Requests multiple GPIO pin configurations. If the BSP provides
+ * support for parallel selection each call to this function will
+ * result in a single call to the GPIO hardware, else each pin
+ * configuration will be done in individual and sequential calls.
+ * All pins must belong to the same GPIO bank.
+ *
+ * @param[in] pins Array of rtems_gpio_pin_conf structures filled with the pins
+ * information and desired configurations. All pins must belong
+ * to the same GPIO bank.
+ * @param[in] pin_count Number of pin configurations in the @var pins array.
+ *
+ * @retval RTEMS_SUCCESSFUL All pins were configured successfully.
+ * @retval RTEMS_INVALID_ID At least one pin number in the @var pins array
+ * is invalid.
+ * @retval RTEMS_RESOURCE_IN_USE At least one pin is already being used.
+ * @retval RTEMS_UNSATISFIED Could not satisfy at least one given configuration.
+ */
+extern rtems_status_code rtems_gpio_multi_select(
+ const rtems_gpio_pin_conf *pins,
+ uint8_t pin_count
+);
+
+/**
+ * @brief Assigns a certain function to a GPIO pin.
+ *
+ * @param[in] pin_number GPIO pin number.
+ * @param[in] function The new function for the pin.
+ * @param[in] output_enabled If TRUE and @var function is DIGITAL_OUTPUT,
+ * then the pin is set with the logical high.
+ * Otherwise it is set with logical low.
+ * @param[in] logic_invert Reverses the digital I/O logic for DIGITAL_INPUT
+ * and DIGITAL_OUTPUT pins.
+ * @param[in] bsp_specific Pointer to a BSP defined structure with BSP-specific
+ * data. This field is handled by the BSP.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin was configured successfully.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_RESOURCE_IN_USE The received pin is already being used.
+ * @retval RTEMS_UNSATISFIED Could not assign the GPIO function.
+ * @retval RTEMS_NOT_DEFINED GPIO function not defined, or NOT_USED.
+ */
+extern rtems_status_code rtems_gpio_request_pin(
+ uint32_t pin_number,
+ rtems_gpio_function function,
+ bool output_enable,
+ bool logic_invert,
+ void *bsp_specific
+);
+
+/**
+ * @brief Configures a single GPIO pin pull resistor.
+ *
+ * @param[in] pin_number GPIO pin number.
+ * @param[in] mode The pull resistor mode.
+ *
+ * @retval RTEMS_SUCCESSFUL Pull resistor successfully configured.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_UNSATISFIED Could not set the pull mode.
+ */
+extern rtems_status_code rtems_gpio_resistor_mode(
+ uint32_t pin_number,
+ rtems_gpio_pull_mode mode
+);
+
+/**
+ * @brief Releases a GPIO pin, making it available to be used again.
+ *
+ * @param[in] pin_number GPIO pin number.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin successfully disabled.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval * Could not disable an active interrupt on this pin,
+ * @see rtems_gpio_disable_interrupt().
+ */
+extern rtems_status_code rtems_gpio_release_pin(uint32_t pin_number);
+
+/**
+ * @brief Releases a GPIO pin, making it available to be used again.
+ *
+ * @param[in] conf GPIO pin configuration to be released.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin successfully disabled.
+ * @retval RTEMS_UNSATISFIED Pin configuration is NULL.
+ * @retval * @see rtems_gpio_release_pin().
+ */
+extern rtems_status_code rtems_gpio_release_configuration(
+ const rtems_gpio_pin_conf *conf
+);
+
+/**
+ * @brief Releases multiple GPIO pins, making them available to be used again.
+ *
+ * @param[in] pins Array of rtems_gpio_pin_conf structures.
+ * @param[in] pin_count Number of pin configurations in the @var pins array.
+ *
+ * @retval RTEMS_SUCCESSFUL Pins successfully disabled.
+ * @retval RTEMS_UNSATISFIED @var pins array is NULL.
+ * @retval * @see rtems_gpio_release_pin().
+ */
+extern rtems_status_code rtems_gpio_release_multiple_pins(
+ const rtems_gpio_pin_conf *pins,
+ uint32_t pin_count
+);
+
+/**
+ * @brief Releases a GPIO pin group, making the pins used available to be
+ * repurposed.
+ *
+ * @param[in] conf GPIO pin configuration to be released.
+ *
+ * @retval RTEMS_SUCCESSFUL Pins successfully disabled.
+ * @retval * @see rtems_gpio_release_pin(), @see rtems_semaphore_delete() or
+ * @see rtems_semaphore_flush().
+ */
+extern rtems_status_code rtems_gpio_release_pin_group(
+ rtems_gpio_group *group
+);
+
+/**
+ * @brief Attaches a debouncing function to a given pin/switch.
+ * Debouncing is done by requiring a certain number of clock ticks to
+ * pass between interrupts. Any interrupt fired too close to the last
+ * will be ignored as it is probably the result of an involuntary
+ * switch/button bounce after being released.
+ *
+ * @param[in] pin_number GPIO pin number.
+ * @param[in] ticks Minimum number of clock ticks that must pass between
+ * interrupts so it can be considered a legitimate
+ * interrupt.
+ *
+ * @retval RTEMS_SUCCESSFUL Debounce function successfully attached to the pin.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED The current pin is not configured as a digital
+ * input, hence it can not be connected to a switch,
+ * or interrupts are not enabled for this pin.
+ */
+extern rtems_status_code rtems_gpio_debounce_switch(
+ uint32_t pin_number,
+ int ticks
+);
+
+/**
+ * @brief Connects a new user-defined interrupt handler to a given pin.
+ *
+ * @param[in] pin_number GPIO pin number.
+ * @param[in] handler Pointer to a function that will be called every time
+ * the enabled interrupt for the given pin is generated.
+ * This function must return information about its
+ * handled/unhandled state.
+ * @param[in] arg Void pointer to the arguments of the user-defined handler.
+ *
+ * @retval RTEMS_SUCCESSFUL Handler successfully connected to this pin.
+ * @retval RTEMS_NO_MEMORY Could not connect more user-defined handlers to
+ * the given pin.
+ * @retval RTEMS_NOT_CONFIGURED The given pin has no interrupt configured.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_TOO_MANY The pin's current handler is set as unique.
+ * @retval RTEMS_RESOURCE_IN_USE The current user-defined handler for this pin
+ * is unique.
+ */
+extern rtems_status_code rtems_gpio_interrupt_handler_install(
+ uint32_t pin_number,
+ rtems_gpio_irq_state (*handler) (void *arg),
+ void *arg
+);
+
+/**
+ * @brief Enables interrupts to be generated on a given GPIO pin.
+ * When fired that interrupt will call the given handler.
+ *
+ * @param[in] pin_number GPIO pin number.
+ * @param[in] interrupt Type of interrupt to enable for the pin.
+ * @param[in] flag Defines the uniqueness of the interrupt handler for the pin.
+ * @param[in] threaded_handling Defines if the handler should be called from a
+ * thread/task or from normal ISR contex.
+ * @param[in] handler Pointer to a function that will be called every time
+ * @var interrupt is generated. This function must return
+ * information about its handled/unhandled state.
+ * @param[in] arg Void pointer to the arguments of the user-defined handler.
+ *
+ * @retval RTEMS_SUCCESSFUL Interrupt successfully enabled for this pin.
+ * @retval RTEMS_UNSATISFIED Could not install the GPIO ISR, create/start
+ * the handler task, or enable the interrupt
+ * on the pin.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED The received pin is not configured
+ * as a digital input, the pin is on a
+ * pin grouping.
+ * @retval RTEMS_RESOURCE_IN_USE The pin already has an enabled interrupt,
+ * or the handler threading policy does not match
+ * the bank's policy.
+ * @retval RTEMS_NO_MEMORY Could not store the pin's interrupt configuration.
+ */
+extern rtems_status_code rtems_gpio_enable_interrupt(
+ uint32_t pin_number,
+ rtems_gpio_interrupt interrupt,
+ rtems_gpio_handler_flag flag,
+ bool threaded_handling,
+ rtems_gpio_irq_state (*handler) (void *arg),
+ void *arg
+);
+
+/**
+ * @brief Disconnects an user-defined interrupt handler from the given pin.
+ * If in the end there are no more user-defined handlers connected
+ * to the pin, interrupts are disabled on the given pin.
+ *
+ * @param[in] pin_number GPIO pin number.
+ * @param[in] handler Pointer to the user-defined handler
+ * @param[in] arg Void pointer to the arguments of the user-defined handler.
+ *
+ * @retval RTEMS_SUCCESSFUL Handler successfully disconnected from this pin.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED Pin has no active interrupts.
+ * @retval * @see rtems_gpio_disable_interrupt()
+ */
+extern rtems_status_code rtems_gpio_interrupt_handler_remove(
+ uint32_t pin_number,
+ rtems_gpio_irq_state (*handler) (void *arg),
+ void *arg
+);
+
+/**
+ * @brief Stops interrupts from being generated on a given GPIO pin
+ * and removes the corresponding handler.
+ *
+ * @param[in] pin_number GPIO pin number.
+ *
+ * @retval RTEMS_SUCCESSFUL Interrupt successfully disabled for this pin.
+ * @retval RTEMS_INVALID_ID Pin number is invalid.
+ * @retval RTEMS_NOT_CONFIGURED Pin has no active interrupts.
+ * @retval RTEMS_UNSATISFIED Could not remove the current interrupt handler,
+ * could not recognize the current active interrupt
+ * on this pin or could not disable interrupts on
+ * this pin.
+ */
+extern rtems_status_code rtems_gpio_disable_interrupt(uint32_t pin_number);
+
+/**
+ * @brief Sets multiple output GPIO pins with the logical high.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] bitmask Bitmask of GPIO pins to set in the given bank.
+ *
+ * @retval RTEMS_SUCCESSFUL All pins were set successfully.
+ * @retval RTEMS_UNSATISFIED Could not set at least one of the pins.
+ */
+extern rtems_status_code rtems_gpio_bsp_multi_set(
+ uint32_t bank,
+ uint32_t bitmask
+);
+
+/**
+ * @brief Sets multiple output GPIO pins with the logical low.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] bitmask Bitmask of GPIO pins to clear in the given bank.
+ *
+ * @retval RTEMS_SUCCESSFUL All pins were cleared successfully.
+ * @retval RTEMS_UNSATISFIED Could not clear at least one of the pins.
+ */
+extern rtems_status_code rtems_gpio_bsp_multi_clear(
+ uint32_t bank,
+ uint32_t bitmask
+);
+
+/**
+ * @brief Returns the value (level) of multiple GPIO input pins.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] bitmask Bitmask of GPIO pins to read in the given bank.
+ *
+ * @retval The function must return a bitmask with the values of the
+ * corresponding pins. 0 for logical low and 1 for logical high.
+ * @retval GPIO_INPUT_ERROR Could not read at least one pin level.
+ */
+extern uint32_t rtems_gpio_bsp_multi_read(uint32_t bank, uint32_t bitmask);
+
+/**
+ * @brief Performs a BSP specific operation on a group of pins.
+ * The implementation for this function may be omitted if the target
+ * does not support the feature, by returning RTEMS_NOT_DEFINED.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pins Array filled with BSP specific pin numbers. All pins belong
+ * to the same select bank.
+ * @param[in] pin_count Number of pin configurations in the @var pins array.
+ * @param[in] arg Pointer to a BSP defined structure with BSP-specific
+ * data. This field is handled by the BSP.
+ *
+ * @retval RTEMS_SUCCESSFUL Operation completed with success.
+ * @retval RTEMS_NOT_DEFINED Group has no BSP specific pins, or the BSP does not
+ * support BSP specific operations for groups.
+ * @retval RTEMS_UNSATISFIED Could not operate on at least one of the pins.
+ */
+extern rtems_status_code rtems_gpio_bsp_specific_group_operation(
+ uint32_t bank,
+ uint32_t *pins,
+ uint32_t pin_count,
+ void *arg
+);
+
+/**
+ * @brief Assigns GPIO functions to all the given pins in a single register
+ * operation.
+ * The implementation for this function may be omitted if the target
+ * does not support the feature, by returning RTEMS_NOT_DEFINED.
+ *
+ * @param[in] pins Array of rtems_gpio_multiple_pin_select structures filled
+ * with the pins desired functions. All pins belong to the
+ * same select bank.
+ * @param[in] pin_count Number of pin configurations in the @var pins array.
+ * @param[in] select_bank Select bank number of the received pins.
+ *
+ * @retval RTEMS_SUCCESSFUL Functions were assigned successfully.
+ * @retval RTEMS_NOT_DEFINED The BSP does not support multiple pin function
+ * assignment.
+ * @retval RTEMS_UNSATISFIED Could not assign the functions to the pins.
+ */
+extern rtems_status_code rtems_gpio_bsp_multi_select(
+ rtems_gpio_multiple_pin_select *pins,
+ uint32_t pin_count,
+ uint32_t select_bank
+);
+
+/**
+ * @brief Sets an output GPIO pin with the logical high.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin was set successfully.
+ * @retval RTEMS_UNSATISFIED Could not set the given pin.
+ */
+extern rtems_status_code rtems_gpio_bsp_set(uint32_t bank, uint32_t pin);
+
+/**
+ * @brief Sets an output GPIO pin with the logical low.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ *
+ * @retval RTEMS_SUCCESSFUL Pin was cleared successfully.
+ * @retval RTEMS_UNSATISFIED Could not clear the given pin.
+ */
+extern rtems_status_code rtems_gpio_bsp_clear(uint32_t bank, uint32_t pin);
+
+/**
+ * @brief Returns the value (level) of a GPIO input pin.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ *
+ * @retval The function must return 0 if the pin level is a logical low,
+ * or non zero if it has a logical high.
+ * @retval GPIO_INPUT_ERROR Could not read the pin level.
+ */
+extern uint32_t rtems_gpio_bsp_get_value(uint32_t bank, uint32_t pin);
+
+/**
+ * @brief Assigns the digital input function to the given pin.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ * @param[in] bsp_specific Pointer to a BSP defined structure with BSP-specific
+ * data.
+ *
+ * @retval RTEMS_SUCCESSFUL Function was assigned successfully.
+ * @retval RTEMS_UNSATISFIED Could not assign the function to the pin.
+ */
+extern rtems_status_code rtems_gpio_bsp_select_input(
+ uint32_t bank,
+ uint32_t pin,
+ void *bsp_specific
+);
+
+/**
+ * @brief Assigns the digital output function to the given pin.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ * @param[in] bsp_specific Pointer to a BSP defined structure with BSP-specific
+ * data.
+ *
+ * @retval RTEMS_SUCCESSFUL Function was assigned successfully.
+ * @retval RTEMS_UNSATISFIED Could not assign the function to the pin.
+ */
+extern rtems_status_code rtems_gpio_bsp_select_output(
+ uint32_t bank,
+ uint32_t pin,
+ void *bsp_specific
+);
+
+/**
+ * @brief Assigns a BSP specific function to the given pin.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ * @param[in] function BSP defined GPIO function.
+ * @param[in] pin_data Pointer to a BSP defined structure with BSP-specific
+ * data.
+ *
+ * @retval RTEMS_SUCCESSFUL Function was assigned successfully.
+ * @retval RTEMS_UNSATISFIED Could not assign the function to the pin.
+ */
+extern rtems_status_code rtems_gpio_bsp_select_specific_io(
+ uint32_t bank,
+ uint32_t pin,
+ uint32_t function,
+ void *pin_data
+);
+
+/**
+ * @brief Configures a single GPIO pin pull resistor.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ * @param[in] mode The pull resistor mode.
+ *
+ * @retval RTEMS_SUCCESSFUL Pull resistor successfully configured.
+ * @retval RTEMS_UNSATISFIED Could not set the pull mode.
+ */
+extern rtems_status_code rtems_gpio_bsp_set_resistor_mode(
+ uint32_t bank,
+ uint32_t pin,
+ rtems_gpio_pull_mode mode
+);
+
+/**
+ * @brief Reads and returns a vector/bank interrupt event line.
+ * The bitmask should indicate with a 1 if the corresponding pin
+ * as a pending interrupt, or 0 if otherwise. The function
+ * should clear the interrupt event line before returning.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] vector GPIO vector/bank.
+ *
+ * @retval Bitmask (max 32-bit) representing a GPIO bank, where a bit set
+ * indicates an active interrupt on that pin.
+ */
+extern uint32_t rtems_gpio_bsp_interrupt_line(rtems_vector_number vector);
+
+/**
+ * @brief Calculates a vector number for a given GPIO bank.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ *
+ * @retval The corresponding rtems_vector_number.
+ */
+extern rtems_vector_number rtems_gpio_bsp_get_vector(uint32_t bank);
+
+/**
+ * @brief Enables interrupts to be generated on a given GPIO pin.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ * @param[in] interrupt Type of interrupt to enable for the pin.
+ *
+ * @retval RTEMS_SUCCESSFUL Interrupt successfully enabled for this pin.
+ * @retval RTEMS_UNSATISFIED Could not enable the interrupt on the pin.
+ */
+extern rtems_status_code rtems_gpio_bsp_enable_interrupt(
+ uint32_t bank,
+ uint32_t pin,
+ rtems_gpio_interrupt interrupt
+);
+
+/**
+ * @brief Stops interrupts from being generated on a given GPIO pin.
+ * This must be implemented by each BSP.
+ *
+ * @param[in] bank GPIO bank number.
+ * @param[in] pin GPIO pin number within the given bank.
+ * @param[in] active_interrupt Interrupt type currently active on this pin.
+ *
+ * @retval RTEMS_SUCCESSFUL Interrupt successfully disabled for this pin.
+ * @retval RTEMS_UNSATISFIED Could not disable interrupts on this pin.
+ */
+extern rtems_status_code rtems_gpio_bsp_disable_interrupt(
+ uint32_t bank,
+ uint32_t pin,
+ rtems_gpio_interrupt interrupt
+);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* LIBBSP_SHARED_GPIO_H */