Commit 5c669c4a authored by Ricardo Cañuelo's avatar Ricardo Cañuelo Committed by Michael S. Tsirkin
Browse files

virtio: kerneldocs fixes and enhancements 



Fix variable names in some kerneldocs, naming in others.
Add kerneldocs for struct vring_desc and vring_interrupt.

Signed-off-by: default avatarRicardo Cañuelo <ricardo.canuelo@collabora.com>
Message-Id: <20220810094004.1250-2-ricardo.canuelo@collabora.com>
Signed-off-by: default avatarMichael S. Tsirkin <mst@redhat.com>
Reviewed-by: default avatarCornelia Huck <cohuck@redhat.com>
parent 9993a4f9

drivers/virtio/virtio_ring.c

+8 −0
Original line number Diff line number Diff line
@@ -2426,6 +2426,14 @@ static inline bool more_used(const struct vring_virtqueue *vq) 
	return vq->packed_ring ? more_used_packed(vq) : more_used_split(vq);

}



/**

 * vring_interrupt - notify a virtqueue on an interrupt

 * @irq: the IRQ number (ignored)

 * @_vq: the struct virtqueue to notify

 *

 * Calls the callback function of @_vq to process the virtqueue

 * notification.

 */

irqreturn_t vring_interrupt(int irq, void *_vq)

{

	struct vring_virtqueue *vq = to_vvq(_vq);

include/linux/virtio.h

+3 −3
Original line number Diff line number Diff line
@@ -11,7 +11,7 @@ 
#include <linux/gfp.h>



/**

 * virtqueue - a queue to register buffers for sending or receiving.

 * struct virtqueue - a queue to register buffers for sending or receiving.

 * @list: the chain of virtqueues for this device

 * @callback: the function to call when buffers are consumed (can be NULL).

 * @name: the name of this virtqueue (mainly for debugging)
@@ -97,7 +97,7 @@ int virtqueue_resize(struct virtqueue *vq, u32 num, 
		     void (*recycle)(struct virtqueue *vq, void *buf));



/**

 * virtio_device - representation of a device using virtio

 * struct virtio_device - representation of a device using virtio

 * @index: unique position on the virtio bus

 * @failed: saved value for VIRTIO_CONFIG_S_FAILED bit (for restore)

 * @config_enabled: configuration change reporting enabled
@@ -156,7 +156,7 @@ size_t virtio_max_dma_size(struct virtio_device *vdev); 
	list_for_each_entry(vq, &vdev->vqs, list)



/**

 * virtio_driver - operations for a virtio I/O driver

 * struct virtio_driver - operations for a virtio I/O driver

 * @driver: underlying device driver (populate name and owner).

 * @id_table: the ids serviced by this driver.

 * @feature_table: an array of feature numbers supported by this driver.

include/linux/virtio_config.h

+3 −3
Original line number Diff line number Diff line
@@ -239,7 +239,7 @@ int virtio_find_vqs_ctx(struct virtio_device *vdev, unsigned nvqs, 


/**

 * virtio_synchronize_cbs - synchronize with virtqueue callbacks

 * @vdev: the device

 * @dev: the virtio device

 */

static inline

void virtio_synchronize_cbs(struct virtio_device *dev)
@@ -258,7 +258,7 @@ void virtio_synchronize_cbs(struct virtio_device *dev) 


/**

 * virtio_device_ready - enable vq use in probe function

 * @vdev: the device

 * @dev: the virtio device

 *

 * Driver must call this to use vqs in the probe function.

 *
@@ -306,7 +306,7 @@ const char *virtio_bus_name(struct virtio_device *vdev) 
/**

 * virtqueue_set_affinity - setting affinity for a virtqueue

 * @vq: the virtqueue

 * @cpu: the cpu no.

 * @cpu_mask: the cpu mask

 *

 * Pay attention the function are best-effort: the affinity hint may not be set

 * due to config support, irq type and sharing.

include/uapi/linux/virtio_ring.h

+11 −5
Original line number Diff line number Diff line
@@ -93,15 +93,21 @@ 
#define VRING_USED_ALIGN_SIZE 4

#define VRING_DESC_ALIGN_SIZE 16



/* Virtio ring descriptors: 16 bytes.  These can chain together via "next". */

/**

 * struct vring_desc - Virtio ring descriptors,

 * 16 bytes long. These can chain together via @next.

 *

 * @addr: buffer address (guest-physical)

 * @len: buffer length

 * @flags: descriptor flags

 * @next: index of the next descriptor in the chain,

 *        if the VRING_DESC_F_NEXT flag is set. We chain unused

 *        descriptors via this, too.

 */

struct vring_desc {

	/* Address (guest-physical). */

	__virtio64 addr;

	/* Length. */

	__virtio32 len;

	/* The flags as indicated above. */

	__virtio16 flags;

	/* We chain unused descriptors via this, too */

	__virtio16 next;

};