[PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[Christoph Hellwig]

Index: linux-2.6/drivers/block/ll_rw_blk.c
===================================================================
--- linux-2.6.orig/drivers/block/ll_rw_blk.c	2005-06-18 17:49:09.000000000 +0200
+++ linux-2.6/drivers/block/ll_rw_blk.c	2005-06-18 17:55:28.000000000 +0200
@@ -2090,7 +2090,7 @@
 /**
  * blk_rq_map_user - map user data to a request, for REQ_BLOCK_PC usage
  * @q:		request queue where request should be inserted
- * @rw:		READ or WRITE data
+ * @rq:		request structure to fill
  * @ubuf:	the user buffer
  * @len:	length of user data
  *
@@ -2098,14 +2098,14 @@
  *    Data will be mapped directly for zero copy io, if possible. Otherwise
  *    a kernel bounce buffer is used.
  *
- *    A matching blk_rq_unmap_user() must be issued at the end of io, while
- *    still in process context.
+ *    A matching blk_rq_unmap_user_iov() must be issued at the end of io,
+ *    while still in process context.
  *
  *    Note: The mapped bio may need to be bounced through blk_queue_bounce()
  *    before being submitted to the device, as pages mapped may be out of
  *    reach. It's the callers responsibility to make sure this happens. The
- *    original bio must be passed back in to blk_rq_unmap_user() for proper
- *    unmapping.
+ *    original bio must be passed back in to blk_rq_unmap_user_iov() for
+ *    proper unmapping.
  */
 int blk_rq_map_user(request_queue_t *q, struct request *rq, void __user *ubuf,
 		    unsigned int len)
@@ -2194,13 +2194,12 @@
 EXPORT_SYMBOL(blk_rq_map_user_iov);
 
 /**
- * blk_rq_unmap_user - unmap a request with user data
- * @rq:		request to be unmapped
- * @bio:	bio for the request
+ * blk_rq_unmap_user - unmap a bio with user data
+ * @bio:	bio to be unmapped
  * @ulen:	length of user buffer
  *
  * Description:
- *    Unmap a request previously mapped by blk_rq_map_user().
+ *    Unmap a bio previously mapped by blk_rq_map_user().
  */
 int blk_rq_unmap_user(struct bio *bio, unsigned int ulen)
 {
@@ -2221,9 +2220,10 @@
 /**
  * blk_rq_map_kern - map kernel data to a request, for REQ_BLOCK_PC usage
  * @q:		request queue where request should be inserted
- * @rw:		READ or WRITE data
+ * @rw:		request to fill
  * @kbuf:	the kernel buffer
  * @len:	length of user data
+ * @gfp_mask:	memory allocation flags
  */
 int blk_rq_map_kern(request_queue_t *q, struct request *rq, void *kbuf,
 		    unsigned int len, unsigned int gfp_mask)
@@ -2252,6 +2252,18 @@
 
 EXPORT_SYMBOL(blk_rq_map_kern);
 
+/**
+ * blk_execute_rq - insert a request into queue for execution
+ * @q:		queue to insert the request in
+ * @bd_disk:	matching gendisk
+ * @rq:		request to insert
+ * @at_head:    insert request at head or tail of queue
+ * @done:	I/O completion handler
+ *
+ * Description:
+ *    Insert a fully prepared request at the back of the io scheduler queue
+ *    for execution.  Don't wait for completion.
+ */
 void blk_execute_rq_nowait(request_queue_t *q, struct gendisk *bd_disk,
 			   struct request *rq, int at_head,
 			   void (*done)(struct request *))
@@ -2274,7 +2286,7 @@
  *
  * Description:
  *    Insert a fully prepared request at the back of the io scheduler queue
- *    for execution.
+ *    for execution and wait for completion.
  */
 int blk_execute_rq(request_queue_t *q, struct gendisk *bd_disk,
 		   struct request *rq, int at_head)

Re: [PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[Christoph Hellwig]

On Mon, Jun 20, 2005 at 12:40:44PM +0200, Jens Axboe wrote:
> On Sun, Jun 19 2005, Christoph Hellwig wrote:
> > @@ -2098,14 +2098,14 @@
> >   *    Data will be mapped directly for zero copy io, if possible. Otherwise
> >   *    a kernel bounce buffer is used.
> >   *
> > - *    A matching blk_rq_unmap_user() must be issued at the end of io, while
> > - *    still in process context.
> > + *    A matching blk_rq_unmap_user_iov() must be issued at the end of io,
> > + *    while still in process context.
> 
> ?

This is ontop of my patch to remove the non-iov variant.

> > @@ -2221,9 +2220,10 @@
> >  /**
> >   * blk_rq_map_kern - map kernel data to a request, for REQ_BLOCK_PC usage
> >   * @q:		request queue where request should be inserted
> > - * @rw:		READ or WRITE data
> > + * @rw:		request to fill
> 
> @rq
> 
> Rest looks good, care to rediff it?

Yeah, will do so later.

Re: [PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[Jens Axboe]

On Sun, Jun 19 2005, Christoph Hellwig wrote:
> @@ -2098,14 +2098,14 @@
>   *    Data will be mapped directly for zero copy io, if possible. Otherwise
>   *    a kernel bounce buffer is used.
>   *
> - *    A matching blk_rq_unmap_user() must be issued at the end of io, while
> - *    still in process context.
> + *    A matching blk_rq_unmap_user_iov() must be issued at the end of io,
> + *    while still in process context.

?

>   *    Note: The mapped bio may need to be bounced through blk_queue_bounce()
>   *    before being submitted to the device, as pages mapped may be out of
>   *    reach. It's the callers responsibility to make sure this happens. The
> - *    original bio must be passed back in to blk_rq_unmap_user() for proper
> - *    unmapping.
> + *    original bio must be passed back in to blk_rq_unmap_user_iov() for
> + *    proper unmapping.
>   */

Ditto

> @@ -2221,9 +2220,10 @@
>  /**
>   * blk_rq_map_kern - map kernel data to a request, for REQ_BLOCK_PC usage
>   * @q:		request queue where request should be inserted
> - * @rw:		READ or WRITE data
> + * @rw:		request to fill

@rq

Rest looks good, care to rediff it?

-- 
Jens Axboe

Re: [PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[Jens Axboe]

On Mon, Jun 20 2005, Christoph Hellwig wrote:
> On Mon, Jun 20, 2005 at 12:40:44PM +0200, Jens Axboe wrote:
> > On Sun, Jun 19 2005, Christoph Hellwig wrote:
> > > @@ -2098,14 +2098,14 @@
> > >   *    Data will be mapped directly for zero copy io, if possible. Otherwise
> > >   *    a kernel bounce buffer is used.
> > >   *
> > > - *    A matching blk_rq_unmap_user() must be issued at the end of io, while
> > > - *    still in process context.
> > > + *    A matching blk_rq_unmap_user_iov() must be issued at the end of io,
> > > + *    while still in process context.
> > 
> > ?
> 
> This is ontop of my patch to remove the non-iov variant.

Hmm, the function names still looked like the older ones.

> > > @@ -2221,9 +2220,10 @@
> > >  /**
> > >   * blk_rq_map_kern - map kernel data to a request, for REQ_BLOCK_PC usage
> > >   * @q:		request queue where request should be inserted
> > > - * @rw:		READ or WRITE data
> > > + * @rw:		request to fill
> > 
> > @rq
> > 
> > Rest looks good, care to rediff it?
> 
> Yeah, will do so later.

Thanks!

-- 
Jens Axboe

Re: [PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[Jens Axboe]

[-- Attachment #1: Type: text/plain, Size: 383 bytes --]

On Sun, Jun 19 2005, Christoph Hellwig wrote:

I've committed a modified patch based on this. There was a typo in the
blk_execute_rq_nowait() kerneldoc update as well, you duplicated the
name from blk_execute_rq().

It's committed to the rq-map branch of the linux-2.6-block.git tree.

(http://kernel.org/git/?p=linux/kernel/git/axboe/linux-2.6-block.git;a=summary)

-- 
Jens Axboe


[-- Attachment #2: rq-map-7.diff --]
[-- Type: text/plain, Size: 2917 bytes --]

diff-tree 73747aed04d3b3fb694961d025f81863b99c6898 (from 994ca9a19616f0d4161a9e825f0835925d522426)
tree d7cae2a3da1e15dc8c87b0ffbf2608eb8c999cc9
parent 994ca9a19616f0d4161a9e825f0835925d522426
author Christoph Hellwig  <hch@lst.de> 1119270061 +0200
committer Jens Axboe <axboe@suse.de> 1119270061 +0200

    [PATCH] ll_rw_blk.c kerneldoc updates
    
    The recent mapping changes didn't update the kerneldoc appropriately.
    
    Original from Christoph Hellwig <hch@lst.de>
    
    Signed-off-by: Jens Axboe <axboe@suse.de>

diff --git a/drivers/block/ll_rw_blk.c b/drivers/block/ll_rw_blk.c
--- a/drivers/block/ll_rw_blk.c
+++ b/drivers/block/ll_rw_blk.c
@@ -2090,7 +2090,7 @@ EXPORT_SYMBOL(blk_insert_request);
 /**
  * blk_rq_map_user - map user data to a request, for REQ_BLOCK_PC usage
  * @q:		request queue where request should be inserted
- * @rw:		READ or WRITE data
+ * @rq:		request structure to fill
  * @ubuf:	the user buffer
  * @len:	length of user data
  *
@@ -2194,12 +2194,11 @@ EXPORT_SYMBOL(blk_rq_map_user_iov);
 
 /**
  * blk_rq_unmap_user - unmap a request with user data
- * @rq:		request to be unmapped
- * @bio:	bio for the request
+ * @bio:	bio to be unmapped
  * @ulen:	length of user buffer
  *
  * Description:
- *    Unmap a request previously mapped by blk_rq_map_user().
+ *    Unmap a bio previously mapped by blk_rq_map_user().
  */
 int blk_rq_unmap_user(struct bio *bio, unsigned int ulen)
 {
@@ -2220,9 +2219,10 @@ EXPORT_SYMBOL(blk_rq_unmap_user);
 /**
  * blk_rq_map_kern - map kernel data to a request, for REQ_BLOCK_PC usage
  * @q:		request queue where request should be inserted
- * @rw:		READ or WRITE data
+ * @rq:		request to fill
  * @kbuf:	the kernel buffer
  * @len:	length of user data
+ * @gfp_mask:	memory allocation flags
  */
 int blk_rq_map_kern(request_queue_t *q, struct request *rq, void *kbuf,
 		    unsigned int len, unsigned int gfp_mask)
@@ -2251,6 +2251,18 @@ int blk_rq_map_kern(request_queue_t *q, 
 
 EXPORT_SYMBOL(blk_rq_map_kern);
 
+/**
+ * blk_execute_rq_nowait - insert a request into queue for execution
+ * @q:		queue to insert the request in
+ * @bd_disk:	matching gendisk
+ * @rq:		request to insert
+ * @at_head:    insert request at head or tail of queue
+ * @done:	I/O completion handler
+ *
+ * Description:
+ *    Insert a fully prepared request at the back of the io scheduler queue
+ *    for execution.  Don't wait for completion.
+ */
 void blk_execute_rq_nowait(request_queue_t *q, struct gendisk *bd_disk,
 			   struct request *rq, int at_head,
 			   void (*done)(struct request *))
@@ -2273,7 +2285,7 @@ void blk_execute_rq_nowait(request_queue
  *
  * Description:
  *    Insert a fully prepared request at the back of the io scheduler queue
- *    for execution.
+ *    for execution and wait for completion.
  */
 int blk_execute_rq(request_queue_t *q, struct gendisk *bd_disk,
 		   struct request *rq, int at_head)

Re: [PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[Christoph Hellwig]

On Mon, Jun 20, 2005 at 02:24:27PM +0200, Jens Axboe wrote:
> On Sun, Jun 19 2005, Christoph Hellwig wrote:
> 
> I've committed a modified patch based on this. There was a typo in the
> blk_execute_rq_nowait() kerneldoc update as well, you duplicated the
> name from blk_execute_rq().
> 
> It's committed to the rq-map branch of the linux-2.6-block.git tree.
> 
> (http://kernel.org/git/?p=linux/kernel/git/axboe/linux-2.6-block.git;a=summary)

James, is this the branch you pull into scsi-block-2.6.git?  I try to
avoid getting lost in all those trees..

Re: [PATCH, scsi-block-2.6] ll_rw_blk.c kerneldoc fixups

[James Bottomley]

On Mon, 2005-06-20 at 14:38 +0200, Christoph Hellwig wrote:
> James, is this the branch you pull into scsi-block-2.6.git?  I try to
> avoid getting lost in all those trees..

Yes, but only the rq-map branch of that repository.

James