[SCSI] docbook and kernel-doc updates

<book id="scsimid">

  <bookinfo>

    <title>SCSI Mid Layer Guide</title>

    <title>SCSI Interfaces Guide</title>

    <authorgroup>

      <author>

        The SCSI subsystem uses a three layer design, with upper, mid, and low

        layers.  Every operation involving the SCSI subsystem (such as reading

        a sector from a disk) uses one driver at each of the 3 levels: one

        upper layer driver, one lower layer driver, and the scsi midlayer.

        upper layer driver, one lower layer driver, and the SCSI midlayer.

      </para>

      <para>

        The SCSI upper layer provides the interface between userspace and the

      <sect2 id="scsi.c">

        <title>drivers/scsi/scsi.c</title>

        <para>Main file for the scsi midlayer.</para>

        <para>Main file for the SCSI midlayer.</para>

!Edrivers/scsi/scsi.c

      </sect2>

      <sect2 id="scsicam.c">

      <sect2 id="scsi_ioctl.c">

        <title>drivers/scsi/scsi_ioctl.c</title>

        <para>

          Handle ioctl() calls for scsi devices.

          Handle ioctl() calls for SCSI devices.

        </para>

!Edrivers/scsi/scsi_ioctl.c

      </sect2>

    <sect1 id="Transport_classes">

      <title>Transport classes</title>

      <para>

        Transport classes are service libraries for drivers in the scsi

        Transport classes are service libraries for drivers in the SCSI

        lower layer, which expose transport attributes in sysfs.

      </para>

      <sect2 id="Fibre_Channel_transport">

 * reference.  You must hold the host's host_lock over this call and

 * any access to the returned scsi_device.

 *

 * Note:  The only reason why drivers would want to use this is because

 * Note:  The only reason why drivers should use this is because

 * they need to access the device list in irq context.  Otherwise you

 * really want to use scsi_device_lookup_by_target instead.

 **/

 * @shost:	SCSI host to invoke error handling on.

 *

 * Schedule SCSI EH without scmd.

 **/

 */

void scsi_schedule_eh(struct Scsi_Host *shost)

