mirror of
https://github.com/SCST-project/scst.git
synced 2026-08-22 07:06:22 +00:00
docs: Add repository guidance for agents
SCST spans a kernel core, transport drivers, user-space programs and configuration tools. Each area has different ABI, build, validation and safety constraints, but the repository has no persistent guidance for automated contributors. Add a root AGENTS.md with cross-component contracts and nested files for components with independent boundaries. Record authoritative sources, generated files, compatibility policy and destructive workflows so changes start from the correct context and avoid live storage state.
This commit is contained in:
Gleb Chesnokov
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
+105
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user