Skip to content

Commit

Permalink
Merge branch 'feature/c6_ulp_gpio' into 'master'
Browse files Browse the repository at this point in the history
ulp: added gpio API for lp core

Closes IDF-6834

See merge request espressif/esp-idf!23766
  • Loading branch information
ESP-Marius committed Jun 1, 2023
2 parents 9f4a296 + dacc51d commit 9f31c65
Show file tree
Hide file tree
Showing 82 changed files with 484 additions and 59 deletions.
155 changes: 155 additions & 0 deletions components/ulp/lp_core/lp_core/include/ulp_lp_core_gpio.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
/*
* SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/

#pragma once

#ifdef __cplusplus
extern "C" {
#endif

#include "hal/gpio_types.h"
#include "hal/rtc_io_ll.h"

typedef enum {
LP_IO_NUM_0 = 0, /*!< GPIO0, input and output */
LP_IO_NUM_1 = 1, /*!< GPIO1, input and output */
LP_IO_NUM_2 = 2, /*!< GPIO2, input and output */
LP_IO_NUM_3 = 3, /*!< GPIO3, input and output */
LP_IO_NUM_4 = 4, /*!< GPIO4, input and output */
LP_IO_NUM_5 = 5, /*!< GPIO5, input and output */
LP_IO_NUM_6 = 6, /*!< GPIO6, input and output */
LP_IO_NUM_7 = 7, /*!< GPIO7, input and output */
} lp_io_num_t;

/**
* @brief Initialize a rtcio pin
*
* @param lp_io_num The rtc io pin to initialize
*/
static inline void ulp_lp_core_gpio_init(lp_io_num_t lp_io_num)
{
rtcio_ll_function_select(lp_io_num, RTCIO_FUNC_RTC);
}

/**
* @brief Enable output
*
* @param lp_io_num The rtc io pin to enable output for
*/
static inline void ulp_lp_core_gpio_output_enable(lp_io_num_t lp_io_num)
{
rtcio_ll_output_enable(lp_io_num);
}

/**
* @brief Disable output
*
* @param lp_io_num The rtc io pin to disable output for
*/
static inline void ulp_lp_core_gpio_output_disable(lp_io_num_t lp_io_num)
{
rtcio_ll_output_disable(lp_io_num);
}

/**
* @brief Enable input
*
* @param lp_io_num The rtc io pin to enable input for
*/
static inline void ulp_lp_core_gpio_input_enable(lp_io_num_t lp_io_num)
{
rtcio_ll_input_enable(lp_io_num);
}

/**
* @brief Disable input
*
* @param lp_io_num The rtc io pin to disable input for
*/
static inline void ulp_lp_core_gpio_input_disable(lp_io_num_t lp_io_num)
{
rtcio_ll_input_disable(lp_io_num);
}

/**
* @brief Set rtcio output level
*
* @param lp_io_num The rtc io pin to set the output level for
* @param level 0: output low; 1: output high.
*/
static inline void ulp_lp_core_gpio_set_level(lp_io_num_t lp_io_num, uint8_t level)
{
rtcio_ll_set_level(lp_io_num, level);
}

/**
* @brief Get rtcio output level
*
* @param lp_io_num The rtc io pin to get the output level for
*/
static inline uint32_t ulp_lp_core_gpio_get_level(lp_io_num_t lp_io_num)
{
return rtcio_ll_get_level(lp_io_num);
}

/**
* @brief Set rtcio output mode
*
* @param lp_io_num The rtc io pin to set the output mode for
* @param mode RTCIO_OUTPUT_NORMAL: normal, RTCIO_OUTPUT_OD: open drain
*/
static inline void ulp_lp_core_gpio_set_output_mode(lp_io_num_t lp_io_num, rtcio_ll_out_mode_t mode)
{
rtcio_ll_output_mode_set(lp_io_num, mode);
}

/**
* @brief Enable internal pull-up resistor
*
* @param lp_io_num The rtc io pin to enable pull-up for
*/
static inline void ulp_lp_core_gpio_pullup_enable(lp_io_num_t lp_io_num)
{
/* Enable internal weak pull-up */
rtcio_ll_pullup_enable(lp_io_num);
}

