From 59e915e822242eef5f227d75fe978342d5647999 Mon Sep 17 00:00:00 2001 From: Gleb Chesnokov Date: Thu, 20 Aug 2026 16:11:57 +0300 Subject: [PATCH] doc/scst_pg.sgml: Update the programming guide 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 08e532715dca ("Remove procfs support") removed the documented procfs callbacks and paths. Commit 2090b6811a11 ("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. --- doc/scst_pg.sgml | 223 +++++++++++++++++------------------------------ 1 file changed, 80 insertions(+), 143 deletions(-) diff --git a/doc/scst_pg.sgml b/doc/scst_pg.sgml index 81dd91023..de9ca477e 100644 --- a/doc/scst_pg.sgml +++ b/doc/scst_pg.sgml @@ -23,6 +23,12 @@ unified consistent interface between SCSI target drivers, backend device handlers and Linux kernel as well as simplifies target drivers development as much as possible. +This guide describes SCST architecture. Exact structure layouts, callback +contracts, execution contexts and state sequences must be taken from the +current scst/include/scst.h and implementation. For the management +interface, consult scst/SysfsRules and the current sysfs +implementation. + It has the following features: @@ -142,7 +148,9 @@ interaction between SCST, its drivers and Linux SCSI subsystem.

To work with SCST a target driver must register its template in SCST by calling scst/include/scst.h for the current layout and callback contracts: struct scst_tgt_template @@ -157,8 +165,6 @@ struct scst_tgt_template unsigned xmit_response_atomic:1; unsigned rdy_to_xfer_atomic:1; - unsigned no_proc_entry:1; - int max_hw_pending_time; int threads_num; @@ -172,7 +178,7 @@ struct scst_tgt_template void (*on_free_cmd) (struct scst_cmd *cmd); - int (*alloc_data_buf) (struct scst_cmd *cmd); + int (*tgt_alloc_data_buf) (struct scst_cmd *cmd); void (*preprocessing_done) (struct scst_cmd *cmd); @@ -183,10 +189,6 @@ struct scst_tgt_template int (*report_aen) (struct scst_aen *aen); - int (*read_proc) (struct seq_file *seq, struct scst_tgt *tgt); - int (*write_proc) (char *buffer, char **start, off_t offset, - int length, int *eof, struct scst_tgt *tgt); - int (*get_initiator_port_transport_id) (struct scst_session *sess, uint8_t **transport_id); } @@ -216,8 +218,6 @@ SG-vector clustering corresponding function supports execution in the atomic (non-sleeping) context. - 0 if the regular SCST allocation should be done. In case of returning -successfully, scst_cmd->tgt_data_buf_alloced will be set by SCST. It is +successfully, scst_cmd->tgt_i_data_buf_alloced will be set by SCST. It is possible that both target driver and dev handler request own memory allocation. If allocation in atomic context, i.e. scst_cmd_atomic() is true, and < 0 is returned, this function will be recalled in thread @@ -325,15 +325,6 @@ scst_unregister_session() returned, if its called in the blocking mode. AENs for such sessions should be ignored. Must be defined, if low-level protocol supports AENs. - Structure -Structure scst/include/scst.h for the current layout and callback contracts: struct scst_dev_type @@ -550,11 +543,9 @@ struct scst_dev_type int type; unsigned parse_atomic:1; - unsigned alloc_data_buf_atomic:1; + unsigned dev_alloc_data_buf_atomic:1; unsigned dev_done_atomic:1; - unsigned no_proc:1; - unsigned pr_cmds_notifications:1; int threads_num; @@ -563,21 +554,20 @@ struct scst_dev_type int (*attach) (struct scst_device *dev); void (*detach) (struct scst_device *dev); - int (*attach_tgt) (struct scst_tgt_device *tgt_dev); - void (*detach_tgt) (struct scst_tgt_device *tgt_dev); + int (*attach_tgt) (struct scst_tgt_dev *tgt_dev); + void (*detach_tgt) (struct scst_tgt_dev *tgt_dev); int (*parse) (struct scst_cmd *cmd); - int (*alloc_data_buf) (struct scst_cmd *cmd); + int (*dev_alloc_data_buf) (struct scst_cmd *cmd); int (*exec) (struct scst_cmd *cmd); int (*dev_done) (struct scst_cmd *cmd); int (*on_free_cmd) (struct scst_cmd *cmd); - int (*task_mgmt_fn) (struct scst_mgmt_cmd *mgmt_cmd, + void (*task_mgmt_fn_received) (struct scst_mgmt_cmd *mgmt_cmd, + struct scst_tgt_dev *tgt_dev); + void (*task_mgmt_fn_done) (struct scst_mgmt_cmd *mgmt_cmd, struct scst_tgt_dev *tgt_dev); - int (*read_proc) (struct seq_file *seq, struct scst_dev_type *dev_type); - int (*write_proc) (char *buffer, char **start, off_t offset, - int length, int *eof, struct scst_dev_type *dev_type); } @@ -590,13 +580,10 @@ unique. bufflen/ and data_direction/ (both - REQUIRED). Returns the command's - - - - . @@ -848,7 +813,7 @@ Where: Consider simplified commands processing example. It assumes that target driver doesn't need own memory allocation, i.e. not defined -alloc_data_buf() callback. Example of such target driver is qla2x00t. +tgt_alloc_data_buf() callback. Example of such target driver is qla2x00t. The commands processing by SCST started when target driver calls SGV cache runtime information and statistics is available in -/proc/scsi_tgt/sgv. +/sys/kernel/scst_tgt/sgv. Target driver qla2x00t @@ -1795,18 +1760,16 @@ some common processing. Driver initialization

