已合并
[ubs-virt-enpu] docs: add AGENTS.md for vcann-rt #231
chenlong360创建于 18 天前
[ubs-virt-enpu] docs: add AGENTS.md for vcann-rt #231
已合并
共 1 个文件变更+115-0
| @@ -0,0 +1,115 @@ | |||
| 1 | +# AGENTS.md | ||
| 2 | + | ||
| 3 | +## Project Overview | ||
| 4 | + | ||
| 5 | +vCANN-RT (virtual CANN Runtime) — NPU resource soft-partitioning solution within `ubs-virt-enpu`. | ||
| 6 | +C11 source code, C++14 test code. CMake project targeting openEuler Linux (ARM64). | ||
| 7 | + | ||
| 8 | +Uses Linux `LD_PRELOAD` hook mechanism to intercept Ascend CANN runtime API calls, enforcing | ||
| 9 | +compute (AI Core) and memory (HBM) resource quotas based on configured allocation policies. | ||
| 10 | + | ||
| 11 | +## Build Commands | ||
| 12 | + | ||
| 13 | +```shell | ||
| 14 | +# Prerequisites: Set environment variables | ||
| 15 | +export ASCEND_HOME_PATH=/usr/local/Ascend/ascend-toolkit/latest | ||
| 16 | +export ENPU_ASCEND_DRIVER_PATH=/usr/local/Ascend # optional, default | ||
| 17 | + | ||
| 18 | +# Release build (produces libvruntime.so + enpu-monitor in build/) | ||
| 19 | +bash make_build.sh | ||
| 20 | + | ||
| 21 | +# Clean build directory | ||
| 22 | +rm -rf build | ||
| 23 | +``` | ||
| 24 | + | ||
| 25 | +## Test Commands | ||
| 26 | + | ||
| 27 | +```shell | ||
| 28 | +# Run all UT tests (build + run + coverage report) | ||
| 29 | +bash build_ut.sh | ||
| 30 | + | ||
| 31 | +# Build only tests (without running) | ||
| 32 | +cd __build && cmake .. -DBUILD_TESTS=ON -DENABLE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug && make vnpu_test | ||
| 33 | + | ||
| 34 | +# Run specific test suite | ||
| 35 | +./__build/test/vnpu_test --gtest_filter="DeviceTest*" | ||
| 36 | + | ||
| 37 | +# Run specific test case | ||
| 38 | +./__build/test/vnpu_test --gtest_filter="MemoryTest.GuardMemory" | ||
| 39 | +``` | ||
| 40 | + | ||
| 41 | +Coverage threshold: **80% line coverage** (enforced by `coverage.sh`). | ||
| 42 | + | ||
| 43 | +## Code Style | ||
| 44 | + | ||
| 45 | +- C11 / C++14 standard | ||
| 46 | +- clang-format for formatting (Google style, 4-space indent, 120 column limit) | ||
| 47 | +- clang-tidy for static analysis | ||
| 48 | +- Comments in Chinese or English as appropriate | ||
| 49 | + | ||
| 50 | +## Dev Environment Tips | ||
| 51 | + | ||
| 52 | +- Default build type is Release; tests auto-switch to Debug for coverage | ||
| 53 | +- `ASCEND_HOME_PATH` must be set to CANN toolkit path | ||
| 54 | +- `ENPU_ASCEND_DRIVER_PATH` defaults to `/usr/local/Ascend` | ||
| 55 | +- `compile_commands.json` is in `build/` (release) or `__build/` (test) | ||
| 56 | +- Point your LSP to the correct build directory for your configuration | ||
| 57 | +- Build artifacts: `libvruntime.so` (hook library) and `enpu-monitor` (monitoring tool) | ||
| 58 | + | ||
| 59 | +## Architecture | ||
| 60 | + | ||
| 61 | +``` | ||
| 62 | +src/ | ||
| 63 | +├── ascend/ # LD_PRELOAD hooks (device, event, memory, kernel, task, graph) | ||
| 64 | +├── tools/ # enpu-monitor tool | ||
| 65 | +├── utils/ # config, dcmi_wrapper, hash_map, utils | ||
| 66 | +└── include/ # Headers | ||
| 67 | + | ||
| 68 | +test/ | ||
| 69 | +├── testcase/ # Unit tests (gtest + mockcpp) | ||
| 70 | +├── stub/ # CANN runtime & DCMI stubs | ||
| 71 | +└── res/ # Test resources | ||
| 72 | + | ||
| 73 | +scripts/ | ||
| 74 | +└── cmake/ # CMake modules (securec, gtest, mockcpp) | ||
| 75 | +``` | ||
| 76 | + | ||
| 77 | +## Security Guidelines | ||
| 78 | + | ||
| 79 | +**禁止以下行为（红线规则）：** | ||
| 80 | + | ||
| 81 | +1. **禁止提交敏感信息** | ||
| 82 | + - API 密钥、密码、Token、证书私钥 | ||
| 83 | + - 数据库连接字符串含凭证 | ||
| 84 | + - SSH 私钥、GPG 密钥 | ||
| 85 | + | ||
| 86 | +2. **禁止硬编码凭证** | ||
| 87 | + - 用户名/密码 | ||
| 88 | + - Access Key/Secret Key | ||
| 89 | + - 认证 Token | ||
| 90 | + | ||
| 91 | +3. **禁止绕过安全检查** | ||
| 92 | + - 禁用 SSL/TLS 验证 | ||
| 93 | + - 注释或删除安全相关代码 | ||
| 94 | + - 关闭认证/授权机制 | ||
| 95 | + - 绕过内存安全函数（securec.h） | ||
| 96 | + | ||
| 97 | +4. **禁止不安全日志** | ||
| 98 | + - 记录敏感数据（密码、Token、个人信息） | ||
| 99 | + - 明文记录凭证 | ||
| 100 | + | ||
| 101 | +**必须遵守：** | ||
| 102 | + | ||
| 103 | +- 使用环境变量或配置文件管理凭证（配置文件需 `.gitignore`） | ||
| 104 | +- 敏感操作需代码审查 | ||
| 105 | +- 定期轮换密钥和凭证 | ||
| 106 | +- 报告安全漏洞不公开披露 | ||
| 107 | +- 始终使用 `securec.h` 提供的安全函数 | ||
| 108 | +- 动态库和可执行文件启用安全编译选项 | ||
| 109 | + | ||
| 110 | +## Commit Guidelines | ||
| 111 | + | ||
| 112 | +- Run `bash build_ut.sh` before committing | ||
| 113 | +- Ensure coverage >= 80% | ||
| 114 | +- Ensure clang-format and clang-tidy checks pass | ||
| 115 | +- Add or update unit tests for code changes (stub new APIs in `test/stub/` as needed) | ||