user_data.h

Go to the documentation of this file.

/********************************** (C) COPYRIGHT *******************************
 * File Name          : user_data.h
 * Description        : Интерфейс доступа к энергонезависимой «пользовательской»
 *                      памяти CH32V003F4P6.
 *
 * Аппаратная область: User Option Bytes, 64 байта по адресу 0x1FFFF800.
 * Данные сохраняются при отключении питания (во flash option page).
 *
 * Важно (ограничения железа):
 *   — Страница 64 байта, но первые 16 байт заняты служебными option bytes
 *     (защита чтения/записи, USER, Data0/1, WRPR0/1).
 *   — Каждый сохраняемый байт занимает 16-битное слово: младший байт = данные,
 *     старший = побитовая инверсия (контроль целостности при загрузке).
 *   — Запись возможна только после стирания всей 64-байтной страницы целиком.
 *
 * Полезная ёмкость для приложения: USER_DATA_CAPACITY (26 байт).
 * Официально WCH выделяет Data0 и Data1 (2 байта); остальное — «Reserved»
 * в зоне 0x1FFFF80C…0x1FFFF83F, используется по той же схеме data/~data.
 *
 * Рекомендуемый порядок работы:
 *   UserData_Init() → Read/Write в RAM-кэш → UserData_Commit().
 *********************************************************************************/
 
#ifndef __USER_DATA_H
#define __USER_DATA_H
 
#include <stdint.h>
#include <stddef.h>
 
/* Базовый адрес 64-байтной страницы User Option Bytes в памяти. */
#define USER_DATA_FLASH_BASE        ((uint32_t)0x1FFFF800U)
 
/* Размер всей аппаратной страницы (байт). */
#define USER_DATA_FLASH_PAGE_SIZE   64U
 
/* Доступный объём пользовательских данных (байт полезной нагрузки). */
#define USER_DATA_CAPACITY          26U
 
/* Смещения в логическом массиве пользователя (индексы 0…25). */
#define USER_DATA_OFF_DATA0         0U   /* официальный байт Data0 */
#define USER_DATA_OFF_DATA1         1U   /* официальный байт Data1 */
#define USER_DATA_OFF_EXT_BASE      2U   /* начало расширенной области (Reserved) */
 
typedef enum {
    USER_DATA_OK = 0,       /* операция успешна */
    USER_DATA_ERR_PARAM,    /* NULL-указатель или некорректный параметр */
    USER_DATA_ERR_RANGE,    /* offset/len выходят за USER_DATA_CAPACITY */
    USER_DATA_ERR_FLASH,    /* ошибка программирования/стирания flash */
    USER_DATA_ERR_BUSY      /* flash занят (редко, при вложенных вызовах) */
} UserData_Status;
 
/*********************************************************************
 * @fn      UserData_Init
 *
 * @brief   Загрузить содержимое энергонезависимой области в RAM-кэш.
 *
 * @details Вызывать один раз при старте (до Read/Write). Чтение из flash
 *          не требует разблокировки. Проверяется целостность полей data/~data
 *          в option page; при сбое кэш заполняется 0xFF (как после erase).
 *          После Init можно работать с кэшем; запись во flash — Commit().
 *
 * @return  USER_DATA_OK — загрузка успешна;
 *          USER_DATA_ERR_BUSY — flash занят (BSY);
 *          USER_DATA_ERR_FLASH — повреждены option bytes (несовпадение data/~data).
 */
UserData_Status UserData_Init(void);
 
/*********************************************************************
 * @fn      UserData_Capacity
 *
 * @brief   Вернуть размер доступной пользовательской области (26).
 */
uint8_t UserData_Capacity(void);
 
/*********************************************************************
 * @fn      UserData_Read
 *
 * @brief   Прочитать len байт из RAM-кэша, начиная с offset.
 *
 * @param   offset — смещение 0 … USER_DATA_CAPACITY-1.
 * @param   buf    — буфер приёмника.
 * @param   len    — число байт для чтения.
 */
UserData_Status UserData_Read(uint8_t offset, uint8_t *buf, uint8_t len);
 
/*********************************************************************
 * @fn      UserData_Write
 *
 * @brief   Записать len байт в RAM-кэш (не во flash!).
 *
 * @details Помечает кэш «грязным»; для сохранения после сброса питания
 *          вызвать UserData_Commit().
 */
UserData_Status UserData_Write(uint8_t offset, const uint8_t *buf, uint8_t len);
 
/*********************************************************************
 * @fn      UserData_ReadByte / UserData_WriteByte
 *
 * @brief   Чтение/запись одного байта по индексу в кэше.
 */
UserData_Status UserData_ReadByte(uint8_t offset, uint8_t *value);
UserData_Status UserData_WriteByte(uint8_t offset, uint8_t value);
 
/*********************************************************************
 * @fn      UserData_Fill
 *
 * @brief   Заполнить диапазон кэша одним значением (например 0xFF).
 */
UserData_Status UserData_Fill(uint8_t offset, uint8_t len, uint8_t value);
 
/*********************************************************************
 * @fn      UserData_Erase
 *
 * @brief   Установить весь пользовательский кэш в 0xFF (логическое «стирание»).
 *
 * @details Во flash изменения появятся только после Commit.
 */
UserData_Status UserData_Erase(void);
 
/*********************************************************************
 * @fn      UserData_Commit
 *
 * @brief   Записать RAM-кэш в User Option Bytes (flash).
 *
 * @details Алгоритм:
 *          1) Сохранить служебные option bytes (RDPR, USER, WRPR*).
 *          2) Стереть всю 64-байтную страницу.
 *          3) Восстановить служебные байты и записать пользовательские.
 *
 *          Операция занимает несколько миллисекунд; не вызывать из ISR.
 *          При ошибке flash служебные байты восстанавливаются из снимка,
 *          сделанного перед стиранием.
 *
 * @return  USER_DATA_OK если не было изменений или запись успешна.
 */
UserData_Status UserData_Commit(void);
 
/*********************************************************************
 * @fn      UserData_IsDirty
 *
 * @brief   true, если кэш изменён и не сохранён в flash.
 */
uint8_t UserData_IsDirty(void);
 
/*********************************************************************
 * @fn      UserData_Buffer
 *
 * @brief   Прямой доступ к RAM-кэшу (USER_DATA_CAPACITY байт).
 *
 * @details Любая модификация через указатель помечает кэш «грязным».
 *          Не выходить за границы массива.
 */
uint8_t *UserData_Buffer(void);
const uint8_t *UserData_ConstBuffer(void);
 
/*********************************************************************
 * @fn      UserData_ReadFlashPageRaw
 *
 * @brief   Прочитать всю 64-байтную страницу option bytes «как в silicon».
 *
 * @param   page — буфер не менее USER_DATA_FLASH_PAGE_SIZE байт.
 *
 * @details Для отладки/диагностики. В page будут и служебные, и пользовательские
 *          байты с инверсными половинами слов.
 */
UserData_Status UserData_ReadFlashPageRaw(uint8_t *page);
 
#endif /* __USER_DATA_H */