# 并行 IO 模拟 SPI 或 I80 接口的 LCD

[English]

并行 IO 并不是总线型的外设，驱动直接为 LCD 创建并行 IO 设备。目前驱动支持 SPI (1 bit 数据位宽) 和 I80 (8 bit 数据位宽 )模式。

1. 调用 `esp_lcd_new_panel_io_parl()` 创建并行 IO 设备。请设置以下参数：

   > - `esp_lcd_panel_io_parl_config_t::clk_src` 设置并行 IO 设备的时钟源。请注意，不同的 ESP 芯片可能有不同的默认时钟源。

   > - `esp_lcd_panel_io_parl_config_t::clk_gpio_num` 设置像素时钟的 GPIO 编号（在某些 LCD 规格书中也被称为 `WR` 或者 `SCLK`）

   > - `esp_lcd_panel_io_parl_config_t::dc_gpio_num` 设置数据或命令选择管脚的 GPIO 编号（在某些 LCD 规格书中也被称为 `RS`）

   > - `esp_lcd_panel_io_parl_config_t::cs_gpio_num` 设置 CS 信号线的 GPIO 编号。（注意，Parallel IO LCD 驱动仅支持单个 LCD 设备）。

   > - `esp_lcd_panel_io_parl_config_t::data_width` 设置数据的位宽（仅支持 `1` 位或 `8` 位）

   > - `esp_lcd_panel_io_parl_config_t::data_gpio_nums` 是数据总线的 GPIO 编号数组。GPIO 的数量应与 `esp_lcd_panel_io_parl_config_t::data_width` 的值等同。

   > - `esp_lcd_panel_io_parl_config_t::max_transfer_bytes` 设置单次传输的最大字节数。

   > - `esp_lcd_panel_io_parl_config_t::dma_burst_size` 设置 dma burst 传输的字节数。

   > - `esp_lcd_panel_io_parl_config_t::pclk_hz` 设置像素时钟的频率 (Hz)。较高的像素时钟频率会带来较高的刷新率，但如果 DMA 带宽不足或 LCD 控制器芯片不支持高像素时钟频率，则可能会导致显示异常。

   > - `esp_lcd_panel_io_parl_config_t::dc_levels` 设置 DC 数据选择和命令选择的有效电平。

   > - `esp_lcd_panel_io_parl_config_t::lcd_cmd_bits` 和 `esp_lcd_panel_io_spi_config_t::lcd_param_bits` 分别设置 LCD 控制器芯片可识别的命令及参数的位宽。不同芯片对位宽要求不同，请提前参阅 LCD 规格书。

   > - `esp_lcd_panel_io_parl_config_t::trans_queue_depth` 设置并行 IO 传输队列的深度。该值越大，可以排队的传输越多，但消耗的内存也越多。

   >     esp_lcd_panel_io_handle_t io_handle = NULL;
   >     esp_lcd_panel_io_parl_config_t io_config = {
   >         .clk_src = PARLIO_CLK_SRC_DEFAULT,
   >         .dc_gpio_num = EXAMPLE_PIN_NUM_DC,
   >         .clk_gpio_num = EXAMPLE_PIN_NUM_PCLK,
   >         .data_gpio_nums = {
   >             EXAMPLE_PIN_NUM_DATA0, // 驱动 SPI 接口的 LCD 时需要设置 DATA0，驱动 I80 接口的 LCD 时需要设置 DATA0~7
   >         },
   >         .data_width = 1, // 驱动 SPI 接口的 LCD 时数据宽度为 1，驱动 I80 接口的 LCD 时数据宽度为 8
   >         .max_transfer_bytes = EXAMPLE_LCD_H_RES * 100 * sizeof(uint16_t), // 单次最多可传输 100 行像素（假设像素格式为 RGB565）
   >         .dma_burst_size = EXAMPLE_DMA_BURST_SIZE,
   >         .cs_gpio_num = EXAMPLE_PIN_NUM_CS,
   >         .pclk_hz = EXAMPLE_LCD_PIXEL_CLOCK_HZ,
   >         .trans_queue_depth = 10,
   >         .dc_levels = {
   >             .dc_cmd_level = 0,
   >             .dc_data_level = 1,
   >         },
   >         .lcd_cmd_bits = EXAMPLE_LCD_CMD_BITS,
   >         .lcd_param_bits = EXAMPLE_LCD_PARAM_BITS,
   >     };

   >     ESP_ERROR_CHECK(esp_lcd_new_panel_io_parl(&io_config, io_handle));

   > 备注

   > 注意，由于硬件限制，ESP32-H2 不能通过并行 IO 模拟驱动 I80 接口 LCD。

