UBS Engine API 参考指南
前言
概述
UBS Engine（UBSE）提供了UBSE程序及其相应的SDK开发库。开发者可以利用该SDK访问UBSE提供的服务，从而实现对内存等资源的调度与管理。
UBSE SDK通过三种形式提供：
- so动态链接库：C和C++语言的开发。
- Python开发库：支持python协议栈开发。
- Go SDK源码库：支持Go协议栈通过import导入开发。
介绍
本文主要介绍UBS Engine SDK对外提供的API。UBS Engine SDK使用C语言开发，对外提供C语言API接口。
约束条件
UBS Engine对外接口的访问入口，是sock文件/run/ubse/ubse.sock，sock文件的安全访问，基于文件权限控制，其属主为ubse，mode为660，如下：
srw-rw---- ubse ubse /run/ubse/ubse.sock
加入ubse group的用户，才能访问UBSE的SDK接口。
libubse client
ubs_engine_client_initialize
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine.h>
int32_t ubs_engine_client_initialize(const char *ubs_engine_uds_path);
描述 DESCRIPTION
创建ubse客户端，完成内部资源申请，记录uds_path信息
在后续的流程中，根据传入的uds_path创建与ubse服务端的socket连接，并将业务端请求发送给ubse服务端，并等待服务端返回结果。
参数 Parameters
| name | IN/OUT | description |
|---|---|---|
| ubs_engine_uds_path | IN | ubse服务端的uds文件路径 传入空路径，则采用ubse默认地址/var/run/ubse/ubse.sock 路径长度限制：遵从linux sun_path 的大小是 108 字节 (#define UNIX_PATH_MAX 108)，所以路径不能超过 107 个字符（不含结尾的空字符 \0） |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ENGINE_ERR_OUT_OF_RANGE | 参数数据长度超108字节 |
| UBS_ENGINE_ERR_RESOURCE | 资源创建失败 |
约束 CONSTRAINTS
暂无
附注 NOTES
暂无
样例 EXAMPLES
以下程序初始化UBSE客户端，并基于客户端完成后续操作。
#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;
}
ubs_engine_client_finalize
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine.h>
void ubs_engine_client_finalize(void);
描述 DESCRIPTION
销毁ubse客户端，完成内部资源释放
参数 PARAMETERS
无
返回值 RETURN VALUE
无
错误 ERRORS
无
约束 CONSTRAINTS
暂无
附注 NOTES
暂无
样例 EXAMPLES
以下程序初始化UBSE客户端，并基于客户端完成后续操作，并销毁客户端，释放资源。
#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;
}
libubse log
ubs_engine_log_callback_register
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_log.h>
void ubs_engine_log_callback_register(ubs_engine_log_handler handler);
描述 DESCRIPTION
注册日志回调函数。
如果没有注册日志函数，或者传入空指针，则采用标准输出打印日志；如果注册了回调函数，则后续日志通过回调函数返回给调用方处理。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| handler | IN | 日志回调函数 |
- 数据结构说明
typedef void (*ubs_engine_log_handler)(uint32_t level, const char *message);
字段说明：
| name | description |
|---|---|
| level | 日志级别，类型为 uint32_t |
| message | 日志消息内容，字符串以 \0 结尾 |
日志级别取值如下：
| level | enum | description |
|---|---|---|
0 |
DEBUG |
调试日志 |
1 |
INFO |
普通信息日志 |
2 |
WARN |
告警日志 |
3 |
ERROR |
错误日志 |
返回值 RETURN VALUE
无。
错误 ERRORS
无。
约束 CONSTRAINTS
传入 NULL 时，日志输出回退到标准输出。
回调函数由调用方提供，调用方需要自行保证回调函数内部的线程安全和资源管理安全。
附注 NOTES
该接口只负责注册日志处理函数，不负责日志级别过滤。
样例 EXAMPLES
以下程序注册一个简单的日志回调函数，将日志打印到标准输出。
#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;
}
libubse topo
ubs_topo_node_list
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_topo.h>
int32_t ubs_topo_node_list(ubs_topo_node_t **node_list, uint32_t *node_cnt);
描述 DESCRIPTION
查询全量节点信息。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| node_list | OUT | 节点信息数组，调用方需要使用 free 主动释放内存 |
| node_cnt | OUT | 节点信息个数，范围 [0, 512] |
- 数据结构说明
#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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
当前只支持 CPU 节点。
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化 UBSE 客户端，并查询全量节点信息。
#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;
}
ubs_topo_node_local_get
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_topo.h>
int32_t ubs_topo_node_local_get(ubs_topo_node_t *node);
描述 DESCRIPTION
查询本节点信息。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| node | OUT | 节点信息 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
当前只支持 CPU 节点。
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化 UBSE 客户端，并查询本节点信息。
#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;
}
ubs_topo_link_list
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_topo.h>
int32_t ubs_topo_link_list(ubs_topo_link_t **cpu_links, uint32_t *cpu_link_cnt);
描述 DESCRIPTION
查询所有 CPU 类型节点的组网拓扑信息，粒度为硬件连线。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| cpu_links | OUT | CPU 连接信息数组，调用方需要使用 free 主动释放内存 |
| cpu_link_cnt | OUT | CPU 连接信息个数，范围 [0, 1024] |
- 数据结构说明
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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
暂无。
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化 UBSE 客户端，并查询 CPU 拓扑连线信息。
#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;
}
libubse mem
ubs_mem_numastat_get
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
查询指定节点numa信息，仅返回可用节点的numa信息，当前只支持本地numa内存，后续会增加远端numa。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| slot_id | IN | 节点标识 |
| numa_mems | OUT | 节点numa信息数组，调用方需要使用 free 接口主动释放内存 |
| numa_mem_cnt | OUT | 节点numa信息个数，范围 [0, 4] |
- 数据结构说明
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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
| UBS_ENGINE_ERR_NODE_NOT_EXIST | 查询节点不存在 |
| UBS_ENGINE_ERR_NODE_FAULT | 查询节点故障 |
约束 CONSTRAINTS
当前只支持本地numa内存
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化UBSE客户端，并基于客户端完成后续操作。
#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;
}
ubs_mem_fd_create
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
在本节点创建fd形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name在节点内保持唯一性 |
| size | IN | 借用大小，单位Byte，取值范围大于等于 4 * 1024 * 1024 |
| owner | IN | 内存资源使用者属主信息，可选参数，NULL 不关注该字段 |
| mode | IN | 内存资源使用者访问权限，可选参数，0 不关注该字段 |
| distance | IN | 内存访问距离 |
| fd_desc | OUT | 内存描述信息 |
- 数据结构说明
// 使用方进程信息
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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name或者size参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由参数owner和mode标识
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_fd_create_with_lender
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
指定借出信息，在本节点创建fd形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name在节点内保持唯一性 |
| owner | IN | 内存资源使用者属主信息，可选参数，NULL 不关注该字段 |
| mode | IN | 内存资源使用者访问权限，可选参数，0 不关注该字段 |
| lender | IN | 借出信息 |
| lender_cnt | IN | 借出信息个数，最大为4 |
| fd_desc | OUT | 内存描述信息 |
- 数据结构说明
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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由参数owner和mode标识
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_fd_create_with_candidate
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
指定候选借出节点范围，在本节点创建fd形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name在节点内保持唯一性 |
| size | IN | 借用大小，单位Byte，取值范围大于等于 4 * 1024 * 1024 |
| owner | IN | 内存资源使用者属主信息，可选参数，NULL 不关注该字段 |
| mode | IN | 内存资源使用者访问权限，可选参数，0 不关注该字段 |
| slot_ids | IN | 候选借出节点范围，最大为16 |
| slot_cnt | IN | 候选借出节点个数 |
| fd_desc | OUT | 内存描述信息 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由参数owner和mode标识
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_fd_permission
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_permission(const char *name, const ubs_mem_fd_owner_t *owner, mode_t mode);
描述 DESCRIPTION
改变本节点fd形态远端内存的permission信息。
- 调用该接口能操控的资源：创建资源时的标识与本次调用方的标识相同
- 调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name在节点内保持唯一性 |
| owner | IN | 内存资源使用者属主信息，必选参数，不允许为 NULL |
| mode | IN | 内存资源使用者访问权限，必选参数，不允许为 0 |
- 数据结构说明
typedef struct {
uid_t uid; // 属主进程的运行用户的uid
gid_t gid; // 属主进程的运行用户的groupid
pid_t pid; // 属主进程的运行用户的pid
} ubs_mem_fd_owner_t;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由参数owner和mode标识
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_fd_get
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_get(const char *name, ubs_mem_fd_desc_t *fd_desc);
描述 DESCRIPTION
查询本节点fd形态远端内存信息。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name在节点内保持唯一性 |
| fd_desc | OUT | fd内存信息 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能查看资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_fd_list
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_list(ubs_mem_fd_desc_t **fd_descs, uint32_t *fd_desc_cnt);
描述 DESCRIPTION
查询本节点所有fd形态远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| fd_descs | OUT | fd内存描述信息数组，调用成功后需要使用 free 接口主动释放内存 |
| fd_desc_cnt | OUT | fd内存描述信息数组中的元素个数，范围 [0, 2000] |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | 参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能查看资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_fd_delete
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_delete(const char *name);
描述 DESCRIPTION
删除本节点指定fd远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name在节点内保持唯一性 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_IMPORT_ABSENT | IMPORT不在位, 无法删除 |
| UBS_ENGINE_ERR_CREATING | 正在创建过程中 |
| UBS_ENGINE_ERR_DELETING | 正在删除过程中 |
| UBS_ENGINE_ERR_UNIMPORT_SUCCESS | UNIMPORT已经成功, unexport失败, 资源没有释放完全, 后续对账能自动回收 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能删除资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
对于异常场景如username、uid改变或者用户被删除，ubse提供cli命令删除内存能力,具体请参考《ubse_cli_user_guide.md》文档。
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_numa_create
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
在本节点创建numa形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name在节点内保持唯一性 |
| size | IN | 借用大小，单位Byte，取值范围大于等于 4 * 1024 * 1024 |
| distance | IN | 内存访问跳数 |
| numa_desc | OUT | 借用形成的远端numa信息 |
- 数据结构说明
#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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name或者size参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由操作系统的numa内存管理模块管理
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_numa_create_with_lender
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
指定借出信息，在本节点创建numa形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识, name最大长度48字节, 含结尾字符\0 name仅可包括大小写字母、数字、"."、":"、"-"以及"_" name节点内保持唯一性 |
| lender | IN | 借出信息 |
| lender_cnt | IN | 借出信息个数，最大为4 |
| numa_desc | OUT | 借用形成的远端numa信息 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由操作系统的numa内存管理模块管理
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_numa_create_with_candidate
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
指定候选借出节点，在本节点创建numa形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识, name最大长度48字节, 含结尾字符\0 name仅可包括大小写字母、数字、"."、":"、"-"以及"_" name在节点内保持唯一性 |
| size | IN | 借用大小，单位Byte，取值范围大于等于 4 * 1024 * 1024 |
| slot_ids | IN | 候选借出节点范围 |
| slot_cnt | IN | 候选借出节点个数，最大为16 |
| numa_desc | OUT | 借用形成的远端numa信息 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由操作系统的numa内存管理模块管理
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
候选节点与当前借入节点，必须满足直连要求
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_numa_get
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_get(const char *name, ubs_mem_numa_desc_t *numa_desc);
描述 DESCRIPTION
查询本节点numa形态远端内存信息。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识, name最大长度48字节, 含结尾字符\0 name仅可包括大小写字母、数字、"."、":"、"-"以及"_" name节点内保持唯一性 |
| numa_desc | OUT | 借用形成的远端numa信息 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能查看资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_numa_list
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_list(ubs_mem_numa_desc_t **numa_descs, uint32_t *numa_desc_cnt);
描述 DESCRIPTION
查询本节点所有numa形态远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| numa_descs | OUT | numa内存描述信息数组，调用成功后需要使用 free 接口主动释放内存 |
| numa_desc_cnt | OUT | numa内存描述信息数组中的元素个数，范围 [0, 2000] |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | 参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能查看资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_numa_delete
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_delete(const char *name);
描述 DESCRIPTION
删除本节点指定numa远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识, name最大长度48字节, 含结尾字符\0 name仅可包括大小写字母、数字、"."、":"、"-"以及"_" name节点内保持唯一性 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_IMPORT_ABSENT | IMPORT不在位, 无法删除 |
| UBS_ENGINE_ERR_CREATING | 正在创建过程中 |
| UBS_ENGINE_ERR_DELETING | 正在删除过程中 |
| UBS_ENGINE_ERR_UNIMPORT_SUCCESS | UNIMPORT已经成功, unexport失败, 资源没有释放完全, 后续对账能自动回收 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能删除资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
对于异常场景如username、uid改变或者用户被删除，ubse提供cli命令删除内存能力,具体请参考《ubse_cli_user_guide.md》文档。
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_create
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
创建共享形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name全局保持唯一性 |
| size | IN | 借用大小，单位Byte，取值范围大于等于 4 * 1024 * 1024 |
| usr_info | IN | 调用方私有数据，UBSE只负责保存，get时原样返回 |
| flag | IN | 额外的内存借用属性，目前支持写接力、自动清理提供方和设置共享内存属性为CacheCoherent（按位组合，每一个二进制位表示一种独立属性）； 可用标志位定义如下： 0x1: 非写接力 0x2: 匿名内存，共享内存没有使用方时，后台对账会自动清理 0x4: 设置共享内存属性为CacheCoherent (默认为NonCacheCoherent) flag使用说明(flag为十进制数): flag 可以用 | 运算进行赋值,表示开启某个属性，比如：- 非写接力 + 匿名: flag= 0x1 | 0x2 = 3; - 匿名+设置共享内存属性为CacheCoherent: flag = 0x2 | 0x4 = 6 - 非写接力+匿名+设置共享内存属性为CacheCoherent: flag = 0x1 | 0x2 | 0x4 = 7 - 其它属性组合, 使用 flag |= 对应标志位 进行组合即可flag其它取值说明: 0：默认值，代表三个标志位对应的属性都不选择 |
| region | IN | 后续使用共享内存的节点范围，可选参数；NULL 表示取集群中全量节点 |
| provider | IN | 资源提供方节点范围，NULL 表示不指定 |
- 数据结构说明
#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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name或者size参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
资源使用权限分离与管理权限分离
使用者由操作系统的numa内存管理模块管理
资源的管理权限由ubse系统自动授予，权限属于该接口的调用者（使用OS的username/uid标识）
调用者的标识处理原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
借出节点的决策原则：指定provider，则从中选择；没有指定provider，则从region中选择；确保所有节点均能使用共享内存
附注 NOTES
暂无。
样例 EXAMPLES
#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, ®ion, NULL);
if (ret != UBS_SUCCESS) {
perror("create shm failed");
ubs_engine_client_finalize();
return -1;
}
ubs_engine_client_finalize();
return 0;
}
ubs_mem_shm_create_with_affinity
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
创建指定CPU平面的共享形态远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识 name最大长度48字节, 含结尾字符\0 name仅可包括大小写字母、数字、"."、":"、"-"以及"_" name全局保持唯一性 |
| size | IN | 借用大小，单位Byte，取值范围大于等于 4 * 1024 * 1024 |
| affinity_socket_id | IN | 亲和的cpu socket_id |
| usr_info | IN | 调用方私有数据，UBSE只负责保存，get时原样返回 |
| flag | IN | 额外的内存借用属性，目前支持写接力、自动清理提供方和设置共享内存属性为CacheCoherent（按位组合，每一个二进制位表示一种独立属性）； 可用标志位定义如下： 0x1: 非写接力 0x2: 匿名内存，共享内存没有使用方时，后台对账会自动清理 0x4: 设置共享内存属性为CacheCoherent (默认为NonCacheCoherent) flag使用说明(flag为十进制数): flag 可以用 | 运算进行赋值,表示开启某个属性，比如：- 非写接力 + 匿名: flag= 0x1 | 0x2 = 3; - 匿名+设置共享内存属性为CacheCoherent: flag = 0x2 | 0x4 = 6 - 非写接力+匿名+设置共享内存属性为CacheCoherent: flag = 0x1 | 0x2 | 0x4 = 7 - 其它属性组合, 使用 flag |= 对应标志位 进行组合即可flag其它取值说明: 0：默认值，代表三个标志位对应的属性都不选择 |
| region | IN | 使用共享内存的节点范围，可选参数；NULL 表示取集群中全量节点 |
| provider | IN | 资源提供方节点范围，NULL 表示不指定 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name或者size参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
附注 NOTES
affinity_socket_id 需要是有效的 CPU socket 标识。
region 内的节点必须能够通过公共节点直连。
算法决策借出节点；指定资源提供方时从中选择，没有指定时从 region 中选择；确保所有节点均能使用共享内存。
样例 EXAMPLES
#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, ®ion, NULL);
if (ret != UBS_SUCCESS) {
perror("create shm with affinity failed");
ubs_engine_client_finalize();
return -1;
}
ubs_engine_client_finalize();
return 0;
}
ubs_mem_shm_create_with_lender
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
指定借出方创建共享形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识 name最大长度48字节, 含结尾字符\0 name仅可包括大小写字母、数字、"."、":"、"-"以及"_" name全局保持唯一性 |
| usr_info | IN | 调用方私有数据，UBSE只负责保存，get时原样返回 |
| flag | IN | 额外的内存借用属性，目前支持写接力、自动清理提供方和设置共享内存属性为CacheCoherent（按位组合，每一个二进制位表示一种独立属性）； 可用标志位定义如下： 0x1: 非写接力 0x2: 匿名内存，共享内存没有使用方时，后台对账会自动清理 0x4: 设置共享内存属性为CacheCoherent (默认为NonCacheCoherent) flag使用说明(flag为十进制数): flag 可以用 | 运算进行赋值,表示开启某个属性，比如：- 非写接力 + 匿名: flag= 0x1 | 0x2 = 3; - 匿名+设置共享内存属性为CacheCoherent: flag = 0x2 | 0x4 = 6 - 非写接力+匿名+设置共享内存属性为CacheCoherent: flag = 0x1 | 0x2 | 0x4 = 7 - 其它属性组合, 使用 flag |= 对应标志位 进行组合即可flag其它取值说明: 0：默认值，代表三个标志位对应的属性都不选择 |
| region | IN | 使用共享内存的节点范围，可选参数；NULL 表示取集群中全量节点 |
| lender | IN | 指定借出节点数据 |
- 数据结构说明
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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | 参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_EXISTED | 借用关系已存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
附注 NOTES
region 内的节点必须能够通过公共节点直连。
借出节点由 lender 明确指定，不再从 region 自动选择；lender 参数需要满足当前硬件拓扑合法性。
ubs_mem_lender_t 结构体内部字段支持以下赋值，推荐无效值时填 UINT32_MAX：
| lender_size(必传) | slot_id(必传) | socket_id(可选) | numa_id(可选) | port_id(可选) | 预期结果 |
|---|---|---|---|---|---|
| √ | √ | 根据slot_id决策 | |||
| √ | √ | √ | 根据socket_id决策 | ||
| √ | √ | √ | 根据numa_id决策 | ||
| √ | √ | √ | 不支持该格式 | ||
| √ | √ | √ | √ | 校验合法性, 根据numa_id决策 | |
| √ | √ | √ | √ | 根据numa_id决策 | |
| √ | √ | √ | √ | 根据socket_id决策 | |
| √ | √ | √ | √ | √ | 校验合法性, 根据numa_id决策 |
合法性校验：对应关系是否符合硬件环境，校验失败则借用失败。
样例 EXAMPLES
#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, ®ion, &lender);
if (ret != UBS_SUCCESS) {
perror("create shm with lender failed");
ubs_engine_client_finalize();
return -1;
}
ubs_engine_client_finalize();
return 0;
}
ubs_mem_shm_attach
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
导入共享形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name全局保持唯一性 |
| owner | IN | 内存资源属主信息，可选参数，NULL 不关注该字段 |
| mode | IN | 内存资源访问权限，可选参数，0 不关注该字段 |
| shm_desc | OUT | 内存描述信息，调用成功后需要使用 free 接口主动释放内存 |
- 数据结构说明
#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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_SHM_NO_CREATE | 共享内存未创建 |
| UBS_ENGINE_ERR_CREATING | 正在创建过程中 |
| UBS_ENGINE_ERR_DELETING | 正在删除过程中 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能导入资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_get
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_get(const char *name, ubs_mem_shm_desc_t **shm_desc);
描述 DESCRIPTION
查询指定共享形态远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，name最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name全局保持唯一性 |
| shm_desc | OUT | 借用形成的远端共享内存信息，调用成功后需要使用 free 接口主动释放内存 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能查看资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_list
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_list(ubs_mem_shm_desc_t **shm_descs, uint32_t *shm_desc_cnt);
描述 DESCRIPTION
查询共享形态远端内存列表。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| shm_descs | OUT | 共享内存描述信息数组，调用成功后需要使用 free 接口主动释放内存 |
| shm_desc_cnt | OUT | 共享内存描述信息数组中的元素个数，范围 [0, 2000] |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | 参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能查看资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_list_with_prefix
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#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);
描述 DESCRIPTION
查询指定借用标识前缀的共享形态远端内存，最多查询到2000条借用内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name_prefix | IN | 指定借用标识前缀，最大长度48字节，含结尾字符 \0仅可包括大小写字母、数字、 .、:、- 以及 _ |
| shm_descs | OUT | 共享内存描述信息数组，调用成功后需要使用 free 接口主动释放内存 |
| shm_desc_cnt | OUT | 共享内存描述信息数组中的元素个数，范围 [0, 2000] |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name_prefix参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_detach
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_detach(const char *name);
描述 DESCRIPTION
删除导入共享形态的远端内存。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name全局保持唯一性 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_SHM_NO_ATTACH | 共享内存未导入 |
| UBS_ENGINE_ERR_SHM_ATTACHING | 正在导入共享内存过程中 |
| UBS_ENGINE_ERR_SHM_DETACHING | 正在删除导入共享内存过程中 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
当前只支持CPU节点
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_delete
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_delete(const char *name);
描述 DESCRIPTION
删除指定共享形态远端内存。该接口只设置删除标记，等到所有 attach 都解除之后才删除。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name全局保持唯一性 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_CREATING | 正在创建过程中 |
| UBS_ENGINE_ERR_DELETING | 正在删除过程中 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
当前只支持CPU节点
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
对于异常场景如username、uid改变或者用户被删除，ubse提供cli命令删除内存能力,具体请参考《ubse_cli_user_guide.md》文档。
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_fault_get
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_fault_get(const char *name, ubs_mem_memids_fault_t *fault);
描述 DESCRIPTION
查询指定共享远端内存的状态。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _name全局保持唯一性 |
| fault | OUT | 内存块的健康状态 |
- 数据结构说明
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;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
ubse自动识别该接口调用方是否为资源管理者，只有管理者能查看资源
资源管理者确定时机：创建资源时UBSE自动确定和记录管理者（使用OS的username/uid标识）
管理者身份识别原则：能够获取username，则使用username；无法获取username，则使用uid
不同节点的用户名需要相同，否则节点间无法进行内存管理动作
附注 NOTES
暂无。
样例 EXAMPLES
#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;
}
ubs_mem_shm_fault_register
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_shm_fault_register(ubs_mem_shm_fault_handler handler);
描述 DESCRIPTION
客户端订阅共享内存故障事件。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| handler | IN | 共享内存故障事件响应处理函数，不允许为NULL |
注册函数返回值 RETURN VALUE
成功返回 0，失败返回非 0。
回调函数类型
typedef int32_t (*ubs_mem_shm_fault_handler)(const char *name, uint64_t memid, ubs_mem_fault_type_t type);
回调函数参数
| name | IN/OUT | description |
|---|---|---|
| name | IN | 发生故障的共享内存借用标识 |
| memid | IN | 发生故障的内存块标识信息 |
| type | IN | 内存块故障类型，详见 ubs_mem_fault_type_t 枚举 |
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;
回调函数返回值 RETURN VALUE
回调处理成功请返回0，失败返回非 0。
附注 NOTES
回调函数需要由调用方自行保证线程安全。
故障事件按用户级别上报。建议同一用户仅在一个进程注册；多进程注册时，各进程需自行甄别故障内存是否属于本进程借用。
服务端检测断链事件自动清理注册监听，不再提供注销接口。
样例 EXAMPLES
#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;
}
ubs_mem_fd_fault_register
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_fd_fault_register(ubs_mem_fd_fault_handler handler);
描述 DESCRIPTION
客户端订阅Fd内存故障事件。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| handler | IN | fd内存故障事件响应处理函数，不允许为NULL |
注册函数返回值 RETURN VALUE
成功返回 0，失败返回非 0。
回调函数类型
typedef int32_t (*ubs_mem_fd_fault_handler)(const char *name, uint64_t memid, ubs_mem_fault_type_t type);
回调函数参数
| name | IN/OUT | description |
|---|---|---|
| name | IN | 发生故障的fd内存借用标识 |
| memid | IN | 发生故障的内存块标识信息 |
| type | IN | 内存块故障类型，详见 ubs_mem_fault_type_t 枚举 |
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;
回调函数返回值 RETURN VALUE
回调处理成功请返回0，失败返回非 0。
附注 NOTES
回调函数需要由调用方自行保证线程安全。
故障事件按用户级别上报。建议同一用户仅在一个进程注册；多进程注册时，各进程需自行甄别故障内存是否属于本进程借用。
服务端检测断链事件自动清理注册监听，不再提供注销接口。
样例 EXAMPLES
#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;
}
ubs_mem_numa_fault_register
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_mem.h>
int32_t ubs_mem_numa_fault_register(ubs_mem_numa_fault_handler handler);
描述 DESCRIPTION
客户端订阅Numa内存故障事件。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| handler | IN | numa内存故障事件响应处理函数，不允许为NULL |
注册函数返回值 RETURN VALUE
成功返回 0，失败返回非 0。
回调函数类型
typedef int32_t (*ubs_mem_numa_fault_handler)(const char *name, uint64_t numaid, ubs_mem_fault_type_t type);
回调函数参数
| name | IN/OUT | description |
|---|---|---|
| name | IN | 发生故障的numa内存借用标识 |
| numaid | IN | 发生故障的远端numa对应的numaid |
| type | IN | 内存块故障类型，详见 ubs_mem_fault_type_t 枚举 |
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;
回调函数返回值 RETURN VALUE
回调处理成功请返回0，失败返回非 0。
附注 NOTES
回调函数需要由调用方自行保证线程安全。
故障事件按用户级别上报。建议同一用户仅在一个进程注册；多进程注册时，各进程需自行甄别故障内存是否属于本进程借用。
已上报故障的numaId对应内存及时删除，该numaId可能被后续借用再次使用。
服务端检测断链事件自动清理注册监听，不再提供注销接口。
样例 EXAMPLES
#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 numa_fault_handler(const char *name, uint64_t numaid, ubs_mem_fault_type_t type)
{
printf("receive numa fault event, name=%s, numaid=%lu, type=%d\n", name, numaid, 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_numa_fault_register(numa_fault_handler);
if (ret != 0) {
perror("register numa fault handler failed");
ubs_engine_client_finalize();
return -1;
}
signal(SIGINT, signal_handler);
signal(SIGTERM, signal_handler);
printf("numa fault handler registered, waiting for events... (press Ctrl+C to exit)\n");
while (g_running) {
pause();
}
ubs_engine_client_finalize();
return 0;
}
ubs_mem_fd_get_memid_by_import
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
int32_t ubs_mem_fd_get_memid_by_import(const char *name, uint64_t import_memid, ubs_mem_export_memid_t *mem_info);
描述 DESCRIPTION
在导入节点指定资源名和导入memId, 查询fd形态的远端内存memId
参数 PARAMTERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _ |
| import_memid | IN | 导入memId |
| ubs_mem_export_memid_t | OUT | 导出信息的数据结构，包含export_slot_id、 export_memid |
- 数据结构说明
typedef struct {
uint32_t export_slot_id; // 导出节点的id
uint64_t export_memid; // 导出内存块标识信息
} ubs_mem_export_memid_t;
返回值 RETURN VALUE
返回UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ERR_INVALID_ARG | 参数无效 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_CREATING | 资源正在创建中 |
| UBS_ENGINE_ERR_DELETING | 资源正在删除中 |
| UBS_ENGINE_ERR_EXPORT_LEDGERING | 导出节点对账中、调用方进行重试 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
附注 NOTES
无
样例 EXAMPLES
#include <stdint.h>
#include <stdio.h>
#include <ubs_engine_mem.h>
static void ubs_mem_fd_get_memid_by_import(void)
{
printf("=== ubs_mem_fd_get_memid_by_import_example ===\n");
char *name = "fd_name_test";
uint64_t import_memid = 9;
ubs_mem_export_memid_t mem_info;
int ret = ubs_mem_fd_get_memid_by_import(name, import_memid, &mem_info);
if (ret != 0) {
printf("ubs_mem_fd_get_memid_by_import failed, ret=%d\n", ret);
} else {
printf("ubs_mem_fd_get_memid_by_import success, export_slot_id=%u, export_memid=%lu\n",
mem_info.export_slot_id, mem_info.export_memid);
}
}
ubs_mem_numa_get_memid_by_import
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
int32_t ubs_mem_numa_get_memid_by_import(const char *name, uint64_t import_memid, ubs_mem_export_memid_t *mem_info);
描述 DESCRIPTION
在导入节点指定资源名和导入memId, 查询numa形态的远端内存memId
参数 PARAMTERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _ |
| import_memid | IN | 导入memId |
| ubs_mem_export_memid_t | OUT | 导出信息的数据结构，包含export_slot_id、 export_memid |
- 数据结构说明
typedef struct {
uint32_t export_slot_id; // 导出节点的id
uint64_t export_memid; // 导出内存块标识信息
} ubs_mem_export_memid_t;
返回值 RETURN VALUE
返回UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ERR_INVALID_ARG | 参数无效 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_CREATING | 资源正在创建中 |
| UBS_ENGINE_ERR_DELETING | 资源正在删除中 |
| UBS_ENGINE_ERR_EXPORT_LEDGERING | 导出节点对账中、调用方进行重试 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
附注 NOTES
无
样例 EXAMPLES
#include <stdint.h>
#include <stdio.h>
#include <ubs_engine_mem.h>
static void ubs_mem_numa_get_memid_by_import(void)
{
printf("=== ubs_mem_numa_get_memid_by_import_example ===\n");
char *name = "numa_name_test";
uint64_t import_memid = 9;
ubs_mem_export_memid_t mem_info;
int ret = ubs_mem_numa_get_memid_by_import(name, import_memid, &mem_info);
if (ret != 0) {
printf("ubs_mem_numa_get_memid_by_import failed, ret=%d\n", ret);
} else {
printf("ubs_mem_numa_get_memid_by_import success, export_slot_id=%u, export_memid=%lu\n",
mem_info.export_slot_id, mem_info.export_memid);
}
}
ubs_mem_shm_get_memid_by_import
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
int32_t ubs_mem_shm_get_memid_by_import(const char *name, uint64_t import_memid, ubs_mem_export_memid_t *mem_info);
描述 DESCRIPTION
在导入节点指定资源名和导入memId, 查询shm形态的远端内存memId
参数 PARAMTERS
| name | IN/OUT | description |
|---|---|---|
| name | IN | 借用标识，最大长度48字节，含结尾字符 \0name仅可包括大小写字母、数字、 .、:、- 以及 _ |
| import_memid | IN | 导入memId |
| ubs_mem_export_memid_t | OUT | 导出信息的数据结构，包含export_slot_id、 export_memid |
- 数据结构说明
typedef struct {
uint32_t export_slot_id; // 导出节点的id
uint64_t export_memid; // 导出内存块标识信息
} ubs_mem_export_memid_t;
返回值 RETURN VALUE
返回UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持对应内存特性 |
| UBS_ERR_INVALID_ARG | 参数无效 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_NOT_EXIST | 借用关系不存在 |
| UBS_ENGINE_ERR_CREATING | 资源正在创建中 |
| UBS_ENGINE_ERR_DELETING | 资源正在删除中 |
| UBS_ENGINE_ERR_EXPORT_LEDGERING | 导出节点对账中、调用方进行重试 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
附注 NOTES
无
样例 EXAMPLES
#include <stdint.h>
#include <stdio.h>
#include <ubs_engine_mem.h>
static void ubs_mem_shm_get_memid_by_import(void)
{
printf("=== ubs_mem_shm_get_memid_by_import_example ===\n");
char *name = "shm_name_test";
uint64_t import_memid = 9;
ubs_mem_export_memid_t mem_info;
int ret = ubs_mem_shm_get_memid_by_import(name, import_memid, &mem_info);
if (ret != 0) {
printf("ubs_mem_shm_get_memid_by_import failed, ret=%d\n", ret);
} else {
printf("ubs_mem_shm_get_memid_by_import success, export_slot_id=%u, export_memid=%lu\n",
mem_info.export_slot_id, mem_info.export_memid);
}
}
libubse urma
ubs_urma_dev_get
库 LIBRARY
ubse 库 (libubse.so)
摘要 SYNOPSIS
#include <ubs_engine_urma.h>
uint32_t ubs_urma_dev_get(ubs_urma_dev_t **urma_devices, uint32_t *urma_cnt);
描述 DESCRIPTION
查询系统中所有可用的 URMA 设备信息，返回设备列表，包括设备名称、健康状态和硬件资源 ID 等信息。
参数 PARAMETERS
| name | IN/OUT | 描述 |
|---|---|---|
| urma_devices | OUT | URMA 设备信息数组指针，调用成功后需用 free() 释放 |
| urma_cnt | OUT | 返回的 URMA 设备数量 |
- 数据结构说明
#define UBS_URMA_NAME_MAX 32 // URMA设备名称最大长度（含结束符）
typedef struct {
char name[UBS_URMA_NAME_MAX]; // 设备名称
uint32_t healthy; // 端口可用状态：0-可用，1-不可用
uint64_t hw_res_id; // 硬件资源 ID
} ubs_urma_dev_t;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持URMA特性 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
暂无
附注 NOTES
暂无
样例 EXAMPLES
以下程序初始化UBSE客户端，查询URMA设备信息。
#include <stdio.h>
#include <stdlib.h>
#include <libubse.h>
#include <ubs_engine_urma.h>
int main(void)
{
int32_t ret;
uint32_t urma_cnt = 0;
ubs_urma_dev_t *urma_devices = NULL;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed.\n");
return -1;
}
ret = ubs_urma_dev_get(&urma_devices, &urma_cnt);
if (UBS_SUCCESS != ret) {
perror("get urma devices failed.\n");
ubs_engine_client_finalize();
return -1;
}
for (uint32_t i = 0; i < urma_cnt; i++) {
printf("URMA device: %s, healthy: %u\n", urma_devices[i].name, urma_devices[i].healthy);
}
free(urma_devices);
ubs_engine_client_finalize();
return 0;
}
ubs_urma_dev_alloc
库 LIBRARY
ubse 库 (libubse.so)
摘要 SYNOPSIS
#include <ubs_engine_urma.h>
uint32_t ubs_urma_dev_alloc(const char *name, ubs_urma_dev_info_t *dev_info);
描述 DESCRIPTION
分配指定的 URMA 设备资源，返回设备的路径信息，包括 bonding 路径、EID 和 FE 路径等。
参数 PARAMETERS
| name | IN/OUT | 描述 |
|---|---|---|
| name | IN | URMA 设备名称，长度不超过 32 字节 |
| dev_info | IN/OUT | 分配的 URMA 设备路径信息，调用方需预先申请内存 |
- 数据结构说明
#define UBS_URMA_NAME_MAX 32 // URMA设备名称最大长度（含结束符）
#define UBS_MAX_URMA_PATH_LENGTH 64 // URMA路径最大长度（含结束符）
#define UBS_FE_PATH_NUM 2 // FE路径数量
typedef struct {
char bonding_path[UBS_MAX_URMA_PATH_LENGTH]; // Bonding 路径
char bonding_eid[UBS_MAX_URMA_PATH_LENGTH]; // Bonding EID
char fe_path[UBS_FE_PATH_NUM][UBS_MAX_URMA_PATH_LENGTH]; // FE 路径数组
} ubs_urma_dev_info_t;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持URMA特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_NOT_EXIST | URMA设备不存在 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
dev_info参数需由调用方预先申请内存- 设备名称长度不能超过 32 字节
附注 NOTES
暂无
样例 EXAMPLES
以下程序初始化UBSE客户端，分配指定的URMA设备。
#include <stdio.h>
#include <string.h>
#include <libubse.h>
#include <ubs_engine_urma.h>
int main(void)
{
int32_t ret;
ubs_urma_dev_info_t dev_info;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed.\n");
return -1;
}
memset(&dev_info, 0, sizeof(dev_info));
ret = ubs_urma_dev_alloc("urma0", &dev_info);
if (UBS_SUCCESS != ret) {
perror("alloc urma device failed.\n");
ubs_engine_client_finalize();
return -1;
}
printf("bonding_path: %s\n", dev_info.bonding_path);
printf("bonding_eid: %s\n", dev_info.bonding_eid);
ubs_engine_client_finalize();
return 0;
}
ubs_urma_dev_free
库 LIBRARY
ubse 库 (libubse.so)
摘要 SYNOPSIS
#include <ubs_engine_urma.h>
uint32_t ubs_urma_dev_free(const char *name);
描述 DESCRIPTION
释放指定的 URMA 设备资源，使其可以被其他进程重新分配使用。
参数 PARAMETERS
| name | IN/OUT | 描述 |
|---|---|---|
| name | IN | URMA 设备名称，长度不超过 32 字节 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ERR_NOT_SUPPORTED | 当前服务不支持URMA特性 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | name参数超出范围 |
| UBS_ENGINE_ERR_NOT_EXIST | URMA设备不存在 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
- 只能释放已分配的设备
- 设备名称长度不能超过 32 字节
附注 NOTES
暂无
样例 EXAMPLES
以下程序初始化UBSE客户端，分配并释放URMA设备。
#include <stdio.h>
#include <string.h>
#include <libubse.h>
#include <ubs_engine_urma.h>
int main(void)
{
int32_t ret;
ubs_urma_dev_info_t dev_info;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed.\n");
return -1;
}
memset(&dev_info, 0, sizeof(dev_info));
ret = ubs_urma_dev_alloc("urma0", &dev_info);
if (UBS_SUCCESS != ret) {
perror("alloc urma device failed.\n");
ubs_engine_client_finalize();
return -1;
}
printf("bonding_path: %s\n", dev_info.bonding_path);
printf("bonding_eid: %s\n", dev_info.bonding_eid);
ret = ubs_urma_dev_free("urma0");
if (UBS_SUCCESS != ret) {
perror("free urma device failed.\n");
}
ubs_engine_client_finalize();
return 0;
}
ubs_urma_qos_create
库 LIBRARY
ubse 库 (libubse.so)
摘要 SYNOPSIS
#include <ubs_engine_urma.h>
uint32_t ubs_urma_qos_create(const ubs_urma_qos_config_t* configs, uint32_t count);
描述 DESCRIPTION
设置URMA设备的ETS QoS配置，为指定优先级分配带宽资源。
参数 PARAMETERS
| name | IN/OUT | 描述 |
|---|---|---|
| configs | IN | QoS配置数组指针，包含优先级和带宽信息 |
| count | IN | 数组元素个数，有效范围 1-2 |
- 数据结构说明
#define UBS_URMA_QOS_CONFIG_MIN_COUNT 1 // QoS配置最小数量
#define UBS_URMA_QOS_CONFIG_MAX_COUNT 2 // QoS配置最大数量
#define UBS_URMA_QOS_PRIORITY_MAX 1 // QoS优先级最大值
typedef struct {
uint32_t priority; // 优先级，值为0或1
uint32_t bandwidth; // 带宽，单位Gbps
} ubs_urma_qos_config_t;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ENGINE_ERR_INVALID_PARAM | 参数错误：count不在1-2范围、优先级超过1、带宽为0、存在重复优先级 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_CONNECT_UBM_FAILED | 访问UBM接口失败 |
| UBS_ENGINE_ERR_URMA_QOS_EXIST | ETS优先级组已存在，请先删除现有配置 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
- 配置数量必须在1-2之间
- 优先级值必须为0或1
- 不允许配置重复的优先级
- 带宽值必须为正整数（大于0），单位Gbps
附注 NOTES
暂无
样例 EXAMPLES
以下程序初始化UBSE客户端，创建单个优先级的QoS配置。
#include <stdio.h>
#include <libubse.h>
#include <ubs_engine_urma.h>
int main(void)
{
int32_t ret;
ubs_urma_qos_config_t config = {
.priority = 0,
.bandwidth = 10
};
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed.\n");
return -1;
}
ret = ubs_urma_qos_create(&config, 1);
if (UBS_SUCCESS != ret) {
perror("create qos failed.\n");
ubs_engine_client_finalize();
return -1;
}
printf("QoS config created successfully.\n");
ubs_engine_client_finalize();
return 0;
}
创建多个优先级的QoS配置：
#include <stdio.h>
#include <libubse.h>
#include <ubs_engine_urma.h>
int main(void)
{
int32_t ret;
ubs_urma_qos_config_t configs[2] = {
{.priority = 0, .bandwidth = 10},
{.priority = 1, .bandwidth = 20}
};
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed.\n");
return -1;
}
ret = ubs_urma_qos_create(configs, 2);
if (UBS_SUCCESS != ret) {
perror("create qos failed.\n");
ubs_engine_client_finalize();
return -1;
}
printf("QoS configs created successfully.\n");
ubs_engine_client_finalize();
return 0;
}
ubs_urma_qos_delete
库 LIBRARY
ubse 库 (libubse.so)
摘要 SYNOPSIS
#include <ubs_engine_urma.h>
uint32_t ubs_urma_qos_delete(void);
描述 DESCRIPTION
清理所有ETS QoS配置，释放已分配的带宽资源。
参数 PARAMETERS
无
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_CONNECT_UBM_FAILED | 访问UBM接口失败 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
暂无
附注 NOTES
暂无
样例 EXAMPLES
以下程序初始化UBSE客户端，删除所有QoS配置。
#include <stdio.h>
#include <libubse.h>
#include <ubs_engine_urma.h>
int main(void)
{
int32_t ret;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed.\n");
return -1;
}
ret = ubs_urma_qos_delete();
if (UBS_SUCCESS != ret) {
perror("delete qos failed.\n");
ubs_engine_client_finalize();
return -1;
}
printf("QoS configs deleted successfully.\n");
ubs_engine_client_finalize();
return 0;
}
ubs_urma_qos_get
库 LIBRARY
ubse 库 (libubse.so)
摘要 SYNOPSIS
#include <ubs_engine_urma.h>
uint32_t ubs_urma_qos_get(ubs_urma_qos_config_t** configs, uint32_t* count);
描述 DESCRIPTION
查询已创建的ETS QoS配置信息。
参数 PARAMETERS
| name | IN/OUT | 描述 |
|---|---|---|
| configs | OUT | QoS配置数组指针，调用成功后需用 free() 释放 |
| count | OUT | 返回的QoS配置数量 |
- 数据结构说明
typedef struct {
uint32_t priority; // 优先级，值为0或1
uint32_t bandwidth; // 带宽，单位Gbps
} ubs_urma_qos_config_t;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见错误 ERRORS
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_CONNECT_UBM_FAILED | 访问UBM接口失败 |
| UBS_ENGINE_ERR_URMA_QOS_NOT_EXISTED | ETS QoS模板未创建 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
暂无
附注 NOTES
调用方需释放configs内存
样例 EXAMPLES
以下程序初始化UBSE客户端，查询QoS配置信息。
#include <stdio.h>
#include <stdlib.h>
#include <libubse.h>
#include <ubs_engine_urma.h>
int main(void)
{
int32_t ret;
uint32_t count = 0;
ubs_urma_qos_config_t* configs = NULL;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed.\n");
return -1;
}
ret = ubs_urma_qos_get(&configs, &count);
if (UBS_SUCCESS != ret) {
perror("get qos failed.\n");
ubs_engine_client_finalize();
return -1;
}
for (uint32_t i = 0; i < count; i++) {
printf("QoS config %u: priority=%u, bandwidth=%u Gbps\n",
i, configs[i].priority, configs[i].bandwidth);
}
free(configs);
ubs_engine_client_finalize();
return 0;
}
libubse npu
ubs_npu_device_list_query
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_npu.h>
int32_t ubs_npu_device_list_query(ubs_ub_devices_list_t* device_list);
描述 DESCRIPTION
查询系统中所有UB设备列表，包括NPU、BUS INSTANCE、NIC PFE、NIC VFE和UB CTRL等设备类型的拓扑属性信息。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| device_list | OUT | UB设备列表，调用方需预先申请内存，查询完成后需使用 ubs_npu_device_list_free 释放内部动态分配的子结构 |
- 数据结构说明
#define MACRO_UBSE_UB_DEVICE_GUID_SIZE 32
#define MACRO_UBSE_UB_UPI_STR_SIZE 4
typedef enum {
UBS_BUSI = 1,
UBS_NPU = 2,
UBS_NIC_PFE = 3,
UBS_NIC_VFE = 4,
UBS_UBCTRL = 5
} ubs_device_type;
typedef struct {
ubs_device_type device_type;
uint8_t slot_id;
uint8_t chip_id;
uint8_t die_id;
uint16_t pf_id;
uint16_t vf_id;
} ubs_ub_devices_type_t;
typedef struct {
uint8_t slot_id;
uint8_t chip_id;
uint8_t guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t bus_instance_guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t affinity_devices_count;
ubs_ub_devices_type_t affinity_devices[];
} npu_attr_t;
typedef struct {
uint8_t guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t sub_devices_count;
ubs_ub_devices_type_t sub_devices[];
} busi_attr_t;
typedef struct {
uint8_t slot_id;
uint8_t chip_id;
uint16_t pf_id;
uint8_t guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t bus_instance_guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t affinity_devices_count;
ubs_ub_devices_type_t affinity_devices[];
} nic_pfe_attr_t;
typedef struct {
uint8_t slot_id;
uint8_t chip_id;
uint16_t pf_id;
uint16_t vf_id;
uint8_t guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t bus_instance_guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t affinity_devices_count;
ubs_ub_devices_type_t affinity_devices[];
} nic_vfe_attr_t;
typedef struct {
uint8_t slot_id;
uint8_t chip_id;
uint8_t die_id;
uint8_t guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
} ubctrl_attr_t;
typedef struct {
ubs_device_type type;
npu_attr_t* attr;
} ubs_npu_t;
typedef struct {
ubs_device_type type;
busi_attr_t* attr;
} ubs_busi_t;
typedef struct {
ubs_device_type type;
nic_pfe_attr_t* attr;
} ubs_nic_pfe_t;
typedef struct {
ubs_device_type type;
nic_vfe_attr_t* attr;
} ubs_nic_vfe_t;
typedef struct {
ubs_device_type type;
ubctrl_attr_t* attr;
} ubs_ubctrl_t;
typedef struct {
ubs_ubctrl_t* ubctrl_ptr;
uint8_t ubctrl_cnt;
ubs_nic_pfe_t* nic_pfe_ptr;
uint8_t nic_pfe_cnt;
ubs_nic_vfe_t* nic_vfe_ptr;
uint8_t nic_vfe_cnt;
ubs_npu_t* npu_ptr;
uint8_t npu_cnt;
ubs_busi_t* busi_ptr;
uint8_t busi_cnt;
} ubs_ub_devices_list_t;
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
约束 CONSTRAINTS
调用方需预先申请 ubs_ub_devices_list_t 结构体内存，传入有效指针。
查询完成后需调用 ubs_npu_device_list_free 释放内部动态分配的子结构（如 attr 指针、affinity_devices 柔性数组等），但不能 free 调用方自身申请的 device_list 结构体本身。
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化UBSE客户端，查询UB设备列表。
#include <stdio.h>
#include <stdlib.h>
#include <ubs_engine.h>
#include <ubs_engine_npu.h>
int main(void)
{
int32_t ret;
ubs_ub_devices_list_t device_list = {0};
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed");
return -1;
}
ret = ubs_npu_device_list_query(&device_list);
if (UBS_SUCCESS != ret) {
perror("query device list failed");
ubs_engine_client_finalize();
return -1;
}
printf("npu_cnt=%u, busi_cnt=%u\n", device_list.npu_cnt, device_list.busi_cnt);
ubs_npu_device_list_free(&device_list);
ubs_engine_client_finalize();
return 0;
}
ubs_npu_device_alloc
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_npu.h>
int32_t ubs_npu_device_alloc(ubs_ub_alloc_devices_info_t* alloc_info, uint8_t* new_bus_instance_guid,
ubs_ub_devices_list_t* device_list);
描述 DESCRIPTION
根据指定的UPI和设备需求列表，分配UB设备资源，返回新创建的bus实例GUID以及更新后的设备列表。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| alloc_info | IN | 分配请求信息，包含UPI字符串、bus实例GUID和目标设备列表 |
| new_bus_instance_guid | OUT | 新创建的bus实例GUID，长度为 MACRO_UBSE_UB_DEVICE_GUID_SIZE，调用方需预先申请内存 |
| device_list | OUT | 分配后的UB设备列表，调用方需预先申请内存，完成后需使用 ubs_npu_device_list_free 释放内部子结构 |
- 数据结构说明
#define MACRO_UBSE_UB_UPI_STR_SIZE 4
#define MACRO_UBSE_UB_DEVICE_GUID_SIZE 32
typedef struct {
uint8_t upi_str[MACRO_UBSE_UB_UPI_STR_SIZE];
uint8_t bus_instance_guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE];
uint8_t ub_dev_list_count;
ubs_ub_devices_type_t* ub_dev_list;
} ubs_ub_alloc_devices_info_t;
字段说明：
| 字段 | 描述 |
|---|---|
| upi_str | UPI标识，取值范围 [1, 0x7fff-1001] |
| bus_instance_guid | 已有的bus实例GUID；传入空GUID（全0）表示创建新bus实例 |
| ub_dev_list_count | 目标设备列表中的设备数量 |
| ub_dev_list | 目标设备列表指针，指定需要分配的设备类型和位置信息 |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
| UBS_ENGINE_ERR_OUT_OF_RANGE | UPI取值超出有效范围 |
| UBS_ENGINE_ERR_NOT_EXIST | bus实例GUID不存在 |
| UBS_ENGINE_ERR_EXISTED | bus实例已存在 |
约束 CONSTRAINTS
UPI取值范围 [1, 0x7fff-1001]，超出范围返回 UBS_ENGINE_ERR_OUT_OF_RANGE。
bus_instance_guid 传入全0时创建新bus实例，传入非全0时在已有bus实例上追加设备。
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化UBSE客户端，分配UB设备资源。
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ubs_engine.h>
#include <ubs_engine_npu.h>
int main(void)
{
int32_t ret;
ubs_ub_devices_type_t dev = {
.device_type = UBS_NPU,
.slot_id = 1,
.chip_id = 0,
.die_id = 0,
.pf_id = 0,
.vf_id = 0
};
ubs_ub_alloc_devices_info_t alloc_info = {0};
uint8_t new_guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE] = {0};
ubs_ub_devices_list_t device_list = {0};
alloc_info.upi_str[0] = 1;
alloc_info.ub_dev_list_count = 1;
alloc_info.ub_dev_list = &dev;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed");
return -1;
}
ret = ubs_npu_device_alloc(&alloc_info, new_guid, &device_list);
if (UBS_SUCCESS != ret) {
perror("alloc device failed");
ubs_engine_client_finalize();
return -1;
}
ubs_npu_device_list_free(&device_list);
ubs_engine_client_finalize();
return 0;
}
ubs_npu_device_free
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_npu.h>
int32_t ubs_npu_device_free(ubs_ub_alloc_devices_info_t* alloc_info);
描述 DESCRIPTION
释放已分配的UB设备资源，根据指定的UPI和bus实例GUID回收对应的设备。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| alloc_info | IN | 释放请求信息，包含UPI字符串、bus实例GUID和需要释放的设备列表 |
- 数据结构说明
同 ubs_npu_device_alloc 中的 ubs_ub_alloc_devices_info_t 结构体。
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
| UBS_ENGINE_ERR_NOT_EXIST | bus实例不存在 |
约束 CONSTRAINTS
只能释放已分配的设备资源。
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化UBSE客户端，释放已分配的UB设备。
#include <stdio.h>
#include <string.h>
#include <ubs_engine.h>
#include <ubs_engine_npu.h>
int main(void)
{
int32_t ret;
ubs_ub_devices_type_t dev = {
.device_type = UBS_NPU,
.slot_id = 1,
.chip_id = 0
};
ubs_ub_alloc_devices_info_t alloc_info = {0};
alloc_info.upi_str[0] = 1;
alloc_info.ub_dev_list_count = 1;
alloc_info.ub_dev_list = &dev;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed");
return -1;
}
ret = ubs_npu_device_free(&alloc_info);
if (UBS_SUCCESS != ret) {
perror("free device failed");
ubs_engine_client_finalize();
return -1;
}
ubs_engine_client_finalize();
return 0;
}
ubs_npu_device_list_free
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_npu.h>
void ubs_npu_device_list_free(ubs_ub_devices_list_t* device_list);
描述 DESCRIPTION
释放 ubs_npu_device_list_query 或 ubs_npu_device_alloc 返回的设备列表中动态分配的内部子结构（如各设备类型的 attr 指针、柔性数组 affinity_devices 等），但不释放调用方自身申请的 device_list 结构体。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| device_list | IN | 需要释放内部子结构的设备列表，由调用方申请内存 |
返回值 RETURN VALUE
无。
错误 ERRORS
无。
约束 CONSTRAINTS
该函数仅释放设备列表内部动态分配的子结构，不释放 device_list 本身。调用方需自行管理 device_list 结构体的生命周期。
重复调用可能导致未定义行为，应确保每个 device_list 只调用一次。
附注 NOTES
调用顺序：先 ubs_npu_device_list_free 释放内部子结构，再由调用方释放自身申请的 device_list 内存（如栈上分配则无需 free）。
样例 EXAMPLES
以下程序演示查询设备列表后释放内部子结构。
#include <stdio.h>
#include <ubs_engine.h>
#include <ubs_engine_npu.h>
int main(void)
{
int32_t ret;
ubs_ub_devices_list_t device_list = {0};
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed");
return -1;
}
ret = ubs_npu_device_list_query(&device_list);
if (UBS_SUCCESS != ret) {
perror("query device list failed");
ubs_engine_client_finalize();
return -1;
}
ubs_npu_device_list_free(&device_list);
ubs_engine_client_finalize();
return 0;
}
ubs_uba_tid_size_query
库 LIBRARY
ubse库 (/usr/lib64/libubse-client.so)
摘要 SYNOPSIS
#include <ubs_engine_npu.h>
int32_t ubs_uba_tid_size_query(uint8_t* bus_instance_guid, uint32_t* tid, uint64_t* uba, uint64_t* size);
描述 DESCRIPTION
根据bus实例GUID查询对应的UBA地址、TID标识和可用size信息。
参数 PARAMETERS
| name | IN/OUT | description |
|---|---|---|
| bus_instance_guid | IN | bus实例GUID，长度为 MACRO_UBSE_UB_DEVICE_GUID_SIZE |
| tid | OUT | TID标识 |
| uba | OUT | UBA地址 |
| size | OUT | 可用size大小，单位Byte |
返回值 RETURN VALUE
返回 UBS_SUCCESS 表示成功，返回其他值表示失败，请见 错误 ERRORS。
错误 ERRORS
| Error | Description |
|---|---|
| UBS_ERR_NULL_POINTER | 空指针 |
| UBS_ENGINE_ERR_CONNECTION_FAILED | 连接UBSE服务端失败 |
| UBS_ENGINE_ERR_AUTH_FAILED | UBSE服务端鉴权不通过 |
| UBS_ENGINE_ERR_TIMEOUT | UBSE服务端处理超时 |
| UBS_ENGINE_ERR_INTERNAL | UBSE服务端内部错误 |
| UBS_ENGINE_ERR_NOT_EXIST | bus实例不存在 |
约束 CONSTRAINTS
传入的 bus_instance_guid 必须是有效的已分配bus实例GUID。
附注 NOTES
暂无。
样例 EXAMPLES
以下程序初始化UBSE客户端，查询指定bus实例的UBA TID size信息。
#include <stdio.h>
#include <string.h>
#include <ubs_engine.h>
#include <ubs_engine_npu.h>
int main(void)
{
int32_t ret;
uint8_t guid[MACRO_UBSE_UB_DEVICE_GUID_SIZE] = {0};
uint32_t tid = 0;
uint64_t uba = 0;
uint64_t size = 0;
ret = ubs_engine_client_initialize("/var/run/ubse/ubse.sock");
if (UBS_SUCCESS != ret) {
perror("init failed");
return -1;
}
ret = ubs_uba_tid_size_query(guid, &tid, &uba, &size);
if (UBS_SUCCESS != ret) {
perror("query uba tid size failed");
ubs_engine_client_finalize();
return -1;
}
printf("tid=%u, uba=%lu, size=%lu\n", tid, uba, size);
ubs_engine_client_finalize();
return 0;
}
UBSE 内存控制器接口说明文档
概述
UBSE 内存控制器提供了一组用于管理内存借用关系的接口。这些接口支持不同类型的内存借用，包括基于 NUMA 的内存借用和基于地址的内存借用。文档中详细描述了每个接口的功能、参数和返回值。
枚举类型
UbseMemStage
表示借用关系的阶段。
| 枚举值 | 描述 |
|---|---|
UBSE_NOT_EXIST |
借用关系不存在 |
UBSE_CREATING |
正在创建中 |
UBSE_DELETING |
正在删除中 |
UBSE_EXIST |
创建成功 |
UBSE_ERR_ONLY_IMPORT |
只存在借入 |
UBSE_ERR_WAIT_UNEXPORT |
等待 unexport 执行 |
UBSE_ERR_ABNORMAL |
删除导入失败，账本与实际状态不一致 |
UbseMemBorrowType
表示借用类型。
| 枚举值 | 描述 |
|---|---|
FD_BORROW |
文件描述符借用 |
NUMA_BORROW |
NUMA 借用 |
ADDR_BORROW |
地址借用 |
SHM_BORROW |
共享内存借用 |
SHM_ATTACH |
共享内存附加 |
UbseMemDistance
表示CPU连线类型。
| 枚举值 | 描述 |
|---|---|
MEM_DISTANCE_L0 |
L0 对应直接 CPU 连线节点 |
MEM_DISTANCE_L1 |
L1 对应通过 1 跳节点（暂不支持） |
MEM_DISTANCE_L2 |
L2 对应超过 1 跳节点（暂不支持） |
结构体
UbseMemResult
表示借用结果。
| 字段 | 类型 | 描述 |
|---|---|---|
name |
std::string |
借用标识 |
importNodeId |
std::string |
借入节点 ID |
realSize |
uint64_t |
实际大小 |
stage |
UbseMemStage |
借用阶段 |
UbseNumaMemoryDebtInfo
表示 NUMA 内存借用账本信息。
| 字段 | 类型 | 描述 |
|---|---|---|
name |
std::string |
资源名称标识 |
borrowNodeId |
std::string |
借入节点 ID |
borrowSocketIdList |
std::vector<int> |
借入 socket ID 列表 |
usrInfo |
uint8_t[UBSE_MAX_USR_INFO_LEN] |
调用方私有数据 |
borrowMemId |
std::vector<uint64_t> |
借入内存 ID 列表 |
lentNodeId |
std::string |
借出节点 ID |
lentSocketIdList |
std::vector<int> |
借出 socket ID 列表 |
lentNumaIdList |
std::vector<int16_t> |
借出 NUMA ID 列表 |
lentNumaSizeList |
std::vector<uint64_t> |
借出 NUMA 大小列表 |
lentMemId |
std::vector<uint64_t> |
借出内存 ID 列表 |
size |
uint64_t |
总借用内存大小 |
remoteNumaId |
int64_t |
远端 NUMA ID |
uid |
uid_t |
发起借用方运行用户的 UID |
username |
std::string |
发起借用方运行用户的名称 |
UbseNumaMemoryImportDebtInfo
表示 NUMA 内存导入账本信息。
| 字段 | 类型 | 默认值 | 描述 |
|---|---|---|---|
name |
std::string |
- | 资源名称标识 |
borrowNodeId |
std::string |
- | 借入节点 ID |
borrowSocketIdList |
std::vector<int> |
- | 借入 socket ID 列表 |
size |
uint64_t |
- | 总借用内存大小（字节） |
usrInfo |
uint8_t[UBSE_MAX_USR_INFO_LEN] |
- | 调用方私有数据 |
remoteNumaId |
int64_t |
-1 |
远端 NUMA ID |
UbseMemBorrower
表示借用方信息。
| 字段 | 类型 | 描述 |
|---|---|---|
nodeId |
std::string |
节点 ID |
affinitySocketId |
int |
可选，亲和 socket ID，-1 表示无效 |
uid |
uid_t |
发起借用方运行用户的 UID |
username |
std::string |
发起借用方运行用户的名称 |
UbseMemNumaLender
表示 NUMA 借出方信息。
| 字段 | 类型 | 描述 |
|---|---|---|
slotId |
uint32_t |
节点唯一标识 |
socketId |
uint32_t |
socket ID |
numaId |
uint64_t |
NUMA ID |
size |
uint64_t |
借出内存大小 单位Byte, 取值范围大于等于4*1024*1024 |
UbseTopoIpAddress
表示拓扑 IP 地址。
| 字段 | 类型 | 描述 |
|---|---|---|
af |
int32_t |
地址族 |
ipv4 |
struct in_addr |
IPv4 地址 |
ipv6 |
struct in6_addr |
IPv6 地址 |
UbseTopoNode
表示拓扑节点。
| 字段 | 类型 | 描述 |
|---|---|---|
slotId |
uint32_t |
节点唯一标识 |
socketIdList |
std::vector<int16_t> |
socket ID 列表 |
numaIdList |
std::vector<int32_t> |
NUMA ID 列表 |
ips |
std::vector<UbseTopoIpAddress> |
IP 地址列表 |
hostName |
std::string |
主机名 |
UbseMemNumaDesc
表示 NUMA 借用形成的远端 NUMA 信息。
| 字段 | 类型 | 描述 |
|---|---|---|
name |
std::string |
借用标识 |
numaId |
int64_t |
远端 NUMA ID |
exportNode |
UbseTopoNode |
借出节点 |
importNode |
UbseTopoNode |
借入节点 |
size |
uint64_t |
借用大小 |
usrInfo |
uint8_t[UBSE_MAX_USR_INFO_LEN] |
调用方私有数据 |
UbseNodeNumaInfo
表示节点 NUMA 信息。
| 字段 | 类型 | 描述 |
|---|---|---|
nodeId |
std::string |
节点 ID |
hostName |
std::string |
主机名 |
numaId |
uint32_t |
NUMA ID |
socketId |
uint32_t |
socket ID |
mReservedMemRatio |
uint64_t |
预留内存比例 |
memTotal |
uint64_t |
总内存量 |
memFree |
uint64_t |
空闲内存量 |
nrHugepages |
uint64_t |
2M 大页数量 |
freeHugepages |
uint64_t |
2M 大页空闲数量 |
usedHugepages |
uint64_t |
2M 大页已用数量 |
timestamp |
uint64_t |
数据采集的时间戳 |
memLent |
uint64_t |
借出内存量 |
memShared |
uint64_t |
共享内存量 |
UbseMemNumaCreateOpt
表示 NUMA 借用的可选项。
| 字段 | 类型 | 描述 |
|---|---|---|
size |
uint64_t |
借出内存大小 单位Byte, 取值范围大于等于4*1024*1024 |
distance |
UbseMemDistance |
内存距离 |
highWatermark |
size_t |
内存使用量百分比 |
usrInfo |
uint8_t[UBSE_MAX_USR_INFO_LEN] |
调用方私有数据 |
UbseMemNumaCandidateOpt
表示指定候选借出节点的 NUMA 借用可选项。继承自 UbseMemNumaCreateOpt。
自有字段：
| 字段 | 类型 | 描述 |
|---|---|---|
slotIds |
std::vector<std::string> |
候选借出节点范围 |
UbseMemAddrBorrowLocAndSizeByPid
表示基于 PID 的地址借用位置和大小。
| 字段 | 类型 | 默认值 | 描述 |
|---|---|---|---|
addr |
uint64_t |
0 |
借用的进程虚拟地址 |
size |
uint64_t |
0 |
该段地址借入大小，单位Byte |
UbseMemProcessLender
表示基于进程的地址借出方信息。
| 字段 | 类型 | 描述 |
|---|---|---|
slotId |
uint32_t |
节点唯一标识 |
socketId |
int |
内存申请借出方节点 socket 信息，-1 表示无效 |
pid |
uint64_t |
借出进程 PID |
vaLists |
std::vector<UbseMemAddrBorrowLocAndSizeByPid> |
借用地址段 |
UbseMemAddrDesc
表示基于地址借用形成的远端 NUMA 信息。
| 字段 | 类型 | 描述 |
|---|---|---|
name |
std::string |
借用标识 |
numaId |
int64_t |
远端 NUMA ID |
lender |
UbseMemProcessLender |
借出节点 |
importNode |
UbseTopoNode |
借入节点 |
size |
uint64_t |
借用大小 |
函数
UbseQueryResult
查询借用标识对应的操作结果。
uint32_t UbseQueryResult(const std::string &name, UbseMemResult &result, UbseMemBorrowType borrowType = UbseMemBorrowType::NUMA_BORROW);
参数:
name: 借用标识result: 借用结果borrowType: 借用类型，默认为NUMA_BORROW
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseGetNumaMemDebtInfoWithNode
返回和传入节点相关的账本信息。
UbseResult UbseGetNumaMemDebtInfoWithNode(const std::string &nodeId, std::vector<UbseNumaMemoryDebtInfo> &debtInfos);
参数:
nodeId: 节点 IDdebtInfos: 借用账本对象集合
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseGetNumaMemDebtInfo
返回当前集群拓扑中的所有对账完成节点的账本信息。
UbseResult UbseGetNumaMemDebtInfo(std::vector<UbseNumaMemoryDebtInfo> &debtInfos);
参数:
debtInfos: 借用账本对象集合
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseGetNumaMemImportDebtInfoWithLocalNode
返回当前节点导入账本信息。本地节点账本已经从 OBMM 恢复完成则返回成功，否则返回部分成功。
UbseResult UbseGetNumaMemImportDebtInfoWithLocalNode(std::vector<UbseNumaMemoryImportDebtInfo> &debtInfos);
参数:
debtInfos: 借用账本对象集合
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseGetAllNodeNumaInfo
返回所有采集到的节点相关的 NUMA 信息。
UbseResult UbseGetAllNodeNumaInfo(std::vector<UbseNodeNumaInfo> &numaNodeInfoList);
参数:
numaNodeInfoList: 节点 NUMA 对象集合
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseGetNodeNumaInfoByNodeId
返回所有采集到的节点指定节点相关的 NUMA 信息。
UbseResult UbseGetNodeNumaInfoByNodeId(const std::string &nodeId, std::vector<UbseNodeNumaInfo> &numaNodeInfoList);
参数:
nodeId: 节点 IDnumaNodeInfoList: 节点 NUMA 对象集合
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseMemNumaCreateWithLender
指定借出信息，提供给插件使用 NUMA 借用。
UbseResult UbseMemNumaCreateWithLender(const std::string &name, const UbseMemBorrower &borrower, const std::vector<UbseMemNumaLender> &lenders, uint8_t usrInfo[UBSE_MAX_USR_INFO_LEN], UbseMemNumaDesc &desc);
参数:
name: 借用标识borrower: 借用方信息lenders: 借出方信息usrInfo: 调用方私有数据desc: 借用形成的远端 NUMA 信息
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseMemNumaCreate
提供给插件使用 NUMA 借用。
UbseResult UbseMemNumaCreate(const std::string &name, const UbseMemBorrower &borrower, const UbseMemNumaCreateOpt &opt, UbseMemNumaDesc &desc);
参数:
name: 借用标识borrower: 借用方信息opt: 借出方信息desc: 借用形成的远端 NUMA 信息
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseMemNumaCreateWithCandidate
指定候选借出节点，提供给插件使用 NUMA 借用。
UbseResult UbseMemNumaCreateWithCandidate(const std::string &name, const UbseMemBorrower &borrower, const UbseMemNumaCandidateOpt &opt, UbseMemNumaDesc &desc);
参数:
name: 借用标识borrower: 借用方信息opt: 借用方信息desc: 借用形成的远端 NUMA 信息
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseMemNumaDelete
删除指定 NUMA 远端内存。
UbseResult UbseMemNumaDelete(const std::string &name, const UbseMemBorrower &borrower);
参数:
name: 借用标识borrower: 借用方信息
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseMemAddrCreate
提供给插件使用地址借用。
UbseResult UbseMemAddrCreate(const std::string &name, const UbseMemBorrower &borrower, const UbseMemProcessLender &lender, uint32_t flag, UbseMemAddrDesc &desc);
参数:
name: 借用标识borrower: 借用方信息lender: 借出方信息flag: 额外的内存借用属性desc: 借用形成的远端 NUMA 信息
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseMemAddrDelete
删除地址借用。
UbseResult UbseMemAddrDelete(const std::string &name, const UbseMemBorrower &borrower);
参数:
name: 借用标识borrower: 借用方信息
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseMemDebtCircleCheck
检查借用是否成环。
UbseResult UbseMemDebtCircleCheck(const std::string &srcNodeId, const std::string &dstNodeId, bool &isCircle);
参数:
srcNodeId: 借入 NodeIddstNodeId: 借出 NodeIdisCircle: 是否成环
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
UbseGetAddrMemDebtInfoWithNode
返回和传入节点相关的地址借用账本信息。传入节点对账完成则返回成功，传入节点未对账完成，如果剩余节点全部对账完成返回成功，否则返回部分成功。
UbseResult UbseGetAddrMemDebtInfoWithNode(const std::string &nodeId, std::vector<UbseMemAddrDesc> &debtInfos);
参数:
nodeId: 节点 IDdebtInfos: 地址借用账本对象集合
返回值:
UBSE_OK: 成功- 其他: 失败，详见
ubse_error.h
常量
UBSE_MAX_USR_INFO_LEN
调用方私有数据的最大长度。
static constexpr uint32_t UBSE_MAX_USR_INFO_LEN = 32;
UBSE_MEM_FLAG_NO_WR_DELAY
非写接力模式标志。
#define UBSE_MEM_FLAG_NO_WR_DELAY 0x1
总结
UBSE 内存控制器提供了一组丰富的接口，用于管理内存借用关系。通过这些接口，可以方便地进行 NUMA 和地址借用，同时支持查询和删除操作。