user_data.c

Go to the documentation of this file.

/********************************** (C) COPYRIGHT *******************************
 * File Name          : user_data.c
 * Description        : Доступ к 64-байтной странице User Option Bytes CH32V003.
 *
 * Карта страницы 0x1FFFF800 (64 байта):
 *
 *   Смещ.   Содержимое (официально)
 *   +0x00   RDPR + nRDPR
 *   +0x04   USER + nUSER
 *   +0x08   Data0 + nData0   ← user_data[0]
 *   +0x0C   Data1 + nData1   ← user_data[1]
 *   +0x10   WRPR0 + nWRPR0
 *   +0x14   WRPR1 + nWRPR1
 *   +0x18   Reserved (48 байт) ← user_data[2…25] (по 2 байта на каждый data-байт)
 *
 * Запись: только erase всей страницы + program halfword (низкий байт = данные).
 *********************************************************************************/
 
#include "user_data.h"
#include "ch32v00x_conf.h"
 
/*
 * Карта 16-битных слов (halfword) страницы option bytes, если смотреть
 * на неё как на массив uint16_t ob[0..31] (64 байта / 2). Используется
 * в UserData_LoadFromFlash()/UserData_Commit() ниже — там же и хранится
 * актуальная нумерация индексов, здесь только сводка для навигации:
 *
 *   ob[0] = RDPR  + ~RDPR   (защита чтения)      — служебное, не трогаем
 *   ob[1] = USER  + ~USER   (конфиг. биты MCU)   — служебное, не трогаем
 *   ob[2] = Data0 + ~Data0  → s_user_cache[0]     — официальный пользовательский байт
 *   ob[3] = Data1 + ~Data1  → s_user_cache[1]     — официальный пользовательский байт
 *   ob[4] = WRPR0 + ~WRPR0  (защита записи flash) — служебное, не трогаем
 *   ob[5] = WRPR1 + ~WRPR1                        — служебное, не трогаем
 *   ob[6..7] = «Reserved» (WRPR2/3 по имени регистра, не используются
 *              аппаратно на CH32V003) — не проверяются на чтении, но
 *              бережно копируются как снимок при Commit (см. hold32[3]),
 *              чтобы случайно не занулить их при erase всей страницы.
 *   ob[8..31] = расширенная пользовательская область (USER_DATA_OFF_EXT_BASE
 *              … USER_DATA_CAPACITY-1) → s_user_cache[2..25].
 *
 * Во всех «данных» halfword старший байт — побитовая инверсия младшего
 * (see UserData_VerifyHalfword) — так аппаратура/программатор проверяют
 * целостность содержимого без отдельной контрольной суммы.
 */
 
/* Индекс первой свободной halfword в OB после WRPR1 (байтовое смещение 0x18). */
#define USER_DATA_OB_HALFWORD_BASE  8U
 
/* Локальные биты управления flash (как в ch32v00x_flash.c). */
#define USER_DATA_CR_OPTPG_Set      ((uint32_t)0x00000010)
#define USER_DATA_CR_OPTPG_Reset    ((uint32_t)0xFFFFFFEF)
#define USER_DATA_CR_OPTER_Set      ((uint32_t)0x00000020)
#define USER_DATA_CR_OPTER_Reset    ((uint32_t)0xFFFFFFDF)
#define USER_DATA_CR_STRT_Set       ((uint32_t)0x00000040)
#define USER_DATA_CR_LOCK_Set       ((uint32_t)0x00000080)
#define USER_DATA_FLASH_KEY1        ((uint32_t)0x45670123)
#define USER_DATA_FLASH_KEY2        ((uint32_t)0xCDEF89AB)
 
static uint8_t s_user_cache[USER_DATA_CAPACITY];
static uint8_t s_dirty;
 
