SCSI/libsrp: document the libsrp source code

index 9ad38e8..0eeeca2 100644
@@ -29,6 +29,10 @@
 #include <scsi/srp.h>
 #include <scsi/libsrp.h>
 
+/*
+ * Allowed values for the 'TASK ATTRIBUTE' field of an SRP_CMD request. See
+ * also section 6.8 of the T10 SRP r16a document.
+ */
 enum srp_task_attributes {
 	SRP_SIMPLE_TASK = 0,
 	SRP_HEAD_TASK = 1,

@@ -44,6 +48,17 @@ do {								\
 /* #define dprintk eprintk */
 #define dprintk(fmt, args...)
 
+/**
+ * srp_iu_pool_alloc() - Allocate a pool of information units for use by an SRP
+ * target.
+ * @q: pointer to the pool structure that will be initialized.
+ * @max: number of information units the pool will contain.
+ * @ring: pointer to an array of 'max' SRP buffer pointers. Each information
+ *   unit allocated for the pool will be initialized such that it points to
+ *   the corresponding SRP buffer in array 'ring'.
+ *
+ * Returns zero upon success and a negative error code upon failure.
+ */
 static int srp_iu_pool_alloc(struct srp_queue *q, size_t max,
 			     struct srp_buf **ring)
 {

@@ -77,12 +92,28 @@ free_pool:
 	return -ENOMEM;
 }
 
+/**
+ * srp_iu_pool_free() - Free the memory allocated by srp_iu_pool_alloc().
+ * @q: SRP queue pointer.
+ *
+ * Note: The memory occupied by the struct srp_queue itself is not freed
+ * -- this is the responsibility of the caller.
+ */
 static void srp_iu_pool_free(struct srp_queue *q)
 {
 	kfree(q->items);
 	kfree(q->pool);
 }
 
+/**
+ * srp_ring_alloc() - Allocate a ring of SRP buffers and set up a coherent DMA
+ * mapping for each buffer.
+ * @dev: device context for DMA mapping.
+ * @max: number of elements the ring will contain.
+ * @size: size in bytes of one ring element.
+ *
+ * Returns a pointer to an array of 'max' pointers to SRP buffers.
+ */
 static struct srp_buf **srp_ring_alloc(struct device *dev,
 				       size_t max, size_t size)
 {

@@ -115,6 +146,13 @@ out:
 	return NULL;
 }
 
+/**
+ * srp_ring_free() - Free the memory allocated by srp_ring_alloc().
+ * @dev: device context for DMA unmapping.
+ * @ring: the buffer ring to be freed.
+ * @max: number of elements the ring contains.
+ * @size: size in bytes of one ring element.
+ */
 static void srp_ring_free(struct device *dev, struct srp_buf **ring, size_t max,
 			  size_t size)
 {

@@ -127,6 +165,16 @@ static void srp_ring_free(struct device *dev, struct srp_buf **ring, size_t max,
 	kfree(ring);
 }
 
+/**
+ * srp_target_alloc() - Initialize an SRP target structure and allocate an SRP
+ * information unit ring.
+ * @target: pointer to the SRP target structure to be initialized.
+ * @dev: device to be associated with the SRP target.
+ * @nr: number of elements the SRP receive ring will contain.
+ * @iu_size: size in bytes of a single information unit.
+ *
+ * Returns zero upon success and a negative error code upon failure.
+ */
 int srp_target_alloc(struct srp_target *target, struct device *dev,
 		     size_t nr, size_t iu_size)
 {

@@ -155,6 +203,10 @@ free_ring:
 }
 EXPORT_SYMBOL_GPL(srp_target_alloc);
 
+/**
+ * srp_target_free() - Free the memory allocated by srp_target_alloc().
+ * @target: SRP target.
+ */
 void srp_target_free(struct srp_target *target)
 {
 	srp_ring_free(target->dev, target->rx_ring, target->rx_ring_size,

@@ -163,6 +215,13 @@ void srp_target_free(struct srp_target *target)
 }
 EXPORT_SYMBOL_GPL(srp_target_free);
 
+/**
+ * srp_iu_get() - Get an information unit that is not in use.
+ * @target: SRP target to receive an information unit from.
+ *
+ * Initialize the ilist and flags members of the information unit before
+ * returning.
+ */
 struct iu_entry *srp_iu_get(struct srp_target *target)
 {
 	struct iu_entry *iue = NULL;

@@ -177,12 +236,27 @@ struct iu_entry *srp_iu_get(struct srp_target *target)
 }
 EXPORT_SYMBOL_GPL(srp_iu_get);
 
+/**
+ * srp_iu_put() - Put an information unit back in the SRP target receive ring.
+ * @iue: information unit to be put back.
+ */
 void srp_iu_put(struct iu_entry *iue)
 {
 	kfifo_put(iue->target->iu_queue.queue, (void *) &iue, sizeof(void *));
 }
 EXPORT_SYMBOL_GPL(srp_iu_put);
 
+/**
+ * srp_direct_data() - Transfer the data referred to by an SRP direct data
+ * buffer descriptor via RDMA.
+ * @sc: SCSI command.
+ * @md: SRP direct data buffer descriptor.
+ * @dir: DMA data direction, the second last parameter passed to the function
+ *       'rdma_io'.
+ * @rdma_io: pointer to a callback function that performs the actual I/O.
+ * @dma_map: whether or not to map and unmap the scsi_sglist(sc).
+ * @ext_desc: ignored.
+ */
 static int srp_direct_data(struct scsi_cmnd *sc, struct srp_direct_buf *md,
 			   enum dma_data_direction dir, srp_rdma_t rdma_io,
 			   int dma_map, int ext_desc)

@@ -216,6 +290,18 @@ static int srp_direct_data(struct scsi_cmnd *sc, struct srp_direct_buf *md,
 	return err;
 }
 
+/**
+ * srp_indirect_data() - Transfer the data referred to by an SRP indirect data
+ * buffer descriptor via RDMA.
+ * @sc: SCSI command.
+ * @cmd: SRP command.
+ * @id: SRP indirect data buffer descriptor.
+ * @dir: DMA data direction, the second last parameter passed to the function
+ *       'rdma_io'.
+ * @rdma_io: pointer to a callback function that performs the actual I/O.
+ * @dma_map: whether or not to map and unmap the scsi_sglist(sc).
+ * @ext_desc: whether or not this command uses an external indirect buffer.
+ */
 static int srp_indirect_data(struct scsi_cmnd *sc, struct srp_cmd *cmd,
 			     struct srp_indirect_buf *id,
 			     enum dma_data_direction dir, srp_rdma_t rdma_io,

@@ -292,6 +378,11 @@ free_mem:
 	return err;
 }
 
+/**
+ * data_out_desc_size() - Compute the number of bytes occupied by the DATA-OUT
+ * descriptor.
+ * @cmd: SRP_CMD request.
+ */
 static int data_out_desc_size(struct srp_cmd *cmd)
 {
 	int size = 0;

@@ -314,8 +405,17 @@ static int data_out_desc_size(struct srp_cmd *cmd)
 	return size;
 }
 
-/*
- * TODO: this can be called multiple times for a single command if it
+/**
+ * srp_transfer_data() - Transfer the data associated with an SRP_CMD request.
+ * @sc: SCSI command.
+ * @cmd: SRP_CMD request.
+ * @rdma_io: callback function for performing RDMA I/O.
+ * @dma_map: second-last parameter passed to rdma_io.
+ * @ext_desc: whether this command uses an external indirect buffer.
+ *
+ * Note: Does not support bidirectional commands.
+ *
+ * To Do: This function can be called multiple times for a single command if it
  * has very long data.
  */
 int srp_transfer_data(struct scsi_cmnd *sc, struct srp_cmd *cmd,

@@ -327,10 +427,23 @@ int srp_transfer_data(struct scsi_cmnd *sc, struct srp_cmd *cmd,
 	int offset, err = 0;
 	u8 format;
 
+	/*
+	 * 'offset' is the offset in bytes of the data buffer descriptor in
+	 * an SRP_CMD request. For an SRP request that transfers data from
+	 * initiator to target, 'offset' is the offset of the data-out buffer
+	 * descriptor. For an SRP request that transfers data from target to
+	 * initiator, 'offset' is the offset of the data-in buffer descriptor.
+	 * In an SRP_CMD request the following descriptors are present starting
+	 * from cmd->add_data: additional CDB, data-out buffer descriptor and
+	 * data-in buffer descriptor.
+	 */
+
+	/* Skip over 'additional CDB' to start of data-out descriptor. */
 	offset = cmd->add_cdb_len * 4;
 
 	dir = srp_cmd_direction(cmd);
 	if (dir == DMA_FROM_DEVICE)
+		/* Skip over data-out descriptor to start of data-in. */
 		offset += data_out_desc_size(cmd);
 
 	if (dir == DMA_TO_DEVICE)

@@ -361,6 +474,13 @@ int srp_transfer_data(struct scsi_cmnd *sc, struct srp_cmd *cmd,
 }
 EXPORT_SYMBOL_GPL(srp_transfer_data);
 
+/**
+ * vscsis_data_length() - Compute the size in bytes of one of the two data
+ * descriptors at the end of an SRP_CMD request.
+ * @cmd: SRP_CMD request.
+ * @dir: DMA_TO_DEVICE for the size of the data-out buffer descriptor;
+ * DMA_FROM_DEVICE for the size of the data-in buffer descriptor.
+ */
 static int vscsis_data_length(struct srp_cmd *cmd, enum dma_data_direction dir)
 {
 	struct srp_direct_buf *md;

@@ -393,6 +513,17 @@ static int vscsis_data_length(struct srp_cmd *cmd, enum dma_data_direction dir)
 	return len;
 }
 
+/**
+ * srp_cmd_queue() - Queue an SRP_CMD request for processing by appropriate
+ * target software, e.g. the user space process tgtd.
+ * @shost: pointer to SCSI host.
+ * @cmd: pointer to SRP_CMD request.
+ * @info: data that is copied to the SCp field of the generated SCSI command.
+ * @itn_id: ID that is passed verbatim to the callback functions registered
+ *   via struct srp_template (see also <scsi/scsi_transport.h>).
+ * @addr: scatter/gather list (struct scatterlist *) to be included in the
+ *   generated SCSI command.
+ */
 int srp_cmd_queue(struct Scsi_Host *shost, struct srp_cmd *cmd, void *info,
 		  u64 itn_id, u64 addr)
 {

98 lines not on this page · raw message

177 lines not on this page · raw message