Skip to content

Commit dc88ac6

Browse files
espressif2022espressif2022
committed
Merge branch 'feat/mmap_appbin' into 'master'
Feat/mmap appbin See merge request ae_group/esp-iot-solution!1246
2 parents 64e68c2 + ca0789b commit dc88ac6

File tree

16 files changed

+626
-173
lines changed

16 files changed

+626
-173
lines changed

‎components/display/tools/esp_mmap_assets/CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# ChangeLog
22

3+
## v1.3.1 (2025-03-17)
4+
5+
* Allow appending files to the end of the app_bin.
6+
37
## v1.3.0 (2024-10-18)
48

59
* CMake Enhancements: Transitioned from Kconfig options to CMake arguments, supporting independent parameters for each partition.

‎components/display/tools/esp_mmap_assets/CMakeLists.txt‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,15 @@
1+
set(PRIV_REQUIRES_LIST spi_flash esp_partition app_update)
2+
3+
if("${IDF_VERSION_MAJOR}.${IDF_VERSION_MINOR}" VERSION_LESS "5.5")
4+
list(APPEND bootloader_support)
5+
else()
6+
list(APPEND esp_bootloader_format)
7+
endif()
8+
19
idf_component_register(
210
SRCS "esp_mmap_assets.c"
311
INCLUDE_DIRS "include"
4-
REQUIRES esp_partition
5-
PRIV_REQUIRES spi_flash
12+
PRIV_REQUIRES ${PRIV_REQUIRES_LIST}
613
)
714

815
include(package_manager)

‎components/display/tools/esp_mmap_assets/README.md‎

Lines changed: 112 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -21,47 +21,132 @@ This module is primarily used for packaging assets (such as images, fonts, etc.)
2121
5. **LVGL-Specific Binary Format Support**:
2222
- Supports image conversion to binary files required by LVGL, ensuring compatibility with the LVGL graphics library and optimizing performance for display rendering.
2323

24+
## Add to Project
2425

