企业官网建设流程全解析

Context 模块架构

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

1. 模块概述

• 功能介绍：Context 模块负责维护 Runtime 的执行上下文，是连接 Device、Stream、Task、Model 和 Module 的核心对象。上层 ACL/Runtime API 进入 Runtime 后，依赖当前线程绑定的 Context 找到对应设备、默认流、用户流、模型资源、模块缓存、系统参数和错误状态。
• 设计目标：
  • 支持rtSetDevice/aclrtSetDevice隐式创建和复用 Primary Context。
  • 支持rtCtxCreate/aclrtCreateContext显式创建用户 Context。
  • 通过线程局部变量维护当前线程的 Context 绑定关系。
  • 统一承载 Context 下属的 Stream、Model、Module、系统参数和错误状态。
  • 通过全局有效集合和 RAII 保护降低 Context handle 误用和并发销毁风险。
  • 为 ACL Graph、FFTS Plus、XPU、Snapshot、runtime_compact 等能力提供扩展入口。

Context 在 Runtime 中主要有三类形态：

2. 使用场景与对外接口

2.1 使用场景

• 场景一：设置设备并使用 Primary Context。

  aclrtSetDevice(0); // Runtime 内部创建或复用设备 0 的 Primary Context，并绑定到当前线程。

• 场景二：显式创建、切换和销毁用户 Context。

  aclrtContext ctx = nullptr; aclrtCreateContext(&ctx, 0); aclrtSetCurrentContext(ctx); // ... 提交任务 ... aclrtDestroyContext(ctx);

• 场景三：获取当前 Context 的默认 Stream。

  aclrtStream stream = nullptr; aclrtCtxGetCurrentDefaultStream(&stream);

• 场景四：设置当前 Context 级系统参数。

  aclrtCtxSetSysParamOpt(ACL_OPT_DETERMINISTIC, 1);

• 场景五：多线程复用同一个用户 Context。

  // 线程 A 创建 Context 后将 handle 传给线程 B。 // 线程 B 需要先调用 aclrtSetCurrentContext(ctx)，再提交该 Context 下的任务。

2.2 对外接口

ACL Context 接口定义在include/external/acl/acl_rt.h，C 符号入口位于src/acl/aclrt_c/runtime/context.c，主要实现位于src/acl/aclrt_impl/context.cpp。

Runtime Context 头文件位于pkg_inc/runtime/runtime/context.h，RTS Context 头文件位于pkg_inc/runtime/runtime/rts/rts_context.h。

Device API 与 Primary Context 生命周期直接相关。

3. 架构总览

整体设计思路

Context 模块采用“公开 API → Runtime C API → API 装饰器 → ApiImpl → Runtime / Context 核心对象”的分层设计。公开 API 不直接操作Context、Device、Stream等资源对象，而是进入Api::Instance()，经过错误处理、Profiling 记录等装饰器后到达ApiImpl。ApiImpl负责参数校验、设备保留、Context 创建销毁和线程绑定。Runtime维护 Primary Context 引用对象，ContextManage维护全局有效 Context 集合，Context本身承载执行资源。

当前 Context 的解析逻辑集中在Runtime::CurrentContext()：

1. 当前线程显式设置过用户 Context 时，优先返回InnerThreadLocalContainer::GetCurCtx()。
2. 当前线程通过rtSetDevice()绑定 Primary Context 时，返回InnerThreadLocalContainer::GetCurRef()中的 Context。
3. 两者都不存在时返回空，调用方通常返回RT_ERROR_CONTEXT_NULL或映射后的 ACL 错误码。

架构分层图

核心模块交互图

4. 详细设计

4.1 核心流程

Primary Context 创建流程

流程说明

Primary Context 是 Device 级默认执行环境，但源码中的保存维度是devId + tsId。Runtime::PrimaryContextRetain()不是只处理当前线程的 TS，而是遍历该 Device 下的 TS RefObject：每个 RefObject 先执行IncRef()，如果返回 true 表示已有 Primary Context，只增加引用并读取已有对象；如果返回 false，说明该 TS 的 Primary Context 首次创建，才会执行DeviceRetain()、new Context(dev, true)、Setup()、ContextManage::InsertContext()和RefObject::SetVal()。遍历完成后，函数按当前线程 TS 返回RT_TSC_ID或RT_TSV_ID对应的 RefObject。ApiImpl::SetDevice()再把这个 RefObject 写入线程局部变量，并清空显式用户 Context。