/**
* @brief Disable internal pull-up resistor
*
* @param lp_io_num The rtc io pin to disable pull-up for
*/
static inline void ulp_lp_core_gpio_pullup_disable(lp_io_num_t lp_io_num)
{
/* Disable internal weak pull-up */
rtcio_ll_pullup_disable(lp_io_num);
}

/**
* @brief Enable internal pull-down resistor
*
* @param lp_io_num The rtc io pin to enable pull-down for
*/
static inline void ulp_lp_core_gpio_pulldown_enable(lp_io_num_t lp_io_num)
{
/* Enable internal weak pull-down */
rtcio_ll_pulldown_enable(lp_io_num);
}

/**
* @brief Disable internal pull-down resistor
*
* @param lp_io_num The rtc io pin to disable pull-down for
*/
static inline void ulp_lp_core_gpio_pulldown_disable(lp_io_num_t lp_io_num)
{
/* Enable internal weak pull-down */
rtcio_ll_pulldown_disable(lp_io_num);
}

#ifdef __cplusplus
}
#endif
2 changes: 2 additions & 0 deletions components/ulp/test_apps/lp_core/main/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ set(app_sources "test_app_main.c" "test_lp_core.c")
set(lp_core_sources "lp_core/test_main.c")
set(lp_core_sources_counter "lp_core/test_main_counter.c")
set(lp_core_sources_set_timer_wakeup "lp_core/test_main_set_timer_wakeup.c")
set(lp_core_sources_gpio "lp_core/test_main_gpio.c")

idf_component_register(SRCS ${app_sources}
INCLUDE_DIRS "lp_core"
Expand All @@ -12,3 +13,4 @@ set(lp_core_exp_dep_srcs ${app_sources})
ulp_embed_binary(lp_core_test_app "${lp_core_sources}" "${lp_core_exp_dep_srcs}")
ulp_embed_binary(lp_core_test_app_counter "${lp_core_sources_counter}" "${lp_core_exp_dep_srcs}")
ulp_embed_binary(lp_core_test_app_set_timer_wakeup "${lp_core_sources_set_timer_wakeup}" "${lp_core_exp_dep_srcs}")
ulp_embed_binary(lp_core_test_app_gpio "${lp_core_sources_gpio}" "${lp_core_exp_dep_srcs}")
35 changes: 35 additions & 0 deletions components/ulp/test_apps/lp_core/main/lp_core/test_main_gpio.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
/*
* SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/

#include <stdint.h>
#include <stdbool.h>
#include "ulp_lp_core_utils.h"
#include "ulp_lp_core_gpio.h"

volatile uint32_t gpio_test_finished;
volatile uint32_t gpio_test_succeeded;


int main (void)
{
ulp_lp_core_gpio_init(LP_IO_NUM_0);

ulp_lp_core_gpio_input_enable(LP_IO_NUM_0);
ulp_lp_core_gpio_output_enable(LP_IO_NUM_0);

ulp_lp_core_gpio_set_level(LP_IO_NUM_0, 0);
gpio_test_succeeded = (ulp_lp_core_gpio_get_level(LP_IO_NUM_0) == 0);

ulp_lp_core_gpio_set_level(LP_IO_NUM_0, 1);
gpio_test_succeeded &= (ulp_lp_core_gpio_get_level(LP_IO_NUM_0) == 1);

ulp_lp_core_gpio_set_level(LP_IO_NUM_0, 0);
gpio_test_succeeded &= (ulp_lp_core_gpio_get_level(LP_IO_NUM_0) == 0);

gpio_test_finished = 1;

return 0;
}
20 changes: 20 additions & 0 deletions components/ulp/test_apps/lp_core/main/test_lp_core.c
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
#include "lp_core_test_app.h"
#include "lp_core_test_app_counter.h"
#include "lp_core_test_app_set_timer_wakeup.h"
#include "lp_core_test_app_gpio.h"
#include "ulp_lp_core.h"
#include "ulp_lp_core_lp_timer_shared.h"
#include "test_shared.h"
Expand All @@ -28,6 +29,9 @@ extern const uint8_t lp_core_main_counter_bin_end[] asm("_binary_lp_core_test_
extern const uint8_t lp_core_main_set_timer_wakeup_bin_start[] asm("_binary_lp_core_test_app_set_timer_wakeup_bin_start");
extern const uint8_t lp_core_main_set_timer_wakeup_bin_end[] asm("_binary_lp_core_test_app_set_timer_wakeup_bin_end");

extern const uint8_t lp_core_main_gpio_bin_start[] asm("_binary_lp_core_test_app_gpio_bin_start");
extern const uint8_t lp_core_main_gpio_bin_end[] asm("_binary_lp_core_test_app_gpio_bin_end");

static void load_and_start_lp_core_firmware(ulp_lp_core_cfg_t* cfg, const uint8_t* firmware_start, const uint8_t* firmware_end)
{
TEST_ASSERT(ulp_lp_core_load_binary(firmware_start,
Expand Down Expand Up @@ -284,3 +288,19 @@ TEST_CASE("LP core can schedule next wake-up time by itself", "[ulp]")

TEST_ASSERT_INT_WITHIN_MESSAGE(5, expected_run_count, ulp_set_timer_wakeup_counter, "LP Core did not wake up the expected number of times");
}

TEST_CASE("LP core gpio tests", "[ulp]")
{
/* Load ULP firmware and start the coprocessor */
ulp_lp_core_cfg_t cfg = {
.wakeup_source = ULP_LP_CORE_WAKEUP_SOURCE_LP_TIMER,
.lp_timer_sleep_duration_us = LP_TIMER_TEST_SLEEP_DURATION_US,
};

load_and_start_lp_core_firmware(&cfg, lp_core_main_gpio_bin_start, lp_core_main_gpio_bin_end);

while(!ulp_gpio_test_finished) {
}

TEST_ASSERT_TRUE(ulp_gpio_test_succeeded);
}
10 changes: 5 additions & 5 deletions docs/en/api-reference/system/ulp-risc-v.rst
Original file line number Diff line number Diff line change
Expand Up @@ -191,17 +191,17 @@ Keeping this in mind, here are some ways that may help you debug you ULP RISC-V

