# SCST Repository Guidance ## Scope and context This file supplies repository-wide context. Before changing a file, read every `AGENTS.md` from the repository root down to that file; a nested file adds component-specific rules and does not replace this one. Start by checking `git status` and preserve unrelated tracked, untracked, ignored, and generated worktree state. SCST is a Linux SCSI target stack. The repository contains a kernel target core, device handlers, transport target drivers, configuration software, and user-space handlers and daemons. ## Architecture map - `scst/` owns the SCST core, built-in device handlers, exported kernel interfaces, kernel/user ABI headers, and in-tree Kbuild/Kconfig integration. - `iscsi-scst/` owns the iSCSI target: its SCST kernel driver, control daemon, protocol/control interfaces, and optional iSER transport. - `qla2x00t-32gbit/` is the default, newer QLogic FC target/initiator source tree for the top-level out-of-tree build; `qla2x00t/` is the alternative legacy tree selected there with `QLA_32GBIT=no`. Generated in-tree patches select a tree independently in `scripts/generate-kernel-patch`; inspect its current target-kernel condition. The trees are alternatives, not interchangeable copies. - `srpt/`, `fcst/`, and `scst_local/` own the SRP/RDMA, FCoE/libfc, and local loopback target drivers respectively. - `usr/` owns user-space SCST ABI consumers: the `scst_user` file handler, ALUA state-change daemon, and event example. - `scstadmin/` owns the configuration grammar, sysfs discovery and mutation, service integration, and configuration application policy. - `scripts/` owns source, patch, release, checkpatch, regression, and performance helpers. `doc/` contains design and ABI references; `www/` contains website material. `debian/`, spec templates, `nightly/`, and `.github/workflows/` own packaging, nightly, and CI integration. ## Cross-component contracts - `scst/include/scst.h` is the current target-driver and device-handler registration/lifecycle contract. `scst/include/scst_const.h`, `scst/include/scst_sgv.h`, `scst/include/scst_debug.h`, and `scst/include/backport.h` are shared support interfaces. `backport.h` is the common kernel-API compatibility layer used by the core and external modules; its availability checks must account for upstream releases, stable-series backports, and vendor kernels rather than only `LINUX_VERSION_CODE`. Changes require an audit of all in-tree consumers, including every target driver and device handler; do not infer callback context, command ownership, teardown ordering, or API availability from an old document. - `scst/include/scst_user.h` plus `scst/src/dev_handlers/scst_user.c` define the `/dev/scst_user` ABI consumed by `usr/fileio/`. `scst/include/scst_event.h` plus `scst/src/scst_event.c` define the event ABI consumed by `usr/events/` and `usr/stpgd/`. Update producers and consumers together and preserve explicit version checks where present. - `scst/SysfsRules`, current sysfs implementations, and the `[key]` metadata convention define the user-visible control contract. Target drivers and handlers produce it; `scstadmin` discovers and consumes it. Keep management operations generic and preserve configuration ordering, especially creating objects before attributes/LUNs and enabling a target last. - `/etc/scst.conf` is produced and consumed by `scstadmin` and service integration. iSCSI configuration additionally crosses the kernel/daemon control boundary in `iscsi-scst/`. Treat grammar, names, defaults, and emitted sysfs values as compatibility-sensitive user interfaces. - SCSI command, task-management, data-transfer, cancellation, session, and target teardown ownership crosses the core/transport boundary. Exact rules live in the current `scst.h` callback comments and each driver's receive, completion, abort, and unregister paths. - T10 protection information crosses the core, supporting device handlers, and PI-capable target drivers. Use `scst/T10-PI` to locate the concepts, then verify capabilities, data and PI scatterlists, actions, and ownership in the current `scst.h` declarations and implementations on both sides. ## Verification order and compatibility This hierarchy is a routing and safety guide, not an interface specification. Resolve a claim by inspecting the nearest current implementation first: - Current tracked code, installed/shared headers, and comments next to the implementation define actual behavior and interfaces. Executable `Makefile`, Kbuild, Kconfig, scripts, and CI definitions define actual build, generation, and validation behavior. - Use `README.md` and `INSTALL.md` for orientation and workflows, and `README.clang`, `README.cross-compilation`, `README.module-signing`, design documents, and component READMEs for rationale and special cases. Recheck every operational or interface claim against current code and recipes. - Use Git history to explain compatibility intent or an otherwise unclear boundary. If prose and implementation differ, do not change behavior merely to match prose or copy the discrepancy here; report it and update the appropriate source or document when that work is in scope. - `AGENTS.md` records ownership, coupling, risk, and where to investigate. It must not be used as evidence for a callback, field, default, command, path, kernel capability, or supported workflow without checking the referenced implementation or documentation. The top-level `Makefile` coordinates `KDIR`, `KVER`, `PASS_CC_TO_MAKE`, `PKG_BUILD_MODE`, `QLA_32GBIT`, and the component order: core, iSCSI, the selected QLA tree, SRPT, local, FCST, user programs, then `scstadmin`. Kernel builds consume `ARCH` and `CROSS_COMPILE`; programs under `usr/` use `CC` directly, and `scstadmin` uses Perl MakeMaker. Verify propagation in the current top-level and component recipes before assuming a variable applies to the whole tree. - `doc/scst_pg.sgml` and `doc/scst_user_spec.sgml` are design and ABI explanations; verify copied declarations and layouts against current headers and code. - `ABT_KERNELS` in `nightly/conf/nightly.conf` is the maintained, canonical list of supported upstream and distribution kernels. `nightly/bin/nightly` passes it to `scripts/run-regression-tests`; the GitHub Actions regression matrix is a practical subset, not the complete support list. Treat changes to `ABT_KERNELS` as support-policy changes and keep duplicated CI entries aligned where applicable. - Do not turn historical minimum-kernel claims into policy. Use the nightly list, compatibility code/conftests, build recipes, and relevant Git history to decide whether a compatibility path is still required. Preserve user-visible configuration and ABI behavior unless a deliberate compatibility change is in scope. ## Generated state Consult `.gitignore` and the producing Makefile/script before editing an unfamiliar file. Never hand-edit generated interface/version headers such as `scst/include/scst_itf_ver.h`, `scst/include/build_mode.h`, or `iscsi-scst/include/iscsi_scst_itf_ver.h`; conftest results; MakeMaker output; module-signing keys; `Module.symvers`; kernel/user objects, modules, binaries, or dependency files; packaging trees/spec output; release archives; or QLogic source-extraction and generated in-tree-patch output. Change the source or recipe and regenerate only when regeneration is part of the task. Treat `scst/src/certs/*.priv` as generated secrets: never display their contents, publish, commit, upload, or pass them to certificate-enrollment tooling; only the public certificate is an enrollment input. ## Validation - Use the narrowest real entry point from the top-level/component Makefiles. The top-level build and packaging workflows are represented by `.github/workflows/ci.yml` and `.github/workflows/coverity.yml`. - Kernel-style checks use `scripts/checkpatch`, `scripts/checkpatch_diff`, or `scripts/checkpatch_commits`. The kernel compatibility, compile, sparse, and smatch workflow is `scripts/run-regression-tests` as configured by `.github/workflows/run_regression_tests.yaml`; it is heavyweight, downloads or prepares kernel trees, and is not a quick unit test. - There is no repository-wide lightweight unit-test target. Read a local `AGENTS.md` before using a component `test` target. For instruction-only or documentation-only changes, inspect the full diff and run `git diff --check`; do not build merely to validate prose. - Never use an untracked local helper as an established project entry point. ## Safety boundaries Without explicit authorization for the exact host, devices, transports, and configuration, do not: - install or uninstall files, sign/enroll keys, run DKMS/package installation, call `depmod`, or start/stop/reload system services; - load, unload, or reload modules with `modprobe`, `insmod`, or `rmmod`; - write SCST or initiator sysfs, apply/save live configuration, or change DLM, ALUA, persistent-reservation, or HA state; - export or write a real block device or backing file, create a target, LUN, session, login, portal, or initiator connection; - change iSCSI, FC/FCoE, QLogic HBA, InfiniBand, RoCE, iWARP, or other RDMA state, including resets, LIPs, discovery, or fabric logins; - run destructive/stress/performance tests, especially scripts that write devices, create filesystems, drop caches, alter CPU policy, access remote hosts, inject faults, or exercise module/service teardown.