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