feat: Add example code

To be squashed

Author: adokitkat

esp_ext_part_tables/examples/basic/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.16)
+
+set(COMPONENTS main)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(esp_ext_part_tables_example_basic)

esp_ext_part_tables/examples/basic/README.md

@@ -0,0 +1,66 @@
+# esp_ext_part_tables basic example
+
+This example demonstrates how to use an ESP32 to read and parse the Master Boot Record (MBR) from a (micro)SD card. It shows how to extract and display information about the card's partitions, such as their type, size, and starting sector, using the ESP-IDF framework.
+
+## Requirements
+
+- any ESP32 board which supports SPI with a (micro)SD card slot or breakout board connected
+- formatted (micro)SD card using MBR (not GPT) as a partition table
+
+## Build and Flash
+
+The example runs on any ESP development board with SD card connected via SPI (use `idf.py menuconfig` -> `Example config` to set used GPIO pins). For example, to build and run the code on ESP32-S3, use:
+
+```
+idf.py set-target esp32s3
+idf.py menuconfig
+idf.py build flash monitor
+```
+
+NOTE 1: This example uses SDSPI instead of SDMMC to connect to SD card due to more ESP32 devices supporting it but it doesn't matter which one one you use in your project to load the first sector containing MBR. 
+
+NOTE 2: ESP-IDF 5.1 or newer enviroment must be set properly before running the example.
+
+## Example output
+
+MicroSD card used in the example showcase has capacity 64GiB and was formatted using Windows Disk Management program to two ~32GiB FAT32 partitions as seen in the picture:
+
+![Screenshot of Disk Management Windows program showing removable Disk 0 (a microSD card) containing 2 FAT32 partitions both roughly 30GB is size](/esp_ext_part_tables/examples/basic/assets/two_fat_partitions.png)
+
+The example code parsed the MBR and printed the loaded partition information (`type 4` corresponds to `ESP_EXT_PART_TYPE_FAT32` in `esp_ext_part_type_known_t` enum, etc.). The second task generated MBR from `esp_ext_part_list_t` definition and then parsed it again and printed the output.
+
+```log
+I (275) esp_ext_part_tables_example_basic: Example started
+I (275) esp_ext_part_tables_example_basic: Starting MBR parsing example task
+I (335) esp_ext_part_tables_example_basic: MBR loaded successfully
+I (335) esp_ext_part_tables_example_basic: MBR parsed successfully
+Partition 0:
+        LBA start sector: 2048, address: 1048576,
+        sector count: 59392000, size: 30408704000,
+        type: 4
+
+Partition 1:
+        LBA start sector: 59394048, address: 30409752576,
+        sector count: 62746624, size: 32126271488,
+        type: 4
+
+I (365) esp_ext_part_tables_example_basic: Starting MBR generation example task
+I (365) esp_ext_part_tables_example_basic: MBR generated successfully
+Partition 0:
+        LBA start sector: 2048, address: 1048576,
+        sector count: 7953, size: 4071936,
+        type: 2
+
+Partition 1:
+        LBA start sector: 10240, address: 5242880,
+        sector count: 10240, size: 5242880,
+        type: 2
+
+I (395) esp_ext_part_tables_example_basic: Example ended
+```
+
+Your output will be different based on (micro)SD card used, partitioning and formatting applied.
+
+## Documentation
+
+See the esp_ext_part_tables component's README.md file.

esp_ext_part_tables/examples/basic/assets/two_fat_partitions.png

@@ -0,0 +1,4 @@
+idf_component_register(
+    SRCS "main.c" "example_utils.c"
+    REQUIRES driver sdmmc
+)

esp_ext_part_tables/examples/basic/main/CMakeLists.txt

@@ -0,0 +1,53 @@
+menu "Example Configuration"
+
+    config EXAMPLE_PIN_MOSI
+        int "MOSI GPIO number"
+        default 15 if IDF_TARGET_ESP32
+        default 35 if IDF_TARGET_ESP32S2
+        default 4 if IDF_TARGET_ESP32S3
+        default 5  if IDF_TARGET_ESP32H2
+        default 36 if IDF_TARGET_ESP32P4
+        default 4  # C3 and others
+
+    config EXAMPLE_PIN_MISO
+        int "MISO GPIO number"
+        default 2 if IDF_TARGET_ESP32
+        default 37 if IDF_TARGET_ESP32S2
+        default 5 if IDF_TARGET_ESP32S3
+        default 0  if IDF_TARGET_ESP32H2
+        default 47 if IDF_TARGET_ESP32P4
+        default 6  # C3 and others
+
+    config EXAMPLE_PIN_CLK
+        int "CLK GPIO number"
+        default 14 if IDF_TARGET_ESP32
+        default 36 if IDF_TARGET_ESP32S2
+        default 2 if IDF_TARGET_ESP32S3
+        default 4  if IDF_TARGET_ESP32H2
+        default 53 if IDF_TARGET_ESP32P4
+        default 5  # C3 and others
+
+    config EXAMPLE_PIN_CS
+        int "CS GPIO number"
+        default 13 if IDF_TARGET_ESP32
+        default 34 if IDF_TARGET_ESP32S2
+        default 8 if IDF_TARGET_ESP32S3
+        default 33 if IDF_TARGET_ESP32P4
+        default 1  # C3 and others
+
+    config EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO
+        depends on SOC_SDMMC_IO_POWER_EXTERNAL
+        bool "SD power supply comes from internal LDO IO (READ HELP!)"
+        default n
+        help
+            Only needed when the SD card is connected to specific IO pins which can be used for high-speed SDMMC.
+            Please read the schematic first and check if the SD VDD is connected to any internal LDO output.
+            Unselect this option if the SD card is powered by an external power supply.
+
+    config EXAMPLE_SD_PWR_CTRL_LDO_IO_ID
+        depends on SOC_SDMMC_IO_POWER_EXTERNAL && EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO
+        int "LDO ID"
+        default 4 if IDF_TARGET_ESP32P4
+        help
+            Please read the schematic first and input your LDO ID.
+endmenu