{

	unsigned long flags;

 *

 * Return value:

 *	0 on failure.

 **/

 */

int scsi_eh_scmd_add(struct scsi_cmnd *scmd, int eh_flag)

{

	struct Scsi_Host *shost = scmd->device->host;

 *    This should be turned into an inline function.  Each scsi command

 *    has its own timer, and as it is added to the queue, we set up the

 *    timer.  When the command completes, we cancel the timer.

 **/

 */

void scsi_add_timer(struct scsi_cmnd *scmd, int timeout,

		    void (*complete)(struct scsi_cmnd *))

{

 * Return value:

 *     1 if we were able to detach the timer.  0 if we blew it, and the

 *     timer function has already started to run.

 **/

 */

int scsi_delete_timer(struct scsi_cmnd *scmd)

{

	int rtn;

 *     only in that the normal completion handling might run, but if the

 *     normal completion function determines that the timer has already

 *     fired, then it mustn't do anything.

 **/

 */

void scsi_times_out(struct scsi_cmnd *scmd)

{

	enum scsi_eh_timer_return (* eh_timed_out)(struct scsi_cmnd *);

 *

 * Return value:

 *     0 when dev was taken offline by error recovery. 1 OK to proceed.

 **/

 */

int scsi_block_when_processing_errors(struct scsi_device *sdev)

{

	int online;

 * scsi_eh_prt_fail_stats - Log info on failures.

 * @shost:	scsi host being recovered.

 * @work_q:	Queue of scsi cmds to process.

 **/

 */

static inline void scsi_eh_prt_fail_stats(struct Scsi_Host *shost,

					  struct list_head *work_q)

{

 * Notes:

 *	When a deferred error is detected the current command has

 *	not been executed and needs retrying.

 **/

 */

static int scsi_check_sense(struct scsi_cmnd *scmd)

{

	struct scsi_sense_hdr sshdr;

 *    queued during error recovery.  the main difference here is that we

 *    don't allow for the possibility of retries here, and we are a lot

 *    more restrictive about what we consider acceptable.

 **/

 */

static int scsi_eh_completed_normally(struct scsi_cmnd *scmd)

{

	/*

/**

 * scsi_eh_done - Completion function for error handling.

 * @scmd:	Cmd that is done.

 **/

 */

static void scsi_eh_done(struct scsi_cmnd *scmd)

{

	struct completion     *eh_action;

/**

 * scsi_try_host_reset - ask host adapter to reset itself

 * @scmd:	SCSI cmd to send hsot reset.

 **/

 */

static int scsi_try_host_reset(struct scsi_cmnd *scmd)

{

	unsigned long flags;

/**

 * scsi_try_bus_reset - ask host to perform a bus reset

 * @scmd:	SCSI cmd to send bus reset.

 **/

 */

static int scsi_try_bus_reset(struct scsi_cmnd *scmd)

{

	unsigned long flags;

 *    unreliable for a given host, then the host itself needs to put a

 *    timer on it, and set the host back to a consistent state prior to

 *    returning.

 **/

 */

static int scsi_try_bus_device_reset(struct scsi_cmnd *scmd)

{

	int rtn;

 *    author of the low-level driver wishes this operation to be timed,

 *    they can provide this facility themselves.  helper functions in

 *    scsi_error.c can be supplied to make this easier to do.

 **/

 */

static int scsi_try_to_abort_cmd(struct scsi_cmnd *scmd)

{

	/*

 * sent must be one that does not transfer any data.  If @sense_bytes != 0

 * @cmnd is ignored and this functions sets up a REQUEST_SENSE command

 * and cmnd buffers to read @sense_bytes into @scmd->sense_buffer.

 **/

 */

void scsi_eh_prep_cmnd(struct scsi_cmnd *scmd, struct scsi_eh_save *ses,

			unsigned char *cmnd, int cmnd_size, unsigned sense_bytes)

{

 * @ses:        saved information from a coresponding call to scsi_prep_eh_cmnd

 *

 * Undo any damage done by above scsi_prep_eh_cmnd().

 **/

 */

void scsi_eh_restore_cmnd(struct scsi_cmnd* scmd, struct scsi_eh_save *ses)

{

	/*

 *

 * Return value:

 *    SUCCESS or FAILED or NEEDS_RETRY

 **/

 */

static int scsi_send_eh_cmnd(struct scsi_cmnd *scmd, unsigned char *cmnd,

			     int cmnd_size, int timeout, unsigned sense_bytes)

{

 *    Some hosts automatically obtain this information, others require

 *    that we obtain it on our own. This function will *not* return until

 *    the command either times out, or it completes.

 **/

 */

static int scsi_request_sense(struct scsi_cmnd *scmd)

{

	return scsi_send_eh_cmnd(scmd, NULL, 0, SENSE_TIMEOUT, ~0);

 *    and that would disturb what we are doing.  Thus we really want to

 *    keep a list of pending commands for final completion, and once we

 *    are ready to leave error handling we handle completion for real.

 **/

 */

void scsi_eh_finish_cmd(struct scsi_cmnd *scmd, struct list_head *done_q)

{

	scmd->device->host->host_failed--;

 *

 *    XXX: Long term this code should go away, but that needs an audit of

 *         all LLDDs first.

 **/

 */

int scsi_eh_get_sense(struct list_head *work_q,

		      struct list_head *done_q)

{

 *

 * Return value:

 *    0 - Device is ready. 1 - Device NOT ready.

 **/

 */

static int scsi_eh_tur(struct scsi_cmnd *scmd)

{

	static unsigned char tur_command[6] = {TEST_UNIT_READY, 0, 0, 0, 0, 0};

 *    command that has timed out.  If the command simply failed, it makes

 *    no sense to try and abort the command, since as far as the shost

 *    adapter is concerned, it isn't running.

 **/

 */

static int scsi_eh_abort_cmds(struct list_head *work_q,

			      struct list_head *done_q)

{

 *

 * Return value:

 *    0 - Device is ready. 1 - Device NOT ready.

 **/

 */

static int scsi_eh_try_stu(struct scsi_cmnd *scmd)

{

	static unsigned char stu_command[6] = {START_STOP, 0, 0, 0, 1, 0};

 * Notes:

 *    If commands are failing due to not ready, initializing command required,

 *	try revalidating the device, which will end up sending a start unit. 

 **/

 */

static int scsi_eh_stu(struct Scsi_Host *shost,

			      struct list_head *work_q,

			      struct list_head *done_q)

 *    devices that are jammed or not - if we have multiple devices, it

 *    makes no sense to try bus_device_reset - we really would need to try

 *    a bus_reset instead. 

 **/

 */

static int scsi_eh_bus_device_reset(struct Scsi_Host *shost,

				    struct list_head *work_q,

				    struct list_head *done_q)

 * @shost:	&scsi host being recovered.

 * @work_q:     &list_head for pending commands.

 * @done_q:	&list_head for processed commands.

 **/

 */

static int scsi_eh_bus_reset(struct Scsi_Host *shost,

			     struct list_head *work_q,

			     struct list_head *done_q)

 * scsi_eh_host_reset - send a host reset 

 * @work_q:	list_head for processed commands.

 * @done_q:	list_head for processed commands.

 **/

 */

static int scsi_eh_host_reset(struct list_head *work_q,

			      struct list_head *done_q)

{

 * scsi_eh_offline_sdevs - offline scsi devices that fail to recover

 * @work_q:	list_head for processed commands.

 * @done_q:	list_head for processed commands.

 *

 **/

 */

static void scsi_eh_offline_sdevs(struct list_head *work_q,

				  struct list_head *done_q)

{

 *    is woken.  In cases where the error code indicates an error that

 *    doesn't require the error handler read (i.e. we don't need to

 *    abort/reset), this function should return SUCCESS.

 **/

 */

int scsi_decide_disposition(struct scsi_cmnd *scmd)

{

	int rtn;

 *

 *	If scsi_allocate_request() fails for what ever reason, we

 *	completely forget to lock the door.

 **/

 */

static void scsi_eh_lock_door(struct scsi_device *sdev)

{

	unsigned char cmnd[MAX_COMMAND_SIZE];

 * Notes:

 *    When we entered the error handler, we blocked all further i/o to

 *    this device.  we need to 'reverse' this process.

 **/

 */

static void scsi_restart_operations(struct Scsi_Host *shost)

{

	struct scsi_device *sdev;

 * @shost: 	host to be recovered.

 * @work_q:     &list_head for pending commands.

 * @done_q:	&list_head for processed commands.

 *

 **/

 */

void scsi_eh_ready_devs(struct Scsi_Host *shost,

			struct list_head *work_q,

			struct list_head *done_q)

/**

 * scsi_eh_flush_done_q - finish processed commands or retry them.

 * @done_q:	list_head of processed commands.

 *

 **/

 */

void scsi_eh_flush_done_q(struct list_head *done_q)

{

	struct scsi_cmnd *scmd, *next;

 *    scsi_finish_cmd() called for it.  we do all of the retry stuff

 *    here, so when we restart the host after we return it should have an

 *    empty queue.

 **/

 */

static void scsi_unjam_host(struct Scsi_Host *shost)

{

	unsigned long flags;

 * Notes:

 *    This is the main error handling loop.  This is run as a kernel thread

 *    for every SCSI host and handles all error handling activity.

 **/

 */

int scsi_error_handler(void *data)

{

	struct Scsi_Host *shost = data;

 *

 * Return value:

 *	1 if valid sense data information found, else 0;

 **/

 */

int scsi_normalize_sense(const u8 *sense_buffer, int sb_len,

                         struct scsi_sense_hdr *sshdr)

{

 *

 * Return value:

 *	pointer to start of (first) descriptor if found else NULL

 **/

 */

const u8 * scsi_sense_desc_find(const u8 * sense_buffer, int sb_len,

				int desc_type)

{

 *

 * Return value:

 *	1 if information field found, 0 if not found.

 **/

 */

int scsi_get_sense_info_fld(const u8 * sense_buffer, int sb_len,

			    u64 * info_out)

{

/**

 * srp_rport_add - add a SRP remote port to the device hierarchy

 *

 * @shost:	scsi host the remote port is connected to.

 * @ids:	The port id for the remote port.

 *

 * publishes a port to the rest of the system

 * Publishes a port to the rest of the system.

 */

struct srp_rport *srp_rport_add(struct Scsi_Host *shost,

				struct srp_rport_identifiers *ids)