-On initialization, qla2x00tgt registers its SCST template tgt2x_template -in the SCST core. Then during template registration SCST core calls -detect() callback which is function q2t_target_detect(). +On initialization, qla2x00tgt registers its callbacks in qla2xxx by +calling q2t_target_driver_reg(), which calls +qla2xxx_tgt_register_driver(). Qla2xxx_tgt_register_driver() stores the +registered callbacks in variable qla_target. -In this function qla2x00tgt registers its callbacks in qla2xxx by -calling qla2xxx_tgt_register_driver(). Qla2xxx_tgt_register_driver() -stores pointer to the being registered callbacks in variable qla_target. - -Then q2t_target_detect() calls qla2xxx_add_targets(), which calls for -each known local FC port (HBA instance) qla_target.tgt_host_action() -callback with ADD_TARGET action. Then q2t_host_action() calls -q2t_add_target() which registers SCST target for this FC port. +Qla2x00tgt then registers its SCST template tgt2x_template in the SCST +core and calls qla2xxx_add_targets(). The latter calls, for each known +local FC port (HBA instance), qla_target.tgt_host_action() with the +ADD_TARGET action. Then q2t_host_action() calls q2t_add_target(), which +registers the SCST target for this FC port. If later a new FC port is hot added, qla2x00_probe_one() will also call for all new local ports qla_target.tgt_host_action() with ADD_TARGET @@ -1956,38 +1919,36 @@ are 3 types of builds: - -Switch between build modes is done by calling "make x2y", where "x" - -current build mode and "y" - desired build mode. For instance, to switch -from release to debug mode you should run "make release2debug". +Select a build mode with Logging levels management

-Logging levels management is done using "trace_level" file located in the -driver's proc interface subdirectory. Each SCST driver has it, except in -the perf build mode. For instance, for SCST core it's located in -/proc/scsi_tgt/. For qla2x00t it's located in /proc/scsi_tgt/qla2x00tgt/. +Logging levels are managed through "trace_level" sysfs attributes when +tracing or debugging is compiled in. The SCST core attribute is +/sys/kernel/scst_tgt/trace_level/. Target-driver and device-handler +attributes are in their respective roots below +/sys/kernel/scst_tgt/targets/ and /sys/kernel/scst_tgt/handlers/. -Reading from it you can find currently enabled logging levels. +Reading an attribute shows the currently enabled logging levels. You can change them by writing in this file, like: -# echo "add scsi" >/proc/scsi_tgt/trace_level +# echo "add scsi" >/sys/kernel/scst_tgt/trace_level The following commands are available: @@ -1997,7 +1958,7 @@ The following commands are available: +Persistent Reservation state dumping is exposed separately through the +per-device @@ -2080,53 +2041,29 @@ available in the release build. Preparing a debug kernel

