docs: Explain custom partition types/subtypes in more detail

Including how to use with C++ (closes https://github.com/espressif/esp-idf/pull/1832)

components/spi_flash/include/esp_partition.h

@@ -35,7 +35,12 @@ extern "C" {
 
 /**
  * @brief Partition type
- * @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
+ *
+ * @note Partition types with integer value 0x00-0x3F are reserved for partition types defined by ESP-IDF.
+ * Any other integer value 0x40-0xFE can be used by individual applications, without restriction.
+ *
+ * @internal Keep this enum in sync with PartitionDefinition class gen_esp32part.py @endinternal
+ *
  */
 typedef enum {
     ESP_PARTITION_TYPE_APP = 0x00,       //!< Application partition type
@@ -44,7 +49,13 @@ typedef enum {
 
 /**
  * @brief Partition subtype
- * @note Keep this enum in sync with PartitionDefinition class gen_esp32part.py
+ *
+ * @note These ESP-IDF-defined partition subtypes apply to partitions of type ESP_PARTITION_TYPE_APP
+ * and ESP_PARTITION_TYPE_DATA.
+ *
+ * Application-defined partition types (0x40-0xFE) can set any numeric subtype value.
+ *
+ * @internal Keep this enum in sync with PartitionDefinition class gen_esp32part.py @endinternal
  */
 typedef enum {
     ESP_PARTITION_SUBTYPE_APP_FACTORY = 0x00,                                 //!< Factory application partition
@@ -112,10 +123,9 @@ typedef struct {
 /**
  * @brief Find partition based on one or more parameters
  *
- * @param type Partition type, one of esp_partition_type_t values
- * @param subtype Partition subtype, one of esp_partition_subtype_t values.
- *                To find all partitions of given type, use
- *                ESP_PARTITION_SUBTYPE_ANY.
+ * @param type Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer
+ * @param subtype Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer.
+ *                To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
  * @param label (optional) Partition label. Set this value if looking
  *             for partition with a specific name. Pass NULL otherwise.
  *
@@ -129,10 +139,9 @@ esp_partition_iterator_t esp_partition_find(esp_partition_type_t type, esp_parti
 /**
  * @brief Find first partition based on one or more parameters
  *
- * @param type Partition type, one of esp_partition_type_t values
- * @param subtype Partition subtype, one of esp_partition_subtype_t values.
- *                To find all partitions of given type, use
- *                ESP_PARTITION_SUBTYPE_ANY.
+ * @param type Partition type, one of esp_partition_type_t values or an 8-bit unsigned integer
+ * @param subtype Partition subtype, one of esp_partition_subtype_t values or an 8-bit unsigned integer
+ *                To find all partitions of given type, use ESP_PARTITION_SUBTYPE_ANY.
  * @param label (optional) Partition label. Set this value if looking
  *             for partition with a specific name. Pass NULL otherwise.
  *
@@ -333,9 +342,9 @@ bool esp_partition_check_identity(const esp_partition_t *partition_1, const esp_
  * @param offset  Address in bytes, where the partition starts
  * @param size  Size of the partition in bytes
  * @param label  Partition name
- * @param type  One of the partition types (ESP_PARTITION_TYPE_*). Note that applications can not be booted from external flash
+ * @param type  One of the partition types (ESP_PARTITION_TYPE_*), or an integer. Note that applications can not be booted from external flash
  *              chips, so using ESP_PARTITION_TYPE_APP is not supported.
- * @param subtype  One of the partition subtypes (ESP_PARTITION_SUBTYPE_*)
+ * @param subtype  One of the partition subtypes (ESP_PARTITION_SUBTYPE_*), or an integer.
  * @param[out] out_partition  Output, if non-NULL, receives the pointer to the resulting esp_partition_t structure
  * @return
  *      - ESP_OK on success

docs/en/api-guides/partition-tables.rst

@@ -7,7 +7,7 @@ Overview
 
 A single {IDF_TARGET_NAME}'s flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
 
-Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table.
+Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data.
 
 Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
 
@@ -74,57 +74,71 @@ Name field can be any meaningful name. It is not significant to the {IDF_TARGET_
 Type field
 ~~~~~~~~~~
 
-Partition type field can be specified as app (0) or data (1). Or it can be a number 0-254 (or as hex 0x00-0xFE). Types 0x00-0x3F are reserved for esp-idf core functions.
+Partition type field can be specified as ``app`` (0x00) or ``data`` (0x01). Or it can be a number 0-254 (or as hex 0x00-0xFE). Types 0x00-0x3F are reserved for ESP-IDF core functions.
 
-If your application needs to store data, please add a custom partition type in the range 0x40-0xFE.
+If your app needs to store data in a format not already supported by ESP-IDF, then please add a custom partition type value in the range 0x40-0xFE.
 
-The bootloader ignores any partition types other than app (0) & data (1).
+See :cpp:type:`esp_partition_type_t` for the enum definitions for ``app`` and ``data`` partitions.
+
+If writing in C++ then specifying a application-defined partition type requires casting an integer to :cpp:type:`esp_partition_type_t` in order to use it with the :ref:`partition API <api-reference-partition-table>`. For example::
+
+    static const esp_partition_type_t APP_PARTITION_TYPE_A = (esp_partition_type_t)0x40;
+
+The ESP-IDF bootloader ignores any partition types other than ``app`` (0x00) and ``data`` (0x01).
 
 SubType
 ~~~~~~~
 
-The 8-bit subtype field is specific to a given partition type. esp-idf currently only specifies the meaning of the subtype field for "app" and "data" partition types.
+The 8-bit subtype field is specific to a given partition type. ESP-IDF currently only specifies the meaning of the subtype field for ``app`` and ``data`` partition types.
+
+See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defined by ESP-IDF, including the following:
 
-* When type is "app", the subtype field can be specified as factory (0), ota_0 (0x10) ... ota_15 (0x1F) or test (0x20).
+* When type is ``app``, the subtype field can be specified as ``factory`` (0x00), ``ota_0`` (0x10) ... ``ota_15`` (0x1F) or ``test`` (0x20).
 
-  - factory (0) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.
+  - ``factory`` (0x00) is the default app partition. The bootloader will execute the factory app unless there it sees a partition of type data/ota, in which case it reads this partition to determine which OTA image to boot.
 
     - OTA never updates the factory partition.
-    - If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ota_0 instead.
-  - ota_0 (0x10) ... ota_15 (0x1F) are the OTA app slots. Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details, which then use the OTA data partition to configure which app slot the bootloader should boot. If using OTA, an application should have at least two OTA application slots (ota_0 & ota_1). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
-  - test (0x20) is a reserved subtype for factory test procedures. It will be used as the fallback boot partition if no other valid app partition is found. It is also possible to configure the bootloader to read a GPIO input during each boot, and boot this partition if the GPIO is held low, see :ref:`bootloader_boot_from_test_firmware`.
+    - If you want to conserve flash usage in an OTA project, you can remove the factory partition and use ``ota_0`` instead.
+  - ``ota_0`` (0x10) ... ``ota_15`` (0x1F) are the OTA app slots. When :doc:`OTA <../api-reference/system/ota>` is in use, the OTA data partition configures which app slot the bootloader should boot. When using OTA, an application should have at least two OTA application slots (``ota_0`` & ``ota_1``). Refer to the :doc:`OTA documentation <../api-reference/system/ota>` for more details.
+  - ``test`` (0x20) is a reserved subtype for factory test procedures. It will be used as the fallback boot partition if no other valid app partition is found. It is also possible to configure the bootloader to read a GPIO input during each boot, and boot this partition if the GPIO is held low, see :ref:`bootloader_boot_from_test_firmware`.
 
-* When type is "data", the subtype field can be specified as ota (0), phy (1), nvs (2), or nvs_keys (4).
+* When type is ``data``, the subtype field can be specified as ``ota`` (0x00), ``phy`` (0x01), ``nvs`` (0x02), nvs_keys (0x04), or a range of other component-specific subtypes (see :cpp:type:`subtype enum <esp_partition_subtype_t>`).
 
-  - ota (0) is the :ref:`OTA data partition <ota_data_partition>` which stores information about the currently selected OTA application. This partition should be 0x2000 bytes in size. Refer to the :ref:`OTA documentation <ota_data_partition>` for more details.
-  - phy (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.
+  - ``ota`` (0) is the :ref:`OTA data partition <ota_data_partition>` which stores information about the currently selected OTA app slot. This partition should be 0x2000 bytes in size. Refer to the :ref:`OTA documentation <ota_data_partition>` for more details.
+  - ``phy`` (1) is for storing PHY initialisation data. This allows PHY to be configured per-device, instead of in firmware.
 
     - In the default configuration, the phy partition is not used and PHY initialisation data is compiled into the app itself. As such, this partition can be removed from the partition table to save space.
     - To load PHY data from this partition, open the project configuration menu (``idf.py menuconfig``) and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION` option. You will also need to flash your devices with phy init data as the esp-idf build system does not do this automatically.
-  - nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
+  - ``nvs`` (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`.
 
     - NVS is used to store per-device PHY calibration data (different to initialisation data).
     - NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/network/esp_wifi>` initialisation function is used.
     - The NVS API can also be used for other application data.
     - It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project.
     - If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes.
-  - nvs_keys (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details.
+  - ``nvs_keys`` (4) is for the NVS key partition. See :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>` for more details.
 
     - It is used to store NVS encryption keys when `NVS Encryption` feature is enabled.
     - The size of this partition should be 4096 bytes (minimum partition size).
 
-Other data subtypes are reserved for future esp-idf uses.
+  - There are other predefined data subtypes for data storage supported by ESP-IDF. These include :doc:`FAT filesystem </api-reference/storage/fatfs>` (:cpp:enumerator:`ESP_PARTITION_SUBTYPE_DATA_FAT`), :doc:`SPIFFS </api-reference/storage/spiffs>` (:cpp:enumerator:`ESP_PARTITION_SUBTYPE_DATA_SPIFFS`), etc.
+
+  Other subtypes of ``data`` type are reserved for future ESP-IDF uses.
+
+* If the partition type is any application-defined value (range 0x40-0xFE), then ``subtype`` field can be any value chosen by the application (range 0x00-0xFE).
+
+  Note that when writing in C++, an application-defined subtype value requires casting to type :cpp:type:`esp_partition_subtype_t` in order to use it with the :ref:`partition API <api-reference-partition-table>`.
 
 Offset & Size
 ~~~~~~~~~~~~~
 
-Partitions with blank offsets will start after the previous partition, or after the partition table in the case of the first partition.
+Partitions with blank offsets in the CSV file will start after the previous partition, or after the partition table in the case of the first partition.
 
-App partitions have to be at offsets aligned to 0x10000 (64K). If you leave the offset field blank,  ``gen_esp32part.py`` will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error.
+Partitions of type ``app`` have to be placed at offsets aligned to 0x10000 (64K). If you leave the offset field blank,  ``gen_esp32part.py`` will automatically align the partition. If you specify an unaligned offset for an app partition, the tool will return an error.
 
 Sizes and offsets can be specified as decimal numbers, hex numbers with the prefix 0x, or size multipliers K or M (1024 and 1024*1024 bytes).
 
-If you want the partitions in the partition table to work with any starting offset (:ref:`CONFIG_PARTITION_TABLE_OFFSET`) of the table itself, leave the offset field (in CSV file) for all partitions blank. Similarly, if changing the partition table offset then be aware that all blank partition offsets may change to match, and that any fixed offsets may now collide with the partition table (causing an error).
+If you want the partitions in the partition table to work relative to any placement (:ref:`CONFIG_PARTITION_TABLE_OFFSET`) of the table itself, leave the offset field (in CSV file) for all partitions blank. Similarly, if changing the partition table offset then be aware that all blank partition offsets may change to match, and that any fixed offsets may now collide with the partition table (causing an error).
 
 Flags
 ~~~~~

docs/en/api-reference/storage/spi_flash.rst

@@ -35,6 +35,8 @@ API Reference - SPI Flash
 .. include-build-file:: inc/esp_flash.inc
 .. include-build-file:: inc/spi_flash_types.inc
 
+.. _api-reference-partition-table:
+
 API Reference - Partition Table
 -------------------------------