diff options
| -rw-r--r-- | docs/07-developers/onboarding-and-standards.md | 50 |
1 files changed, 48 insertions, 2 deletions
diff --git a/docs/07-developers/onboarding-and-standards.md b/docs/07-developers/onboarding-and-standards.md index ef6388e..ee4c2b9 100644 --- a/docs/07-developers/onboarding-and-standards.md +++ b/docs/07-developers/onboarding-and-standards.md @@ -123,9 +123,27 @@ The following rules each come from a real bug and are enforced in review: ### 3.2 Userspace and tools (`userspace/`, `tools/`, `scripts/`) -* C: same style as the kernel module where practical. +* **C: 4-space indentation, ~100 columns** — deliberately *not* the kernel + style. This is the style the existing sources use (`libvgpu.c`, + `rpc_emulator.c`, the test binaries); the per-area configs are + `userspace/.clang-format` and `tools/.clang-format` (LLVM base). Do not + mass-reformat existing files; the config governs new code and hunks you + are already editing. +* C naming and structure: `snake_case` functions and structs + (`gsp_alloc_args`, `rpc_emu_bar_config`), types as `*_t` + (`vgpu_error_t`), `_LIBVGPU_H_`-style include guards, and prototypes in + the matching header with `extern "C"` for the public API. +* C error handling: return the library's status type (`vgpu_error_t`), not + raw `errno`; translate at the syscall boundary (`map_errno`), check every + allocation and return value, and fail closed. No `abort()`/`exit()` in + library code — the caller owns the error. +* Every C/Python/shell source file starts with + `SPDX-License-Identifier: BSD-3-Clause` plus a one-line copyright; + kernel sources use `GPL-2.0` instead. Per-file identifiers govern (see + [`../README.md`](../README.md) §7). * Python/shell: `shellcheck` clean shell, `python3` with no exotic - dependencies; scripts must be re-runnable and idempotent. + dependencies; scripts must be re-runnable and idempotent. Shell scripts + start with `set -e`; operational scripts use the full `set -euo pipefail`. * Tools must live **in-tree** (never in `/tmp`) so they survive reboots and are reviewable. @@ -145,6 +163,34 @@ The following rules each come from a real bug and are enforced in review: offset are 0x100000 too low (the wrong functions) — re-derive any conclusion drawn from them. +### 3.4 Tracked conventions (de facto) + +These are the practices review already expects; they are written down so new +contributors do not have to infer them. + +* **Commit messages**: `<subsystem>: <description>` — an imperative, + lower-case subsystem token (`vgsp`, `vgsp-rm`, `sema`, `guest-diag`, + `scripts`, `tools`, `debug/issue`), then what changed. Cite issues inline + as `(ISSUE-0001)`; the register is + [`../../debug/issue/README.md`](../../debug/issue/README.md). Commit + messages are public: describe behaviour and evidence (same rule as tracked + docs). +* **Document status and change markers**: long-lived deep-dive documents open + with a `> Status: ...` preamble under the H1 and append a + `<!-- change (YYYY-MM-DD): ... -->` comment recording substantive edits — + see + [`../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md`](../../debug/risc-v-gsp-rm-vm/docs/00-OVERVIEW.md). +* **Config and firmware layout**: `config/hardware/` holds per-architecture + profiles and `config/versions/` per-driver-version profiles — portability + work is a config change before it is a code change. A versioned firmware + tree is `firmware/<SERIES>-GSP/<MAJOR.MINOR>/` (images fetched by + `install.sh`; analysis artifacts tracked). See + [`../06-portability/hardware-software-matrix.md`](../06-portability/hardware-software-matrix.md). +* **SPDX enforcement point**: the per-file `SPDX-License-Identifier` governs + a file's license regardless of its directory; every new source file must + carry one (BSD-3-Clause for userspace/tools/scripts/docs, GPL-2.0 for + `kernel/**`). + ## 4. Tooling | Tool | Purpose | |