MT2523 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 check General Purpose Input Output in wiki .

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 freely programmable to input and output directions. If the direction is configured as output through programming direction register, the data written to the output register will be output on the pin, the output data register is also read accessible while a read 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 can be got from input data register. Unlike the output circuit, there are 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 can help the input data of target pin be equivalent to a default value if the pin is left unconnected.
  2. Peripheral mode architecture : Pins can operate in one of several specified peripheral modes as the pin is connected to onboard peripherals/modules through a multiplexer, in other words, it can only operate in one mode at a time to avoid conflict between peripherals sharing the same pin.

How to use this driver

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 is used to configure 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 is used to get 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 is used to set output data of 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 is used to get output data of target GPIO which is last set 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 is used to set direction of 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 is used to get direction of target GPIO. More...
 
hal_gpio_status_t hal_gpio_set_high_impedance (hal_gpio_pin_t gpio_pin)
 This function is used to set target GPIO to high impedance state. More...
 
hal_gpio_status_t hal_gpio_clear_high_impedance (hal_gpio_pin_t gpio_pin)
 This function is used to make target GPIO out of high impedance state. More...
 
hal_gpio_status_t hal_gpio_toggle_pin (hal_gpio_pin_t gpio_pin)
 This function is used to toggle output data of 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 is used to enable input data inverse of target GPIO, after this function, the input data of 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 is used to disable input data inverse of target GPIO. More...
 
hal_gpio_status_t hal_gpio_pull_up (hal_gpio_pin_t gpio_pin)
 This function is used to set target GPIO to pull-up state, after this function, the input data of target pin will be equivalent to high if the pin is left unconnected. More...
 
hal_gpio_status_t hal_gpio_pull_down (hal_gpio_pin_t gpio_pin)
 This function is used to set target GPIO to pull-down state, after this function, the input data of target pin will be equivalent to low if the pin is left unconnected. More...
 
hal_gpio_status_t hal_gpio_disable_pull (hal_gpio_pin_t gpio_pin)
 This function is used to disable pull-up or pull-down of 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 is used to set pull up/down state of GPIO who has more than one pull-up or pull-down resister. 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 is used to set clock out source of target GPIO. More...
 

Modules

 Enum
 

Function Documentation

hal_gpio_status_t hal_gpio_clear_high_impedance ( hal_gpio_pin_t  gpio_pin)

This function is used to make target GPIO out of high impedance state.

High impedance can prevent 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_pinspecifies pin number to set.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
Example
1 hal_gpio_status_t ret;
2 
3 ret = hal_gpio_init(gpio_pin);
4 ret = hal_gpio_set_high_impedance(gpio_pin);
5 // do something else
6 ret = hal_gpio_clear_high_impedance(gpio_pin); //put target GPIO out of high impedance state before other configuration
7 ret = hal_gpio_deinit(gpio_pin);
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 deinit.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
hal_gpio_status_t hal_gpio_disable_inversion ( hal_gpio_pin_t  gpio_pin)

This function is used to disable input data inverse of target GPIO.

Parameters
[in]gpio_pinspecifies pin number to config.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
Example
1 hal_gpio_status_t ret;
2 
3 ret = hal_gpio_init(gpio_pin);
4 ret = hal_gpio_enable_inversion(gpio_pin);
5 // do something else
6 ret = hal_gpio_disable_inversion(gpio_pin);
7 ret = hal_gpio_deinit(gpio_pin);
hal_gpio_status_t hal_gpio_disable_pull ( hal_gpio_pin_t  gpio_pin)

This function is used to disable pull-up or pull-down of target GPIO.

This function only works on the pin which has only one pull-up resister and one pull-down resister.

Parameters
[in]gpio_pinspecifies pin number to set.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
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 work in 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 set to disable
9 ret = hal_gpio_deinit(gpio_pin);
hal_gpio_status_t hal_gpio_enable_inversion ( hal_gpio_pin_t  gpio_pin)

This function is used to enable input data inverse of target GPIO, after this function, the input data of target GPIO will always be inversed until the inverse function is disabled.

Parameters
[in]gpio_pinspecifies pin number to inverse.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
Example
1 hal_gpio_status_t ret;
2 
3 ret = hal_gpio_init(gpio_pin);
4 ret = hal_gpio_enable_inversion(gpio_pin);
5 // do something else
6 ret = hal_gpio_disable_inversion(gpio_pin);
7 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 is used to get direction of target GPIO.

Parameters
[in]gpio_pinspecifies pin number to operate.
[in]gpio_directionrepresents direction of target GPIO, the direction can be input and output.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, it means a wrong parameter(except for pin number) is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
hal_gpio_status_t hal_gpio_get_input ( hal_gpio_pin_t  gpio_pin,
hal_gpio_data_t gpio_data 
)

This function is used to get input data of target GPIO when the direction of the GPIO is input.

