已合并
[virt-awaresched] docs: add AGENTS.md for VSched #232
Lumize创建于 20 天前
[virt-awaresched] docs: add AGENTS.md for VSched #232
已合并
共 1 个文件变更+137-0
| @@ -0,0 +1,137 @@ | |||
| 1 | +# AGENTS.md | ||
| 2 | + | ||
| 3 | +## Project Overview | ||
| 4 | + | ||
| 5 | +Virt-awaresched (VSched) is an openEuler virtualization scheduling service for Kunpeng CPU topologies. It collects VM and host CPU topology information, assigns vCPU threads with cluster locality in mind, and supports static and dynamic affinity modes to reduce cross-cluster access and unnecessary vCPU migration. | ||
| 6 | + | ||
| 7 | +This is a C++17/CMake project for openEuler Linux, primarily ARM64. The two shipped executables are: | ||
| 8 | + | ||
| 9 | +- `vas_daemon`: the privileged scheduling daemon. | ||
| 10 | +- `vasctl`: the administrator CLI, communicating with the daemon through `/var/run/vas/vas_uds.sock`. | ||
| 11 | + | ||
| 12 | +## Build Commands | ||
| 13 | + | ||
| 14 | +Run build commands from the repository root on openEuler/Linux. | ||
| 15 | + | ||
| 16 | +```shell | ||
| 17 | +# Release build (default) | ||
| 18 | +bash build.sh | ||
| 19 | + | ||
| 20 | +# Debug build | ||
| 21 | +bash build.sh -D | ||
| 22 | + | ||
| 23 | +# Build an RPM package | ||
| 24 | +bash build.sh package | ||
| 25 | + | ||
| 26 | +# Clean generated build state, then rebuild | ||
| 27 | +bash build.sh -c | ||
| 28 | +``` | ||
| 29 | + | ||
| 30 | +Required build dependencies include `gcc`, `gcc-c++`, `cmake`, `make`, `patch`, `libvirt-devel`, and `libboundscheck`. The build script uses the repository-local `build/` directory; executables are generated under `build/bin/`, and RPM output is copied to `output/`. | ||
| 31 | + | ||
| 32 | +## Test Commands | ||
| 33 | + | ||
| 34 | +```shell | ||
| 35 | +# Build and run all unit tests | ||
| 36 | +bash build.sh test | ||
| 37 | + | ||
| 38 | +# Run a test suite | ||
| 39 | +bash build.sh test -- --gtest_filter="TestClusterSched.*" | ||
| 40 | + | ||
| 41 | +# Run one test case | ||
| 42 | +bash build.sh test -- --gtest_filter="TestClusterSched.testUpdateDomainInfo1" | ||
| 43 | + | ||
| 44 | +# Run unit tests and generate coverage data | ||
| 45 | +bash build.sh test -C | ||
| 46 | +``` | ||
| 47 | + | ||
| 48 | +Unit tests use GoogleTest and MockCpp. Add tests under the matching module in `test/` and register new test areas through the relevant `CMakeLists.txt`. Prefer the narrowest relevant filter while iterating, then run the full unit-test command before handoff. | ||
| 49 | + | ||
| 50 | +## Code Style | ||
| 51 | + | ||
| 52 | +- Use C++17 and the repository's `.clang-format` configuration. | ||
| 53 | +- The formatting baseline is Google style with 4-space indentation, right-aligned pointers, and a 120-column limit. | ||
| 54 | +- Match existing naming, error-return, logging, and ownership patterns in the surrounding module. | ||
| 55 | +- Use the project logger from `src/log`; do not introduce ad hoc standard-output logging in daemon code. | ||
| 56 | +- Define shared error codes in `src/include/error.h` and keep public APIs documented with Doxygen-style comments. | ||
| 57 | +- Keep changes scoped. Do not mix scheduling behavior changes with unrelated cleanup. | ||
| 58 | + | ||
| 59 | +## Development Environment Tips | ||
| 60 | + | ||
| 61 | +- Linux/openEuler is the authoritative build and runtime environment. Windows inspection can validate text and diffs, but it cannot validate libvirt, cgroups, `/sys`, `/proc`, RPM packaging, or daemon behavior. | ||
| 62 | +- CMake exports `compile_commands.json` in `build/`; point the C++ language server at that build directory. | ||
| 63 | +- The daemon expects `qemu:///system`, the cpuset cgroup hierarchy, CPU/NUMA topology under `/sys`, and process information under `/proc`. | ||
| 64 | +- Dynamic affinity additionally requires the target kernel's tidal-affinity support, `dynamic_affinity=enable` in `/proc/cmdline`, `cpuset.preferred_cpus`, and access to `/proc/sys/kernel/sched_util_low_pct`. | ||
| 65 | +- Do not assume documentation alone proves kernel behavior; validate dynamic-affinity changes against the target openEuler kernel and a representative VM workload. | ||
| 66 | +- Preserve the exact cgroup path semantics and distinguish static writes to `cpuset.cpus` from dynamic writes to both `cpuset.cpus` and `cpuset.preferred_cpus`. | ||
| 67 | + | ||
| 68 | +## Architecture | ||
| 69 | + | ||
| 70 | +```text | ||
| 71 | +src/ | ||
| 72 | +|-- cli/ # Command parsing, serialization, and UDS client/server support | ||
| 73 | +|-- include/ # Shared definitions and error codes | ||
| 74 | +|-- log/ # Project logging | ||
| 75 | +|-- util/ # Common helpers | ||
| 76 | +|-- vasctl/ # Administrator CLI and command registration | ||
| 77 | +`-- vasd/ # Scheduling daemon | ||
| 78 | + |-- acquire/ # CPU topology, /proc data, libvirt VM data, VM events | ||
| 79 | + |-- api/ # Daemon command handlers | ||
| 80 | + |-- arg_parse/ # Daemon options and dynamic-affinity environment checks | ||
| 81 | + |-- cluster_sched/ # Allocation, compaction, reassignment, and cgroup binding | ||
| 82 | + |-- conf/ # Runtime configuration | ||
| 83 | + |-- looper/ # Main event/periodic scheduling loop | ||
| 84 | + `-- security/ # Privilege and security checks | ||
| 85 | + | ||
| 86 | +test/ | ||
| 87 | +|-- cli/ # CLI-related unit tests | ||
| 88 | +|-- log/ # Logging unit tests | ||
| 89 | +|-- util/ # Utility unit tests | ||
| 90 | +`-- vasd/ # Daemon module unit tests | ||
| 91 | +``` | ||
| 92 | + | ||
| 93 | +The main runtime flow is: | ||
| 94 | + | ||
| 95 | +```text | ||
| 96 | +vas_daemon startup | ||
| 97 | + -> initialize logging, privileges, arguments, libvirt, and CPU topology | ||
| 98 | + -> collect VM/vCPU state and listen for libvirt lifecycle events | ||
| 99 | + -> ClusterSched selects NUMA/cluster-local CPU assignments | ||
| 100 | + -> write assignments to VM vCPU cgroup files | ||
| 101 | + -> handle vasctl commands over the Unix domain socket | ||
| 102 | + -> periodically compact or reschedule allocations | ||
| 103 | +``` | ||
| 104 | + | ||
| 105 | +Use `docs/design/ARCHITECTURE.md`, `docs/config/CONFIG.md`, `docs/cli/`, and `docs/test/TEST.md` for feature-specific details. When documentation and implementation differ, treat the current source and CMake wiring as authoritative and call out the mismatch. | ||
| 106 | + | ||
| 107 | +## Security Guidelines | ||
| 108 | + | ||
| 109 | +**Prohibited:** | ||
| 110 | + | ||
| 111 | +1. Do not commit passwords, tokens, private keys, certificates, personal data, or credential-bearing connection strings. | ||
| 112 | +2. Do not hard-code credentials or environment-specific secrets. | ||
| 113 | +3. Do not weaken TLS, authentication, authorization, privilege, path, or input validation checks. | ||
| 114 | +4. Do not log credentials, sensitive VM data, or other secrets. | ||
| 115 | +5. Do not broaden daemon or installed-file permissions without an explicit security review. | ||
| 116 | + | ||
| 117 | +**Required:** | ||
| 118 | + | ||
| 119 | +- Validate external input and preserve bounds-checked operations. | ||
| 120 | +- Keep the UDS and installed-file permission model least-privileged. | ||
| 121 | +- Treat changes touching root execution, libvirt, cgroups, `/proc`, `/sys`, command parsing, or package installation as security-sensitive. | ||
| 122 | +- Never replace runtime paths with developer-machine-specific absolute paths. | ||
| 123 | + | ||
| 124 | +## Validation and Handoff | ||
| 125 | + | ||
| 126 | +- For source changes, run `bash build.sh` and `bash build.sh test` on openEuler/Linux. | ||
| 127 | +- For focused test changes, record the exact GoogleTest filter used and still run the full suite before handoff when the environment permits. | ||
| 128 | +- For packaging changes, run `bash build.sh package`, inspect the generated RPM, and verify its digest and file list. | ||
| 129 | +- For scheduling or affinity changes, supplement unit tests with runtime checks against libvirt, the target cgroup layout, and representative `/sys` and `/proc` state. | ||
| 130 | +- If validation is limited to Windows or static inspection, state that boundary explicitly; do not describe the change as runtime-verified. | ||
| 131 | + | ||
| 132 | +## Commit Guidelines | ||
| 133 | + | ||
| 134 | +- Follow Conventional Commits: `<type>(<scope>): <subject>`. | ||
| 135 | +- Typical types are `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, and `perf`. | ||
| 136 | +- Keep each commit focused and include tests or documentation when behavior or interfaces change. | ||
| 137 | +- Before committing, format changed C/C++ files with `clang-format`, run the applicable build/tests, and confirm no sensitive or generated files are staged. | ||