-SCST logging can produce huge amount of logging, which default kernel -configuration can't cope with, so it needs some extra adjustments. - -For that you should change in lib/Kconfig.debug or init/Kconfig -depending from your kernel version LOG_BUF_SHIFT from "12 21" to "12 25". - -Then you should in your .config set CONFIG_LOG_BUF_SHIFT to 25. +SCST logging can produce a huge amount of output, so size the printk ring +buffer using facilities supported by the exact target kernel. Current +kernels document CONFIG_LOG_BUF_SHIFT and the log_buf_len boot parameter +in Documentation/admin-guide/kernel-parameters.rst. Do not modify a +kernel Kconfig limit solely to force a historical buffer size. Also, Linux kernel has a lot of helpful debug facilities, like lockdep, which allows to catch various deadlocks, or memory allocation debugging. It is recommended to enable them during SCST debugging. -The following options are recommended to be enabled (available depending -from your kernel version): CONFIG_SLUB_DEBUG, CONFIG_PRINTK_TIME, -CONFIG_MAGIC_SYSRQ, CONFIG_DEBUG_FS, CONFIG_DEBUG_KERNEL, -CONFIG_DEBUG_SHIRQ, CONFIG_DETECT_SOFTLOCKUP, CONFIG_DETECT_HUNG_TASK, -CONFIG_SLUB_DEBUG_ON, CONFIG_SLUB_STATS, CONFIG_DEBUG_PREEMPT, -CONFIG_DEBUG_RT_MUTEXES, CONFIG_DEBUG_PI_LIST, CONFIG_DEBUG_SPINLOCK, -CONFIG_DEBUG_MUTEXES, CONFIG_DEBUG_LOCK_ALLOC, CONFIG_PROVE_LOCKING, -CONFIG_LOCKDEP, CONFIG_LOCK_STAT, CONFIG_DEBUG_SPINLOCK_SLEEP, -CONFIG_STACKTRACE, CONFIG_DEBUG_BUGVERBOSE, CONFIG_DEBUG_VM, -CONFIG_DEBUG_VIRTUAL, CONFIG_DEBUG_WRITECOUNT, CONFIG_DEBUG_MEMORY_INIT, -CONFIG_DEBUG_LIST, CONFIG_DEBUG_SG, CONFIG_DEBUG_NOTIFIERS, -CONFIG_FRAME_POINTER, CONFIG_FAULT_INJECTION, CONFIG_FAILSLAB, -CONFIG_FAIL_PAGE_ALLOC, CONFIG_FAIL_MAKE_REQUEST, -CONFIG_FAIL_IO_TIMEOUT, CONFIG_FAULT_INJECTION_DEBUG_FS, -CONFIG_FAULT_INJECTION_STACKTRACE_FILTER. +Select the lock, memory, watchdog, stack-trace and fault-injection +facilities relevant to the problem from the target kernel's own Kconfig. +Option names and dependencies differ across kernels supported by SCST; +consult that kernel's Kconfig help and documentation instead of copying a +fixed symbol list. Preparing logging subsystem

-It is recommended that you system logger daemon on the target configured: - - - - To store kernel logs in separate files on the fastest disk you -have. It will be better if this disk is dedicated for logging or, at -least, doesn't contain your LUNs data. - - To write the kernel logs to the disk in asynchronous manner, i.e. -without calling fsync() after each written message. Usually, you can -achieve it, if you add a '-' sign before the corresponding file path in -your syslog daemon conf file, like: - -kern.* -/var/log/kern.log - - +Configure the target's active journal or syslog implementation to persist +kernel messages without filtering SCST output. Log paths and +configuration syntax are distribution-specific. Verify that the complete +boot log is retained before reproducing the problem. Decoding OOPS messages