doc: initial parallel IO programming guide

Also correct the GPIO information on esp32h2.
2023-02-22 13:29:31 +08:00
parent f534247a00
commit a7f5ff32ff
8 changed files with 48 additions and 10 deletions
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -74,6 +74,8 @@ MCPWM_DOCS = ['api-reference/peripherals/mcpwm.rst']

 DEDIC_GPIO_DOCS = ['api-reference/peripherals/dedic_gpio.rst']

+PARLIO_DOCS = ['api-reference/peripherals/parlio.rst']
+
 PCNT_DOCS = ['api-reference/peripherals/pcnt.rst']

 RMT_DOCS = ['api-reference/peripherals/rmt.rst']
@@ -173,6 +175,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
                            'SOC_USB_SERIAL_JTAG_SUPPORTED':USB_SERIAL_JTAG_DOCS,
                            'SOC_DEDICATED_GPIO_SUPPORTED':DEDIC_GPIO_DOCS,
                            'SOC_SPIRAM_SUPPORTED':SPIRAM_DOCS,
+                            'SOC_PARLIO_SUPPORTED':PARLIO_DOCS,
                            'SOC_PCNT_SUPPORTED':PCNT_DOCS,
                            'SOC_RMT_SUPPORTED':RMT_DOCS,
                            'SOC_DAC_SUPPORTED':DAC_DOCS,
--- a/docs/doxygen/Doxyfile
+++ b/docs/doxygen/Doxyfile
@@ -88,6 +88,8 @@ INPUT = \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_sync.h \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_timer.h \
    $(PROJECT_PATH)/components/driver/mcpwm/include/driver/mcpwm_types.h \
+    $(PROJECT_PATH)/components/driver/parlio/include/driver/parlio_tx.h \
+    $(PROJECT_PATH)/components/driver/parlio/include/driver/parlio_types.h \
    $(PROJECT_PATH)/components/driver/pcnt/include/driver/pulse_cnt.h \
    $(PROJECT_PATH)/components/driver/rmt/include/driver/rmt_common.h \
    $(PROJECT_PATH)/components/driver/rmt/include/driver/rmt_encoder.h \
@@ -199,6 +201,7 @@ INPUT = \
    $(PROJECT_PATH)/components/hal/include/hal/lcd_types.h \
    $(PROJECT_PATH)/components/hal/include/hal/ledc_types.h \
    $(PROJECT_PATH)/components/hal/include/hal/mcpwm_types.h \
+    $(PROJECT_PATH)/components/hal/include/hal/parlio_types.h \
    $(PROJECT_PATH)/components/hal/include/hal/pcnt_types.h \
    $(PROJECT_PATH)/components/hal/include/hal/rmt_types.h \
    $(PROJECT_PATH)/components/hal/include/hal/rtc_io_types.h \
--- a/docs/en/api-reference/peripherals/gpio/esp32h2.inc
+++ b/docs/en/api-reference/peripherals/gpio/esp32h2.inc
@@ -62,11 +62,11 @@ The table below provides more information on pin usage, and please note the comm
      - Strapping pin

    * - GPIO10
-      -
+      - Analog comparator reference voltage
      -

    * - GPIO11
-      -
+      - Analog comparator input (non-inverting)
      -

    * - GPIO12
@@ -137,7 +137,8 @@ The table below provides more information on pin usage, and please note the comm

    - Strapping pin: GPIO2, GPIO3, GPIO8, GPIO9, and GPIO25 are strapping pins. For more infomation, please refer to `ESP32H2 datasheet <https://www.espressif.com/sites/default/files/documentation/esp32h2_datasheet_en.pdf>`_.
 	  - SPI0/1: GPIO15-21 are usually used for SPI flash and not recommended for other uses.
-	  - USB-JTAG: GPIO 26 and 27 are used by USB-JTAG by default. In order to use them as GPIOs, USB-JTAG will be disabled by the drivers.
-    - For chip variants with an SiP flash built in, GPIO15 ~ GPIO21 are dedicated to connecting the SiP flash; therefore, only the remaining 21 GPIO pins are available.
+	  - USB-Serial-JTAG: GPIO 26 and 27 are used by USB-Serial-JTAG by default. In order to use them as GPIOs, USB-Serial-JTAG will be disabled by the drivers.
+    - For chip variants with an SiP flash built in, GPIO15 ~ GPIO21 are dedicated to connecting the SiP flash and are not fan-out to the external pins. In addition, GPIO6 ~ GPIO7 are also not fan-out to the external pins. In conclusion, only GPIO0~ GPIO5, GPIO8~ GPIO14, GPIO22~ GPIO27 are available to users.
+    - For chip variant without SiP flash, apart from the flash IOs mentioned above, GPIO22 is not fan-out to the external pin, thus they're not available to users.

 ---
--- a/docs/en/api-reference/peripherals/index.rst
+++ b/docs/en/api-reference/peripherals/index.rst
@@ -22,6 +22,7 @@ Peripherals API
    lcd
    ledc
    :SOC_MCPWM_SUPPORTED: mcpwm
