diff --git a/components/nvs_flash/project_include.cmake b/components/nvs_flash/project_include.cmake new file mode 100644 index 0000000000..a427c1ed01 --- /dev/null +++ b/components/nvs_flash/project_include.cmake @@ -0,0 +1,64 @@ +# nvs_create_partition_image +# +# Create a NVS image of the specified CSV on the host during build and +# optionally have the created image flashed using `idf.py flash` +function(nvs_create_partition_image partition csv) + set(options FLASH_IN_PROJECT) + set(one VERSION) + set(multi DEPENDS) + cmake_parse_arguments(arg "${options}" "${one}" "${multi}" "${ARGN}") + + # Default to version 2 + if(NOT DEFINED arg_VERSION) + set(arg_VERSION 2) + endif() + + idf_build_get_property(idf_path IDF_PATH) + set(nvs_partition_gen_py + ${PYTHON} + ${idf_path}/components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py + ) + + get_filename_component(csv_full_path ${csv} ABSOLUTE) + + partition_table_get_partition_info(size "--partition-name ${partition}" "size") + partition_table_get_partition_info(offset "--partition-name ${partition}" "offset") + + if("${size}" AND "${offset}") + set(image_file ${CMAKE_BINARY_DIR}/${partition}.bin) + + add_custom_command( + OUTPUT ${image_file} + COMMAND ${nvs_partition_gen_py} generate --version ${arg_VERSION} ${csv_full_path} ${image_file} ${size} + MAIN_DEPENDENCY ${csv_full_path} + DEPENDS ${arg_DEPENDS} + COMMENT "Generating NVS partition image for ${partition} from ${csv}" + ) + + add_custom_target(nvs_${partition}_bin ALL DEPENDS ${image_file}) + + set_property( + DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" + APPEND + PROPERTY ADDITIONAL_CLEAN_FILES ${image_file} + ) + + idf_component_get_property(main_args esptool_py FLASH_ARGS) + idf_component_get_property(sub_args esptool_py FLASH_SUB_ARGS) + esptool_py_flash_target(${partition}-flash "${main_args}" "${sub_args}" ALWAYS_PLAINTEXT) + esptool_py_flash_to_partition(${partition}-flash "${partition}" "${image_file}") + + add_dependencies(${partition}-flash nvs_${partition}_bin) + + if(arg_FLASH_IN_PROJECT) + esptool_py_flash_to_partition(flash "${partition}" "${image_file}") + add_dependencies(flash nvs_${partition}_bin) + endif() + else() + set(message + "Failed to create NVS image for partition '${partition}'. " + "Check project configuration if using the correct partition table file." + ) + fail_at_build_time(nvs_${partition}_bin "${message}") + endif() +endfunction() diff --git a/docs/en/api-reference/storage/nvs_flash.rst b/docs/en/api-reference/storage/nvs_flash.rst index fefd079e1f..4ed71d82d2 100644 --- a/docs/en/api-reference/storage/nvs_flash.rst +++ b/docs/en/api-reference/storage/nvs_flash.rst @@ -92,6 +92,40 @@ NVS Partition Generator Utility This utility helps generate NVS partition binary files which can be flashed separately on a dedicated partition via a flashing utility. Key-value pairs to be flashed onto the partition can be provided via a CSV file. For more details, please refer to :doc:`nvs_partition_gen`. +Instead of calling the ``nvs_partition_gen.py`` tool manually, the creation of the partition binary files can also be done directly from CMake using the function ``nvs_create_partition_image``:: + + nvs_create_partition_image( [FLASH_IN_PROJECT] [VERSION 1 | 2] [DEPENDS dep dep dep ...]) + +**Positional Arguments**: + ++---------------+---------------------------------------------------------------+ +| Parameter | Description | ++===============+===============================================================+ +| ``partition`` | Name of the NVS parition | ++---------------+---------------------------------------------------------------+ +| ``csv`` | Path to CSV file to parse | ++---------------+---------------------------------------------------------------+ + +**Optional Arguments**: + ++----------------------+----------------------------------------------------------------------+ +| Parameter | Description | ++======================+======================================================================+ +| ``FLASH_IN_PROJECT`` | Flash the image when using ``idf.py flash`` | ++----------------------+----------------------------------------------------------------------+ +| ``VERSION`` | Set multipage blob version (Default: Version 2) | +| | | +| | Version 1 - Multipage blob support disabled | +| | | +| | Version 2 - Multipage blob support enabled | ++----------------------+----------------------------------------------------------------------+ +| ``DEPENDS`` | Specify files on which the command depends | ++----------------------+----------------------------------------------------------------------+ + +If FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``idf.py -flash`` (e.g. if your parition name is ``nvs`` ``idf.py nvs-flash``). + +``nvs_create_partition_image`` must be called from one of the component ``CMakeLists.txt`` files. Currently only non-encrypted partitions are supported. + Application Example -------------------