/*****************************************************************************
* @file    BootMark.h
* @brief   Boot标记管理模块 - 负责读写APP启动标记
* @details Flash区域规划：
*          - Boot标记区：0x08020000-0x0803FFFF (128KB Flash参数表区)
*          - APP1标记：0x08020000 (32字节)
*          - APP2标记：0x08020020 (32字节)
*          - APP1区域：0x08080000-0x080BFFFF (256KB)
*          - APP2区域：0x080C0000-0x080FFFFF (256KB)
*          - OTA下载区：0x08100000-0x0813FFFF (Bank2第一个256KB)
* @author  AI Assistant
* @date    2025-12-21
*****************************************************************************/

#ifndef __BOOTMARK_H__
#define __BOOTMARK_H__

#ifdef __cplusplus
extern "C" {
#endif

/*****************************************************************************
* 头文件包含
*****************************************************************************/
#include "stm32h7xx_hal.h"

/*****************************************************************************
* 宏定义
*****************************************************************************/
// Flash地址定义 (Single Bank with Staging 架构)
// BANK 1
#define BOOT_LOADER_ADDR        0x08000000  // Bootloader (128KB)
#define BOOT_MARK_BASE_ADDR     0x08020000  // BootMark / Config (128KB)
#define BOOT_APP_ADDR           0x08040000  // APP 运行区 (256KB)

// BANK 2
#define BOOT_OTA_DOWNLOAD_ADDR  0x08100000  // OTA加密下载区 (256KB)
#define BOOT_OTA_STAGING_ADDR   0x08140000  // OTA解密暂存区 (256KB)
#define BOOT_PARAM_ADDR         0x08180000  // 参数存储区 (128KB)
#define BOOT_PATH_ADDR          0x081A0000  // 路径存储区 (128KB)

#define BOOT_APP_MAX_SIZE       (256 * 1024)  // APP最大大小：256KB

// 魔术字和标志
#define BOOT_MARK_MAGIC         0x424F4F54  // "BOOT" ASCII码
#define BOOT_UPDATE_PENDING     0x5A5A5A5A  // 待更新标志
#define BOOT_UPDATE_NONE        0x00000000  // 无更新

// 返回值定义
#define BOOT_OK                 0           // 成功
#define BOOT_ERR_PARAM          -1          // 参数错误
#define BOOT_ERR_FLASH          -2          // Flash操作失败
#define BOOT_ERR_CRC            -3          // CRC校验失败
#define BOOT_ERR_MAGIC          -4          // 魔术字错误
#define BOOT_ERR_NO_UPDATE      -5          // 没有待处理的更新

/*****************************************************************************
* 数据类型定义
*****************************************************************************/

/**
 * @brief Boot标记结构体（32字节对齐）
 */
typedef struct {
    uint32_t u32Magic;           // 魔术字：0x424F4F54 ("BOOT")
    uint32_t u32UpdateFlag;      // 更新标志：0x5A5A5A5A = 有更新待处理
    uint32_t u32FirmwareSize;    // 暂存区固件大小
    uint32_t u32FirmwareCRC;     // 暂存区固件CRC32
    uint32_t u32Version;         // 新固件版本号
    uint32_t u32SrcAddress;      // 源地址（暂存区）
    uint32_t u32DstAddress;      // 目标地址（APP运行区）
    uint32_t u32BootMarkCRC;     // 本结构体的CRC32（除本字段外的前28字节）
} BootMark_t;

/*****************************************************************************
* 函数声明
*****************************************************************************/

/**
 * @brief 初始化Boot标记模块
 * @return BOOT_OK=成功，其他=失败
 */
int32_t BootMark_Init(void);

/**
 * @brief 读取Boot标记
 * @param pMark 输出Boot标记结构体
 * @return BOOT_OK=成功，BOOT_ERR_CRC=CRC错误，BOOT_ERR_MAGIC=魔术字错误
 */
int32_t BootMark_Read(BootMark_t *pMark);

/**
 * @brief 写入Boot标记（请求更新）
 * @param pMark Boot标记结构体
 * @return BOOT_OK=成功，其他=失败
 */
int32_t BootMark_Write(const BootMark_t *pMark);

/**
 * @brief 清除Boot标记（更新完成或取消）
 * @return BOOT_OK=成功，其他=失败
 */
int32_t BootMark_Clear(void);

/**
 * @brief 验证暂存区固件完整性（CRC32校验）
 * @param pMark Boot标记（包含暂存区地址、大小、CRC）
 * @return BOOT_OK=校验通过，BOOT_ERR_CRC=校验失败
 */
int32_t BootMark_VerifyStaging(const BootMark_t *pMark);

/**
 * @brief 计算Boot标记的CRC32（用于pMark->u32BootMarkCRC字段）
 * @param pMark Boot标记结构体
 * @return CRC32值
 */
uint32_t BootMark_CalculateCRC(const BootMark_t *pMark);

#ifdef __cplusplus
}
#endif

#endif /* __BOOTMARK_H__ */