+    :SOC_PARLIO_SUPPORTED: parlio
    :SOC_PCNT_SUPPORTED: pcnt
    :SOC_RMT_SUPPORTED: rmt
    :esp32: sd_pullup_requirements
--- a/docs/en/api-reference/peripherals/parlio.rst
+++ b/docs/en/api-reference/peripherals/parlio.rst
@@ -0,0 +1,27 @@
+Parallel IO
+===========
+
+Introduction
+------------
+
+The Parallel IO peripheral is a general purpose parallel interface that can be used to connect to external devices such as LED matrix, LCD display, Printer and Camera. The peripheral has independent TX and RX units. Each unit can have up to 8 or 16 data signals plus 1 or 2 clock signals. [1]_
+
+.. warning::
+	At the moment, the Parallel IO driver only supports TX mode. The RX feature is still working in progress.
+
+
+Application Examples
+--------------------
+
+* Simple REG LED Matrix with HUB75 interface: :example:`peripherals/parlio/simple_rgb_led_matrix`.
+
+
+API Reference
+-------------
+
+.. include-build-file:: inc/parlio_tx.inc
+.. include-build-file:: inc/components/driver/parlio/include/driver/parlio_types.inc
+.. include-build-file:: inc/components/hal/include/hal/parlio_types.inc
+
+.. [1]
+   Different ESP chip series might have different numbers of PARLIO TX/RX instances, and the maximum data bus can also be different. For more details, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > Chapter *Parallel IO (PARLIO)* [`PDF <{IDF_TARGET_TRM_EN_URL}#parlio>`__]. The driver will not forbid you from applying for more driver objects, but it will return error when all available hardware resources are used up. Please always check the return value when doing resource allocation (e.g. :cpp:func:`parlio_new_tx_unit`).
--- a/docs/zh_CN/api-reference/peripherals/gpio/esp32h2.inc
+++ b/docs/zh_CN/api-reference/peripherals/gpio/esp32h2.inc
@@ -64,11 +64,11 @@
      - Strapping 管脚

    * - GPIO10
-      -
+      - 模拟比较器外部参考电压
      -

    * - GPIO11
-      -
+      - 模拟比较器同相输入
      -

    * - GPIO12
@@ -137,9 +137,10 @@

 .. note::

-    - Strapping 管脚：GPIO2、GPIO3、GPIO8、GPIO9 和 GPIO25 是 Strapping 管脚。更多信息请参考 `ESP32-H2 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-h2_datasheet_cn.pdf>`_。
-    - SPI0/1：GPIO15-21 通常用于 SPI flash，不推荐用于其他用途。
-    - USB-JTAG：GPIO26 和 GPIO27 默认用于 USB-JTAG。用做 GPIO 时驱动程序将禁用 USB-JTAG。
-    - 对于内置 SiP flash 的芯片型号，GPIO15 ~ GPIO21 专门用于连接 SiP flash; 因此，对于这类芯片只有 21 个 GPIO 管脚可用。
+    - Strapping 管脚： GPIO2、GPIO3、GPIO8、GPIO9 和 GPIO25 是 Strapping 管脚。更多信息请参考 `ESP32-H2 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-h2_datasheet_cn.pdf>`_。
+    - SPI0/1: GPIO15-21 通常用于 SPI flash, 不推荐用于其他用途。
+    - USB-Serial-JTAG: GPIO26 和 GPIO27 默认用于 USB-Serial-JTAG。用做 GPIO 时驱动程序将禁用 USB-Serial-JTAG。
+    - 对于合封了 flash 的芯片型号， GPIO15 ~ GPIO21 专门用于连接该 flash, 并未引出至芯片管脚。且 GPIO6 ~ GPIO7 也未引出至芯片管脚，用户不可用。用户可配置使用其他剩余的 19 个 GPIO 管脚, 编号为: GPIO0 ~ GPIO5、GPIO8 ~ GPIO14、GPIO22 ~ GPIO27。
+    - 对于未合封 flash 的芯片型号， 除了以上提到的给 Flash 专用的 GPIO 以外, GPIO22 也并未引出至芯片管脚，用户不可用。

 ---
--- a/docs/zh_CN/api-reference/peripherals/index.rst
+++ b/docs/zh_CN/api-reference/peripherals/index.rst
@@ -22,6 +22,7 @@
    lcd
    ledc
    :SOC_MCPWM_SUPPORTED: mcpwm
+    :SOC_PARLIO_SUPPORTED: parlio
    :SOC_PCNT_SUPPORTED: pcnt
    :SOC_RMT_SUPPORTED: rmt
    :SOC_SDMMC_HOST_SUPPORTED: sd_pullup_requirements
--- a/docs/zh_CN/api-reference/peripherals/parlio.rst
+++ b/docs/zh_CN/api-reference/peripherals/parlio.rst
@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/peripherals/parlio.rst
				`@@ -0,0 +1 @@`
				`.. include:: ../../../en/api-reference/peripherals/parlio.rst`