* Share program state through shared variables: as described in :ref:`ulp-riscv-access-variables`, both the main CPU and the ULP core can easily access global variables in RTC memory. Writing state information to such a variable from the ULP and reading it from the main CPU can help you discern what is happening on the ULP core. The downside of this approach is that it requires the main CPU to be awake, which will not always be the case. Keeping the main CPU awake might even, in some cases, mask problems, as some issues may only occur when certain power domains are powered down.

* Use the bit-banged UART driver to print: the ULP RISC-V component comes with a low-speed bit-banged UART TX driver that can be used for printing information independently of the main CPU state. See :example:`system/ulp_riscv/uart_print` for an example of how to use this driver.
* Use the bit-banged UART driver to print: the ULP RISC-V component comes with a low-speed bit-banged UART TX driver that can be used for printing information independently of the main CPU state. See :example:`system/ulp/ulp_riscv/uart_print` for an example of how to use this driver.

* Trap signal: the ULP RISC-V has a hardware trap that will trigger under certain conditions, e.g., illegal instruction. This will cause the main CPU to be woken up with the wake-up cause :cpp:enumerator:`ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG`.

Application Examples
--------------------

* ULP RISC-V Coprocessor polls GPIO while main CPU is in deep sleep: :example:`system/ulp_riscv/gpio`.
* ULP RISC-V Coprocessor uses bit-banged UART driver to print: :example:`system/ulp_riscv/uart_print`.
* ULP RISC-V Coprocessor reads external temperature sensor while main CPU is in deep sleep: :example:`system/ulp_riscv/ds18b20_onewire`.
* ULP RISC-V Coprocessor reads external I2C temperature and humidity sensor (BMP180) while the main CPU is in Deep-sleep and wakes up the main CPU once a threshold is met: :example:`system/ulp_riscv/i2c`.
* ULP RISC-V Coprocessor polls GPIO while main CPU is in deep sleep: :example:`system/ulp/ulp_riscv/gpio`.
* ULP RISC-V Coprocessor uses bit-banged UART driver to print: :example:`system/ulp/ulp_riscv/uart_print`.
* ULP RISC-V Coprocessor reads external temperature sensor while main CPU is in deep sleep: :example:`system/ulp/ulp_riscv/ds18b20_onewire`.
* ULP RISC-V Coprocessor reads external I2C temperature and humidity sensor (BMP180) while the main CPU is in Deep-sleep and wakes up the main CPU once a threshold is met: :example:`system/ulp/ulp_riscv/i2c`.

