From ab58baa106155969a9c842f4c3049cad125ba44d Mon Sep 17 00:00:00 2001 From: GaoChao Date: Sat, 29 Nov 2025 11:43:00 +0800 Subject: [PATCH] docs: add comprehensive documentation index to README files - Add detailed documentation section with API, device, and system interface docs - Include links to all interface documentation (libobmm, obmm_export, obmm_import, etc.) - Add device documentation links (kernel module, shared memory device) - Add system interface documentation (sysfs, preimport monitoring) - Include other documentation links (README, release notes) - Update deployment note with openEuler Kernel PR #19100 reference Signed-off-by: GaoChao --- README.en.md | 31 ++++++++++++++++++++++++++++--- README.md | 27 ++++++++++++++++++++++++++- doc/README.md | 2 +- doc/libobmm.md | 4 ++-- doc/obmm_export.md | 8 ++++---- 5 files changed, 61 insertions(+), 11 deletions(-) diff --git a/README.en.md b/README.en.md index ce999ea..ce2c25f 100644 --- a/README.en.md +++ b/README.en.md @@ -74,6 +74,31 @@ OBMM's ownership mechanism and cross-node memory sharing capabilities provide th > **Technical Vision**: OBMM not only solves current consistency issues but also provides foundational support for future computing architecture innovations. As hardware technology develops, OBMM will continue to evolve, supporting richer application scenarios and higher performance requirements. +## 📚 Documentation + +### API Documentation +- **[Userspace Library Overview](doc/libobmm.md)** - libobmm interface overview, core data structures, usage models +- **[Memory Export](doc/obmm_export.md)** - `obmm_export()` interface documentation +- **[Memory Unexport](doc/obmm_unexport.md)** - `obmm_unexport()` interface documentation +- **[Memory Import](doc/obmm_import.md)** - `obmm_import()` interface documentation +- **[Memory Unimport](doc/obmm_unimport.md)** - `obmm_unimport()` interface documentation +- **[Memory Preimport](doc/obmm_preimport.md)** - `obmm_preimport()` interface documentation +- **[Memory Unpreimport](doc/obmm_unpreimport.md)** - `obmm_unpreimport()` interface documentation +- **[Ownership Setting](doc/obmm_set_ownership.md)** - `obmm_set_ownership()` interface documentation +- **[Memory Query](doc/obmm_query.md)** - `obmm_query_memid_by_pa()`, `obmm_query_pa_by_memid()` interface documentation + +### Device Documentation +- **[OBMM Kernel Module](doc/obmm.md)** - obmm.ko parameter description and /dev/obmm device documentation +- **[Shared Memory Device](doc/obmm_shmdev.md)** - obmm_shmdev\${mem_id} device usage documentation + +### System Interface Documentation +- **[Shared Memory Device Sysfs](doc/obmm_shmdev_sysfs.md)** - /sys/devices/obmm/obmm_shmdev\${mem_id}/ monitoring directory content description +- **[Preimport Sysfs](doc/obmm_preimport_sysfs.md)** - /proc/obmm/preimport_info monitoring file format description + +### Other Documentation +- **[Documentation Directory](doc/README.md)** - Documentation organization structure description +- **[Release Notes](doc/RELEASE-NOTES.md)** - Version release information + ## 🤝 Community Support - Issue Reporting: [Gitee Issues](https://gitee.com/openeuler/obmm/issues) @@ -81,9 +106,9 @@ OBMM's ownership mechanism and cross-node memory sharing capabilities provide th ## 📄 License -The kernl module obmm is licensed under the [GPL-2.0](LICENSE/GPL-2.0) License. +The kernel module obmm is licensed under the [GPL-2.0](LICENSE/GPL-2.0) License. -The userspace libobmm is licensed under the [MulanPSL2](LICENSE/MulanPSL2) License. +The userspace libobmm is licensed under the [Mulan-PSL-v2](LICENSE/Mulan-PSL-v2) License. ## 🏷️ Project Timeline |Date | Event | Milestone | @@ -102,4 +127,4 @@ The userspace libobmm is licensed under the [MulanPSL2](LICENSE/MulanPSL2) Licen --- -**Note**: This project requires corresponding hardware platform support. Please ensure your environment meets all dependency requirements before deployment. +**Note**: This project requires corresponding hardware platform support and kernel modifications (related code has been submitted to [openEuler Kernel PR #19100](https://gitee.com/openeuler/kernel/pulls/19100)). Please ensure your environment meets all dependency requirements before deployment. diff --git a/README.md b/README.md index 811c568..093b6ac 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,31 @@ OBMM 的所有权机制和跨节点内存共享能力为未来更多创新应用 > **技术愿景**: OBMM 不仅解决当前的一致性问题，更为未来的计算架构创新提供基础支撑。随着硬件技术的发展，OBMM 将持续演进，支持更丰富的应用场景和更高的性能要求。 +## 📚 文档 + +### API 文档 +- **[用户态库总览](doc/libobmm.md)** - libobmm 接口总览、核心数据结构说明、使用模型说明 +- **[内存导出](doc/obmm_export.md)** - `obmm_export()` 接口说明 +- **[内存取消导出](doc/obmm_unexport.md)** - `obmm_unexport()` 接口说明 +- **[内存导入](doc/obmm_import.md)** - `obmm_import()` 接口说明 +- **[内存取消导入](doc/obmm_unimport.md)** - `obmm_unimport()` 接口说明 +- **[内存预导入](doc/obmm_preimport.md)** - `obmm_preimport()` 接口说明 +- **[取消预导入](doc/obmm_unpreimport.md)** - `obmm_unpreimport()` 接口说明 +- **[所有权设置](doc/obmm_set_ownership.md)** - `obmm_set_ownership()` 接口说明 +- **[内存查询](doc/obmm_query.md)** - `obmm_query_memid_by_pa()`, `obmm_query_pa_by_memid()` 接口说明 + +### 设备文档 +- **[OBMM 内核模块](doc/obmm.md)** - obmm.ko 参数说明与 /dev/obmm 设备说明 +- **[共享内存设备](doc/obmm_shmdev.md)** - obmm_shmdev\${mem_id} 设备使用说明 + +### 系统接口文档 +- **[共享内存设备 Sysfs](doc/obmm_shmdev_sysfs.md)** - /sys/devices/obmm/obmm_shmdev\${mem_id}/ 维测目录内容说明 +- **[预导入 Sysfs](doc/obmm_preimport_sysfs.md)** - /proc/obmm/preimport_info 维测文件格式说明 + +### 其他文档 +- **[文档目录说明](doc/README.md)** - 文档组织结构说明 +- **[发布说明](doc/RELEASE-NOTES.md)** - 版本发布信息 + ## 🤝 社区支持 - 问题报告: [Gitee Issues](https://gitee.com/openeuler/obmm/issues) @@ -102,4 +127,4 @@ OBMM 的所有权机制和跨节点内存共享能力为未来更多创新应用 --- -**注意**: 本项目需要相应的硬件平台支持。在部署前请确认您的环境满足所有依赖要求。 \ No newline at end of file +**注意**: 本项目需要相应的硬件平台支持和内核态修改支持（相关代码已提交至 [openEuler Kernel PR #19100](https://gitee.com/openeuler/kernel/pulls/19100)）。在部署前请确认您的环境满足所有依赖要求。 \ No newline at end of file diff --git a/doc/README.md b/doc/README.md index 79d9bb9..9108d91 100644 --- a/doc/README.md +++ b/doc/README.md @@ -18,7 +18,7 @@ | --------------------- | ------------------------------------------------------------ | | libobmm.md | libobmm 接口总览、核心数据结构说明、使用模型说明、粒度说明 | | obmm_export.md | `obmm_export()`接口说明 | -| obmm_export.md | `obmm_unexport()` 接口说明 | +| obmm_unexport.md | `obmm_unexport()` 接口说明 | | obmm_import.md | `obmm_import()` 接口说明 | | obmm_unimport.md | `obmm_unimport()` 接口说明 | | obmm_preimport.md | `obmm_preimport()` 接口说明 | diff --git a/doc/libobmm.md b/doc/libobmm.md index 2308488..56f51be 100644 --- a/doc/libobmm.md +++ b/doc/libobmm.md @@ -2,7 +2,7 @@ OBMM 是在单机内管理远端内存的基础组件，可以将本地内存导出（export），将其他系统导出的内存引入（import）。export、import 两方的 OBMM 组件依次完成数据通路配置后，import 侧的应用可以像使用本端内存一样，使用 `load` 、`store` 访问远端内存。 -OBMM 组件包含用户态库 libobmm.so 和内核模块 obmm.ko（详见obmm(4)）。本文档包含 libomm 的功能总览，并介绍其中的关键数据结构。libobmm 的每个函数有专有的文档展开描述。 +OBMM 组件包含用户态库 libobmm.so 和内核模块 obmm.ko（详见obmm(4)）。本文档包含 libobmm 的功能总览，并介绍其中的关键数据结构。libobmm 的每个函数有专有的文档展开描述。 ## OBMM API 总览 @@ -55,7 +55,7 @@ OBMM 使用64位整数编码内存每段 OBMM 内存，其中 `OBMM_INVALID_MEMI struct obmm_mem_desc { uint64_t addr; uint64_t length; - /* 128bit eid, ordered by small-endian */ + /* 128bit eid, ordered by little-endian */ uint8_t seid[16]; uint8_t deid[16]; uint32_t tokenid; diff --git a/doc/obmm_export.md b/doc/obmm_export.md index dbae399..4cbb5e0 100644 --- a/doc/obmm_export.md +++ b/doc/obmm_export.md @@ -78,7 +78,7 @@ struct obmm_mem_desc { length需要满足如下要求： 1. length必须按OBMM基础粒度对齐，同时满足内存分配器与UMMU的粒度约束。 -**falgs**: 导出内存的属性，当前仅支持0。 +**flags**: 导出内存的属性，当前仅支持0。 **desc**: 指向一个OBMM的内存描述符，用于传入内存的属性参数，同时接收地址信息。其中priv_len、priv域段为入参，addr，length，tokenid域段为出参，其他参数会被忽略。 @@ -116,7 +116,7 @@ struct obmm_mem_desc { * flags 允许值有：`OBMM_EXPORT_FLAG_FAST` 和 `OBMM_EXPORT_FLAG_ALLOW_MMAP`。 * `ENODEV`: 只允许从已上线的本地NUMA节点分配内存。 * `ENOMEM`：系统内存不足。 -* `EEXIST：`申请`region` 已存在。 +* `EEXIST:` 申请`region` 已存在。 * `E2BIG`：请求的 NUMA 数量大于系统支持最大值。 * `ENOSPC`：指定范围内无可用 `memid`。 * `EOVERFLOW`：内存溢出，请求的内存总大小超出`unsigned long`的范围。 @@ -153,7 +153,7 @@ int export_interface_demo(void) struct obmm_mem_desc desc = { .priv_len = 0 }; - memcpy(desc->deid, &device_deid, 4); + memcpy(desc.deid, &device_deid, 4); /* Export memory from OBMM. */ id = obmm_export(length, flags, &desc); if (id == OBMM_INVALID_MEMID) { @@ -189,7 +189,7 @@ int export_useraddr_interface_demo(void) struct obmm_mem_desc desc = { .priv_len = 0 }; - memcpy(desc->deid, &device_deid, 4); + memcpy(desc.deid, &device_deid, 4); /* Export memory from OBMM. */ id = obmm_export_useraddr(length, flags, &desc); if (id == OBMM_INVALID_MEMID) { -- Gitee