[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [PATCH v9 09/10] admin: conformance clauses
On Thu, Nov 24, 2022 at 5:08 AM Michael S. Tsirkin <mst@redhat.com> wrote: > > Add conformance clauses for admin commands and admin virtqueues. > > Signed-off-by: Michael S. Tsirkin <mst@redhat.com> > --- > admin.tex | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 158 insertions(+) > > diff --git a/admin.tex b/admin.tex > index eec12a9..e83a9f5 100644 > --- a/admin.tex > +++ b/admin.tex > @@ -222,6 +222,107 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti > It is assumed that all members in a group support and are used > with the same list of commands. > > +\devicenormative{\paragraph}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands} > + > +The device MUST validate \field{opcode}, \field{group_type} and > +\field{group_member_id}, set \field{status} to VIRTIO_ADMIN_STATUS_EINVAL and > +nd if any of these has an invalid or unsupported value, set typo > +\field{status_qualifier} accordingly. > + > +If a command completes successfully, the device MUST set > +\field{status} to VIRTIO_ADMIN_STATUS_OK. > + > +If a command fails, the device MUST set > +\field{status} to a value different from VIRTIO_ADMIN_STATUS_OK. > + > +If \field{status} is set to VIRTIO_ADMIN_STATUS_EINVAL, the > +device state MUST NOT change, that is the command MUST NOT have > +any side effects on the device, in particular the device MUST not > +enter an error state as a result of this command. > + > +If a command fails, the device state generally SHOULD NOT change, > +as far as possible. > + > +The device MAY enforce additional restrictions and dependencies on > +opcodes used by the driver and MAY fail the command > +VIRTIO_ADMIN_CMD_LIST_USE with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL > +and \field{status_qualifier} set to VIRTIO_ADMIN_STATUS_Q_INVALID_FIELD > +if the list of commands used violate internal device dependencies. > + > +If the device supports multiple group types, commands for each group > +type MUST operate independently of each other, in particular, > +the device MAY return different results for VIRTIO_ADMIN_CMD_LIST_QUERY > +for different group types. > + > +After reset, and before receiving VIRTIO_ADMIN_CMD_LIST_USE for a given group type > +the device MUST assume > +that the list of legal commands used by the driver consists of > +the two commands VIRTIO_ADMIN_CMD_LIST_QUERY and VIRTIO_ADMIN_CMD_LIST_USE. > + > +After completing VIRTIO_ADMIN_CMD_LIST_USE successfully, > +the device MUST set the list of legal commands used by the driver > +to the one supplied in \field{command_specific_data}. > + > +The device MUST set the list of legal commands used by the driver > +to the one supplied in VIRTIO_ADMIN_CMD_LIST_USE. > + > +The device MUST validate commands against the list used by > +the driver and MUST fail any commands not in the list with > +\field{status} set to VIRTIO_ADMIN_STATUS_EINVAL > +and \field{status_qualifier} set to > +VIRTIO_ADMIN_STATUS_Q_INVALID_OPCODE. > + > +The list of supported commands MUST NOT shrink (but MAY expand): > +after reporting a given command as supported through > +VIRTIO_ADMIN_CMD_LIST_QUERY the device MUST NOT later report it > +as unsupported. Further, after a given set of commands has been > +used (via a successful VIRTIO_ADMIN_CMD_LIST_USE), then after a > +device or system reset the device SHOULD complete successfully > +any following calls to VIRTIO_ADMIN_CMD_LIST_USE with the same > +list of commands; if this command VIRTIO_ADMIN_CMD_LIST_USE fails > +after a device or system reset, the device MUST not fail it > +solely because of the command list used. Failure to do so would > +interfere with resuming from suspend and error recovery. > + > + > +\drivernormative{\paragraph}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands} > + > +The driver MAY discover whether device supports a specific group type > +by issuing VIRTIO_ADMIN_CMD_LIST_QUERY with the matching > +\field{group_type}. > + > +The driver MUST issue VIRTIO_ADMIN_CMD_LIST_USE > +and wait for it to be completed with status > +VIRTIO_ADMIN_STATUS_OK before issuing any commands > +(except for the initial VIRTIO_ADMIN_CMD_LIST_QUERY > +and VIRTIO_ADMIN_CMD_LIST_USE). > + > +The driver SHOULD NOT set bits in device_admin_cmds > +if it is not familiar with how the command opcode > +is used, as dependencies between command opcodes might exist. > + > +The driver MUST NOT request (via VIRTIO_ADMIN_CMD_LIST_USE) > +the use of any commands not previously reported as > +supported for the same group type by VIRTIO_ADMIN_CMD_LIST_QUERY. > + > +The driver MUST NOT use any commands for a given group type > +before sending VIRTIO_ADMIN_CMD_LIST_USE with the correct > +list of command opcodes and group type. > + > +The driver MAY block use of VIRTIO_ADMIN_CMD_LIST_QUERY and > +VIRTIO_ADMIN_CMD_LIST_USE by issuing VIRTIO_ADMIN_CMD_LIST_USE > +with respective bits cleared in \field{command_specific_data}. > + > +The driver MUST handle a command error with a reserved \field{status} > +value in the same way as \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL > +(except possibly for different error reporting/diagnostic messages). > + > +The driver MUST handle a command error with a reserved > +\field{status_qualifier} value in the same way as > +\field{status_qualifier} set to > +VIRTIO_ADMIN_STATUS_Q_INVALID_COMMAND (except possibly for > +different error reporting/diagnostic messages). > + > \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Administration Virtqueues} > > An administration virtqueue of an owner device is used to submit > @@ -275,3 +376,60 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic > new fields can be added to the tail of a structure, > with the driver using the full structure without concern > for versioning. > + > +\devicenormative{\paragraph}{Group administration commands}{Basic Facilities of a Virtio Device / Administration virtqueues} > + > +The device MUST support device-readable and device-writeable buffers > +shorter than described in this specification, by > +\begin{enumerate} > +\item assuming that any data that would be read outside the > +device-readable buffers is set to zero, and s/"is set"/"are set" > +\item discarding data that would be written outside the > +specified device-writeable buffers. > +\end{enumerate} > + > +The device MUST support device-readable and device-writeable buffers > +longer than described in this specification, by > +\begin{enumerate} > +\item ignoring any data in device-readable buffers outside > +the expected length, and > +\item only writing the expected structure to the device-writeable > +buffers, ignoring any extra buffers, and reporting the > +actual length of data written, in bytes, > +as buffer used length. > +\end{enumerate} > + > +The device SHOULD initialize the device-writeable buffer > +up to the length of the structure described by this specification or > +the length of the buffer supplied by the driver (even if the buffer is > +all set to zero), whichever is shorter. > + > +The device MUST NOT fail a command solely because the buffers > +provided are shorter or longer than described in this > +specification. I may miss something but how can it work if the buffer is shorter? > + > +The device MUST process commands on a given administration virtqueue > +in the order in which they are queued. Is it better to use "complete" than "process" here? Or we can reuse part of the in-order description. (Or maybe a flush command) > + > +If multiple administration virtqueues have been configured, > +device MAY process commands on distinct virtqueues with > +no order constraints. > + > +\drivernormative{\paragraph}{Group administration commands}{Basic Facilities of a Virtio Device / Administration virtqueues} > + > +The driver MAY supply device-readable and device-writeable buffers > +longer than described in this specification. > + > +The driver SHOULD supply device-readable buffers at least as > +large as the structure described by this specification > +(even if the buffer is all set to zero). > + > +The driver MUST NOT assume that the device will initialize the whole > +structure as described in the specification; instead, > +the driver MUST assume that the structure > +outside the part of the buffer used by the device > +is set to zero. Won't this have security implications? E.g information leak. Thanks > + > +If multiple administration virtqueues have been configured, > +the driver MUST ensure ordering for commands > +placed on different administration virtqueues. > -- > MST >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]