API Reference
-------------
Expand Down
4 changes: 2 additions & 2 deletions docs/en/api-reference/system/ulp.rst
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,8 @@ Declaration of the entry point symbol comes from the generated header file menti
Application Examples
--------------------

* ULP FSM Coprocessor counts pulses on an IO while main CPU is in deep sleep: :example:`system/ulp_fsm/ulp`.
* ULP FSM Coprocessor polls ADC in while main CPU is in deep sleep: :example:`system/ulp_fsm/ulp_adc`.
* ULP FSM Coprocessor counts pulses on an IO while main CPU is in deep sleep: :example:`system/ulp/ulp_fsm/ulp`.
* ULP FSM Coprocessor polls ADC in while main CPU is in deep sleep: :example:`system/ulp/ulp_fsm/ulp_adc`.

API Reference
-------------
Expand Down
10 changes: 5 additions & 5 deletions docs/zh_CN/api-reference/system/ulp-risc-v.rst
Original file line number Diff line number Diff line change
Expand Up @@ -191,17 +191,17 @@ RTC I2C 控制器提供了在 RTC 电源域中作为 I2C 主机的功能。ULP R

* 通过共享变量查看程序状态:如 :ref:`ulp-riscv-access-variables` 中所述,主 CPU 以及 ULP 内核都可以轻松访问 RTC 内存中的全局变量。通过 ULP 向该变量中写入状态信息,然后通过主 CPU 读取状态信息,可帮助您了解 ULP 内核的状态。该方法的缺点在于它要求主 CPU 一直处于唤醒状态,但现实情况可能并非如此。有时,保持主 CPU 处于唤醒状态还可能会掩盖一些问题,因为某些问题可能仅在特定电源域断电时才会出现。

* 使用 bit-banged UART 驱动程序打印:ULP RISC-V 组件中有一个低速 bit-banged UART TX 驱动程序,可用于打印独立于主 CPU 状态的信息。有关如何使用此驱动程序的示例,请参阅 :example:`system/ulp_riscv/uart_print`。
* 使用 bit-banged UART 驱动程序打印:ULP RISC-V 组件中有一个低速 bit-banged UART TX 驱动程序,可用于打印独立于主 CPU 状态的信息。有关如何使用此驱动程序的示例,请参阅 :example:`system/ulp/ulp_riscv/uart_print`。

* 陷阱信号:ULP RISC-V 有一个硬件陷阱,将在特定条件下触发,例如非法指令。这将导致主 CPU 被 :cpp:enumerator:`ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG` 唤醒。

应用示例
--------------------

* 主 CPU 处于 Deep-sleep 状态时,ULP RISC-V 协处理器轮询 GPIO::example:`system/ulp_riscv/gpio`。
* ULP RISC-V 协处理器使用 bit-banged UART 驱动程序打印::example:`system/ulp_riscv/uart_print`.
* 主 CPU 处于 Deep-sleep 状态时,ULP RISC-V 协处理器读取外部温度传感器::example:`system/ulp_riscv/ds18b20_onewire`。
* 主 CPU 处于 Deep-sleep 状态时,ULP RISC-V 协处理器读取外部 I2C 温度和湿度传感器 (BMP180),达到阈值时唤醒主 CPU::example:`system/ulp_riscv/i2c`.
* 主 CPU 处于 Deep-sleep 状态时,ULP RISC-V 协处理器轮询 GPIO::example:`system/ulp/ulp_riscv/gpio`。
* ULP RISC-V 协处理器使用 bit-banged UART 驱动程序打印::example:`system/ulp/ulp_riscv/uart_print`.
* 主 CPU 处于 Deep-sleep 状态时,ULP RISC-V 协处理器读取外部温度传感器::example:`system/ulp/ulp_riscv/ds18b20_onewire`。
* 主 CPU 处于 Deep-sleep 状态时,ULP RISC-V 协处理器读取外部 I2C 温度和湿度传感器 (BMP180),达到阈值时唤醒主 CPU::example:`system/ulp/ulp_riscv/i2c`.

