scst/AGENTS.md

SCST Repository Guidance

Scope and context

Before editing, read applicable AGENTS.md files from the repository root to the changed files. Nested guidance adds to this file. Check 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.
• tests/ginkgo/ owns management, SCSI and fio component tests; follow its component guidance for interfaces, validation and live-host boundaries.
• 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 file records ownership, cross-component constraints, risks and where to investigate. It is not an interface specification; resolve behavior claims against the nearest current implementation.

• Current code, installed/shared headers and implementation comments define behavior. Makefiles, Kbuild/Kconfig, scripts and CI define build, generation and validation workflows.
• Use README.md and INSTALL.md for workflows. Consult README.clang, README.cross-compilation, README.module-signing, design documents and component READMEs for the relevant toolchain, architecture or component.
• Use Git history for compatibility intent. If documentation disagrees with implementation, report it and update the appropriate source when in scope; do not change behavior merely to match prose.

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

• Follow CONTRIBUTING.md for code style and commit conventions. Before handoff, inspect the final diff and run the applicable checks below from the repository root. Use the resolved base commit of the submitted series as <base>; do not silently substitute a moving branch.

  Change	Required local checks
  Any change	git diff --check <base>; inspect added files too, including files not yet tracked.
  Prepared commits	scripts/checkpatch_commits <base>; run Conform as described in CONTRIBUTING.md and review prefixes against its registry.
  Uncommitted C changes	scripts/checkpatch_diff <base>. Rerun the per-commit checks once the series is prepared.
  Shell scripts or sourced shell files	ShellCheck and syntax checks as described below.
  Python files	python3 -m py_compile <changed-files>.
  Go files	gofmt -l <changed-files> must produce no output; follow component validation guidance.

• For changed Bash files, run bash -n <file> for each file and shellcheck -x -P SCRIPTDIR <changed-files>. For POSIX shell files, use sh -n and ShellCheck's sh dialect. Check sourced files with the caller's dialect if they have no shebang. Include new files and files outside scripts/: make shellcheck currently covers only Bash scripts under scripts/ whose paths already exist in HEAD.

• Fix diagnostics introduced by the change. Report any remaining diagnostic with its location and reason; do not extend ignore lists just to pass. A missing tool or failed invocation is not a passed check. Report the checked base and HEAD, commands, results and checks not run. After editing code or commit messages, rerun the affected checks on the final version.

• 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.

• scripts/run-regression-tests provides kernel compatibility, compilation, sparse and smatch checks. It downloads or prepares kernel trees and is not part of the lightweight checks above. Static checks do not establish build or runtime correctness.

• make ginkgo-check checks the component-test framework only. Read component guidance before using its test target. Do not build merely to validate instruction-only or documentation-only changes.

• 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.