diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..92c1cae8b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,164 @@ +# 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. diff --git a/fcst/AGENTS.md b/fcst/AGENTS.md new file mode 100644 index 000000000..3d602f16d --- /dev/null +++ b/fcst/AGENTS.md @@ -0,0 +1,39 @@ +# FCST + +## Ownership and interfaces + +This directory owns the SCST FCoE target built on the kernel libfc stack. +`ft_scst.c` is the SCST target-template boundary, `ft_sess.c` owns libfc local/ +remote port to SCST target/session mapping, `ft_cmd.c` and `ft_io.c` own FCP +command/data/response processing, and `fcst.h` is the private shared interface. +It depends on both SCST and libfc; it does not own generic FCoE initiator/DCB +configuration. + +`Kbuild`, `Kconfig`, and `Makefile` define the in-tree/out-of-tree build, +SCST symbol dependency, and libfc compatibility selection. Current source and +kernel headers implement the behavior; use `README` to locate operational +workflows and verify every example against them. + +## Change boundaries + +- Preserve command ownership across libfc exchanges/frames and SCST commands. + Data buffers cannot be released until their asynchronous libfc consumer is + finished; audit response, write-data, abort, timeout, and task-management + completion paths together. +- Port/session lookup and teardown use mutex, RCU, and kref lifetimes while + libfc notifications and SCST unregister callbacks interact. Re-derive exact + lock, grace-period, reference, and callback order from current code. +- SCST API or sysfs changes require the repository-wide target-driver and + `scstadmin` audits. libfc API adaptation belongs in the established build/ + compatibility boundary, not in user-visible configuration. + +## Generated files, validation, and safety + +Objects, modules, `Module.symvers`, and dependency metadata are generated. +The focused compile entry point is top-level `make fcst` or this component's +Makefile; no component unit-test target exists. + +Do not load/unload FCST or FCoE modules, configure DCB/FCoE interfaces, enable +FC ports/targets, expose LUNs, create fabric sessions, issue a LIP/reset, or +run traffic/teardown tests without authorization for the exact host, CNA, +Ethernet fabric, initiators, and storage. diff --git a/iscsi-scst/AGENTS.md b/iscsi-scst/AGENTS.md new file mode 100644 index 000000000..f29cd3d8a --- /dev/null +++ b/iscsi-scst/AGENTS.md @@ -0,0 +1,66 @@ +# iSCSI-SCST + +## Ownership and boundaries + +This directory owns the SCST iSCSI target across kernel and user space: +`kernel/` implements the target and network data path, `usr/` implements +`iscsi-scstd` and its control/configuration logic, `include/` holds their +shared control interfaces, and `kernel/isert-scst/` adds the optional iSER/RDMA +transport. It depends on the SCST core and does not own generic SCST LUN/device +semantics or the top-level `scst.conf` grammar. + +## Where to verify behavior + +- `include/iscsi_scst.h` is the shared kernel/daemon ioctl and netlink ABI. + `kernel/config.c`, `kernel/event.c`, `usr/ctldev.c`, and `usr/event.c` are + its principal producers/consumers. Preserve fixed-width layout, compat + handling, and `ISCSI_SCST_INTERFACE_VERSION` registration checks. +- `kernel/iscsi_hdr.h` and `usr/iscsi_hdr.h` express the same wire protocol in + environment-specific forms; they are not generated copies. Audit both sides + for a protocol PDU, field, digest, or byte-order change. +- `include/iscsit_transport.h` is the private kernel transport boundary used + by the base iSCSI code and iSER. Changes require auditing both + implementations. +- Verify behavior in current code, `Makefile`, Kbuild/Kconfig files, and + conftests. Use `README`, HOWTOs, and man pages to locate workflows and + compatibility intent, then recheck their commands, defaults, and interfaces + against the implementation. The daemon is part of the functioning target, + not a replaceable convenience utility. +- `usr/config.c` implements the retained `/etc/iscsi-scstd.conf` parser, and + `usr/iscsi_adm.c` implements the legacy runtime administration client. Treat + both as compatibility interfaces. New persistent configuration belongs to + `scstadmin` and `/etc/scst.conf`, whose grammar is outside this directory. + +## Coupled changes + +- Change the kernel and daemon together for control messages, target/session/ + connection parameters, authentication policy, events, or daemon-open state. + Keep the generated interface hash/version check; never edit + `include/iscsi_scst_itf_ver.h` directly. +- Sysfs attributes and `[key]` metadata are consumed by `scstadmin`; audit its + discovery, write, and configuration serialization paths when changing them. +- Command receive, write-data completion, response, abort, task management, + connection close, session unregister, and target teardown cross the SCST and + network lifecycles. Re-derive exact reference, locking, and completion order + from current kernel code and `scst/include/scst.h`. +- iSER compatibility is selected by RDMA/OFED conftests and symbols. Do not + replace feature tests with an assumed kernel-version boundary. + +## Generated files, validation, and safety + +Conftest results/build logs, the interface-version header, `.depend*`, objects, +modules, `Module.symvers`, and `usr/iscsi-scstd`/`usr/iscsi-scst-adm` are build +artifacts. Change their sources or recipes instead. + +The focused compile entry point is top-level `make iscsi` or `make -C +iscsi-scst`; it builds both user and kernel parts and may run compatibility +conftests. There is no component unit-test target; use repository CI, +checkpatch, and regression entry points as appropriate. + +Do not install or run the daemon, open portals, apply iSCSI configuration, +create targets/sessions/connections, perform discovery/login/logout, manipulate +CHAP secrets, or alter TCP, network-namespace, iSER, or RDMA state without +explicit authorization for both endpoints and the network. Legacy +`iscsi-scst-adm` account operations can expose CHAP secrets through process +arguments and shell history; do not invoke them with real credentials unless +that exposure and cleanup are explicitly accepted. diff --git a/qla2x00t-32gbit/AGENTS.md b/qla2x00t-32gbit/AGENTS.md new file mode 100644 index 000000000..4c4c85878 --- /dev/null +++ b/qla2x00t-32gbit/AGENTS.md @@ -0,0 +1,52 @@ +# Newer QLogic FC Target Tree + +## Ownership and architecture + +This is the default QLogic tree selected by the top-level out-of-tree build. +The in-tree patch generator has independent target-kernel selection logic in +`scripts/generate-kernel-patch`. This directory contains a vendor-derived +qla2xxx initiator/HBA driver, its target-mode integration, and the SCST adapter +under `qla2x00-target/`. It is maintained separately from the legacy +`qla2x00t/` tree; verify hardware-support claims in the current device table +and probe code rather than treating either README as an inventory. + +- `qla2x00-target/scst_qla2xxx.c` is the SCST target-template adapter. + `qla2x00-target/qla_tgt.c` and the root `qla_target.c` implement the QLogic + target side; `qla_target.h` is the internal initiator/target callback and + data-layout boundary. +- The remaining root qla2xxx sources own HBA probing, firmware/mailbox, fabric, + interrupt, reset, initiator, and hardware compatibility behavior. +- `Makefile`, `qla2x00-target/Makefile`, Kbuild/Kconfig files, and + `Makefile_in-tree` own out-of-tree/in-tree composition. The SCST adapter + depends on the matching qla2xxx module and `scst/src/Module.symvers`. + +## Change boundaries + +- Preserve the two-module symbol and callback boundary. When changing a + visible interface or shared data layout in `qla_target.h`, audit both halves + and the interface-magic convention documented in that header. +- SCST command receive, DMA/data transfer, response, abort/SRR/task management, + session deletion, target disable, HBA reset, and module teardown form one + asynchronous lifetime. Re-derive exact lock order, references, workqueue + ownership, cancellation, and completion-once behavior from current code and + `scst/include/scst.h`; do not summarize the state machine here. +- A shared SCST target API or sysfs change requires auditing every target + driver. A QLogic-specific fix should be evaluated for `qla2x00t/`, but must + not be copied mechanically because the two trees have different internals + and hardware scope. +- Preserve kernel/backport feature handling in current build/code; do not use + a version-only shortcut where the tree already has a feature test. + +## Generated files, validation, and safety + +Objects, modules, `Module.symvers`, dependency metadata, extracted upstream +qla2xxx trees, and generated in-tree patch sets are artifacts. Do not edit +them or run extraction/patch-generation helpers unless that regeneration is +explicitly requested. Use the top-level selected-QLogic build or this +component's Makefile for compile validation; no hardware unit-test target is +provided. + +Never load/unload this driver, bind an HBA, enable target mode, expose WWPNs or +LUNs, log into a fabric, issue a LIP/reset, flash/query firmware through active +hardware, or run teardown/error-injection tests without authorization for the +exact host, HBA ports, fabric, initiators, and backing devices. diff --git a/qla2x00t/AGENTS.md b/qla2x00t/AGENTS.md new file mode 100644 index 000000000..4caa37124 --- /dev/null +++ b/qla2x00t/AGENTS.md @@ -0,0 +1,48 @@ +# Legacy QLogic FC Target Tree + +## Ownership and architecture + +This is the legacy QLogic qla2xxx/SCST target tree selected by the top-level +out-of-tree build with `QLA_32GBIT=no`; it is not that build's default. The +in-tree patch generator has independent target-kernel selection logic in +`scripts/generate-kernel-patch`. This directory contains a patched +initiator/HBA source tree plus the SCST target addon in `qla2x00-target/`. +Treat its hardware scope and behavior as distinct from +`qla2x00t-32gbit/`. + +- `qla2x00-target/qla2x00t.c` owns the SCST target template and transport + lifecycle. `qla2x_tgt_def.h`/`qla2x_tgt.h` define the private callback and + shared-data boundary between the initiator and target halves. +- The root qla2xxx sources own HBA, firmware, fabric, interrupt, reset, and + initiator behavior. `Makefile`, `qla2x00-target/Makefile`, Kbuild/Kconfig + files, and in-tree recipes own module composition and kernel compatibility. +- Out-of-tree target mode uses matching qla2xxx and target modules plus SCST + symbols; preserve `BUILD_2X_MODULE` and `Module.symvers` assumptions. + +## Change boundaries + +- Audit both halves for callback signature, shared structure, ownership, or + module-order changes, and update the interface-magic convention documented + in `qla2x_tgt_def.h` when its visible boundary changes. Keep SCST command/ + session/target references valid across receive, DMA, response, abort/task + management, fabric logout, HBA reset, and unregister; derive exact locks and + teardown sequence from current code. +- A shared SCST API/sysfs change requires auditing all target drivers. Evaluate + QLogic-specific fixes for the newer tree too, but do not mechanically port + code between different driver generations. +- Use the README and HOWTO to locate operational concepts, but verify hardware + support in `qla2xxx_pci_tbl[]` in `qla_os.c` and NPIV behavior in the current + target-template callbacks. Do not import claims from another revision or + from the newer tree without code and history support. + +## Generated files, validation, and safety + +`qla2xxx-orig/`, `in-tree-patches/`, modules, objects, `Module.symvers`, and +dependency files are generated/extracted output. Never hand-edit them or run +download/extraction/patch-generation scripts unless explicitly requested. +Compile through the selected top-level QLogic target or this component's +Makefile; there is no hardware unit-test target. + +Do not load/unload modules, bind or reset an HBA, enable target mode, expose +WWPNs/LUNs, change fabric sessions, issue LIPs, or run hardware teardown tests +without approval for the exact host, HBA ports, fabric, initiators, and storage. diff --git a/scst/AGENTS.md b/scst/AGENTS.md new file mode 100644 index 000000000..1ab337e03 --- /dev/null +++ b/scst/AGENTS.md @@ -0,0 +1,105 @@ +# SCST Core and Device Handlers + +## Ownership + +This directory owns the SCST kernel core, its in-tree device handlers, common +headers, persistent-reservation/DLM integration, sysfs implementation, and +Kbuild/Kconfig integration. It does not own transport-specific protocol state, +the `scstadmin` configuration parser, or user-space handler behavior. + +## Where to verify interfaces + +- Start with `include/scst.h` and its current callback comments for target + templates, device types, sessions, commands, task management, transfer + callbacks, execution context, and registration/unregistration. Verify a + change against the definitions and call sites that implement the contract. +- `include/scst_const.h`, `include/scst_sgv.h`, `include/scst_debug.h`, and + `include/backport.h` are shared with external modules. `src/Makefile`, + `src/Kbuild`, `src/dev_handlers/Kbuild`, and the Kconfig/Makefile in-tree + files own build composition and compatibility plumbing. +- `SysfsRules` plus `src/scst_sysfs.c`, `src/scst_tg.c`, `src/scst_targ.c`, + and handler sysfs code define the control surface consumed by `scstadmin`. +- `include/scst_user.h`/`src/dev_handlers/scst_user.c` and + `include/scst_event.h`/`src/scst_event.c` are kernel/user ABI pairs. + `doc/scst_user_spec.sgml` and `doc/scst_pg.sgml` are explanatory references, + not substitutes for current code. +- `T10-PI` explains the protection-information boundary. Verify its interface + details in current `_dif_` declarations and implementations, and audit the + supporting handler and every PI-capable target driver together. +- `src/scst_dlm.c` and `src/scst_pres.c` implement DLM-backed persistent- + reservation handling. Use `README.dlm` and `README.drbd` for background, not + as deployment scripts. Verify `cluster_mode`, lockspace naming, and + `t10_dev_id` behavior in current code; SCST does not own membership, quorum, + fencing, or resource-manager policy. + +Headers installed by `src/Makefile` are shared interfaces, even when most +consumers are in this repository. Everything under `src/` that is not exported +through those headers or sysfs is internal unless current code establishes +otherwise. + +## Change boundaries + +- A change to `scst.h` or shared constants requires auditing every target + driver, every device handler, generated interface hashes, and out-of-tree + compatibility implications. Do not bypass or hard-code the interface + version mechanism. +- A `scst_user.h` or `scst_event.h` change must update its kernel producer and + all `usr/` consumers together. Keep fixed-width layout, compat-ioctl, buffer + ownership, and explicit version checks intact where they exist; do not make + an unversioned event-layout change silently. +- A sysfs name, `[key]` marker, management command, ordering rule, or default + is also a `scstadmin` compatibility change. Audit save, parse, compare, and + apply paths before changing it. +- Device handlers own SCSI command parsing/execution and backend semantics; + the core owns generic command/session lifecycle. Preserve the documented + atomic-versus-thread context, completion-once, abort/cancellation, reference, + and unregister contracts. Re-derive exact locking and callback sequences + from current code for each change. + +## Kernel compatibility and backports + +`include/backport.h` is the shared compatibility layer for kernel APIs used by +the core, handlers, and target drivers. Keep its entries grouped and sorted by +the upstream header that owns the API, as required by the file prologue. Model +actual API availability: inspect the upstream introduction, stable-series +backports, and relevant RHEL, UEK, SUSE, or Ubuntu differences instead of +assuming that the base kernel version is sufficient. + +- For a generic kernel helper or type, keep normal call sites on the current + API and put the narrow compatibility wrapper, alias, or fallback in + `backport.h` when that matches existing practice. Keep behavior-specific + branches and component capability probes, such as RDMA conftests, with the + component that owns them. +- `backport.h` is included through `scst.h` and `scst_debug.h` and is installed + for external module builds. Audit the core, device handlers, all target + drivers, and installed-header consumers after changing it. Do not assume + that the generated interface hash detects every installed-header change; + verify the current hash inputs in `src/Makefile`. +- `scripts/generate-kernel-patch` includes this header in generated in-tree + patches, and `scripts/specialize-patch` evaluates recognized compatibility + predicates. Audit both scripts when adding a new predicate form or vendor + feature macro. +- Use the root-defined `ABT_KERNELS` matrix in `nightly/conf/nightly.conf` as + the support boundary. Do not remove an old compatibility branch based only + on a README minimum or mainline age; first confirm that no listed upstream + or distribution kernel needs it. Backport changes call for focused + multi-kernel regression coverage around the affected version boundary and + representative vendor kernels. + +## Generated files and validation + +`include/scst_itf_ver.h` is generated from interface header hashes; +`include/build_mode.h`, `build_mode`, signing keys under `src/certs/`, +`Module.symvers`, objects, modules, and dependency metadata are build state. +Do not edit them manually. Build-mode targets change generated state. Private +keys under `src/certs/` are secrets; their contents must not be displayed, and +the keys must not be committed, uploaded, or supplied to enrollment tools. + +The focused compile entry point is top-level `make scst` (or the component +Makefile with the same `KDIR`/toolchain assumptions). Kernel-style and +multi-kernel checks are the repository scripts and CI workflows named in the +root instructions. No separate lightweight core unit-test target exists. + +Never install/load the core or handlers, configure sysfs, attach/export +devices, enable debug fault injection, or exercise DLM/HA/persistent- +reservation state without explicit environment and device authorization. diff --git a/scst_local/AGENTS.md b/scst_local/AGENTS.md new file mode 100644 index 000000000..05f014a8c --- /dev/null +++ b/scst_local/AGENTS.md @@ -0,0 +1,42 @@ +# SCST Local Target + +## Ownership and interfaces + +This directory owns the `scst_local` loopback target: it presents SCST-exported +LUNs back to the same kernel through the SCSI midlayer. `scst_local.c` owns the +SCST target template, local SCSI host/command bridge, target/session management, +TransportID attributes, error handling, and teardown. `Kbuild`, `Makefile`, and +`in-tree/` own out-of-tree and in-tree composition. + +Start with `scst/include/scst.h` for the common target-driver contract and +`scst/SysfsRules` for common configuration conventions, then verify both in +their current implementations. `README` documents the local sysfs additions +and the user-space-target use case, but exact locking and lifecycle behavior +must be read from current code. + +## Change boundaries + +- One command crosses both the local SCSI initiator lifecycle and the SCST + target lifecycle. Preserve completion-once, abort/reset, queueing, sense/data, + session, device-release, and target-unregister ownership across both sides. +- Session/adapter removal interacts with SCST and device-model locks. Re-derive + the current lock order and deferred-release requirements before changing + close or teardown paths; do not call device removal while holding a lock that + the callback path can reacquire. +- Sysfs management commands and target/session attributes are consumed by + `scstadmin`. Audit parser/serializer/discovery behavior for changes. A shared + SCST callback change still requires all target drivers to be checked. + +## Generated files, validation, and safety + +Objects, modules, `Module.symvers`, and dependency metadata are generated. +The focused compile entry point is top-level `make scst_local` or this +component's Makefile; no component unit-test target exists. + +This driver can expose storage recursively on the same host. Never load it, +create local targets/sessions/LUNs, mount or use returned devices, or run abort/ +reset/teardown tests without explicit authorization. In particular, preserve +the backing-mode restrictions implemented by the current I/O and allocation +paths; use `README` to locate the risk, not as a substitute for checking the +code. Unsafe local use can recurse into memory reclaim and deadlock or corrupt +the backing storage. diff --git a/scstadmin/AGENTS.md b/scstadmin/AGENTS.md new file mode 100644 index 000000000..ce125b13b --- /dev/null +++ b/scstadmin/AGENTS.md @@ -0,0 +1,54 @@ +# scstadmin + +## Ownership and verification map + +This directory owns the `scstadmin` command, SCST Perl module, configuration +grammar and serialization, live sysfs discovery/mutation, and init/systemd +integration. It does not define kernel attributes or transport semantics. + +- `scstadmin` is a tracked symlink to `scstadmin.sysfs/`. + `scstadmin.sysfs/scstadmin` is the current parser, comparison, ordering, and + apply implementation. +- `scstadmin.sysfs/scst-1.0.0/lib/SCST/SCST.pm` owns sysfs discovery and + low-level mutations. `scst/SysfsRules` and current kernel sysfs code define + the producer side. +- `scstadmin.sysfs/man5/scst.conf.5` and + `scstadmin.sysfs/man1/scstadmin.1` document the public format and CLI. Verify + details against the current parser before changing behavior; the manpage + date is not proof that the parser is unchanged. +- `Makefile`, `scstadmin.sysfs/Makefile`, + `scstadmin.sysfs/scst-1.0.0/Makefile.PL`, packaging templates, and service + scripts implement build/install integration. + +## Compatibility and coupled changes + +- Treat stanza names, nesting, quoting/comments, attribute spelling, defaults, + warning/error behavior, and emitted ordering as user-visible compatibility + contracts. Current code still recognizes a deprecated format; do not remove + or silently reinterpret it without an explicit migration decision. +- Discovery must remain driven by sysfs and `[key]` metadata. Do not hard-code + a transport's dynamic attributes into generic code when the kernel can + describe them. +- Changes to kernel management commands, attributes, defaults, or enablement + order require auditing `SCST.pm` and the read/write/compare/apply paths. + Conversely, grammar changes must be checked against service startup, + examples, manpages, all target drivers, and iSCSI daemon requirements. +- Applying a partial configuration can affect live targets not named by the + file. Preserve the explicit `-force` boundary and inspect Git history when + changing reconciliation/removal behavior. + +## Generated files, validation, and safety + +Perl MakeMaker output under `scstadmin.sysfs/scst-1.0.0/`, including +`Makefile`, `Makefile.old`, `blib/`, `MYMETA.*`, and `pm_to_blib`, is +generated. Packaging trees/spec output, archives, and installed-script +substitutions are generated too. Do not edit them manually. + +The component `make test` is not an isolated parser unit suite: its tests can +kill/start daemons, load/unload modules, and create/remove live SCST objects. +`scstadmin -check_config` also requires root and a live SCST sysfs view. Run +neither without explicit authorization for a disposable SCST test host. + +Do not invoke configuration apply/write/clear operations, service scripts, +module management, LIP/reset helpers, or tests against a real host without an +approved configuration and recovery plan. diff --git a/srpt/AGENTS.md b/srpt/AGENTS.md new file mode 100644 index 000000000..9503b6acf --- /dev/null +++ b/srpt/AGENTS.md @@ -0,0 +1,44 @@ +# SRPT + +## Ownership and sources of truth + +This directory owns the `ib_srpt` SCST target over SRP on InfiniBand and, +through RDMA/CM, RoCE or iWARP. `src/ib_srpt.c` and `src/ib_srpt.h` own the +transport, channel/session, RDMA, command, and teardown implementation. +`src/Kbuild`, `src/Kconfig`, `Makefile`, and `conftest/` own its in-tree, +out-of-tree, distribution-RDMA, and OFED compatibility. + +`session-management.txt` is a useful lifecycle design reference and `README` +describes configuration. Verify exact states, callbacks, and supported APIs in +current code and conftests. `README_in-tree` and `README.ofed` are historical +integration procedures. `Testing.txt` is a privileged maintainer checklist +with historical steps, not an automated test suite, and +`Measurement-Results.txt` is a hardware-specific historical snapshot; none of +these establishes current kernel, OFED, test, or performance policy. + +## Change boundaries + +- The driver depends on SCST target/session APIs and RDMA core/CM/IB APIs. + Preserve SCST and RDMA object references across login/relogin, QP completion, + data transfer, abort/task management, disconnect, session unregister, port + removal, and module exit. +- Completion, CM callbacks, async events, work, and SCST callbacks can race. + Re-derive current channel state, mutex/spinlock context, completion-once, QP + drain, and asynchronous free ordering from code for every lifecycle change. +- Keep RDMA/OFED conftests as capability probes. Do not replace them with + unverified kernel- or vendor-version assumptions. +- Changes to SCST callbacks or sysfs `[key]` attributes require the repository- + wide driver and `scstadmin` audits described in the root instructions. + +## Generated files, validation, and safety + +`conftest/*/result-*.txt`, conftest build logs, objects, modules, +`Module.symvers`, and dependency metadata are generated. The focused compile +entry point is top-level `make srpt` or this component's Makefile; the build +runs compatibility conftests. There is no safe local unit-test target. + +The procedures in `Testing.txt` include module/service churn, sysfs writes, +remote initiator logins, resets, fault injection, filesystems, stress I/O, and +device-overwriting benchmarks. Run none of them without explicit disposable +target/initiator, HCA ports, fabric, devices, and recovery authorization. Do +not install OFED, change RDMA state, or load/unload SRP modules implicitly. diff --git a/usr/AGENTS.md b/usr/AGENTS.md new file mode 100644 index 000000000..83258570d --- /dev/null +++ b/usr/AGENTS.md @@ -0,0 +1,43 @@ +# SCST User-Space Programs + +## Ownership and interfaces + +This directory owns C programs that consume SCST kernel/user interfaces: + +- `fileio/` implements a user-space device handler over `/dev/scst_user`. + `scst/include/scst_user.h` and + `scst/src/dev_handlers/scst_user.c` own the kernel side of that ABI. +- `stpgd/` consumes SCST events and dispatches ALUA state transitions through + `scst_on_stpg`. `events/` is a small event-API example and is not part of the + default `usr/Makefile` build/install set. +- `scst/include/scst_event.h` and `scst/src/scst_event.c` own the event ABI. + +These programs do not own generic SCST configuration, backend kernel handler +semantics, or target transport protocols. + +## Change boundaries + +- Update user and kernel producers/consumers together for any ioctl, event, + structure layout, command/subcommand, flag, error, or version change. Keep + fixed-width types, 32/64-bit compatibility, interface versioning where + present, and ownership/reuse rules for shared buffers and commands. +- For `fileio`, trace registration, memory mapping/allocation, command receive, + execution, completion, exception, abort, and unregister paths before changing + lifetime behavior. Use current code and `doc/scst_user_spec.sgml`; do not + rely on the document alone. +- For `stpgd`, treat event filtering and the external helper invocation as a + cluster/control boundary. Changes may alter ALUA state on multiple nodes. + +## Generated files, validation, and safety + +`fileio_tgt`, `stpgd`, the optional `events` binary, `.depend*`, objects, and +installed files are generated artifacts. Build through `usr/Makefile` or the +focused top-level `make usr`; the default build covers `fileio` and `stpgd`, +not `events`. These programs use `CC` directly; kernel `ARCH` and +`CROSS_COMPILE` settings do not by themselves select a user-space cross +compiler. There is no local unit-test target. + +Do not run these programs against `/dev/scst_user`, install them, invoke +`scst_on_stpg`, or change ALUA/cluster state without explicit authorization. +Do not point a handler at a real backing file or block device unless the exact +storage and destructive-test scope are approved.