UBS Engine API 参考指南 ​

#include <ubs_engine.h>
int32_t ubs_engine_client_initialize(const char *ubs_engine_uds_path);

#include <stdio.h>
#include <ubs_engine.h>

int main(void)
{
    int32_t ret;

    char *path = "/var/run/ubse/ubse.sock";
    ret = ubs_engine_client_initialize(path);
    if (UBS_SUCCESS != ret) {
        perror("init failed.\n");
        return -1;
    }
        
    /* Do your work here... */

    /* Do your work here... */

    return 0;
}

#include <ubs_engine.h>
void ubs_engine_client_finalize(void);

#include <stdio.h>
#include <ubs_engine.h>

int main(void)
{
    int32_t ret;

    char *path = "/var/run/ubse/ubse.sock";
    ret = ubs_engine_client_initialize(path);
    if (UBS_SUCCESS != ret) {
        perror("init failed.\n");
        return -1;
    }
        
    /* Do your work here... */

    ubs_engine_client_finalize();

    return 0;
}

#include <ubs_engine_log.h>
void ubs_engine_log_callback_register(ubs_engine_log_handler handler);

#include <stdio.h>
#include <ubs_engine_log.h>

static void simple_log_handler(uint32_t level, const char *message)
{
    printf("[level=%u] %s\n", level, message ? message : "(null)");
}

int main(void)
{
    ubs_engine_log_callback_register(simple_log_handler);

    /* Do your work here... */

    return 0;
}

#include <ubs_engine_log.h>

int main(void)
{
    ubs_engine_log_callback_register(NULL);
    return 0;
}

#include <ubs_engine_topo.h>
int32_t ubs_topo_node_list(ubs_topo_node_t **node_list, uint32_t *node_cnt);

#define UBS_TOPO_SOCKET_NUM 2
#define UBS_TOPO_IPADDR_NUM 50
#define UBS_TOPO_NUMA_NUM 4

typedef struct {
    int32_t af;           // 地址族，ipv4为AF_INET，ipv6为AF_INET6
    struct in_addr ipv4;  // ipv4地址
    struct in6_addr ipv6; // IPv6地址
} ubs_topo_ip_address_t;

typedef struct {
    uint32_t slot_id;                                      // 节点唯一标识
    uint32_t socket_id[UBS_TOPO_SOCKET_NUM];               // socket id 列表
    uint32_t numa_ids[UBS_TOPO_SOCKET_NUM][UBS_TOPO_NUMA_NUM]; // socket 下的 numa id 列表
    ubs_topo_ip_address_t ips[UBS_TOPO_IPADDR_NUM];        // IP 地址列表
    char host_name[HOST_NAME_MAX];                         // 主机名
} ubs_topo_node_t;

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_topo.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    ubs_topo_node_t *node_list = NULL;
    uint32_t node_cnt = 0;

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_topo_node_list(&node_list, &node_cnt);
    if (ret != UBS_SUCCESS) {
        perror("get nodes failed");
        ubs_engine_client_finalize();
        return -1;
    }

    /* Do your work here... */

    free(node_list);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_topo.h>
int32_t ubs_topo_node_local_get(ubs_topo_node_t *node);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_topo.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    ubs_topo_node_t local_node;

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_topo_node_local_get(&local_node);
    if (ret != UBS_SUCCESS) {
        perror("get local node failed");
        ubs_engine_client_finalize();
        return -1;
    }

    /* Do your work here... */

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_topo.h>
int32_t ubs_topo_link_list(ubs_topo_link_t **cpu_links, uint32_t *cpu_link_cnt);

typedef struct {
    uint32_t slot_id;        // 节点id
    uint32_t socket_id;      // socket id, 0xFFFFFFFF表示无效值
    uint32_t port_id;        // 端口id
    uint32_t peer_slot_id;   // 对端节点id
    uint32_t peer_socket_id; // 对端socket id, 0xFFFFFFFF表示无效值
    uint32_t peer_port_id;   // 对端端口id
} ubs_topo_link_t;

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_topo.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    ubs_topo_link_t *cpu_links = NULL;
    uint32_t cpu_link_cnt = 0;

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_topo_link_list(&cpu_links, &cpu_link_cnt);
    if (ret != UBS_SUCCESS) {
        perror("get node cpu list failed");
        ubs_engine_client_finalize();
        return -1;
    }

    /* Do your work here... */

    free(cpu_links);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_numastat_get(uint32_t slot_id, ubs_mem_numastat_t **numa_mems, uint32_t *numa_mem_cnt);

