Re: [PATCH v2 7/8] um: add PCI over virtio emulation driver

[Bjorn Helgaas]

On Mon, Mar 01, 2021 at 04:07:07PM +0100, Johannes Berg wrote:
> From: Johannes Berg <johannes.berg@xxxxxxxxx>
> 
> To support testing of PCI/PCIe drivers in UML, add a PCI bus
> support driver. This driver uses virtio, which in UML is really
> just vhost-user, to talk to devices, and adds the devices to
> the virtual PCI bus in the system.

Hi Johannes,

The virtio_pcidev_ops kernel-doc below doesn't match the actual enum,
so it generates several warnings:

  include/uapi/linux/virtio_pcidev.h:41: warning: Enum value 'VIRTIO_PCIDEV_OP_RESERVED' not described in enum 'virtio_pcidev_ops'
  include/uapi/linux/virtio_pcidev.h:41: warning: Enum value 'VIRTIO_PCIDEV_OP_MMIO_READ' not described in enum 'virtio_pcidev_ops'
  include/uapi/linux/virtio_pcidev.h:41: warning: Enum value 'VIRTIO_PCIDEV_OP_MMIO_WRITE' not described in enum 'virtio_pcidev_ops'
  include/uapi/linux/virtio_pcidev.h:41: warning: Excess enum value 'VIRTIO_PCIDEV_OP_BAR_READ' description in 'virtio_pcidev_ops'
  include/uapi/linux/virtio_pcidev.h:41: warning: Excess enum value 'VIRTIO_PCIDEV_OP_BAR_WRITE' description in 'virtio_pcidev_ops'

FWIW, here's the command I used to find these:

  $ find include drivers/pci -type f -path "*pci*.[ch]" | xargs scripts/kernel-doc -none

> diff --git a/include/uapi/linux/virtio_pcidev.h b/include/uapi/linux/virtio_pcidev.h
> new file mode 100644
> index 000000000000..89daa88bcfef
> --- /dev/null
> +++ b/include/uapi/linux/virtio_pcidev.h
> @@ -0,0 +1,64 @@
> +/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */
> +/*
> + * Copyright (C) 2021 Intel Corporation
> + * Author: Johannes Berg <johannes@xxxxxxxxxxxxxxxx>
> + */
> +#ifndef _UAPI_LINUX_VIRTIO_PCIDEV_H
> +#define _UAPI_LINUX_VIRTIO_PCIDEV_H
> +#include <linux/types.h>
> +
> +/**
> + * enum virtio_pcidev_ops - virtual PCI device operations
> + * @VIRTIO_PCIDEV_OP_CFG_READ: read config space, size is 1, 2, 4 or 8;
> + *	the @data field should be filled in by the device (in little endian).
> + * @VIRTIO_PCIDEV_OP_CFG_WRITE: write config space, size is 1, 2, 4 or 8;
> + *	the @data field contains the data to write (in little endian).
> + * @VIRTIO_PCIDEV_OP_BAR_READ: read BAR mem/pio, size can be variable;
> + *	the @data field should be filled in by the device (in little endian).
> + * @VIRTIO_PCIDEV_OP_BAR_WRITE: write BAR mem/pio, size can be variable;
> + *	the @data field contains the data to write (in little endian).
> + * @VIRTIO_PCIDEV_OP_MMIO_MEMSET: memset MMIO, size is variable but
> + *	the @data field only has one byte (unlike @VIRTIO_PCIDEV_OP_MMIO_WRITE)
> + * @VIRTIO_PCIDEV_OP_INT: legacy INTx# pin interrupt, the addr field is 1-4 for
> + *	the number
> + * @VIRTIO_PCIDEV_OP_MSI: MSI(-X) interrupt, this message basically transports
> + *	the 16- or 32-bit write that would otherwise be done into memory,
> + *	analogous to the write messages (@VIRTIO_PCIDEV_OP_MMIO_WRITE) above
> + * @VIRTIO_PCIDEV_OP_PME: Dummy message whose content is ignored (and should be
> + *	all zeroes) to signal the PME# pin.
> + */
> +enum virtio_pcidev_ops {
> +	VIRTIO_PCIDEV_OP_RESERVED = 0,
> +	VIRTIO_PCIDEV_OP_CFG_READ,
> +	VIRTIO_PCIDEV_OP_CFG_WRITE,
> +	VIRTIO_PCIDEV_OP_MMIO_READ,
> +	VIRTIO_PCIDEV_OP_MMIO_WRITE,
> +	VIRTIO_PCIDEV_OP_MMIO_MEMSET,
> +	VIRTIO_PCIDEV_OP_INT,
> +	VIRTIO_PCIDEV_OP_MSI,
> +	VIRTIO_PCIDEV_OP_PME,
> +};