[SCSI] Add Documentation and integrate into docbook build
Add Documentation/DocBook/scsi_midlayer.tmpl, add to Makefile, and update
lots of kerneldoc comments in drivers/scsi/*.
Updated with comments from Stefan Richter, Stephen M. Cameron,
James Bottomley and Randy Dunlap.
Signed-off-by: Rob Landley <rob@landley.net>
Signed-off-by: James Bottomley <James.Bottomley@HansenPartnership.com>
diff --git a/drivers/scsi/scsi_lib.c b/drivers/scsi/scsi_lib.c
index a9ac5b1..199b024 100644
--- a/drivers/scsi/scsi_lib.c
+++ b/drivers/scsi/scsi_lib.c
@@ -175,7 +175,7 @@
*
* returns the req->errors value which is the scsi_cmnd result
* field.
- **/
+ */
int scsi_execute(struct scsi_device *sdev, const unsigned char *cmd,
int data_direction, void *buffer, unsigned bufflen,
unsigned char *sense, int timeout, int retries, int flags)
@@ -274,7 +274,7 @@
/**
* scsi_req_map_sg - map a scatterlist into a request
* @rq: request to fill
- * @sg: scatterlist
+ * @sgl: scatterlist
* @nsegs: number of elements
* @bufflen: len of buffer
* @gfp: memory allocation flags
@@ -365,14 +365,16 @@
* @sdev: scsi device
* @cmd: scsi command
* @cmd_len: length of scsi cdb
- * @data_direction: data direction
+ * @data_direction: DMA_TO_DEVICE, DMA_FROM_DEVICE, or DMA_NONE
* @buffer: data buffer (this can be a kernel buffer or scatterlist)
* @bufflen: len of buffer
* @use_sg: if buffer is a scatterlist this is the number of elements
* @timeout: request timeout in seconds
* @retries: number of times to retry request
- * @flags: or into request flags
- **/
+ * @privdata: data passed to done()
+ * @done: callback function when done
+ * @gfp: memory allocation flags
+ */
int scsi_execute_async(struct scsi_device *sdev, const unsigned char *cmd,
int cmd_len, int data_direction, void *buffer, unsigned bufflen,
int use_sg, int timeout, int retries, void *privdata,
@@ -1804,7 +1806,7 @@
* @timeout: command timeout
* @retries: number of retries before failing
* @data: returns a structure abstracting the mode header data
- * @sense: place to put sense data (or NULL if no sense to be collected).
+ * @sshdr: place to put sense data (or NULL if no sense to be collected).
* must be SCSI_SENSE_BUFFERSIZE big.
*
* Returns zero if successful; negative error number or scsi
@@ -1871,8 +1873,7 @@
EXPORT_SYMBOL_GPL(scsi_mode_select);
/**
- * scsi_mode_sense - issue a mode sense, falling back from 10 to
- * six bytes if necessary.
+ * scsi_mode_sense - issue a mode sense, falling back from 10 to six bytes if necessary.
* @sdev: SCSI device to be queried
* @dbd: set if mode sense will allow block descriptors to be returned
* @modepage: mode page being requested
@@ -1881,13 +1882,13 @@
* @timeout: command timeout
* @retries: number of retries before failing
* @data: returns a structure abstracting the mode header data
- * @sense: place to put sense data (or NULL if no sense to be collected).
+ * @sshdr: place to put sense data (or NULL if no sense to be collected).
* must be SCSI_SENSE_BUFFERSIZE big.
*
* Returns zero if unsuccessful, or the header offset (either 4
* or 8 depending on whether a six or ten byte command was
* issued) if successful.
- **/
+ */
int
scsi_mode_sense(struct scsi_device *sdev, int dbd, int modepage,
unsigned char *buffer, int len, int timeout, int retries,
@@ -2007,14 +2008,13 @@
EXPORT_SYMBOL(scsi_test_unit_ready);
/**
- * scsi_device_set_state - Take the given device through the device
- * state model.
+ * scsi_device_set_state - Take the given device through the device state model.
* @sdev: scsi device to change the state of.
* @state: state to change to.
*
* Returns zero if unsuccessful or an error if the requested
* transition is illegal.
- **/
+ */
int
scsi_device_set_state(struct scsi_device *sdev, enum scsi_device_state state)
{
@@ -2264,7 +2264,7 @@
* Must be called with user context, may sleep.
*
* Returns zero if unsuccessful or an error if not.
- **/
+ */
int
scsi_device_quiesce(struct scsi_device *sdev)
{
@@ -2289,7 +2289,7 @@
* queues.
*
* Must be called with user context, may sleep.
- **/
+ */
void
scsi_device_resume(struct scsi_device *sdev)
{
@@ -2326,8 +2326,7 @@
EXPORT_SYMBOL(scsi_target_resume);
/**
- * scsi_internal_device_block - internal function to put a device
- * temporarily into the SDEV_BLOCK state
+ * scsi_internal_device_block - internal function to put a device temporarily into the SDEV_BLOCK state
* @sdev: device to block
*
* Block request made by scsi lld's to temporarily stop all
@@ -2342,7 +2341,7 @@
* state, all commands are deferred until the scsi lld reenables
* the device with scsi_device_unblock or device_block_tmo fires.
* This routine assumes the host_lock is held on entry.
- **/
+ */
int
scsi_internal_device_block(struct scsi_device *sdev)
{
@@ -2382,7 +2381,7 @@
* (which must be a legal transition) allowing the midlayer to
* goose the queue for this device. This routine assumes the
* host_lock is held upon entry.
- **/
+ */
int
scsi_internal_device_unblock(struct scsi_device *sdev)
{
@@ -2460,7 +2459,7 @@
/**
* scsi_kmap_atomic_sg - find and atomically map an sg-elemnt
- * @sg: scatter-gather list
+ * @sgl: scatter-gather list
* @sg_count: number of segments in sg
* @offset: offset in bytes into sg, on return offset into the mapped area
* @len: bytes to map, on return number of bytes mapped
@@ -2509,8 +2508,7 @@
EXPORT_SYMBOL(scsi_kmap_atomic_sg);
/**
- * scsi_kunmap_atomic_sg - atomically unmap a virtual address, previously
- * mapped with scsi_kmap_atomic_sg
+ * scsi_kunmap_atomic_sg - atomically unmap a virtual address, previously mapped with scsi_kmap_atomic_sg
* @virt: virtual address to be unmapped
*/
void scsi_kunmap_atomic_sg(void *virt)
