[PATCH] virtio_blk.c: Add documentation for vring_enable_cb()

[PATCH] virtio_blk.c: Add documentation for vring_enable_cb()

[Jes.Sorensen]

From: Jes Sorensen <Jes.Sorensen@redhat.com>

Hi,

This patch adds a bit of documentation to vring_enable_cb() to make it
crystal clear that the function returns false when there is more work
to do and true when the queue is empty.

I wasted several hours trying to figure out why a piece of code wasn't
working due to this, and I know others hit the same problem. Hopefully
this can save a bit of suffering for others in the future.

Cheers,
Jes


Jes Sorensen (1):
  Add documentation for vring_enable_cb()

 drivers/virtio/virtio_ring.c |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

[PATCH] virtio_blk.c: Add documentation for vring_enable_cb()

[Jes.Sorensen]

From: Jes Sorensen <Jes.Sorensen@redhat.com>

Add documentation for vring_enable_cb() as return logic may not be
obvious for the caller.

Signed-off-by: Jes Sorensen <Jes.Sorensen@redhat.com>
---
 drivers/virtio/virtio_ring.c |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

diff --git a/drivers/virtio/virtio_ring.c b/drivers/virtio/virtio_ring.c
index 0f90634..2cdcdca 100644
--- a/drivers/virtio/virtio_ring.c
+++ b/drivers/virtio/virtio_ring.c
@@ -333,6 +333,11 @@ static void vring_disable_cb(struct virtqueue *_vq)
 	vq->vring.avail->flags |= VRING_AVAIL_F_NO_INTERRUPT;
 }
 
+/*
+ * Enable interrupts and check whether there is anything in the queue.
+ * Note, vring_enable_cb() returns TRUE if the queue is empty,  and
+ * FALSE if the queue is not empty and there is work to do.
+ */
 static bool vring_enable_cb(struct virtqueue *_vq)
 {
 	struct vring_virtqueue *vq = to_vvq(_vq);
-- 
1.6.5.2

Re: [PATCH] virtio_blk.c: Add documentation for vring_enable_cb()

[Michael S. Tsirkin]

On Wed, May 19, 2010 at 05:50:49PM +0200, Jes.Sorensen@redhat.com wrote:
> From: Jes Sorensen <Jes.Sorensen@redhat.com>
> 
> Add documentation for vring_enable_cb() as return logic may not be
> obvious for the caller.
> 
> Signed-off-by: Jes Sorensen <Jes.Sorensen@redhat.com>

Yes. Confused me too.
Acked-by: Michael S. Tsirkin <mst@redhat.com>

> ---
>  drivers/virtio/virtio_ring.c |    5 +++++
>  1 files changed, 5 insertions(+), 0 deletions(-)
> 
> diff --git a/drivers/virtio/virtio_ring.c b/drivers/virtio/virtio_ring.c
> index 0f90634..2cdcdca 100644
> --- a/drivers/virtio/virtio_ring.c
> +++ b/drivers/virtio/virtio_ring.c
> @@ -333,6 +333,11 @@ static void vring_disable_cb(struct virtqueue *_vq)
>  	vq->vring.avail->flags |= VRING_AVAIL_F_NO_INTERRUPT;
>  }
>  
> +/*
> + * Enable interrupts and check whether there is anything in the queue.
> + * Note, vring_enable_cb() returns TRUE if the queue is empty,  and
> + * FALSE if the queue is not empty and there is work to do.
> + */
>  static bool vring_enable_cb(struct virtqueue *_vq)
>  {
>  	struct vring_virtqueue *vq = to_vvq(_vq);
> -- 
> 1.6.5.2