scc/libs/sccf/include/sccf_utils.h

/**
 * @file sccf_utils.h
 * @brief SCCF 格式辅助函数
 *
 * 提供基于节头表的节定位、查找和遍历函数, 不涉及字节序转换。
 * 假设文件已经为主机字节序。
 */

#ifndef __SCC_FORMAT_UTILS_H__
#define __SCC_FORMAT_UTILS_H__

#include "sccf.h"
#include <scc_core.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @name 节头表定位
 * @{
 */

/**
 * @brief 获取节头表的起始地址
 * @param base 文件缓冲区起始地址
 * @return 节头表指针 (需强制转换为 sccf_sect_header_t*)
 */
static inline u8 *sccf_sect_header_table(u8 *base) {
    return base + sizeof(sccf_header_t);
}

/**
 * @brief 获取指定索引的节头指针
 * @param base 文件缓冲区起始地址
 * @param idx  节索引 (0 <= idx < sect_header_num)
 * @return 指向该节头的指针, 若索引无效返回 null
 */
static inline sccf_sect_header_t *sccf_sect_header(u8 *base, usize idx) {
    sccf_header_t *hdr = (sccf_header_t *)base;
    if (idx >= (usize)hdr->sect_header_num)
        return null;
    u8 *table = sccf_sect_header_table(base);
    return (sccf_sect_header_t *)(table + idx * sizeof(sccf_sect_header_t));
}

/** @} */

/**
 * @name 节数据定位
 * @{
 */

/**
 * @brief 计算指定索引的节数据在文件中的偏移
 * @param base 文件缓冲区起始地址
 * @param idx  节索引
 * @return 数据起始偏移 (相对于文件头) , 若索引无效返回 0, 有效值始终大于 0
 */
static inline usize sccf_sect_data_offset(u8 *base, usize idx) {
    const sccf_header_t *hdr = (const sccf_header_t *)base;
    if (idx >= (usize)hdr->sect_header_num)
        return 0;

    usize offset = sizeof(sccf_header_t) +
                   (usize)hdr->sect_header_num * sizeof(sccf_sect_header_t);
    for (usize i = 0; i < idx; ++i) {
        const sccf_sect_header_t *sh = sccf_sect_header(base, i);
        offset +=
            (usize)sh->size; /* 使用 size 字段作为节数据在文件中的实际大小 */
    }
    return offset;
}

/**
 * @brief 获取指定索引的节数据起始地址
 * @param base 文件缓冲区起始地址
 * @param idx  节索引
 * @return 数据起始地址, 若索引无效返回 null
 */
static inline u8 *sccf_sect_data(u8 *base, usize idx) {
    usize off = sccf_sect_data_offset(base, idx);
    return (off == 0) ? null : base + off;
}

/** @} */

/**
 * @name 节查找
 * @{
 */

/**
 * @brief 查找指定类型的第一个节
 * @param base 文件缓冲区起始地址
 * @param type 要查找的节类型 (如 SCCF_SECT_CODE)
 * @return 节索引, 未找到返回 hdr->sect_header_num
 */
static inline usize sccf_find_sect_by_type(u8 *base, sccf_enum_t type) {
    const sccf_header_t *hdr = (const sccf_header_t *)base;
    for (usize i = 0; i < (usize)hdr->sect_header_num; ++i) {
        sccf_sect_header_t *sh = sccf_sect_header(base, i);
        if (sh->scf_sect_type == type)
            return i;
    }
    return (usize)hdr->sect_header_num;
}

/**
 * @brief 查找指定名称的节
 * @param base 文件缓冲区起始地址
 * @param name 8字节名称 (不足补零, 可用 memcmp 比较)
 * @return 节索引, 未找到返回 hdr->sect_header_num
 */
static inline usize sccf_find_sect_by_name(u8 *base, const u8 name[8]) {
    const sccf_header_t *hdr = (const sccf_header_t *)base;
    for (usize i = 0; i < (usize)hdr->sect_header_num; ++i) {
        const sccf_sect_header_t *sh = sccf_sect_header(base, i);
        if (scc_memcmp(sh->name, name, 8) == 0)
            return i;
    }
    return (usize)hdr->sect_header_num;
}

/** @} */

/**
 * @name 节遍历
 * @{
 */

/**
 * @brief 遍历所有节的回调函数类型
 * @param idx   节索引
 * @param sh    节头指针
 * @param data  节数据起始地址
 * @param size  节数据大小 (即节头的 size 字段)
 * @param user  用户自定义数据
 */
typedef void (*sccf_sect_visit_fn)(usize idx, const sccf_sect_header_t *sh,
                                   const u8 *data, usize size, void *user);

/**
 * @brief 遍历所有节, 对每个节调用回调函数
 * @param base  文件缓冲区起始地址
 * @param visit 回调函数
 * @param user  用户数据透传
 */
static inline void sccf_foreach_sect(u8 *base, sccf_sect_visit_fn visit,
                                     void *user) {
    const sccf_header_t *hdr = (const sccf_header_t *)base;
    for (usize i = 0; i < (usize)hdr->sect_header_num; ++i) {
        sccf_sect_header_t *sh = sccf_sect_header(base, i);
        const u8 *data = sccf_sect_data(base, i);
        if (data) {
            visit(i, sh, data, (usize)sh->size, user);
        }
    }
}

/** @} */

/**
 * @defgroup 序列化和反序列化
 */
typedef SCC_VEC(u8) sccf_buffer_t;
typedef SCC_VEC(u8) sccf_sect_data_t;
typedef SCC_VEC(sccf_sect_data_t) sccf_sect_data_vec_t;
typedef SCC_VEC(sccf_sect_header_t) sccf_sect_header_vec_t;

typedef struct {
    sccf_header_t header;
    sccf_sect_header_vec_t sect_headers;
    sccf_sect_data_vec_t sect_datas;
} sccf_t;

/**
 * @brief 初始化sccf
 * @param[out] sccf
 */
static inline void sccf_init(sccf_t *sccf) {
    scc_memcpy(sccf->header.magic, SCCF_MAGIC, sizeof(sccf->header.magic));
    sccf->header.type = 0;
    sccf->header.version = SCCF_VERSION;
    sccf->header.arch = SCCF_ARCH_UNKNOWN;
    sccf->header.entry_point = 0;
    sccf->header.sect_header_num = 0;
    scc_memset(sccf->header.reserved, 0, sizeof(sccf->header.reserved));
    scc_vec_init(sccf->sect_headers);
    scc_vec_init(sccf->sect_datas);
}

/**
 * @brief 从buffer解析到sccf可以选择是否复制, 如果不复制则不能修改
 * @warning 注意内存释放, 如果选择复制的话
 *
 * @param[out] sccf
 * @param[in] buffer
 * @param[in] copied
 */
static inline void sccf_parse(sccf_t *sccf, sccf_buffer_t *buffer, int copied) {
    u8 *data = scc_vec_unsafe_get_data(*buffer);
    sccf->header = *(sccf_header_t *)data;
    usize offset = sizeof(sccf_header_t);
    if (copied) {
        scc_vec_init(sccf->sect_headers);
        for (usize i = 0; i < sccf->header.sect_header_num; i += 1) {
            scc_vec_push(sccf->sect_headers,
                         *(sccf_sect_header_t *)(data + offset));
            offset += sizeof(sccf_sect_header_t);
        }
    } else {
        u8 *header_table = data + offset;
        scc_vec_unsafe_from_buffer(sccf->sect_headers,
                                   (sccf_sect_header_t *)header_table,
                                   sccf->header.sect_header_num);
        offset += sizeof(sccf_sect_header_t) * sccf->header.sect_header_num;
    }

    scc_vec_init(sccf->sect_datas);
    scc_vec_foreach(sccf->sect_headers, i) {
        sccf_sect_header_t *header = &scc_vec_at(sccf->sect_headers, i);
        sccf_sect_data_t sect_data;
        scc_vec_init(sect_data);
        if (copied) {
            scc_vec_realloc(sect_data, header->size);
            scc_memcpy(scc_vec_unsafe_get_data(sect_data), data + offset,
                       header->size);
            scc_vec_size(sect_data) = header->size;
        } else {
            scc_vec_unsafe_from_buffer(sect_data, data + offset, header->size);
        }
        scc_vec_push(sccf->sect_datas, sect_data);
        offset += header->size;
    }
}

/**
 * @brief 获取sccf大小
 *
 * @param[in] sccf
 * @return usize
 */
static inline usize sccf_size(sccf_t *sccf) {
    if (scc_vec_size(sccf->sect_datas) != scc_vec_size(sccf->sect_headers) ||
        scc_vec_size(sccf->sect_headers) != sccf->header.sect_header_num) {
        Panic();
    }
    usize size = sizeof(sccf_header_t);
    size += sizeof(sccf_sect_header_t) * sccf->header.sect_header_num;
    scc_vec_foreach(sccf->sect_headers, i) {
        sccf_sect_header_t *sccf_sect_header =
            &scc_vec_at(sccf->sect_headers, i);
        Assert(scc_vec_size(scc_vec_at(sccf->sect_datas, i)) ==
               sccf_sect_header->size);
        size += sccf_sect_header->size;
    }
    return size;
}

/**
 * @brief 将sccf转换成buffer
 * @warning buffer需要被初始化且为空
 *
 * @param[in] sccf
 * @param[out] buffer
 */
static inline void sccf_write(sccf_t *sccf, sccf_buffer_t *buffer) {
    usize size = sccf_size(sccf);
    if (scc_vec_size(*buffer) < size) {
        scc_vec_realloc(*buffer, size);
        scc_vec_size(*buffer) = size;
    }
    u8 *data = scc_vec_unsafe_get_data(*buffer);
    usize offset = 0;
    scc_memcpy(data, &sccf->header, sizeof(sccf_header_t));
    data += sizeof(sccf_header_t);
    scc_memcpy(data, scc_vec_unsafe_get_data(sccf->sect_headers),
               sizeof(sccf_sect_header_t) * sccf->header.sect_header_num);
    data += sizeof(sccf_sect_header_t) * sccf->header.sect_header_num;

    scc_vec_foreach(sccf->sect_datas, i) {
        sccf_sect_data_t *sect_data = &scc_vec_at(sccf->sect_datas, i);
        scc_memcpy(data, scc_vec_unsafe_get_data(*sect_data), sect_data->size);
        data += sect_data->size;
    }
    if (data - scc_vec_unsafe_get_data(*buffer) != size) {
        Panic();
    }
}

#ifdef __cplusplus
}
#endif

#endif /* __SCC_FORMAT_UTILS_H__ */