/*********************************************************************
 * @fn      UserData_FlashWait
 *
 * @brief   Дождаться завершения текущей операции flash и проверить её
 *          результат.
 *
 * @details Вызывается после КАЖДОЙ операции со страницей option bytes
 *          (erase, program halfword) — по спецификации периферии flash
 *          CH32V003 запись в CTLR (STRT/OPTPG/OPTER) только запускает
 *          операцию, а её фактическое выполнение асинхронно относительно
 *          шины: пока не снят бит BSY в STATR, содержимое затрагиваемой
 *          области не определено. Занимает от единиц до нескольких
 *          миллисекунд — вызывающий код (UserData_Commit) не должен
 *          работать из ISR.
 *
 *          WRPRTERR (Write Protection Error) означает попытку записи в
 *          защищённую область — для option bytes практически не должно
 *          происходить, но проверяется на случай отсутствия разблокировки
 *          (см. UserData_UnlockFlash) или порчи регистров защиты. EOP
 *          (End Of Programming) — штатный флаг успешного завершения,
 *          просто сбрасывается, чтобы не «протух» до следующей проверки.
 *
 * @return  USER_DATA_OK — операция завершилась штатно (EOP, без WRPRTERR);
 *          USER_DATA_ERR_FLASH — обнаружен WRPRTERR.
 */
static UserData_Status UserData_FlashWait(void)
{
    while (FLASH_GetFlagStatus(FLASH_FLAG_BSY) != RESET) {
    }
 
    if (FLASH_GetFlagStatus(FLASH_FLAG_WRPRTERR) != RESET) {
        FLASH_ClearFlag(FLASH_FLAG_WRPRTERR);
        return USER_DATA_ERR_FLASH;
    }
 
    if (FLASH_GetFlagStatus(FLASH_FLAG_EOP) != RESET) {
        FLASH_ClearFlag(FLASH_FLAG_EOP);
    }
 
    return USER_DATA_OK;
}
 
/*********************************************************************
 * @fn      UserData_UnlockFlash
 *
 * @brief   Разблокировка основной flash и отдельно option bytes.
 *
 * @details Два независимых замка: FLASH_Unlock() (стандартная функция
 *          SPL, снимает LOCK через KEYR/FKEYR) открывает основную flash-
 *          память, а запись в OBKEYR фиксированной парой ключей KEY1/KEY2
 *          отдельно разблокирует именно страницу option bytes (OPTWRE в
 *          CTLR). Без второго шага биты OPTPG/OPTER в UserData_Commit()
 *          не будут иметь эффекта, хотя основная flash уже разблокирована.
 */
static void UserData_UnlockFlash(void)
{
    FLASH_Unlock();
    FLASH->OBKEYR = USER_DATA_FLASH_KEY1;
    FLASH->OBKEYR = USER_DATA_FLASH_KEY2;
}
 
/*********************************************************************
 * @fn      UserData_LockFlash
 *
 * @brief   Заблокировать flash после программирования option bytes.
 *
 * @details Установка бита LOCK в CTLR блокирует ОБА замка, снятых в
 *          UserData_UnlockFlash() (основную flash и option bytes) —
 *          отдельного «lock» для OBKEYR не требуется.
 */
static void UserData_LockFlash(void)
{
    FLASH->CTLR |= USER_DATA_CR_LOCK_Set;
}
 
/*********************************************************************
 * @fn      UserData_VerifyHalfword
 *
 * @brief   Проверить целостность одной 16-битной ячейки option bytes.
 *
 * @param   hw — прочитанное из option page 16-битное слово (младший
 *          байт — данные, старший — ожидаемая инверсия данных).
 *
 * @details В option bytes CH32V003 каждый байт данных аппаратно дублируется
 *          инвертированным байтом-«напарником» в том же 16-битном слове —
 *          так исключается ложное считывание при частичном сбое ячейки
 *          (без этого отдельного бита чётности/CRC на этой странице нет).
 *          Два допустимых состояния: полностью стёртая ячейка (0xFFFF —
 *          инверсия 0xFF тоже 0xFF, совпадение случайное, но проверяется
 *          отдельно первым условием) или корректно запрограммированная
 *          (data ^ inv == 0xFF). Любое другое сочетание — повреждение
 *          (например, прерванная запись при потере питания).
 *
 * @return  USER_DATA_OK — ячейка цела (стёрта или корректно записана);
 *          USER_DATA_ERR_FLASH — data/~data не согласованы.
 */
static UserData_Status UserData_VerifyHalfword(uint16_t hw)
{
    uint8_t data = (uint8_t)hw;
    uint8_t inv = (uint8_t)(hw >> 8);
 
    if (data == 0xFFU && inv == 0xFFU) {
        return USER_DATA_OK;
    }
    if ((uint8_t)(data ^ inv) == 0xFFU) {
        return USER_DATA_OK;
    }
    return USER_DATA_ERR_FLASH;
}
 
