scst: Clarify synchronization and cleanup comments

Explain the state protected by existing core and transport locks beside
their declarations. Identify the writer/reader pairing for
io_context_ready and the ordering of the shared diagnostic-buffer
clearing. No lock, barrier or memory access is added or removed.

Correct repeated words in callback lifetime comments. Describe
label/error cleanup without suggesting a switch-fallthrough annotation,
and drop the redundant annotation between adjacent empty case labels.

Source review also identified the old LKML date/index link in the
I/O-context comment. Use the message-ID archive link retained in the
historical branch for that discussion.

Checkpatch reports REPEATED_WORD:

  Possible repeated word: 'that'

Checkpatch reports UNCOMMENTED_DEFINITION:

  spinlock_t definition without comment

Checkpatch reports PREFER_FALLTHROUGH:

  Prefer 'fallthrough;' over fallthrough comment

Checkpatch reports MEMORY_BARRIER:

  memory barrier without comment

fcst/ft_scst.c

@@ -25,6 +25,7 @@ unsigned int ft_debug_logging;
 module_param_named(debug_logging, ft_debug_logging, int, 0644);
 MODULE_PARM_DESC(debug_logging, "log levels bigmask");
 
+/* Serializes local-port publication/removal and session management. */
 DEFINE_MUTEX(ft_lport_lock);
 
 static struct notifier_block ft_notifier = {

iscsi-scst/kernel/iscsi.h

@@ -79,6 +79,7 @@ struct iscsi_thread {
 };
 
 struct iscsi_thread_pool {
+	/* Protects read scheduling and connection close flags. */
 	spinlock_t rd_lock;
 	struct list_head rd_list;
 	wait_queue_head_t rd_waitq;
@@ -96,6 +97,7 @@ struct iscsi_thread_pool {
 	/* Entry in iscsi_thread_pools_list */
 	struct list_head thread_pools_list_entry;
 
+	/* Protects thread-list membership and enumeration. */
 	struct mutex tp_mutex;
 	struct list_head threads_list; /* protected by tp_mutex */
 };
@@ -113,6 +115,7 @@ struct iscsi_attr {
 struct iscsi_target {
 	struct scst_tgt *scst_tgt;
 
+	/* Serializes session/connection management and target attributes. */
 	struct mutex target_mutex;
 
 	struct list_head session_list; /* protected by target_mutex */
@@ -144,6 +147,7 @@ struct iscsi_session {
 	struct iscsi_tgt_params tgt_params;
 	atomic_t active_cmds;
 
+	/* Protects CmdSN sequencing, pending commands and delayed TM responses. */
 	spinlock_t sn_lock;
 	u32 exp_cmd_sn; /* protected by sn_lock */
 
@@ -210,6 +214,7 @@ struct iscsi_conn {
 
 	atomic_t conn_ref_cnt;
 
+	/* Protects queued writes, response timeout lists and timer state. */
 	spinlock_t write_list_lock;
 	/* List of data pdus to be sent. Protected by write_list_lock */
 	struct list_head write_list;
@@ -315,6 +320,7 @@ struct iscsi_conn {
 	unsigned int nop_in_interval; /* in jiffies */
 	unsigned int nop_in_timeout; /* in jiffies */
 	struct list_head nop_req_list;
+	/* Protects the list of outstanding NOP-In requests. */
 	spinlock_t nop_req_list_lock;
 	u32 nop_in_ttt;
 

iscsi-scst/kernel/isert-scst/iser.h

@@ -171,6 +171,7 @@ struct isert_conn {
 	struct isert_wr		*post_recv_first;
 	struct isert_wr		*post_recv_curr;
 
+	/* Protects the receive WR chain and its pending count above. */
 	spinlock_t		post_recv_lock;
 
 	spinlock_t		tx_lock ____cacheline_aligned;
@@ -185,6 +186,7 @@ struct isert_conn {
 	struct isert_cq		*cq_desc;
 
 	enum isert_conn_state	state;
+	/* Serializes connection-state changes, disconnect and drain posting. */
 	struct mutex		state_mutex;
 
 	u32			responder_resources;
@@ -249,6 +251,7 @@ struct isert_device {
 };
 
 struct isert_global {
+	/* Protects portal-list membership and live portal accounting. */
 	spinlock_t		portal_lock;
 	/* protected by portal_lock */
 	struct list_head	portal_list;

iscsi-scst/kernel/isert-scst/isert.h

@@ -68,6 +68,7 @@ struct isert_listener_dev {
 	struct cdev cdev;
 	dev_t devno;
 	wait_queue_head_t waitqueue;
+	/* Protects the new/current connection lists and listener portal slots. */
 	struct mutex conn_lock;
 	struct list_head new_conn_list;
 	struct list_head curr_conn_list;
@@ -99,6 +100,7 @@ struct isert_conn_dev {
 	struct iscsi_conn *conn;
 	unsigned int idx;
 	int occupied;
+	/* Protects login request/response PDU ownership. */
 	spinlock_t pdu_lock;
 	struct iscsi_cmnd *login_req;
 	struct iscsi_cmnd *login_rsp;

iscsi-scst/kernel/target.c

@@ -26,6 +26,7 @@
 
 #define MAX_NR_TARGETS		BIT(30)
 
+/* Serializes target, session and connection management requests. */
 DEFINE_MUTEX(target_mgmt_mutex);
 
 /* All 3 protected by target_mgmt_mutex */

iscsi-scst/usr/iscsid.c

@@ -1411,7 +1411,6 @@ void cmnd_finish(struct connection *conn)
 		conn->state = STATE_LOGIN;
 		break;
 	case STATE_SECURITY_FULL:
-		/* fall through */
 	case STATE_LOGIN_FULL:
 		if (conn->session_type == SESSION_NORMAL)
 			conn->state = STATE_KERNEL;

scst/include/scst.h

@@ -1725,6 +1725,7 @@ struct scst_tgt {
 	int retry_cmds;
 	struct timer_list retry_timer;
 	struct list_head retry_cmd_list;
+	/* Protects the target retry queue and timer state above. */
 	spinlock_t tgt_lock;
 
 	/* Used to wait until session finished to unregister */
@@ -1968,6 +1969,7 @@ struct scst_pr_abort_all_pending_mgmt_cmds_counter {
  * Structure to control commands' queuing and threads pool processing the queue
  */
 struct scst_cmd_threads {
+	/* Protects the active command queue shared by the pool threads. */
 	spinlock_t cmd_list_lock;
 	struct list_head active_cmd_list; /* commands queue */
 	wait_queue_head_t cmd_list_waitQ;

scst/src/dev_handlers/scst_user_main.c

@@ -1176,7 +1176,7 @@ out:
 out_nomem:
 	if (ucmd->cmd)
 		scst_set_busy(ucmd->cmd);
-	/* fall through */
+	/* Continue with abnormal command completion. */
 
 out_err:
 	if (ucmd->cmd)

scst/src/scst_copy_mgr.c

@@ -142,6 +142,7 @@ struct scst_cm_ec_cmd_priv {
 #define SCST_CM_ERROR_WRITE	2
 	int cm_error;
 
+	/* Serializes descriptor progress and generated-command completion. */
 	struct mutex cm_mutex;
 
 	int cm_cur_in_flight; /* commands */
@@ -2276,7 +2277,7 @@ static void scst_cm_init_inq_finish(struct scst_cmd *cmd)
 
 	/*
 	 * Since scst_cm_inq_retry_fn() uses cmd->tgt_i_priv, only free that
-	 * pointer once it is clear that that function won't be called.
+	 * pointer once it is clear that the function won't be called.
 	 */
 	kfree(priv);
 	priv = NULL;

scst/src/scst_debug.c

@@ -182,6 +182,7 @@ const char *debug_transport_id_to_initiator_name(const uint8_t *transport_id)
 	 * missing their NULL terminator.
 	 */
 	memset(name_buf, 0, SIZEOF_NAME_BUF);
+	/* Order clearing the terminator before filling the next diagnostic name. */
 	smp_mb();
 
 	switch (transport_id[0] & 0x0f) {

scst/src/scst_lib.c

@@ -5277,6 +5277,7 @@ found:
 			t->acg_dev->acg->acg_io_grouping_type);
 	} else {
 		wait_event(a->ioctx_wq, a->io_context_ready);
+		/* Pair with scst_ioctx_get() before reading the published I/O context. */
 		smp_rmb();
 		TRACE_DBG("Going to share IO context %p (res %p, ini %s, dev %s, cmd_threads %p, grouping type %d)",
 			  res->active_cmd_threads->io_context, res,

scst/src/scst_main.c

@@ -101,6 +101,7 @@ char *scst_cluster_name;
 
 unsigned int scst_setup_id;
 
+/* Protects the initialization command queue and poll accounting. */
 spinlock_t scst_init_lock;
 wait_queue_head_t scst_init_cmd_list_waitQ;
 struct list_head scst_init_cmd_list;
@@ -123,12 +124,14 @@ struct percpu_ref scst_cmd_count;
 struct percpu_ref scst_mcmd_count;
 struct scst_percpu_info scst_percpu_infos[NR_CPUS];
 
+/* Protects the active and delayed management-command queues. */
 spinlock_t scst_mcmd_lock;
 struct list_head scst_active_mgmt_cmd_list;
 struct list_head scst_delayed_mgmt_cmd_list;
 wait_queue_head_t scst_mgmt_cmd_list_waitQ;
 
 wait_queue_head_t scst_mgmt_waitQ;
+/* Protects the session initialization and shutdown queues. */
 spinlock_t scst_mgmt_lock;
 struct list_head scst_sess_init_list;
 struct list_head scst_sess_shut_list;
@@ -162,6 +165,7 @@ static int scst_virt_dev_last_id; /* protected by scst_mutex */
 
 cpumask_t default_cpu_mask;
 
+/* Serializes read/replace operations on the latency-measurement mode. */
 spinlock_t scst_measure_latency_lock;
 atomic_t scst_measure_latency;
 
@@ -1773,6 +1777,7 @@ out_wait:
 		 */
 		wait_event(cmd_threads->ioctx_wq,
 			   cmd_threads->io_context_ready);
+		/* Pair with scst_ioctx_get() before sharing the initialized I/O context. */
 		smp_rmb();
 	}
 

scst/src/scst_priv.h

@@ -203,6 +203,7 @@ extern wait_queue_head_t scst_mgmt_cmd_list_waitQ;
 extern struct percpu_ref scst_cmd_count;
 extern struct percpu_ref scst_mcmd_count;
 struct scst_percpu_info {
+	/* Protects this CPU's tasklet command queue. */
 	spinlock_t tasklet_lock;
 	struct list_head tasklet_cmd_list;
 	struct tasklet_struct tasklet;
@@ -218,6 +219,7 @@ extern cpumask_t default_cpu_mask;
 
 struct scst_cmd_thread_t {
 	struct list_head thr_active_cmd_list;
+	/* Protects this thread's active command queue. */
 	spinlock_t thr_cmd_list_lock;
 	struct task_struct *cmd_thread;
 	struct scst_cmd_threads *thr_cmd_threads;

scst/src/scst_targ.c

@@ -1323,7 +1323,6 @@ set_res:
 			       "Atomic context and non-WRITE data direction, rescheduling (cmd %p)",
 			       cmd);
 		res = SCST_CMD_STATE_RES_NEED_THREAD;
-		/* fall through */
 	}
 #endif
 
@@ -4403,7 +4402,8 @@ int scst_init_thread(void *arg)
  * Note: A more elegant approach would be to allocate the I/O context in
  * scst_init_threads() instead of this function. That approach is only possible
  * though after exporting alloc_io_context(). A previous discussion of this
- * topic can be found here: http://lkml.org/lkml/2008/12/11/282.
+ * topic, including the proposed exports, can be found here:
+ * https://lore.kernel.org/lkml/20081211190627.GA23742@kernel.dk/
  */
 static void scst_ioctx_get(struct scst_cmd_threads *p_cmd_threads)
 {
@@ -4437,6 +4437,7 @@ static void scst_ioctx_get(struct scst_cmd_threads *p_cmd_threads)
 
 	mutex_unlock(&p_cmd_threads->io_context_mutex);
 
+	/* Publish the I/O context before the ready flag; waiters pair with smp_rmb(). */
 	smp_wmb();
 	p_cmd_threads->io_context_ready = true;
 }

scst_local/scst_local.c

@@ -112,11 +112,13 @@ struct scst_local_sess {
 
 	int number;
 
+	/* Protects transport_id replacement and access to its length/data. */
 	struct mutex tr_id_mutex;
 	u8 *transport_id;
 	int transport_id_len;
 
 	struct work_struct aen_work;
+	/* Protects the pending AEN work list. */
 	spinlock_t aen_lock;
 	struct list_head aen_work_list; /* protected by aen_lock */
 

srpt/src/ib_srpt.c

@@ -3025,7 +3025,7 @@ static void srpt_cm_rtu_recv(struct srpt_rdma_ch *ch)
 
 	/*
 	 * Note: calling srpt_close_ch() if the transition to the LIVE state
-	 * fails is not necessary since that means that that function has
+	 * fails is not necessary since that means that the function has
 	 * already been invoked from another thread.
 	 */
 	if (!srpt_set_ch_state(ch, CH_LIVE))

srpt/src/ib_srpt.h

@@ -421,6 +421,7 @@ struct srpt_rdma_ch {
 	int			req_lim;
 	int			req_lim_delta;
 	u16			imm_data_offset;
+	/* Protects channel state, request credits and the free send-context list. */
 	spinlock_t		spinlock;
 	struct list_head	free_list;
 	enum rdma_ch_state	state;
@@ -482,6 +483,7 @@ struct srpt_port {
 	union ib_gid		gid;
 	struct work_struct	work;
 	wait_queue_head_t	ch_release_waitq;
+	/* Protects port configuration, nexus/channel lists and login admission. */
 	struct mutex		mutex;
 	struct list_head	nexus_list;
 	struct scst_tgt		*scst_tgt;

usr/fileio/fileio.c

@@ -492,7 +492,7 @@ out_unreg:
 				res = errno;
 				PRINT_ERROR("Unable to unregister device: %s",
 					strerror(res));
-				/* fall through */
+				/* Close the descriptor even if unregistering failed. */
 			}
 		}
 		close(devs[i].scst_usr_fd);