scst/AGENTS.md

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.