/*********************************************************************
 * @fn      UserData_CacheFillErased
 *
 * @brief   Заполнить RAM-кэш значением 0xFF (логически стёртое состояние).
 *
 * @details 0xFF выбрано не произвольно: это то же значение, которое
 *          физически имеет каждая ячейка flash сразу после erase (см.
 *          UserData_VerifyHalfword) — так поведение «данные повреждены/
 *          отсутствуют» в RAM-кэше неотличимо от «страница только что
 *          стёрта», и вызывающий код (LCM_LoadConfig) может использовать
 *          общую проверку magic-байта для обоих случаев.
 */
static void UserData_CacheFillErased(void)
{
    uint8_t i;
 
    for (i = 0U; i < USER_DATA_CAPACITY; i++) {
        s_user_cache[i] = 0xFFU;
    }
}
 
/*********************************************************************
 * @fn      UserData_LoadFromFlash
 *
 * @brief   Считать пользовательские байты из option page в s_user_cache.
 *
 * @details Из каждой 16-битной ячейки в кэш берётся только младший байт
 *          (старший — контрольная инверсия, см. UserData_VerifyHalfword).
 *          Перед копированием ЛЮБОГО байта в кэш сначала проверяются
 *          служебные ячейки ob[0]/ob[1] (RDPR/USER) и ob[4]/ob[5]
 *          (WRPR0/WRPR1, см. карту в начале файла) — если повреждена
 *          хотя бы одна из них, всей странице нельзя доверять (например,
 *          питание пропало в середине предыдущего Commit), и функция
 *          прерывается ДО того, как начнёт заполнять s_user_cache —
 *          вызывающий UserData_Init() в этом случае откатится на
 *          UserData_CacheFillErased() и вернёт ошибку целиком, не
 *          оставляя кэш в частично заполненном состоянии.
 *
 *          ob[6]/ob[7] («Reserved») сознательно не проверяются — они не
 *          используются приложением, их integrity не влияет на данные
 *          LCM; порядок проверок оставляет их «как есть» на аппаратном
 *          уровне без дополнительных требований.
 *
 *          Data0/Data1 (ob[2]/ob[3]) и расширенная область (ob[8…31])
 *          проверяются и копируются по одному байту — при первой же
 *          повреждённой ячейке функция также прерывается сразу, без
 *          попытки восстановить оставшиеся байты.
 */
static UserData_Status UserData_LoadFromFlash(void)
{
    const uint16_t *ob = (const uint16_t *)USER_DATA_FLASH_BASE;
    UserData_Status st;
    uint8_t i;
 
    /* Служебные ячейки: RDPR/USER (защита чтения, конфигурация MCU) */
    st = UserData_VerifyHalfword(ob[0]);
    if (st != USER_DATA_OK) {
        return st;
    }
    st = UserData_VerifyHalfword(ob[1]);
    if (st != USER_DATA_OK) {
        return st;
    }
    /* Служебные ячейки: WRPR0/WRPR1 (защита записи flash по секторам) */
    st = UserData_VerifyHalfword(ob[4]);
    if (st != USER_DATA_OK) {
        return st;
    }
    st = UserData_VerifyHalfword(ob[5]);
    if (st != USER_DATA_OK) {
        return st;
    }
 
    /* Официальные пользовательские байты Data0/Data1 → s_user_cache[0..1] */
    st = UserData_VerifyHalfword(ob[2]);
    if (st != USER_DATA_OK) {
        return st;
    }
    s_user_cache[0] = (uint8_t)ob[2];
 
    st = UserData_VerifyHalfword(ob[3]);
    if (st != USER_DATA_OK) {
        return st;
    }
    s_user_cache[1] = (uint8_t)ob[3];
 
    /* Расширенная область (Reserved, ob[8…31]) → s_user_cache[2..25] */
    for (i = USER_DATA_OFF_EXT_BASE; i < USER_DATA_CAPACITY; i++) {
        uint16_t hw = ob[USER_DATA_OB_HALFWORD_BASE + (i - USER_DATA_OFF_EXT_BASE)];
 
        st = UserData_VerifyHalfword(hw);
        if (st != USER_DATA_OK) {
            return st;
        }
        s_user_cache[i] = (uint8_t)hw;
    }
 
    return USER_DATA_OK;
}
 
