Таблицы разделов¶
Инструмент сборки partition_table из SiFli-SDK читает описание разделов платы и генерирует ptab.h с макросами разделов, которые использует приложение. Таблица разделов описывает адресное пространство всей используемой памяти: NOR Flash, NAND Flash, eMMC, SD-карт, PSRAM и встроенной SRAM.
Для каждой платы задана раскладка памяти по умолчанию, которой следуют все собираемые для неё приложения. Проект может предоставить собственную конфигурацию таблицы разделов, заменяющую настройки платы по умолчанию.
Включение таблиц разделов¶
В настройках промежуточного ПО включите Use partition table to manage all memory layout (использовать таблицу разделов для управления всей разметкой памяти). Кроме того, в Kconfig.proj проекта должна быть следующая настройка; в примерах SiFli-SDK она уже есть.
# APP-specific configuration.
config CUSTOM_MEM_MAP
bool
select custom_mem_map
default y if !SOC_SIMULATOR
Выбор формата¶
SiFli-SDK поддерживает три формата таблиц разделов. Для новых проектов используйте v3, если только существующая плата или продукт не должны сохранить конфигурацию v1/v2.
| Формат | Файл описания | Основная модель | Для новых проектов? |
|---|---|---|---|
| v1 | ptab.json |
Список памяти в JSON, теги и необязательные метаданные ftab, img и exec |
Нет; только для сопровождения старых проектов. |
| v2 | ptab.json |
Список памяти в JSON с именованными типизированными разделами образов и исполнения | Нет; сохраняйте, если от этого формата зависит существующая плата. |
| v3 | ptab.yaml |
Разделы YAML с полями type, subtype, region, exec, генерируемыми макросами и оверлеями проекта |
Да. |
Система сборки сначала ищет ptab.yaml (v3), а при его отсутствии использует ptab.json (v1/v2). Порядок поиска: каталог платы, каталог чипа, корень BSP и customer/boards/<board>/.
v1: теги JSON и метаданные образов¶
В v1 в ptab.json используется массив JSON. Отдельного поля версии нет, но файл может начинаться с элемента заголовка, содержащего "version": "1".
Каждая запись памяти задаёт:
mem: имя памяти, напримерflash2илиpsram1.base: шестнадцатеричный базовый адрес памяти; проверьте его по карте памяти целевого устройства.regions: список разделов в этой памяти.
Для каждого региона задаются offset и max_size в байтах. Список tags региона генерирует макросы разделов. Например, FLASH_BOOT_LOADER создаёт макросы FLASH_BOOT_LOADER_START_ADDR, FLASH_BOOT_LOADER_OFFSET и FLASH_BOOT_LOADER_SIZE; начальный адрес равен base памяти плюс offset региона.
| Поле | Назначение |
|---|---|
ftab |
Описывает запись Flash Table. |
img |
Указывает образ в разделе для генерируемых скриптов прошивки. Если проект создаёт несколько бинарных файлов, используйте proj_name:binary_name. |
exec |
Указывает исполняемую программу, чтобы общие скрипты линковки могли выбрать адрес кода. |
custom |
Добавляет в генерируемый ptab.h пользовательские макросы с целочисленными значениями. |
Для PSRAM документация различает адресные пространства CBUS и SBUS. Задайте exec для раздела CBUS, чтобы код использовал адрес исполнения; если этот адрес используется для копирования кода, укажите xip-адрес ftab в разделе SBUS.
v2: именованные типизированные разделы JSON¶
В v2 также используется ptab.json, но в заголовке обязательно должно быть указано "version": "2". Поля памяти остаются прежними: mem, base и regions. В регионе сохраняются offset и max_size, а также могут использоваться tags и custom; v2 дополнительно вводит name, type и необязательное поле core для раздела исполнения.
| Поле или тип | Значение |
|---|---|
name |
Имя раздела. Имена образов программы должны совпадать с именем соответствующей программы или именем AddCustomImg. Для программы из нескольких файлов можно использовать proj_name:1, proj_name:2 и т. д. |
core |
Ядро, выполняющее раздел app_exec: hcpu, lcpu или acpu. |
app_img |
Основной раздел для хранения образа программы, записываемый инструментом прошивки. |
app_img2 |
Резервный раздел образа программы; обычно используется вместе с основным разделом при обновлении. |
app_exec |
Адресное пространство, из которого выполняется программа. |
bootloader, main, dfu и ftab — зарезервированные имена. Для пользовательских образов можно задавать другие имена, например acpu. Если в таблице не определены разделы ftab и bootloader, инструмент сформирует конфигурацию по умолчанию; перед тем как полагаться на неё, проверьте созданный ptab.h.
v3: разделы YAML и оверлеи¶
В v3 используется ptab.yaml; это рекомендуемый формат. Вместо устаревшей модели tags он вводит явные поля type и subtype, отделяет разделы от физической топологии с помощью логических имён region и во время сборки генерирует ptab.h, ftab.bin и фрагменты скриптов линковки.
| Область | Поле | Обязательно | Значение |
|---|---|---|---|
| Верхний уровень | version |
Да | Должно быть 3. |
| Верхний уровень | chip |
Да | Номер модели чипа, например SF32LB525UC6. |
| Верхний уровень | memory |
Нет | Описание внешней памяти. |
| Верхний уровень | partitions |
Да | Список разделов. |
| Раздел | name, type, region, offset, size |
Да | Идентификатор, тип, логический регион памяти и размещение. Для offset и size можно использовать префикс 0x или суффикс KB/MB. |
| Раздел | subtype, exec, core, attrs |
Нет | Специализация, место исполнения для не-XiP кода, целевое ядро и пользовательские атрибуты. |
В каждом внешнем описании memory указываются интерфейс mpi или sdmmc, значение type (nand, nor или sd) и размер. В region можно ссылаться на эту внешнюю память, hpsys_ram или lpsys_ram.
Каждой region соответствуют адрес хранения SBUS и адрес CBUS для исполнения процессором или XiP. SDK загружает эту карту из данных SiliconSchema для данного чипа. В FAL_PART_TABLE имя устройства определяется областью хранения region раздела, а не exec: mpi1–mpi5 соответствуют NOR_FLASH1_DEV_NAME–NOR_FLASH5_DEV_NAME, а sdmmc1 и sdmmc2 — SDMMC1_DEV_NAME и SDMMC2_DEV_NAME соответственно.
| Тип | Подтип или назначение | Значение |
|---|---|---|
ftab |
— | Раздел Flash Table. |
bootloader |
— | Раздел bootloader. |
app |
factory |
Основное заводское приложение; генерирует CODE_START_ADDR и CODE_SIZE. |
app |
dfu |
Отдельное приложение DFU. |
app |
ex |
Раздел ресурсов. Сборка создаёт выходные файлы образов ресурсов для соответствующей toolchain. |
data |
flashdb_kv |
База данных FlashDB KV; генерирует макросы KVDB_* и включается в FAL_PART_TABLE. |
data |
filesystem, littlefs, fat или fatfs |
В документации указано, что filesystem генерирует макросы FS_REGION_* и включается в FAL_PART_TABLE. В другом разделе littlefs, fat и fatfs также перечислены как подтипы, генерирующие эти макросы, но при этом названы пока не имеющими эффекта; проверьте поведение этих трёх подтипов для целевой версии SDK. В том же описании макросов также используется имя подтипа flashdb, тогда как таблица подтипов и правила FAL используют flashdb_kv; не считайте эти имена псевдонимами без проверки в целевой версии SDK. |
data |
ram, calibration, raw или int_res |
RAM, калибровочные данные, необработанные данные под управлением приложения либо внутренние ресурсы, включённые в ELF и разделяемые по имени секции. |
Автоматически создаваемая в v3 таблица FAL_PART_TABLE включает только data/flashdb_kv, data/filesystem и разделы app, у которых подтип не равен ex. В неё не входят ftab, bootloader, app/ex и другие подтипы data, включая littlefs, fat, fatfs, raw, ram, calibration и int_res. В записях используется имя (name) каждого раздела; старые псевдонимы разметки, такие как main, dfu_code и fs_root, не преобразуются в имена разделов. При переходе на v3 не задавайте FAL_PART_TABLE вручную; удалите имеющийся на уровне платы custom_mem_map.h, чтобы избежать предупреждения о повторном определении.
Для каждого раздела ptab.h генерирует макросы <NAME>_START_ADDR, <NAME>_SIZE и <NAME>_OFFSET, где <NAME> — имя раздела в верхнем регистре. Если тип памяти региона распознан, генерируется также <NAME>_MEM_TYPE. Для раздела app/factory макрос CODE_START_ADDR использует адрес из exec, если он задан; иначе используется адрес CBUS этого раздела.
Используйте exec: {region, offset}, если код нельзя исполнять непосредственно из места хранения, например, если приложение из NAND Flash копируется в PSRAM. Без exec начальный адрес кода вычисляется по адресу хранения раздела в CBUS. Параметр attrs добавляет пользовательские макросы в ptab.h.
Значения по умолчанию и оверлеи проекта¶
В v3 системные разделы по умолчанию выводятся автоматически, если они не заданы явно. Для SF32LB52 flash_table и bootloader можно определить по региону хранения заводского приложения HCPU; для загрузочного хранилища NAND или SDMMC также добавляются описанные в документации стандартные разделы данных. Для SF32LB56 и SF32LB58 можно не задавать flash_table и bootloader во внутренней mpi5. Стандартные окна SiP PSRAM и разделы RAM также можно не указывать, если проект не меняет раскладку RAM.
Для небольшого изменения проекта используйте ptab.overlay.yaml вместо копирования всей таблицы ptab.yaml платы. Оверлей позволяет добавить новый раздел или изменить существующий:
partitions:
- op: override
name: fs_region
size: 5MB
- op: add
name: log_region
type: data
subtype: raw
region: mpi2
offset: 0x00F00000
size: 64KB
Оверлей платы имеет приоритет над оверлеем чипа. Он может изменять только разделы: нельзя менять memory, chip или version, а также удалять разделы. Оверлей применяется только к ptab.yaml v3 на уровне платы и не может использоваться вместе с полной проектной таблицей ptab.yaml или ptab.json. Если плата по-прежнему использует ptab.json (v1/v2) и полная ptab.yaml не выбрана, сборка проигнорирует оверлей с предупреждением и продолжит работу без него. В этом случае ptab.effective.yaml не создаётся. Если оверлей применён, сборка записывает итоговый результат в ptab.effective.yaml для проверки.
Генерируемые файлы и проверка¶
| Результат | Назначение |
|---|---|
ptab.h |
Генерируемый заголовочный файл C с макросами разделов. |
ftab.bin |
Двоичная Flash Table для bootloader. В v3 файл создаётся непосредственно средствами Python, без подпроекта ftab. |
link_copy.lds / link_copy.sct |
Созданные копии скриптов линковки GCC или Keil. В v3 используются шаблоны Jinja2. |
ptab.effective.yaml |
Итоговая таблица v3 после обработки оверлея, если он применён. |
Перед интеграцией проверьте таблицу платы v3:
Проверка контролирует синтаксис имён разделов, допустимость типов и подтипов, корректность регионов, пересечения разделов и уникальность bootloader. Чтобы просмотреть итоговую конфигурацию v3, используемую сборкой, выполните:
sdk.py ptab-export --board=<board-name>
sdk.py ptab-export --board=<board-name> --output /tmp/ptab.effective.yaml
sdk.py ptab-export --strict
Проверка сгенерированной Flash Table¶
После сборки файл ftab.bin появится в каталоге сборки. Инициализируйте среду SDK и просмотрите первый найденный в текущем проекте файл build_*/ftab.bin:
В Windows PowerShell инициализируйте среду командой ./export.ps1. Если в проекте несколько каталогов сборки для разных плат, укажите путь. Для обработки результата скриптом используйте JSON:
sdk.py ftab-dump --path build_<board_name>/ftab.bin
sdk.py ftab-dump --path build_<board_name>/ftab.bin --format json
Таблица содержит записи разделов, описания образов для процессов DFU и загрузки, а также указатели на активные образы HCPU, LCPU, bootloader и boot.
Проверка продукта¶
- Проект намеренно использует таблицу платы либо явно заданную конфигурацию проекта.
- Синтаксис v1, v2 или v3 соответствует файлу, который фактически находит система сборки.
- Адреса хранения и исполнения образов заданы правильно, особенно для памяти без XiP и PSRAM.
- Для разделов приложения, резервной копии, DFU, файловой системы, калибровки и данных приложения достаточно места, и они не пересекаются.
- Проверены
ptab.h,ftab.binи, при использовании оверлеев v3,ptab.effective.yaml. - Процедура аварийной прошивки задокументирована отдельно от обычного пути обновления.
Полные первоисточники см. в официальной документации SiFli-SDK: таблицы разделов, v1, v2 и v3.
Последнее обновление: