From nobody Mon Apr 13 13:14:08 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 71514C25B0D for ; Tue, 16 Aug 2022 02:02:25 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233131AbiHPCCW (ORCPT ); Mon, 15 Aug 2022 22:02:22 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56368 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233088AbiHPCBV (ORCPT ); Mon, 15 Aug 2022 22:01:21 -0400 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTP id AF128220068 for ; Mon, 15 Aug 2022 14:53:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1660600406; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3QJuMC2X3Ls7xg8Zv+wmV/GtRe9wR+MYC+AaCjrIFhI=; b=QzuYzXBdF4XJt871UR41qevJr4jLydu5qOoiBSgVl0B2BXrCp8/Yc/VW91+dK9iAQm1etH LpBosegnj16dFmydjGsbe4u71oga148519cD8V4kX9bDEIUXGu5QepKT9heXbrxMlv1RQk wzH44h7qRqMDRGt5EH1VWWTsAJMONBY= Received: from mail-wm1-f71.google.com (mail-wm1-f71.google.com [209.85.128.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_128_GCM_SHA256) id us-mta-47-VIAVkVvDNSC22gt2ND_O4w-1; Mon, 15 Aug 2022 17:53:25 -0400 X-MC-Unique: VIAVkVvDNSC22gt2ND_O4w-1 Received: by mail-wm1-f71.google.com with SMTP id v24-20020a7bcb58000000b003a37681b861so1584023wmj.9 for ; Mon, 15 Aug 2022 14:53:25 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=in-reply-to:content-transfer-encoding:content-disposition :mime-version:references:message-id:subject:cc:to:from:date :x-gm-message-state:from:to:cc; bh=3QJuMC2X3Ls7xg8Zv+wmV/GtRe9wR+MYC+AaCjrIFhI=; b=1ZCLHpGh5nn2F1pL+rrG6bKKKkiSVs+bxDK3SDnHu9UtGX2i3WFYkR8eZxcLv7gC6x JbGtMjQOMcvYIU0+yD+d4OKbBUAMNKtOzVzFq9skAjJQB5kcux1gKUOdYx+/rg1Hh/Nv HtWGnMJpxDYbSIMVanPrZyB/Kvif5IMlw8+tyQRzv8ZWxFgD0Yi6R8BDxAnpFIDFx97S Hi1sFTMum6JVmp/2LwGAzoes2oq2uH9Y91O9OtF4mlQmaMza7qbkSKVjZmKh9M9iAVKh J7IXJ0YL131A0YvuBfHFeyH9ihLTLyCjLv2PV6fxWbBhK+5dlAiHzwQtnSZs23vcF4M4 13/A== X-Gm-Message-State: ACgBeo2Sm69WPcopHJL7AIBkGQo074N6FZaexv97g73H015x10njA4pD FDwHP9RNOEA3ZjSz1kObelnzPXPIsDn928szkvRopO5C3Ap1fhKnpjEaf/kub8mvsgstJ45UPIX ckXeIw2RPu8i9gibC/N2oRCfP8EHotag27AQCkqfbt2wpoM3DuJXbnzHdYG9ZMyJjsZIY4A== X-Received: by 2002:adf:ce89:0:b0:220:6cc5:aff8 with SMTP id r9-20020adfce89000000b002206cc5aff8mr9905810wrn.396.1660600404333; Mon, 15 Aug 2022 14:53:24 -0700 (PDT) X-Google-Smtp-Source: AA6agR4OAJ7a0UnnYJ7tqTWqb9naQHIU382zVYRVHjmmnON5u7E9HsMntuwmikOY+aox36XmsS1mBQ== X-Received: by 2002:adf:ce89:0:b0:220:6cc5:aff8 with SMTP id r9-20020adfce89000000b002206cc5aff8mr9905783wrn.396.1660600403993; Mon, 15 Aug 2022 14:53:23 -0700 (PDT) Received: from redhat.com ([2.55.4.37]) by smtp.gmail.com with ESMTPSA id n6-20020a1c2706000000b003a511e92abcsm10796901wmn.34.2022.08.15.14.53.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 15 Aug 2022 14:53:23 -0700 (PDT) Date: Mon, 15 Aug 2022 17:53:20 -0400 From: "Michael S. Tsirkin" To: linux-kernel@vger.kernel.org Cc: Xuan Zhuo , Jason Wang , "David S. Miller" , Eric Dumazet , Jakub Kicinski , Paolo Abeni , virtualization@lists.linux-foundation.org, netdev@vger.kernel.org, Linus Torvalds , Jens Axboe , James Bottomley , "Martin K. Petersen" , Guenter Roeck , Greg KH , Ricardo =?utf-8?Q?Ca=C3=B1uelo?= , Cornelia Huck Subject: [PATCH v2 1/1] virtio: kerneldocs fixes and enhancements Message-ID: <20220815215251.154451-2-mst@redhat.com> References: <20220815215251.154451-1-mst@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Disposition: inline Content-Transfer-Encoding: quoted-printable In-Reply-To: <20220815215251.154451-1-mst@redhat.com> X-Mailer: git-send-email 2.27.0.106.g8ac3dc51b1 X-Mutt-Fcc: =sent Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Ricardo Ca=C3=B1uelo Fix variable names in some kerneldocs, naming in others. Add kerneldocs for struct vring_desc and vring_interrupt. Signed-off-by: Ricardo Ca=C3=B1uelo Message-Id: <20220810094004.1250-2-ricardo.canuelo@collabora.com> Signed-off-by: Michael S. Tsirkin Reviewed-by: Cornelia Huck diff --git a/drivers/virtio/virtio_ring.c b/drivers/virtio/virtio_ring.c index d66c8e6d0ef3..4620e9d79dde 100644 --- a/drivers/virtio/virtio_ring.c +++ b/drivers/virtio/virtio_ring.c @@ -2426,6 +2426,14 @@ static inline bool more_used(const struct vring_virt= queue *vq) return vq->packed_ring ? more_used_packed(vq) : more_used_split(vq); } =20 +/** + * 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 =3D to_vvq(_vq); diff --git a/include/linux/virtio.h b/include/linux/virtio.h index a3f73bb6733e..dcab9c7e8784 100644 --- a/include/linux/virtio.h +++ b/include/linux/virtio.h @@ -11,7 +11,7 @@ #include =20 /** - * 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)); =20 /** - * 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) =20 /** - * 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. diff --git a/include/linux/virtio_config.h b/include/linux/virtio_config.h index 36ec7be1f480..4b517649cfe8 100644 --- a/include/linux/virtio_config.h +++ b/include/linux/virtio_config.h @@ -239,7 +239,7 @@ int virtio_find_vqs_ctx(struct virtio_device *vdev, uns= igned nvqs, =20 /** * 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) =20 /** * 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 b= e set * due to config support, irq type and sharing. diff --git a/include/uapi/linux/virtio_ring.h b/include/uapi/linux/virtio_r= ing.h index 476d3e5c0fe7..f8c20d3de8da 100644 --- a/include/uapi/linux/virtio_ring.h +++ b/include/uapi/linux/virtio_ring.h @@ -93,15 +93,21 @@ #define VRING_USED_ALIGN_SIZE 4 #define VRING_DESC_ALIGN_SIZE 16 =20 -/* 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; }; =20 --=20 MST