SHMEM_LOG_LEVEL【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmemControls SHMEM runtime log level.Values:ERRORWARNINFODEBUGDefault: WARN. Effective time: read during SHMEM initialization, for exampleaclshmemx_init_attr.--- ## 5. C/C 格式与命名空间第 5 章 SHMEM C/C 代码采用 Google C 风格的基本约束并结合项目既有习惯。仓库根目录提供 [.clang-format](https://link.gitcode.com/i/bcd693d71b7f5ec7ec4b791415165ce9)以仓库配置为准新增代码不应通过手工排版对抗 clang-format。仓库实际的 .clang-format 关键配置与规范一致 - BasedOnStyle: Google - ColumnLimit: 120 - IndentWidth: 4UseTab: Never - PointerAlignment: Left指针左对齐例如 int *ptr - BreakBeforeBraces: CustomAfterFunction: true函数左大括号换行其余紧凑 - SortIncludes: falseinclude 顺序由开发者按语义组织不强制字母序 基本要求缩进 4 空格、单行不超过 120 列、指针左对齐、函数/变量/文件名使用 snake_case、枚举值与公共宏使用全大写下划线、不使用 tab、函数参数较多时按语义分组换行、有意未使用的参数使用 (void)param; 显式标记。函数声明示例 c ACLSHMEM_HOST_API void aclshmemx_putmem_on_stream( void *dst, void *src, size_t elem_size, int32_t pe, aclrtStream stream);命名空间使用上公共头文件禁止using namespace std;推荐显式完全限定名// 不推荐 using namespace std; class Foo { public: vectorint values; };// 推荐 class Foo { public: std::vectorint values; };源文件中允许函数内部局部命名空间别名void create_endpoint() { namespace local_alias fully::qualified::namespace_name; local_alias::Endpoint endpoint; }6. 公共类型与 ABI第 6 章6.1 公共类型要求类型名使用aclshmem_*_t或aclshmemx_*_t枚举值使用ACLSHMEM_*或ACLSHMEMX_*公共结构体字段使用snake_case。公共结构体字段应有注释说明用途、生命周期、单位和合法范围。面向 ABI 的结构体建议包含version、size或等价版本字段对外结构体新增字段时优先尾部追加不重排已有字段。指针字段必须说明所有权、是否可为空、是否要求对称内存、是否要求对齐enum 字段必须说明非法值处理方式。结构体初始化应提供初始化宏、初始化函数或明确的零初始化约定。公共数据结构中不得出现aclshmemi_*字段类型、内部句柄或内部上下文指针。规范引用的公共初始化属性结构体与仓库 include/host/shmem_host_def.h 中的实际定义一致typedef struct aclshmemx_init_attr_t { int my_pe; int n_pes; char ip_port[ACLSHMEM_MAX_IP_PORT_LEN] {}; uint64_t local_mem_size; aclshmem_init_optional_attr_t option_attr { (1 16) sizeof(aclshmem_init_optional_attr_t), ACLSHMEM_DATA_OP_MTE, DEFAULT_TIMEOUT, DEFAULT_TIMEOUT, DEFAULT_TIMEOUT}; void* comm_args nullptr; uint64_t instance_id 0; } aclshmemx_init_attr_t;对照仓库源码注释可以进一步理解各字段语义my_pe为当前进程 PE 号n_pes为全部进程总数ip_port为通信服务端的 IP 与端口端口不得与其他模块和进程冲突local_mem_size在aclshmemx_init_attr()下表示默认对称堆的用户可分配容量在aclshmemx_init_attr_with_buffers()下表示固定 user-buffer 前缀之后追加的可分配容量descriptor 大小不计入该值该容量内的内存可通过公共对称分配接口获取。6.2 内部类型要求内部类型不得成为用户需要声明、传入、保存或解释的对象不允许typedef struct aclshmemi_context aclshmem_context_t;。确有必要暴露状态或句柄时应封装成公共 opaque 类型typedef struct public_context *public_context_t;并在文档中明确创建接口、销毁接口、是否可复制、是否可跨线程使用、是否可跨 PE 使用、finalize 后是否失效、失败后句柄是否有效。用户不应依赖公共句柄的内部布局。仓库中的aclshmem_handle_t见 include/host_device/shmem_common_types.h就是这类用户只持有句柄、不依赖内部布局的 opaque 类型形态。6.3 存量兼容策略新增公共 API、公共类型和公共宏必须符合上述规则存量不符合规则的公共符号不得扩大使用范围。确需保留的历史兼容符号应满足不在新增代码中继续使用、不在示例和新文档中推荐使用、有明确替代接口、有迁移说明、有删除计划或兼容性说明。若历史内部前缀符号已完成整改如aclshmemi_*迁移到aclshmemx_*公共头文件、示例和用户文档中不应再保留旧内部前缀别名。7. Host API 与 Device API第 7 章7.1 Host APIHost API 指由 Host CPU 调用的接口负责初始化、配置、资源管理、同步和任务下发应满足使用ACLSHMEM_HOST_API或项目统一导出宏命名使用aclshmem_*或aclshmemx_*注释明确执行域为 Host、是否线程安全、是否阻塞对异步提交接口说明完成条件对 stream 接口说明入队成功、本地完成和 stream 同步要求对将进入 Device 路径的参数做必要合法性检查避免 Device release 路径重复兜底。仓库中的 Host 声明确实统一标注了ACLSHMEM_HOST_API例如 include/host/init/shmem_host_init.h 的aclshmemx_init_attr与 include/host/data_plane/shmem_host_p2p_sync.h 的aclshmemx_handle_wait。Host API 不强制全部返回int规则如下管理类、配置类、提交类和新增功能类接口原则上返回int或aclshmem_error_code_t内存分配类接口可以返回指针但必须明确失败返回NULL的语义释放类接口可以返回void但必须明确空指针行为和调用前置条件查询类接口可以通过返回值或输出参数返回结果但必须明确失败处理方式公共 API 不抛异常、不返回未文档化的特殊值。示例ACLSHMEM_HOST_API int aclshmemx_init_attr( aclshmemx_bootstrap_t bootstrap_flags, aclshmemx_init_attr_t *attributes); ACLSHMEM_HOST_API void *aclshmem_malloc(size_t size); ACLSHMEM_HOST_API int aclshmem_finalize(void); ACLSHMEM_HOST_API void aclshmem_free(void *ptr);7.2 Device APIDevice API 指在设备执行上下文中调用的接口负责数据搬运、远端访存、原子和同步应满足使用ACLSHMEM_DEVICE或项目统一 device 标记注释明确调用域device-only、block、warp、vector、AIV、AIC 或 host/device 皆可不引入发布路径上的非必要 runtime 分支不依赖未文档化的编译宏组合对内存可见性、同步需求和线程域限制写清楚对传输引擎、芯片型号、CANN 版本依赖写清楚对 UB workspace、sync_id、event_id、notify 地址等资源写清楚生命周期和复用规则Device release 路径不做非必要兜底检查。仓库中的 Device 声明统一使用ACLSHMEM_DEVICE标记例如 include/device/gm2gm/engine/shmem_device_mte.h 中大量ACLSHMEM_DEVICE修饰的 MTE 引擎接口aclshmemx_mte_put_nbi、aclshmemx_mte_quiet、aclshmemx_mte_atomic_*等。Device API 注释应明确支持的数据类型指针地址空间要求global memory、UB、LocalTensor对称地址要求PE 参数合法范围是否同步返回是否需要quiet、fence、barrier、sync或 engine-specific quiet并发限制同一 PE、同一 remote address、同一 sync_id 是否支持并发使用不支持类型/平台/线程域时的行为哪些错误由 Host 侧检查、哪些 debug 检查仅在 Device debug 模式启用。7.3 Device 侧 release/debug 检查边界Device 侧代码应区分三类分支规范给出了清晰的判定表类型release 路径是否允许说明业务语义分支允许例如按线程域、数据类型、传输引擎选择不同实现编译期能力分派允许例如#if、if constexpr、模板特化防御性参数检查默认不允许应放入 debug 模式或 Host 侧检查状态兜底检查默认不允许应在 Host 侧、初始化阶段或提交阶段处理慢路径 fallback默认不允许除非已证明是必要语义且有性能评估平台兼容 fallback默认不允许应在 Host 侧能力查询或初始化阶段处理Device release 路径不推荐的写法if (ptr NULL) { return; } if (!is_supported_engine(engine)) { fallback_to_other_engine(...); } if (!is_aligned(ptr, 32)) { slow_path(...); }Device 侧检查宏要求宏位于公共头文件时使用ACLSHMEM_*或ACLSHMEMX_*前缀只位于内部实现文件时使用ACLSHMEMI_*前缀debug check 在 release 编译中必须为空实现或被编译器完全优化掉不得改变 release 行为不得引入用户可依赖的错误返回语义。项目尚未统一引入并验证 debug check 封装前对外规范不预置具体 debug 宏名。8. API 注释规范第 8 章公共 API 使用 Doxygen 风格注释新增或修改公共 API 时注释至少包含brief一句话说明接口行为参数说明每个参数标注[in]、[out]或[in,out]返回值说明成功值和失败错误码执行域Host、Device、stream、block、warp、vector、AIV 或 AIC阻塞语义blocking、non-blocking、入队或异步提交完成语义何时本地完成、何时远端可见、是否需要quiet、barrier、sync、engine-specific quiet 或 stream 同步线程安全是否可并发调用是否要求外部串行化内存要求是否要求对称内存、地址空间、对齐、大小单位和生命周期Device 检查边界哪些合法性由 Host 侧保证哪些 debug 检查仅在 debug 模式启用失败行为失败后输出参数、句柄、stream 任务和内存状态是否有效。注释中避免重复代码字面含义例如不要把count注释成 the count应说明单位、范围和行为影响。Host API 推荐模板/** * brief Submit a non-blocking put operation to a remote PE. * * param[in] dst Destination symmetric address on the remote PE. Must not be NULL. * param[in] src Source buffer on the local PE. Must not be NULL. * param[in] size Number of bytes to transfer. * param[in] pe Remote PE number. Must be in the valid PE range. * * note Address requirements: dst points to symmetric memory on pe. src is * used as supplied and may be any valid local device GM buffer. * note RDMA-enabled configuration: If initialization enables RDMA by setting * ACLSHMEM_DATA_OP_ROCE, complete transfer ranges for both operands must * remain within their respective symmetric memory allocations. Runtime * dispatch may select RDMA * for the target PE; callers need not determine the per-operation engine. * note Execution domain: Host. * note Blocking semantics: non-blocking. Returning from this void API only * means the submission path has returned; it is not a completion signal. * note Completion semantics: the caller must call aclshmem_quiet(), * aclshmem_barrier(), aclshmem_sync(), an engine-specific quiet API, * or synchronize the associated stream as documented before reusing * resources or assuming remote visibility. * note Failure behavior: this existing API does not return a status code. * Implementations must document diagnostics and error propagation * through the established project mechanism. * note Thread safety: thread-safe after successful initialization unless * otherwise documented. */ ACLSHMEM_HOST_API void aclshmem_putmem_nbi(void *dst, void *src, size_t elem_size, int32_t pe);Device API 注释示例强调调用域与 debug 检查边界/** * brief Put data from the current device execution context to a remote PE. * * param[in] dst Destination symmetric address on the remote PE. * param[in] src Source address in device global memory. * param[in] size Number of bytes to transfer. * param[in] pe Remote PE number. * * note Address requirements: dst points to symmetric memory on pe. src is * used as supplied and may be any valid address in device global memory. * note RDMA-enabled configuration: If initialization enables RDMA by setting * ACLSHMEM_DATA_OP_ROCE, complete transfer ranges for both operands must * remain within their respective symmetric memory allocations. Runtime * dispatch may select RDMA * for the target PE; callers need not determine the per-operation engine. * note Execution domain: Device. * note The caller must ensure that dst and src are non-NULL, properly aligned, * and that pe is valid. These conditions may be checked only in debug * builds. Release device code does not perform defensive fallback checks. * note Completion semantics: the caller must use the documented quiet or sync * operation before assuming remote visibility. */ /* device-side public API declaration */9. 错误处理与日志第 9 章9.1 返回码成功返回0或ACLSHMEM_SUCCESS失败返回稳定的负值错误码或文档明确的失败值。公共 API 不抛异常、不返回未文档化的特殊值。不把底层依赖错误码直接作为公共错误码泄漏除非该错误码已被纳入公共契约。错误码按语义分层层级典型场景参数错误空指针、越界、非法枚举值、非法 size、非法 alignment状态错误未初始化、重复初始化、finalize 后调用、上下文不匹配资源错误内存不足、句柄失效、sync_id 不足、event 不足、底层依赖不可用运行错误超时、远端不可达、设备执行失败、stream 提交失败能力错误当前平台、芯片、CANN 版本、传输引擎或后端不支持内部错误不变量破坏或不应发生的状态应记录日志并返回稳定错误码9.2 调用侧处理调用有状态返回值的公共 API 后应检查返回值失败路径应及时退出或进入统一错误处理逻辑不应继续使用无效指针、无效句柄、无效 team、无效 stream、未完成初始化的上下文、分配失败返回的NULL、提交失败但仍假定存在的异步任务。示例int ret aclshmemx_set_sdma_config(offset, ub_size, sync_id); if (ret ! ACLSHMEM_SUCCESS) { SHM_LOG_ERROR(aclshmemx_set_sdma_config failed, ret ret); return ret; } void *buf aclshmem_malloc(size); if (buf NULL) { SHM_LOG_ERROR(aclshmem_malloc failed, size size); aclshmem_finalize(); return ACLSHMEM_MALLOC_FAILED; }9.3 日志对外日志使用项目统一 logger 或 logger 回调错误日志应包含 API 名称、错误码和关键上下文。日志不得泄漏敏感信息、密钥、用户数据内容、完整内存 dump 或未经脱敏的网络地址。同一失败路径避免重复打印公共 API 默认不应输出大量 INFO 日志性能路径中的日志必须可关闭或按日志级别控制。Device 侧调试输出不得进入默认发布路径Device 侧 release 路径不得通过日志替代错误处理。日志中的错误码必须与返回码一致避免误导排障。推荐格式SHM_LOG_ERROR(aclshmem_team_split_strided failed, ret ret , start start , stride stride , size size);10. 异步与同步语义第 10 章带有nbi、on_stream或其他异步语义的接口必须明确成功返回是否仅表示提交成功是否表示任务已入队数据何时本地可复用远端数据何时可见用户需要调用哪个完成性接口Host 发起和 Device 发起的操作是否属于同一完成域stream 同步、device 同步、SHMEM quiet、barrier、sync 之间的关系。10.1 必须区分的六种状态状态含义提交成功API 参数检查通过任务已提交到运行时、内部队列或传输引擎入队成功任务已进入 stream、SQ、WQ 或 engine 队列本地完成本地 buffer 可复用或本地写入已完成远端可见远端 PE 可以观察到数据更新通信完成当前执行域发起的通信操作已完成全局同步完成指定 team 或所有 PE 达到同步点10.2 完成性接口异步接口必须说明需要哪个完成性接口aclshmem_quiet、aclshmem_fence、aclshmem_barrier、aclshmem_sync、stream 同步接口、device 同步接口或 engine-specific quiet/wait 接口MTE、SDMA、RDMA、UDMA 对应。10.3 示例代码要求示例代码中如果使用异步接口必须显式展示完成性操作aclshmem_putmem_nbi(dst, src, size, pe); /* Required before reusing src or assuming remote visibility. */ aclshmem_quiet();stream 示例必须展示 stream 同步或明确交给调用者同步aclshmemx_putmem_on_stream(dst, src, size, pe, stream); aclError acl_ret aclrtSynchronizeStream(stream); if (acl_ret ! ACL_SUCCESS) { return ACLSHMEM_INNER_ERROR; }11. 内存与对齐第 11 章SHMEM 通信路径对内存布局、对称性、cache line、page、UB workspace 和硬件 DMA 对齐敏感。新增公共结构体、共享状态、通信缓冲区、对称堆分配和内存池切分逻辑时应按分配来源和使用场景分别说明对齐要求不得只写按 cache line 对齐这类泛化描述。11.1 对称堆分配用户/API 语义统一使用对称内存symmetric memory仅在描述底层预留堆、heap_base、heap_size或分配器实现时使用对称堆symmetric heap。用户可通信的对称内存应通过公共内存 API 获取aclshmem_malloc、aclshmem_calloc、aclshmem_align、aclshmemx_malloc、aclshmemx_calloc、aclshmemx_align。示例和文档不得要求用户依赖内部堆实现。使用aclshmem_align(alignment, size)时alignment必须为 2 的幂调用侧必须处理分配失败返回NULL的情况size 0、分配失败和返回NULL的语义必须在接口注释或调用侧体现。各 PE 上的对称内存必须保持一致的分配关系相同顺序、相同大小或文档明确允许的方式。不得把普通malloc/new的 Host 地址作为 SHMEM 对称地址传入 RMA、AMO、signal 或同步 API不得在公共 ABI 中暴露内部 allocator 布局、chunk header、free list、页表或远端地址翻译细节。11.2 初始化属性与对称内存大小涉及local_mem_size、heap size、page size 或内部映射大小时单位必须写明为 byte是否要求所有 PE 一致必须写清楚是否按 page 向上对齐必须写清楚不得在业务代码中散落裸数字应使用统一宏或 helper 做对齐例如ALIGN_TO(size, page)对齐失败、整数溢出和 size 超过上限必须有错误处理公共结构体中表示内存大小的字段应使用size_t、uint64_t或项目统一类型不使用不明确宽度的int。11.3 AscendCL Device/Host 内存二次分配基于aclrtMalloc、aclrtMallocHost或其他 AscendCL 接口申请大块内存并自行切分时每个子段必须满足对应 API 的 size 和起始地址对齐要求子段大小按 32 字节向上对齐后额外保留 32 字节即类似ALIGN_UP(len, 32) 32模式子段起始地址满足 64 字节对齐大块内存切分逻辑必须集中封装不得在业务代码中手写不同版本的ALIGN_UP不得假设普通malloc/new返回的 Host 地址可直接满足 Device DMA、RMA 或异步拷贝路径要求。对齐与溢出检查要求alignment必须为 2 的幂对齐计算必须检查alignment合法性非法时返回错误或 0指针对齐检查必须同时验证 alignment 合法性和地址对齐涉及 size 加法或乘法时必须检查整数溢出对齐与溢出检查 helper 属于内部实现不得放入include/**应使用项目统一封装。11.4 Ascend C LocalTensor、UB 和数据搬运LocalTensor/UB 相关缓冲区默认按 32 字节粒度设计和检查如果具体 API 要求 512B、64B、128B 或其他粒度必须在 API 注释、config 结构和示例中写明。UB workspace 字段必须说明地址空间、size 单位、最小容量、对齐要求、生命周期、是否可跨调用复用、是否可被多个 core 并发使用。sync_id、event_id、notify 地址、flag 地址等同步资源必须说明分配来源和复用规则。不同 TPosition、不同传输引擎、不同芯片型号的对齐要求可能不同不得把某一接口的 32B 或 512B 约束推广成全仓唯一规则。11.5 cache line、L2 cache line 和 page需要 scalar cache line 对齐时使用项目统一常量不硬编码64需要 L2 cache line 对齐时使用项目统一常量不硬编码512需要 SHMEM page 对齐时使用项目统一常量不硬编码2 * 1024 * 1024共享状态、同步 flag、signal、doorbell、notify 地址和跨 PE 访问的元数据结构必须避免伪共享固定布局结构体必须配合static_assert(sizeof(...))、字段 offset 检查或 ABI 测试公共 ABI 不得依赖未文档化的编译器 padding、临时结构体布局或内部 allocator 实现。示例static_assert(SCALAR_DATA_CACHELINE_SIZE 64, Unexpected scalar cache line size); static_assert(L2_CACHELINE_SIZE 512, Unexpected L2 cache line size);11.6 对齐检查涉及对齐的公共 Host API 应在入口处检查alignment 是否为 2 的幂、pointer 是否满足 alignment、size 是否满足最小粒度、size 对齐计算是否溢出、对称地址是否来自合法对称堆、UB workspace 是否满足 size 和地址空间要求。检查失败应返回参数错误不得继续提交通信操作。Device API release 路径不应重复做上述非必要兜底检查Device 侧只在 debug 模式下保留对应DCHECK或断言。12. msSanitizer 约束第 12 章12.1 检查范围新增代码涉及以下路径时必须评估是否需要使用 msSanitizer 做内存检测或竞争检测SHMEM RMA 路径SHMEM AMO 路径signal / wait / sync 路径Device kernel 访问路径工具支持范围内的 DMA / SDMA / RDMA / UDMA / MTE 等传输路径跨 PE 远端访问路径runtime 内部异步拷贝路径。后续新增传输路径或相关接口时必须主动拉起 msSanitizer 支持范围检查确认工具是否覆盖该路径并在 PR 中记录检查结论、验证命令和结果若工具暂不支持应说明原因并补充等效验证依据或后续验证计划。12.2 使用方式SHMEM 的 msSanitizer 验证通过编译插桩和运行时工具拉起完成使用bash scripts/build.sh -mssanitizer或组合样例参数例如bash scripts/build.sh -examples -mssanitizer。USE_MSSANITIZERON时CMake 会按SOC_TYPE与 bisheng 版本设置 sanitizer 编译选项非 Ascend950 固定为-g --cce-enable-sanitizerAscend950 在新版本 CANN 下同样启用该选项旧版本仅加-g此时 AscendC API 相关内存检测不可用详见 cmake 配置日志。运行时必须使用 mssanitizer 拉起目标程序mssanitizer -- application parameter1 parameter2 ...样例验证可参考 allgather 方式bash scripts/build.sh -examples -mssanitizer cd examples/allgather mssanitizer -- bash run.sh -pes 212.3 PR 要求涉及以下变更时PR 说明中应注明 msSanitizer 验证结果新增 allocator、修改对称堆、修改 Host/Device buffer 管理、修改通信 buffer 生命周期、修改 RMA/AMO/signal/sync/DMA 路径、修改非aclrt地址进入 Device 或通信路径的逻辑。PR 提交前应使用 msSanitizer 拉起本地测试无法覆盖的路径应在 PR 中说明原因并提供等效验证依据或后续验证计划。13. 示例代码规范第 13 章示例代码是用户学习 API 的第一入口应遵守比普通测试更严格的对外边界只使用aclshmem_*和aclshmemx_*公共 API不包含内部头文件、不调用内部函数、不使用aclshmemi_*或ACLSHMEMI_*不依赖未文档化环境变量环境变量示例使用SHMEM_*展示完整的初始化流程、返回值检查、通信完成操作和资源释放流程异步示例必须包含完成性操作Device 示例必须说明执行域、启动方式和 Host 侧参数检查多 PE 示例必须说明运行命令、PE 数量、预期输出和常见失败排查入口。推荐示例结构int main(int argc, char **argv) { /* Build attributes with aclshmemx_set_attr_uniqueid_args or project helper first. */ int ret aclshmemx_init_attr(bootstrap_flags, attributes); if (ret ! ACLSHMEM_SUCCESS) { return ret; } int my_pe aclshmem_my_pe(); int npes aclshmem_n_pes(); void *buf aclshmem_malloc(kSize); if (buf NULL) { aclshmem_finalize(); return ACLSHMEM_MALLOC_FAILED; } if (my_pe 0 npes 1) { aclshmem_putmem_nbi(remote_dst, buf, kSize, 1); aclshmem_quiet(); } aclshmem_barrier_all(); aclshmem_free(buf); aclshmem_finalize(); return 0; }Device 示例中参数合法性应在 Host 侧检查if (dst NULL || src NULL || size 0) { return ACLSHMEM_INVALID_PARAM; } if (!is_aligned(dst, 32) || !is_aligned(src, 32)) { return ACLSHMEM_INVALID_PARAM; } /* Launch kernel after validation. */不推荐在 Device kernel 中重复兜底if (dst NULL || src NULL) { return; }仓库中examples/下的大量示例如 examples/allgather、examples/init、examples/notifywait都可以作为上述规范的对照样本阅读。14. 测试与验证要求第 14 章新增代码至少应包含与风险匹配的验证变更类型验证要求命名或头文件边界变更增加静态检查或脚本检查公共 API 行为变更增加单元测试或系统测试异步语义变更覆盖提交成功、入队成功、完成、远端可见和异常路径Device API 变更覆盖不同线程域、编译宏组合和芯片能力组合Device release/debug 检查变更确认 release 路径不引入非必要if-else兜底检查内存分配或对齐变更覆盖 size 为 0、非法 alignment、未对齐地址、溢出、分配失败和释放路径msSanitizer 相关变更覆盖非aclrt地址进入通信或 Device 访问路径的验证场景ABI 相关变更检查结构体大小、字段顺序、字段 offset 和初始化兼容性示例变更确保示例可编译、可运行并有可验证输出传输引擎变更覆盖 MTE、SDMA、RDMA、UDMA 等对应路径性能路径变更除正确性测试外应保留性能基线对比测试代码可以使用内部 helper但公共示例和用户文档不得使用内部符号。Device 侧性能路径测试应至少确认release 编译下 debug check 被消除、release 路径无新增非必要防御性分支、debug 编译下非法参数能被 debug check 捕获、Host 侧参数检查覆盖 Device release 路径依赖的前置条件。15. 发布前检查清单与可执行命令第 15 章提交公共 API、公共头文件、Device 侧性能路径或示例前至少检查以下项新增或修改的include/**不引入aclshmemi_*接口或数据结构、不引入ACLSHMEMI_*公共宏新增或修改的examples/**和对外文档中无内部前缀推荐用法新增公共 API 使用aclshmem_*或aclshmemx_*公共类型使用aclshmem_*_t或aclshmemx_*_t枚举值使用ACLSHMEM_*或ACLSHMEMX_*新增公共宏使用ACLSHMEM_*或ACLSHMEMX_*新增内部宏使用ACLSHMEMI_*且不得进入公共头文件、示例和用户文档环境变量使用SHMEM_*不使用ACLSHMEM_*公共头文件和 examples 公共 include 头文件无全局using namespace新增头文件使用 include guard命名与文件路径对应新增源码文件含版权头年份与署名正确示例代码只包含公共头文件只调用公共 API异步接口注释和示例写明完成性操作Host API 与 Device API 的调用域写清楚Device release 路径不包含非必要兜底if-else检查Device 防御性检查已放入 debug 模式返回值和错误码语义可被用户稳定依赖公共结构体的版本、生命周期、字段单位和 ABI 影响已说明内存对齐要求已写明分配来源、对齐粒度和失败处理非aclrt地址进入通信或 Device 访问路径的新增逻辑已完成 msSanitizer 验证相关测试、静态检查或等效验证已执行。15.1 增量提交检查命令以下命令用于检查本次新增或修改的代码优先检查 staged diff 或 review diff历史兼容别名不应把全仓命中直接等同于新增代码违规# 新增公共区域不得引入 aclshmemi_* 或 ACLSHMEMI_* 推荐用法。 git diff --cached -U0 -- include examples docs \ | rg ^\.*\baclshmemi_|\.*\bACLSHMEMI_ # 新增公共 API 避免驼峰命名需要结合上下文人工判断。 git diff --cached -U0 -- include \ | rg ^\.*\b[A-Za-z0-9][A-Z][A-Za-z0-9_]*\s*\( # 示例和对外文档不得新增内部路径 include。 git diff --cached -U0 -- examples docs \ | rg ^\.*#\s*include\s*[].*(internal|detail|private|src)/ # 新增环境变量不得使用 ACLSHMEM_*。 git diff --cached -U0 -- src examples docs \ | rg ^\.*(getenv\(ACLSHMEM_|ACLSHMEM_[A-Z0-9_]) # 公共头文件和 examples 公共 include 头文件不得新增全局 using namespace。 git diff --cached -U0 -- include examples/**/include \ | rg ^\.*\busing\snamespace\b # 异步示例需要人工复核完成性操作。 git diff --cached -U0 -- examples docs \ | rg ^\.*(nbi|on_stream|quiet|barrier|sync|Synchronize)15.2 全量基线辅助命令只用于评估仓库历史基线和清理范围需先形成清理计划或 allowlist不得直接用全量命中否定普通新增代码rg -n \baclshmemi_ include examples docs \ --glob !**/coding_style_guide.md rg -n \bACLSHMEMI_ include examples docs \ --glob !**/coding_style_guide.md rg -n \busing\snamespace\b include examples/**/include15.3 Device 侧检查命令# 辅助发现 Device 侧新增 if 分支需要人工判断是否为业务语义分支。 git diff --cached -U0 -- include/device src \ | rg ^\.*\bif\s*\( # 辅助发现新增 fallback 语义。 git diff --cached -U0 -- include/device src \ | rg ^\.*\b(fallback|slow_path|return;|return\s0;)\b检查要求Device 侧新增if如果属于参数检查、状态检查、对齐检查或能力兜底应放入 debug check 或迁移到 Host 侧如果属于业务语义分支应在代码或 PR 中说明必要性新增 fallback 必须说明是否属于功能语义必需路径并提供性能影响评估。15.4 自动化检查提示可将下面内容与规范文件一起提供给自动化检查工具作为检查要求请按 docs/coding_style_guide.md 检查本次改动优先关注 1. 新增或修改的 include/** 是否出现 aclshmemi_* 接口、数据结构或 ACLSHMEMI_* 公共宏。 2. 公共 API 是否只使用 aclshmem_* 或 aclshmemx_* 前缀。 3. 公共宏是否使用 ACLSHMEM_* 或 ACLSHMEMX_*内部宏是否使用 ACLSHMEMI_*。 4. 新增或修改的 examples/** 是否只使用公共 API是否包含内部头文件或内部符号。 5. 环境变量是否使用 SHMEM_*是否错误使用 ACLSHMEM_*。 6. 公共头文件是否存在 using namespace。 7. Device release 路径是否新增非必要 if-else 兜底检查防御性检查是否在 debug 模式。 8. 内存路径是否说明对齐要求非 aclrt 地址进入通信或 Device 路径是否纳入 msSanitizer 验证范围。 9. 异步接口和示例是否明确 quiet、barrier、sync、stream synchronize 或 engine-specific quiet 等完成性操作。 10. 公共结构体、公共类型、错误码和 ABI 影响是否有注释和兼容性说明。【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库基于OpenSHMEM 标准协议实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考