gpio_matrix_in and gpio_matrix_out documentation is incorrect for esp32c3 (IDFGH-10490)

[colincross]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

General issue report

The documentation for gpio_matrix_out states:

  * @param uint32_t signal_idx : signal index.
  *                        signal_idx == 0x100, cancel output put to the gpio

The parameter passed here is written directly to the GPIO_FUNCn_OUT_SEL_CFG_REG register, which according to the ESP32-C3 TRM:

If a value 128 is written to this field, bit n of GPIO_OUT_REG and GPIO_ENABLE_REG will be selected as the output value and output enable. (R/W)

The 0x100 value is correct for ESP32, but not for ESP32-C3. The same problem is also present in the ESP32-C6 copy of the file. Calling gpio_matrix_out(pin, 0x100, 0, 0) on ESP32-C3 results in connecting the output pin to signal 0, the SPIQ_out peripheral, with the GPIO_FUNCn_OUT_INV_SEL bit set.

Similarly, the documentation for gpio_matrix_in states:

  * @param uint32_t gpio : gpio number, 0~0x2f
  *                        gpio == 0x3C, input 0 to signal
  *                        gpio == 0x3A, input nothing to signal
  *                        gpio == 0x38, input 1 to signal

but the TRM entry for GPIO_FUNCn_IN_SEL_CFG_REG says:

Or selects 0x1e for a constantly high input or 0x1f for a constantly low input.

Fixing the documentation would help, but even better would be to provide #define entries for these constants so that the same code can be used on multiple ESP32 platforms without having to #ifdef each supported platform, and update the list of #ifdefs each time a new ESP32 platform is released.

[suda-morris]

@colincross The GPIO_MATRIX_CONST_ONE_INPUT and GPIO_MATRIX_CONST_ZERO_INPUT defined in the soc/gpio_pins.h are what you want.

[suda-morris]

Calling gpio_matrix_out(pin, 0x100, 0, 0) on ESP32-C3 results in connecting the output pin to signal 0

why? doesn't this mean to connect the signal whose ID is 0x100 to the GPIO with the number of pin? and signal 0x100 is SIG_GPIO_OUT_IDX, which means the normal GPIO output signal.

[colincross]

SIG_GPIO_OUT_IDX is 128 on ESP32-C3 (see https://github.com/espressif/esp-idf/blob/master/components/soc/esp32c3/include/soc/gpio_sig_map.h#L176), not 256 like on other platforms. The GPIO_FUNCn_OUT_SEL field on ESP32-C3 is only 8 bits wide, so writing 0x100 to it sets GPIO_FUNCn_OUT_SEL=0x00 and GPIO_FUNCn_OUT_INV_SEL=1.

Thanks for the pointers to SIG_GPIO_OUT_IDX, GPIO_MATRIX_CONST_ONE_INPUT, and GPIO_MATRIX_CONST_ZERO_INPUT, those are exactly the values needed, so the only problem is that the gpio_matrix_in and gpio_matrix_out documentation refers to incorrect hardcoded values and should instead refer to those macros.

[suda-morris]

Thanks for the explanation. BTW, you can switch to using the APIs provided by esp_rom_gpio.h, which one is treated as stable and public APIs across all targets, including the API documentation there.

[colincross]

I also found GPIO_FUNC_IN_HIGH and GPIO_FUNC_IN_LOW in rom/gpio.h, which have the correct values for all platforms except for esp32c3, where they are 0x38 and 0x3C when they should be 0x1e and 0x1f: https://github.com/espressif/esp-idf/blob/master/components/esp_rom/include/esp32c3/rom/gpio.h#L31

[JBKingdon]

@colincross Just wanted to say thank you for opening this issue. I think this may explain something that drove me nuts for weeks :)

[huster-songtao]

#define FASTLED_INTERNAL                             //  Otherwise FastLED shows compile messages
#include <FastLEDHub.h>

#define NUM_LEDS 100
#define LED_TYPE WS2812B
#define LIGHTSTRIP_PIN 5

CRGB leds[NUM_LEDS];

void setup()
{
  FastLEDHub.initialize("Project Name");
  FastLEDHub.addLeds<LED_TYPE, LIGHTSTRIP_PIN, GRB>(leds, NUM_LEDS);
}

void loop()
{
  FastLEDHub.handle();
}

d:\Arduino\Sketchbook\libraries\FastLED\src\platforms\esp\32\clockless_rmt_esp32.cpp: In member function 'void ESP32RMTController::startOnChannel(int)':
d:\Arduino\Sketchbook\libraries\FastLED\src\platforms\esp\32\clockless_rmt_esp32.cpp:266:29: error: 'RMTMEM' was not declared in this scope
266 | mRMT_mem_start = & (RMTMEM.chan[mRMT_channel].data32[0].val);
| ^~~~~~
d:\Arduino\Sketchbook\libraries\FastLED\src\platforms\esp\32\clockless_rmt_esp32.cpp: In static member function 'static void ESP32RMTController::doneOnChannel(rmt_channel_t, void*)':
d:\Arduino\Sketchbook\libraries\FastLED\src\platforms\esp\32\clockless_rmt_esp32.cpp:347:5: error: 'gpio_matrix_out' was not declared in this scope; did you mean 'gpio_iomux_out'?
347 | gpio_matrix_out(pController->mPin, 0x100, 0, 0);
| ^~~~~~~~~~~~~~~
| gpio_iomux_out

exit status 1

Compilation error: exit status 1

https://user-images.githubusercontent.com/94954133/281659178-4d72d9af-ab59-4087-a02d-a1741ad86c8b.png