/*********************************************************************
 * @fn      UserData_ProgramHalfwordRaw
 *
 * @brief   Записать готовое 16-битное слово целиком (для служебных
 *          ячеек: RDPR, USER, WRPR0/1, Reserved WRPR2/3).
 *
 * @param   addr  — адрес halfword в option page (после erase — 0xFFFF).
 * @param   value — оба байта уже подготовлены вызывающим кодом (см.
 *          снимок hold[] в UserData_Commit — там value — это старое
 *          значение data+~data, считанное ДО erase, чтобы восстановить
 *          служебные биты «как было»).
 *
 * @details В отличие от UserData_ProgramUserByte(), сюда передаётся
 *          именно 16-битное значение (не 8-битный «полезный» байт) —
 *          используется, когда старший байт слова не является простой
 *          инверсией младшего в терминах бизнес-логики приложения (для
 *          RDPR/USER/WRPR это пара регистр+его собственная аппаратная
 *          инверсия, формируемая контроллером при исходной записи).
 */
static UserData_Status UserData_ProgramHalfwordRaw(volatile uint16_t *addr, uint16_t value)
{
    *addr = value;
    return UserData_FlashWait();
}
 
/*********************************************************************
 * @fn      UserData_ProgramUserByte
 *
 * @brief   Записать один пользовательский байт (Data0/Data1 или байт
 *          расширенной области).
 *
 * @param   addr — адрес halfword в option page.
 * @param   data — «полезный» байт (0…255), который должен получить
 *          пользователь при последующем чтении.
 *
 * @details Пишется только младший байт значения (старший = 0x00 в
 *          записываемом uint16_t) — контроллер flash CH32V003 сам
 *          подставляет побитовую инверсию data в старший байт слова при
 *          программировании option bytes (аппаратная особенность именно
 *          этой страницы, в отличие от «сырых» служебных ячеек через
 *          UserData_ProgramHalfwordRaw). Результат затем можно проверить
 *          через UserData_VerifyHalfword().
 */
static UserData_Status UserData_ProgramUserByte(volatile uint16_t *addr, uint8_t data)
{
    *addr = (uint16_t)data;
    return UserData_FlashWait();
}
 
/*********************************************************************
 * @fn      UserData_Commit
 *
 * @brief   Сохранить s_user_cache в flash с сохранением служебных option bytes.
 *
 * @details Единственный способ изменить option bytes на CH32V003 —
 *          стереть страницу ЦЕЛИКОМ (нет операции «стереть один байт»),
 *          поэтому нельзя просто перезаписать только Data0/Data1 и
 *          расширенную область: это уничтожило бы RDPR/USER/WRPR* —
 *          защиту чтения/записи и системные настройки MCU. Алгоритм:
 *
 *          1) Снимок (hold[]) — читаем ТЕКУЩЕЕ содержимое всех 8 служебных
 *             halfword (ob[0..7], см. карту в начале файла) ДО erase,
 *             чтобы потом записать их обратно «как было». Пользовательские
 *             Data0/Data1 (hold32[1]) собираются не из flash, а из
 *             s_user_cache — так одной и той же процедурой восстановления
 *             (см. шаг 3) применяется и новое пользовательское значение.
 *          2) Erase всей 64-байтной страницы (OPTER+STRT). После этого
 *             ВСЕ 32 halfword читаются как 0xFFFF, независимо от того,
 *             что было раньше.
 *          3) Program — сначала восстанавливаем 8 служебных halfword из
 *             снимка (обычный OPTPG, «сырые» значения), затем поверх
 *             расширенной области пишем НЕ-0xFF байты из s_user_cache
 *             через UserData_ProgramUserByte(). Байты со значением 0xFF
 *             пропускаются намеренно — сразу после erase они и так 0xFF
 *             (лишняя операция записи не нужна и лишь расходует ресурс
 *             цикла P/E flash).
 *
 *          При ошибке на любом шаге после erase (WRPRTERR/EOP-фейл)
 *          функция сразу прерывается и возвращает ошибку — страница
 *          может остаться частично восстановленной (это ограничение
 *          самого железа: erase уже не откатить). s_dirty сбрасывается
 *          в 0 только при полном успехе.
 */