关键代码：

// 文件位置：src/runtime/core/src/api_impl/api_impl.cc rtError_t ApiImpl::SetDevice(const int32_t devId) { Runtime * const rt = Runtime::Instance(); RefObject<Context *> *context = rt->PrimaryContextRetain(static_cast<uint32_t>(devId)); NULL_PTR_RETURN_MSG(context, RT_ERROR_DEVICE_RETAIN); InnerThreadLocalContainer::SetCurRef(context); Context * const curCtx = context->GetVal(); CHECK_CONTEXT_VALID_WITH_RETURN(curCtx, RT_ERROR_CONTEXT_NULL); InnerThreadLocalContainer::SetCurCtx(nullptr); return RT_ERROR_NONE; }

用户 Context 创建流程

流程说明

用户 Context 有三类入口：ACL 的aclrtCreateContext()会先进入aclrtCreateContextImpl()，再调用rtCtxCreateEx(..., RT_CTX_NORMAL_MODE, deviceId)；Runtime C API 的rtCtxCreate()/rtCtxCreateEx()会先拒绝当前不支持的RT_CTX_GEN_MODE；RTS 的rtsCtxCreate()会检查 flags 范围。三类入口最终都会进入ApiImpl::ContextCreate()。ContextCreate()通过 driver 查询设备数量并校验devId，读取当前线程tsId后调用NewContext()。NewContext()retain 对应 Device，构造Context(dev, false)并执行Setup()。创建成功后，ContextCreate()将 Context 插入ContextManage，再调用ContextSetCurrent()，因此新创建的用户 Context 会成为当前线程的活跃 Context，同时清空 Primary Context 引用。

关键代码：

// 文件位置：src/runtime/core/src/api_impl/api_impl.cc rtError_t ApiImpl::ContextCreate(Context ** const inCtx, const int32_t devId) { rtError_t error = NewContext(static_cast<uint32_t>(devId), tsId, inCtx); ERROR_RETURN_MSG_INNER(error, "new context failed, drv devId=%d", devId); ContextManage::InsertContext(*inCtx); error = ContextSetCurrent(*inCtx); ERROR_RETURN_MSG_INNER(error, "Failed to set current context"); return RT_ERROR_NONE; }

Context 销毁流程

流程说明

用户 Context 销毁前会先确认 handle 仍在ContextManage有效集合中，然后拒绝销毁IsPrimary()为 true 的 Context。Primary Context 只能通过rtDeviceReset()对应路径释放。Context::TearDown()清理 Context 下的 Model、Stream 和在线 Profiling Stream；用户 Context 的默认 Stream 也在该阶段释放。Context 从有效集合移除后，如果仍被其他线程保护使用，则等最后一个ContextProtect析构时释放。

Primary Context 的释放路径在Runtime::PrimaryContextRelease()，该路径按引用计数递减，计数归零后执行回调、Context::TearDown()、ContextManage::EraseContextFromSet()和RefObject::ResetVal()。

当前 Context 获取流程

关键代码：

// 文件位置：src/runtime/core/src/runtime.cc Context *Runtime::CurrentContext() const { Context * const curCtx = InnerThreadLocalContainer::GetCurCtx(); if (curCtx != nullptr) { return curCtx; } RefObject<Context *> * const curRef = InnerThreadLocalContainer::GetCurRef(); if (curRef != nullptr) { return curRef->GetPrimaryCtxCallBackFlag() ? curRef->GetVal(false) : curRef->GetVal(); } return nullptr; }

Context 初始化流程

流程说明

Context::Setup()建立 Context 的基础执行环境。Context::Init()创建moduleAllocator_并初始化 Context 级系统参数数组。SetOverflowAddr()为浮点溢出检测分配设备侧地址，大小由OVERFLOW_ADDR_MAX_SIZE定义。Primary Context 的默认 Stream 来自 Device 的 Primary Stream；用户 Context 则通过StreamFactory::CreateStream()创建自己的默认 Stream。

Context 同步流程

流程说明