API 参考
-------------
Expand Down
4 changes: 2 additions & 2 deletions docs/zh_CN/api-reference/system/ulp.rst
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,8 @@ ULP FSM 协处理器代码由汇编语言编写,使用 `binutils-esp32ulp 工
应用示例
--------------------

* 主处理器处于 Deep-sleep 状态时,ULP FSM 协处理器对 IO 脉冲进行计数::example:`system/ulp_fsm/ulp`。
* 主处理器处于 Deep-sleep 状态时,ULP FSM 协处理器轮询 ADC::example:`system/ulp_fsm/ulp_adc`。
* 主处理器处于 Deep-sleep 状态时,ULP FSM 协处理器对 IO 脉冲进行计数::example:`system/ulp/ulp_fsm/ulp`。
* 主处理器处于 Deep-sleep 状态时,ULP FSM 协处理器轮询 ADC::example:`system/ulp/ulp_fsm/ulp_adc`。

API 参考
-------------
Expand Down
34 changes: 19 additions & 15 deletions examples/system/.build-test-rules.yml
Original file line number Diff line number Diff line change
Expand Up @@ -84,10 +84,6 @@ examples/system/light_sleep:
temporary: true
reason: target(s) not supported yet

examples/system/lp_core/lp_i2c:
enable:
- if: SOC_LP_I2C_SUPPORTED == 1

examples/system/ota/advanced_https_ota:
disable:
- if: IDF_TARGET == "esp32h2"
Expand Down Expand Up @@ -175,45 +171,53 @@ examples/system/task_watchdog:
temporary: true
reason: target esp32c2 is not supported yet

examples/system/ulp_fsm/ulp:
examples/system/ulp/lp_core/gpio:
enable:
- if: SOC_LP_CORE_SUPPORTED == 1

examples/system/ulp/lp_core/lp_i2c:
enable:
- if: SOC_LP_I2C_SUPPORTED == 1

examples/system/ulp/ulp_fsm/ulp:
disable:
- if: SOC_ULP_FSM_SUPPORTED != 1

examples/system/ulp_fsm/ulp_adc:
examples/system/ulp/ulp_fsm/ulp_adc:
enable:
- if: IDF_TARGET in ["esp32", "esp32s3"]
temporary: true
reason: the other targets are not tested yet

examples/system/ulp_riscv/adc:
examples/system/ulp/ulp_riscv/adc:
enable:
- if: IDF_TARGET in ["esp32s2", "esp32s3"]
- if: SOC_RISCV_COPROC_SUPPORTED == 1
temporary: true
reason: the other targets are not tested yet

examples/system/ulp_riscv/ds18b20_onewire:
examples/system/ulp/ulp_riscv/ds18b20_onewire:
enable:
- if: IDF_TARGET == "esp32s2"
temporary: true
reason: the other targets are not tested yet

examples/system/ulp_riscv/gpio:
examples/system/ulp/ulp_riscv/gpio:
enable:
- if: IDF_TARGET in ["esp32s2", "esp32s3"]
- if: SOC_RISCV_COPROC_SUPPORTED == 1
temporary: true
reason: the other targets are not tested yet

examples/system/ulp_riscv/gpio_interrupt:
examples/system/ulp/ulp_riscv/gpio_interrupt:
enable:
- if: IDF_TARGET in ["esp32s2", "esp32s3"]
- if: SOC_RISCV_COPROC_SUPPORTED == 1
temporary: true
reason: the other targets are not tested yet

examples/system/ulp_riscv/i2c:
examples/system/ulp/ulp_riscv/i2c:
enable:
- if: SOC_RISCV_COPROC_SUPPORTED == 1

examples/system/ulp_riscv/uart_print:
examples/system/ulp/ulp_riscv/uart_print:
enable:
- if: SOC_RISCV_COPROC_SUPPORTED == 1

Expand Down
6 changes: 6 additions & 0 deletions examples/system/ulp/lp_core/gpio/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# The following lines of boilerplate have to be in your project's CMakeLists
# in this exact order for cmake to work correctly
cmake_minimum_required(VERSION 3.16)

include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(lp_core_gpio_example)
Loading

0 comments on commit 9f31c65

Please sign in to comment.