typedef enum {
    NUMA_LOCAL, // 本地numa
    NUMA_REMOTE // 远端numa, 当前不支持
} ubs_mem_numa_type_t;

typedef struct {
    uint32_t slot_id;              // 节点唯一标识, 采用slotid, 与UBM保持一致
    uint32_t socket_id;            // socket id
    uint32_t numa_id;              // 节点中的 numa id
    ubs_mem_numa_type_t numa_type; // numa 类型
    uint32_t mem_lend_ratio;       // 池化内存借出比例上限
    uint64_t mem_total;            // 内存总量, 单位字节
    uint64_t mem_free;             // 内存空闲量, 单位字节
    uint32_t huge_pages_2M;        // 2M大页数量
    uint32_t free_huge_pages_2M;   // 2M大页空闲数量
    uint32_t huge_pages_1G;        // 1G大页数量
    uint32_t free_huge_pages_1G;   // 1G大页空闲数量
    uint64_t mem_borrow;           // 借用的内存，单位字节
    uint64_t mem_lend;             // 借出的内存，单位字节
} ubs_mem_numastat_t;

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    uint32_t node_id = 1;
    uint32_t numa_mem_cnt = 0;
    ubs_mem_numastat_t *numa_mem = NULL;

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_numastat_get(node_id, &numa_mem, &numa_mem_cnt);
    if (ret != UBS_SUCCESS) {
        perror("get numastat failed");
        ubs_engine_client_finalize();
        return -1;
    }

    /* Do your work here... */

    free(numa_mem);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_create(const char *name, uint64_t size, const ubs_mem_fd_owner_t *owner, mode_t mode,
                          ubs_mem_distance_t distance, ubs_mem_fd_desc_t *fd_desc);

// 使用方进程信息
typedef struct {
    uid_t uid; // 属主进程的运行用户的uid
    gid_t gid; // 属主进程的运行用户的groupid
    pid_t pid; // 属主进程的运行用户的pid, 指定pid时, pid消失后自动释放借用内存(暂不提供)
} ubs_mem_fd_owner_t;

typedef enum {
    MEM_DISTANCE_L0, // L0对应直连节点
    MEM_DISTANCE_L1, // L1对应通过1跳节点, 暂不支持
    MEM_DISTANCE_L2  // L2对应超过1跳节点, 暂不支持
} ubs_mem_distance_t;

typedef struct {
    uint64_t lender_size; // 借出内存大小, 单位Byte, 取值范围大于或等于4*1024*1024
    uint32_t slot_id;     // 节点唯一标识, 采用slotid, 与lcne保持一致
    uint32_t socket_id;   // socket id
    uint32_t numa_id;     // 节点中的numa id
    uint32_t port_id;     // 指定链路借用
} ubs_mem_lender_t;

typedef enum {
    UBSE_NOT_EXIST = 0,         // 借用关系不存在
    UBSE_CREATING = 1,          // 正在创建中
    UBSE_DELETING = 2,          // 正在删除中
    UBSE_EXIST = 3,             // 创建成功
    UBSE_ERR_ONLY_IMPORT = 4,   // 只存在借入
    UBSE_ERR_WAIT_UNEXPORT = 5, // 等待unexport执行，对账会执行，可以手动删除
    UBSE_ERR_ABNORMAL = 6,      // 删除导入失败，账本与实际状态不一致
    UBSE_END = 7                // 类型转换边界值, 不表示任何内存状态
} ubs_mem_stage;

#define UBS_MEM_MAX_NAME_LENGTH 48
#define UBS_MEM_MAX_MEMID_NUM 2048

typedef struct {
    char name[UBS_MEM_MAX_NAME_LENGTH];     // 借用标识
    uint32_t memid_cnt;                     // 导出的内存块数量
    uint64_t memids[UBS_MEM_MAX_MEMID_NUM]; // 内存块标识信息，对应设备路径格式为 /dev/obmm_shmdev<memid>
    uint64_t mem_size;                      // 借用大小
    size_t unit_size;                       // 芯片表项拆分粒度, 单位Byte
    ubs_topo_node_t export_node;            // 借出节点, 其中ips字段无效, 需通过topo接口获取
    ubs_topo_node_t import_node;            // 借入节点, 其中ips字段无效, 需通过topo接口获取
    ubs_mem_stage mem_stage;                // 内存状态
} ubs_mem_fd_desc_t;

