Re: [virtio-dev] [PATCH v13] admin: Add group member legacy register access commands

[Cornelia Huck <cohuck@redhat.com>]

On Fri, Jul 07 2023, Parav Pandit <parav@nvidia.com> wrote:

(...)

> +When the device supports VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO command, the group

s/supports/supports the/

> +owner device hardwires VF BAR0 to zero in the SR-IOV Extended capability.

(...)

> +\devicenormative{\paragraph}{Legacy Interface}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface}
> +
> +A device MUST either support all of, or none of
> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE,
> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ,
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE and
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ commands.
> +
> +For VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE,

s/For/For the/

> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ,
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE and
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ commands,
> +the device MUST decode and encode (respectively) the value of the
> +\field{data} using the little-endian format.
> +
> +For VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE and

s/For/For the/

> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ commands, 
> +the device MUST fail the command when the value of the
> +\field{offset} and the length of the \field{data} does not refer to a

"do not", I think?

> +single field or is not completely within the virtio common configuration
> +excluding the device-specific configuration.
> +
> +For VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE and

s/For/For the/

> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ commands,
> +the device MUST fail the command when the value of the
> +\field{offset} and the length of the \field{data} does not refer to a

"do not"?

> +single field or is not completely within the virtio device-specific
> +configuration.
> +
> +The command VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE MUST have the same effect
> +as writing into the virtio common configuration structure through the legacy
> +interface.
> +
> +The command VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ MUST have the same effect as
> +reading from the virtio common configuration structure through the legacy
> +interface.
> +
> +The command VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE MUST have the same effect as
> +writing into the virtio device-specific configuration through the legacy
> +interface.
> +
> +The command VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ MUST have the same effect as
> +reading from the virtio device-specific configuration through the legacy
> +interface.
> +
> +For the SR-IOV group type, when the owner device supports
> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ,
> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE, VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ,
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE and VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO
> +commands,
> +\begin{itemize}
> +\item the owner device and the group member device SHOULD follow the rules
> +for the PCI Revision ID and Subsystem Device ID of the non-transitional devices
> +documented in section \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery}.
> +
> +\item the owner device SHOULD follow the rules for the PCI Device ID of the non-transitional
> +devices documented in section
> +\ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery}.
> +
> +\item any driver notification received by the device at any of the notification
> +address supplied in the command result of
> +VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO MUST function as if the device received
> +the notification through VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE
> +command at an offset \field{offset} matching \field{Queue Notify}.
> +\end{itemize}
> +
> +If the device supports VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO command,

s/support/supports the/

> +\begin{itemize}
> +\item the device MUST also support all of VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE,
> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ,
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE and
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ commands.
> +
> +\item in the command result of VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO, the last
> +\field{struct virtio_pci_legacy_notify_info} entry MUST have \field{flags} of
> +zero.
> +
> +\item in the command result of VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO, valid
> +entries MUST have a \field{bar} which is not hardwired to zero.
> +
> +\item in the command result of VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO, valid
> +entries MUST have an \field{offset} aligned to 2-byte.
> +
> +\item the device MAY support VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO with entries
> +of the owner device or the member device or both of them.
> +
> +\item for the SR-IOV group type, the group owner device MUST hardwire VF BAR0
> +to zero in the SR-IOV Extended capability.
> +\end{itemize}
> +
> +\drivernormative{\paragraph}{Legacy Interface}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface}
> +
> +For VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE,

s/For/For the/

> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ,
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE and
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ commands,
> +the driver MUST encode and decode (respectively) the value of the \field{data}
> +using the little-endian format.
> +
> +For VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE and

s/For/For the/

> +VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ commands,
> +the driver SHOULD set \field{offset} and the length of the \field{data}
> +to refer to a single field within the virtio common configuration structure
> +excluding the device-specific configuration.
> +
> +For VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE and
> +VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ commands,
> +the driver SHOULD set \field{offset} and the length of the \field{data}
> +to refer to a single field within device specific configuration.
> +
> +If VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO command is supported, the driver

s/If/If the/

> +SHOULD use the notification address to send all driver notifications to the
> +device.

(...)