feat: Add a component for parsing external partition tables (IEC-333)

[adokitkat]

Checklist

• Component contains License
• Component contains README.md
• Component contains idf_component.yml file with url field defined
• Component was added to upload job
• Component was added to build job
• Optional: Component contains unit tests
• CI passing

Description

This MR adds a component which can parse and generate external partition tables. Right now it only supports MBR. Adding support for another partition table like GPT is possible but not planned for now.

esp_err_t esp_mbr_parse(void* mbr_buf, esp_ext_part_list_t* part_list, esp_mbr_parse_extra_args_t* extra_args);

esp_err_t esp_mbr_generate(mbr_t* mbr, esp_ext_part_list_t* part_list, esp_mbr_generate_extra_args_t* extra_args);

Parsing a partition table outputs esp_ext_part_list_t structure filled with esp_ext_part_list_item_t items.

typedef struct {
    uint32_t data[1];
    esp_ext_part_signature_type_t type;
} esp_ext_part_list_signature_t;

typedef struct {
    uint64_t address; /*!< Start address in bytes */
    uint64_t size; /*!< Size in bytes */
    uint64_t extra; /*!< Extra information (e.g. LittleFS block size stored in CHS hack, etc.) */
    char *label;
    esp_ext_part_flags_t flags; /*!< Flags for the partition */
    uint8_t type; /*!< Known partition type for this component (usually a part of `esp_ext_part_type_known_t`) */
} esp_ext_part_t;

typedef struct esp_ext_part_list_item_ {
    esp_ext_part_t info;
    SLIST_ENTRY(esp_ext_part_list_item_) next;
} esp_ext_part_list_item_t;

typedef struct {
    esp_ext_part_list_signature_t signature; /*!< Disk signature or identifier */
    SLIST_HEAD(esp_ext_part_list_head_, esp_ext_part_list_item_) head; /*!< Head of the partition list */
    esp_ext_part_list_flags_t flags; /*!< Flags for the partition list */
    esp_ext_part_sector_size_t sector_size; /*!< Sector size (storage medium property) */
} esp_ext_part_list_t;

When generating MBR, user can decide on sector size (512B, 4KiB) and partition alignment (4KiB, 1MiB). The defaults are 512B sector size and 1MiB partition alignment.

Note: Generating MBR doesn't mean formatting any partition on given sector span, however helper function could be created which would combine this behavior - each partition type has it's own formatting function (FATFS formats differently than LittleFS, etc.).

These are recognized types:

typedef enum {
    ESP_EXT_PART_TYPE_UNKNOWN = 0,
    ESP_EXT_PART_TYPE_FAT12,
    ESP_EXT_PART_TYPE_FAT16, /*!< FAT16 with LBA addressing */
    ESP_EXT_PART_TYPE_FAT32, /*!< FAT32 with LBA addressing */
    ESP_EXT_PART_TYPE_LITTLEFS, /*!< Possibly LittleFS (MBR CHS field => LittleFS block size hack) */
// Note: The following types are not supported, but we can return a type for them
    ESP_EXT_PART_TYPE_LINUX_ANY, /*!< Linux partition (any type) */
    ESP_EXT_PART_TYPE_EXFAT_OR_NTFS, /*!< Not supported, but we can return a type for it */
    ESP_EXT_PART_TYPE_GPT_PROTECTIVE_MBR, /*!< Not supported, but we can return a type for it */
} esp_ext_part_type_known_t;

Future TODOs and could haves:

• FATFS and this component is right now not coupled - it would be nice to add a function to FATFS or VFS, which could return FAT type of a partition, so it ca be used in this component.
• Add support for BDL and generic BDL partition components, also probably PR to esp_littlefs repo
• Support formatting along with partitioning?
• Maybe add something like ESP_EXT_PART_TYPE_FAT_ANY and a function which inspects a FAT partition and decides on a correct type? This would require BDL.

[CLAassistant]

All committers have signed the CLA.

[adokitkat]

@igrr @pacucha42 please take a look

[pacucha42]

The code base looks good to me, however, I left few questions here and there. Thanks for you efforts @adokitkat !

Generally, it would be great to provide more explanations and in-code comments.

[pacucha42]

@adokitkat - all my comments seem addressed. LGTM, thanks.

Please, also revisit your future updates/todos in this PR description and create appropriate trackers.

[pacucha42]

Approved

[huming2207]

Hey @adokitkat I've got a question about this MBR library. How can I specify a custom partition type?

For example I've got a SD card, the first partition is a FAT32 partition for generic storage, and the second partition is my own SQLite3 running directly on raw SD card block sport (see https://github.com/huming2207/sqlite3-sdmmc). According to Wikipedia article about this https://en.wikipedia.org/wiki/Partition_type I might need to assign the second partition with type 0xDA. How can I achieve that?

[adokitkat]

Hey @adokitkat I've got a question about this MBR library. How can I specify a custom partition type?

Hi @huming2207. Good question. I have added new function pointer arguments to both esp_mbr_parse_extra_args_t and esp_mbr_generate_extra_args_t structs which you can use to pass your own custom MBR type <-> internal type conversion/parsing functions, as well as exposed the default functions in esp_mbr_utils.h (esp_mbr_generate_default_supported_partition_types, esp_mbr_parse_default_supported_partition_types), so you can e.g. wrap them and add your custom types that way.

What do you think about it?

[huming2207]

I have added new function pointer arguments to both esp_mbr_parse_extra_args_t and esp_mbr_generate_extra_args_t structs which you can use to pass your own custom MBR type <-> internal type conversion/parsing functions, as well as exposed the default functions in esp_mbr_utils.h (esp_mbr_generate_default_supported_partition_types, esp_mbr_parse_default_supported_partition_types), so you can e.g. wrap them and add your custom types that way.

Thanks @adokitkat I think that looks great.