Skip to contentSkip to conversation

virtio: kdoc for struct virtio_pci_modern_device

PATCH In review Shannon Nelson 3 participants 4 messages Aug 28, 2023 – Sep 1, 2023

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 virtio: kdoc for struct virtio_pci_modern_device

Finally following up to Simon's suggestion for some kdoc attention on struct virtio_pci_modern_device.

---
 include/linux/virtio_pci_modern.h | 34 ++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 12 deletions(-)
include/linux/virtio_pci_modern.h +22 -12
index 067ac1d789bc..a38c729d1973 100644
@@ -12,37 +12,47 @@ struct virtio_pci_modern_common_cfg {
 	__le16 queue_reset;		/* read-write */
 };
 
+/**
+ * struct virtio_pci_modern_device - info for modern PCI virtio
+ * @pci_dev:	    Ptr to the PCI device struct
+ * @common:	    Position of the common capability in the PCI config
+ * @device:	    Device-specific data (non-legacy mode)
+ * @notify_base:    Base of vq notifications (non-legacy mode)
+ * @notify_pa:	    Physical base of vq notifications
+ * @isr:	    Where to read and clear interrupt
+ * @notify_len:	    So we can sanity-check accesses
+ * @device_len:	    So we can sanity-check accesses
+ * @notify_map_cap: Capability for when we need to map notifications per-vq
+ * @notify_offset_multiplier: Multiply queue_notify_off by this value
+ *                            (non-legacy mode).
+ * @modern_bars:    Bitmask of BARs
+ * @id:		    Device and vendor id
+ * @device_id_check: Callback defined before vp_modern_probe() to be used to
+ *		    verify the PCI device is a vendor's expected device rather
+ *		    than the standard virtio PCI device
+ *		    Returns the found device id or ERRNO
+ * @dma_mask:	    Optional mask instead of the traditional DMA_BIT_MASK(64),
+ *		    for vendor devices with DMA space address limitations
+ */
 struct virtio_pci_modern_device {
 	struct pci_dev *pci_dev;
 
 	struct virtio_pci_common_cfg __iomem *common;
-	/* Device-specific data (non-legacy mode)  */
 	void __iomem *device;
-	/* Base of vq notifications (non-legacy mode). */
 	void __iomem *notify_base;
-	/* Physical base of vq notifications */
 	resource_size_t notify_pa;
-	/* Where to read and clear interrupt */
 	u8 __iomem *isr;
 
-	/* So we can sanity-check accesses. */
 	size_t notify_len;
 	size_t device_len;
 
-	/* Capability for when we need to map notifications per-vq. */
 	int notify_map_cap;
 
-	/* Multiply queue_notify_off by this value. (non-legacy mode). */
 	u32 notify_offset_multiplier;
-
 	int modern_bars;
-
 	struct virtio_device_id id;
 
-	/* optional check for vendor virtio device, returns dev_id or -ERRNO */
 	int (*device_id_check)(struct pci_dev *pdev);
-
-	/* optional mask for devices with limited DMA space */
 	u64 dma_mask;
 };
 
Signature · 6 lines
2.17.1

_______________________________________________
Virtualization mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/virtualization
maintainer
#1 lore raw

Hi,

Quoted 6 lines · Shannon Nelson

Finally following up to Simon's suggestion for some kdoc attention on struct virtio_pci_modern_device.

IMHO this is net-next material and net-next is closed, so please repost this with a proper tag when net-next reopens in ~2w.

Thanks,

Paolo

_______________________________________________
Virtualization mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/virtualization

#2 lore raw
Quoted 11 lines · Paolo Abeni
Quoted 6 lines · Shannon Nelson

Finally following up to Simon's suggestion for some kdoc attention on struct virtio_pci_modern_device.

IMHO this is net-next material and net-next is closed, so please repost this with a proper tag when net-next reopens in ~2w.

Yeah, I wasn't quite sure on this whether to call it net or net-next. I'll followup later.

Cheers,
sln

Quoted 5 lines

Thanks,

Paolo

maintainer Acked-by on v1 1/1
#3 lore raw
In reply to Shannon Nelson
Quoted 7 lines · Shannon Nelson

Finally following up to Simon's suggestion for some kdoc attention on struct virtio_pci_modern_device.

When you repost it,

Thanks!

Quoted 72 lines
---
 include/linux/virtio_pci_modern.h | 34 ++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 12 deletions(-)
include/linux/virtio_pci_modern.h +22 -13
index 067ac1d789bc..a38c729d1973 100644
@@ -12,37 +12,47 @@ struct virtio_pci_modern_common_cfg {
        __le16 queue_reset;             /* read-write */
 };
 
+/**
+ * struct virtio_pci_modern_device - info for modern PCI virtio
+ * @pci_dev:       Ptr to the PCI device struct
+ * @common:        Position of the common capability in the PCI config
+ * @device:        Device-specific data (non-legacy mode)
+ * @notify_base:    Base of vq notifications (non-legacy mode)
+ * @notify_pa:     Physical base of vq notifications
+ * @isr:           Where to read and clear interrupt
+ * @notify_len:            So we can sanity-check accesses
+ * @device_len:            So we can sanity-check accesses
+ * @notify_map_cap: Capability for when we need to map notifications per-vq
+ * @notify_offset_multiplier: Multiply queue_notify_off by this value
+ *                            (non-legacy mode).
+ * @modern_bars:    Bitmask of BARs
+ * @id:                    Device and vendor id
+ * @device_id_check: Callback defined before vp_modern_probe() to be used to
+ *                 verify the PCI device is a vendor's expected device rather
+ *                 than the standard virtio PCI device
+ *                 Returns the found device id or ERRNO
+ * @dma_mask:      Optional mask instead of the traditional DMA_BIT_MASK(64),
+ *                 for vendor devices with DMA space address limitations
+ */
 struct virtio_pci_modern_device {
        struct pci_dev *pci_dev;
 
        struct virtio_pci_common_cfg __iomem *common;
-       /* Device-specific data (non-legacy mode)  */
        void __iomem *device;
-       /* Base of vq notifications (non-legacy mode). */
        void __iomem *notify_base;
-       /* Physical base of vq notifications */
        resource_size_t notify_pa;
-       /* Where to read and clear interrupt */
        u8 __iomem *isr;
 
-       /* So we can sanity-check accesses. */
        size_t notify_len;
        size_t device_len;
 
-       /* Capability for when we need to map notifications per-vq. */
        int notify_map_cap;
 
-       /* Multiply queue_notify_off by this value. (non-legacy mode). */
        u32 notify_offset_multiplier;
-
        int modern_bars;
-
        struct virtio_device_id id;
 
-       /* optional check for vendor virtio device, returns dev_id or -ERRNO */
        int (*device_id_check)(struct pci_dev *pdev);
-
-       /* optional mask for devices with limited DMA space */
        u64 dma_mask;
 };
 
--

2.17.1