esp_ext_part_tables/examples/basic/main/Kconfig.projbuild

@@ -0,0 +1,100 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdint.h>
+#include "esp_err.h"
+#include "esp_log.h"
+#include "driver/sdspi_host.h"
+#include "sdmmc_cmd.h"
+#if SOC_SDMMC_IO_POWER_EXTERNAL
+#include "sd_pwr_ctrl_by_on_chip_ldo.h"
+#endif
+
+static const char *TAG = "esp_ext_part_tables_example_basic_utils";
+
+#define PIN_NUM_MISO  CONFIG_EXAMPLE_PIN_MISO
+#define PIN_NUM_MOSI  CONFIG_EXAMPLE_PIN_MOSI
+#define PIN_NUM_CLK   CONFIG_EXAMPLE_PIN_CLK
+#define PIN_NUM_CS    CONFIG_EXAMPLE_PIN_CS
+
+esp_err_t load_first_sector_from_sd_card(void* mbr_buffer)
+{
+    // This function loads the first sector (MBR) from the SD card into the provided buffer
+    // It uses SDSPI but can be adapted for SDMMC as well
+    esp_err_t ret = ESP_OK; 
+    sdmmc_host_t host = SDSPI_HOST_DEFAULT();
+
+    // For SoCs where the SD power can be supplied both via an internal or external (e.g. on-board LDO) power supply.
+    // When using specific IO pins (which can be used for ultra high-speed SDMMC) to connect to the SD card
+    // and the internal LDO power supply, we need to initialize the power supply first.
+#if CONFIG_EXAMPLE_SD_PWR_CTRL_LDO_INTERNAL_IO
+    sd_pwr_ctrl_ldo_config_t ldo_config = {
+        .ldo_chan_id = CONFIG_EXAMPLE_SD_PWR_CTRL_LDO_IO_ID,
+    };
+    sd_pwr_ctrl_handle_t pwr_ctrl_handle = NULL;
+
+    ret = sd_pwr_ctrl_new_on_chip_ldo(&ldo_config, &pwr_ctrl_handle);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to create a new on-chip LDO power control driver");
+        return;
+    }
+    host.pwr_ctrl_handle = pwr_ctrl_handle;
+#endif
+
+    spi_bus_config_t bus_cfg = {
+        .mosi_io_num = PIN_NUM_MOSI,
+        .miso_io_num = PIN_NUM_MISO,
+        .sclk_io_num = PIN_NUM_CLK,
+        .quadwp_io_num = -1,
+        .quadhd_io_num = -1,
+        .max_transfer_sz = 4000,
+    };
+
+    ret = spi_bus_initialize(host.slot, &bus_cfg, SDSPI_DEFAULT_DMA);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to initialize bus.");
+        return ret;
+    }
+
+    sdspi_device_config_t slot_config = SDSPI_DEVICE_CONFIG_DEFAULT();
+    slot_config.gpio_cs = PIN_NUM_CS;
+    slot_config.host_id = host.slot;
+
+    ret = host.init();
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to initialize host.");
+        spi_bus_free(host.slot);
+        return ret;
+    }
+
+    int slot = -1;
+    ret = sdspi_host_init_device((const sdspi_device_config_t*)&slot_config, &slot);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to initialize SPI device.");
+        spi_bus_free(host.slot);
+        return ret;
+    }
+    host.slot = slot;
+
+    sdmmc_card_t card = {0};
+    ret = sdmmc_card_init(&host, &card);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to initialize SD card.");
+        spi_bus_free(host.slot);
+        return ret;
+    }
+
+    ret = sdmmc_read_sectors(&card, mbr_buffer, 0, 1);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to read first sector from SD card.");
+        spi_bus_free(host.slot);
+        return ret;
+    }
+
+    return ESP_OK;
+}

esp_ext_part_tables/examples/basic/main/example_utils.c

@@ -0,0 +1,19 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+esp_err_t load_first_sector_from_sd_card(void* mbr_buffer);
+
+#ifdef __cplusplus
+}
+#endif

esp_ext_part_tables/examples/basic/main/example_utils.h

@@ -0,0 +1,4 @@
+dependencies:
+  esp_ext_part_tables:
+    version: "*"
+    override_path: '../../..'