Repository navigation
docs: Bring SCST documentation in sync with current code - #384
Merged
Merged
Conversation
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.
Add repository-local skills for developing, linting, and independently reviewing committed SCST patch ranges. Keep lint in the main agent, require it before a terminal read-only reviewer, and bound review-driven revisions to three attempts.
The top-level guides still describe retired source, QLogic, service and kernel-support workflows. Following them can select the wrong driver, cross-compile only part of the tree, or misstate module-signing policy. Commit 7aade0a ("Makefile: Make the qla2x00t-32gbit driver the default QLogic FC driver") made the newer tree the default. Commit 0d3c901 ("debian, scstadmin: Add systemd scst.service") added the installed systemd unit. Point source users at GitHub and kernel support at nightly/conf/nightly.conf. Separate kernel and user-space cross builds, follow the current service recipes, and make module acceptance depend on the target kernel and platform policy.
All four AskingQuestions copies direct users to the removed top-level Linux REPORTING-BUGS file. They also present reports built around Linux 2.6, procfs and obsolete module names without an age marker. Point each copy at Documentation/admin-guide/reporting-issues.rst, the current kernel reporting guide. Keep the old reports as examples of useful diagnostic detail, but label them historical so their commands are not reused as SCST setup instructions.
README.performance runs fio against a block device, exports LUNs, logs in iSCSI sessions and may enable multipath. Its placeholders look copyable, but using the wrong path or host can overwrite storage and change both target and initiator state. Put an explicit safety boundary before the first command. Require authorization for the exact hosts, transports and configuration, and allow the workflow only with verified disposable backing devices.
The core guides have drifted across VDISK, sysfs, build modes, performance tuning and cache semantics. Some advice requires removed kernel patches, prescribes CFQ unconditionally, or treats volatile write-back data as durable. Use scst_vdisk.c for backend options, current sysfs code for attributes, scst/Makefile for build_mode.h and nightly/conf/nightly.conf for the kernel support boundary. Correct the enabled and tgt tokens and document the T10-PI protection SG count. Commit 9a0c18a ("scst: Disable I/O context sharing for kernel v4.21 and later kernels") limits I/O grouping to old kernels. Linux commit f664a3cc17b7 ("scsi: kill off the legacy IO path") also makes CFQ advice invalid for current kernels. Commit d84fc07 ("vdisk_fileio: Add support for asynchronous I/O processing") added direct I/O to VDISK, and commit 3fc775c ("EXTENDED COPY support") implemented another open ToDo item. Remove both completed tasks and replace stale performance and durability claims with behavior derived from the current stack.
README.dlm embeds a 2015 Pacemaker recipe that disables quorum and fencing. README.drbd also says persistent reservation state is never shared between nodes. The first is unsafe for shared storage and the second contradicts the current cluster_mode implementation. Commit 6420070 ("scst: Synchronize persistent reservation state between cluster nodes") added DLM-backed reservation synchronization. The current contract lives in scst_dlm.c and scst_pres.c, while fencing and resource-manager policy remain outside SCST. Replace the fixed Pacemaker commands with DLM dependencies and startup and shutdown ordering. Require fencing, describe cluster_mode, retain the DRBD protocol C requirement and leave multipath policy to the installed initiator stack.
The programming guide presents copied structure layouts, callbacks and management paths as current interfaces. API and build changes have left those copies describing fields and operations that no longer exist. Commit 08e5327 ("Remove procfs support") removed the documented procfs callbacks and paths. Commit 2090b68 ("qla2x00t: remove detect() callback") moved QLogic setup out of the template detect hook. Make scst/include/scst.h and scst/SysfsRules authoritative, and label embedded declarations as historical outlines. Update callback names, QLogic initialization, sysfs trace commands and build modes. The supported kernels in nightly/conf/nightly.conf also span different Kconfig and logging interfaces. Refer readers to the exact target kernel instead of prescribing fixed debug symbols, buffer limits and syslog paths.
The scst_user specification copies ioctl structures and command payloads that predate several ABI extensions. Building a handler from those layouts can select the wrong union member, alignment or completion path. Commit 3fc775c ("EXTENDED COPY support") added remapping payloads. Commit daee4dc ("WRITE SAME command improvements") added WRITE SAME descriptors. Commit d1bd22a ("scst_user: avoid global locks") left the explicit unregister ioctl as an obsolete no-op. Use scst/include/scst_user.h and scst_user.c as the producer-side source of truth. Synchronize registration, command, reply and subcommand layouts, version checks, reserved fields and ioctl rules. Update the fileio_tgt, stpgd and event guides from current code. Make live-storage and event-consumption risks explicit.
The iSCSI READMEs, HOWTO and man pages combine current code with procfs, old daemon configuration and fixed runtime output. The result documents invalid paths, the wrong object creation order and unsafe live commands. Commit 08e5327 ("Remove procfs support") removed the main obsolete interface. Commit 70eb596 ("Rework iSCSI aborts to make them more correct and remove recent workarounds (one more post-IET cleanup)") added the SCST abort callback requested by an old ToDo entry. Use iscsi_scst.h, kernel/config.c and usr/config.c for the kernel and daemon contract. Correct sysfs ownership, authentication limits, setup ordering, logging and dynamic output, and remove the completed task. Keep iscsi-scstd.conf and iscsi-scst-adm documented because current code still consumes them, but direct new setups to scst.conf. Replace the removed service command and warn before exposing storage, credentials, portals or sessions.
The iSER and distribution guides prescribe OFED 1.5 installation, deleting packaged RDMA modules, patching kernel builds and applying host-wide tuning. The Gentoo procedure targets SVN, while the bundled OCF agents are neither built nor exercised by repository CI. Commit 0255740 ("isert: Support building against MOFED without patching the kernel build system") established the supported header-selection model. Current Makefile conftests and isert-scst sources define the remaining compatibility and transport limits. Replace fixed OFED and tuning recipes with those sources and matching vendor guidance. Reduce the Gentoo and resource-agent documents to historical integration notes, and spell out their module, sysfs, daemon, session and storage side effects before any reuse.
The scstadmin manuals still describe the 2.0 parser, a database backend and SysV-only service integration. They omit current ALUA operations and call -check_config an offline check even though it reads live sysfs. Commit 3a8d70b ("- Remove old scst_db stuff which no longer works with even procfs.") removed the database implementation. The current grammar and apply order live in scstadmin.sysfs/scstadmin, while SCST/SCST.pm consumes the kernel-provided sysfs metadata. Document the current commands, quoting, comments, DEVICE references and systemd environment handling. Keep deprecated-format conversion, but explain that it reconciles live state. Mark conversion, checking, examples, installation and service operations with their root, sysfs and exported-storage effects.
The SRPT guides mix current RDMA/CM code with Linux 2.6, procfs and OFED 1.5 procedures. Their parameter defaults, session names and tuning advice no longer describe the driver built by this tree. Commit 020ec68 ("ib_srpt: Change default behavior from using SRQ to not using SRQ") changed receive queues, and commit 434207a ("ib_srpt: Restore immediate data support") changed request sizing. Commit fa58faf ("ib_srpt: Add RDMA/CM support") added the IP-based session naming mode. Commit 08e5327 ("Remove procfs support") invalidated the in-tree setup, while commit d6fd031 ("Split Makefiles: move kernel build rules into Kbuild files") moved the fault-injection flag. Commit c2bd2e8 ("ib_srpt: Remove "thread" kernel module parameter and keep thread=1 behavior - the other two modes could cause soft lockup complaints") made threaded completion unconditional. Use ib_srpt.c, ib_srpt.h and conftests for current behavior. Scope SCSI multiqueue advice after Linux commit f664a3cc17b7 ("scsi: kill off the legacy IO path"), and mark OFED, HA, benchmark and test recipes as historical or destructive.
The legacy and newer QLogic guides disagree about the default driver, supported adapters, NPIV, sysfs layout and module lifecycle. The HOWTO also carries SVN, kernel replacement, firmware flashing and discovery commands that can disrupt active storage. Commit 7aade0a ("Makefile: Make the qla2x00t-32gbit driver the default QLogic FC driver") selected the newer tree by default. Commit a788a4e ("Newer version of QLogic target driver with 16G (26xx/83xx) support") added that tree and disabled legacy NPIV target callbacks. Commit 08e5327 ("Remove procfs support") removed the old management path. Use each qla2xxx_pci_tbl[] and qla_os.c for hardware and firmware facts. Document QLA_32GBIT=no, current per-port sysfs state, reset effects and the matched qla2xxx_scst and qla2x00tgt modules. Replace unsafe generic recipes with repository or vendor sources and mark every HBA, fabric, target and backing-device operation as live.
The FCST setup has stale step references and an invalid target enable path. A reader following it reaches the wrong prerequisites and cannot address enabled after entering the target directory. Commit 87bde8a ("fcst/README: Update this README file") shortened the procedure without updating its cross-references. Commit 7a12737 ("Simplify README by eliminating example using of ini_groups.") changed the LUN setup but left $LPORT duplicated in the following path. Repair the references, terminology and relative enable command, and clarify the LUN 0 compatibility note. The same procedure installs packages, creates an FCoE interface, loads modules and exports storage, so require authorization for the host, CNA, fabric, initiators and backing devices before it is run.
The scst_local README omits exported attributes, claims dynamic sessions cannot be saved and uses an invalid module path. Its walkthrough also creates and exports a writable backing file on the same host without a safety boundary. Commit 84d335f ("scst_local: Make the SCSI host number available in sysfs") added host_no. Commit 00caf4d ("scstadmin: Make -write_config save the scst_local session name") added the missing serialization. Document host_no and version from scst_local.c and remove the obsolete session warning. Use ./scst_local.ko, fix the malformed sysfs path and explain that add_default_tgt=0 suppresses default objects. Require an isolated host and disposable backing path while retaining the recursion, mount and swap restrictions.
The website links to stale deployed manuals, generated pages and a QLogic snapshot that is not in the repository. Several feature summaries also describe code that has since changed or disappeared. Commit 7aade0a ("Makefile: Make the qla2x00t-32gbit driver the default QLogic FC driver") changed the default QLogic tree. Commit 3a8d70b ("- Remove old scst_db stuff which no longer works with even procfs.") removed database-backed scstadmin configuration. Commit d84fc07 ("vdisk_fileio: Add support for asynchronous I/O processing") removed O_DIRECT as a fileio_tgt-only distinction. Linux commit 066465251303 ("tgt: removal") removed scsi_tgt in 2014, turning the website prediction into a completed historical event. Commit 10ebf80 ("Docs update") merged the SGV cache text into doc/scst_pg.sgml. Link website entries to maintained repository sources, use the real lowercase make rpm target, update the affected feature descriptions and remove references to files that are not tracked.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.