25-
## Add to project
26+
Packages from this repository are uploaded to [Espressif's component service](https://components.espressif.com/). You can add them to your project via `idf.py add-dependency`, e.g.
2627

27-
Packages from this repository are uploaded to [Espressif's component service](https://components.espressif.com/).
28-
You can add them to your project via `idf.py add-dependancy`, e.g.
29-
```
30-
idf.py add-dependency esp_mmap_assets
28+
```sh
29+
idf.py add-dependency esp_mmap_assets
3130
```
3231

33-
Alternatively, you can create `idf_component.yml`. More is in [Espressif's documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html).
32+
Alternatively, you can create `idf_component.yml`. More details are available in [Espressif's documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html).
3433

3534
## Usage
3635

3736
### CMake
38-
Optionally, users can opt to have the image automatically flashed together with the app binaries, partition tables, etc. on idf.py flash by specifying FLASH_IN_PROJECT. For example:
37+
38+
The following options are supported. These options allow you to configure various aspects of image handling.
39+
3940
```c
41+
set(options
42+
FLASH_IN_PROJECT,
43+
FLASH_APPEND_APP,
44+
MMAP_SUPPORT_SJPG,
45+
MMAP_SUPPORT_SPNG,
46+
MMAP_SUPPORT_QOI,
47+
MMAP_SUPPORT_SQOI,
48+
MMAP_SUPPORT_RAW,
49+
MMAP_RAW_DITHER,
50+
MMAP_RAW_BGR_MODE)
51+
```
52+
53+
```c
54+
set(one_value_args
55+
MMAP_FILE_SUPPORT_FORMAT,
56+
MMAP_SPLIT_HEIGHT,
57+
MMAP_RAW_FILE_FORMAT)
58+
```
59+
60+
### Option Explanations
61+
62+
#### General Options
63+
64+
- **`FLASH_IN_PROJECT`**: Users can opt to have the image automatically flashed together with the app binaries, partition tables, etc. on `idf.py flash`
65+
- **`FLASH_APPEND_APP`**: Enables appending binary data (`bin`) to the application binary (`app_bin`).
66+
- **`MMAP_FILE_SUPPORT_FORMAT`**: Specifies supported file formats (e.g., `.png`, `.jpg`, `.ttf`).
67+
- **`MMAP_SPLIT_HEIGHT`**: Defines height for image splitting to reduce memory usage. Depends on:
68+
- `MMAP_SUPPORT_SJPG`
69+
- `MMAP_SUPPORT_SPNG`
70+
- `MMAP_SUPPORT_SQOI`
71+
72+
##### General demo
73+
74+
```c
4075
spiffs_create_partition_assets(
4176
my_spiffs_partition
4277
my_folder
4378
FLASH_IN_PROJECT
44-
MMAP_FILE_SUPPORT_FORMAT ".png"
45-
MMAP_SUPPORT_QOI
46-
MMAP_SUPPORT_SQOI
47-
MMAP_SPLIT_HEIGHT 16)
48-
```
49-
Additionally, the following options are supported. These options allow you to configure various aspects of image handling, such as enabling support for different formats (SJPG, SPNG, QOI, SQOI, RAW), and controlling how RAW images are processed.
50-
```c
51-
set(options FLASH_IN_PROJECT, // Defines storage type (flash in project)
52-
MMAP_SUPPORT_SJPG, // Enable support for SJPG format
53-
MMAP_SUPPORT_SPNG, // Enable support for SPNG format
54-
MMAP_SUPPORT_QOI, // Enable support for QOI format
55-
MMAP_SUPPORT_SQOI, // Enable support for SQOI format
56-
MMAP_SUPPORT_RAW, // Enable support for RAW format (LVGL conversion only)
57-
MMAP_RAW_DITHER, // Enable dithering for RAW images (LVGL conversion only)
58-
MMAP_RAW_BGR_MODE) // Enable BGR mode for RAW images (LVGL conversion only)
59-
60-
set(one_value_args MMAP_FILE_SUPPORT_FORMAT, // Specify supported file format (e.g., .png, .jpg)
61-
MMAP_SPLIT_HEIGHT, // Define the height for image splitting
62-
MMAP_RAW_FILE_FORMAT) // Specify the file format for RAW images (LVGL conversion only)
79+
MMAP_FILE_SUPPORT_FORMAT ".jpg,.png,.ttf"
80+
)
81+
```
6382

64-
```
83+
#### Supported Image Formats
84+
85+
- **`MMAP_SUPPORT_SJPG`**: Enables support for **SJPG** format.
86+
- **`MMAP_SUPPORT_SPNG`**: Enables support for **SPNG** format.
87+
- **`MMAP_SUPPORT_QOI`**: Enables support for **QOI** format.
88+
- **`MMAP_SUPPORT_SQOI`**: Enables support for **SQOI** format. Depends on:
89+
- `MMAP_SUPPORT_QOI`
90+
91+
##### Image Splitting Demo
92+
93+
```c
94+
spiffs_create_partition_assets(
95+
my_spiffs_partition
96+
my_folder
97+
FLASH_IN_PROJECT
98+
MMAP_FILE_SUPPORT_FORMAT ".jpg"
99+
MMAP_SUPPORT_SJPG
100+
MMAP_SPLIT_HEIGHT 16
101+
)
102+
```
103+
104+
#### LVGL Bin Support
105+
106+
- **`MMAP_SUPPORT_RAW`**: Converts images to LVGL-supported **Binary** data.
107+
108+
**References:**
109+
- LVGL v8: [Use detailed reference](https://github.com/W-Mai/lvgl_image_converter)
110+
- LVGL v9: [Use detailed reference](https://github.com/lvgl/lvgl/blob/master/scripts/LVGLImage.py)
111+
112+
- **`MMAP_RAW_FILE_FORMAT`**: Specifies file format for **RAW** images.
113+
- **LVGL v8**: `{true_color, true_color_alpha, true_color_chroma, indexed_1, indexed_2, indexed_4, indexed_8, alpha_1, alpha_2, alpha_4, alpha_8, raw, raw_alpha, raw_chroma}`
114+
- **LVGL v9**: Not used.
115+
116+
- **`MMAP_RAW_COLOR_FORMAT`**: Specifies color format for **RAW** images.
117+
- **LVGL v8**: `{RGB332, RGB565, RGB565SWAP, RGB888}`
118+
- **LVGL v9**: `{L8, I1, I2, I4, I8, A1, A2, A4, A8, ARGB8888, XRGB8888, RGB565, RGB565A8, ARGB8565, RGB888, AUTO, RAW, RAW_ALPHA}`
119+
120+
- **`MMAP_RAW_DITHER`**: Enables **dithering** for **RAW** images.
121+
- **LVGL v8**: Requires dithering.
122+
- **LVGL v9**: Not used.
123+
124+
- **`MMAP_RAW_BGR_MODE`**: Enables **BGR mode** for **RAW** images.
125+
- **LVGL v8**: Not used.
126+
- **LVGL v9**: Not used.
127+
128+
##### LVGL v9 demo
129+
130+
```c
131+
spiffs_create_partition_assets(
132+
.........
133+
MMAP_FILE_SUPPORT_FORMAT ".png"
134+
MMAP_SUPPORT_RAW
135+
MMAP_RAW_COLOR_FORMAT "ARGB8888"
136+
)
137+
```
138+
139+
##### LVGL v8 demo
140+
141+
```c
142+
spiffs_create_partition_assets(
143+
.........
144+
MMAP_FILE_SUPPORT_FORMAT ".png"
145+
MMAP_SUPPORT_RAW
146+
MMAP_RAW_FILE_FORMAT "true_color_alpha"
147+
MMAP_RAW_COLOR_FORMAT "RGB565SWAP"
148+
)
149+
```
65150

66151
### Initialization
67152
```c

‎components/display/tools/esp_mmap_assets/config_template.json.in‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,6 @@
1616
"support_raw_dither": @support_raw_dither@,
1717
"support_raw_bgr": @support_raw_bgr@,
1818
"support_raw_ff": "@arg_MMAP_RAW_FILE_FORMAT@",
19-
"support_raw_cf": "@arg_MMAP_RAW_COLOR_FORMAT@"
19+
"support_raw_cf": "@arg_MMAP_RAW_COLOR_FORMAT@",
20+
"app_bin_path": "@app_bin_path@"
2021
}

‎components/display/tools/esp_mmap_assets/esp_mmap_assets.c‎

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
2+
* SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
33
*
44
* SPDX-License-Identifier: Apache-2.0
55
*/
@@ -10,6 +10,8 @@
1010
#include <spi_flash_mmap.h>
1111
#include <esp_attr.h>
1212
#include <esp_partition.h>
13+
#include "esp_ota_ops.h"
14+
#include "esp_image_format.h"
1315
#include "esp_mmap_assets.h"
1416

1517
static const char *TAG = "mmap_assets";
@@ -76,7 +78,10 @@ esp_err_t mmap_assets_new(const mmap_assets_config_t *config, mmap_assets_handle
7678

7779
map_asset->flags.mmap_enable = config->flags.mmap_enable;
7880

79-
const esp_partition_t *partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, config->partition_label);
81+
const esp_partition_t *running = esp_ota_get_running_partition();
82+
ESP_GOTO_ON_FALSE(running, ESP_ERR_NOT_FOUND, err, TAG, "Can not find running partition");
83+
84+
const esp_partition_t *partition = esp_partition_find_first(ESP_PARTITION_TYPE_ANY, ESP_PARTITION_SUBTYPE_ANY, config->partition_label);
8085
ESP_GOTO_ON_FALSE(partition, ESP_ERR_NOT_FOUND, err, TAG, "Can not find \"%s\" in partition table", config->partition_label);
8186
map_asset->partition = partition;
8287

@@ -85,15 +90,34 @@ esp_err_t mmap_assets_new(const mmap_assets_config_t *config, mmap_assets_handle
8590
uint32_t stored_chksum = 0;
8691
uint32_t calculated_checksum = 0;
8792

93+
uint32_t offset = 0;
94+
uint32_t size = 0;
95+
96+
if ((partition->address == running->address) && (partition->size == running->size)) {
97+
98+
const esp_partition_pos_t part = {
99+
.offset = running->address,
100+
.size = running->size,
101+
};
102+
esp_image_metadata_t metadata;
103+
esp_image_get_metadata(&part, &metadata);
104+
105+
offset = metadata.image_len;
106+
ESP_LOGD(TAG, "partition:%s(0x%x), offset:0x%X", partition->label, (unsigned int)partition->address, (unsigned int)offset);
107+
ESP_GOTO_ON_FALSE(partition->size > offset, ESP_ERR_INVALID_SIZE, err, TAG, "Partition %s size is insufficient", partition->label);
108+
}
109+
110+
size = partition->size - offset;
111+
88112
if (map_asset->flags.mmap_enable) {
89113
int free_pages = spi_flash_mmap_get_free_pages(ESP_PARTITION_MMAP_DATA);
90114
uint32_t storage_size = free_pages * 64 * 1024;
91115
ESP_LOGD(TAG, "The storage free size is %ld KB", storage_size / 1024);
92-
ESP_LOGD(TAG, "The partition size is %ld KB", partition->size / 1024);
93-
ESP_GOTO_ON_FALSE((storage_size > partition->size), ESP_ERR_INVALID_SIZE, err, TAG, "The free size is less than %s partition required", partition->label);
116+
ESP_LOGD(TAG, "The partition size is %ld KB", size / 1024);
117+
ESP_GOTO_ON_FALSE((storage_size > size), ESP_ERR_INVALID_SIZE, err, TAG, "The free size is less than %s partition required", partition->label);
94118

95119
mmap_handle = (esp_partition_mmap_handle_t *)malloc(sizeof(esp_partition_mmap_handle_t));
96-
ESP_GOTO_ON_ERROR(esp_partition_mmap(partition, 0, partition->size, ESP_PARTITION_MMAP_DATA, &root, mmap_handle), err, TAG, "esp_partition_mmap failed");
120+
ESP_GOTO_ON_ERROR(esp_partition_mmap(partition, offset, size, ESP_PARTITION_MMAP_DATA, &root, mmap_handle), err, TAG, "esp_partition_mmap failed");
97121

98122
stored_files = *(int *)(root + ASSETS_FILE_NUM_OFFSET);
99123
stored_chksum = *(uint32_t *)(root + ASSETS_CHECKSUM_OFFSET);
@@ -275,7 +299,7 @@ const uint8_t *mmap_assets_get_mem(mmap_assets_handle_t handle, int index)
275299
}
276300
}
277301

278-
const char * mmap_assets_get_name(mmap_assets_handle_t handle, int index)
302+
const char *mmap_assets_get_name(mmap_assets_handle_t handle, int index)
279303
{
280304
assert(handle && "handle is invalid");
281305
mmap_assets_t *map_asset = (mmap_assets_t *)(handle);

‎components/display/tools/esp_mmap_assets/idf_component.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
version: 1.3.0
1+
version: 1.3.1
22
targets:
33
- esp32
44
- esp32c2
@@ -13,7 +13,8 @@ dependencies:
1313
version: 0.*
1414
idf:
1515
version: '>=5.0'
16-
description: assets mmap tool
16+
description: Tool for packaging and managing resource files into bin files using memory mapping for efficient asset handling.
17+
1718
issues: https://github.com/espressif/esp-iot-solution/issues
1819
repository: git://github.com/espressif/esp-iot-solution.git
1920
url: https://github.com/espressif/esp-iot-solution/tree/master/components/display/tools/esp_mmap_assets

‎components/display/tools/esp_mmap_assets/include/esp_mmap_assets.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ size_t mmap_assets_copy_mem(mmap_assets_handle_t handle, size_t offset, void *de
8989
*
9090
* @return Pointer to the asset name, or NULL if index is invalid.
9191
*/
92-
const char * mmap_assets_get_name(mmap_assets_handle_t handle, int index);
92+
const char *mmap_assets_get_name(mmap_assets_handle_t handle, int index);
9393

9494
/**
9595
* @brief Get the size of the asset at the specified index.

‎components/display/tools/esp_mmap_assets/project_include.cmake‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
function(spiffs_create_partition_assets partition base_dir)
66
# Define option flags (BOOL)
77
set(options FLASH_IN_PROJECT
8+
FLASH_APPEND_APP
89
MMAP_SUPPORT_SJPG
910
MMAP_SUPPORT_SPNG
1011
MMAP_SUPPORT_QOI
@@ -171,30 +172,46 @@ function(spiffs_create_partition_assets partition base_dir)
171172
string(TOLOWER "${arg_MMAP_RAW_DITHER}" support_raw_dither)
172173
string(TOLOWER "${arg_MMAP_RAW_BGR_MODE}" support_raw_bgr)
173174

174-
set(CONFIG_FILE_PATH "${CMAKE_BINARY_DIR}/mmap_build/${base_dir_name}/config.json")
175+
set(app_bin_path "${CMAKE_BINARY_DIR}/${CMAKE_PROJECT_NAME}.bin")
176+
177+
set(CONFIG_FILE_PATH "${CMAKE_BINARY_DIR}/mmap_build/${base_dir_name}.json")
175178
configure_file(
176179
"${TARGET_COMPONENT_PATH}/config_template.json.in"
177180
"${CONFIG_FILE_PATH}"
178181
@ONLY
179182
)
180183

181-
add_custom_target(spiffs_${partition}_bin ALL
184+
add_custom_target(assets_${partition}_bin ALL
182185
COMMENT "Move and Pack assets..."
183186
COMMAND python ${MVMODEL_EXE} --config "${CONFIG_FILE_PATH}"
184187
DEPENDS ${arg_DEPENDS}
185188
VERBATIM)
186189

187-
set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY
188-
ADDITIONAL_CLEAN_FILES
189-
${image_file})
190+
if(arg_FLASH_APPEND_APP)
191+
add_custom_target(assets_${partition}_merge_bin ALL
192+
COMMENT "Merge Bin..."
193+
COMMAND python ${TARGET_COMPONENT_PATH}/spiffs_assets_gen.py --config "${CONFIG_FILE_PATH}" --merge
194+
COMMAND ${CMAKE_COMMAND} -E rm "${build_dir}/.bin_timestamp" # Remove the timestamp file to force re-run
195+
DEPENDS assets_${partition}_bin app
196+
VERBATIM)
197+
endif()
190198

191199
if(arg_FLASH_IN_PROJECT)
192-
esptool_py_flash_to_partition(flash "${partition}" "${image_file}")
193-
add_dependencies(flash spiffs_${partition}_bin)
200+
set(assets_target "assets_${partition}_bin")
201+
202+
if(arg_FLASH_APPEND_APP)
203+
set(assets_target "assets_${partition}_merge_bin")
204+
add_dependencies(app-flash ${assets_target})
205+
else()
206+
esptool_py_flash_to_partition(flash "${partition}" "${image_file}")
207+
endif()
208+
209+
add_dependencies(flash ${assets_target})
194210
endif()
211+
195212
else()
196213
set(message "Failed to create assets bin for partition '${partition}'. "
197214
"Check project configuration if using the correct partition table file.")
198-
fail_at_build_time(spiffs_${partition}_bin "${message}")
215+
fail_at_build_time(assets_${partition}_bin "${message}")
199216
endif()
200217
endfunction()

0 commit comments

Comments
 (0)