UserData_Status UserData_Commit(void)
{
    volatile uint16_t *ob = (volatile uint16_t *)USER_DATA_FLASH_BASE;
    uint16_t hold[8];
    uint32_t *hold32 = (uint32_t *)hold;
    const uint32_t *ob32 = (const uint32_t *)USER_DATA_FLASH_BASE;
    UserData_Status st;
    uint8_t i;
 
    if (!s_dirty) {
        return USER_DATA_OK;
    }
 
    /* Снимок служебных полей до стирания страницы (побайтно как uint32,
       т.к. ob32[k] покрывает пару halfword ob[2k]/ob[2k+1] — см. карту). */
    hold32[0] = ob32[0]; /* RDPR, USER */
    hold32[1] = (uint32_t)s_user_cache[0] | ((uint32_t)s_user_cache[1] << 16); /* Data0, Data1 — новое значение из кэша */
    hold32[2] = ob32[2]; /* WRPR0, WRPR1 */
    hold32[3] = ob32[3]; /* Reserved WRPR2, WRPR3 */
 
    UserData_UnlockFlash();
 
    /* Стирание всей 64-байтной user option page (одной операцией —
       частичное стирание аппаратно не поддерживается). */
    FLASH->CTLR |= USER_DATA_CR_OPTER_Set;
    FLASH->CTLR |= USER_DATA_CR_STRT_Set;
    st = UserData_FlashWait();
    if (st != USER_DATA_OK) {
        FLASH->CTLR &= USER_DATA_CR_OPTER_Reset;
        UserData_LockFlash();
        return st;
    }
    FLASH->CTLR &= USER_DATA_CR_OPTER_Reset;
 
    /* Восстановление 8 служебных halfword (ob[0..7]) из снимка hold[] —
       без этого шага MCU лишится настроек RDPR/USER/WRPR* после erase. */
    FLASH->CTLR |= USER_DATA_CR_OPTPG_Set;
    for (i = 0; i < 8U; i++) {
        st = UserData_ProgramHalfwordRaw(&ob[i], hold[i]);
        if (st != USER_DATA_OK) {
            FLASH->CTLR &= USER_DATA_CR_OPTPG_Reset;
            UserData_LockFlash();
            return st;
        }
    }
 
    /* Расширенная пользовательская область (байты 2…25): пишем только
       непустые значения — 0xFF после erase уже установлен аппаратно. */
    for (i = USER_DATA_OFF_EXT_BASE; i < USER_DATA_CAPACITY; i++) {
        if (s_user_cache[i] != 0xFFU) {
            st = UserData_ProgramUserByte(
                &ob[USER_DATA_OB_HALFWORD_BASE + (i - USER_DATA_OFF_EXT_BASE)],
                s_user_cache[i]);
            if (st != USER_DATA_OK) {
                FLASH->CTLR &= USER_DATA_CR_OPTPG_Reset;
                UserData_LockFlash();
                return st;
            }
        }
    }
 
    FLASH->CTLR &= USER_DATA_CR_OPTPG_Reset;
    UserData_LockFlash();
 
    s_dirty = 0U;
    return USER_DATA_OK;
}
 
/*********************************************************************
 * @fn      UserData_Init
 *
 * @brief   Загрузить содержимое option bytes в RAM-кэш при старте.
 *
 * @details Проверка BSY ПЕРЕД чтением — защита от редкого случая,
 *          когда предыдущая операция flash (например, зависшая после
 *          сброса питания в середине программирования) ещё не завершена;
 *          в этом состоянии содержимое страницы недостоверно, поэтому
 *          UserData_LoadFromFlash() даже не вызывается. И здесь, и при
 *          ошибке чтения кэш откатывается на «всё 0xFF» — вызывающий код
 *          (LCM_LoadConfig) распознаёт это как «нет валидной конфигурации»
 *          и применяет заводские значения по несовпадению magic-байта.
 */