Parameters
[in]gpio_pinspecifies pin number to operate.
[in]gpio_datarepresents input data received from target GPIO.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, it means a wrong parameter(except for pin number) is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
hal_gpio_status_t hal_gpio_get_output ( hal_gpio_pin_t  gpio_pin,
hal_gpio_data_t gpio_data 
)

This function is used to get output data of target GPIO which is last set when the direction of the GPIO is output.

Parameters
[in]gpio_pinspecifies pin number to operate.
[in]gpio_datarepresents output data of target GPIO.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, it means a wrong parameter(except for pin number) is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
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 used.

Parameters
[in]gpio_pinspecifies pin number to init.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
hal_gpio_status_t hal_gpio_pull_down ( hal_gpio_pin_t  gpio_pin)

This function is used to set target GPIO to pull-down state, after this function, the input data of target pin will be equivalent to low if the pin is left unconnected.

This function only works on the pin which has only one pull-down resister.

Parameters
[in]gpio_pinspecifies pin number to set.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
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 work in 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 is used to set target GPIO to pull-up state, after this function, the input data of target pin will be equivalent to high if the pin is left unconnected.

This function only works on the pin which has only one pull-up resister.

Parameters
[in]gpio_pinspecifies pin number to set.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
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 work in 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_clockout ( hal_gpio_clock_t  gpio_clock_num,
hal_gpio_clock_mode_t  clock_mode 
)

This function is used to set clock out source of target GPIO.

To facilitate application use, 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_numspecifies pin clock number to set.
[in]clock_modespecifies clock mode to set to target GPIO.
Returns
To indicate whether this function call is successful or not, for example If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, it means a wrong parameter(except for pin number) is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
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_of_clockout); // set the pin to work in clock output mode
6 ret = hal_gpio_set_clockout(gpio_clock_num, clock_mode); // the pin will output clock on the frequency decided by clock_mode, gpio_clock_num is determined by the previous step according to the pin number
7 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 is used to set direction of target GPIO.

Parameters
[in]gpio_pinspecifies pin number to set.
[in]gpio_directionspecified the direction of target GPIO, the direction can be input and output.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, it means a wrong parameter(except for pin number) is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
hal_gpio_status_t hal_gpio_set_high_impedance ( hal_gpio_pin_t  gpio_pin)

This function is used to set target GPIO to high impedance state.

High impedance can prevent target GPIO from electric leakage. The pin in high impedance state can be seen as an open circuit because connecting it to a low impedance circuit will not affect that circuit. It is adviced to put the pin into high impedance state if the pin is unused to optimize the power consumption.

Parameters
[in]gpio_pinspecifies pin number to set.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
hal_gpio_status_t hal_gpio_set_output ( hal_gpio_pin_t  gpio_pin,
hal_gpio_data_t  gpio_data 
)

This function is used to set output data of target GPIO.

Parameters
[in]gpio_pinspecifies pin number to operate.
[in]gpio_datarepresents output data of target GPIO.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_INVALID_PARAMETER, it means a wrong parameter(except for pin number) is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
Note
Warning
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 is used to set pull up/down state of GPIO who has more than one pull-up or pull-down resister.

Parameters
[in]gpio_pinspecifies pin number to configure.
[in]gpio_pupdspecifies pull-up or pull-down of target GPIO.
[in]gpio_r0works with gpio_r1 to specify pull resister of target GPIO.
[in]gpio_r1works with gpio_r0 to specify pull resister of target GPIO.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
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 work in 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 decided by combination of gpio_pupd,gpio_r0 and gpio_r1
8 ret = hal_gpio_deinit(gpio_pin);
hal_gpio_status_t hal_gpio_toggle_pin ( hal_gpio_pin_t  gpio_pin)

This function is used to toggle output data of target GPIO when the direction of the pin is output.

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

Parameters
[in]gpio_pinspecifies pin number to toggle.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_GPIO_STATUS_OK, it means success; If the return value is HAL_GPIO_STATUS_ERROR_PIN, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_GPIO_STATUS_ERROR, it means failure.
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 work in 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 is used to configure pinmux of target GPIO.

Pinmux represents Pin Multiplexor which 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. All the alternate functions of every pin can be seen from hal_pinmux_define.h.

Parameters
[in]gpio_pinspecifies pin number to configure.
[in]function_indexspecifies the function for the pin.
Returns
To indicate whether this function call is successful or not, for example: If the return value is HAL_PINMUX_STATUS_OK, it means success; If the return value is HAL_PINMUX_STATUS_INVALID_FUNCTION, it means a wrong alternate function is given, the parameter must be verified; If the return value is HAL_PINMUX_STATUS_ERROR_PORT, it means a wrong pin number is given, the parameter must be verified; If the return value is HAL_PINMUX_STATUS_ERROR, it means failure.
Note
Warning