From 414dba50090d0e2cd5ce1611fda3cbffcc9ebf13 Mon Sep 17 00:00:00 2001 From: morris Date: Mon, 28 Jul 2025 13:43:31 +0800 Subject: [PATCH] refactor(lcd)!: remove deprecated types --- components/esp_lcd/include/esp_lcd_io_i80.h | 6 +----- components/esp_lcd/include/esp_lcd_io_spi.h | 2 -- components/esp_lcd/include/esp_lcd_panel_dev.h | 14 +++++--------- components/esp_lcd/include/esp_lcd_panel_ops.h | 14 +------------- components/esp_lcd/include/esp_lcd_types.h | 12 ------------ .../esp_lcd/rgb/include/esp_lcd_panel_rgb.h | 16 ++-------------- components/esp_lcd/src/esp_lcd_panel_ops.c | 5 ----- .../release-6.x/6.0/peripherals.rst | 11 +++++++++++ .../release-6.x/6.0/peripherals.rst | 11 +++++++++++ .../camera/dvp_spi_lcd/main/dvp_spi_lcd_main.c | 2 +- 10 files changed, 32 insertions(+), 61 deletions(-) diff --git a/components/esp_lcd/include/esp_lcd_io_i80.h b/components/esp_lcd/include/esp_lcd_io_i80.h index d8a1683772..c9647a1764 100644 --- a/components/esp_lcd/include/esp_lcd_io_i80.h +++ b/components/esp_lcd/include/esp_lcd_io_i80.h @@ -29,11 +29,7 @@ typedef struct { gpio_num_t data_gpio_nums[ESP_LCD_I80_BUS_WIDTH_MAX]; /*!< GPIOs used for data lines */ size_t bus_width; /*!< Number of data lines, 8 or 16 */ size_t max_transfer_bytes; /*!< Maximum transfer size, this determines the length of internal DMA link */ - union { - size_t psram_trans_align __attribute__((deprecated)); /*!< DMA transfer alignment for data allocated from PSRAM */ - size_t dma_burst_size; /*!< DMA burst size, in bytes */ - }; - size_t sram_trans_align __attribute__((deprecated)); /*!< DMA transfer alignment for data allocated from SRAM */ + size_t dma_burst_size; /*!< DMA burst size, in bytes */ } esp_lcd_i80_bus_config_t; /** diff --git a/components/esp_lcd/include/esp_lcd_io_spi.h b/components/esp_lcd/include/esp_lcd_io_spi.h index 3fe7f31f09..9fb0b0bd9d 100644 --- a/components/esp_lcd/include/esp_lcd_io_spi.h +++ b/components/esp_lcd/include/esp_lcd_io_spi.h @@ -35,8 +35,6 @@ typedef struct { unsigned int dc_high_on_cmd: 1; /*!< If enabled, DC level = 1 indicates command transfer */ unsigned int dc_low_on_data: 1; /*!< If enabled, DC level = 0 indicates color data transfer */ unsigned int dc_low_on_param: 1; /*!< If enabled, DC level = 0 indicates parameter transfer */ - unsigned int octal_mode: 1 __attribute__((deprecated("This bitfield is deprecated"))); /*!< Deprecated, driver will detect the bus mode automatically */ - unsigned int quad_mode: 1 __attribute__((deprecated("This bitfield is deprecated"))); /*!< Deprecated, driver will detect the bus mode automatically */ unsigned int sio_mode: 1; /*!< Read and write through a single data line (MOSI) */ unsigned int lsb_first: 1; /*!< transmit LSB bit first */ unsigned int cs_high_active: 1; /*!< CS line is high active */ diff --git a/components/esp_lcd/include/esp_lcd_panel_dev.h b/components/esp_lcd/include/esp_lcd_panel_dev.h index 9683ce0039..c17ead8bb6 100644 --- a/components/esp_lcd/include/esp_lcd_panel_dev.h +++ b/components/esp_lcd/include/esp_lcd_panel_dev.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -18,18 +18,14 @@ extern "C" { * @brief Configuration structure for panel device */ typedef struct { - union { - esp_lcd_color_space_t color_space; /*!< @deprecated Set RGB color space, please use rgb_ele_order instead */ - lcd_color_rgb_endian_t rgb_endian; /*!< @deprecated Set RGB data endian, please use rgb_ele_order instead */ - lcd_rgb_element_order_t rgb_ele_order; /*!< Set RGB element order, RGB or BGR */ - }; - lcd_rgb_data_endian_t data_endian; /*!< Set the data endian for color data larger than 1 byte */ - uint32_t bits_per_pixel; /*!< Color depth, in bpp */ + lcd_rgb_element_order_t rgb_ele_order; /*!< Set RGB element order, RGB or BGR */ + lcd_rgb_data_endian_t data_endian; /*!< Set the data endian for color data larger than 1 byte */ + uint32_t bits_per_pixel; /*!< Color depth, in bpp */ gpio_num_t reset_gpio_num; /*!< GPIO used to reset the LCD panel, set to -1 if it's not used */ + void *vendor_config; /*!< vendor specific configuration, optional, left as NULL if not used */ struct { uint32_t reset_active_high: 1; /*!< Setting this if the panel reset is high level active */ } flags; /*!< LCD panel config flags */ - void *vendor_config; /*!< vendor specific configuration, optional, left as NULL if not used */ } esp_lcd_panel_dev_config_t; #ifdef __cplusplus diff --git a/components/esp_lcd/include/esp_lcd_panel_ops.h b/components/esp_lcd/include/esp_lcd_panel_ops.h index 47e22c78ca..14280ad46f 100644 --- a/components/esp_lcd/include/esp_lcd_panel_ops.h +++ b/components/esp_lcd/include/esp_lcd_panel_ops.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -121,18 +121,6 @@ esp_err_t esp_lcd_panel_invert_color(esp_lcd_panel_handle_t panel, bool invert_c */ esp_err_t esp_lcd_panel_disp_on_off(esp_lcd_panel_handle_t panel, bool on_off); -/** - * @brief Turn off the display - * - * @param[in] panel LCD panel handle, which is created by other factory API like `esp_lcd_new_panel_st7789()` - * @param[in] off Whether to turn off the screen - * @return - * - ESP_OK on success - * - ESP_ERR_NOT_SUPPORTED if this function is not supported by the panel - */ -esp_err_t esp_lcd_panel_disp_off(esp_lcd_panel_handle_t panel, bool off) -__attribute__((deprecated("use esp_lcd_panel_disp_on_off instead"))); - /** * @brief Enter or exit sleep mode * diff --git a/components/esp_lcd/include/esp_lcd_types.h b/components/esp_lcd/include/esp_lcd_types.h index 3add34a8b8..162b6d7c63 100644 --- a/components/esp_lcd/include/esp_lcd_types.h +++ b/components/esp_lcd/include/esp_lcd_types.h @@ -40,18 +40,6 @@ typedef enum { LCD_RGB_ELEMENT_ORDER_BGR = COLOR_RGB_ELEMENT_ORDER_BGR, /*!< RGB element order: BGR */ } lcd_rgb_element_order_t; -/** @cond */ -/// for backward compatible -typedef lcd_rgb_element_order_t lcd_color_rgb_endian_t; -#define LCD_RGB_ENDIAN_RGB (lcd_color_rgb_endian_t)LCD_RGB_ELEMENT_ORDER_RGB -#define LCD_RGB_ENDIAN_BGR (lcd_color_rgb_endian_t)LCD_RGB_ELEMENT_ORDER_BGR - -typedef lcd_rgb_element_order_t esp_lcd_color_space_t; -#define ESP_LCD_COLOR_SPACE_RGB (esp_lcd_color_space_t)LCD_RGB_ELEMENT_ORDER_RGB -#define ESP_LCD_COLOR_SPACE_BGR (esp_lcd_color_space_t)LCD_RGB_ELEMENT_ORDER_BGR -#define ESP_LCD_COLOR_SPACE_MONOCHROME (esp_lcd_color_space_t)2 -/** @endcond */ - /** * @brief Type of LCD panel IO event data */ diff --git a/components/esp_lcd/rgb/include/esp_lcd_panel_rgb.h b/components/esp_lcd/rgb/include/esp_lcd_panel_rgb.h index fe5693291b..e9e7709890 100644 --- a/components/esp_lcd/rgb/include/esp_lcd_panel_rgb.h +++ b/components/esp_lcd/rgb/include/esp_lcd_panel_rgb.h @@ -116,11 +116,6 @@ typedef esp_lcd_rgb_panel_general_cb_t esp_lcd_rgb_panel_vsync_cb_t; */ typedef bool (*esp_lcd_rgb_panel_bounce_buf_fill_cb_t)(esp_lcd_panel_handle_t panel, void *bounce_buf, int pos_px, int len_bytes, void *user_ctx); -/** @cond */ -/// for backward compatible -typedef esp_lcd_rgb_panel_frame_buf_complete_cb_t esp_lcd_rgb_panel_bounce_buf_finish_cb_t __attribute__((deprecated("esp_lcd_rgb_panel_bounce_buf_finish_cb_t is deprecated, use esp_lcd_rgb_panel_frame_buf_complete_cb_t instead"))); -/** @endcond */ - /** * @brief Group of supported RGB LCD panel callbacks * @note The callbacks are all running under ISR environment @@ -132,10 +127,7 @@ typedef struct { But doesn't mean the draw buffer finishes the refreshing to the screen. */ esp_lcd_rgb_panel_vsync_cb_t on_vsync; /*!< VSYNC event callback */ esp_lcd_rgb_panel_bounce_buf_fill_cb_t on_bounce_empty; /*!< Bounce buffer empty callback. */ - union { - esp_lcd_rgb_panel_frame_buf_complete_cb_t on_bounce_frame_finish __attribute__((deprecated)); /*!< Bounce buffer finish callback. */ - esp_lcd_rgb_panel_frame_buf_complete_cb_t on_frame_buf_complete; /*!< A whole frame buffer was just sent to the LCD DMA */ - }; + esp_lcd_rgb_panel_frame_buf_complete_cb_t on_frame_buf_complete; /*!< A whole frame buffer was just sent to the LCD DMA */ } esp_lcd_rgb_panel_event_callbacks_t; /** @@ -150,11 +142,7 @@ typedef struct { size_t num_fbs; /*!< Number of screen-sized frame buffers that allocated by the driver. By default (set to either 0 or 1) only one frame buffer will be used. Maximum number of buffers are 3 */ size_t bounce_buffer_size_px; /*!< If it's non-zero, the driver allocates two DRAM bounce buffers for DMA use. DMA fetching from DRAM bounce buffer is much faster than PSRAM frame buffer. */ - size_t sram_trans_align __attribute__((deprecated)); /*!< Alignment of buffers (frame buffer or bounce buffer) that allocated in SRAM */ - union { - size_t psram_trans_align __attribute__((deprecated)); /*!< Alignment of buffers (frame buffer) that allocated in PSRAM */ - size_t dma_burst_size; /*!< DMA burst size, in bytes */ - }; + size_t dma_burst_size; /*!< DMA burst size, in bytes */ gpio_num_t hsync_gpio_num; /*!< GPIO used for HSYNC signal */ gpio_num_t vsync_gpio_num; /*!< GPIO used for VSYNC signal */ gpio_num_t de_gpio_num; /*!< GPIO used for DE signal, set to -1 if it's not used */ diff --git a/components/esp_lcd/src/esp_lcd_panel_ops.c b/components/esp_lcd/src/esp_lcd_panel_ops.c index d4e6bd9ade..3eaa27a89c 100644 --- a/components/esp_lcd/src/esp_lcd_panel_ops.c +++ b/components/esp_lcd/src/esp_lcd_panel_ops.c @@ -72,11 +72,6 @@ esp_err_t esp_lcd_panel_disp_on_off(esp_lcd_panel_handle_t panel, bool on_off) return panel->disp_on_off(panel, on_off); } -esp_err_t esp_lcd_panel_disp_off(esp_lcd_panel_handle_t panel, bool off) -{ - return esp_lcd_panel_disp_on_off(panel, !off); -} - esp_err_t esp_lcd_panel_disp_sleep(esp_lcd_panel_handle_t panel, bool sleep) { ESP_RETURN_ON_FALSE(panel, ESP_ERR_INVALID_ARG, TAG, "invalid panel handle"); diff --git a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst index ab30315a0c..78e1a8cb70 100644 --- a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst @@ -137,3 +137,14 @@ SDMMC ---------------------------------------------- The legacy Sigma-Delta Modulator driver ``driver/sigmadelta.h`` is deprecated since version 5.0 (see :ref:`deprecate_sdm_legacy_driver`). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the :component:`esp_driver_sdm`, and the header file path is ``driver/sdm.h``. + +LCD +--- + +- The GPIO number type in the LCD driver has been changed from ``int`` to the more type-safe ``gpio_num_t``. For example, instead of using ``5`` as the GPIO number, you now need to use ``GPIO_NUM_5``. +- The ``psram_trans_align`` and ``sram_trans_align`` members in the :cpp:type:`esp_lcd_i80_bus_config_t` structure have been replaced by the :cpp:member:`esp_lcd_i80_bus_config_t::dma_burst_size` member, which sets the DMA burst transfer size. +- The ``psram_trans_align`` and ``sram_trans_align`` members in the :cpp:type:`esp_lcd_rgb_panel_config_t` structure have also been replaced by the :cpp:member:`esp_lcd_rgb_panel_config_t::dma_burst_size` member for configuring the DMA burst transfer size. +- The ``octal_mode`` and ``quad_mode`` flags in the :cpp:type:`esp_lcd_panel_io_spi_config_t` structure have been removed. The driver now automatically detects the data line mode of the current SPI bus. +- The ``color_space`` and ``rgb_endian`` configuration options in the :cpp:type:`esp_lcd_panel_dev_config_t` structure have been replaced by the :cpp:member:`esp_lcd_panel_dev_config_t::rgb_ele_order` member, which sets the RGB element order. The corresponding types ``lcd_color_rgb_endian_t`` and ``esp_lcd_color_space_t`` have also been removed; use :cpp:type:`lcd_rgb_element_order_t` instead. +- The ``esp_lcd_panel_disp_off`` function has been removed. Please use the :func:`esp_lcd_panel_disp_on_off` function to control display on/off. +- The ``on_bounce_frame_finish`` member in :cpp:type:`esp_lcd_rgb_panel_event_callbacks_t` has been replaced by :cpp:member:`esp_lcd_rgb_panel_event_callbacks_t::on_frame_buf_complete`, which indicates that a complete frame buffer has been sent to the LCD controller. diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst index dcf0e4ec97..d5349a2c49 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst @@ -137,3 +137,14 @@ SDMMC --------------------------------- 旧版的 Sigma-Delta 调制器驱动 ``driver/sigmadelta.h`` 在 5.0 的版本中就已经被弃用（请参考 :ref:`deprecate_sdm_legacy_driver`）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 :component:`esp_driver_sdm` 组件中，头文件引用路径为 ``driver/sdm.h``。 + +LCD +--- + +- LCD 驱动中的 GPIO 编号已经从 ``int`` 类型修改为更加类型安全的 ``gpio_num_t`` 类型。比如原来使用 ``5`` 作为 GPIO 编号，现在需要使用 ``GPIO_NUM_5``。 +- :cpp:type:`esp_lcd_i80_bus_config_t` 结构体中的 ``psram_trans_align`` 和 ``sram_trans_align`` 均已被 :cpp:member:`esp_lcd_i80_bus_config_t::dma_burst_size` 成员取代，用来设置 DMA 的突发传输大小。 +- :cpp:type:`esp_lcd_rgb_panel_config_t` 结构体中的 ``psram_trans_align`` 和 ``sram_trans_align`` 均已被 :cpp:member:`esp_lcd_rgb_panel_config_t::dma_burst_size` 成员取代，用来设置 DMA 的突发传输大小。 +- :cpp:type:`esp_lcd_panel_io_spi_config_t` 结构体中的 ``octal_mode`` 和 ``quad_mode`` 标志均已删除，驱动已经可以自动探测到当前 SPI 总线的数据线模式。 +- :cpp:type:`esp_lcd_panel_dev_config_t` 结构体中的 ``color_space`` 和 ``rgb_endian`` 配置均已被 :cpp:member:`esp_lcd_panel_dev_config_t::rgb_ele_order` 成员取代，用来设置 RGB 元素的排列顺序。对应的类型 ``lcd_color_rgb_endian_t`` 和 ``esp_lcd_color_space_t`` 也已被移除，请使用 :cpp:type:`lcd_rgb_element_order_t` 替代。 +- ``esp_lcd_panel_disp_off`` 函数已被移除。请使用 :func:`esp_lcd_panel_disp_on_off` 函数来控制显示内容的开关。 +- :cpp:type:`esp_lcd_rgb_panel_event_callbacks_t` 中的 ``on_bounce_frame_finish`` 成员已被 :cpp:member:`esp_lcd_rgb_panel_event_callbacks_t::on_frame_buf_complete` 成员取代，用于指示一个完整的帧缓冲区已被发送给 LCD 控制器。 diff --git a/examples/peripherals/camera/dvp_spi_lcd/main/dvp_spi_lcd_main.c b/examples/peripherals/camera/dvp_spi_lcd/main/dvp_spi_lcd_main.c index bd9b1855fa..b5c63adcb9 100644 --- a/examples/peripherals/camera/dvp_spi_lcd/main/dvp_spi_lcd_main.c +++ b/examples/peripherals/camera/dvp_spi_lcd/main/dvp_spi_lcd_main.c @@ -91,7 +91,7 @@ static void lcd_display_init(esp_lcd_panel_handle_t *lcd_panel_hdl, esp_lcd_pane ESP_LOGI(TAG, "New ST7789 panel"); const esp_lcd_panel_dev_config_t panel_dev_cfg = { .reset_gpio_num = EXAMPLE_LCD_RST, - .color_space = ESP_LCD_COLOR_SPACE_RGB, + .rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB, .bits_per_pixel = EXAMPLE_RGB565_BITS_PER_PIXEL, }; ESP_ERROR_CHECK(esp_lcd_new_panel_st7789(lcd_io_hdl, &panel_dev_cfg, &panel_handle));