[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH v8 9/9] admin: conformance clauses
Add conformance clauses for admin commands and admin virtqueues. Signed-off-by: Michael S. Tsirkin <mst@redhat.com> --- admin.tex | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) diff --git a/admin.tex b/admin.tex index 589e06a..290cbbc 100644 --- a/admin.tex +++ b/admin.tex @@ -227,6 +227,71 @@ \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} + +Device MUST validate \field{opcode}, \field{group_type} and +\field{group_member_id}, set \field{status} to VIRTIO_ADMIN_STATUS_EINVAL and +set \field{status_qualifier} accordingly if any of these has an +invalid or unsupported value. + +If \field{status} is set to VIRTIO_ADMIN_STATUS_EINVAL, the +command MUST NOT have any side effects, in particular the device +MUST not enter an error state as a result of this command. + +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, +device MAY return different results for VIRTIO_ADMIN_CMD_LIST_QUERY +for different group types. + +Before receiving VIRTIO_ADMIN_CMD_LIST_USE for a given group type +device MUST assume +that the list of legal commands used by driver consists of two commands +VIRTIO_ADMIN_CMD_LIST_QUERY and VIRTIO_ADMIN_CMD_LIST_USE. + +Device MUST set the list of legal commands used by driver +with the one supplied in VIRTIO_ADMIN_CMD_LIST_USE. + +Device MUST validate commands against the list used by +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. + +List of supported commands MUST NOT change: after reporting a +given command as supported through VIRTIO_ADMIN_CMD_LIST_QUERY +device MUST NOT later report it as unsupported. + +\drivernormative{\paragraph}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands} + +Driver MAY discover whether device supports a specific group type +by issuing VIRTIO_ADMIN_CMD_LIST_QUERY with the matching +\field{group_type}. + +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). + +Driver SHOULD NOT set bits in device_admin_cmds +if it is not familiar with how the command opcode +is used, since there could exist dependencies between +command opcodes. + +Driver MUST NOT request (by 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. + +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. + \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Administration Virtqueues} An administration virtqueue of an owner device is used to submit @@ -279,3 +344,60 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic new fields can be added to the tail of a structure, with driver using the full structure without concern for versioning. + +\devicenormative{\paragraph}{Group administration commands}{Basic Facilities of a Virtio Device / Administration virtqueues} + +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 +\item discarding data that would be written outside the +specified device-writeable buffers. +\end{enumerate} + +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} + +Device SHOULD initialize the device-writeable buffer +up to the smaller of the structure described by +this specification and the length of the buffer supplied by the +driver (even if the buffer is all set to zero). + +Device MUST NOT fail a command solely because the buffers +provided are shorter or longer than described in this +specification. + +Device MUST process commands on a given administration virtqueues +in the order in which they are queued. + +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} + +Driver MAY supply device-readable and device-writeable buffers +longer than described in this specification. + +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). + +Driver MUST NOT assume that 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. + +If multiple administration virtqueues have been configured, +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]