diff --git a/cpu/esp32/include/periph_cpu.h b/cpu/esp32/include/periph_cpu.h index b98bef3584..eb6c3e80f5 100644 --- a/cpu/esp32/include/periph_cpu.h +++ b/cpu/esp32/include/periph_cpu.h @@ -11,7 +11,7 @@ * @{ * * @file - * @brief CPU specific definitions and functions for peripheral handling + * @brief Peripheral configuration that is common for all ESP32x SoCs * * @author Gunar Schorcht */ @@ -144,112 +144,77 @@ typedef enum { #endif /* ndef DOXYGEN */ /** @} */ -/** - * @name Predefined GPIO names - * @{ - */ -#define GPIO0 (GPIO_PIN(PORT_GPIO,0)) -#define GPIO1 (GPIO_PIN(PORT_GPIO,1)) -#define GPIO2 (GPIO_PIN(PORT_GPIO,2)) -#define GPIO3 (GPIO_PIN(PORT_GPIO,3)) -#define GPIO4 (GPIO_PIN(PORT_GPIO,4)) -#define GPIO5 (GPIO_PIN(PORT_GPIO,5)) -#define GPIO6 (GPIO_PIN(PORT_GPIO,6)) -#define GPIO7 (GPIO_PIN(PORT_GPIO,7)) -#define GPIO8 (GPIO_PIN(PORT_GPIO,8)) -#define GPIO9 (GPIO_PIN(PORT_GPIO,9)) -#define GPIO10 (GPIO_PIN(PORT_GPIO,10)) -#define GPIO11 (GPIO_PIN(PORT_GPIO,11)) -#define GPIO12 (GPIO_PIN(PORT_GPIO,12)) -#define GPIO13 (GPIO_PIN(PORT_GPIO,13)) -#define GPIO14 (GPIO_PIN(PORT_GPIO,14)) -#define GPIO15 (GPIO_PIN(PORT_GPIO,15)) -#define GPIO16 (GPIO_PIN(PORT_GPIO,16)) -#define GPIO17 (GPIO_PIN(PORT_GPIO,17)) -#define GPIO18 (GPIO_PIN(PORT_GPIO,18)) -#define GPIO19 (GPIO_PIN(PORT_GPIO,19)) -/* GPIO 20 is not available */ -#define GPIO21 (GPIO_PIN(PORT_GPIO,21)) -#define GPIO22 (GPIO_PIN(PORT_GPIO,22)) -#define GPIO23 (GPIO_PIN(PORT_GPIO,23)) -/* GPIO 24 is not available */ -#define GPIO25 (GPIO_PIN(PORT_GPIO,25)) -#define GPIO26 (GPIO_PIN(PORT_GPIO,26)) -#define GPIO27 (GPIO_PIN(PORT_GPIO,27)) -/* GPIOs 28 ...32 are not available */ -#define GPIO32 (GPIO_PIN(PORT_GPIO,32)) -#define GPIO33 (GPIO_PIN(PORT_GPIO,33)) -/* GPIOs 34 ... 39 can only be used as inputs and do not have pullups/pulldowns */ -#define GPIO34 (GPIO_PIN(PORT_GPIO,34)) -#define GPIO35 (GPIO_PIN(PORT_GPIO,35)) -#define GPIO36 (GPIO_PIN(PORT_GPIO,36)) -#define GPIO37 (GPIO_PIN(PORT_GPIO,37)) -#define GPIO38 (GPIO_PIN(PORT_GPIO,38)) -#define GPIO39 (GPIO_PIN(PORT_GPIO,39)) -/** @} */ - /** * @name ADC configuration * - * ESP32 integrates two 12-bit ADCs (ADC1 and ADC2) capable of measuring up to - * 18 analog signals in total. Most of these ADC channels are either connected - * to a number of integrated sensors like a Hall sensors, touch sensors and a - * temperature sensor or can be connected with certain GPIOs. Integrated - * sensors are disabled in RIOT's implementation and are not accessible. Thus, - * up to 18 GPIOs, the RTC GPIOs, can be used as ADC inputs: + * ESP32x SoCs integrate two SAR ADCs (ADC1 and ADC2). The bit width of the + * ADC devices, the number of channels per device and the GPIOs that can be + * used as ADC channels depend on the respective ESP32x SoC family. For + * details, see: * - * - ADC1 supports 8 channels: GPIO 32-39 - * - ADC2 supports 10 channels: GPIO 0, 2, 4, 12-15, 25-27 + * - \ref esp32_adc_channels_esp32 "ESP32" * - * For each ADC line, an attenuation of the input signal can be defined - * separately unsing function *adc_set_attenuation*, see file - * ```$RIOTBASE/cpu/esp32/include/adc_arch.h```. - * This results in different full ranges of the measurable voltage - * at the input. The attenuation can be set to 0 dB, 3 dB, 6 dB and 11 dB, - * with 11 dB being the standard attenuation. Since an ADC input is measured - * against a reference voltage Vref of 1.1 V, approximately the following - * measurement ranges are given when using a corresponding attenuation: + * #ADC_GPIOS in the board-specific peripheral configuration defines the + * list of GPIOs that can be used as ADC channels on the board, for example: + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * #define ADC_GPIOS { GPIO0, GPIO2, GPIO4 } + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * Thereby the order of the listed GPIOs determines the mapping between the + * ADC lines of the RIOT and the GPIOs. The maximum number of GPIOs in the + * list is #ADC_NUMOF_MAX. The board specific configuration of #ADC_GPIOS + * can be overridden by [Application specific configurations] + * (#esp32_application_specific_configurations). + * + * The number of defined ADC channels #ADC_NUMOF is determined automatically + * from the #ADC_GPIOS definition. + * + * @note As long as the GPIOs listed in #ADC_GPIOS are not initialized as ADC + * channels with the #adc_init function, they can be used for other + * purposes. + * + * With the function #adc_set_attenuation an attenuation of the input signal + * can be defined separately for each ADC channel. + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * extern int adc_set_attenuation(adc_t line, adc_attenuation_t atten); + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * This leads to different measurable maximum values for the voltage at the input. + * The higher the attenuation is, the higher the voltage measured at the input + * can be. + * + * The attenuation can be set to 4 fixed values 0 dB, 2.5/3 dB, 6 dB and + * 11/12 dB, where 11 dB respectively 12 dB is the default attenuation. * *
* - * Attenuation | Voltage Range | Symbol - * ----------------|-------------------|---------------------- - * 0 dB | 0 ... 1.1V (Vref) | ADC_ATTENUATION_0_DB - * 3 dB | 0 ... 1.5V | ADC_ATTENUATION_3_DB - * 6 dB | 0 ... 2.2V | ADC_ATTENUATION_6_DB - * 11 dB (default) | 0 ... 3.3V | ADC_ATTENUATION_11_DB + * Attenuation | Voltage Range | Symbol + * -----------:|-------------------|--------------------------- + * 0 dB | 0 ... 1.1V (Vref) | `ADC_ATTEN_DB_0` + * 2.5 / 3 dB | 0 ... 1.5V | `ADC_ATTEN_DB_2_5` + * 6 dB | 0 ... 2.2V | `ADC_ATTEN_DB_6` + * 11 / 12 dB | 0 ... 3.3V | `ADC_ATTEN_DB_11` (default) * - *
+ *
* - * Please note: The reference voltage Vref can vary from device to device in - * the range of 1.0V and 1.2V. The Vref of a device can be read with the - * function *adc_vref_to_gpio25* at the pin GPIO 25, see file - * ```$RIOTBASE/cpu/esp32/include/adc_arch.h```. The results of the ADC - * input can then be adjusted accordingly. + * @note The reference voltage Vref can vary from device to device in the range + * of 1.0V and 1.2V. * - * ADC_GPIOS in the board-specific peripheral configuration defines a list of - * GPIOs that can be used as ADC channels. The order of the listed GPIOs - * determines the mapping between the RIOT's ADC lines and the GPIOs. + * The Vref of a device can be read at a predefined GPIO with the function + * #adc_line_vref_to_gpio. The results of the ADC input can then be adjusted + * accordingly. + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * extern int adc_line_vref_to_gpio(adc_t line, gpio_t gpio); + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * For the GPIO that can be used with this function, see: * - * @note ADC_GPIOS must be defined even if there are no GPIOs that could be - * used as ADC channels on the board. In this case, an empty list hast to be - * defined which just contains the curly braces. - * - * ADC_NUMOF is determined automatically from the ADC_GPIOS definition. - * - * @note As long as the GPIOs listed in ADC_GPIOS are not initialized - * as ADC channels with the *adc_init* function, they can be used for other - * purposes. + * - \ref esp32_adc_channels_esp32 "ESP32" * * @{ */ /** * @brief Number of ADC channels that could be used at maximum - * - * @note GPIO37 and GPIO38 are usually not broken out on ESP32 modules and are - * therefore not usable. The maximum number of ADC channels (ADC_NUMOF_MAX) - * is therefore set to 16. */ #define ADC_NUMOF_MAX (SOC_ADC_CHANNEL_NUM(0) + SOC_ADC_CHANNEL_NUM(1)) @@ -258,54 +223,90 @@ typedef enum { /** * @name DAC configuration * - * ESP32 supports 2 DAC lines at GPIO25 and GPIO26. These DACs have a width of - * 8 bits and produce voltages in the range from 0 V to 3.3 V (VDD_A). The 16 - * bits DAC values given as parameter of function *dac_set* are down-scaled - * to 8 bit. + * Some ESP32x SoCs support 2 DAC lines at predefined GPIOs, depending on the + * respective ESP32x SoC family. These DACs have a width of 8 bits and produce + * voltages in the range from 0 V to 3.3 V (VDD_A). The 16 bit DAC values + * given as parameter of function #dac_set are down-scaled to 8 bit. * - * DAC_GPIOS in the board-specific peripheral configuration defines a list of - * GPIOs that can be used as DAC channels. The order of the listed GPIOs - * determines the mapping between the RIOT's DAC lines and the GPIOs. + * The GPIOs that can be used as DAC channels for a given board are defined by + * the `#DAC_GPIOS` macro in the board-specific peripheral configuration. + * The specified GPIOs in the list must match the predefined GPIOs that can be + * used as DAC channels on the respective ESP32x SoC. * - * @note DAC_GPIOS must be defined even if there are no GPIOs that could be - * used as DAC channels on the board. In this case, an empty list hast to be - * defined which just contains the curly braces. + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * #define DAC_GPIOS { GPIO25, GPIO26 } + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * - * DAC_NUMOF is determined automatically from the DAC_GPIOS definition. + * This configuration can be changed by [application-specific configurations] + * (#esp32_application_specific_configurations). * - * @note As long as the GPIOs listed in DAC_GPIOS are not initialized - * as DAC channels with the *dac_init* function, they can be used for other + * The order of the listed GPIOs determines the mapping between the RIOT's + * DAC lines and the GPIOs. The maximum number of GPIOs in the list is + * #DAC_NUMOF_MAX. + * + * #DAC_NUMOF is determined automatically from the #DAC_GPIOS definition. + * + * @note As long as the GPIOs listed in #DAC_GPIOS are not initialized + * as DAC channels with the #dac_init function, they can be used for other * purposes. + * + * DACs are currently only supported for the \ref esp32_dac_channels_esp32 + * "ESP32 SoC" variant. + * * @{ */ /** * @brief Number of DAC channels that could be used at maximum. */ +#if defined(SOC_DAC_SUPPORTED) || DOXYGEN #define DAC_NUMOF_MAX (SOC_DAC_PERIPH_NUM) +#endif /** @} */ /** * @name I2C configuration * - * ESP32 has two built-in I2C interfaces. + * ESP32x SoCs integrate up to two I2C hardware interfaces. * * The board-specific configuration of the I2C interface I2C_DEV(n) requires * the definition of * - * I2Cn_SPEED, the bus speed, - * I2Cn_SCL, the GPIO used as SCL signal, and - * I2Cn_SDA, the GPIO used as SDA signal, + * `I2Cn_SPEED`, the bus speed for I2C_DEV(n), + * `I2Cn_SCL`, the GPIO used as SCL signal for I2C_DEV(n), and + * `I2Cn_SDA`, the GPIO used as SDA signal for I2C_DEV(n), * - * where n can be 0 or 1. If they are not defined, the I2C interface - * I2C_DEV(n) is not used. + * where `n` can be 0 or 1. If they are not defined, the I2C interface + * I2C_DEV(n) is not used, for example: + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * #define I2C0_SPEED I2C_SPEED_FAST + * #define I2C0_SCL GPIO22 + * #define I2C0_SDA GPIO21 * - * @note The configuration of the I2C interfaces I2C_DEV(n) must be in - * continuous ascending order of n. + * #define I2C1_SPEED I2C_SPEED_NORMAL + * #define I2C1_SCL GPIO13 + * #define I2C1_SDA GPIO16 + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * - * I2C_NUMOF is determined automatically from board-specific peripheral - * definitions of I2Cn_SPEED, I2Cn_SCK, and I2Cn_SDA. + * The board-specific pin configuration of I2C interfaces can be changed by + * [application specific configurations](#esp32_application_specific_configurations) + * by overriding the according `I2Cn_*` symbols. + * + * @note + * - To ensure that the `I2Cn_*` symbols define the configuration for + * I2C_DEV(n), the definition of the configuration of I2C interfaces + * I2C_DEV(n) must be in continuous ascending order of `n`. + * That is, if I2C_DEV(1) is used by defining the `I2C1_*` symbols, + * I2C_DEV(0) must also be used by defining the `I2C0_*` symbols. + * - The GPIOs listed in the configuration are only initialized as I2C + * signals when the `periph_i2c` module is used. Otherwise they are not + * allocated and can be used for other purposes. + * - The same configuration is used when the I2C bit-banging software + * implementation is used by enabling module `esp_i2c_sw` (default). + * + * The number of used I2C interfaces #I2C_NUMOF is determined automatically + * from board-specific peripheral definitions of I2C_DEV(n). * * @{ */ @@ -345,33 +346,53 @@ typedef struct { */ #define I2C_NUMOF_MAX (SOC_I2C_NUM) -#define PERIPH_I2C_NEED_READ_REG /**< i2c_read_reg required */ -#define PERIPH_I2C_NEED_READ_REGS /**< i2c_read_regs required */ -#define PERIPH_I2C_NEED_WRITE_REG /**< i2c_write_reg required */ -#define PERIPH_I2C_NEED_WRITE_REGS /**< i2c_write_regs required */ +#define PERIPH_I2C_NEED_READ_REG /**< Implementation requires #i2c_read_reg */ +#define PERIPH_I2C_NEED_READ_REGS /**< Implementation requires #i2c_read_regs */ +#define PERIPH_I2C_NEED_WRITE_REG /**< Implementation requires #i2c_write_reg */ +#define PERIPH_I2C_NEED_WRITE_REGS /**< Implementation requires #i2c_write_regs */ /** @} */ /** * @name PWM configuration * - * The implementation of the PWM peripheral driver uses the LED PWM Controller - * (LEDC) module of the ESP32x SoC. This LEDC module has one or two channel - * groups with 6 or 8 channels each. The channels of each channel group can - * use one of 4 timers as clock source. Thus, it is possible to define at - * 4 or 8 virtual PWM devices in RIOT with different frequencies and - * resolutions. Regardless of whether the LEDC module of the ESP32x SoC has - * one or two channel groups, the PWM driver implementation allows to organize - * the available channels into up to 4 virtual PWM devices. + * The PWM peripheral driver for ESP32x SoCs uses the LED PWM Controller (LEDC) + * module for implementation. The LEDC module has either 1 or 2 channel groups + * with 6 or 8 channels each, where the first channel group comprises the + * low-speed channels and the second channel group comprises the high-speed + * channels. The difference is that changes in the configuration of the + * high-speed channels take effect with the next PWM cycle, while the changes + * in the configuration of the low-speed channels must be explicitly updated + * by a trigger. + * + * The low-speed channel group always exists while the existence of the + * high-speed channel group depends on respective ESP32x SoC family. + * + * Each channel group has 4 timers which can be used as clock source by the + * channels of the respective channel group. Thus it would be possible to + * define a maximum of 4 virtual PWM devices in RIOT per channel group with + * different frequencies and resolutions. However, regardless of whether the + * LEDC module of the ESP32x SoC has one or two channel groups, the PWM driver + * implementation only allows the available channels to be organized into + * up to 4 virtual PWM devices. * * The assignment of the available channels to the virtual PWM devices is * done in the board-specific peripheral configuration by defining the * macros `PWM0_GPIOS`, `PWM1_GPIOS`, `PWM2_GPIOS` and `PWM3_GPIOS` These - * macros specify the GPIOs that are used as channels for the available - * virtual PWM devices PWM_DEV(0) ... PWM_DEV(3) in RIOT. The mapping of - * these channels to the available channel groups and channel group timers - * is done by the driver automatically as follows. + * macros specify the GPIOs that are used as channels for the 4 possible + * virtual PWM devices PWM_DEV(0) ... PWM_DEV(3) in RIOT, for example: + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * #define PWM0_GPIOS { GPIO0, GPIO2, GPIO4, GPIO16, GPIO17 } + * #define PWM1_GPIOS { GPIO27, GPIO32, GPIO33 } + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * This configuration can be changed by [application-specific configurations] + * (#esp32_application_specific_configurations). + * + * The mapping of the GPIOs as channels of the available channel groups and + * channel group timers is organized by the driver automatically as follows: * *
+ * * Macro | 1 Channel Group | 2 Channel Groups | Timer * -------------|-----------------------|------------------------|--------------- * `PWM0_GPIOS` | `LEDC_LOW_SPEED_MODE` | `LEDC_LOW_SPEED_MODE` | `LEDC_TIMER_0` @@ -380,20 +401,23 @@ typedef struct { * `PWM3_GPIOS` | `LEDC_LOW_SPEED_MODE` | `LEDC_HIGH_SPEED_MODE` | `LEDC_TIMER_3` * *
+ * * For example, if the LEDC module of the ESP32x SoC has two channel groups, - * two virtual PWM devices with 2 x 6/8 channels could be used by defining - * 'PWM0_GPIOS' and 'PWM1_GPIOS' with 6/8 GPIOs each. + * two virtual PWM devices with 2 x 6 (or 8) channels could be used by defining + * 'PWM0_GPIOS' and 'PWM1_GPIOS' with 6 (or 8) GPIOs each. + * + * The number of used PWM devices #PWM_NUMOF is determined automatically from the + * definition of `PWM0_GPIOS`, `PWM1_GPIOS`, `PWM2_GPIOS` and `PWM3_GPIOS`. * * @note * - The total number of channels defined for a channel group must not exceed - * #PWM_CH_NUMOF_MAX. + * #PWM_CH_NUMOF_MAX * - The definition of `PWM0_GPIOS`, `PWM1_GPIOS`, `PWM2_GPIOS` and - * `PWM3_GPIOS` can be omitted. In this case the existing macros should - * be defined in ascending order, as the first defined macro is assigned - * to PWM_DEV(0), the second defined macro is assigned to PWM_DEV(1) - * and so on. So the minimal configuration would define all channels by - * `PWM0_GPIOS` as PWM_DEV(0). - * - #PWM_NUMOF is determined automatically. + * `PWM3_GPIOS` can be omitted. However, to ensure that `PWMn_GPIOS` defines + * the configuration for PWM_DEV(n), the PWM channels must be defined in + * continuous ascending order from `n`. That means, if `PWM1_GPIOS` is + * defined, `PWM0_GPIOS` must be defined before, and so on. So a minimal + * configuration would define all channels by `PWM0_GPIOS` as PWM_DEV(0). * - The order of the GPIOs in these macros determines the mapping between * RIOT's PWM channels and the GPIOs. * - As long as the GPIOs listed in `PWM0_GPIOS`, `PWM1_GPIOS`, @@ -472,17 +496,26 @@ typedef struct { /** * @name SPI configuration * - * ESP32 has four SPI controllers: + * ESP32x SoCs have up to four SPI controllers dependent on the specific ESP32x + * SoC variant (family): * - * - controller SPI0 is reserved for caching the flash memory (CPSI) - * - controller SPI1 is reserved for external memories like flash and PSRAM (FSPI) - * - controller SPI2 realizes interface HSPI that can be used for peripherals - * - controller SPI3 realizes interface VSPI that can be used for peripherals + * - Controller SPI0 is reserved for caching external memory like Flash + * - Controller SPI1 is reserved for external memories like PSRAM + * - Controller SPI2 can be used as general purpose SPI (GPSPI) + * - Controller SPI3 can be used as general purpose SPI (GPSPI) * - * Thus, a maximum of two SPI controllers can be used as peripheral interfaces: + * The controllers SPI0 and SPI1 share the same bus signals and can only + * operate in memory mode on most ESP32x SoC variants. Therefore, depending on + * the specific ESP32x SoC family, a maximum of two SPI controllers can be used + * as peripheral interfaces: * - * - VSPI - * - HSPI + * - Controller SPI2 is identified by `SPI2_HOST` (also called FSPI or HSPI) + * - Controller SPI3 is identified by `SPI3_HOST` (also called VSPI) + * + * In former ESP-IDF versions, SPI interfaces were identified by the alias + * names `FSPI`, `HSPI` and `VSPI`, which are sometimes also used in data + * sheets. These alias names have been declared obsolete in ESP-IDF. For + * source code compatibility reasons these alias names are defined here. * * SPI interfaces could be used in quad SPI mode, but RIOT's low level * device driver doesn't support it. @@ -490,18 +523,47 @@ typedef struct { * The board-specific configuration of the SPI interface SPI_DEV(n) requires * the definition of * - * - SPIn_CTRL, the SPI controller which is used for the interface (VSPI or HSPI), - * - SPIn_SCK, the GPIO used as clock signal - * - SPIn_MISO, the GPIO used as MISO signal - * - SPIn_MOSI, the GPIO used as MOSI signal, and - * - SPIn_CS0, the GPIO used as CS signal when the cs parameter in spi_aquire - * is GPIO_UNDEF, + * - `SPIn_CTRL`, the SPI controller (`SPI_HOST2`/`SPI_HOST3`) used for SPI_DEV(n), + * - `SPIn_SCK`, the GPIO used as clock signal used for SPI_DEV(n) + * - `SPIn_MISO`, the GPIO used as MISO signal used for SPI_DEV(n) + * - `SPIn_MOSI`, the GPIO used as MOSI signal used for SPI_DEV(n), and + * - `SPIn_CS0`, the GPIO used as CS signal for SPI_DEV(n) when the `cs` + * parameter in #spi_acquire is #GPIO_UNDEF, * - * where n can be 0 or 1. If they are not defined, the according SPI interface - * SPI_DEV(n) is not used. + * where `n` can be 0 and 1. If they are not defined, the according SPI + * interface SPI_DEV(n) is not used, for example: + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * #define SPI0_CTRL SPI3_HOST // VSPI could also be used on ESP32 variant + * #define SPI0_SCK GPIO18 // SCK signal + * #define SPI0_MISO GPIO19 // MISO signal + * #define SPI0_MOSI GPIO23 // MOSI signal + * #define SPI0_CS0 GPIO5 // CS0 signal * - * SPI_NUMOF is determined automatically from the board-specific peripheral - * definitions of SPIn_*. + * #define SPI1_CTRL SPI2_HOST // HSPI could also be used here on ESP32 variant + * #define SPI1_SCK GPIO14 // SCK Camera + * #define SPI1_MISO GPIO12 // MISO Camera + * #define SPI1_MOSI GPIO13 // MOSI Camera + * #define SPI1_CS0 GPIO15 // CS0 Camera + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * The pin configuration of SPI interfaces can be changed by + * [application specific configurations](#esp32_application_specific_configurations) + * by overriding the according `SPIn_*` symbols. + * + * @note + * - To ensure that the `SPIn_*` symbols define the configuration for + * SPI_DEV(n), the definition of the configuration of SPI interfaces + * SPI_DEV(n) must be in continuous ascending order of `n`. + * That is, if SPI_DEV(1) is used by defining the `SPI1_*` symbols, + * SPI_DEV(0) must also be used by defining the `SPI0_*` symbols. + * - The order in which the available interfaces `SPI2_HOST` (alias `HSPI` or + * `FSP`) and `SPI3_HOST` (alias `HSPI`) are assigned doesn't matter. + * - The GPIOs listed in the configuration are only initialized as SPI + * signals when the `periph_spi` module is used. Otherwise they are not + * allocated and can be used for other purposes. + * + * #SPI_NUMOF is determined automatically from the board-specific peripheral + * configuration for SPI_DEV(n). * * @{ */ @@ -523,12 +585,19 @@ typedef enum { #endif /* !DOXYGEN */ /** - * @brief SPI controllers that can be used for peripheral interfaces + * @brief Mapping of SPI controller type for source code compatibility */ -typedef enum { - HSPI = HSPI_HOST, /**< HSPI interface controller */ - VSPI = VSPI_HOST, /**< VSPI interface controller */ -} spi_ctrl_t; +typedef spi_host_device_t spi_ctrl_t; + +/* + * In former ESP-IDF versions, SPI interfaces were identified by the alias + * names `FSPI`, `HSPI` and `VSPI`, which are sometimes also used in data + * sheets. These alias names have been declared obsolete in ESP-IDF. For + * source code compatibility reasons these alias names are defined here. + */ +#define HSPI SPI2_HOST /**< Alias name for SPI2_HOST as used in former ESP-IDF versions */ +#define FSPI SPI2_HOST /**< Alias name for SPI2_HOST as used in former ESP-IDF versions */ +#define VSPI SPI3_HOST /**< Alias name for SPI3_HOST as used in former ESP-IDF versions */ /** * @brief SPI configuration structure type @@ -554,16 +623,29 @@ typedef struct { /** * @name Timer configuration depending on which implementation is used * - * Timers are MCU built-in feature and not board-specific. They are therefore - * configured here. + * There are two different implementations for hardware timers. + * + * - **Timer Module implementation** Depending on the ESP32x SoC variant + * (family) it provides up to 4 high speed timers, where 1 timer is used for + * system time. The remaining timer devices with **1 channel** each can be + * used as RIOT timer devices with a clock rate of 1 MHz. + * - **Counter implementation** Dependent on the ESP32x SoC variant (family), + * the MCU has up to 3 CCOMPARE (cycle compare) registers. Two of them can be + * used to implement up to **2 timer devices** with **1 channel** each and a + * clock rate of 1 MHz. This is a feature of Xtensa-based ESP32x SoC variants. + * + * By default, the timer module is used. To use the counter implementation, add + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * USEMODULE += esp_hw_counter + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * to application's makefile. + * + * Timers are MCU built-in features and not board-specific. There is nothing to + * be configured. * @{ */ -#ifdef MODULE_ESP_HW_COUNTER -/** Hardware ccount/ccompare registers are used for timer implementation */ -#define TIMER_NUMOF (2) -#define TIMER_CHANNEL_NUMOF (1) -#else +#ifndef MODULE_ESP_HW_COUNTER /** * @brief Hardware timer modules are used for timer implementation (default) * @@ -591,24 +673,41 @@ typedef struct { /** * @name UART configuration * - * ESP32 supports up to three UART devices. UART_DEV(0) has a fixed pin - * configuration and is always available. All ESP32 boards use it as standard - * configuration for the console. + * ESP32x SoCs integrate up to three UART devices, depending on the specific + * ESP32x SoC variant (family). * - * UART_DEV(0).TXD GPIO1 - * UART_DEV(0).RXD GPIO3 + * The pin configuration of the UART device UART_DEV(n) is defined in the + * board-specific peripheral configuration by * - * The pin configuration of UART_DEV(1) and UART_DEV(2) are defined in - * board specific peripheral configuration by + * - `UARTn_TXD`, the GPIO used as TxD signal for UART_DEV(n), and + * - `UARTn_RXD`, the GPIO used as RxD signal for UART_DEV(n), * - * - UARTn_TXD, the GPIO used as TxD signal, and - * - UARTn_RXD, the GPIO used as RxD signal, + * where `n` can be in range of 0 and UART_NUMOF_MAX-1. If they are not defined, + * the according UART interface UART_DEV(n) is not used, for example: + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c} + * #define UART1_TX GPIO10 // TxD signal of UART_DEV(1) + * #define UART1_RX GPIO9 // RxD signal of UART_DEV(1) + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * - * where n can be 1 or 2. If they are not defined, the according UART interface - * UART_DEV(n) is not used. + * The pin configuration of UART interfaces can be changed by + * [application specific configurations](#esp32_application_specific_configurations) + * by overriding the according `UARTn_*` symbols. * - * UART_NUMOF is determined automatically from the board-specific peripheral - * definitions of UARTn_*. + * @note To ensure that the `UARTn_*` symbols define the configuration for + * UART_DEV(n), the configuration of the UART interfaces UART_DEV(n) + * must be in continuous ascending order of `n`. That is, if UART_DEV(1) + * is to be used by defining the `UART1_*` symbols, UART_DEV(0) must also + * be used by defining the `UART0_*` symbols, and if UART_DEV(2) + * is to be used by defining the `UART2_*` symbols, UART_DEV(0) and + * UART_DEV(1) must also be used by defining the `UART0_*` and + * `UART1_*` symbols + * + * #UART_NUMOF is determined automatically from the board-specific peripheral + * configuration for UART_DEV(n). + * + * UART_DEV(0) has usually a fixed pin configuration that is used by all + * ESP32x boards as standard configuration for the console. The GPIOs + * used for UART_DEV(0) depend on the ESP32x SoC family. * * @{ */ @@ -627,13 +726,22 @@ typedef struct { #define UART_NUMOF_MAX (SOC_UART_NUM) /** @} */ -#ifdef MODULE_PERIPH_CAN -#include "can_esp.h" -#endif - #ifdef __cplusplus } #endif +/** + * @brief Include ESP32x family specific peripheral configuration + */ +#if defined(CPU_FAM_ESP32) +#include "periph_cpu_esp32.h" +#else +#error "ESP32x family implementation missing" +#endif + +#ifdef MODULE_PERIPH_CAN +#include "can_esp.h" +#endif + #endif /* PERIPH_CPU_H */ /** @} */ diff --git a/cpu/esp32/include/periph_cpu_esp32.h b/cpu/esp32/include/periph_cpu_esp32.h new file mode 100644 index 0000000000..e89e59cafa --- /dev/null +++ b/cpu/esp32/include/periph_cpu_esp32.h @@ -0,0 +1,240 @@ +/* + * Copyright (C) 2022 Gunar Schorcht + * + * This file is subject to the terms and conditions of the GNU Lesser + * General Public License v2.1. See the file LICENSE in the top level + * directory for more details. + */ + +/** + * @ingroup cpu_esp32 + * @{ + * + * @file + * @brief ESP32 specific peripheral configuration + * + * @author Gunar Schorcht + */ + +#ifndef PERIPH_CPU_ESP32_H +#define PERIPH_CPU_ESP32_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @name Predefined GPIO names + * @{ + */ +#define GPIO0 (GPIO_PIN(PORT_GPIO,0)) +#define GPIO1 (GPIO_PIN(PORT_GPIO,1)) +#define GPIO2 (GPIO_PIN(PORT_GPIO,2)) +#define GPIO3 (GPIO_PIN(PORT_GPIO,3)) +#define GPIO4 (GPIO_PIN(PORT_GPIO,4)) +#define GPIO5 (GPIO_PIN(PORT_GPIO,5)) +#define GPIO6 (GPIO_PIN(PORT_GPIO,6)) +#define GPIO7 (GPIO_PIN(PORT_GPIO,7)) +#define GPIO8 (GPIO_PIN(PORT_GPIO,8)) +#define GPIO9 (GPIO_PIN(PORT_GPIO,9)) +#define GPIO10 (GPIO_PIN(PORT_GPIO,10)) +#define GPIO11 (GPIO_PIN(PORT_GPIO,11)) +#define GPIO12 (GPIO_PIN(PORT_GPIO,12)) +#define GPIO13 (GPIO_PIN(PORT_GPIO,13)) +#define GPIO14 (GPIO_PIN(PORT_GPIO,14)) +#define GPIO15 (GPIO_PIN(PORT_GPIO,15)) +#define GPIO16 (GPIO_PIN(PORT_GPIO,16)) +#define GPIO17 (GPIO_PIN(PORT_GPIO,17)) +#define GPIO18 (GPIO_PIN(PORT_GPIO,18)) +#define GPIO19 (GPIO_PIN(PORT_GPIO,19)) +/* GPIO 20 is not available */ +#define GPIO21 (GPIO_PIN(PORT_GPIO,21)) +#define GPIO22 (GPIO_PIN(PORT_GPIO,22)) +#define GPIO23 (GPIO_PIN(PORT_GPIO,23)) +/* GPIO 24 is not available */ +#define GPIO25 (GPIO_PIN(PORT_GPIO,25)) +#define GPIO26 (GPIO_PIN(PORT_GPIO,26)) +#define GPIO27 (GPIO_PIN(PORT_GPIO,27)) +/* GPIOs 28 ...32 are not available */ +#define GPIO32 (GPIO_PIN(PORT_GPIO,32)) +#define GPIO33 (GPIO_PIN(PORT_GPIO,33)) +/* GPIOs 34 ... 39 can only be used as inputs and do not have pullups/pulldowns */ +#define GPIO34 (GPIO_PIN(PORT_GPIO,34)) +#define GPIO35 (GPIO_PIN(PORT_GPIO,35)) +#define GPIO36 (GPIO_PIN(PORT_GPIO,36)) +#define GPIO37 (GPIO_PIN(PORT_GPIO,37)) +#define GPIO38 (GPIO_PIN(PORT_GPIO,38)) +#define GPIO39 (GPIO_PIN(PORT_GPIO,39)) +/** @} */ + +/** + * @name ADC configuration + * + * ESP32 integrates two 12-bit ADCs (ADC1 and ADC2) with 18 channels in total: + * + * - **ADC1** supports 8 channels: GPIOs 32-39 + * - **ADC2** supports 10 channels: GPIOs 0, 2, 4, 12-15, 25-27 + * + * Most of these ADC channels are either connected to a number of integrated + * sensors like a Hall sensors, touch sensors and a temperature sensor or can + * be connected with certain GPIOs. Integrated sensors are disabled in RIOT's + * implementation and are not accessible. Thus, up to 18 GPIOs can be used as + * ADC channels: + * + * @note + * - GPIO37 and GPIO38 are usually not broken out on ESP32 boards and can not + * be used therefore. + * - ADC2 is also used by the WiFi module. The GPIOs connected to ADC2 are + * therefore not available as ADC channels if the modules `esp_wifi` or + * `esp_now` are used. + * - Vref can be read with function #adc_line_vref_to_gpio at GPIO25. + */ + +/** @} */ + +/** + * @name DAC configuration + * + * ESP32 supports 2 DAC lines at GPIO25 and GPIO26. + */ + +/** + * @name I2C configuration + * + * ESP32 has two built-in I2C interfaces. + * + * The following table shows the default configuration of I2C interfaces + * used for a large number of ESP32 boards. It can be overridden by + * [application-specific configurations](#esp32_application_specific_configurations). + * + *
+ * + * Device | Signal | Pin | Symbol | Remarks + * :----------|:-------|:-------|:--------------|:---------------- + * I2C_DEV(0) | | | `#I2C0_SPEED` | default is `I2C_SPEED_FAST` + * I2C_DEV(0) | SCL | GPIO22 | `#I2C0_SCL` | - + * I2C_DEV(0) | SDA | GPIO21 | `#I2C0_SDA` | - + * + *

+ */ + +/** + * @name PWM configuration + * + * The ESP32 LEDC module has 2 channel groups with 8 channels each. Each of + * these channels can be clocked by one of the 4 timers. + */ + +/** + * @name SPI configuration + * + * ESP32 has four SPI controllers where SPI0 and SPI1 share the same bus and + * are used as interface for external memory: + * + * - Controller SPI0 is reserved for caching external memory like Flash + * - Controller SPI1 is reserved for external memoriy like PSRAM + * - Controller SPI2 can be used as general purpose SPI (also called HSPI) + * - Controller SPI3 can be used as general purpose SPI (also called VSPI) + * + * Thus, only SPI2 (HSPI) and SPI3 (VSPI) can be used as general purpose SPI + * in RIOT as SPI_DEV(0) and SPI_DEV(1) in arbitrary order. + * + * The following table shows the pin configuration used for most boards, even + * though it **can vary** from board to board. + * + *
+ * + * Device |Signal| Pin | Symbol | Remarks + * :-----------------------|:----:|:-------|:-----------:|:--------------------------- + * `SPI_HOST0`/`SPI_HOST1` | SCK | GPIO6 |- | reserved for flash and PSRAM + * `SPI_HOST0`/`SPI_HOST1` | CMD | GPIO11 |- | reserved for flash and PSRAM + * `SPI_HOST0`/`SPI_HOST1` | SD0 | GPIO7 |- | reserved for flash and PSRAM + * `SPI_HOST0`/`SPI_HOST1` | SD1 | GPIO8 |- | reserved for flash and PSRAM + * `SPI_HOST0`/`SPI_HOST1` | SD2 | GPIO9 |- | reserved for flash and PSRAM (only in `qio` or `qout` mode) + * `SPI_HOST0`/`SPI_HOST1` | SD3 | GPIO10 |- | reserved for flash and PSRAM (only in `qio` or `qout` mode) + * `SPI_HOST2` (`HSPI`) | SCK | GPIO14 |`#SPI1_SCK` | can be used + * `SPI_HOST2` (`HSPI`) | MISO | GPIO12 |`#SPI1_MISO` | can be used + * `SPI_HOST2` (`HSPI`) | MOSI | GPIO13 |`#SPI1_MOSI` | can be used + * `SPI_HOST2` (`HSPI`) | CS0 | GPIO15 |`#SPI1_CS0` | can be used + * `SPI_HOST3` (`VSPI`) | SCK | GPIO18 |`#SPI0_SCK` | can be used + * `SPI_HOST3` (`VSPI`) | MISO | GPIO19 |`#SPI0_MISO` | can be used + * `SPI_HOST3` (`VSPI`) | MOSI | GPIO23 |`#SPI0_MOSI` | can be used + * `SPI_HOST3` (`VSPI`) | CS0 | GPIO18 |`#SPI0_CS0` | can be used + * + *

+ * + * Some boards use the `HSPI` (`SPI_HOST2`) as SD-Card interface (SDIO) in 4-bit SD mode. + * + *
+ * + * Device|Pin | SD 4-bit mode | SPI mode + * :---------------------|:------:|:-------------:|:----------: + * `SPI_HOST2` (`HSPI`) | GPIO14 | CLK | SCK + * `SPI_HOST2` (`HSPI`) | GPIO15 | CMD | CS0 + * `SPI_HOST2` (`HSPI`) | GPIO2 | DAT0 | MISO + * `SPI_HOST2` (`HSPI`) | GPIO4 | DAT1 | - + * `SPI_HOST2` (`HSPI`) | GPIO12 | DAT2 | - + * `SPI_HOST2` (`HSPI`) | GPIO13 | DAT3 | MOSI + * + *

+ * + * @note On these boards, all these signals are pulled up. This may cause + * flashing problems due to the bootstrap function of the GPIO2 pin, + * see section [GPIO pins](#esp32_gpio_pins_esp32). Therefore, it can + * be necessary to either press the **Boot** button, to remove the SD card + * or to remove the peripheral hardware to flash RIOT. + */ + +/** + * @name Timer configuration depending on which implementation is used + * + * Timers are MCU built-in feature and not board-specific. They are therefore + * configured here. + * + * ESP32 has two timer groups with two timers each, resulting in a total of + * four timers. Since one timer is used as system timer, up to three timers + * with one channel each can be used in RIOT as timer devices + * TIMER_DEV(0) ... TIMER_DEV(2). + * + * Additionally ESP32 has three CCOMPARE registers which can be used + * alternatively as timer devices TIMER_DEV(0) ... TIMER_DEV(2) can be used + * in RIOT if the module `esp_hw_counter` is enabled. + * + * @{ + */ + +#ifdef MODULE_ESP_HW_COUNTER +/** Hardware ccount/ccompare registers are used for timer implementation */ +#define TIMER_NUMOF (2) +#define TIMER_CHANNEL_NUMOF (1) +#endif + +/** + * @name UART configuration + * + * ESP32 integrates three UART interfaces. The following default pin + * configuration of UART interfaces as used by a most boards can be overridden + * by the application, see section [Application-Specific Configurations] + * (#esp32_application_specific_configurations). + * + *
+ * + * Device |Signal|Pin |Symbol |Remarks + * :-----------|:-----|:-------|:-----------|:---------------- + * UART_DEV(0) | TxD | GPIO1 |`#UART0_TXD`| cannot be changed + * UART_DEV(0) | RxD | GPIO3 |`#UART0_RXD`| cannot be changed + * UART_DEV(1) | TxD | GPIO10 |`#UART1_TXD`| optional, can be overridden + * UART_DEV(1) | RxD | GPIO9 |`#UART1_RXD`| optional, can be overridden + * UART_DEV(2) | TxD | - |`UART2_TXD` | optional, can be overridden + * UART_DEV(2) | RxD | - |`UART2_RXD` | optional, can be overridden + * + *

+ * + */ + +#ifdef __cplusplus +} +#endif + +#endif /* PERIPH_CPU_ESP32_H */ +/** @} */ diff --git a/dist/tools/doccheck/exclude_patterns b/dist/tools/doccheck/exclude_patterns index 5553caeff2..19855e3185 100644 --- a/dist/tools/doccheck/exclude_patterns +++ b/dist/tools/doccheck/exclude_patterns @@ -14965,3 +14965,4 @@ pkg/nimble/autoadv/include/nimble_autoadv_params\.h:[0-9]+: warning: Member NIMB pkg/nimble/autoadv/include/nimble_autoadv_params\.h:[0-9]+: warning: Member NIMBLE_AUTOADV_OWN_ADDR_TYPE \(macro definition\) of file nimble_autoadv_params\.h is not documented\. pkg/nimble/autoadv/include/nimble_autoadv_params\.h:[0-9]+: warning: Member NIMBLE_AUTOADV_FILTER_POLICY \(macro definition\) of file nimble_autoadv_params\.h is not documented\. pkg/nimble/autoadv/include/nimble_autoadv_params\.h:[0-9]+: warning: Member NIMBLE_AUTOADV_PARAMS \(macro definition\) of file nimble_autoadv_params\.h is not documented\. +cpu/esp32/include/periph_cpu_esp32\.h:[0-9]+: warning: Member GPIO[0-9]+ \(macro definition\) of file periph_cpu_esp32\.h is not documented.