This section provides introduction to the General Purpose Input Output (GPIO) APIs, including terms and acronyms, features, architecture, how to use APIs, the GPIO function groups, enums, structures and functions.
More...
This section provides introduction to the General Purpose Input Output (GPIO) APIs, including terms and acronyms, features, architecture, how to use APIs, the GPIO function groups, enums, structures and functions.
Terms and acronyms
| Terms | Details |
| GPIO | General Purpose Input Output is a generic pin on an integrated circuit defined as an input or output pin, and controlled by the user at run time. For more information, please refer to General Purpose Input Output in Wikipedia . |
Supported features
- Support GPIO and peripheral operating modes.
GPIO operates in various modes depending on the user configuration:
- GPIO mode: In this mode the pin is programmed as a software controlled input or output by reading or writing to and from the corresponding data register. Both input data and output data can be digital low or digital high.
- Peripheral mode: In this mode the pin operates as an embedded peripheral. The microcontroller pin connects the peripheral through a multiplexer to only one alternate function at a time. The peripheral module must configure the pinmux to the corresponding pin before it is used. Two ways to apply pinmux configuration: call hal_pinmux_set_function() or configure the Easy pinmux tool (EPT), a software tool providing a graphical user interface for pinmux configuration. For more information about alternate functions of the pins, please refer to hal_pinmux_define.h.
- Call hal_pinmux_set_function() to set the pin mode and call hal_gpio_set_direction() to set the direction of GPIO. If the pin is in GPIO mode, call the hal_gpio_get_input() to get input data of the pin, and hal_gpio_set_output() to set data to output.
- Support toggle function.
The toggle function inverses output data of pins for every function call.
Call hal_gpio_toggle_pin() to toggle the output data of the target pin.
- Support pull-up and pull-down functions.
The pull-up and pull-down functions define the input state of a pin if no signal source is connected. Both the pull-up and pull-down functions are implemented using resistors. Set the pull state of the target pin by configuring the GPIO registers.
Call hal_gpio_pull_down() to set the pin to pull down state and hal_gpio_pull_up() to set the pin to pull up state.
- Support pull-up and pull-down with different resistance functions.
Pins can be configured to pull up or pull down state with different resistance, if needed.
Call hal_gpio_set_pupd_register() to set a pull state with corresponding resistance according to hardware design.
- Support inversion function.
Inversion function inverses input data of the GPIO until the function is disabled, it is useful when the chip is input high active while the connected device is output and low active.
Call hal_gpio_enable_inversion() to inverse the input data of the pin until the function is disabled by calling hal_gpio_disable_inversion().
- Support output clock function.
There are 6 clock-out ports embedded in all GPIO pins and each of them can be configured with appropriate clock frequency to send outside the chip.
Call hal_gpio_set_clockout() to set the output clock source of target pin after configuring the pin to operate in output clock mode.
Software architecture of GPIO
The GPIO driver supports two modes of operation as described below.
- GPIO mode architecture: If the pin is specified to operate in GPIO mode, it can be programmed in input and output directions. If the direction is configured as output through direction register, the data written to the output register will be output on the pin, the output data register is also accessible while an access to the output data register only gets the last written value. The output pin is push-pull type by default, push-pull output here means a type of electronic circuit that uses a pair of active devices that alternately supply current to, or absorb current from, a connected load. Push-pull outputs are present in TTL and CMOS digital logic circuits and in some types of amplifiers, and are usually implemented as a complementary pair of transistors, one dissipating or sinking current from the load to ground or a negative power supply, and the other supplying or sourcing current to the load from a positive power supply. If the direction is configured as input, the data present on the pin is received from an input data register. Unlike the output circuit, the Schmitt trigger and pull-up and pull-down resistors on the input circuit. Among them, Schmitt trigger is an active circuit which converts an analog input signal to a digital output signal. The pull-up and pull-down resistors help to set the target pin to the default voltage level (high or low) when the target pin is not connected to the external source.
- Peripheral mode architecture : The pins operate in one of several onboard peripheral modes based on multiplexer settings. It can only operate in one mode at a time to avoid conflict between peripherals sharing the same pin.
How to use this driver
Peripheral mode.
|
| hal_gpio_status_t | hal_gpio_init (hal_gpio_pin_t gpio_pin) |
| | This function initializes the GPIO hardware with basic functionality. More...
|
| |
| hal_gpio_status_t | hal_gpio_deinit (hal_gpio_pin_t gpio_pin) |
| | This function deinitializes the GPIO hardware to its default status. More...
|
| |
| hal_pinmux_status_t | hal_pinmux_set_function (hal_gpio_pin_t gpio_pin, uint8_t function_index) |
| | This function configures the pinmux of target GPIO. More...
|
| |
| hal_gpio_status_t | hal_gpio_get_input (hal_gpio_pin_t gpio_pin, hal_gpio_data_t *gpio_data) |
| | This function gets the input data of target GPIO when the direction of the GPIO is input. More...
|
| |
| hal_gpio_status_t | hal_gpio_set_output (hal_gpio_pin_t gpio_pin, hal_gpio_data_t gpio_data) |
| | This function sets the output data of the target GPIO. More...
|
| |
| hal_gpio_status_t | hal_gpio_get_output (hal_gpio_pin_t gpio_pin, hal_gpio_data_t *gpio_data) |
| | This function gets the output data of the target GPIO when the direction of the GPIO is output. More...
|
| |
| hal_gpio_status_t | hal_gpio_set_direction (hal_gpio_pin_t gpio_pin, hal_gpio_direction_t gpio_direction) |
| | This function sets the direction of the target GPIO. More...
|
| |
| hal_gpio_status_t | hal_gpio_get_direction (hal_gpio_pin_t gpio_pin, hal_gpio_direction_t *gpio_direction) |
| | This function gets the direction of the target GPIO. More...
|
| |
| hal_gpio_status_t | hal_gpio_set_high_impedance (hal_gpio_pin_t gpio_pin) |
| | This function sets the target GPIO to high impedance state. More...
|
| |
| hal_gpio_status_t | hal_gpio_clear_high_impedance (hal_gpio_pin_t gpio_pin) |
| | This function removes the high impedance state for the target GPIO. More...
|
| |
| hal_gpio_status_t | hal_gpio_toggle_pin (hal_gpio_pin_t gpio_pin) |
| | This function toggles the output data of the target GPIO when the direction of the pin is output. More...
|
| |
| hal_gpio_status_t | hal_gpio_enable_inversion (hal_gpio_pin_t gpio_pin) |
| | This function enables the input data inversion of the target GPIO, after this function, the input data of the target GPIO will always be inversed until the inverse function is disabled. More...
|
| |
| hal_gpio_status_t | hal_gpio_disable_inversion (hal_gpio_pin_t gpio_pin) |
| | This function disables the input data inversion of the target GPIO. More...
|
| |
| hal_gpio_status_t | hal_gpio_pull_up (hal_gpio_pin_t gpio_pin) |
| | This function sets the target GPIO to pull-up state, after this function, the input data of the target pin will be equivalent to high if the pin is disconnected. More...
|
| |
| hal_gpio_status_t | hal_gpio_pull_down (hal_gpio_pin_t gpio_pin) |
| | This function sets the target GPIO to the pull-down state, after this function, the input data of the target pin will be equivalent to low if the pin is disconnected. More...
|
| |
| hal_gpio_status_t | hal_gpio_disable_pull (hal_gpio_pin_t gpio_pin) |
| | This function disables pull-up or pull-down of the target GPIO. More...
|
| |
| hal_gpio_status_t | hal_gpio_set_pupd_register (hal_gpio_pin_t gpio_pin, uint8_t gpio_pupd, uint8_t gpio_r0, uint8_t gpio_r1) |
| | This function sets the pull up/down state of the GPIO that has more than one pull-up or pull-down resistor. More...
|
| |
| hal_gpio_status_t | hal_gpio_set_clockout (hal_gpio_clock_t gpio_clock_num, hal_gpio_clock_mode_t clock_mode) |
| | This function sets the clock-out source of the target GPIO. More...
|
| |
This function removes the high impedance state for the target GPIO.
High impedance can prevent the target GPIO from electric leakage. It is necessary to call this function before further configuration if the pin is in high impedance state.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to set. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
3 ret = hal_gpio_init(gpio_pin);
4 ret = hal_gpio_set_high_impedance(gpio_pin);
6 ret = hal_gpio_clear_high_impedance(gpio_pin); // Put the target GPIO out of high impedance state before other configuration.
7 ret = hal_gpio_deinit(gpio_pin);
This function deinitializes the GPIO hardware to its default status.
The target pin must be deinitialized if not used.
- Parameters
-
| [in] | gpio_pin | specifies pin number to deinitialize. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function disables the input data inversion of the target GPIO.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to configure. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
3 ret = hal_gpio_init(gpio_pin);
4 ret = hal_gpio_enable_inversion(gpio_pin);
6 ret = hal_gpio_disable_inversion(gpio_pin);
7 ret = hal_gpio_deinit(gpio_pin);
This function disables pull-up or pull-down of the target GPIO.
This function operates on the pins with one pull-up and one pull-down resistors.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to set. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
2 hal_pinmux_status_t ret_pinmux_status;
4 ret = hal_gpio_init(gpio_pin);
5 ret_pinmux_status = hal_pinmux_set_function(gpio_pin, function_index); // Set the pin to GPIO mode.
6 ret = hal_gpio_set_direction(gpio_pin, HAL_GPIO_DIRECTION_INPUT);
7 ret = hal_gpio_pull_down(gpio_pin);
8 ret = hal_gpio_disable_pull(gpio_pin); // Pull state of the target GPIO is disabled.
9 ret = hal_gpio_deinit(gpio_pin);
This function enables the input data inversion of the target GPIO, after this function, the input data of the target GPIO will always be inversed until the inverse function is disabled.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to inverse. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
3 ret = hal_gpio_init(gpio_pin);
4 ret = hal_gpio_enable_inversion(gpio_pin);
6 ret = hal_gpio_disable_inversion(gpio_pin);
7 ret = hal_gpio_deinit(gpio_pin);
This function gets the direction of the target GPIO.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to operate. |
| [in] | gpio_direction | is the direction of target GPIO, the direction can be input or output. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, a wrong parameter (except for pin number) is given, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function gets the input data of target GPIO when the direction of the GPIO is input.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to operate. |
| [in] | gpio_data | is the input data received from the target GPIO. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, a wrong parameter (except for pin number) is given, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function gets the output data of the target GPIO when the direction of the GPIO is output.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to operate. |
| [in] | gpio_data | is output data of the target GPIO. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, a wrong parameter (except for pin number) is given, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function initializes the GPIO hardware with basic functionality.
The target pin must be initialized before use.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to initialize. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function sets the target GPIO to the pull-down state, after this function, the input data of the target pin will be equivalent to low if the pin is disconnected.
This function operates on the pin with one pull-down resistor.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to set. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
2 hal_pinmux_status_t ret_pinmux_status;
4 ret = hal_gpio_init(gpio_pin);
5 ret_pinmux_status = hal_pinmux_set_function(gpio_pin, function_index); // Set the pin to GPIO mode.
6 ret = hal_gpio_set_direction(gpio_pin, HAL_GPIO_DIRECTION_INPUT);
7 ret = hal_gpio_pull_down(gpio_pin); // Pull state of the target GPIO is set to pull-down.
8 ret = hal_gpio_deinit(gpio_pin);
This function sets the target GPIO to pull-up state, after this function, the input data of the target pin will be equivalent to high if the pin is disconnected.
This function operates on the pins with only one pull-up resistor.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to set. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
2 hal_pinmux_status_t ret_pinmux_status;
4 ret = hal_gpio_init(gpio_pin);
5 ret_pinmux_status = hal_pinmux_set_function(gpio_pin, function_index); // Set the pin to GPIO mode.
6 ret = hal_gpio_set_direction(gpio_pin, HAL_GPIO_DIRECTION_INPUT);
7 ret = hal_gpio_pull_up(gpio_pin); // Pull state of the target GPIO is set to pull-up.
8 ret = hal_gpio_deinit(gpio_pin);
This function sets the clock-out source of the target GPIO.
The software can configure which clock to send outside the chip. There are 6 clock-out ports embedded in all GPIO pins, and each clock-out can be programmed to output appropriate clock source. This function can only be used after configuring the pin to operate in output clock mode.
- Parameters
-
| [in] | gpio_clock_num | specifies pin clock number to set. |
| [in] | clock_mode | specifies the clock mode to set to the target GPIO. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, a wrong parameter (except for pin number) is given, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
2 hal_pinmux_status_t ret_pinmux_status;
4 ret = hal_gpio_init(gpio_pin);
5 ret_pinmux_status = hal_pinmux_set_function(gpio_pin, function_index_of_clockout); // Set the pin to work in clock output mode
6 ret = hal_gpio_set_clockout(gpio_clock_num, clock_mode); // The clock-out frequency is defined in clock_mode and gpio_clock_num is determined by the previous step for a given pin number.
7 ret = hal_gpio_deinit(gpio_pin);
This function sets the direction of the target GPIO.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to set. |
| [in] | gpio_direction | is the direction of the target GPIO, the direction can be input or output. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, a wrong parameter (except for pin number) is given, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function sets the target GPIO to high impedance state.
High impedance can prevent the target GPIO from electric leakage. The pin in high impedance state acts as an open circuit, although it is connected to a low impedance circuit, it will not be affected. It is recommended to put the pin into high impedance state, if the pin is not in use to optimize the power consumption.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to set. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function sets the output data of the target GPIO.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to operate. |
| [in] | gpio_data | is the output data of the target GPIO. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, a wrong parameter (except for pin number) is given, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
This function sets the pull up/down state of the GPIO that has more than one pull-up or pull-down resistor.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to configure. |
| [in] | gpio_pupd | specifies the pull-up or pull-down of the target GPIO. |
| [in] | gpio_r0 | works with gpio_r1 to specify the pull-up and pull-down resistor of the target GPIO. |
| [in] | gpio_r1 | works with gpio_r0 to specify the pull-up and pull-down resistor of the target GPIO. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
2 hal_pinmux_status_t ret_pinmux_status;
4 ret = hal_gpio_init(gpio_pin);
5 ret_pinmux_status = hal_pinmux_set_function(gpio_pin, function_index); // Set the pin to GPIO mode.
6 ret = hal_gpio_set_direction(gpio_pin, HAL_GPIO_DIRECTION_INPUT);
7 ret = hal_gpio_set_pupd_register(gpio_pin,gpio_pupd,gpio_r0,gpio_r1); // Pull state of the target GPIO is set to a state determined by the combination of gpio_pupd,gpio_r0 and gpio_r1.
8 ret = hal_gpio_deinit(gpio_pin);
This function toggles the output data of the target GPIO when the direction of the pin is output.
After this function, the output data of the target GPIO will be inversed.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to toggle. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_GPIO_STATUS_OK, the operation completed successfully. If the return value is HAL_GPIO_STATUS_ERROR_PIN, invalid input pin number, the parameter must be verified. If the return value is HAL_GPIO_STATUS_ERROR, the operation failed.
- Note
- Warning
- Example
2 hal_pinmux_status_t ret_pinmux_status;
4 ret = hal_gpio_init(gpio_pin);
5 ret_pinmux_status = hal_pinmux_set_function(gpio_pin, function_index); // Set the pin to GPIO mode.
6 ret = hal_gpio_set_direction(gpio_pin, HAL_GPIO_DIRECTION_OUTPUT);
7 ret = hal_gpio_set_output(gpio_pin, HAL_GPIO_DATA_HIGH);
8 ret = hal_gpio_toggle_pin(gpio_pin); // Output data of gpio_pin will be toggled to low from high.
9 ret = hal_gpio_deinit(gpio_pin);
This function configures the pinmux of target GPIO.
Pin Multiplexer (pinmux) connects the pin and the onboard peripherals, so the pin will operate in a specific mode once the pin is programmed to a peripheral's function. The alternate functions of every pin are provided in hal_pinmux_define.h.
- Parameters
-
| [in] | gpio_pin | specifies the pin number to configure. |
| [in] | function_index | specifies the function for the pin. |
- Returns
- To indicate whether this function call is successful or not. If the return value is HAL_PINMUX_STATUS_OK, the operation completed successfully. If the return value is HAL_PINMUX_STATUS_INVALID_FUNCTION, a wrong alternate function is given, the parameter must be verified. If the return value is HAL_PINMUX_STATUS_ERROR_PORT, invalid input pin number, the parameter must be verified. If the return value is HAL_PINMUX_STATUS_ERROR, the operation failed.
- Note
- Warning
1.8.11 