2. 安装 LCD 控制器驱动程序。LCD 控制器驱动程序负责向 LCD 控制器芯片发送命令和参数。在此步骤中，需要指定上一步骤中分配到的并行 IO 设备句柄以及一些面板特定配置：

   > - `esp_lcd_panel_dev_config_t::reset_gpio_num` 设置 LCD 的硬件复位 GPIO 编号。如果 LCD 没有硬件复位管脚，则将此设置为 `-1`。

   > - `esp_lcd_panel_dev_config_t::rgb_ele_order` 设置每个颜色数据的 RGB 元素顺序。

   > - `esp_lcd_panel_dev_config_t::bits_per_pixel` 设置像素颜色数据的位宽。LCD 驱动程序使用此值计算要发送到 LCD 控制器芯片的字节数。

   > - `esp_lcd_panel_dev_config_t::data_endian` 指定传输到屏幕的数据的字节序。不超过一字节的颜色格式（如 RGB232）不需要指定数据字节序。若驱动程序不支持指定数据字节序，则将忽略此字段。

   >     esp_lcd_panel_handle_t panel_handle = NULL;
   >     esp_lcd_panel_dev_config_t panel_config = {
   >         .reset_gpio_num = EXAMPLE_PIN_NUM_RST,
   >         .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_BGR,
   >         .bits_per_pixel = 16,
   >     };
   >     // 为 ST7789 创建 LCD 面板句柄，并指定并行 IO 设备句柄
   >     ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(io_handle, &panel_config, &panel_handle));

# API 参考

## Header File

- components/esp_lcd/include/esp_lcd_io_parl.h

- This header file can be included with:

  >     #include "esp_lcd_io_parl.h"

- This header file is a part of the API provided by the `esp_lcd` component. To declare that your component depends on `esp_lcd`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_lcd

  > or

  >     PRIV_REQUIRES esp_lcd

## Functions

esp_err_t esp_lcd_new_panel_io_parl(const esp_lcd_panel_io_parl_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io)

  Create LCD panel IO, for parlio interface.

  参数:

    - io_config -- [in] IO configuration, for parlio interface

    - ret_io -- [out] Returned panel IO handle

  返回:

    - ESP_ERR_INVALID_ARG if parameter is invalid

    - ESP_ERR_NOT_SUPPORTED if some configuration can't be satisfied, e.g. pixel clock out of the range

    - ESP_ERR_NO_MEM if out of memory

    - ESP_OK on success

void *esp_lcd_parlio_alloc_draw_buffer(esp_lcd_panel_io_handle_t io, size_t size, uint32_t caps)

  Allocate a draw buffer that can be used by parlio interface LCD panel.

  备注

  This function differs from the normal 'heap_caps_*' functions in that it can also automatically handle the alignment required by DMA burst, cache line size, etc.

  参数:

    - io -- [in] Panel IO handle, created by `esp_lcd_new_panel_io_parl()`

    - size -- [in] Size of memory to be allocated

    - caps -- [in] Bitwise OR of MALLOC_CAP_* flags indicating the type of memory desired for the allocation

  返回:

    Pointer to a new buffer of size 'size' with capabilities 'caps', or NULL if allocation failed

## Structures

struct esp_lcd_panel_io_parl_config_t

  Parallel Panel IO configuration structure, for intel 8080 interface(8 data-lines) or SPI interface(1 data-lines)

  Public Members

  int dc_gpio_num

    GPIO used for D/C line

  int clk_gpio_num

    GPIO used for CLK line

  int cs_gpio_num

    GPIO used for CS line

  int data_gpio_nums[ESP_PARLIO_LCD_WIDTH_MAX]

    GPIOs used for data lines

  size_t data_width

    Number of data lines, 1(SPI) or 8(I80)

  uint32_t pclk_hz

    Frequency of pixel clock

  parlio_clock_source_t clk_src

    Clock source for the Parlio peripheral

  size_t max_transfer_bytes

    Maximum transfer size, this determines the length of internal DMA link

  size_t dma_burst_size

    DMA burst size, in bytes

  size_t trans_queue_depth

    Transaction queue size, larger queue, higher throughput

  int lcd_cmd_bits

    Bit-width of LCD command

  int lcd_param_bits

    Bit-width of LCD parameter

  unsigned int dc_cmd_level

    Level of DC line in CMD phase

  unsigned int dc_data_level

    Level of DC line in DATA phase

  struct esp_lcd_panel_io_parl_config_t dc_levels

    Each LCD device might have its own D/C control logic

  unsigned int cs_active_high

    If set, a high level of CS line will select the device, otherwise, CS line is low level active

  struct esp_lcd_panel_io_parl_config_t flags

    Panel IO config flags

## Macros

ESP_PARLIO_LCD_WIDTH_MAX

  Maximum data width of parlio lcd interface

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。