EasyFlash API описание

Все поддерживаемые API-интерфейсы объявлены в файле easyflash/inc/easyflash.h. Рекомендуется использовать CTRL+F для поиска.

Термины:

• Резервная область: это область хранения, определённая EasyFlash, которая содержит переменные среды, загруженные программы и журналы. Подробную структуру хранилища можно найти в комментариях в начале файла easyflash/src/easyflash.c или в документации по переносу (раздел 55 «Резервная область»).

1. Интерфейс пользователя

1.1 Инициализация

Инициализируйте различные компоненты EasyFlash. После инициализации можно использовать следующие API.

Для компонента переменных среды, если flash инициализируется впервые, автоматически вызывается функция ef_env_set_default, восстанавливающая переменные среды по умолчанию, определённые в файле переноса. Впоследствии при каждом запуске будет автоматически проверяться состояние переменных среды во flash, и они будут восстановлены до значений по умолчанию при серьёзном повреждении flash. Если включена функция инкрементного обновления, также будет выполнена проверка инкрементного обновления и, если версии не совпадают, будет выполнено инкрементное обновление.

EfErrCode easyflash_init(void)

1.2 Переменные среды

После версии V4.0 переменные среды в EasyFlash хранятся в двоичном формате (формат blob), что позволяет верхнему уровню поддерживать передачу данных любого типа. В версиях до V4.0 нижний уровень использует строковый формат для хранения переменных среды, который также может быть преобразован в формат blob, поэтому V4.0 полностью совместим с предыдущими API, такими как ef_get_env/ef_set_env, которые могут использоваться только со строковыми ENV.

Кроме того, строковые ENV имеют ограничение по длине: по умолчанию EF_STR_ENV_VALUE_MAX_SIZE установлено значение 128 байт, и если длина превышает это значение, ef_get_env может не работать, и необходимо использовать ef_get_env_blob.

1.2.1 Получение переменной среды

Используйте имя переменной среды для получения соответствующего значения. Поддерживаются два интерфейса:

1.2.1.1 Получить переменную среды типа blob

size_t ef_get_env_blob(const char *key, void *value_buf, size_t buf_len, size_*save_value_len)

Пример:

char value[32];
size_t len;
/* Если длина переменной среды неизвестна, сначала можно получить реальную длину из flash через len */
ef_get_env_blob("key", NULL, 0, &len);
/* Если известна длина, используйте value для сохранения данных переменной среды и верните фактическую длину */
len = ef_get_env_blob("key", value, sizeof(value), NULL);

1.2.1.2 Получить переменную строкового типа

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

char *ef_get_env(const char *key)

1.2.2 Установка переменной среды

Этот метод позволяет добавлять, изменять и удалять переменные среды.

• Добавить: если переменная среды с таким именем не существует в таблице переменных среды, она будет добавлена;
• Изменить: если переменная среды с этим именем уже существует в текущей таблице переменных среды, значение переменной будет изменено на входящее значение;
• Удалить: если входящее значение равно NULL, соответствующая переменная среды будет удалена.

1.2.1.1 Установить переменную среды типа blob

EfErrCode ef_set_env_blob(const char *key, const void *value_buf, size_t buf_len)

1.2.1.2 Установить переменную строкового типа

EfErrCode ef_set_env(const char *key, const char *value)

1.2.3 Удалить переменную среды

Эта функция удаляет переменную среды.

EfErrCode ef_del_env(const char *key)

1.2.4 Сбросить переменную среду

Сбросьте переменные среды в памяти до значений по умолчанию. Метод настройки переменных среды по умолчанию см. в документации по миграции.

EfErrCode ef_env_set_default(void)

1.2.5 Печать переменных среды

Выведите все переменные среды во Flash, используя метод печати, определённый в интерфейсе переноса (\easyflash\port\ef_port.c).

void ef_print_env(void)

1.3 Онлайн-обновление

1.3.1 Очистка резервной области от приложения

EfErrCode ef_erase_bak_app(size_t app_size)

1.3.2 Очистить пользовательское приложение

Обратите внимание: не вызывайте эту функцию в приложении.

EfErrCode ef_erase_user_app(uint32_t user_app_addr, size_t user_app_size)

1.3.3 Очистить приложение с помощью указанного метода очистки

Если пользовательское приложение и резервная область находятся в разных Flash-областях, необходимо указать дополнительный метод очистки. Функция ef_erase_user_app использует метод ef_port_erase, определённый в файле переноса, для очистки, кроме этого, остальные функции одинаковы.

Обратите внимание: не вызывайте эту функцию в приложении.

EfErrCode ef_erase_spec_user_app(uint32_t user_app_addr, size_t app_size,
        EfErrCode (*app_erase)(uint32_t addr, | Параметр                                    | Описание                                                           |
| :------------------------------------------- | :----------------------------------------------------------------- |
| user_app_addr                                  | Адрес входа в пользовательское приложение                          |
| user_app_size                                   | Размер пользовательского приложения                                |
| app_erase                                      | Метод стирания, указанный пользователем для приложения             |

#### 1.3.4 Стирание Bootloader

*Примечание: не вызывайте этот метод в Bootloader.*

```C
EfErrCode ef_erase_bl(uint32_t bl_addr, size_t bl_size)

1.3.5 Запись данных в резервную область

Метод непрерывной записи данных во флэш-память для загрузки программы в резервную область.

Примечание: перед записью убедитесь, что флэш-память была стёрта.

EfErrCode ef_write_data_to_bak(uint8_t *data,
                               size_t size,
                               size_t *cur_size,
                               size_t total_size)

1.3.6 Копирование приложения из резервной области

Копирование готового приложения из резервной области по указанному адресу пользовательского приложения.

Примечание:

1. Перед копированием необходимо стереть существующее приложение.
2. Не вызывайте этот метод из приложения.

EfErrCode ef_copy_app_from_bak(uint32_t user_app_addr, size_t app_size)

1.3.7 Копирование приложения с использованием указанного метода записи

Если пользовательское приложение и резервная область находятся на разных флэш-устройствах, то необходимо указать дополнительный метод записи. Метод ef_copy_app_from_bak использует метод ef_port_write из файла переноса для выполнения операции записи. В остальном эти два метода идентичны.

EfErrCode ef_copy_spec_app_from_bak(uint32_t user_app_addr, size_t app_size,
        EfErrCode (*app_write)(uint32_t addr, const uint32_t *buf, size_t size))

1.3.8 Копирование Bootloader из резервной области

Копирует готовый Bootloader из резервной области по заданному адресу.

Примечание:

1. Перед копированием необходимо стереть существующий Bootloader.
2. Не вызывайте этот метод из Bootloader.

EfErrCode ef_copy_bl_from_bak(uint32_t bl_addr, size_t bl_size)

1.4 Хранение логов

1.4.1 Чтение существующего журнала из флэш-памяти

EfErrCode ef_log_read(size_t index, uint32_t *log, size_t size);

1.4.2 Сохранение журнала во флэш-памяти

EfErrCode ef_log_write(const uint32_t *log, size_t size);

1.4.3 Очистка всех журналов во флэш-памяти

EfErrCode ef_log_clean(void);

1.4.4 Получение размера всех сохранённых журналов

size_t ef_log_get_used_size(void);