// Copyright (2025) Beijing Volcano Engine Technology Ltd.
// SPDX-License-Identifier: Apache-2.0

// 火山引擎平台适配层头文件 - 定义硬件抽象层的接口和数据结构
// 高性能版本针对ESP32平台的系统调用和资源管理进行了优化

#ifndef __CONV_AI_PLATFORM_VOLC_PLATFORM_H__
#define __CONV_AI_PLATFORM_VOLC_PLATFORM_H__

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

// 内存管理函数声明
void* hal_malloc(size_t size);                          // 内存分配
void* hal_calloc(size_t num, size_t size);              // 内存分配并清零
void* hal_realloc(void* ptr, size_t new_size);          // 内存重新分配
void hal_free(void* ptr);                               // 内存释放
#define HAL_SAFE_FREE(ptr) do { if (ptr) { hal_free(ptr); ptr = NULL; } } while (0)  // 安全释放宏

// 互斥锁类型定义和函数声明
typedef void* hal_mutex_t;                              // 互斥锁句柄
hal_mutex_t hal_mutex_create(void);                    // 创建互斥锁
void hal_mutex_lock(hal_mutex_t mutex);                // 加锁
void hal_mutex_unlock(hal_mutex_t mutex);              // 解锁
void hal_mutex_destroy(hal_mutex_t mutex);             // 销毁互斥锁

// 时间管理函数声明
uint64_t hal_get_time_ms(void);                        // 获取当前时间（毫秒）

// 设备标识函数声明
int hal_get_uuid(char* uuid, size_t size);             // 获取设备UUID

// 线程管理相关定义
#define THREAD_NAME_MAX_LEN 16                         // 线程名称最大长度
typedef void* hal_tid_t;                                // 线程句柄

// 线程参数结构体 - 配置线程创建参数
typedef struct {
    char name[THREAD_NAME_MAX_LEN];                    // 线程名称
    int priority;                                      // 线程优先级
    int stack_size;                                   // 栈大小
    int bind_cpu;                                     // CPU绑定
    int stack_in_ext;                                 // 是否使用外部栈
} hal_thread_param_t;

// 线程管理函数声明
int hal_thread_create(hal_tid_t* thread, const hal_thread_param_t* param, void (*start_routine)(void *), void* args);  // 创建线程
int hal_thread_detach(hal_tid_t thread);               // 分离线程
void hal_thread_exit(hal_tid_t thread);                // 退出线程
void hal_thread_sleep(int time_ms);                     // 线程休眠
void hal_thread_destroy(hal_tid_t thread);             // 销毁线程

// 平台信息函数声明
int hal_get_platform_info(char* info, size_t size);    // 获取平台信息

// 随机数函数声明
int hal_fill_random(uint8_t* data, size_t size);       // 填充随机数

#ifdef __cplusplus
}
#endif
#endif /* __CONV_AI_PLATFORM_VOLC_PLATFORM_H__ */