SFUD (Serial Flash Universal Driver) Универсальный драйвер для последовательных Flash

0. Что такое SFUD

SFUD — это открытая библиотека для универсального драйвера последовательных Flash по интерфейсу SPI. Из-за большого разнообразия моделей Flash на рынке, а также различий в спецификациях и командах для различных моделей Flash, SFUD был разработан для решения этих проблем, чтобы продукты могли поддерживать Flash разных производителей и спецификаций. Это повышает переиспользуемость и расширяемость программного обеспечения, связанного с Flash, а также позволяет избегать рисков, связанных с дефицитом или прекращением производства Flash.- Основные характеристики: поддержка SPI/QSPI интерфейсов, объектно-ориентированный подход (поддержка нескольких объектов Flash), гибкость в настройке, высокая расширяемость, поддержка 4-байтовых адресов

• Затраты ресурсов:
  • Стандартные затраты: RAM: 0. 2 КБ, ROM: 5. 5 КБ
  • Минимальные затраты: RAM: 0. 1 КБ, ROM: 3. 6 КБ
• Концепция:
  • Что такое SFDP: Это стандарт параметров функций последовательного Flash, разработанный ассоциацией JEDEC (ассоциацией по твердотельным технологиям). Последняя версия V1. 6B (см. здесь). Этот стандарт определяет, что в каждом Flash существует таблица параметров, содержащая спецификации Flash, такие как емкость, размер блока записи, команды стирания, режимы адресации и т. д. В настоящее время, за исключением некоторых старых моделей Flash от некоторых производителей, которые не поддерживают этот стандарт, большинство новых моделей Flash поддерживают стандарт SFDP. Поэтому при инициализации библиотеки сначала читаются параметры из таблицы SFDP.
  • Что делать, если SFDP не поддерживается: Если Flash не поддерживает стандарт SFDP, SFUD будет проверять, поддерживает ли таблица параметров Flash, предоставленная в конфигурационном файле ( [/sfud/inc/sfud_flash_def. h](https://github.com/armink/SFUD/blob/4bee2d0417a7ce853cc7aa3639b03fe825611fd9/sfud/inc/sfud_flash_def. h#L116-L142) ), данную модель Flash.Если поддержка отсутствует, параметры данной модели Flash можно добавить в конфигурационный файл (подробности о добавлении см. в разделе 2.5 Добавление Flash, не поддерживаемого библиотекой). После получения спецификаций Flash можно выполнять все операции с Flash.## 1. Почему следует выбрать SFUD — Избегайте рисков, связанных с нехваткой Flash, прекращением производства Flash или расширением функциональности проекта;
• Все больше проектов хранят прошивку в последовательном Flash-памятнике, например: прошивка ESP8266, BIOS на материнской плате и прошивки других распространенных электронных устройств. Однако спецификации и команды для различных типов Flash не унифицированы. Использование SFUD позволяет избежать проблем совместимости различных типов Flash при работе с одинаковыми функциональными программными платформами, что повышает переиспользуемость программного обеспечения;
• Упрощение процесса программирования, снижение сложности разработки. Теперь достаточно настроить SPI-связь, чтобы начать работу с последовательным Flash;
• Может использоваться для создания программатора/загрузчика для Flash.## 2. Использование SFUD

2.1 Поддерживаемые Flash

Ниже приведена таблица, содержащая все Flash, которые были протестированы на реальных устройствах на платформе Demo. Flash, которые не поддерживают стандарт SFDP, уже определены в таблице параметров Flash. Для улучшения и поддержания Flash, которые не поддерживают стандарт SFDP, требуется участие всех пользователей (Github|OSChina|Coding).Если вам понравился этот открытый проект, вы можете нажать на Star в правом верхнем углу страницы проекта и порекомендовать его другим пользователям, которым он может быть полезен.

Примечание: В режиме QSPI двойные линии означают поддержку двойного быстрого чтения, а четверные линии — поддержку четверного быстрого чтения.

В большинстве случаев, флэш-память, поддерживающая четверное быстрое чтение, также поддерживает двойное быстрое чтение.### 2.2 Описание API

Сначала рассмотрим основную структуру sfud_flash, используемую в этой библиотеке. Определение структуры находится в файле /sfud/inc/sfud_def.h. Для каждого SPI Flash существует соответствующий экземпляр этой структуры, который мы будем называть объектом Flash-устройства. После успешной инициализации в структуре sfud_flash->chip будут храниться основные параметры SPI Flash. Если SPI Flash поддерживает SFDP, то дополнительные параметры можно получить через sfud_flash->sfdp. Многие из следующих функций будут использовать объект Flash-устройства в качестве первого параметра для выполнения операций над конкретным SPI Flash.

2.2.1 Инициализация библиотеки SFUD

Вызов функции sfud_device_init для инициализации всех устройств в таблице устройств Flash. Если используется только одно устройство Flash, можно использовать только sfud_device_init для его инициализации.

Внимание: После инициализации все SPI Flash по умолчанию находятся в состоянии отмены защиты записи. Если необходимо включить защиту записи, используйте функцию sfud_write_status для изменения состояния SPI Flash.

sfud_err sfud_init(void)

2.2.2 Инициализация конкретного устройства Flash

sfud_err sfud_device_init(sfud_flash *flash)

При включении режима QSPI в SFUD, Flash-драйверы в SFUD поддерживают использование QSPI-канала для связи. В отличие от традиционного режима SPI, использование QSPI может ускорить чтение данных из Flash, но при записи данных скорость записи Flash может быть медленнее, чем скорость передачи данных по SPI, поэтому ускорение записи данных в режиме QSPI не так заметно.

Поэтому поддержка SFUD режима QSPI ограничивается только быстрым чтением. С помощью этой функции можно настроить фактическую ширину данных QSPI-канала, которую поддерживает Flash, например: 1 линия (значение по умолчанию, т.е. традиционный режим SPI), 2 линии, 4 линии.

После настройки SFUD будет использовать наилучший режим быстрого чтения, соответствующий текущей ширине данных QSPI-канала, из расширенной таблицы QSPI Flash. Затем при вызове функции sfud_read() будет использоваться функция передачи данных в режиме QSPI для отправки этого режима чтения.

sfud_err sfud_qspi_fast_read_enable(sfud_flash *flash, uint8_t data_line_width)

В конфигурационном файле SFUD определяется таблица Flash устройств, которая хранит все Flash устройства, которые будут использоваться. Поэтому SFUD поддерживает одновременную работу с несколькими Flash устройствами. Конфигурация таблицы устройств определена макросом SFUD_FLASH_DEVICE_TABLE в файле /sfud/inc/sfud_cfg.h. Подробные методы конфигурации см. в разделе 2.3 Методы конфигурации Flash. Этот метод возвращает объект Flash устройства по индексу, указанному в таблице устройств. Если индекс выходит за пределы таблицы устройств, возвращается NULL.

sfud_flash *sfud_get_device(size_t index)

2.2.5 Чтение данных из Flash

sfud_err sfud_read(const sfud_flash *flash, uint32_t addr, size_t size, uint8_t *data)

2.2.6 Удаление данных из Flash> Внимание: Операция удаления должна быть выровнена по размеру блока удаления чипа Flash (подробнее см. в руководстве по Flash, обычно это размер блока). После завершения инициализации можно проверить размер блока удаления с помощью sfud_flash->chip.erase_gran. Убедитесь, что начальный адрес и размер удаления выровнены по размеру блока удаления чипа Flash, иначе удаление может привести к потере других данных.```C

sfud_err sfud_erase(const sfud_flash *flash, uint32_t addr, size_t size)

|Параметр|Описание|
|:-------|:------|
|flash|Объект Flash-устройства|
|addr|Начальный адрес|
|size|Общая размерность данных, удаляемых с начального адреса|

#### 2.2.7 Удаление всех данных с Flash

```C
sfud_err sfud_chip_erase(const sfud_flash *flash)

2.2.8 Запись данных в Flash

sfud_err sfud_write(const sfud_flash *flash, uint32_t addr, size_t size, const uint8_t *data)

2.2.9 Сначала удаление, затем запись данных в Flash

Внимание: Операция удаления будет выровнена в соответствии с размером блока удаления Flash (см. документацию Flash, обычно это размер блока). После завершения инициализации можно получить размер блока удаления с помощью sfud_flash->chip.erase_gran. Убедитесь, что начальный адрес и размер удаления выровнены в соответствии с размером блока удаления Flash, иначе удаление приведет к потере других данных.```C sfud_err sfud_erase_write(const sfud_flash *flash, uint32_t addr, size_t size, const uint8_t *data)

|Параметр                                    |Описание|
|:-----                                  |:----|
|flash                                   |Объект Flash-устройства|
|addr                                    |Начальный адрес|
|size                                    |Общий размер данных, записываемых с начального адреса|
|data                                    |Данные для записи|

#### 2.2.10 Чтение состояния Flash

```C
sfud_err sfud_read_status(const sfud_flash *flash, uint8_t *status)

2.2.11 Запись (изменение) состояния Flash

sfud_err sfud_write_status(const sfud_flash *flash, bool is_volatile, uint8_t status)

2.3 Методы конфигурации

Все конфигурации находятся в файле /sfud/inc/sfud_cfg.h. Пожалуйста, ознакомьтесь с описанием конфигураций ниже и выберите подходящие для вашего проекта.

2.3.1 Режим отладки

Включение/выключение макропредопределения SFUD_DEBUG_MODE

2.3.2 Использование функции SFDP параметровВключение/выключение макропредопределения SFUD_USING_SFDP

Внимание: При отключении будет выполняться только запрос к таблице Flash параметров, предоставленной в файле /sfud/inc/sfud_flash_def.h. Это снижает адаптивность программного обеспечения, но уменьшает объем кода.

2.3.3 Использование встроенной таблицы параметров Flash

Включение/выключение макропредопределения SFUD_USING_FLASH_INFO_TABLE

Внимание: При отключении библиотека будет поддерживать только Flash, соответствующие стандарту SFDP. Это также уменьшает объем кода. Кроме того, хотя бы одно из этих двух макропредопределений должно быть определено, можно выбрать и оба варианта.

2.3.4 Не использовать ни SFDP, ни таблицу параметров Flash

Для дальнейшего уменьшения объема кода макропредопределения SFUD_USING_SFDP и SFUD_USING_FLASH_INFO_TABLE также могут не быть определены.

В этом случае, необходимо указать параметры Flash при определении устройства Flash, а затем инициализировать его с помощью функции sfud_device_init. Пример кода:

sfud_flash sfud_norflash0 = {
        .name = "norflash0",
        .spi.name = "SPI1",
        .chip = { "W25Q64FV", SFUD_MF_ID_WINBOND, 0x40, 0x17, 8L * 1024L * 1024L, SFUD_WM_PAGE_256B, 4096, 0x20 } };
......
sfud_device_init(&sfud_norflash0);
......

2.3.5 Таблица устройств Flash

Если в продукте используется несколько устройств Flash, можно добавить таблицу устройств Flash. Измените макропредопределение SFUD_FLASH_DEVICE_TABLE, пример:```C enum { SFUD_W25Q64CV_DEVICE_INDEX = 0, SFUD_GD25Q64B_DEVICE_INDEX = 1, };

#define SFUD_FLASH_DEVICE_TABLE
{
[SFUD_W25Q64CV_DEVICE_INDEX] = {.name = "W25Q64CV", .spi.name = "SPI1"},
[SFUD_GD25Q64B_DEVICE_INDEX] = {.name = "GD25Q64B", .spi.name = "SPI3"},
}

Выше определены два устройства Flash (в большинстве случаев одного достаточно), имена этих устройств — `"W25Q64CV"` и `"GD25Q64B"`, соответствующие именам SPI-устройств `"SPI1"` и `"SPI3"` (используются при миграции SPI-интерфейса, находятся в файле `/sfud/port/sfud_port.c`). `SFUD_W25Q64CV_DEVICE_INDEX` и `SFUD_GD25Q64B_DEVICE_INDEX` — эти перечисления определяют индексы устройств в таблице устройств, которые можно получить с помощью функции `sfud_get_device_table()`, а затем использовать эти индексы для доступа к конкретным устройствам.#### 2.3.6 QSPI режим

Включите/выключите макропараметр `SFUD_USING_QSPI`

При включении SFUD также будет поддерживать флэш-память, подключённую к QSPI шине.

### 2.4 Инструкции по портированиюФайлы для портирования расположены в `/sfud/port/sfud_port.c`. Метод `sfud_err sfud_spi_port_init(sfud_flash *flash)` в этом файле является методом портирования, предоставленным библиотекой. Внутри этого метода выполняются настройки драйверов чтения/записи SPI для каждого устройства (обязательно), количество попыток повтора (обязательно), интерфейса повтора (необязательно) и блокировки SPI (необязательно). Для более подробных инструкций по портированию можно обратиться к файлам портирования для различных платформ в демо-примерах.### 2.5 Добавление поддержки не поддерживаемых библиотекой флэш-устройств

Для этого необходимо изменить файл `/sfud/inc/sfdu_flash_def.h`. Все поддерживаемые флэш-устройства указаны в макропараметре `SFUD_FLASH_CHIP_TABLE`. Необходимые параметры флэш-устройств, которые нужно подготовить, включают: | Название | ID-идентификатор производителя | ID-идентификатор типа | ID-идентификатор ёмкости | Объём | Режим записи | Размер блока стирания (наименьшая единица стирания) | Команда стирания, соответствующая размеру блока |. В качестве примера рассмотрим добавление флэш-устройства `GD25Q64B` компании GigaDevice.Это устройство является одним из ранних моделей GigaDevice, поэтому оно не поддерживает стандарт SFDP. Сначала необходимо загрузить документацию устройства и найти три ID, возвращаемые командой 0x9F. Здесь нам нужны последние два байта ID, то есть `type id` и `capacity id`. Для `GD25Q64B` эти ID равны `0x40` и `0x17` соответственно. Все остальные параметры флеш-устройства можно найти в документации устройства. Особое внимание следует уделить параметру **режим записи**, поскольку библиотека поддерживает четыре режима записи, подробно описанных в перечислении `sfud_write_mode` в начале файла. Одно и то же устройство может поддерживать несколько режимов записи одновременно, в зависимости от ситуации. Для `GD25Q64B` поддерживаемый режим записи должен быть `SFUD_WM_PAGE_256B`, то есть запись от 1 до 256 байт на страницу. Соответствующие параметры для `GD25Q64B` флеш-устройства будут следующими:```
    {"GD25Q64B", SFUD_MF_ID_GIGADEVICE, 0x40, 0x17, 8 * 1024 * 1024, SFUD_WM_PAGE_256B, 4096, 0x20},

Затем добавьте это устройство в конец макропараметра SFUD_FLASH_CHIP_TABLE, чтобы завершить поддержку библиотекой GD25Q64B.

2.6 Примеры

В настоящее время поддерживаются следующие примеры для различных платформ:

2.7 Лицензия

Используется лицензия MIT, подробности можно найти в файле LICENSE проекта.