#include <stdio.h>
#include <unistd.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    ubs_mem_fd_owner_t owner = {
        .uid = getuid(),
        .gid = getgid(),
        .pid = getpid()
    };
    mode_t mode = 0x700;
    const char *name = "test_mem";
    uint64_t size = 1024ULL * 1024ULL * 1024ULL;
    ubs_mem_distance_t dist = MEM_DISTANCE_L0;
    ubs_mem_fd_desc_t fd_desc;

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_create(name, size, &owner, mode, dist, &fd_desc);
    if (ret != UBS_SUCCESS) {
        perror("create fd mem failed");
        ubs_engine_client_finalize();
        return -1;
    }

    /* Do your work here... */

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_create_with_lender(const char *name, const ubs_mem_fd_owner_t *owner, mode_t mode,
                                      const ubs_mem_lender_t *lender, uint32_t lender_cnt, ubs_mem_fd_desc_t *fd_desc);

typedef struct {
    uint64_t lender_size; // 借出内存大小，单位Byte, 取值范围大于或等于4*1024*1024
    uint32_t slot_id;     // 节点唯一标识，采用slotid, 与lcne保持一致
    uint32_t socket_id;   // socket id
    uint32_t numa_id;     // 节点中的 numa id
    uint32_t port_id;     // 指定链路借用
} ubs_mem_lender_t;

#include <stdio.h>
#include <unistd.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    ubs_mem_fd_owner_t owner = {
        .uid = getuid(),
        .gid = getgid(),
        .pid = getpid()
    };
    mode_t mode = 0x700;
    const char *name = "test_mem";
    ubs_mem_fd_desc_t fd_desc;
    ubs_mem_lender_t lender = {
        .lender_size = 128ULL * 1024ULL * 1024ULL,
        .slot_id = 2,
        .socket_id = UINT32_MAX,
        .numa_id = 1,
        .port_id = UINT32_MAX
    };

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_create_with_lender(name, &owner, mode, &lender, 1, &fd_desc);
    if (ret != UBS_SUCCESS) {
        perror("create fd mem with lender failed");
        ubs_engine_client_finalize();
        return -1;
    }

    /* Do your work here... */

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_create_with_candidate(const char *name, uint64_t size, const ubs_mem_fd_owner_t *owner, mode_t mode,
                                         const uint32_t *slot_ids, uint32_t slot_cnt, ubs_mem_fd_desc_t *fd_desc);

#include <stdio.h>
#include <unistd.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    ubs_mem_fd_owner_t owner = {
        .uid = getuid(),
        .gid = getgid(),
        .pid = getpid()
    };
    mode_t mode = 0x700;
    const char *name = "test_mem";
    uint64_t size = 1024ULL * 1024ULL * 1024ULL;
    uint32_t slot_ids[2] = {1, 2};
    ubs_mem_fd_desc_t fd_desc;

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_create_with_candidate(name, size, &owner, mode, slot_ids, 2, &fd_desc);
    if (ret != UBS_SUCCESS) {
        perror("create fd mem with candidate failed");
        ubs_engine_client_finalize();
        return -1;
    }

    /* Do your work here... */

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_permission(const char *name, const ubs_mem_fd_owner_t *owner, mode_t mode);

typedef struct {
    uid_t uid; // 属主进程的运行用户的 uid
    gid_t gid; // 属主进程的运行用户的 groupid
    pid_t pid; // 属主进程的运行用户的 pid
} ubs_mem_fd_owner_t;

#include <stdio.h>
#include <unistd.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    const char *path = "/var/run/ubse/ubse.sock";
    ubs_mem_fd_owner_t owner = {
        .uid = getuid(),
        .gid = getgid(),
        .pid = getpid()
    };

    ret = ubs_engine_client_initialize(path);
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_permission("test_mem", &owner, 0x700);
    if (ret != UBS_SUCCESS) {
        perror("set permission failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_get(const char *name, ubs_mem_fd_desc_t *fd_desc);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_fd_desc_t fd_desc;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_get("test_mem", &fd_desc);
    if (ret != UBS_SUCCESS) {
        perror("get fd mem failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_list(ubs_mem_fd_desc_t **fd_descs, uint32_t *fd_desc_cnt);

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_fd_desc_t *fd_descs = NULL;
    uint32_t fd_desc_cnt = 0;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_list(&fd_descs, &fd_desc_cnt);
    if (ret != UBS_SUCCESS) {
        perror("list fd mem failed");
        ubs_engine_client_finalize();
        return -1;
    }

    free(fd_descs);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_delete(const char *name);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_delete("test_mem");
    if (ret != UBS_SUCCESS) {
        perror("delete fd mem failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_create(const char *name, uint64_t size, ubs_mem_distance_t distance,
                            ubs_mem_numa_desc_t *numa_desc);

#define UBS_MEM_MAX_NAME_LENGTH 48
#define UBSE_MAX_USR_INFO_LENGTH 32

typedef struct {
    char name[UBS_MEM_MAX_NAME_LENGTH];        // 借用标识
    int64_t numaid;                            // 形成远端 numa 对应的 numaid
    ubs_topo_node_t export_node;               // 借出节点，其中 ips 字段无效，需通过 topo 接口获取
    ubs_topo_node_t import_node;               // 借入节点，其中 ips 字段无效，需通过 topo 接口获取
    uint64_t size;                             // 借用大小
    ubs_mem_stage mem_stage;                   // 内存状态
    uint8_t usrInfo[UBSE_MAX_USR_INFO_LENGTH]; // 调用方私有数据，UBSE 只负责保存，get 时原样返回
} ubs_mem_numa_desc_t;

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_numa_desc_t numa_desc;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_numa_create("test_numa", 128ULL * 1024ULL * 1024ULL, MEM_DISTANCE_L0, &numa_desc);
    if (ret != UBS_SUCCESS) {
        perror("create numa mem failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_create_with_lender(const char *name, const ubs_mem_lender_t *lender, uint32_t lender_cnt,
                                        ubs_mem_numa_desc_t *numa_desc);

#include <stdio.h>
#include <stdint.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_numa_desc_t numa_desc;
    ubs_mem_lender_t lender = {
        .lender_size = 128ULL * 1024ULL * 1024ULL,
        .slot_id = 2,
        .socket_id = UINT32_MAX,
        .numa_id = 1,
        .port_id = UINT32_MAX
    };

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_numa_create_with_lender("test_numa", &lender, 1, &numa_desc);
    if (ret != UBS_SUCCESS) {
        perror("create numa with lender failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_create_with_candidate(const char *name, uint64_t size, const uint32_t *slot_ids, uint32_t slot_cnt,
                                           ubs_mem_numa_desc_t *numa_desc);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    uint32_t slot_ids[2] = {1, 2};
    ubs_mem_numa_desc_t numa_desc;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_numa_create_with_candidate("test_numa", 128ULL * 1024ULL * 1024ULL, slot_ids, 2, &numa_desc);
    if (ret != UBS_SUCCESS) {
        perror("create numa with candidate failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_get(const char *name, ubs_mem_numa_desc_t *numa_desc);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_numa_desc_t numa_desc;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_numa_get("test_numa", &numa_desc);
    if (ret != UBS_SUCCESS) {
        perror("get numa failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_list(ubs_mem_numa_desc_t **numa_descs, uint32_t *numa_desc_cnt);

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_numa_desc_t *numa_descs = NULL;
    uint32_t numa_desc_cnt = 0;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_numa_list(&numa_descs, &numa_desc_cnt);
    if (ret != UBS_SUCCESS) {
        perror("list numa mem failed");
        ubs_engine_client_finalize();
        return -1;
    }

    free(numa_descs);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_delete(const char *name);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_numa_delete("test_numa");
    if (ret != UBS_SUCCESS) {
        perror("delete numa failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_create(const char *name, uint64_t size, uint8_t usr_info[32], uint64_t flag,
                           const ubs_mem_nodes_t *region, const ubs_mem_nodes_t *provider);

#define UBS_MEM_MAX_SLOT_NUM 16
#define UBS_MEM_MAX_USR_INFO_LEN 32
#define UBS_MEM_FLAG_NO_WR_DELAY 0x1   // 非写接力
#define UBS_MEM_FLAG_SHM_ANONYMOUS 0x2 // 共享内存没有使用方时，后台对账时自动清理提供方
#define UBS_MEM_FLAG_CACHEABLE 0x4     // 设置 cacheableFlag 为 1

typedef struct {
    uint32_t node_cnt;                        // 实际有效的节点数量
    uint32_t slot_ids[UBS_MEM_MAX_SLOT_NUM];  // 节点 ID 数组
} ubs_mem_nodes_t;

#include <stdio.h>
#include <string.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    uint8_t usr_info[UBS_MEM_MAX_USR_INFO_LEN] = {0};
    ubs_mem_nodes_t region = {
        .node_cnt = 2,
        .slot_ids = {1, 2}
    };

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_create("demo_shm", 4ULL * 1024ULL * 1024ULL, usr_info, 0, &region, NULL);
    if (ret != UBS_SUCCESS) {
        perror("create shm failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_create_with_affinity(const char *name, uint64_t size, uint32_t affinity_socket_id,
                                         uint8_t usr_info[32], uint64_t flag, const ubs_mem_nodes_t *region,
                                         const ubs_mem_nodes_t *provider);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    uint8_t usr_info[UBS_MEM_MAX_USR_INFO_LEN] = {0};
    ubs_mem_nodes_t region = {
        .node_cnt = 2,
        .slot_ids = {1, 2}
    };

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_create_with_affinity("demo_shm", 4ULL * 1024ULL * 1024ULL, 0, usr_info, 0, &region, NULL);
    if (ret != UBS_SUCCESS) {
        perror("create shm with affinity failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_create_with_lender(const char *name, uint8_t usr_info[32], uint64_t flag,
                                       const ubs_mem_nodes_t *region, const ubs_mem_lender_t *lender);

typedef struct {
    uint64_t lender_size; // 借出内存大小，单位 Byte, 取值范围大于或等于 4*1024*1024
    uint32_t slot_id;     // 节点唯一标识，采用 slotid, 与 lcne 保持一致
    uint32_t socket_id;   // socket id
    uint32_t numa_id;     // 节点中的 numa id
    uint32_t port_id;     // 指定链路借用
} ubs_mem_lender_t;

#include <stdio.h>
#include <stdint.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    uint8_t usr_info[UBS_MEM_MAX_USR_INFO_LEN] = {0};
    ubs_mem_nodes_t region = {
        .node_cnt = 2,
        .slot_ids = {1, 2}
    };
    ubs_mem_lender_t lender = {
        .slot_id = 2,
        .numa_id = 1,
        .socket_id = UINT32_MAX,
        .port_id = UINT32_MAX,
        .lender_size = 128ULL * 1024ULL * 1024ULL
    };

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_create_with_lender("demo_shm", usr_info, 0, &region, &lender);
    if (ret != UBS_SUCCESS) {
        perror("create shm with lender failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_attach(const char *name, const ubs_mem_fd_owner_t *owner, mode_t mode,
                           ubs_mem_shm_desc_t **shm_desc);

#define UBS_MEM_MAX_MEMID_NUM 2048
#define UBS_MEM_MAX_NAME_LENGTH 48
#define UBS_MEM_MAX_USR_INFO_LEN 32

typedef struct {
    uint32_t memid_cnt;                     // 导出的内存块数量
    uint64_t memids[UBS_MEM_MAX_MEMID_NUM]; // 内存块标识信息，对应设备路径格式为 /dev/obmm_shmdev<memid>
    ubs_topo_node_t import_node;            // 借入节点，其中 ips 字段无效，需通过 topo 接口获取
    ubs_mem_stage mem_stage;                // 内存状态
} ubs_mem_shm_import_desc_t;

typedef struct {
    char name[UBS_MEM_MAX_NAME_LENGTH];     // 借用标识
    uint64_t mem_size;                      // 借用大小
    size_t unit_size;                       // 芯片表项拆分粒度，单位 Byte
    ubs_topo_node_t export_node;            // 借出节点，其中 ips 字段无效，需通过 topo 接口获取
    uint8_t usr_info[UBS_MEM_MAX_USR_INFO_LEN]; // 调用方私有数据
    uint32_t import_desc_cnt;               // 导入内存描述符信息的数量
    ubs_mem_stage mem_stage;                // 内存状态
    ubs_mem_shm_import_desc_t *import_desc; // 导入内存描述符信息
} ubs_mem_shm_desc_t;

#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_fd_owner_t owner = {
        .uid = getuid(),
        .gid = getgid(),
        .pid = getpid()
    };
    ubs_mem_shm_desc_t *shm_desc = NULL;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_attach("demo_shm", &owner, 0666, &shm_desc);
    if (ret != UBS_SUCCESS) {
        perror("attach shm failed");
        ubs_engine_client_finalize();
        return -1;
    }

    free(shm_desc);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_get(const char *name, ubs_mem_shm_desc_t **shm_desc);

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_shm_desc_t *shm_desc = NULL;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_get("demo_shm", &shm_desc);
    if (ret != UBS_SUCCESS) {
        perror("get shm failed");
        ubs_engine_client_finalize();
        return -1;
    }

    free(shm_desc);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_list(ubs_mem_shm_desc_t **shm_descs, uint32_t *shm_desc_cnt);

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_shm_desc_t *shm_descs = NULL;
    uint32_t shm_desc_cnt = 0;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_list(&shm_descs, &shm_desc_cnt);
    if (ret != UBS_SUCCESS) {
        perror("list shm failed");
        ubs_engine_client_finalize();
        return -1;
    }

    free(shm_descs);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_list_with_prefix(const char *name_prefix, ubs_mem_shm_desc_t **shm_descs, uint32_t *shm_desc_cnt);

#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_shm_desc_t *shm_descs = NULL;
    uint32_t shm_desc_cnt = 0;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_list_with_prefix("demo", &shm_descs, &shm_desc_cnt);
    if (ret != UBS_SUCCESS) {
        perror("list shm with prefix failed");
        ubs_engine_client_finalize();
        return -1;
    }

    free(shm_descs);
    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_detach(const char *name);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_detach("demo_shm");
    if (ret != UBS_SUCCESS) {
        perror("detach shm failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_delete(const char *name);

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_delete("demo_shm");
    if (ret != UBS_SUCCESS) {
        perror("delete shm failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_fault_get(const char *name, ubs_mem_memids_fault_t *fault);

typedef enum {
    UB_MEM_ATOMIC_DATA_ERR = 0,
    UB_MEM_READ_DATA_ERR,
    UB_MEM_FLOW_POISON,
    UB_MEM_FLOW_READ_AUTH_POISON,
    UB_MEM_FLOW_READ_AUTH_RESPERR,
    UB_MEM_TIMEOUT_POISON,
    UB_MEM_TIMEOUT_RESPERR,
    UB_MEM_READ_DATA_POISON,
    UB_MEM_READ_DATA_RESPERR,
    MAR_NOPORT_VLD_INT_ERR, // 无物理地址
    MAR_FLUX_INT_ERR,
    MAR_WITHOUT_CXT_ERR,
    RSP_BKPRE_OVER_TIMEOUT_ERR, // 无物理地址
    MAR_NEAR_AUTH_FAIL_ERR,
    MAR_FAR_AUTH_FAIL_ERR,
    MAR_TIMEOUT_ERR,
    MAR_ILLEGAL_ACCESS_ERR,
    REMOTE_READ_DATA_ERR_OR_WRITE_RESPONSE_ERR,
    MEM_EXPORT_FAULT,
    MEM_LINK_DOWN,
    MEM_LINK_UP,
    UB_MEM_HEALTHY = 1000, // 无故障
} ubs_mem_fault_type_t;

#define UBS_MEM_MAX_MEMID_NUM 2048

typedef struct {
    uint32_t memid_cnt;                                       // 导出的内存块数量
    uint64_t memids[UBS_MEM_MAX_MEMID_NUM];                   // 导出内存块标识信息
    ubs_mem_fault_type_t memid_status[UBS_MEM_MAX_MEMID_NUM]; // 内存块的健康状态，与 memids 一一对应
} ubs_mem_memids_fault_t;

#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

int main(void)
{
    int32_t ret;
    ubs_mem_memids_fault_t fault_info;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_fault_get("demo_shm", &fault_info);
    if (ret != UBS_SUCCESS) {
        perror("get shm fault failed");
        ubs_engine_client_finalize();
        return -1;
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_fault_register(ubs_mem_shm_fault_handler handler);

typedef int32_t (*ubs_mem_shm_fault_handler)(const char *name, uint64_t memid, ubs_mem_fault_type_t type);

typedef enum {
    UB_MEM_ATOMIC_DATA_ERR = 0,
    UB_MEM_READ_DATA_ERR,
    UB_MEM_FLOW_POISON,
    UB_MEM_FLOW_READ_AUTH_POISON,
    UB_MEM_FLOW_READ_AUTH_RESPERR,
    UB_MEM_TIMEOUT_POISON,
    UB_MEM_TIMEOUT_RESPERR,
    UB_MEM_READ_DATA_POISON,
    UB_MEM_READ_DATA_RESPERR,
    MAR_NOPORT_VLD_INT_ERR,
    MAR_FLUX_INT_ERR,
    MAR_WITHOUT_CXT_ERR,
    RSP_BKPRE_OVER_TIMEOUT_ERR,
    MAR_NEAR_AUTH_FAIL_ERR,
    MAR_FAR_AUTH_FAIL_ERR,
    MAR_TIMEOUT_ERR,
    MAR_ILLEGAL_ACCESS_ERR,
    REMOTE_READ_DATA_ERR_OR_WRITE_RESPONSE_ERR,
    MEM_EXPORT_FAULT,
    MEM_LINK_DOWN,
    MEM_LINK_UP,
    UB_MEM_HEALTHY = 1000,
} ubs_mem_fault_type_t;

#include <stdio.h>
#include <signal.h>
#include <unistd.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

static volatile int g_running = 1;

static void signal_handler(int sig)
{
    (void)sig;
    g_running = 0;
}

int32_t shm_fault_handler(const char *name, uint64_t memid, ubs_mem_fault_type_t type)
{
    printf("receive shm fault event, name=%s, memid=%lu, type=%d\n", name, memid, type);
    return 0;
}

int main(void)
{
    int32_t ret;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_shm_fault_register(shm_fault_handler);
    if (ret != 0) {
        perror("register shm fault handler failed");
        ubs_engine_client_finalize();
        return -1;
    }

    signal(SIGINT, signal_handler);
    signal(SIGTERM, signal_handler);

    printf("shm fault handler registered, waiting for events... (press Ctrl+C to exit)\n");
    while (g_running) {
        pause();
    }

    ubs_engine_client_finalize();
    return 0;
}

#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_fault_register(ubs_mem_fd_fault_handler handler);

typedef int32_t (*ubs_mem_fd_fault_handler)(const char *name, uint64_t memid, ubs_mem_fault_type_t type);

typedef enum {
    UB_MEM_ATOMIC_DATA_ERR = 0,
    UB_MEM_READ_DATA_ERR,
    UB_MEM_FLOW_POISON,
    UB_MEM_FLOW_READ_AUTH_POISON,
    UB_MEM_FLOW_READ_AUTH_RESPERR,
    UB_MEM_TIMEOUT_POISON,
    UB_MEM_TIMEOUT_RESPERR,
    UB_MEM_READ_DATA_POISON,
    UB_MEM_READ_DATA_RESPERR,
    MAR_NOPORT_VLD_INT_ERR,
    MAR_FLUX_INT_ERR,
    MAR_WITHOUT_CXT_ERR,
    RSP_BKPRE_OVER_TIMEOUT_ERR,
    MAR_NEAR_AUTH_FAIL_ERR,
    MAR_FAR_AUTH_FAIL_ERR,
    MAR_TIMEOUT_ERR,
    MAR_ILLEGAL_ACCESS_ERR,
    REMOTE_READ_DATA_ERR_OR_WRITE_RESPONSE_ERR,
    MEM_EXPORT_FAULT,
    MEM_LINK_DOWN,
    MEM_LINK_UP,
    UB_MEM_HEALTHY = 1000,
} ubs_mem_fault_type_t;

#include <stdio.h>
#include <signal.h>
#include <unistd.h>
#include <ubs_engine.h>
#include <ubs_engine_mem.h>

static volatile int g_running = 1;

static void signal_handler(int sig)
{
    (void)sig;
    g_running = 0;
}

int32_t fd_fault_handler(const char *name, uint64_t memid, ubs_mem_fault_type_t type)
{
    printf("receive fd fault event, name=%s, memid=%lu, type=%d\n", name, memid, type);
    return 0;
}

int main(void)
{
    int32_t ret;

    ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
    if (ret != UBS_SUCCESS) {
        perror("init failed");
        return -1;
    }

    ret = ubs_mem_fd_fault_register(fd_fault_handler);
    if (ret != 0) {
        perror("register fd fault handler failed");
        ubs_engine_client_finalize();
        return -1;
    }

    signal(SIGINT, signal_handler);
    signal(SIGTERM, signal_handler);

    printf("fd fault handler registered, waiting for events... (press Ctrl+C to exit)\n");
    while (g_running) {
        pause();
    }

    ubs_engine_client_finalize();
    return 0;
}