Context::Synchronize()首先确认defaultStream_存在，然后遍历streams_收集需要同步的用户 Stream。IsStreamNotSync()会跳过特定类型的 Stream；处于 capture 状态的 Stream 不能在该路径同步。收集完成后，Context 先执行任务回收，再通过CheckStatus()检查设备状态和 Context 失败状态，最后调用SyncStreamsWithTimeout()同步收集到的 Stream。

Stream、Model 和 Module 管理

4.2 核心机制详解

线程绑定机制

设计思想：当前线程只能有一个生效的 Context 来源。显式用户 Context 和 Primary Context 引用分别保存在不同 TLS 字段中，设置其中一个时会清空另一个。

// 文件位置：src/runtime/core/src/api_impl/api_impl.cc rtError_t ApiImpl::ContextSetCurrent(Context * const inCtx) { InnerThreadLocalContainer::SetCurCtx(inCtx); InnerThreadLocalContainer::SetCurRef(nullptr); (void)ThreadLocalContainer::GetOrCreateWatchDogHandle(); return RT_ERROR_NONE; }

Context handle 有效性与并发销毁保护

设计思想：Context handle 是 opaque pointer，Runtime 需要防止无效指针进入核心逻辑，也要避免一个线程销毁 Context 时另一个线程仍在使用。ContextManage保存有效 Context 集合，ContextProtect负责作用域内使用计数回落和延迟释放。

CHECK_CONTEXT_VALID_WITH_RETURN宏封装了有效性检查和ContextProtect构造。ContextManage::EraseContextFromSet()删除 Context 时，会先从集合中移除，再标记删除状态；如果使用计数不为 0，释放动作由最后一个ContextProtect完成。

Primary Context 引用计数

设计思想：Primary Context 与 Device/TS 绑定，多次设置同一 Device 时复用已有 Context。Runtime 使用priCtxs_[devId][tsId]保存RefObject<Context *>，通过引用计数控制创建和销毁。

rtsGetPrimaryCtxState()/aclrtGetPrimaryCtxState()最终进入Runtime::GetPrimaryCtxState()，该函数遍历指定 Device 下的 TS 引用对象，只要存在引用计数大于 0 的 Primary Context，就返回 active。

系统参数作用域

rtCtxSetSysParamOpt()和rtsCtxSetSysParamOpt()设置的是当前 Context 的系统参数，最终写入Context::sysParamOpt_。sysParamOpt_使用pair<bool, int64_t>保存是否已设置和值。读取未设置参数时，Context::CtxGetSysParamOpt()返回RT_ERROR_NOT_SET_SYSPARAMOPT，API 层映射为对外错误码。

// 文件位置：src/runtime/core/src/context/context.cc rtError_t Context::CtxSetSysParamOpt(const rtSysParamOpt configOpt, const int64_t configVal) { const std::unique_lock<std::mutex> mutexLock(sysParamOptLock_); sysParamOpt_[configOpt].first = true; sysParamOpt_[configOpt].second = configVal; return RT_ERROR_NONE; }

错误状态传播

Context 维护两类错误状态：lastErr_记录最近一次错误，GetContextLastErr()读取后会清零；failureError_记录失败模式下需要传播的错误。ContextManage::SetGlobalFailureErr()会按 Device ID 遍历有效 Context，设置 Context failure error、Stream 状态和 Device 状态。Context::CheckStatus()会检查设备运行状态、驱动状态、设备业务状态和 Context failure error；只有ctxMode_ == STOP_ON_FAILURE时，Context failure error 会作为返回错误继续向上传播。

Module 懒分配

Context::Init()初始化的是moduleAllocator_，真正的Module对象在Context::GetModule()首次访问对应Program时通过device_->ModuleAlloc(prog)创建，并记录到Program与 Context 的映射关系。释放时通过Context::ReleaseModule()清空 allocator 条目，并调用device_->ModuleRelease()。

4.3 特性扩展

Context 的特性扩展主要采用两种方式。

ACL Graph 扩展

ACL Graph 相关 Context 实现位于src/runtime/feature/aclgraph/context_aclgraph.cc、src/runtime/feature/aclgraph/context_standard_soc_aclgraph.cc和src/runtime/feature/aclgraph/tiny/context_tiny_stub_aclgraph.cc，主要为 Stream Capture 和 CaptureModel 提供入口。

FFTS Plus 扩展

