HIXL 待废弃 ADXL 错误码全解析定义、语义、可恢复性与排障指引【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读本文面向在 CANN/HIXL 开源仓库中使用或维护待废弃 ADXLAscend Direct Xfer Library单边通信接口的开发者系统梳理docs/zh/api/cpp/deprecated_ADXL-error-code.md中定义的全部状态码先介绍其uint32_t类型与数值编码规则再逐个讲解 SUCCESS、PARAM_INVALID、TIMEOUT、NOT_CONNECTED、ALREADY_CONNECTED、NOTIFY_FAILED、UNSUPPORTED、FAILED 的含义与可恢复性并结合仓库源码include/adxl/adxl_types.h、src/llm_datadist/adxl/adxl_utils.cc 等说明这些错误码在参数校验、链路管理、传输超时等环节的产生路径与底层映射机制最后给出基于日志与现场保留的排查建议。读完本文你将能够准确解读 ADXL 接口返回值快速定位参数、建链与传输类故障。一、ADXL 错误码的总体设计ADXL 是 HIXL 仓库中即将废弃的单边通信编程模型其核心类为AdxlEngine对外接口Initialize、Connect、TransferSync、TransferAsync等统一以Status类型作为返回值。所有错误码都定义在 include/adxl/adxl_types.h 中类型为uint32_tnamespace adxl { using Status uint32_t; // status codes constexpr Status SUCCESS 0U; constexpr Status PARAM_INVALID 103900U; constexpr Status TIMEOUT 103901U; constexpr Status NOT_CONNECTED 103902U; constexpr Status ALREADY_CONNECTED 103903U; constexpr Status NOTIFY_FAILED 103904U; constexpr Status UNSUPPORTED 103905U; constexpr Status FAILED 503900U; constexpr Status RESOURCE_EXHAUSTED 203900U; } // namespace adxl从数值编码可以看出如下规律可在 adxl_types.h 第 37-46 行 核对0U成功码唯一的非错误返回值103900U ~ 103905U一类错误码覆盖参数、超时、建链、通知、能力不支持等可预期的业务错误203900URESOURCE_EXHAUSTED资源耗尽类错误虽未出现在待废弃文档的错误码表中但仓库源码中已实际定义并使用见下文“源码中的实际使用”一节503900UFAILED通用失败码用于兜底所有未单独归类的情况。Status同时被 HIXL 主库hixl命名空间与 LLM DataDist 模块复用为统一的返回值类型理解 ADXL 错误码有助于顺带理解仓库内其他模块的返回语义。二、错误码含义速查表待废弃文档给出了完整的错误码语义对照下表完整继承并补充了“产生场景”说明基于仓库源码归纳| 枚举值 | 数值 | 含义 | 是否可恢复 | 解决办法 | |--|--|--|--|--| | SUCCESS | 0U | 成功 | 无 | 不涉及。 | | PARAM_INVALID | 103900U | 参数错误 | 是 | 基于日志排查错误原因。 | | TIMEOUT | 103901U | 处理超时 | 否 | 保留现场获取 Host/Device 日志并备份。 | | NOT_CONNECTED | 103902U | 没有建链 | 是 | 上层排查建链情况。 | | ALREADY_CONNECTED | 103903U | 已经建链重复建链 | 是 | 上层排查建链情况。 | | NOTIFY_FAILED | 103904U | 通知失败 | 否 | 预留错误码暂不会返回。 | | UNSUPPORTED | 103905U | 不支持的参数或接口 | 是 | 预留错误码暂不会返回。 | | FAILED | 503900U | 通用失败 | 否 | 保留现场获取 Host/Device 日志并备份。 |关键结论PARAM_INVALID、NOT_CONNECTED、ALREADY_CONNECTED、UNSUPPORTED 属于可恢复错误业务侧在修正参数或完成建链后可以重试TIMEOUT 与 FAILED 属于不可恢复错误出现后不建议直接重试同一操作而应保留现场、收集日志后按故障流程处理NOTIFY_FAILED 与 UNSUPPORTED 在当前版本为预留错误码文档明确说明“暂不会返回”业务代码可以按防御式编程处理但不应依赖其触发路径。三、错误码的产生路径源码级剖析错误码并非凭空定义下面结合仓库源码说明各错误码在真实调用链中是如何被抛出与返回的。3.1 参数校验PARAM_INVALID 的主要来源PARAM_INVALID是出现频率最高的错误码之一绝大多数由参数校验宏产生。仓库中的校验宏定义在 src/llm_datadist/adxl/adxl_checker.h// Check if the parameter is null. If yes, return PARAM_INVALID and record the error #define ADXL_CHK_NULL_RET_STATUS(val, ...) ... // Check if the parameter is valid. If not, return PARAM_INVALID and record the error #define ADXL_CHK_BOOL_RET_STATUS(expr, status, ...) ...典型使用场景见 src/llm_datadist/adxl/adxl_inner_engine.cc例如中转内存池配置解析失败、buffer 数量/大小非法第 228-245 行OPTION_AUTO_CONNECT取值不为 0 或 1第 141-146 行传输类型非法第 469 行查询一个不存在的异步请求句柄第 560-561 行。在 src/llm_datadist/adxl/buffer_transfer_service.cc 中中转传输服务还会对 buffer 长度总和、地址溢出ge::AddOverflow、切片数量等进行校验失败同样返回PARAM_INVALID。3.2 建链状态NOT_CONNECTED 与 ALREADY_CONNECTED这两个错误码对应链路管理。在 adxl_inner_engine.cc 中执行TransferSync、TransferAsync、GetTransferStatus等接口时若通过remote_engine查询不到对应 channel即返回NOT_CONNECTED见第 490、525、566-571、603 行等建链阶段若发现重复建链则返回ALREADY_CONNECTED对应Connect接口返回语义。这与文档中“NOT_CONNECTED没有建链上层排查建链情况ALREADY_CONNECTED已经建链上层排查建链情况”的描述完全一致这两个错误码本质是引导业务层检查自身建链流程属于可恢复错误。3.3 超时TIMEOUT 的触发场景TIMEOUT并非只在传输阶段出现建链Connect默认超时 1000ms、断链、传输、异步传输等待见 adxl_inner_engine.cc 第 621 行都可能因超时返回。在 buffer_transfer_service.cc 中大量time_cost timeout的判断第 106、112、131、150、167、209、248、267 行等表明中转传输的每一步取 buffer、等待对端、拷贝完成都有独立超时控制任一环节超时即返回TIMEOUT。由于文档将TIMEOUT标记为不可恢复处理建议是不要盲目重试先确认网络质量、对端负载与配置的超时值是否合理。3.4 预留错误码NOTIFY_FAILED 与 UNSUPPORTEDNOTIFY_FAILED103904U文档明确“预留错误码暂不会返回”当前仓库源码中未见其实际返回路径UNSUPPORTED103905U同样为预留错误码但在 buffer_transfer_service.cc 第 522、560 行 可见其潜在使用逻辑当底层批量拷贝接口返回“特性不支持”如ACL_ERROR_RT_FEATURE_NOT_SUPPORT时会向上转换为UNSUPPORTED。也就是说该错误码在特定型号/特性组合下有被触发的可能业务侧可提前做好防御。3.5 兜底失败FAILEDFAILED503900U是所有无法归类的失败的兜底值。典型产生路径adxl_utils.cc 第 35、62 行错误码转换映射表中找不到对应项时统一返回FAILEDadxl_inner_engine.cc 第 284、382、430 行内存池分配失败、segment table 为空、未知传输分支等内部错误。3.6 资源耗尽RESOURCE_EXHAUSTED虽然待废弃文档的错误码表未列出但源码 adxl_types.h 第 46 行 定义了RESOURCE_EXHAUSTED 203900U且 adxl_utils.cc 第 82-85 行 的NeedErrorLog函数将其视为“仅告警、不刷错误日志”的状态adxl_utils.cc 第 87-99 行 的IsLinkFatal也将其判定为非链路致命错误。异步传输资源不足时如TransferAsync返回RESOURCE_EXHAUSTED业务侧可以等待资源释放后重试。四、错误码的底层映射机制ADXL 作为上层库需要把底层 Hccl、ACL Runtime、LLM DataDist 的错误码“翻译”成自己的Status。翻译逻辑集中在 src/llm_datadist/adxl/adxl_utils.cc这是理解错误码数值对应关系的核心证据Status ConvertCommErrorToAdxlStatus(HcclResult ret) { static const std::mapHcclResult, Status hccl2adxl { {HCCL_SUCCESS, SUCCESS}, {HCCL_E_PARA, PARAM_INVALID}, {HCCL_E_TIMEOUT, TIMEOUT}, {HCCL_E_NOT_SUPPORT, UNSUPPORTED}, }; ... return FAILED; // 未命中映射表时兜底 } Status AclError2AdxlStatus(aclError ret) { static const std::mapaclError, Status acl2adxl { {ACL_ERROR_NONE, SUCCESS}, {ACL_ERROR_RT_STREAM_SYNC_TIMEOUT, TIMEOUT}, }; ... return static_castStatus(ret); // 其余原样透传 } Status LLMError2AdxlStatus(ge::Status ret) { static const std::mapge::Status, Status llm2adxl { {llm_datadist::LLM_SUCCESS, SUCCESS}, {llm_datadist::LLM_PARAM_INVALID, PARAM_INVALID}, {llm_datadist::LLM_TIMEOUT, TIMEOUT}, {llm_datadist::LLM_NOT_YET_LINK, NOT_CONNECTED}, {llm_datadist::LLM_ALREADY_LINK, ALREADY_CONNECTED}, }; ... return FAILED; }从中可以提炼三个实用结论错误语义在多层间保持对齐LLM DataDist 的“未建链/已建链”错误LLM_NOT_YET_LINK、LLM_ALREADY_LINK会映射为 ADXL 的NOT_CONNECTED、ALREADY_CONNECTED说明这两个错误码主要服务于建链状态管理无法识别的底层错误一律收敛为 FAILED由于FAILED不可恢复遇到它时往往需要去 Host/Device 日志中查找更底层的原始错误码Hccl 错误、ACL 错误等ACL 错误存在“原样透传”路径AclError2AdxlStatus对未命中映射表的aclError直接以static_castStatus(ret)返回因此返回值为非表内数值时可对照 ACL Runtime 错误码定义进一步定位。五、错误码的日志与分类辅助函数仓库还提供了两个与错误码配合使用的辅助函数adxl_utils.cc有助于理解错误的严重度分级bool NeedErrorLog(Status status) { std::setStatus warnning_status {RESOURCE_EXHAUSTED}; return !warnning_status.count(status); } bool IsLinkFatal(Status status) { switch (status) { case SUCCESS: case PARAM_INVALID: case NOT_CONNECTED: case ALREADY_CONNECTED: case UNSUPPORTED: case RESOURCE_EXHAUSTED: return false; default: return true; } }NeedErrorLog除RESOURCE_EXHAUSTED外的错误都会记录错误日志即资源耗尽被当作“可告警但非致命”的状态IsLinkFatalPARAM_INVALID、NOT_CONNECTED、ALREADY_CONNECTED、UNSUPPORTED、RESOURCE_EXHAUSTED均不视为链路致命只有TIMEOUT、FAILED等未列出状态被视为链路致命——这与文档表格中“是否可恢复”的判定完全吻合可作为错误分级的源码级佐证。六、常见接口返回值与错误码对照为了便于实战查阅下表汇总了待废弃 ADXL 主要接口的返回码组合依据 docs/zh/api/cpp/deprecated_ADXL-interface.md 中的“返回值”章节整理| 接口 | 可能返回的错误码 | 说明 | |--|--|--| | Initialize | SUCCESS / PARAM_INVALID / 其他 | 参数错误时返回 PARAM_INVALID | | Connect | SUCCESS / PARAM_INVALID / TIMEOUT / ALREADY_CONNECTED / 其他 | 重复建链返回 ALREADY_CONNECTED超时返回 TIMEOUT | | Disconnect | SUCCESS / PARAM_INVALID / NOT_CONNECTED / 其他 | 未建链时返回 NOT_CONNECTED | | TransferSync | SUCCESS / PARAM_INVALID / NOT_CONNECTED / TIMEOUT / 其他 | 未建链或传输超时分别返回对应码 | | TransferAsync | SUCCESS / PARAM_INVALID / NOT_CONNECTED / RESOURCE_EXHAUSTED / 其他 | 资源不足返回 RESOURCE_EXHAUSTED源码已定义并可能返回 | | GetTransferStatus | SUCCESS / FAILED / NOT_CONNECTED / 其他 | req 非法或传输失败返回 FAILED | | SendNotify / GetNotifies | SUCCESS / 其他 | 未建链等场景返回其他错误 | | RegisterMem / DeregisterMem | SUCCESS / PARAM_INVALID / 其他 | 参数错误返回 PARAM_INVALID | | MallocMem / FreeMem | SUCCESS / 其他 | — | | ExportToShareableHandle | SUCCESS / PARAM_INVALID / 其他 | addr 为空、非 MallocMem 地址或内存已释放时返回 PARAM_INVALID | | GetCapability | SUCCESS / PARAM_INVALID | feature_type 为负数时返回 PARAM_INVALID |从上表可以看到PARAM_INVALID几乎是所有带参接口的统一参数校验出口NOT_CONNECTED集中在建链与传输类接口TIMEOUT主要出现在建链与同步传输场景。七、排障实践建议结合错误码语义、可恢复性与源码实现给出如下排障流程先判断错误类别可恢复PARAM_INVALID、NOT_CONNECTED、ALREADY_CONNECTED、UNSUPPORTED修正参数或调整建链流程后重试不可恢复TIMEOUT、FAILED不要盲目重试进入现场保留流程。保留现场并收集日志对于 TIMEOUT、FAILED按照文档要求“保留现场获取 Host/Device 日志并备份”同时留意日志中的原始底层错误码Hccl / ACL 错误因为FAILED是底层错误映射失败后的兜底值。建链类错误先查链路NOT_CONNECTED / ALREADY_CONNECTED 出现时优先检查Connect的调用时机、remote_engine标识是否与对端一致、Server 端是否正常监听容器场景还需确认hccn_tool可访问详见 deprecated_ADXL-interface.md 的 Connect 约束说明。超时类错误检查配置与网络Connect建议超时配置在 200ms 以上TLS 开启时建议 2000ms 以上同步传输超时时间默认为 1000ms可通过接口的timeout_in_millis参数调整。资源耗尽按需重试收到 RESOURCE_EXHAUSTED 时等待资源如中转 buffer 池、异步请求槽位释放后可重试该错误不会污染链路状态。八、相关文档索引错误码本文档docs/zh/api/cpp/deprecated_ADXL-error-code.md接口定义与约束docs/zh/api/cpp/deprecated_ADXL-interface.md数据结构定义docs/zh/api/cpp/deprecated_ADXL-data-structure.md错误码头文件权威数值来源include/adxl/adxl_types.h错误码映射与辅助函数src/llm_datadist/adxl/adxl_utils.cc参数校验宏src/llm_datadist/adxl/adxl_checker.h引擎内部错误码使用src/llm_datadist/adxl/adxl_inner_engine.cc中转传输超时与校验src/llm_datadist/adxl/buffer_transfer_service.ccLLM DataDist 错误码定义映射来源include/llm_datadist/llm_datadist.h、include/llm_datadist/llm_error_codes.h说明本文所述错误码定义与行为以当前开源仓库CANN/HIXL代码为准文档中标注“待废弃”表明该接口系列处于弃用过渡期新业务建议优先评估 HIXL 主库与 LLM DataDist 接口迁移时可参考仓库中的 deprecated_ADXL-interface.md 与 HIXL 主接口文档。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HIXL 待废弃 ADXL 错误码全解析：定义、语义、可恢复性与排障指引
HIXL 待废弃 ADXL 错误码全解析定义、语义、可恢复性与排障指引【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl导读本文面向在 CANN/HIXL 开源仓库中使用或维护待废弃 ADXLAscend Direct Xfer Library单边通信接口的开发者系统梳理docs/zh/api/cpp/deprecated_ADXL-error-code.md中定义的全部状态码先介绍其uint32_t类型与数值编码规则再逐个讲解 SUCCESS、PARAM_INVALID、TIMEOUT、NOT_CONNECTED、ALREADY_CONNECTED、NOTIFY_FAILED、UNSUPPORTED、FAILED 的含义与可恢复性并结合仓库源码include/adxl/adxl_types.h、src/llm_datadist/adxl/adxl_utils.cc 等说明这些错误码在参数校验、链路管理、传输超时等环节的产生路径与底层映射机制最后给出基于日志与现场保留的排查建议。读完本文你将能够准确解读 ADXL 接口返回值快速定位参数、建链与传输类故障。一、ADXL 错误码的总体设计ADXL 是 HIXL 仓库中即将废弃的单边通信编程模型其核心类为AdxlEngine对外接口Initialize、Connect、TransferSync、TransferAsync等统一以Status类型作为返回值。所有错误码都定义在 include/adxl/adxl_types.h 中类型为uint32_tnamespace adxl { using Status uint32_t; // status codes constexpr Status SUCCESS 0U; constexpr Status PARAM_INVALID 103900U; constexpr Status TIMEOUT 103901U; constexpr Status NOT_CONNECTED 103902U; constexpr Status ALREADY_CONNECTED 103903U; constexpr Status NOTIFY_FAILED 103904U; constexpr Status UNSUPPORTED 103905U; constexpr Status FAILED 503900U; constexpr Status RESOURCE_EXHAUSTED 203900U; } // namespace adxl从数值编码可以看出如下规律可在 adxl_types.h 第 37-46 行 核对0U成功码唯一的非错误返回值103900U ~ 103905U一类错误码覆盖参数、超时、建链、通知、能力不支持等可预期的业务错误203900URESOURCE_EXHAUSTED资源耗尽类错误虽未出现在待废弃文档的错误码表中但仓库源码中已实际定义并使用见下文“源码中的实际使用”一节503900UFAILED通用失败码用于兜底所有未单独归类的情况。Status同时被 HIXL 主库hixl命名空间与 LLM DataDist 模块复用为统一的返回值类型理解 ADXL 错误码有助于顺带理解仓库内其他模块的返回语义。二、错误码含义速查表待废弃文档给出了完整的错误码语义对照下表完整继承并补充了“产生场景”说明基于仓库源码归纳| 枚举值 | 数值 | 含义 | 是否可恢复 | 解决办法 | |--|--|--|--|--| | SUCCESS | 0U | 成功 | 无 | 不涉及。 | | PARAM_INVALID | 103900U | 参数错误 | 是 | 基于日志排查错误原因。 | | TIMEOUT | 103901U | 处理超时 | 否 | 保留现场获取 Host/Device 日志并备份。 | | NOT_CONNECTED | 103902U | 没有建链 | 是 | 上层排查建链情况。 | | ALREADY_CONNECTED | 103903U | 已经建链重复建链 | 是 | 上层排查建链情况。 | | NOTIFY_FAILED | 103904U | 通知失败 | 否 | 预留错误码暂不会返回。 | | UNSUPPORTED | 103905U | 不支持的参数或接口 | 是 | 预留错误码暂不会返回。 | | FAILED | 503900U | 通用失败 | 否 | 保留现场获取 Host/Device 日志并备份。 |关键结论PARAM_INVALID、NOT_CONNECTED、ALREADY_CONNECTED、UNSUPPORTED 属于可恢复错误业务侧在修正参数或完成建链后可以重试TIMEOUT 与 FAILED 属于不可恢复错误出现后不建议直接重试同一操作而应保留现场、收集日志后按故障流程处理NOTIFY_FAILED 与 UNSUPPORTED 在当前版本为预留错误码文档明确说明“暂不会返回”业务代码可以按防御式编程处理但不应依赖其触发路径。三、错误码的产生路径源码级剖析错误码并非凭空定义下面结合仓库源码说明各错误码在真实调用链中是如何被抛出与返回的。3.1 参数校验PARAM_INVALID 的主要来源PARAM_INVALID是出现频率最高的错误码之一绝大多数由参数校验宏产生。仓库中的校验宏定义在 src/llm_datadist/adxl/adxl_checker.h// Check if the parameter is null. If yes, return PARAM_INVALID and record the error #define ADXL_CHK_NULL_RET_STATUS(val, ...) ... // Check if the parameter is valid. If not, return PARAM_INVALID and record the error #define ADXL_CHK_BOOL_RET_STATUS(expr, status, ...) ...典型使用场景见 src/llm_datadist/adxl/adxl_inner_engine.cc例如中转内存池配置解析失败、buffer 数量/大小非法第 228-245 行OPTION_AUTO_CONNECT取值不为 0 或 1第 141-146 行传输类型非法第 469 行查询一个不存在的异步请求句柄第 560-561 行。在 src/llm_datadist/adxl/buffer_transfer_service.cc 中中转传输服务还会对 buffer 长度总和、地址溢出ge::AddOverflow、切片数量等进行校验失败同样返回PARAM_INVALID。3.2 建链状态NOT_CONNECTED 与 ALREADY_CONNECTED这两个错误码对应链路管理。在 adxl_inner_engine.cc 中执行TransferSync、TransferAsync、GetTransferStatus等接口时若通过remote_engine查询不到对应 channel即返回NOT_CONNECTED见第 490、525、566-571、603 行等建链阶段若发现重复建链则返回ALREADY_CONNECTED对应Connect接口返回语义。这与文档中“NOT_CONNECTED没有建链上层排查建链情况ALREADY_CONNECTED已经建链上层排查建链情况”的描述完全一致这两个错误码本质是引导业务层检查自身建链流程属于可恢复错误。3.3 超时TIMEOUT 的触发场景TIMEOUT并非只在传输阶段出现建链Connect默认超时 1000ms、断链、传输、异步传输等待见 adxl_inner_engine.cc 第 621 行都可能因超时返回。在 buffer_transfer_service.cc 中大量time_cost timeout的判断第 106、112、131、150、167、209、248、267 行等表明中转传输的每一步取 buffer、等待对端、拷贝完成都有独立超时控制任一环节超时即返回TIMEOUT。由于文档将TIMEOUT标记为不可恢复处理建议是不要盲目重试先确认网络质量、对端负载与配置的超时值是否合理。3.4 预留错误码NOTIFY_FAILED 与 UNSUPPORTEDNOTIFY_FAILED103904U文档明确“预留错误码暂不会返回”当前仓库源码中未见其实际返回路径UNSUPPORTED103905U同样为预留错误码但在 buffer_transfer_service.cc 第 522、560 行 可见其潜在使用逻辑当底层批量拷贝接口返回“特性不支持”如ACL_ERROR_RT_FEATURE_NOT_SUPPORT时会向上转换为UNSUPPORTED。也就是说该错误码在特定型号/特性组合下有被触发的可能业务侧可提前做好防御。3.5 兜底失败FAILEDFAILED503900U是所有无法归类的失败的兜底值。典型产生路径adxl_utils.cc 第 35、62 行错误码转换映射表中找不到对应项时统一返回FAILEDadxl_inner_engine.cc 第 284、382、430 行内存池分配失败、segment table 为空、未知传输分支等内部错误。3.6 资源耗尽RESOURCE_EXHAUSTED虽然待废弃文档的错误码表未列出但源码 adxl_types.h 第 46 行 定义了RESOURCE_EXHAUSTED 203900U且 adxl_utils.cc 第 82-85 行 的NeedErrorLog函数将其视为“仅告警、不刷错误日志”的状态adxl_utils.cc 第 87-99 行 的IsLinkFatal也将其判定为非链路致命错误。异步传输资源不足时如TransferAsync返回RESOURCE_EXHAUSTED业务侧可以等待资源释放后重试。四、错误码的底层映射机制ADXL 作为上层库需要把底层 Hccl、ACL Runtime、LLM DataDist 的错误码“翻译”成自己的Status。翻译逻辑集中在 src/llm_datadist/adxl/adxl_utils.cc这是理解错误码数值对应关系的核心证据Status ConvertCommErrorToAdxlStatus(HcclResult ret) { static const std::mapHcclResult, Status hccl2adxl { {HCCL_SUCCESS, SUCCESS}, {HCCL_E_PARA, PARAM_INVALID}, {HCCL_E_TIMEOUT, TIMEOUT}, {HCCL_E_NOT_SUPPORT, UNSUPPORTED}, }; ... return FAILED; // 未命中映射表时兜底 } Status AclError2AdxlStatus(aclError ret) { static const std::mapaclError, Status acl2adxl { {ACL_ERROR_NONE, SUCCESS}, {ACL_ERROR_RT_STREAM_SYNC_TIMEOUT, TIMEOUT}, }; ... return static_castStatus(ret); // 其余原样透传 } Status LLMError2AdxlStatus(ge::Status ret) { static const std::mapge::Status, Status llm2adxl { {llm_datadist::LLM_SUCCESS, SUCCESS}, {llm_datadist::LLM_PARAM_INVALID, PARAM_INVALID}, {llm_datadist::LLM_TIMEOUT, TIMEOUT}, {llm_datadist::LLM_NOT_YET_LINK, NOT_CONNECTED}, {llm_datadist::LLM_ALREADY_LINK, ALREADY_CONNECTED}, }; ... return FAILED; }从中可以提炼三个实用结论错误语义在多层间保持对齐LLM DataDist 的“未建链/已建链”错误LLM_NOT_YET_LINK、LLM_ALREADY_LINK会映射为 ADXL 的NOT_CONNECTED、ALREADY_CONNECTED说明这两个错误码主要服务于建链状态管理无法识别的底层错误一律收敛为 FAILED由于FAILED不可恢复遇到它时往往需要去 Host/Device 日志中查找更底层的原始错误码Hccl 错误、ACL 错误等ACL 错误存在“原样透传”路径AclError2AdxlStatus对未命中映射表的aclError直接以static_castStatus(ret)返回因此返回值为非表内数值时可对照 ACL Runtime 错误码定义进一步定位。五、错误码的日志与分类辅助函数仓库还提供了两个与错误码配合使用的辅助函数adxl_utils.cc有助于理解错误的严重度分级bool NeedErrorLog(Status status) { std::setStatus warnning_status {RESOURCE_EXHAUSTED}; return !warnning_status.count(status); } bool IsLinkFatal(Status status) { switch (status) { case SUCCESS: case PARAM_INVALID: case NOT_CONNECTED: case ALREADY_CONNECTED: case UNSUPPORTED: case RESOURCE_EXHAUSTED: return false; default: return true; } }NeedErrorLog除RESOURCE_EXHAUSTED外的错误都会记录错误日志即资源耗尽被当作“可告警但非致命”的状态IsLinkFatalPARAM_INVALID、NOT_CONNECTED、ALREADY_CONNECTED、UNSUPPORTED、RESOURCE_EXHAUSTED均不视为链路致命只有TIMEOUT、FAILED等未列出状态被视为链路致命——这与文档表格中“是否可恢复”的判定完全吻合可作为错误分级的源码级佐证。六、常见接口返回值与错误码对照为了便于实战查阅下表汇总了待废弃 ADXL 主要接口的返回码组合依据 docs/zh/api/cpp/deprecated_ADXL-interface.md 中的“返回值”章节整理| 接口 | 可能返回的错误码 | 说明 | |--|--|--| | Initialize | SUCCESS / PARAM_INVALID / 其他 | 参数错误时返回 PARAM_INVALID | | Connect | SUCCESS / PARAM_INVALID / TIMEOUT / ALREADY_CONNECTED / 其他 | 重复建链返回 ALREADY_CONNECTED超时返回 TIMEOUT | | Disconnect | SUCCESS / PARAM_INVALID / NOT_CONNECTED / 其他 | 未建链时返回 NOT_CONNECTED | | TransferSync | SUCCESS / PARAM_INVALID / NOT_CONNECTED / TIMEOUT / 其他 | 未建链或传输超时分别返回对应码 | | TransferAsync | SUCCESS / PARAM_INVALID / NOT_CONNECTED / RESOURCE_EXHAUSTED / 其他 | 资源不足返回 RESOURCE_EXHAUSTED源码已定义并可能返回 | | GetTransferStatus | SUCCESS / FAILED / NOT_CONNECTED / 其他 | req 非法或传输失败返回 FAILED | | SendNotify / GetNotifies | SUCCESS / 其他 | 未建链等场景返回其他错误 | | RegisterMem / DeregisterMem | SUCCESS / PARAM_INVALID / 其他 | 参数错误返回 PARAM_INVALID | | MallocMem / FreeMem | SUCCESS / 其他 | — | | ExportToShareableHandle | SUCCESS / PARAM_INVALID / 其他 | addr 为空、非 MallocMem 地址或内存已释放时返回 PARAM_INVALID | | GetCapability | SUCCESS / PARAM_INVALID | feature_type 为负数时返回 PARAM_INVALID |从上表可以看到PARAM_INVALID几乎是所有带参接口的统一参数校验出口NOT_CONNECTED集中在建链与传输类接口TIMEOUT主要出现在建链与同步传输场景。七、排障实践建议结合错误码语义、可恢复性与源码实现给出如下排障流程先判断错误类别可恢复PARAM_INVALID、NOT_CONNECTED、ALREADY_CONNECTED、UNSUPPORTED修正参数或调整建链流程后重试不可恢复TIMEOUT、FAILED不要盲目重试进入现场保留流程。保留现场并收集日志对于 TIMEOUT、FAILED按照文档要求“保留现场获取 Host/Device 日志并备份”同时留意日志中的原始底层错误码Hccl / ACL 错误因为FAILED是底层错误映射失败后的兜底值。建链类错误先查链路NOT_CONNECTED / ALREADY_CONNECTED 出现时优先检查Connect的调用时机、remote_engine标识是否与对端一致、Server 端是否正常监听容器场景还需确认hccn_tool可访问详见 deprecated_ADXL-interface.md 的 Connect 约束说明。超时类错误检查配置与网络Connect建议超时配置在 200ms 以上TLS 开启时建议 2000ms 以上同步传输超时时间默认为 1000ms可通过接口的timeout_in_millis参数调整。资源耗尽按需重试收到 RESOURCE_EXHAUSTED 时等待资源如中转 buffer 池、异步请求槽位释放后可重试该错误不会污染链路状态。八、相关文档索引错误码本文档docs/zh/api/cpp/deprecated_ADXL-error-code.md接口定义与约束docs/zh/api/cpp/deprecated_ADXL-interface.md数据结构定义docs/zh/api/cpp/deprecated_ADXL-data-structure.md错误码头文件权威数值来源include/adxl/adxl_types.h错误码映射与辅助函数src/llm_datadist/adxl/adxl_utils.cc参数校验宏src/llm_datadist/adxl/adxl_checker.h引擎内部错误码使用src/llm_datadist/adxl/adxl_inner_engine.cc中转传输超时与校验src/llm_datadist/adxl/buffer_transfer_service.ccLLM DataDist 错误码定义映射来源include/llm_datadist/llm_datadist.h、include/llm_datadist/llm_error_codes.h说明本文所述错误码定义与行为以当前开源仓库CANN/HIXL代码为准文档中标注“待废弃”表明该接口系列处于弃用过渡期新业务建议优先评估 HIXL 主库与 LLM DataDist 接口迁移时可参考仓库中的 deprecated_ADXL-interface.md 与 HIXL 主接口文档。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