UserData_Status UserData_Init(void)
{
    UserData_Status st;
 
    if (FLASH_GetFlagStatus(FLASH_FLAG_BSY) != RESET) {
        UserData_CacheFillErased();
        s_dirty = 0U;
        return USER_DATA_ERR_BUSY;
    }
 
    st = UserData_LoadFromFlash();
    if (st != USER_DATA_OK) {
        UserData_CacheFillErased();
        s_dirty = 0U;
        return st;
    }
 
    s_dirty = 0U;
    return USER_DATA_OK;
}
 
uint8_t UserData_Capacity(void)
{
    return USER_DATA_CAPACITY;
}
 
/*********************************************************************
 * @fn      UserData_CheckRange
 *
 * @brief   Проверить корректность пары (offset, len) относительно
 *          логического массива RAM-кэша.
 *
 * @details len == 0 считается ошибкой параметра (а не «нулевой операцией
 *          без эффекта») — вызывающий код почти всегда ожидает реального
 *          чтения/записи хотя бы одного байта, а len == 0 чаще всего
 *          признак ошибки в вызывающем коде. Сложение offset+len ведётся
 *          в uint16_t, чтобы избежать переполнения uint8_t при offset,
 *          близком к 255 (даже если такой offset для 26-байтного кэша
 *          заведомо некорректен).
 */
static UserData_Status UserData_CheckRange(uint8_t offset, uint8_t len)
{
    if (len == 0U) {
        return USER_DATA_ERR_PARAM;
    }
    if ((uint16_t)offset + (uint16_t)len > USER_DATA_CAPACITY) {
        return USER_DATA_ERR_RANGE;
    }
    return USER_DATA_OK;
}
 
UserData_Status UserData_Read(uint8_t offset, uint8_t *buf, uint8_t len)
{
    UserData_Status st;
    uint8_t i;
 
    if (buf == NULL) {
        return USER_DATA_ERR_PARAM;
    }
 
    st = UserData_CheckRange(offset, len);
    if (st != USER_DATA_OK) {
        return st;
    }
 
    for (i = 0; i < len; i++) {
        buf[i] = s_user_cache[offset + i];
    }
 
    return USER_DATA_OK;
}
 
UserData_Status UserData_Write(uint8_t offset, const uint8_t *buf, uint8_t len)
{
    UserData_Status st;
    uint8_t i;
 
    if (buf == NULL) {
        return USER_DATA_ERR_PARAM;
    }
 
    st = UserData_CheckRange(offset, len);
    if (st != USER_DATA_OK) {
        return st;
    }
 
    for (i = 0; i < len; i++) {
        s_user_cache[offset + i] = buf[i];
    }
 
    s_dirty = 1U;
    return USER_DATA_OK;
}
 
UserData_Status UserData_ReadByte(uint8_t offset, uint8_t *value)
{
    if (value == NULL) {
        return USER_DATA_ERR_PARAM;
    }
    return UserData_Read(offset, value, 1U);
}
 
UserData_Status UserData_WriteByte(uint8_t offset, uint8_t value)
{
    return UserData_Write(offset, &value, 1U);
}
 
UserData_Status UserData_Fill(uint8_t offset, uint8_t len, uint8_t value)
{
    UserData_Status st;
    uint8_t i;
 
    st = UserData_CheckRange(offset, len);
    if (st != USER_DATA_OK) {
        return st;
    }
 
    for (i = 0; i < len; i++) {
        s_user_cache[offset + i] = value;
    }
 
    s_dirty = 1U;
    return USER_DATA_OK;
}
 
UserData_Status UserData_Erase(void)
{
    return UserData_Fill(0U, USER_DATA_CAPACITY, 0xFFU);
}
 
uint8_t UserData_IsDirty(void)
{
    return s_dirty;
}
 
uint8_t *UserData_Buffer(void)
{
    return s_user_cache;
}
 
const uint8_t *UserData_ConstBuffer(void)
{
    return s_user_cache;
}
 
UserData_Status UserData_ReadFlashPageRaw(uint8_t *page)
{
    uint8_t i;
 
    if (page == NULL) {
        return USER_DATA_ERR_PARAM;
    }
 
    for (i = 0; i < USER_DATA_FLASH_PAGE_SIZE; i++) {
        page[i] = *(volatile uint8_t *)(USER_DATA_FLASH_BASE + i);
    }
 
    return USER_DATA_OK;
}