From b0d3b8514abd2f49b479dc775a03725c25b2f11c Mon Sep 17 00:00:00 2001 From: Bart Van Assche Date: Tue, 22 Oct 2024 11:07:57 -0700 Subject: scsi: core: Update API documentation Since the .slave_alloc(), .slave_destroy() and .slave_configure() methods have been renamed in struct scsi_host_template, also rename these in the API documentation. Signed-off-by: Bart Van Assche Link: https://lore.kernel.org/r/20241022180839.2712439-6-bvanassche@acm.org Reviewed-by: Damien Le Maol Signed-off-by: Martin K. Petersen --- Documentation/scsi/scsi_mid_low_api.rst | 78 ++++++++++++++++----------------- 1 file changed, 39 insertions(+), 39 deletions(-) (limited to 'Documentation') diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 2df29b92e196..a93df7c3ae50 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -112,9 +112,9 @@ Those usages in group c) should be handled with care, especially in a that are shared with the mid level and other layers. All functions defined within an LLD and all data defined at file scope -should be static. For example the slave_alloc() function in an LLD +should be static. For example the sdev_init() function in an LLD called "xxx" could be defined as -``static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }`` +``static int xxx_sdev_init(struct scsi_device * sdev) { /* code */ }`` .. [#] the scsi_host_alloc() function is a replacement for the rather vaguely named scsi_register() function in most situations. @@ -149,21 +149,21 @@ scsi devices of which only the first 2 respond:: scsi_add_host() ----> scsi_scan_host() -------+ | - slave_alloc() - slave_configure() --> scsi_change_queue_depth() + sdev_init() + sdev_configure() --> scsi_change_queue_depth() | - slave_alloc() - slave_configure() + sdev_init() + sdev_configure() | - slave_alloc() *** - slave_destroy() *** + sdev_init() *** + sdev_destroy() *** *** For scsi devices that the mid level tries to scan but do not - respond, a slave_alloc(), slave_destroy() pair is called. + respond, a sdev_init(), sdev_destroy() pair is called. If the LLD wants to adjust the default queue settings, it can invoke -scsi_change_queue_depth() in its slave_configure() routine. +scsi_change_queue_depth() in its sdev_configure() routine. When an HBA is being removed it could be as part of an orderly shutdown associated with the LLD module being unloaded (e.g. with the "rmmod" @@ -176,8 +176,8 @@ same:: ===----------------------=========-----------------===------ scsi_remove_host() ---------+ | - slave_destroy() - slave_destroy() + sdev_destroy() + sdev_destroy() scsi_host_put() It may be useful for a LLD to keep track of struct Scsi_Host instances @@ -202,8 +202,8 @@ An LLD can use this sequence to make the mid level aware of a SCSI device:: ===-------------------=========--------------------===------ scsi_add_device() ------+ | - slave_alloc() - slave_configure() [--> scsi_change_queue_depth()] + sdev_init() + sdev_configure() [--> scsi_change_queue_depth()] In a similar fashion, an LLD may become aware that a SCSI device has been removed (unplugged) or the connection to it has been interrupted. Some @@ -218,12 +218,12 @@ upper layers with this sequence:: ===----------------------=========-----------------===------ scsi_remove_device() -------+ | - slave_destroy() + sdev_destroy() It may be useful for an LLD to keep track of struct scsi_device instances -(a pointer is passed as the parameter to slave_alloc() and -slave_configure() callbacks). Such instances are "owned" by the mid-level. -struct scsi_device instances are freed after slave_destroy(). +(a pointer is passed as the parameter to sdev_init() and +sdev_configure() callbacks). Such instances are "owned" by the mid-level. +struct scsi_device instances are freed after sdev_destroy(). Reference Counting @@ -331,7 +331,7 @@ Details:: * bus scan when an HBA is added (i.e. scsi_scan_host()). So it * should only be called if the HBA becomes aware of a new scsi * device (lu) after scsi_scan_host() has completed. If successful - * this call can lead to slave_alloc() and slave_configure() callbacks + * this call can lead to sdev_init() and sdev_configure() callbacks * into the LLD. * * Defined in: drivers/scsi/scsi_scan.c @@ -374,8 +374,8 @@ Details:: * Might block: no * * Notes: Can be invoked any time on a SCSI device controlled by this - * LLD. [Specifically during and after slave_configure() and prior to - * slave_destroy().] Can safely be invoked from interrupt code. + * LLD. [Specifically during and after sdev_configure() and prior to + * sdev_destroy().] Can safely be invoked from interrupt code. * * Defined in: drivers/scsi/scsi.c [see source code for more notes] * @@ -506,7 +506,7 @@ Details:: * Notes: If an LLD becomes aware that a scsi device (lu) has * been removed but its host is still present then it can request * the removal of that scsi device. If successful this call will - * lead to the slave_destroy() callback being invoked. sdev is an + * lead to the sdev_destroy() callback being invoked. sdev is an * invalid pointer after this call. * * Defined in: drivers/scsi/scsi_sysfs.c . @@ -627,14 +627,14 @@ Interface functions are supplied (defined) by LLDs and their function pointers are placed in an instance of struct scsi_host_template which is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()]. Some are mandatory. Interface functions should be declared static. The -accepted convention is that driver "xyz" will declare its slave_configure() +accepted convention is that driver "xyz" will declare its sdev_configure() function as:: - static int xyz_slave_configure(struct scsi_device * sdev); + static int xyz_sdev_configure(struct scsi_device * sdev); and so forth for all interface functions listed below. -A pointer to this function should be placed in the 'slave_configure' member +A pointer to this function should be placed in the 'sdev_configure' member of a "struct scsi_host_template" instance. A pointer to such an instance should be passed to the mid level's scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()]. @@ -657,9 +657,9 @@ Summary: - ioctl - driver can respond to ioctls - proc_info - supports /proc/scsi/{driver_name}/{host_no} - queuecommand - queue scsi command, invoke 'done' on completion - - slave_alloc - prior to any commands being sent to a new device - - slave_configure - driver fine tuning for given device after attach - - slave_destroy - given device is about to be shut down + - sdev_init - prior to any commands being sent to a new device + - sdev_configure - driver fine tuning for given device after attach + - sdev_destroy - given device is about to be shut down Details:: @@ -960,7 +960,7 @@ Details:: /** - * slave_alloc - prior to any commands being sent to a new device + * sdev_init - prior to any commands being sent to a new device * (i.e. just prior to scan) this call is made * @sdp: pointer to new device (about to be scanned) * @@ -975,24 +975,24 @@ Details:: * prior to its initial scan. The corresponding scsi device may not * exist but the mid level is just about to scan for it (i.e. send * and INQUIRY command plus ...). If a device is found then - * slave_configure() will be called while if a device is not found - * slave_destroy() is called. + * sdev_configure() will be called while if a device is not found + * sdev_destroy() is called. * For more details see the include/scsi/scsi_host.h file. * * Optionally defined in: LLD **/ - int slave_alloc(struct scsi_device *sdp) + int sdev_init(struct scsi_device *sdp) /** - * slave_configure - driver fine tuning for given device just after it + * sdev_configure - driver fine tuning for given device just after it * has been first scanned (i.e. it responded to an * INQUIRY) * @sdp: device that has just been attached * * Returns 0 if ok. Any other return is assumed to be an error and * the device is taken offline. [offline devices will _not_ have - * slave_destroy() called on them so clean up resources.] + * sdev_destroy() called on them so clean up resources.] * * Locks: none * @@ -1004,11 +1004,11 @@ Details:: * * Optionally defined in: LLD **/ - int slave_configure(struct scsi_device *sdp) + int sdev_configure(struct scsi_device *sdp) /** - * slave_destroy - given device is about to be shut down. All + * sdev_destroy - given device is about to be shut down. All * activity has ceased on this device. * @sdp: device that is about to be shut down * @@ -1023,12 +1023,12 @@ Details:: * by this driver for given device should be freed now. No further * commands will be sent for this sdp instance. [However the device * could be re-attached in the future in which case a new instance - * of struct scsi_device would be supplied by future slave_alloc() - * and slave_configure() calls.] + * of struct scsi_device would be supplied by future sdev_init() + * and sdev_configure() calls.] * * Optionally defined in: LLD **/ - void slave_destroy(struct scsi_device *sdp) + void sdev_destroy(struct scsi_device *sdp) -- cgit From 8d14bfb539522fff4cc0f90cd3c402d5aeef3c6a Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 4 Dec 2024 19:13:07 -0800 Subject: scsi: docs: Remove init_this_scsi_driver() Finish removing mention of init_this_scsi_driver() that was removed ages ago. Fixes: 83c9f08e6c6a ("scsi: remove the old scsi_module.c initialization model") Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20241205031307.130441-1-rdunlap@infradead.org Cc: Christoph Hellwig Cc: Martin K. Petersen Cc: James E.J. Bottomley Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Martin K. Petersen --- Documentation/scsi/scsi_mid_low_api.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) (limited to 'Documentation') diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index a93df7c3ae50..941680487e90 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -625,7 +625,7 @@ Interface Functions =================== Interface functions are supplied (defined) by LLDs and their function pointers are placed in an instance of struct scsi_host_template which -is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()]. +is passed to scsi_host_alloc() or scsi_register(). Some are mandatory. Interface functions should be declared static. The accepted convention is that driver "xyz" will declare its sdev_configure() function as:: @@ -636,8 +636,8 @@ and so forth for all interface functions listed below. A pointer to this function should be placed in the 'sdev_configure' member of a "struct scsi_host_template" instance. A pointer to such an instance -should be passed to the mid level's scsi_host_alloc() [or scsi_register() / -init_this_scsi_driver()]. +should be passed to the mid level's scsi_host_alloc() or scsi_register(). +. The interface functions are also described in the include/scsi/scsi_host.h file immediately above their definition point in "struct scsi_host_template". @@ -817,10 +817,6 @@ Details:: * The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this * function (or struct Scsi_Host::name if this function is not * available). - * In a similar manner, init_this_scsi_driver() outputs to the console - * each host's "info" (or name) for the driver it is registering. - * Also if proc_info() is not supplied, the output of this function - * is used instead. * * Optionally defined in: LLD **/ -- cgit From c17618cf664ddf54b264ea74df9e8ab3e3ceda3b Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Wed, 4 Dec 2024 20:18:39 -0800 Subject: scsi: Eliminate scsi_register() and scsi_unregister() usage & docs scsi_mid_low_api.rst refers to scsi_register() and scsi_unregister() but these functions don't exist. They have been replaced by more meaningful names. Update one driver (megaraid_mbox.c) that uses "scsi_unregister" in a warning message. Update scsi_mid_low_api.rst to eliminate references to scsi_register() and scsi_unregister(). Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20241205041839.164404-1-rdunlap@infradead.org Cc: James E.J. Bottomley Cc: Martin K. Petersen Cc: Bart Van Assche Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Kashyap Desai Cc: Sumit Saxena Cc: Shivasharan S Cc: Chandrakanth patil Cc: megaraidlinux.pdl@broadcom.com Signed-off-by: Martin K. Petersen --- Documentation/scsi/scsi_mid_low_api.rst | 55 +++------------------------------ 1 file changed, 5 insertions(+), 50 deletions(-) (limited to 'Documentation') diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 941680487e90..9d15e20b0b5e 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -101,7 +101,7 @@ supplied functions" below. Those functions in group b) are listed in a section entitled "Interface functions" below. Their function pointers are placed in the members of "struct scsi_host_template", an instance of which is passed to -scsi_host_alloc() [#]_. Those interface functions that the LLD does not +scsi_host_alloc(). Those interface functions that the LLD does not wish to supply should have NULL placed in the corresponding member of struct scsi_host_template. Defining an instance of struct scsi_host_template at file scope will cause NULL to be placed in function @@ -116,9 +116,6 @@ should be static. For example the sdev_init() function in an LLD called "xxx" could be defined as ``static int xxx_sdev_init(struct scsi_device * sdev) { /* code */ }`` -.. [#] the scsi_host_alloc() function is a replacement for the rather vaguely - named scsi_register() function in most situations. - Hotplug initialization model ============================ @@ -302,14 +299,12 @@ Summary: - scsi_host_alloc - return a new scsi_host instance whose refcount==1 - scsi_host_get - increments Scsi_Host instance's refcount - scsi_host_put - decrements Scsi_Host instance's refcount (free if 0) - - scsi_register - create and register a scsi host adapter instance. - scsi_remove_device - detach and remove a SCSI device - scsi_remove_host - detach and remove all SCSI devices owned by host - scsi_report_bus_reset - report scsi _bus_ reset observed - scsi_scan_host - scan SCSI bus - scsi_track_queue_full - track successive QUEUE_FULL events - scsi_unblock_requests - allow further commands to be queued to given host - - scsi_unregister - [calls scsi_host_put()] Details:: @@ -474,27 +469,6 @@ Details:: void scsi_host_put(struct Scsi_Host *shost) - /** - * scsi_register - create and register a scsi host adapter instance. - * @sht: pointer to scsi host template - * @privsize: extra bytes to allocate in hostdata array (which is the - * last member of the returned Scsi_Host instance) - * - * Returns pointer to new Scsi_Host instance or NULL on failure - * - * Might block: yes - * - * Notes: When this call returns to the LLD, the SCSI bus scan on - * this host has _not_ yet been done. - * The hostdata array (by default zero length) is a per host scratch - * area for the LLD. - * - * Defined in: drivers/scsi/hosts.c . - **/ - struct Scsi_Host * scsi_register(struct scsi_host_template * sht, - int privsize) - - /** * scsi_remove_device - detach and remove a SCSI device * @sdev: a pointer to a scsi device instance @@ -524,7 +498,7 @@ Details:: * * Notes: Should only be invoked if the "hotplug initialization * model" is being used. It should be called _prior_ to - * scsi_unregister(). + * calling scsi_host_put(). * * Defined in: drivers/scsi/hosts.c . **/ @@ -601,31 +575,12 @@ Details:: void scsi_unblock_requests(struct Scsi_Host * shost) - /** - * scsi_unregister - unregister and free memory used by host instance - * @shp: pointer to scsi host instance to unregister. - * - * Returns nothing - * - * Might block: no - * - * Notes: Should not be invoked if the "hotplug initialization - * model" is being used. Called internally by exit_this_scsi_driver() - * in the "passive initialization model". Hence a LLD has no need to - * call this function directly. - * - * Defined in: drivers/scsi/hosts.c . - **/ - void scsi_unregister(struct Scsi_Host * shp) - - - Interface Functions =================== Interface functions are supplied (defined) by LLDs and their function pointers are placed in an instance of struct scsi_host_template which -is passed to scsi_host_alloc() or scsi_register(). +is passed to scsi_host_alloc(). Some are mandatory. Interface functions should be declared static. The accepted convention is that driver "xyz" will declare its sdev_configure() function as:: @@ -636,7 +591,7 @@ and so forth for all interface functions listed below. A pointer to this function should be placed in the 'sdev_configure' member of a "struct scsi_host_template" instance. A pointer to such an instance -should be passed to the mid level's scsi_host_alloc() or scsi_register(). +should be passed to the mid level's scsi_host_alloc(). . The interface functions are also described in the include/scsi/scsi_host.h @@ -1111,7 +1066,7 @@ of interest: hostdata[0] - area reserved for LLD at end of struct Scsi_Host. Size is set by the second argument (named 'xtr_bytes') to - scsi_host_alloc() or scsi_register(). + scsi_host_alloc(). vendor_id - a unique value that identifies the vendor supplying the LLD for the Scsi_Host. Used most often in validating -- cgit From a9dcee18a2200ee6c273ef9e0915b83179cc2ff3 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Thu, 19 Dec 2024 13:49:28 -0800 Subject: scsi: documentation: scsi_eh: updates for EH changes SCSI_SOFTIRQ and scsi_softirq() are no longer used. Change to block layer equivalents. scsi_setup_cmd_retry() has been deleted. Remove references to it. SCSI_EH_CANCEL_CMD has been deleted. Remove references to it. scsi_eh_abort_cmds() has been deleted. Remove references to it. [mkp: fixed START STOP UNIT] Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20241219214928.1170302-1-rdunlap@infradead.org Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: James E.J. Bottomley Cc: Martin K. Petersen Signed-off-by: Martin K. Petersen --- Documentation/scsi/scsi_eh.rst | 46 +++++++++--------------------------------- 1 file changed, 9 insertions(+), 37 deletions(-) (limited to 'Documentation') diff --git a/Documentation/scsi/scsi_eh.rst b/Documentation/scsi/scsi_eh.rst index 104d09e9af09..36cff176c5e6 100644 --- a/Documentation/scsi/scsi_eh.rst +++ b/Documentation/scsi/scsi_eh.rst @@ -54,13 +54,13 @@ invoking hostt->queuecommand() or the block layer will time it out. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For all non-EH commands, scsi_done() is the completion callback. It -just calls blk_complete_request() to delete the block layer timer and -raise SCSI_SOFTIRQ +just calls blk_mq_complete_request() to delete the block layer timer and +raise BLOCK_SOFTIRQ. -SCSI_SOFTIRQ handler scsi_softirq calls scsi_decide_disposition() to -determine what to do with the command. scsi_decide_disposition() -looks at the scmd->result value and sense data to determine what to do -with the command. +The BLOCK_SOFTIRQ indirectly calls scsi_complete(), which calls +scsi_decide_disposition() to determine what to do with the command. +scsi_decide_disposition() looks at the scmd->result value and sense +data to determine what to do with the command. - SUCCESS @@ -110,7 +110,7 @@ The timeout handler is scsi_timeout(). When a timeout occurs, this function retry which failed), when retries are exceeded, or when the EH deadline is expired. In these cases Step #3 is taken. - 3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the + 3. scsi_eh_scmd_add(scmd) is invoked for the command. See [1-4] for more information. 1.3 Asynchronous command aborts @@ -277,7 +277,6 @@ scmd->allowed. :ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd - - scsi_setup_cmd_retry() - move from local eh_work_q to local eh_done_q :LOCKING: none @@ -317,7 +316,7 @@ scmd->allowed. ``scsi_eh_get_sense`` This action is taken for each error-completed - (!SCSI_EH_CANCEL_CMD) commands without valid sense data. Most + command without valid sense data. Most SCSI transports/LLDDs automatically acquire sense data on command failures (autosense). Autosense is recommended for performance reasons and as sense information could get out of @@ -347,30 +346,6 @@ scmd->allowed. - otherwise No action. - 3. If !list_empty(&eh_work_q), invoke scsi_eh_abort_cmds(). - - ``scsi_eh_abort_cmds`` - - This action is taken for each timed out command when - no_async_abort is enabled in the host template. - hostt->eh_abort_handler() is invoked for each scmd. The - handler returns SUCCESS if it has succeeded to make LLDD and - all related hardware forget about the scmd. - - If a timedout scmd is successfully aborted and the sdev is - either offline or ready, scsi_eh_finish_cmd() is invoked for - the scmd. Otherwise, the scmd is left in eh_work_q for - higher-severity actions. - - Note that both offline and ready status mean that the sdev is - ready to process new scmds, where processing also implies - immediate failing; thus, if a sdev is in one of the two - states, no further recovery action is needed. - - Device readiness is tested using scsi_eh_tur() which issues - TEST_UNIT_READY command. Note that the scmd must have been - aborted successfully before reusing it for TEST_UNIT_READY. - 4. If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs() ``scsi_eh_ready_devs`` @@ -384,7 +359,7 @@ scmd->allowed. For each sdev which has failed scmds with valid sense data of which scsi_check_sense()'s verdict is FAILED, - START_STOP_UNIT command is issued w/ start=1. Note that + START STOP UNIT command is issued w/ start=1. Note that as we explicitly choose error-completed scmds, it is known that lower layers have forgotten about the scmd and we can reuse it for STU. @@ -478,9 +453,6 @@ except for #1 must be implemented by eh_strategy_handler(). - shost->host_failed is zero. - - Each scmd is in such a state that scsi_setup_cmd_retry() on the - scmd doesn't make any difference. - - shost->eh_cmd_q is cleared. - Each scmd->eh_entry is cleared. -- cgit From defb7541dac0e0da862421297685425ab9ee89b2 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 17 Dec 2024 16:07:48 -0800 Subject: scsi: driver-api: documentation: Change what is added to docbook For scsi_devinfo.c, use :export: so that exported symbols are put into the docbook. Drop :internal: -- they aren't needed in the docbook. For scsi_proc.c, drop :internal:. This will cause all documented private (as is already done) and exported symbols to be added to the docbook. For scsi_scan.c, switch from :internal: to :export: so that exported symbols are put into the generated docbook. Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20241218000748.932850-1-rdunlap@infradead.org Cc: James E.J. Bottomley Cc: Martin K. Petersen Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Martin K. Petersen --- Documentation/driver-api/scsi.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 273281474c09..bf2be96cc2d6 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -126,7 +126,7 @@ Manage scsi_dev_info_list, which tracks blacklisted and whitelisted devices. .. kernel-doc:: drivers/scsi/scsi_devinfo.c - :internal: + :export: drivers/scsi/scsi_ioctl.c ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -162,7 +162,6 @@ statistics and to pass information directly to the lowlevel driver. I.E. plumbing to manage /proc/scsi/\* .. kernel-doc:: drivers/scsi/scsi_proc.c - :internal: drivers/scsi/scsi_netlink.c ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -193,7 +192,7 @@ else, sequentially scan LUNs up until some maximum is reached, or a LUN is seen that cannot have a device attached to it. .. kernel-doc:: drivers/scsi/scsi_scan.c - :internal: + :export: drivers/scsi/scsi_sysctl.c ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit From d102c6d589c29c220fd11808381df11a4501647f Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 21 Dec 2024 13:25:39 -0800 Subject: scsi: documentation: Corrections for struct updates Update scsi_mid_low_api.rst for changes to struct scsi_host and struct scsi_cmnd. struct scsi_host: - no_async_abort is gone - drop sh_list w/ no replacement - change my_devices to __devices struct scsi_cmnd: - removed 'done' (now in struct scsi_driver); use scsi_done() or scsi_done_direct() callbacks - change previous request_bufflen to scsi_bufflen() - change previous use_sg field to scsi_dma_map() or scsi_sg_count() - change previous request_buffer field to reference to 'usg_sg' text [mkp: removed more obsolete stuff] Signed-off-by: Randy Dunlap Link: https://lore.kernel.org/r/20241221212539.1314560-1-rdunlap@infradead.org Cc: James E.J. Bottomley Cc: Martin K. Petersen Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Signed-off-by: Martin K. Petersen --- Documentation/scsi/scsi_mid_low_api.rst | 67 +++++++++------------------------ 1 file changed, 18 insertions(+), 49 deletions(-) (limited to 'Documentation') diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst index 9d15e20b0b5e..3cd6dce98e74 100644 --- a/Documentation/scsi/scsi_mid_low_api.rst +++ b/Documentation/scsi/scsi_mid_low_api.rst @@ -683,11 +683,7 @@ Details:: * * Calling context: kernel thread * - * Notes: If 'no_async_abort' is defined this callback - * will be invoked from scsi_eh thread. No other commands - * will then be queued on current host during eh. - * Otherwise it will be called whenever scsi_timeout() - * is called due to a command timeout. + * Notes: This is called only for a command that has timed out. * * Optionally defined in: LLD **/ @@ -990,7 +986,7 @@ struct scsi_host_template There is one "struct scsi_host_template" instance per LLD [#]_. It is typically initialized as a file scope static in a driver's header file. That way members that are not explicitly initialized will be set to 0 or NULL. -Member of interest: +Members of interest: name - name of driver (may contain spaces, please limit to @@ -1006,6 +1002,13 @@ Member of interest: - primary callback that the mid level uses to inject SCSI commands into an LLD. + vendor_id + - a unique value that identifies the vendor supplying + the LLD for the Scsi_Host. Used most often in validating + vendor-specific message requests. Value consists of an + identifier type and a vendor-specific value. + See scsi_netlink.h for a description of valid formats. + The structure is defined and commented in include/scsi/scsi_host.h .. [#] In extreme situations a single driver may have several instances @@ -1046,9 +1049,6 @@ of interest: - maximum number of commands that can be queued on devices controlled by the host. Overridden by LLD calls to scsi_change_queue_depth(). - no_async_abort - - 1=>Asynchronous aborts are not supported - - 0=>Timed-out commands will be aborted asynchronously hostt - pointer to driver's struct scsi_host_template from which this struct Scsi_Host instance was spawned @@ -1057,22 +1057,10 @@ of interest: transportt - pointer to driver's struct scsi_transport_template instance (if any). FC and SPI transports currently supported. - sh_list - - a double linked list of pointers to all struct Scsi_Host - instances (currently ordered by ascending host_no) - my_devices - - a double linked list of pointers to struct scsi_device - instances that belong to this host. hostdata[0] - area reserved for LLD at end of struct Scsi_Host. Size - is set by the second argument (named 'xtr_bytes') to + is set by the second argument (named 'privsize') to scsi_host_alloc(). - vendor_id - - a unique value that identifies the vendor supplying - the LLD for the Scsi_Host. Used most often in validating - vendor-specific message requests. Value consists of an - identifier type and a vendor-specific value. - See scsi_netlink.h for a description of valid formats. The scsi_host structure is defined in include/scsi/scsi_host.h @@ -1094,30 +1082,11 @@ Members of interest: cmnd - array containing SCSI command - cmnd_len + cmd_len - length (in bytes) of SCSI command sc_data_direction - direction of data transfer in data phase. See "enum dma_data_direction" in include/linux/dma-mapping.h - request_bufflen - - number of data bytes to transfer (0 if no data phase) - use_sg - - ==0 -> no scatter gather list, hence transfer data - to/from request_buffer - - >0 -> scatter gather list (actually an array) in - request_buffer with use_sg elements - request_buffer - - either contains data buffer or scatter gather list - depending on the setting of use_sg. Scatter gather - elements are defined by 'struct scatterlist' found - in include/linux/scatterlist.h . - done - - function pointer that should be invoked by LLD when the - SCSI command is completed (successfully or otherwise). - Should only be called by an LLD if the LLD has accepted - the command (i.e. queuecommand() returned or will return - 0). The LLD may invoke 'done' prior to queuecommand() - finishing. result - should be set by LLD prior to calling 'done'. A value of 0 implies a successfully completed command (and all @@ -1140,13 +1109,13 @@ Members of interest: device - pointer to scsi_device object that this command is associated with. - resid + resid_len (access by calling scsi_set_resid() / scsi_get_resid()) - an LLD should set this unsigned integer to the requested transfer length (i.e. 'request_bufflen') less the number - of bytes that are actually transferred. 'resid' is + of bytes that are actually transferred. 'resid_len' is preset to 0 so an LLD can ignore it if it cannot detect underruns (overruns should not be reported). An LLD - should set 'resid' prior to invoking 'done'. The most + should set 'resid_len' prior to invoking 'done'. The most interesting case is data transfers from a SCSI target device (e.g. READs) that underrun. underflow @@ -1155,10 +1124,10 @@ Members of interest: figure. Not many LLDs implement this check and some that do just output an error message to the log rather than report a DID_ERROR. Better for an LLD to implement - 'resid'. + 'resid_len'. -It is recommended that a LLD set 'resid' on data transfers from a SCSI -target device (e.g. READs). It is especially important that 'resid' is set +It is recommended that a LLD set 'resid_len' on data transfers from a SCSI +target device (e.g. READs). It is especially important that 'resid_len' is set when such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR (and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much data has been received then the safest approach is to indicate no bytes have @@ -1168,7 +1137,7 @@ a LLD might use these helpers:: scsi_set_resid(SCpnt, scsi_bufflen(SCpnt)); where 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512 -bytes blocks has been received 'resid' could be set like this:: +bytes blocks have been received 'resid_len' could be set like this:: scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512)); -- cgit