FFTS Plus Context 实现位于src/runtime/feature/ffts/context_ffts_standard_soc.cc，tiny 平台 stub 位于src/runtime/feature/ffts/context_ffts_tiny_stub.cc。标准实现中，Context::FftsPlusTaskLaunch()从 Stream 分配TS_TASK_TYPE_FFTS_PLUS任务，初始化 FFTS Plus task，等待参数拷贝完成后通过 Device 提交任务。Stream 处于 capture 状态时，还会补充 RDMA PI value modify 任务。

XPU Context 扩展

XPU Context 定义在src/runtime/core/inc/context/xpu_context.hpp，实现位于src/runtime/feature/xpu/xpu_context.cc和src/runtime/feature/xpu/runtime_xpu_adapt.cc。XpuContext继承Context，重写Setup()、TearDown()、StreamCreate()、TearDownStream()和CheckStatus()。

Snapshot 和恢复

Context 模块通过ContextManage为 Snapshot 提供设备、Stream 和 Model 维度的信息入口。ContextManage::DeviceGetStreamlist()、DeviceGetModelList()遍历有效 Context 集合并筛选指定 Device；SnapShotProcessBackup()、SnapShotProcessRestore()调用 Model 备份恢复、ACL Graph 恢复以及驱动资源备份恢复。

runtime_compact Context

runtime_compact使用 C 结构体实现轻量 Context，代码位于src/runtime_compact/feature/inc/context.h、src/runtime_compact/feature/src/context_common.c、src/runtime_compact/feature/src/context_linux.c和src/runtime_compact/feature/src/context_liteos.c。

compact Context 保存Device *、Stream vector 和 stream lock，创建时从g_contextMemPool分配，销毁和查询时通过内存池序列号判断 handle 是否仍有效。

4.4 模块职责划分

4.5 核心数据结构

5. 关键文件索引

6. 测试覆盖

7. 设计约束与维护建议

• Primary Context 只能通过 Device 生命周期释放，用户显式销毁接口不能销毁IsPrimary()为 true 的 Context。
• 新增以Context *为入参的 API 时，应使用CHECK_CONTEXT_VALID_WITH_RETURN或等价逻辑，保证 handle 已登记且ContextProtect覆盖 API 执行区间。
• 调用ContextManage::CheckContextIsValid(ctx, true)后必须配套ContextProtect，否则 Context 使用计数不会在作用域结束时回落。
• 切换当前 Context 时需要明确处理curCtx和curRef。显式 Context 使用SetCurCtx(ctx)并清空curRef；设置 Device 使用SetCurRef(ref)并清空curCtx。
• 新增 Context 下属资源时，需要补齐Context::TearDown()、异常回收、Snapshot 备份恢复和必要的测试用例。
• 新增平台差异实现时，优先放入src/runtime/feature/或现有平台 stub 文件，避免把平台条件散落到核心 Context 主流程。
• 新增 ACL/RTS API 时，需要同步检查include/external/acl/acl_rt.h、pkg_inc/runtime/runtime/context.h、pkg_inc/runtime/runtime/rts/rts_context.h、src/runtime/api/api.hpp、src/runtime/core/src/api_impl/api_impl.cc和 profiler 装饰器。

8. 性能与可靠性关注点

• Primary Context 通过引用计数复用，避免同一 Device/TS 组合重复创建默认执行环境。
• 用户 Context 销毁先从ContextManage有效集合移除，再结合使用计数延迟释放，降低并发使用时的 UAF 风险。
• Context::Setup()区分 Primary Context 和用户 Context 的默认 Stream 来源，避免用户 Context 销毁时误删 Device 的 Primary Stream。
• Context::Synchronize()跳过无需同步的 Stream，并拒绝同步 capture 状态的 Stream，避免捕获期间破坏 Stream Capture 状态。
• Module 采用按 Program ID 懒分配模式，moduleAllocator_在 Context 初始化时创建，具体 Module 在首次GetModule()时创建。
• Context 级 sysparam 保存在sysParamOpt_中，同一进程内不同 Context 可以保存不同配置。

本模块文档基于src/runtime/core/src/context/、src/runtime/core/src/runtime.cc、src/runtime/core/src/api_impl/api_impl.cc及 Context 相关 API、feature、runtime_compact 源码整理。

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime