Dedicated GPIO¶

Overview¶

The dedicated GPIO is designed for CPU interaction with GPIO matrix and IO MUX. Any GPIO that is configured as “dedicated” can be access by CPU instructions directly, which makes it easy to achieve a high GPIO flip speed, and simulate serial/parallel interface in a bit-banging way. As toggling a GPIO in this “CPU Dedicated” way costs few overhead, it would be great for cases like performance measurement using an oscilloscope.

Create/Destroy GPIO Bundle¶

A GPIO bundle is a group of GPIOs, which can be manipulated at the same time in one CPU cycle. The maximal number of GPIOs that a bundle can contain is limited by each CPU. What’s more, the GPIO bundle has a strong relevance to the CPU which it derives from. Any operations on the GPIO bundle should be put inside a task which is running on the same CPU core to the GPIO bundle belongs to. Likewise, only those ISRs who are installed on the same CPU core are allowed to do operations on that GPIO bundle.

注解

Dedicated GPIO is more of a CPU peripheral, so it has a strong relationship with CPU core. It’s highly recommended to install and operate GPIO bundle in a pin-to-core task. For example, if GPIOA is connected to CPU0, and the dedicated GPIO instruction is issued from CPU1, then it’s impossible to control GPIOA.

To install a GPIO bundle, one needs to call dedic_gpio_new_bundle() to allocate the software resources and connect the dedicated channels to user selected GPIOs. Configurations for a GPIO bundle are covered in dedic_gpio_bundle_config_t structure:

gpio_array: An array that contains GPIO number.
array_size: Element number of gpio_array.
flags: Extra flags to control the behavior of GPIO Bundle.
- in_en and out_en are used to select whether to enable the input and output function (note, they can be enabled together).
- in_invert and out_invert are used to select whether to invert the GPIO signal.

The following code shows how to install a output only GPIO bundle:

// configure GPIO
const int bundleA_gpios[] = {0, 1};
gpio_config_t io_conf = {
    .mode = GPIO_MODE_OUTPUT,
};
for (int i = 0; i < sizeof(bundleA_gpios) / sizeof(bundleA_gpios[0]); i++) {
    io_conf.pin_bit_mask = 1ULL << bundleA_gpios[i];
    gpio_config(&io_conf);
}
// Create bundleA, output only
dedic_gpio_bundle_handle_t bundleA = NULL;
dedic_gpio_bundle_config_t bundleA_config = {
    .gpio_array = bundleA_gpios,
    .array_size = sizeof(bundleA_gpios) / sizeof(bundleA_gpios[0]),
    .flags = {
        .out_en = 1,
    },
};
ESP_ERROR_CHECK(dedic_gpio_new_bundle(&bundleA_config, &bundleA));

To uninstall the GPIO bundle, one needs to call dedic_gpio_del_bundle().

注解

dedic_gpio_new_bundle() doesn’t cover any GPIO pad configuration (e.g. pull up/down, drive ability, output/input enable), so before installing a dedicated GPIO bundle, you have to configure the GPIO separately using GPIO driver API (e.g. gpio_config()). For more information about GPIO driver, please refer to GPIO API Reference.

GPIO Bundle Operations¶

Operations	Functions
Write to GPIOs in the bundle by mask	`dedic_gpio_bundle_write()`
Read the value that input to bundle	`dedic_gpio_bundle_read_out()`
Read the value that output from bundle	`dedic_gpio_bundle_read_in()`

注解

The functions above just wrap the customized instructions defined for ESP32-S3, for the details of those instructions, please refer to ESP32-S3 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF].

Manipulate GPIOs by Writing Assembly Code¶

For advanced users, they can always manipulate the GPIOs by writing assembly code or invoking CPU Low Level APIs. The usual procedure could be:

Allocate a GPIO bundle: dedic_gpio_new_bundle()
Query the mask occupied by that bundle: dedic_gpio_get_out_mask() or/and dedic_gpio_get_in_mask()
Call CPU LL apis (e.g. cpu_ll_write_dedic_gpio_mask) or write assembly code with that mask
The fasted way of toggling IO is to use the dedicated “set/clear” instructions:

CPU Arch	Set bits of GPIO	Clear bits of GPIO	Remarks
Xtensa	set_bit_gpio_out imm[7:0]	clr_bit_gpio_out imm[7:0]	immediate value width depends on the number of dedicated GPIO channels
RISC-V	csrrsi rd, csr, imm[4:0]	csrrci rd, csr, imm[4:0]	can only control the lowest 4 GPIO channels

For details of supported dedicated GPIO instructions, please refer to ESP32-S3 Technical Reference Manual > IO MUX and GPIO Matrix (GPIO, IO_MUX) [PDF]. The supported dedicated CPU instructions are also wrapped inside soc/cpu_ll.h as helper inline functions.

注解

Writing assembly code in application could make your code hard to port between targets, because those customized instructions are not guaranteed to remain the same format on different targets.

Application Example¶

Matrix keyboard example based on dedicated GPIO: peripherals/gpio/matrix_keyboard.

API Reference¶

Header File¶

components/driver/include/driver/dedic_gpio.h

Functions¶

esp_err_t dedic_gpio_get_out_mask(dedic_gpio_bundle_handle_t bundle, uint32_t *mask)¶

Get allocated channel mask.

Return

ESP_OK: Get channel mask successfully
ESP_ERR_INVALID_ARG: Get channel mask failed because of invalid argument
ESP_FAIL: Get channel mask failed because of other error

Note

Each bundle should have at least one mask (in or/and out), based on bundle configuration.

Note

With the returned mask, user can directly invoke LL function like “cpu_ll_write_dedic_gpio_mask” or write assembly code with dedicated GPIO instructions, to get better performance on GPIO manipulation.

Parameters

[in] bundle: Handle of GPIO bundle that returned from “dedic_gpio_new_bundle”
[out] mask: Returned mask value for on specific direction (in or out)

esp_err_t dedic_gpio_get_in_mask(dedic_gpio_bundle_handle_t bundle, uint32_t *mask)¶

esp_err_t dedic_gpio_new_bundle(const dedic_gpio_bundle_config_t *config, dedic_gpio_bundle_handle_t *ret_bundle)¶

Create GPIO bundle and return the handle.

Return

ESP_OK: Create GPIO bundle successfully
ESP_ERR_INVALID_ARG: Create GPIO bundle failed because of invalid argument
ESP_ERR_NO_MEM: Create GPIO bundle failed because of no capable memory
ESP_ERR_NOT_FOUND: Create GPIO bundle failed because of no enough continuous dedicated channels
ESP_FAIL: Create GPIO bundle failed because of other error

Note

One has to enable at least input or output mode in “config” parameter.

Parameters

[in] config: Configuration of GPIO bundle
[out] ret_bundle: Returned handle of the new created GPIO bundle

esp_err_t dedic_gpio_del_bundle(dedic_gpio_bundle_handle_t bundle)¶

Destory GPIO bundle.

Return

ESP_OK: Destory GPIO bundle successfully
ESP_ERR_INVALID_ARG: Destory GPIO bundle failed because of invalid argument
ESP_FAIL: Destory GPIO bundle failed because of other error

Parameters

[in] bundle: Handle of GPIO bundle that returned from “dedic_gpio_new_bundle”

void dedic_gpio_bundle_write(dedic_gpio_bundle_handle_t bundle, uint32_t mask, uint32_t value)¶

Write value to GPIO bundle.

Note

The mask is seen from the view of GPIO bundle. For example, bundleA contains [GPIO10, GPIO12, GPIO17], to set GPIO17 individually, the mask should be 0x04.

Note

For performance reasons, this function doesn’t check the validity of any parameters, and is placed in IRAM.

Parameters

[in] bundle: Handle of GPIO bundle that returned from “dedic_gpio_new_bundle”
[in] mask: Mask of the GPIOs to be written in the given bundle
[in] value: Value to write to given GPIO bundle, low bit represents low member in the bundle

uint32_t dedic_gpio_bundle_read_out(dedic_gpio_bundle_handle_t bundle)¶

Read the value that output from the given GPIO bundle.

Return

Value that output from the GPIO bundle, low bit represents low member in the bundle

Note

For performance reasons, this function doesn’t check the validity of any parameters, and is placed in IRAM.

Parameters

[in] bundle: Handle of GPIO bundle that returned from “dedic_gpio_new_bundle”

uint32_t dedic_gpio_bundle_read_in(dedic_gpio_bundle_handle_t bundle)¶

Read the value that input to the given GPIO bundle.

Return

Value that input to the GPIO bundle, low bit represents low member in the bundle

Note

For performance reasons, this function doesn’t check the validity of any parameters, and is placed in IRAM.

Parameters

[in] bundle: Handle of GPIO bundle that returned from “dedic_gpio_new_bundle”

Structures¶

struct dedic_gpio_bundle_config_t¶

Type of Dedicated GPIO bundle configuration.

Public Members

const int *gpio_array¶: Array of GPIO numbers, gpio_array[0] ~ gpio_array[size-1] <=> low_dedic_channel_num ~ high_dedic_channel_num

size_t array_size¶: Number of GPIOs in gpio_array

unsigned int in_en : 1¶: Enable input

unsigned int in_invert : 1¶: Invert input signal

unsigned int out_en : 1¶: Enable output

unsigned int out_invert : 1¶: Invert output signal

struct dedic_gpio_bundle_config_t::[anonymous] flags¶: Flags to control specific behaviour of GPIO bundle

Type Definitions¶

typedef struct dedic_gpio_bundle_t *dedic_gpio_bundle_handle_t¶: Type of Dedicated GPIO bundle.

提供有关此文档的反馈