From 3b7e16f18257fa30ea8d3b3c34b590fb6dea2496 Mon Sep 17 00:00:00 2001 From: Linda Date: Mon, 15 Apr 2024 15:41:26 +0800 Subject: [PATCH] docs: add code snippet showing how to configure usb pins to gpio --- docs/en/api-reference/peripherals/gpio.rst | 52 +++++++++++++------ docs/zh_CN/api-reference/peripherals/gpio.rst | 52 +++++++++++++------ 2 files changed, 72 insertions(+), 32 deletions(-) diff --git a/docs/en/api-reference/peripherals/gpio.rst b/docs/en/api-reference/peripherals/gpio.rst index a6ae8fe326..617d43fd1a 100644 --- a/docs/en/api-reference/peripherals/gpio.rst +++ b/docs/en/api-reference/peripherals/gpio.rst @@ -10,6 +10,28 @@ GPIO Summary :start-after: gpio-summary :end-before: --- +.. only:: SOC_RTCIO_INPUT_OUTPUT_SUPPORTED + + .. only:: not SOC_LP_PERIPHERALS_SUPPORTED + + There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when: + + .. only:: SOC_LP_PERIPHERALS_SUPPORTED + + There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power, analog subsystem, and Low-Power(LP) peripherals. These pin functions can be used when: + + .. list:: + + - In Deep-sleep mode + :SOC_ULP_FSM_SUPPORTED: - The :doc:`Ultra Low Power FSM co-processor <../../api-reference/system/ulp>` is running + :SOC_RISCV_COPROC_SUPPORTED: - The :doc:`Ultra Low Power RISC-V co-processor <../../api-reference/system/ulp-risc-v>` is running + :SOC_LP_CORE_SUPPORTED: - The :doc:`Ultra Low Power LP-Core co-processor <../../api-reference/system/ulp-lp-core>` is running + - Analog functions such as ADC/DAC/etc are in use + :SOC_LP_PERIPHERALS_SUPPORTED: - LP peripherals, such as LP_UART, LP_I2C, are in use + +Check Current Configuration of IOs +---------------------------------- + GPIO driver offers a dump function :cpp:func:`gpio_dump_io_configuration` to show the current configurations of IOs, such as pull-up/pull-down, input/output enable, pin mapping, etc. Below is an example of how to dump the configuration of GPIO4, GPIO18, and GPIO26: :: @@ -49,27 +71,25 @@ In addition, if you would like to dump the configurations of all IOs, you can us gpio_dump_all_io_configuration(stdout, SOC_GPIO_VALID_GPIO_MASK); -If an IO pin is routed to a peripheral signal through the GPIO matrix, the signal ID printed in the dump information is defined in the ``soc/gpio_sig_map.h`` file. The word ``**RESERVED**`` indicates the IO is occupied by either FLASH or PSRAM. It is strongly not recommended to reconfigure them for other application purposes. +If an IO pin is routed to a peripheral signal through the GPIO matrix, the signal ID printed in the dump information is defined in the :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/gpio_sig_map.h` header file. The word ``**RESERVED**`` indicates the IO is occupied by either SPI flash or PSRAM. It is strongly not recommended to reconfigure them for other application purposes. -.. only:: SOC_RTCIO_INPUT_OUTPUT_SUPPORTED +.. only:: esp32c3 or esp32c6 or esp32h2 or esp32p4 or esp32s2 or esp32s3 - .. only:: not SOC_LP_PERIPHERALS_SUPPORTED + Configure USB PHY Pins to GPIO + ------------------------------- - There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when: + To configure the USB PHY pins to GPIO, you can use the function :cpp:func:`gpio_config`. Below is an example of how to configure the USB PHY pins to GPIO: - .. only:: SOC_LP_PERIPHERALS_SUPPORTED - - There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power, analog subsystem, and Low-Power(LP) peripherals. These pin functions can be used when: - - .. list:: - - - In Deep-sleep mode - :SOC_ULP_FSM_SUPPORTED: - The :doc:`Ultra Low Power FSM co-processor <../../api-reference/system/ulp>` is running - :SOC_RISCV_COPROC_SUPPORTED: - The :doc:`Ultra Low Power RISC-V co-processor <../../api-reference/system/ulp-risc-v>` is running - :SOC_LP_CORE_SUPPORTED: - The :doc:`Ultra Low Power LP-Core co-processor <../../api-reference/system/ulp-lp-core>` is running - - Analog functions such as ADC/DAC/etc are in use - :SOC_LP_PERIPHERALS_SUPPORTED: - LP peripherals, such as LP_UART, LP_I2C, are in use + .. code-block:: c + gpio_config_t usb_phy_conf = { + .pin_bit_mask = (1ULL << USB_PHY_DP_PIN) | (1ULL << USB_PHY_DM_PIN), + .mode = GPIO_MODE_INPUT_OUTPUT, + .pull_up_en = 0, + .pull_down_en = 0, + .intr_type = GPIO_INTR_DISABLE, + }; + gpio_config(&usb_phy_conf); .. only:: SOC_GPIO_SUPPORT_PIN_GLITCH_FILTER or SOC_GPIO_FLEX_GLITCH_FILTER_NUM diff --git a/docs/zh_CN/api-reference/peripherals/gpio.rst b/docs/zh_CN/api-reference/peripherals/gpio.rst index a6d0399541..e071fc9319 100644 --- a/docs/zh_CN/api-reference/peripherals/gpio.rst +++ b/docs/zh_CN/api-reference/peripherals/gpio.rst @@ -10,6 +10,28 @@ GPIO 汇总 :start-after: gpio-summary :end-before: --- +.. only:: SOC_RTCIO_INPUT_OUTPUT_SUPPORTED + + .. only:: not SOC_LP_PERIPHERALS_SUPPORTED + + 当 GPIO 连接到 RTC 低功耗和模拟子系统时，{IDF_TARGET_NAME} 芯片还单独支持 RTC GPIO。可在以下情况时使用这些管脚功能： + + .. only:: SOC_LP_PERIPHERALS_SUPPORTED + + 当 GPIO 连接到 RTC 低功耗、模拟子系统、低功耗外设时，{IDF_TARGET_NAME} 芯片还单独支持 RTC GPIO。可在以下情况时使用这些管脚功能： + + .. list:: + + - 处于 Deep-sleep 模式时 + :SOC_ULP_FSM_SUPPORTED: - :doc:`超低功耗协处理器 (ULP-FSM) <../../api-reference/system/ulp>` 运行时 + :SOC_RISCV_COPROC_SUPPORTED: - :doc:`超低功耗协处理器 (ULP-RISC-V) <../../api-reference/system/ulp-risc-v>` 运行时 + :SOC_LP_CORE_SUPPORTED: - :doc:`超低功耗协处理器 (ULP-LP-Core) <../../api-reference/system/ulp-lp-core>` 运行时 + - 使用 ADC/DAC 等模拟功能时 + :SOC_LP_PERIPHERALS_SUPPORTED: - 使用低功耗外设时，例如： LP_UART ， LP_I2C 等 + +获取 IO 管脚实时配置状态 +-------------------------------------------- + GPIO 驱动提供了一个函数 :cpp:func:`gpio_dump_io_configuration` 用来输出指定管脚的实时配置状态，包括上下拉、输入输出使能、管脚映射等。例如，以下命令可用于输出 GPIO4，GPIO8 与 GPIO26 的配置状态： :: @@ -49,27 +71,25 @@ GPIO 驱动提供了一个函数 :cpp:func:`gpio_dump_io_configuration` 用来 gpio_dump_all_io_configuration(stdout, SOC_GPIO_VALID_GPIO_MASK); -当 IO 管脚是通过 GPIO 交换矩阵连接到内部外设信号，输出信息打印中的外设信号 ID 定义可以在 ``soc/gpio_sig_map.h`` 文件中查看。``**RESERVED**`` 字样则表示此 IO 被用于连接 FLASH 或 PSRAM，因此该引脚不应该被其他任何应用场景所征用并进行重新配置。 +如果 IO 管脚通过 GPIO 交换矩阵连接到内部外设信号，输出信息打印中的外设信号 ID 定义可以在 :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/gpio_sig_map.h` 头文件中查看。``**RESERVED**`` 字样则表示此 IO 用于连接 SPI flash 或 PSRAM，强烈建议不要重新配置这些管脚用于其他功能。 -.. only:: SOC_RTCIO_INPUT_OUTPUT_SUPPORTED +.. only:: esp32c3 or esp32c6 or esp32h2 or esp32p4 or esp32s2 or esp32s3 - .. only:: not SOC_LP_PERIPHERALS_SUPPORTED + 配置 USB PHY 管脚 为普通 GPIO 管脚 + --------------------------------------- - 当 GPIO 连接到 RTC 低功耗和模拟子系统时，{IDF_TARGET_NAME} 芯片还单独支持 RTC GPIO。可在以下情况时使用这些管脚功能： + 要将 USB PHY 管脚配置为普通 GPIO 管脚，可使用函数 :cpp:func:`gpio_config`，请参考以下代码片段来进行配置。 - .. only:: SOC_LP_PERIPHERALS_SUPPORTED - - 当 GPIO 连接到 RTC 低功耗、模拟子系统、低功耗外设时，{IDF_TARGET_NAME} 芯片还单独支持 RTC GPIO。可在以下情况时使用这些管脚功能： - - .. list:: - - - 处于 Deep-sleep 模式时 - :SOC_ULP_FSM_SUPPORTED: - :doc:`超低功耗协处理器 (ULP-FSM) <../../api-reference/system/ulp>` 运行时 - :SOC_RISCV_COPROC_SUPPORTED: - :doc:`超低功耗协处理器 (ULP-RISC-V) <../../api-reference/system/ulp-risc-v>` 运行时 - :SOC_LP_CORE_SUPPORTED: - :doc:`超低功耗协处理器 (ULP-LP-Core) <../../api-reference/system/ulp-lp-core>` 运行时 - - 使用 ADC/DAC 等模拟功能时 - :SOC_LP_PERIPHERALS_SUPPORTED: - 使用低功耗外设时，例如： LP_UART ， LP_I2C 等 + .. code-block:: c + gpio_config_t usb_phy_conf = { + .pin_bit_mask = (1ULL << USB_PHY_DP_PIN) | (1ULL << USB_PHY_DM_PIN), + .mode = GPIO_MODE_INPUT_OUTPUT, + .pull_up_en = 0, + .pull_down_en = 0, + .intr_type = GPIO_INTR_DISABLE, + }; + gpio_config(&usb_phy_conf); .. only:: SOC_GPIO_SUPPORT_PIN_GLITCH_FILTER or SOC_GPIO_FLEX_GLITCH_FILTER_NUM