MT7687 API Reference  LinkIt SDK v4
GPIO

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...

Overview

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

Software architecture of GPIO

The GPIO driver supports two modes of operation as described below.

  1. 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.
  2. 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.

Functions

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_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_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...
 

Modules

 Enum
 

Function Documentation

hal_gpio_status_t hal_gpio_deinit ( hal_gpio_pin_t  gpio_pin)

This function deinitializes the GPIO hardware to its default status.

The target pin must be deinitialized if not used.

Parameters
[in]gpio_pinspecifies 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
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.

This function operates on the pins with one pull-up and one pull-down resistors.

Parameters
[in]gpio_pinspecifies 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
1 hal_gpio_status_t ret;
2 hal_pinmux_status_t ret_pinmux_status;
3 
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);
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.

Parameters
[in]gpio_pinspecifies the pin number to operate.
[in]gpio_directionis 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
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.

Parameters
[in]gpio_pinspecifies the pin number to operate.
[in]gpio_datais 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
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.

Parameters
[in]gpio_pinspecifies the pin number to operate.
[in]gpio_datais 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
hal_gpio_status_t hal_gpio_init ( hal_gpio_pin_t  gpio_pin)

This function initializes the GPIO hardware with basic functionality.

The target pin must be initialized before use.

Parameters
[in]gpio_pinspecifies 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
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.

This function operates on the pin with one pull-down resistor.

Parameters
[in]gpio_pinspecifies 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
1 hal_gpio_status_t ret;
2 hal_pinmux_status_t ret_pinmux_status;
3 
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);
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.

This function operates on the pins with only one pull-up resistor.

Parameters
[in]gpio_pinspecifies 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
1 hal_gpio_status_t ret;
2 hal_pinmux_status_t ret_pinmux_status;
3 
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);
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.

Parameters
[in]gpio_pinspecifies the pin number to set.
[in]gpio_directionis 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
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.

Parameters
[in]gpio_pinspecifies the pin number to operate.
[in]gpio_datais 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
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.

After this function, the output data of the target GPIO will be inversed.

Parameters
[in]gpio_pinspecifies 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
1 hal_gpio_status_t ret;
2 hal_pinmux_status_t ret_pinmux_status;
3 
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);
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.

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_pinspecifies the pin number to configure.
[in]function_indexspecifies 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