diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 69d41fc..ea4ed16 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,10 +1,8 @@ -# Thanks for proposing a change to the Virtual I/O Device (VIRTIO) specification! -The VIRTIO TC is not yet accepting pull requests at this time as they are not -integrated with our voting system. +# Thanks for proposing a change to the virtio-msg specification -Instead, please -- [] Propose the spec change (preferably as a patch) on the [mailing list](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback). -- [] Open an [issue](https://github.com/oasis-tcs/virtio-spec/issues), - including the link to the proposal in the [mailing list archives](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback). +This is not the same as proposing a change to the VirtIO spec. This +repository is intended for preparing the virtio-msg transport +specification before it's submission to the VIRTIO TC. -The TC will vote and apply the change. +If your intention was to suggestion to change to the upstream please +propose the change as a patch to the [mailing list](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=virtio#feedback). diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml new file mode 100644 index 0000000..2cc39e3 --- /dev/null +++ b/.github/workflows/deploy.yaml @@ -0,0 +1,27 @@ +name: Deploy current state + +on: + push: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install Tools + run: | + sudo apt install texlive-full + + - name: Build Docs + run: | + make local-all + echo ${{ github.sha }} > Release.txt + + - name: Create a Draft Release + uses: softprops/action-gh-release@v2 + with: + draft: true + name: working-draft + files: | + Release.txt + virtio-v1.4-wd01.pdf diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..180fd17 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,18 @@ +name: CI + +on: + push: + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Install Tools + run: | + sudo apt install texlive-full + + - name: Build HTML + run: | + make local-html diff --git a/DIFFVERSION b/DIFFVERSION index 67ec309..9bcc9ec 100644 --- a/DIFFVERSION +++ b/DIFFVERSION @@ -1 +1 @@ -v1.2-cs01 +v1.3-wd02 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..989b429 --- /dev/null +++ b/Makefile @@ -0,0 +1,33 @@ +# -*- Mode: makefile -*- +# +# Basic Makefile to aid automation of document building +# + +.PHONY: all local +all: + ./makeall.sh + +local-all: + ./makeall.sh local + +.PHONY: html local-html + +html: + ./makehtml.sh + +local-html: + ./makehtml.sh local + +.PHONY: clean +clean: + git clean -fd + +.PHONY: help +help: + @echo "Build the VIRTIO specification documents." + @echo "" + @echo "Possible operations are:" + @echo + @echo " $(MAKE) Build everything" + @echo " $(MAKE) html Build local html" + @echo " $(MAKE) clean Remove all intermediate files" diff --git a/REVISION b/REVISION index ba56baf..e3c043e 100644 --- a/REVISION +++ b/REVISION @@ -1 +1 @@ -virtio-v1.3-csd01 +virtio-v1.4-wd01 diff --git a/admin-cmds-capabilities.tex b/admin-cmds-capabilities.tex new file mode 100644 index 0000000..f917a0d --- /dev/null +++ b/admin-cmds-capabilities.tex @@ -0,0 +1,249 @@ +\subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities} + +Device and driver capabilities are implemented as structured groupings for +specific device functionality and their related resource objects. The device exposes +its supported functionality and resource object limits through an administration +command, utilizing the 'self group type.' Each capability possesses a +unique ID. Through an administration command, also employing the +'self group type,' the driver reports the functionality and +resource object limits it intends to use. Before executing any operations +related to the capabilities, the driver communicates these +capabilities to the device. The driver is allowed to set the +capability at any time, provided there are no pending operations +at the device level associated with that capability. + +The device presents the supported capability IDs to the driver as a bitmap. +The driver uses the administration command to learn about the +supported capabilities bitmap. + +A capability consists of one or more fields, where each field can be a +limit number, a bitmap, or an array of entries. In an array field, +the structure depends on the specific array and the capability type. +For each bitmap field, the driver sets the desired bits - but only out of +those bits in a bitmap that the device has presented. +The driver sets each limit number field to a desired value that +is smaller than or equal to the value the device presented. +Similarly, for an array field, the driver sets the desired capability +entries but only out of the capability entries that the device has presented. + +It is anticipated that any necessary new fields for a capability will be +appended to the structure's end, ensuring both forward and backward +compatibility between the device and driver. Furthermore, to avoid +indefinite growth of a single capability, it is expected that new +functionality will lead to the creation of new capability rather +than expanding existing ones. + +Capabilities are categorized into two ranges by their IDs, as listed: + +\begin{table}[H] +\caption{Capability ids} +\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids} +\begin{tabularx}{\textwidth}{ |l|X| } +\hline +Id & Description \\ +\hline \hline +0x0000-0x07ff & Generic capability for all device types \\ +\hline +0x0800-0x0fff & Device type specific capability \\ +\hline +0x1000 - 0xFFFF & Reserved for future \\ +\hline +\end{tabularx} +\end{table} + +Common capabilities are listed: + +\begin{table}[H] +\caption{Common capability ids} +\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / Common capability ids} +\begin{tabularx}{\textwidth}{ |l|l|X| } +\hline +Id & Name & Description \\ +\hline \hline +0x0000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-DEV-PARTS-CAP]{VIRTIO_DEV_PARTS_CAP} & Device parts capability \\ +\hline +0x0001-0x07ff & - & Generic capability for all device types \\ +\hline +\end{tabularx} +\end{table} + +Device type specific capabilities are described separately for each device +type under \field{Device and driver capabilities}. + +The device and driver capabilities commands are currently defined for self group +type. + +\begin{enumerate} +\item VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY +\item VIRTIO_ADMIN_CMD_DEVICE_CAP_GET +\item VIRTIO_ADMIN_CMD_DRIVER_CAP_SET +\end{enumerate} + +\paragraph{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-CAP-ID-LIST-QUERY} + +This command queries the bitmap of capability ids +listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}. + +For the command VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, \field{opcode} is set to 0x7. +\field{group_member_id} is set to zero. + +This command has no command specific data. + +\begin{lstlisting} +struct virtio_admin_cmd_query_cap_id_result { + le64 supported_caps[]; +}; +\end{lstlisting} + +When the command completes successfully, \field{command_specific_result} +is in the format \field{struct virtio_admin_cmd_query_cap_id_result}. + +\field{supported_caps} is an array of 64 bit values in little-endian byte +order, in which a bit is set if the specific capability is supported. +Thus, \field{supported_caps[0]} refers to the first 64-bit value in this +array corresponding to capability ids 0 to +63, \field{supported_caps[1]} is the second 64-bit value corresponding to +capability ids 64 to 127, etc. For example, the array of size 2 including +the values 0x3 in \field{supported_caps[0]} and 0x1 in +\field{supported_caps[1]} indicates that only capability id 0, 1 +and 64 are supported. +The length of the array depends on the supported capabilities - it is +large enough to include bits set for all supported capability ids, +that is the length can be calculated by starting with the largest +supported capability id adding one, dividing by 64 and rounding up. +In other words, for VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY the length of +\field{command_specific_result} will be +$DIV_ROUND_UP(max_cap_id, 64) * 8$ where DIV_ROUND_UP is integer division +with round up and \field{max_cap_id} is the largest available capability id. + +The array is also allowed to be larger and to additionally include an arbitrary +number of all-zero entries. + +\paragraph{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DEVICE-CAP-GET} + +This command gets the device capability for the specified capability +id \field{id}. + +For the command VIRTIO_ADMIN_CMD_DEVICE_CAP_GET, \field{opcode} is set to 0x8. +\field{group_member_id} is set to zero. + +\field{command_specific_data} is in format +\field{struct virtio_admin_cmd_cap_get_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_cap_get_data { + le16 id; + u8 reserved[6]; +}; +\end{lstlisting} + +\field{id} refers to the capability id listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}. +\field{reserved} is reserved for future use and set to zero. + +\begin{lstlisting} +struct virtio_admin_cmd_cap_get_result { + u8 cap_specific_data[]; +}; +\end{lstlisting} + +When the command completes successfully, \field{command_specific_result} +is in the format \field{struct virtio_admin_cmd_cap_get_result} responded +by the device. Each capability uses different capability specific +\field{cap_specific_data} and is described separately. + +\paragraph{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DRIVER-CAP-SET} + +This command sets the driver capability, indicating to the device which capability +the driver uses. The driver can set a resource object limit capability that is smaller +than or equal to the value published by the device capability. +If the capability is a set of flags, the driver sets the flag bits that are set +in the device capability; the driver does not set any flag bits that are not +set by the device. + +For the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET, \field{opcode} is set to 0x9. +\field{group_member_id} is set to zero. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_cap_set_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_cap_set_data { + le16 id; + u8 reserved[6]; + u8 cap_specific_data[]; +}; +\end{lstlisting} + +\field{id} refers to the capability id listed in \ref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / capability ids}. +\field{reserved} is reserved for future use and set to zero. + +There is no command specific result. +When the command completes successfully, the driver capability is updated to +the values supplied in \field{cap_specific_data}. + +\devicenormative{\paragraph}{Device and driver capabilities}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities} + +If the device supports capabilities, it MUST support the commands +VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, +VIRTIO_ADMIN_CMD_DRIVER_CAP_SET, and +VIRTIO_ADMIN_CMD_DEVICE_CAP_GET. + +For the VIRTIO_ADMIN_CMD_DRIVER_CAP_SET command, +\begin{itemize} +\item the device MUST support the setting of resource object limit driver capability to a +value that is same as or smaller than the one reported in the device +capability, +\item the device MUST support the setting of capability flags bits to +all or fewer bits than the one reported in the device capability; +\end{itemize} +this is applicable unless specific capability fields are explicitly +stated as non-writable in the VIRTIO_ADMIN_CMD_DEVICE_CAP_GET command. + +The device MAY complete the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with +\field{status} set to VIRTIO_ADMIN_STATUS_EINVAL, +if the capability resource object limit is larger than the value reported by the +device's capability, or the capability flag bit is set, which is not set in +the device's capability. + +The device MUST complete the commands VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, +VIRTIO_ADMIN_CMD_DRIVER_CAP_GET, and VIRTIO_ADMIN_CMD_DRIVER_CAP_SET +with \field{status} set to VIRTIO_ADMIN_STATUS_EINVAL if the commands are not +for the self group type. + +The device SHOULD complete the commands VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY, +VIRTIO_ADMIN_CMD_DRIVER_CAP_GET, VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with +\field{status} set to VIRTIO_ADMIN_STATUS_EINVAL if the commands are not for the +self group type. + +The device SHOULD complete the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with +\field{status} set to VIRTIO_ADMIN_STATUS_EBUSY if the command requests to disable +a capability while the device still has valid resource objects related to the +capability being disabled. + +The device SHOULD complete the comands VIRTIO_ADMIN_CMD_DEVICE_CAP_GET and +VIRTIO_ADMIN_CMD_DRIVER_CAP_SET with \field{status} set to +VIRTIO_ADMIN_STATUS_ENXIO if the capability id is not reported +in command VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY. + +Upon a device reset, the device MUST reset all driver capabilities. + +The device SHOULD treat the driver resource limits as zero if the +driver has not set such capability, unless otherwise explicitly stated. + +\drivernormative{\paragraph}{Device and driver capabilities}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities} + +The driver MUST send the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET before +using any resource objects that depend on such a capability. + +In VIRTIO_ADMIN_CMD_DRIVER_CAP_SET command, the driver MUST NOT set +\begin{itemize} +\item the resource object limit value larger than the value reported +by the device in the command VIRTIO_ADMIN_CMD_DEVICE_CAP_GET, +\item flags bits which was not reported by the device in the command +VIRTIO_ADMIN_CMD_DEVICE_CAP_GET, +\item array entries not reported by the device in the command +VIRTIO_ADMIN_CMD_DEVICE_CAP_GET. +\end{itemize} + +The driver MUST NOT disable any of the driver capability using the command +VIRTIO_ADMIN_CMD_DRIVER_CAP_SET when related resource objects +are created but not destroyed. diff --git a/admin-cmds-device-parts.tex b/admin-cmds-device-parts.tex new file mode 100644 index 0000000..3a16692 --- /dev/null +++ b/admin-cmds-device-parts.tex @@ -0,0 +1,469 @@ +\subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} + +In some systems, there is a need to capture the state of all or part of +a device and subsequently restore either the same device or a +different one to this captured state. A group owner device can support +administration commands to facilitate these get and set operations for +the group member devices. + +For example, a hypervisor can use the administration commands to +capture parts of the device state and save the result as part of +a VM snapshot. Later, the hypervisor can retrieve the snapshot and use the +administration commands to restore parts of a device to resume +VM operation. + +As another example, these commands can be used to facilitate VM migration by the +hypervisor: one (source) hypervisor can get parts of a device and send +the results to another (destination) hypervisor, which will in turn +set (restore) parts of (another) device to resume the VM operation on +the destination. + +The device comprises many device parts which the driver can get and set. +Administration commands are provided to either get and set all the device +parts at once, or to get the device parts metadata that indicates which +device parts are present, and later to get and set specific device parts. +To get and set the device parts or their metadata, the driver first creates a +device parts resource object, indicating whether the object should +handle get or set operations but not both simultaneously. The device and the +driver indicate the device parts resource objects' limit using the capability +VIRTIO_DEV_PARTS_CAP. + +The device can be stopped to prevent device parts from changing. +When the device is stopped, it does not initiate any transport requests. +For instance, the device refrains from sending any configuration or +virtqueue notifications and does not access any virtqueues or the driver's +buffer memory. While the driver may remain active and continue to send +notifications to the device, potentially updating some device parts, +the device itself will not initiate any transport requests. + +\paragraph{VIRTIO_DEV_PARTS_CAP} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-DEV-PARTS-CAP} + +The capability VIRTIO_DEV_PARTS_CAP indicates the device parts resource objects limit. +\field{cap_specific_data} is in the format \field{struct virtio_dev_parts_cap}. + +\begin{lstlisting} +struct virtio_dev_parts_cap { + u8 get_parts_resource_objects_limit; + u8 set_parts_resource_objects_limit; +}; +\end{lstlisting} + +\field{get_parts_resource_objects_limit} indicates the supported device parts +resource objects for retrieving the device parts. +\field{set_parts_resource_objects_limit} indicates the supported device parts +resource objects for restoring the device parts. + +\paragraph{VIRTIO_RESOURCE_OBJ_DEV_PARTS}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-RESOURCE-OBJ-DEV-PARTS} + +A device parts resource object is used to either get or set the device parts. +Before performing any get or set operation for the device parts, the driver +creates the device parts resource object +VIRTIO_RESOURCE_OBJ_DEV_PARTS using the administration command +\nameref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-CREATE}. +The driver indicates the intended purpose (get or set) at the time of creating the +device parts resource object. +For the device parts resource object, both \field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_resource_obj_dev_parts}. + +\begin{lstlisting} +struct virtio_resource_obj_dev_parts { + u8 type; +#define VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_GET 0 +#define VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_SET 1 + u8 reserved[7]; +}; +\end{lstlisting} + +When \field{type} is set to VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_GET, +the driver can use the object to capture the device parts and the metadata of +these device parts. When \field{type} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS_TYPE_SET, the driver can use the +object to restore the device parts. + +\paragraph{Device parts handling commands}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands} + +The owner driver uses the following resource object handling administration +commands. These commands are only used for the device parts resource +object after the driver creates the VIRTIO_RESOURCE_OBJ_DEV_PARTS object. +These commands are currently only defined for the SR-IOV group type: + +\begin{enumerate} +\item VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET +\item VIRTIO_ADMIN_CMD_DEV_PARTS_GET +\item VIRTIO_ADMIN_CMD_DEV_PARTS_SET +\end{enumerate} + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-METADATA-GET} + +This command obtains the metadata of the device parts. This metadata includes +the maximum size of the device parts, the count of device parts, and a list of +the device part headers. + +For the command VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET, \field{opcode} is set +to 0xe. The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_parts_metadata_data}. +\field{group_member_id} refers to the member device to be accessed. +The resource object \field{type} in the \field{hdr} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS and \field{id} is set to the ID of the +device parts resource object. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_parts_metadata_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + u8 type; + u8 reserved[7]; +}; + +#define VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_SIZE 0 +#define VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_COUNT 1 +#define VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_LIST 2 + +struct virtio_admin_cmd_dev_parts_metadata_result { + union { + struct { + le32 size; + le32 reserved; + } parts_size; + struct { + le32 count; + le32 reserved; + } hdr_list_count; + struct { + le32 count; + le32 reserved; + struct virtio_dev_part_hdr hdrs[]; + } hdr_list; + }; +}; +\end{lstlisting} + +When the command completes successfully, the +\field{command_specific_result} is in the format +\field{struct virtio_admin_cmd_dev_parts_metadata_result}. + +When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_SIZE, +the device responds with \field{parts_size}. \field{parts_size.size} indicates +the maximum size in bytes for all the device parts. + +When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_COUNT, the +device responds with \field{hdr_list_count.count}. The +\field{hdr_list_count.count} indicates an count of +\field{struct virtio_dev_part_hdr} metadata entries that the device can +provide when the \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_LIST +in a subsequent VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET command. + +When \field{type} is set to VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_TYPE_LIST, +the device responds with \field{hdr_list}. \field{hdr_list} +indicates the device parts metadata. + +\field{reserved} is reserved and set to 0. + +The command responds with the \field{status} VIRTIO_ADMIN_STATUS_ENOMEM +when the size of \field{command_specific_result} is not sufficient enough +for the response. + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_GET} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-GET} + +This command captures the device parts. For the command +VIRTIO_ADMIN_CMD_DEV_PARTS_GET, \field{opcode} is set to 0xf. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_parts_get_data}. +\field{group_member_id} refers to the member device to be accessed. +The resource object \field{type} in the \field{hdr} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS and \field{id} is set to the ID of the +device parts resource object. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_parts_get_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + u8 type; + u8 reserved[7]; + struct virtio_dev_part_hdr hdr_list[]; +}; + +#define VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_SELECTED 0 +#define VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_ALL 1 + +struct virtio_admin_cmd_dev_parts_get_result { + struct virtio_dev_part parts[]; +}; + +\end{lstlisting} + +When the driver wants to capture specific device parts, \field{type} is set to +VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_SELECTED and \field{hdr_list} is set to the +device parts of interest. + +When the driver wants to retrieve all the device parts, \field{type} is set to +VIRTIO_ADMIN_CMD_DEV_PARTS_GET_TYPE_ALL, and \field{hdr_list} is empty. + +\field{reserved} is reserved and set to 0. + +When the command completes successfully, the \field{command_specific_result} is +in the format \field{struct virtio_admin_cmd_dev_parts_get_result}, containing +either the selected device parts or all the device parts. + +If the requested device part does not exist, the device skips the device part +without any error. + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_PARTS_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-SET} + +This command sets one or multiple device parts. For the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET, \field{opcode} is set to 0x10. +The \field{group_member_id} refers to the member device to be accessed. +The resource object \field{type} in the \field{hdr} is set to +VIRTIO_RESOURCE_OBJ_DEV_PARTS and \field{id} is set to the ID of the +device parts resource object. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_parts_set_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + struct virtio_dev_part parts[]; +}; +\end{lstlisting} + +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_parts_set_data}. + +This command has no command specific result. + +The driver stops the device before setting any device parts. + +When the command completes successfully, the device has updated device +parts to the value supplied in \field{virtio_admin_cmd_dev_parts_set_data}. + +The device parts set by this command take effect when the device is resumed +using the VIRTIO_ADMIN_CMD_DEV_MODE_SET command. + +When the command fails with a status other than VIRTIO_ADMIN_STATUS_OK, the +device does not have any side effects. + +\subparagraph{VIRTIO_ADMIN_CMD_DEV_MODE_SET}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-MODE-SET} + +This command either stops the device from initiating any transport requests or +resumes the device operation. For the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, +\field{opcode} is set to 0x11. \field{group_member_id} indicates the member +device to be accessed. + +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_dev_mode_set_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_dev_mode_set_data { + u8 flags; +}; + +#define VIRTIO_ADMIN_CMD_DEV_MODE_F_STOPPED 0 +\end{lstlisting} + +This command has no command specific result. + +When the command completes successfully and if the \field{flags} field is set +to VIRTIO_ADMIN_CMD_DEV_MODE_F_STOPPED (bit 0), the device is stopped. +When the device is stopped, the device stops initiating all transport +communications, which includes: + +\begin{enumerate} +\item stopping configuration change notifications +\item stopping all virtqueue notifications +\item stops accessing all virtqueues and the driver buffer memory +\end{enumerate} + +After the device is stopped, the device parts remain unchanged unless +the driver initiates any transport requests. + +When the device is stopped, it writes back any associated descriptors for all +observed buffers to prevent out-of-order processing if the device is resumed. + +When the command completes successfully and if the \field{flags} field +is set to zero, the device resumes its operation. If the command completes +with an error, it does not produce any side effects on the device. + +\paragraph{Device parts order}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order} + +Device parts are usually captured and restored using get and set administration +commands respectively; when multiple device parts are captured or restored, +they are arranged in the specific order listed: + +Some of the device parts do not need to be written to the device when restored, such +device parts are listed as \field{O}. When a such an optional device part is +exchanged using \field{struct virtio_dev_part}, it is marked as optional by +setting VIRTIO_DEV_PART_F_OPTIONAL(bit 0) in the \field{flags}. + +\begin{table}[H] +\caption{Device parts order} +\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order} +\begin{tabularx}{\textwidth}{ |l|l|X| } +\hline +Part name & Optional & Mandatory preceding parts \\ +\hline \hline +\hline +VIRTIO_DEV_PART_DEV_FEATURES & O & Nil \\ +\hline +VIRTIO_DEV_PART_DRV_FEATURES & - & Nil \\ +\hline +VIRTIO_DEV_PART_PCI_COMMON_CFG & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES \\ +\hline +VIRTIO_DEV_PART_DEVICE_STATUS & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG \\ +\hline +VIRTIO_DEV_PART_VQ_CFG & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG, + VIRTIO_DEV_PART_DEVICE_STATUS \\ +\hline +VIRTIO_DEV_PART_VQ_NOTIFY_CFG & - & VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_DRV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG, + VIRTIO_DEV_PART_DEVICE_STATUS, VIRTIO_DEV_PART_VQ_CFG \\ +\hline +\hline +\end{tabularx} +\end{table} + +\devicenormative{\subparagraph}{Device parts}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} + +A device MUST either support all of, or none of +VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET, +VIRTIO_ADMIN_CMD_DEV_PARTS_GET, VIRTIO_ADMIN_CMD_DEV_PARTS_SET, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, and +VIRTIO_ADMIN_CMD_DEV_MODE_SET commands, where resource commands apply to +the resource object VIRTIO_RESOURCE_OBJ_DEV_PARTS. + +The device MUST support getting the device parts multiple times +with the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET. + +When there are multiple device parts in the command +VIRTIO_ADMIN_CMD_DEV_PARTS_GET, the device MUST respond the device parts in the +same order as listed in the table +\nameref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order}. + +The device SHOULD respond with an error status for the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET if the device is not stopped. + +The device MUST support the command VIRTIO_ADMIN_CMD_DEV_PARTS_SET, +allowing the same or different device parts to be set multiple times. + +The device MUST respond with an error for the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET, if there is a mismatch between the +device part length supplied in the VIRTIO_ADMIN_CMD_DEV_PARTS_SET +and the device part length in the device. + +The device MUST NOT set the device part VIRTIO_DEV_PART_DEV_FEATURES in +the command VIRTIO_ADMIN_CMD_DEV_PARTS_SET; instead, +it must verify that the device features supplied in +VIRTIO_DEV_PART_DEV_FEATURES match those the device has. + +The device may ignore the setting of a device part that has the +VIRTIO_DEV_PART_F_OPTIONAL bit set. + +For the SR-IOV group type, when the device is stopped using the command +VIRTIO_ADMIN_CMD_DEV_MODE_SET, +\begin{itemize} +\item the device MUST not initiate any PCI transaction, +\item the device MUST finish all the outstanding PCI transactions before completing + the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, +\item the device MUST write any associated descriptors to the driver memory for + all the observed buffers, +\item the device MUST accept driver notifications and the device MAY update any + device parts, +\item the device MUST respond with valid values for PCI read requests, +\item the device MUST operate in the same way for the PCI architected interfaces + regardless of the device mode. +\item the device MUST not generate any PCI PME. +\end{itemize} + +When the device is stopped, +\begin{itemize} +\item the device MUST not access any virtqueue memory or any memory referred + by the virtqueue. +\item the device MUST not generate any configuration change notification + or any virtqueue notification. +\end{itemize} + +For the SR-IOV group type, +\begin{itemize} +\item the device MUST respond to the commands +VIRTIO_ADMIN_CMD_DEV_MODE_SET, VIRTIO_ADMIN_CMD_DEV_PARTS_SET +after the member device completes FLR, if the FLR is in progress on the device +when the device receives any of these commands. + +\item the member device MUST respond to the commands +VIRTIO_ADMIN_CMD_DEV_MODE_SET and VIRTIO_ADMIN_CMD_DEV_PARTS_SET +after the device reset completes in the device, if the +device reset is in progress when the device receives any of these commands. + +\item the member device MUST respond to commands +VIRTIO_ADMIN_CMD_DEV_MODE_SET and VIRTIO_ADMIN_CMD_DEV_PARTS_SET +after the device power management state +transition completes on the device, if the power management state transition +is in progress when the device receives any of these commands. +\end{itemize} + +When the \field{flags} is set to VIRTIO_ADMIN_CMD_DEV_MODE_FLAGS_STOPPED +in the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, and if the device is already +stopped before, the device MUST complete the command successfully. + +When the VIRTIO_ADMIN_CMD_DEV_MODE_FLAGS_STOPPED \field{flags} clear, +in the command VIRTIO_ADMIN_CMD_DEV_MODE_SET, and if the device is +not stopped before, the device MUST complete the command successfully. + +For the SR-IOV group type, the device MUST clear all the device parts to +the default value when the member device is reset or undergo an PCI FLR. + +The device MAY NOT respond to the selected device part in \field{hdr_list} +in the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET if the device part is invalid +in the device. + +For the commands VIRTIO_ADMIN_CMD_DEV_PARTS_GET and +VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET, when the device responds with: +\begin{itemize} +\item +VIRTIO_DEV_PART_DRV_FEATURES or VIRTIO_DEV_PART_PCI_COMMON_CFG, it MUST be +preceded by VIRTIO_DEV_PART_DEV_FEATURES. + +\item VIRTIO_DEV_PART_PCI_COMMON_CFG, it MUST be preceded by +VIRTIO_DEV_PART_DEV_FEATURES. + +\item VIRTIO_DEV_PART_PCI_COMMON_CFG, it MUST be preceded by +VIRTIO_DEV_PART_DEV_FEATURES and VIRTIO_DEV_PART_DRV_FEATURES. + +\item VIRTIO_DEV_PART_DEV_CFG, it MUST be preceded by VIRTIO_DEV_PART_DEV_FEATURES. + +\item VIRTIO_DEV_PART_DRV_CFG, it be preceded by VIRTIO_DEV_PART_DEV_FEATURES, +VIRTIO_DEV_PART_DRV_FEATURES and VIRTIO_DEV_PART_DEV_CFG. + +\item VIRTIO_DEV_PART_DEVICE_STAtUS, it is preceded by VIRTIO_DEV_PART_DEV_FEATURES, +VIRTIO_DEV_PART_DRV_FEATURES, and VIRTIO_DEV_PART_DEV_CFG. +\end{itemize} + +When the device receives a VIRTIO_ADMIN_CMD_DEV_PARTS_SET command containing the +parts VIRTIO_DEV_PART_DEV_FEATURES, VIRTIO_DEV_PART_PCI_COMMON_CFG and +VIRTIO_DEV_PART_DEV_CFG, the device SHOULD only verify that the provided configuration is +correct but SHOULD NOT apply it, especially for the fields that are designated +as read-only and invariant. This ensures that the device respects the +immutability of certain configuration aspects while still performing necessary +validation checks. + +\drivernormative{\subparagraph}{Device parts}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} + +The driver MUST set the mode to VIRTIO_ADMIN_CMD_DEV_MODE_F_STOPPED in +the command VIRTIO_ADMIN_CMD_DEV_MODE_SET before setting parts using the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET. + +When there are multiple device parts in the command +VIRTIO_ADMIN_CMD_DEV_PARTS_SET, the driver MUST set the device parts in the same +order as listed in the table +\nameref{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts order/ Device parts order}. + +For the SR-IOV group type, the driver SHOULD NOT access the device configuration +space described in section +\ref{sec:Basic Facilities of a Virtio Device / Device Configuration Space} +when the device is stopped. + +The driver SHOULD allocate sufficient response buffer to receive all the device +parts metadata in the command VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET. + +The driver SHOULD allocate sufficient response buffer to receive all the device +parts in the command VIRTIO_ADMIN_CMD_DEV_PARTS_GET. diff --git a/admin-cmds-legacy-interface.tex b/admin-cmds-legacy-interface.tex index b9c96d4..56142aa 100644 --- a/admin-cmds-legacy-interface.tex +++ b/admin-cmds-legacy-interface.tex @@ -17,10 +17,10 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device The following commands support such a legacy interface functionality: \begin{enumerate} -\item Legacy Common Configuration Write Command -\item Legacy Common Configuration Read Command -\item Legacy Device Configuration Write Command -\item Legacy Device Configuration Read Command +\item VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE +\item VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ +\item VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE +\item VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ \end{enumerate} These commands are currently only defined for the SR-IOV group type and @@ -29,8 +29,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device Bus / PCI Device Layout / Legacy Interfaces: A Note on PCI Device Layout} except that little-endian format is assumed unconditionally. -\paragraph{Legacy Common Configuration Write Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group -administration commands / Legacy Interface / Legacy Common Configuration Write Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-WRITE} This command has the same effect as writing into the virtio common configuration structure through the legacy interface. The \field{command_specific_data} is in @@ -59,7 +59,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device This command has no command specific result. -\paragraph{Legacy Common Configuration Read Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Common Configuration Read Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-READ} This command has the same effect as reading from the virtio common configuration structure through the legacy interface. The \field{command_specific_data} is in @@ -94,7 +95,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device returned by the device. The length of the data read is simply the length of \field{data}. -\paragraph{Legacy Device Configuration Write Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Device Configuration Write Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-WRITE} This command has the same effect as writing into the virtio device-specific configuration through the legacy interface. The \field{command_specific_data} is in @@ -123,7 +125,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device This command has no command specific result. -\paragraph{Legacy Device Configuration Read Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Device Configuration Read Command} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-READ} This command has the same effect as reading from the virtio device-specific configuration through the legacy interface. The \field{command_specific_data} is in @@ -159,7 +162,8 @@ \subsubsection{Legacy Interfaces}\label{sec:Basic Facilities of a Virtio Device The length of the data read is simply the length of \field{data}. -\paragraph{Legacy Driver Notification}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / Legacy Driver Notifications} +\paragraph{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-NOTIFY-INFO} The driver of the owner device can send a driver notification to the member device operated using the legacy interface by executing diff --git a/admin-cmds-resource-objects.tex b/admin-cmds-resource-objects.tex new file mode 100644 index 0000000..68f5862 --- /dev/null +++ b/admin-cmds-resource-objects.tex @@ -0,0 +1,287 @@ +\subsubsection{Device resource objects}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} + +Providing certain functionality consumes limited device resources such as +memory, processing units, buffer memory, or end-to-end credits. A device may +support multiple types of resource objects, each controlling different device +functionality. To manage this, virtio provides +\field{Device resource objects} that the driver can create, modify, and +destroy using administration commands with the self group type. Creating and +destroying a resource object consume and release device resources, respectively. +The device resource object query command returns the resource object as +maintained by the device. + +For each resource type, the number of resource objects that can be created +is reported by the device as part of a device capability +\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities}. +The driver reports the desired (same or lower) number of resource objects +as part of a driver capability \ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities}. +For each device object type, resource object limit is defined by field +\field{limit} using \field{Device and driver capabilities}. + +\begin{lstlisting} +le32 limit; /* maximum resource id = limit - 1 */ +\end{lstlisting} + +Each resource object has a unique resource object ID - a driver-assigned number +in the range of 0 to \field{limit - 1}, where the \field{limit} is the maximum +number set by the driver for this resource object type. These resource IDs are unique within +each resource object type. The driver assigns the resource ID when creating a +device resource object. Once the resource object is successfully created, +subsequent resource modification, query, and destroy commands use this +resource object ID. No two resource objects share the same ID. Destroying a +resource object allows for the reuse of its ID for another resource object +of the same type. + +A valid resource object id is \field{limit - 1}. For example, when a device +reports a \field{limit = 10} capability for a resource object, and drivers sets +\field{limit = 8}, the valid resource object id range for the device and the +driver is 0 to 7 for all the resource object commands. In this example, +the driver can only create 8 resource objects of a specified type. + +A resource object of one type may depend on the resource object of another type. +Such dependency between resource objects is established by referring to the unique +resource ID in the administration commands. For example, a driver creates a +resource object identified by ID A of one type, then creates another resource +object identified by ID B of a different type, which depends on resource object +A. This dependency establishes the lifecycle of these resource objects. The driver +that creates the dependent resource object must destroy the resource objects in the +exact reverse order of their creation. In this example, the driver would +destroy resource object B before destroying resource object A. + +Some resource object types are generic, common across multiple devices. +Others are specific for one device type. + +\begin{tabular}{|l|l|} +\hline +Resource object type & Description \\ +\hline \hline +0x000-0x1ff & Generic resource object type common across all devices \\ +\hline +0x200-0x4ff & Device type specific resource object \\ +\hline +0x500-0xffff & Reserved for future use \\ +\hline +\end{tabular} + +Following generic resource objects are defined which are described separately. + +\begin{tabularx}{\textwidth}{ |X||X|X| } +\hline +Resource object type & Name & Description \\ +\hline \hline +0x000 & VIRTIO_RESOURCE_OBJ_DEV_PARTS & Device parts object, see \ref{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO-RESOURCE-OBJ-DEV-PARTS} \\ +\hline +0x001-0x1ff & - & Generic resource object range reserved \\ +\hline +\hline +\end{tabularx} + +When the device resets, it starts with zero resources of each type; the driver +can create resources up to the published \field{limit}. The driver can +destroy and recreate the resource one or multiple times. Upon device reset, +all resource objects created by the driver are destroyed within the device. + +Following administration commands control device resource objects, +they are supported for the self group type, occasionally some resource +objects can be created for the SR-IOV group type as well. Such sr-iov group +type specific resource objects are listed where such objects is defined. + +\begin{enumerate} +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY +\item VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY +\end{enumerate} + +Each resource object administration command uses a common header +\field{struct virtio_admin_cmd_resource_obj_cmd_hdr}. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_cmd_hdr { + le16 type; + u8 reserved[2]; + le32 id; /* Indicates unique resource object id per resource object type */ +}; + +\end{lstlisting} + +\field{type} refers to the device resource object type. +\field{id} uniquely identifies the resource object of a specified \field{type}. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-CREATE} + +This command creates the specified resource object of \field{type} identified by the +resource id \field{id}. The valid range of \field{id} is defined by the +device in the related device capability. The driver assigns the unique \field{id} +for the resource for the specified \field{type}. + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, \field{opcode} is set to 0xa. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_obj_create_data}. +\field{resource_obj_specific_data} refers to the resource object specific data. +Each resource uses a different \field{resource_obj_specific_data} and is described +separately. + +\field{flags} is reserved for future extension for optional resource object attributes and +is set to 0. Each resource object uses a different value for +\field{flags} and it is described separately. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_create_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + le64 flags; + u8 resource_obj_specific_data[]; +}; +\end{lstlisting} + +When the command completes successfully, the resource object is created by the +device and the device can immediately begin using it. +This command has no command specific result. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-MODIFY} + +This command modifies the attributes of an existing device resource object. +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, \field{opcode} is set to 0xb. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_modify_data}. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. +\field{id} identifies the resource object of type \field{type} whose attributes +to modify. +This command modifies the attributes supplied in \field{resource_obj_specific_data}. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_modify_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + le64 flags; + u8 resource_obj_specific_data[]; +}; +\end{lstlisting} + +This command has no command specific result. +When the command completes successfully, attributes of the resource object is +set to the values supplied in \field{resource_obj_specific_data}. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-QUERY} + +This command queries attributes of the existing resource object. +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, \field{opcode} is set to 0xc. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_obj_query_data}. +\field{id} identifies the existing resource object of type \field{type} whose +attributes to query. + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_query_data { + struct virtio_admin_cmd_resource_obj_cmd_hdr hdr; + le64 flags; +}; +\end{lstlisting} + +\begin{lstlisting} +struct virtio_admin_cmd_resource_obj_query_result { + u8 resource_obj_specific_result[]; +}; +\end{lstlisting} + +\field{command_specific_result} is in the format +\field{virtio_admin_cmd_resource_obj_query_result}. + +When the command completes successfully, the attributes of the specified +resource object are are set in \field{resource_obj_specific_data}. + +\paragraph{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} +\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-DESTROY} + +This command destroys the previously created device resource object. +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY, \field{opcode} is set to 0xd. +The \field{command_specific_data} is in the format +\field{struct virtio_admin_cmd_resource_obj_cmd_hdr}. +\field{group_member_id} is set to zero for self-group type and set to +the member device to be accessed for the SR-IOV group type. +\field{id} identifies the existing resource object of type \field{type}. + +This command destroys the specified resource object of \field{type} identified +by \field{id}, which is previously created using +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE command. + +This command has no command specific result. +When the command completes successfully, the resource object is destroyed from the device. + +\devicenormative{\paragraph}{Device resource objects}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} + +The device SHOULD complete the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +with \field{status} set to VIRTIO_ADMIN_STATUS_EEXIST if a resource object already exists +with supplied resource \field{id} for the specified \field{type}. + +The device SHOULD complete the commands VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, +VIRTIO_ADMIN_CMD_RESOURCE_QUERY and +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY with \field{status} set to +VIRTIO_ADMIN_STATUS_ENXIO if the specified resource object does not exist. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE if the device fail to create the +resource object. + +The device SHOULD complete the commands VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY or +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY commands with \field{status} set to +VIRTIO_ADMIN_STATUS_EBUSY if other resource objects depend on the resource object +being modified or destroyed. + +The device MUST allow recreating the resource object using the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE which was previously +destroyed using the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY respectively +without undergoing a device reset. + +The device SHOULD allow creating the resource object using +the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE with any resource +id as long as the resource object is not created. + +The device MAY fail the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE even if the +resources within the device have not reached up to the \field{max_limit} +but the device MAY have reached an internal limit. + +When a capability represents a number of resource objects, the device SHOULD +allow creating as many resource objects as represented by the driver capability. + +The device MUST NOT have any side effects on the resource object when the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY fails. + +The device MUST complete the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY +with \field{resource_obj_specific_data} which is matching the +\field{resource_obj_specific_data} of last VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +or VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY command. + +On device reset, the device MUST destroy all the resource objects which +have been created. + +\drivernormative{\paragraph}{Device resource objects}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} + +The driver MUST not create a second resource object of the same type with same +ID using command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE before destroying the +previously created resource object. + +The driver MUST NOT create more resource objects of a specified \field{type} using +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE than the maximum limit set by the +driver capability. + +The driver SHOULD NOT modify, query and destroy the resource object which is +already destroyed previously by the driver. + +The driver SHOULD NOT destroy the resource object on which other resource objects +are depending; the driver SHOULD destroy all the resource objects which do not depend +on other resource objects. + +The driver MUST NOT set the capability related to the resource objects if the +resource objects have been created using the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE +and not yet destroyed. + +The driver MUST send the command VIRTIO_ADMIN_CMD_DRIVER_CAP_SET before using +any resources related to such capability. diff --git a/admin.tex b/admin.tex index 0803c26..cfca5e3 100644 --- a/admin.tex +++ b/admin.tex @@ -1,7 +1,10 @@ \section{Device groups}\label{sec:Basic Facilities of a Virtio Device / Device groups} It is occasionally useful to have a device control a group of -other devices. Terminology used in such cases: +other devices (the group may occasionally include the device +itself) within a group. The owner device itself is not a +member of the group (except in the special case of the self group). +Terminology used in such cases: \begin{description} \item[Device group] @@ -10,7 +13,7 @@ \section{Device groups}\label{sec:Basic Facilities of a Virtio Device / Device g or owner, the device controlling the group. \item[Member device] a device within a group. The owner device itself is not - a member of the group. + a member of the group except for the \field{Self group type}. \item[Member identifier] each member has this identifier, unique within the group and used to address it through the owner device. @@ -37,6 +40,11 @@ \section{Device groups}\label{sec:Basic Facilities of a Virtio Device / Device g The following group types, and their identifiers, are currently specified: \begin{description} +\item[Self group type (0x0)] +This device group includes the owner device itself and no other devices. +The group type identifier for this group is 0x0. +The member identifier for this group has a value of 0x0. + \item[SR-IOV group type (0x1)] This device group has a PCI Single Root I/O Virtualization (SR-IOV) physical function (PF) device as the owner and includes @@ -78,6 +86,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti /* Device-readable part */ le16 opcode; /* + * 0 - Self * 1 - SR-IOV * 2-65535 - reserved */ @@ -117,17 +126,40 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline 0x0001 & VIRTIO_ADMIN_CMD_LIST_USE & Provides to device list of commands used for this group type \\ \hline -0x0002 & VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE & Writes into the legacy common configuration structure \\ +0x0002 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-WRITE]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_WRITE} & Writes into the legacy common configuration structure \\ +\hline +0x0003 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-COMMON-CFG-READ]{VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ} & Reads from the legacy common configuration structure \\ +\hline +0x0004 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-WRITE]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE} & Writes into the legacy device configuration structure \\ +\hline +0x0005 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-DEV-CFG-READ]{VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ} & Reads into the legacy device configuration structure \\ +\hline +0x0006 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Legacy Interface / VIRTIO-ADMIN-CMD-LEGACY-NOTIFY-INFO]{VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO} & Query the notification region information \\ +\hline +0x0007 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-CAP-ID-LIST-QUERY]{VIRTIO_ADMIN_CMD_CAP_ID_LIST_QUERY} & Query the supported device capabilities bitmap \\ +\hline +0x0008 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DEVICE-CAP-GET]{VIRTIO_ADMIN_CMD_DEVICE_CAP_GET} & Get the device capabilities \\ +\hline +0x0009 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / VIRTIO-ADMIN-CMD-DRIVER-CAP-SET]{VIRTIO_ADMIN_CMD_DRIVER_CAP_SET} & Set the driver capabilities \\ \hline -0x0003 & VIRTIO_ADMIN_CMD_LEGACY_COMMON_CFG_READ & Reads from the legacy common configuration structure \\ +0x000a & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-CREATE]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE} & Create a device resource object \\ \hline -0x0004 & VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_WRITE & Writes into the legacy device configuration structure \\ +0x000c & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-MODIFY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY} & Modify a device resource object \\ \hline -0x0005 & VIRTIO_ADMIN_CMD_LEGACY_DEV_CFG_READ & Reads into the legacy device configuration structure \\ +0x000b & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-QUERY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY} & Query a device resource object \\ \hline -0x0006 & VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO & Query the notification region information \\ +0x000d & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects / VIRTIO-ADMIN-CMD-RESOURCE-OBJ-DESTROY]{VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY} & Destroy a device resource object \\ \hline -0x0007 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ +0x000e & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-METADATA-GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_METADATA_GET} & Get the metadata of the device parts \\ +\hline +0x000f & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-GET]{VIRTIO_ADMIN_CMD_DEV_PARTS_GET} & Get the device parts \\ +\hline +0x0010 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-PARTS-SET]{VIRTIO_ADMIN_CMD_DEV_PARTS_SET} & Set the device parts \\ +\hline +0x0011 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / Device parts handling commands / VIRTIO-ADMIN-CMD-DEV-MODE-SET]{VIRTIO_ADMIN_CMD_DEV_MODE_SET} & Stop or resume the device \\ +\hline +\hline +0x0013 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd} \\ \hline 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure) \\ \hline @@ -153,12 +185,18 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti \hline \hline 00 & VIRTIO_ADMIN_STATUS_OK & successful completion \\ \hline +06 & VIRTIO_ADMIN_STATUS_ENXIO & no such capability or resource\\ +\hline 11 & VIRTIO_ADMIN_STATUS_EAGAIN & try again \\ \hline 12 & VIRTIO_ADMIN_STATUS_ENOMEM & insufficient resources \\ \hline +16 & VIRTIO_ADMIN_STATUS_EBUSY & device busy \\ +\hline 22 & VIRTIO_ADMIN_STATUS_EINVAL & invalid command \\ \hline +28 & VIRTIO_ADMIN_STATUS_ENOSPC & resources exhausted on device \\ +\hline other & - & group administration command error \\ \hline \end{tabular} @@ -297,6 +335,9 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti might differ between different group types. \input{admin-cmds-legacy-interface.tex} +\input{admin-cmds-capabilities.tex} +\input{admin-cmds-resource-objects.tex} +\input{admin-cmds-device-parts.tex} \devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands} @@ -450,7 +491,7 @@ \section{Administration Virtqueues}\label{sec:Basic Facilities of a Virtio Devic than one administration virtqueue. If VIRTIO_F_ADMIN_VQ has been negotiated, an owner device exposes one -or more adminstration virtqueues. The number and locations of the +or more administration virtqueues. The number and locations of the administration virtqueues are exposed by the owner device in a transport specific manner. diff --git a/conformance.tex b/conformance.tex index dc00e84..d92a236 100644 --- a/conformance.tex +++ b/conformance.tex @@ -32,8 +32,10 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Driver Conformance / Memory Driver Conformance}, \ref{sec:Conformance / Driver Conformance / I2C Adapter Driver Conformance}, \ref{sec:Conformance / Driver Conformance / SCMI Driver Conformance}, -\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance} or -\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}. +\ref{sec:Conformance / Driver Conformance / GPIO Driver Conformance}, +\ref{sec:Conformance / Driver Conformance / PMEM Driver Conformance}, +\ref{sec:Conformance / Driver Conformance / CAN Driver Conformance} or +\ref{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -59,8 +61,10 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \ref{sec:Conformance / Device Conformance / Memory Device Conformance}, \ref{sec:Conformance / Device Conformance / I2C Adapter Device Conformance}, \ref{sec:Conformance / Device Conformance / SCMI Device Conformance}, -\ref{sec:Conformance / Device Conformance / GPIO Device Conformance} or -\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}. +\ref{sec:Conformance / Device Conformance / GPIO Device Conformance}, +\ref{sec:Conformance / Device Conformance / PMEM Device Conformance}, +\ref{sec:Conformance / Device Conformance / CAN Device Conformance} or +\ref{sec:Conformance / Device Conformance / SPI Controller Device Conformance}. \item Clause \ref{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance}. \end{itemize} @@ -76,6 +80,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Device Reset} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Device Configuration Space} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues} +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Message Framing} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} @@ -94,6 +99,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{drivernormative:General Initialization And Device Operation / Device Initialization} \item \ref{drivernormative:General Initialization And Device Operation / Device Cleanup} \item \ref{drivernormative:Reserved Feature Bits} +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities} +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} \end{itemize} \conformance{\subsection}{PCI Driver Conformance}\label{sec:Conformance / Driver Conformance / PCI Driver Conformance} @@ -152,6 +160,8 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/scmi/driver-conformance.tex} \input{device-types/gpio/driver-conformance.tex} \input{device-types/pmem/driver-conformance.tex} +\input{device-types/can/driver-conformance.tex} +\input{device-types/spi/driver-conformance.tex} \conformance{\section}{Device Conformance}\label{sec:Conformance / Device Conformance} @@ -162,6 +172,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Feature Bits} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Device Reset} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Device Configuration Space} +\item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset / Virtqueue Reset} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Message Framing} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors} @@ -173,6 +184,9 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Packed Virtqueues / Scatter-Gather Support} \item \ref{devicenormative:Basic Facilities of a Virtio Device / Shared Memory Regions} \item \ref{devicenormative:Reserved Feature Bits} +\item \ref{devicenormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities} +\item \ref{devicenormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects} +\item \ref{devicenormative:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts} \end{itemize} \conformance{\subsection}{PCI Device Conformance}\label{sec:Conformance / Device Conformance / PCI Device Conformance} @@ -238,6 +252,8 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets} \input{device-types/scmi/device-conformance.tex} \input{device-types/gpio/device-conformance.tex} \input{device-types/pmem/device-conformance.tex} +\input{device-types/can/device-conformance.tex} +\input{device-types/spi/device-conformance.tex} \conformance{\section}{Legacy Interface: Transitional Device and Transitional Driver Conformance}\label{sec:Conformance / Legacy Interface: Transitional Device and Transitional Driver Conformance} A conformant implementation MUST be either transitional or diff --git a/content.tex b/content.tex index c17ffa6..67b1bf3 100644 --- a/content.tex +++ b/content.tex @@ -493,7 +493,7 @@ \section{Driver Notifications} \label{sec:Basic Facilities of a Virtio Device / \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Exporting Objects} When an object created by one virtio device needs to be -shared with a seperate virtio device, the first device can +shared with a separate virtio device, the first device can export the object by generating a UUID which can then be passed to the second device to identify the object. @@ -503,11 +503,12 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo UUIDs as specified by \hyperref[intro:rfc4122]{[RFC4122]}. \input{admin.tex} +\input{device-parts.tex} \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation} We start with an overview of device initialization, then expand on the -details of the device and how each step is preformed. This section +details of the device and how each step is performed. This section is best read along with the bus-specific section which describes how to communicate with the specific device. @@ -649,7 +650,7 @@ \chapter{Device Types}\label{sec:Device Types} Discovering what devices are available and their type is bus-dependent. -\begin{tabular} { |l|c| } +\begin{longtable} { |l|c| } \hline Device ID & Virtio Device \\ \hline \hline @@ -737,9 +738,15 @@ \chapter{Device Types}\label{sec:Device Types} \hline 44 & ISM device \\ \hline -45 & SPI master \\ +45 & SPI controller \\ \hline -\end{tabular} +46 & TEE device \\ +\hline +47 & CPU balloon device \\ +\hline +48 & Media device \\ +\hline +\end{longtable} Some of the devices above are unspecified by this document, because they are seen as immature or especially niche. Be warned @@ -767,6 +774,8 @@ \chapter{Device Types}\label{sec:Device Types} \input{device-types/scmi/description.tex} \input{device-types/gpio/description.tex} \input{device-types/pmem/description.tex} +\input{device-types/can/description.tex} +\input{device-types/spi/description.tex} \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits} diff --git a/device-parts.tex b/device-parts.tex new file mode 100644 index 0000000..7197929 --- /dev/null +++ b/device-parts.tex @@ -0,0 +1,232 @@ +\section{Device parts}\label{sec:Basic Facilities of a Virtio Device / Device parts} + +Device parts represent the device state, with parts for basic +device facilities such as driver features, as well as transport specific +and device type specific parts. In memory, each device part consists +of a header \field{struct virtio_dev_part_hdr} followed by +the device part data in \field{value}. The driver can get and set +these device parts using administration commands. + +\begin{lstlisting} +struct virtio_dev_part_hdr { + le16 part_type; + u8 flags; + u8 reserved; + union { + struct { + le32 offset; + le32 reserved; + } pci_common_cfg; + struct { + le16 index; + u8 reserved[6]; + } vq_index; + } selector; + le32 length; +}; + +#define VIRTIO_DEV_PART_F_OPTIONAL 0 + +struct virtio_dev_part { + struct virtio_dev_part_hdr hdr; + u8 value[]; +}; + +\end{lstlisting} + +Each device part consists of a fixed size \field{hdr} followed by optional +part data in field \field{value}. The device parts are divided into +two categories and identified by \field{part_type}. The common device parts are +independent of the device type and, are in the range \field{0x0000 - 0x01FF}. Common +device parts are listed in +\ref{table:Basic Facilities of a Virtio Device / Device parts / Common device parts} +The device parts in the range \field{0x0200 - 0x05FF} are specific to a device type +such as a network or console device. +The device part is identified by the \field{part_type} field as listed: + +\begin{description} +\item[0x0000 - 0x01FF] - common part - used to describe a part of the device that + is independent of the device type +\item[0x0200 - 0x05FF] - device type specific part - used to indicate parts + that are device type specific +\item[0x0600 - 0xFFFF] - reserved +\end{description} + +Some device parts are optional, the device can function without them. +For example, such parts can help improve performance, with the device working +slower, yet still correctly, even without the parts. In another example, +optional parts can be used for validation, with the device being able to deduce +the part itself, the part being helpful to detect driver or user errors. +Such device parts are marked optional by setting bit 0 +(VIRTIO_DEV_PART_F_OPTIONAL) in the \field{flags}. + +\field{reserved} is reserved and set to zero. + +\field{length} indicates the length of the \field{value} in bytes. The length +of the device part depends on the device part itself and is described separately. +The device part data is in \field{value} and is \field{part_type} specific. + +\field{selector} further specifies the part. It is only used for some +\field{part_type} values. + +\field{selector.pci_common_cfg.offset} is the offset of the +field in the \nameref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}. It is valid only when the \field{part_type} is set to VIRTIO_DEV_PART_PCI_COMMON_CFG, +otherwise it is reserved and set to 0. + +\field{selector.vq_index.index} is the index of the virtqueue. It is valid +only when the \field{part_type} is VIRTIO_DEV_PART_VQ_CFG or +VIRTIO_DEV_PART_VQ_CFG. + +\subsection{Common device parts}\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts} + +Common parts are independent of the device type. +\field{part_type} and \field{value} for each part are documented as follows: + +\begin{table} +\caption{Common device parts} +\label{table:Basic Facilities of a Virtio Device / Device parts / Common device parts} +\begin{tabularx}{\textwidth}{ |l||l|X| } +\hline +Type & Name & Description \\ +\hline \hline +0x100 & VIRTIO_DEV_PART_DEV_FEATURES & Device features, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DEV-FEATURES} \\ +\hline +0x101 & VIRTIO_DEV_PART_DRV_FEATURES & Driver features, \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DRV-FEATURES} \\ +\hline +0x102 & VIRTIO_DEV_PART_PCI_COMMON_CFG & PCI common configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-PCI-COMMON-CFG} \\ +\hline +0x103 & VIRTIO_DEV_PART_DEVICE_STATUS & Device status, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DEVICE-STATUS} \\ +\hline +0x104 & VIRTIO_DEV_PART_VQ_CFG & Virtqueue configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-VQ-CFG} \\ +\hline +0x105 & VIRTIO_DEV_PART_VQ_NOTIFY_CFG & Virtqueue notification configuration, see \ref{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-VQ-NOTIFY-CFG} \\ +\hline +0x106 - 0x2FF & - & Common device parts range reserved for future \\ +\hline +\hline +\end{tabularx} +\end{table} + +\subsubsection{VIRTIO_DEV_PART_DEV_FEATURES} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DEV-FEATURES} + +For VIRTIO_DEV_PART_DEV_FEATURES, \field{part_type} is set to 0x100. +The VIRTIO_DEV_PART_DEV_FEATURES field indicates features offered by the device. +\field{value} is in the format of \field{struct virtio_dev_part_features}. +\field{feature_bits} is in the format listed in +\ref{sec:Basic Facilities of a Virtio Device / Feature Bits}. +\field{length} is the length of the \field{struct virtio_dev_part_features}. + +If the VIRTIO_DEV_PART_DEV_FEATURES device part is present, there is exactly +one instance of it in the get or set commands. + +The VIRTIO_DEV_PART_DEV_FEATURES part is optional for which +the VIRTIO_DEV_PART_F_OPTIONAL (bit 0) \field{flags} is set. + +\begin{lstlisting} +struct virtio_dev_part_features { + le64 feature_bits[]; +}; +\end{lstlisting} + +\subsubsection{VIRTIO_DEV_PART_DRV_FEATURES} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DRV-FEATURES} + +For VIRTIO_DEV_PART_DRV_FEATURES, \field{part_type} is set to 0x101. +The VIRTIO_DEV_PART_DRV_FEATURES field indicates features set by the driver. +\field{value} is in the format of \field{struct virtio_dev_part_features}. +\field{feature_bits} is in the format listed in +\ref{sec:Basic Facilities of a Virtio Device / Feature Bits}. +\field{length} is the length of the \field{struct virtio_dev_part_features}. + +If the VIRTIO_DEV_PART_DEV_FEATURES device part present, there is exactly +one instance of it in the get or set commands. + +\subsubsection{VIRTIO_DEV_PART_PCI_COMMON_CFG} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-PCI-COMMON-CFG} + +For VIRTIO_DEV_PART_PCI_COMMON_CFG, \field{part_type} is set to 0x102. +VIRTIO_DEV_PART_PCI_COMMON_CFG refers to the common device configuration +fields. \field{offset} refers to the +byte offset of single field in the common configuration layout described in +\field{struct virtio_pci_common_cfg}. \field{value} is in the format depending on +the \field{offset}, for example when \field{cfg_offset = 18}, \field{value} +is in the format of \field{num_queues}. \field{length} is the length of +\field{value} in bytes of a single structure field whose offset is \field{offset}. + +One or multiple VIRTIO_DEV_PART_PCI_COMMON_CFG parts may exist in the +get or set commands; each such part corresponds to a unique \field{offset}. + +\subsubsection{VIRTIO_DEV_PART_DEVICE_STATUS} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-DEVICE-STATUS} + +For VIRTIO_DEV_PART_DEVICE_STATUS, \field{part_type} is set to 0x103. +The VIRTIO_DEV_PART_DEVICE_STATUS field indicates the device status as listed in +\ref{sec:Basic Facilities of a Virtio Device / Device Status Field}. +\field{value} is in the format \field{device_status} of +\field{struct virtio_pci_common_cfg}. + +If the VIRTIO_DEV_PART_DEV_FEATURES device part is present, there is exactly +one instance of it in the get or set commands. + +There is exactly one part may exist in the get or set +commands. + +\subsubsection{VIRTIO_DEV_PART_VQ_CFG} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-VQ-CFG} + +For VIRTIO_DEV_PART_VQ_CFG, \field{part_type} is set to 0x104. +\field{value} is in the format \field{struct virtio_dev_part_vq_cfg}. +\field{length} is the length of \field{struct virtio_dev_part_vq_cfg}. + +\begin{lstlisting} +struct virtio_dev_part_vq_cfg { + le16 queue_size; + le16 vector; + le16 enabled; + le16 reserved; + le64 queue_desc; + le64 queue_driver; + le64 queue_device; +}; +\end{lstlisting} + +\field{queue_size}, \field{vector}, \field{queue_desc}, +\field{queue_driver} and \field{queue_device} correspond to the +fields of \field{struct virtio_pci_common_cfg} when used for PCI transport. + +One or multiple instances of the device part VIRTIO_DEV_PART_VQ_CFG may exist in +the get and set commands. Each such device part corresponds to a unique virtqueue identified +by the \field{vq_index.index}. + +\subsubsection{VIRTIO_DEV_PART_VQ_NOTIFY_CFG} +\label{sec:Basic Facilities of a Virtio Device / Device parts / Common device parts / VIRTIO-DEV-PART-VQ-NOTIFY-CFG} + +For VIRTIO_DEV_PART_VQ_NOTIFY_CFG, \field{part_type} is set to 0x105. +\field{value} is in the format \field{struct virtio_dev_part_vq_notify_data}. +\field{length} is the length of \field{struct virtio_dev_part_vq_notify_data}. + +\begin{lstlisting} +struct virtio_dev_part_vq_notify_data { + le16 queue_notify_off; + le16 queue_notif_config_data; + u8 reserved[4]; +}; +\end{lstlisting} + +\field{queue_notify_off} and \field{queue_notif_config_data} corresponds to the +fields in \field{struct virtio_pci_common_cfg} described in the +\nameref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}. + +One or multiple instance of the device part VIRTIO_DEV_PART_VQ_NOTIFY_CFG may exist +in the get and set commands, each such device part corresponds to a unique +virtqueue identified by the \field{vq_index.index}. + +\field{reserved} is reserved and set to 0. + +\subsection{Assumptions} +For the SR-IOV group type, some hypervisors do not allow the driver to access +the PCI configuration space and the MSI-X Table space directly. Such hypervisors +query and save these fields without the need for this device parts. +Therefore, this version of the specification does not have it in the device parts. A future +extension of the device part may further include them as new device part. diff --git a/device-types/blk/description.tex b/device-types/blk/description.tex index f04c932..2712ada 100644 --- a/device-types/blk/description.tex +++ b/device-types/blk/description.tex @@ -108,7 +108,7 @@ \subsection{Device configuration layout}\label{sec:Device Types / Block Device / } topology; u8 writeback; u8 unused0; - u16 num_queues; + le16 num_queues; le32 max_discard_sectors; le32 max_discard_seg; le32 discard_sector_alignment; diff --git a/device-types/can/description.tex b/device-types/can/description.tex new file mode 100644 index 0000000..24b29ed --- /dev/null +++ b/device-types/can/description.tex @@ -0,0 +1,249 @@ +\section{CAN Device}\label{sec:Device Types / CAN Device} + +virtio-can is a virtio based CAN (Controller Area Network) controller. +It is used to give a virtual machine access to a CAN bus. The CAN bus +might either be a physical CAN bus or a virtual CAN bus between virtual +machines or a combination of both. + +\subsection{Device ID}\label{sec:Device Types / CAN Device / Device ID} + +36 + +\subsection{Virtqueues}\label{sec:Device Types / CAN Device / Virtqueues} + +\begin{description} +\item[0] Txq +\item[1] Rxq +\item[2] Controlq +\end{description} + +The \field{Txq} is used to send CAN packets to the CAN bus. + +The \field{Rxq} is used to receive CAN packets from the CAN bus. + +The \field{Controlq} is used to control the state of the CAN controller. + +\subsection{Feature bits}{Device Types / CAN Device / Feature bits} + +Actual CAN controllers support Extended CAN IDs with 29 bits (CAN~2.0B) +as well as Standard CAN IDs with 11 bits (CAN~2.0A). The support of +CAN~2.0B Extended CAN IDs is considered as mandatory for this +specification. + +\begin{description} + +\item[VIRTIO_CAN_F_CAN_CLASSIC (0)] + +The device supports classic CAN frames with a maximum payload size of 8 +bytes. + +\item[VIRTIO_CAN_F_CAN_FD (1)] + +The device supports CAN FD frames with a maximum payload size of 64 +bytes. + +\item[VIRTIO_CAN_F_RTR_FRAMES (2)] + +The device supports RTR (remote transmission request) frames. RTR frames +are only supported with classic CAN. + +\item[VIRTIO_CAN_F_LATE_TX_ACK (3)] + +The virtio CAN device marks transmission requests from the \field{Txq} +as used after the CAN message has been transmitted on the CAN bus. If +this feature bit has not been negotiated, the device is allowed to mark +transmission requests already as used when the CAN message has been +scheduled for transmission but might not yet have been transmitted on +the CAN bus. + +\end{description} + +\subsubsection{Feature bit requirements}\label{sec:Device Types / CAN Device / Feature bits / Feature bit requirements} + +Some CAN feature bits require other CAN feature bits: +\begin{description} +\item[VIRTIO_CAN_F_RTR_FRAMES] Requires VIRTIO_CAN_F_CAN_CLASSIC. +\end{description} + +It is required that at least one of VIRTIO_CAN_F_CAN_CLASSIC and +VIRTIO_CAN_F_CAN_FD is negotiated. + +\subsection{Device configuration layout}\label{sec:Device Types / CAN Device / Device configuration layout} + +Device configuration fields are listed below, they are read-only for a +driver. The \field{status} always exists. A single read-only bit (for +the driver) is currently defined for \field{status}: + +\begin{lstlisting} +struct virtio_can_config { +#define VIRTIO_CAN_S_CTRL_BUSOFF (1 << 0) + le16 status; +}; +\end{lstlisting} + +The bit VIRTIO_CAN_S_CTRL_BUSOFF in \field{status} is used to indicate +the unsolicited CAN controller state change from started to stopped due +to a detected bus off condition. + +\drivernormative{\subsubsection}{Device Initialization}{Device Types / CAN Device / Device Operation / Initialization} + +The driver MUST populate the \field{Rxq} with empty device-writeable +buffers of at least the size of struct virtio_can_rx, see section +\ref{struct virtio-can-rx}. + +\subsection{Device Operation}\label{sec:Device Types / CAN Device / Device Operation} + +A device operation has an outcome which is described by one of the +following values: + +\begin{lstlisting} +#define VIRTIO_CAN_RESULT_OK 0 +#define VIRTIO_CAN_RESULT_NOT_OK 1 +\end{lstlisting} + +Other values are to be treated like VIRTIO_CAN_RESULT_NOT_OK. + +\subsubsection{Controller Mode}\label{sec:Device Types / CAN Device / Device Operation / Controller Mode} + +The general format of a request in the \field{Controlq} is + +\begin{lstlisting} +struct virtio_can_control_out { +#define VIRTIO_CAN_SET_CTRL_MODE_START 0x0201 +#define VIRTIO_CAN_SET_CTRL_MODE_STOP 0x0202 + le16 msg_type; +}; +\end{lstlisting} + +To participate in bus communication the CAN controller is started by +sending a VIRTIO_CAN_SET_CTRL_MODE_START control message, to stop +participating in bus communication it is stopped by sending a +VIRTIO_CAN_SET_CTRL_MODE_STOP control message. Both requests are +confirmed by the result of the operation. + +\begin{lstlisting} +struct virtio_can_control_in { + u8 result; +}; +\end{lstlisting} + +If the transition succeeded the \field{result} is VIRTIO_CAN_RESULT_OK +otherwise it is VIRTIO_CAN_RESULT_NOT_OK. If a status update is +necessary, the device updates the configuration \field{status} before +marking the request used. As the configuration \field{status} change is +caused by a request from the driver the device is allowed to omit the +configuration change notification here. The device marks the request +used when the CAN controller has finalized the transition to the +requested controller mode. + +On transition to the STOPPED state the device cancels all CAN messages +already pending for transmission and marks them as used with +\field{result} VIRTIO_CAN_RESULT_NOT_OK. In the STOPPED state the +device marks messages received from the +\field{Txq} as used with \field{result} VIRTIO_CAN_RESULT_NOT_OK without +transmitting them to the CAN bus. + +Initially the CAN controller is in the STOPPED state. + +Control queue messages are processed in order. + +\devicenormative{\subsubsection}{CAN Message Transmission}{Device Types / CAN Device / Device Operation / CAN Message Transmission} + +The driver transmits messages by placing outgoing CAN messages in the +\field{Txq} virtqueue. + +\label{struct virtio-can-tx-out} +\begin{lstlisting} +struct virtio_can_tx_out { +#define VIRTIO_CAN_TX 0x0001 + le16 msg_type; + le16 length; /* 0..8 CC, 0..64 CAN-FD, 0..2048 CAN-XL, 12 bits */ + u8 reserved_classic_dlc; /* If CAN classic length = 8 then DLC can be 8..15 */ + u8 padding; + le16 reserved_xl_priority; /* May be needed for CAN XL priority */ +#define VIRTIO_CAN_FLAGS_FD 0x4000 +#define VIRTIO_CAN_FLAGS_EXTENDED 0x8000 +#define VIRTIO_CAN_FLAGS_RTR 0x2000 + le32 flags; + le32 can_id; + u8 sdu[]; +}; + +struct virtio_can_tx_in { + u8 result; +}; +\end{lstlisting} + +The length of the \field{sdu} is determined by the \field{length}. + +The type of a CAN message identifier is determined by \field{flags}. The +3 most significant bits of \field{can_id} do not bear the information +about the type of the CAN message identifier and are 0. + +The device MUST reject any CAN frame type for which support has not been +negotiated with VIRTIO_CAN_RESULT_NOT_OK in \field{result} and MUST NOT +schedule the message for transmission. A CAN frame with an undefined bit +set in \field{flags} is treated like a CAN frame for which support has +not been negotiated. + +The device MUST reject any CAN frame for which \field{can_id} or +\field{sdu} length are out of range or the CAN controller is in an +invalid state with VIRTIO_CAN_RESULT_NOT_OK in \field{result} and MUST +NOT schedule the message for transmission. + +If the parameters are valid the message is scheduled for transmission. + +If feature VIRTIO_CAN_F_CAN_LATE_TX_ACK has been negotiated the +transmission request MUST be marked as used with \field{result} set to +VIRTIO_CAN_OK after the CAN controller acknowledged the successful +transmission on the CAN bus. If this feature bit has not been negotiated +the transmission request MAY already be marked as used with +\field{result} set to VIRTIO_CAN_OK when the transmission request has +been processed by the virtio CAN device and send down the protocol stack +being scheduled for transmission. + +\subsubsection{CAN Message Reception}\label{sec:Device Types / CAN Device / Device Operation / CAN Message Reception} + +Messages can be received by providing empty incoming buffers to the +virtqueue \field{Rxq}. + +\label{struct virtio-can-rx} +\begin{lstlisting} +struct virtio_can_rx { +#define VIRTIO_CAN_RX 0x0101 + le16 msg_type; + le16 length; /* 0..8 CC, 0..64 CAN-FD, 0..2048 CAN-XL, 12 bits */ + u8 reserved_classic_dlc; /* If CAN classic length = 8 then DLC can be 8..15 */ + u8 padding; + le16 reserved_xl_priority; /* May be needed for CAN XL priority */ + le32 flags; + le32 can_id; + u8 sdu[]; +}; +\end{lstlisting} + +If the feature VIRTIO_CAN_F_CAN_FD has been negotiated the maximal +possible \field{sdu} length is 64, if the feature has not been +negotiated the maximal possible \field{sdu} length is 8. + +The actual length of the \field{sdu} is determined by the \field{length}. + +The type of a CAN message identifier is determined by \field{flags} in +the same way as for transmitted CAN messages, see section +\ref{struct virtio-can-tx-out}. The 3 most significant bits of \field{can_id} do not +bear the information about the type of the CAN message identifier and +are 0. The flag bits are exactly the same as for the \field{flags} of +struct virtio_can_tx_out. + +\subsubsection{BusOff Indication}\label{sec:Device Types / CAN Device / Device Operation / BusOff Indication} + +There are certain error conditions so that the physical CAN controller +has to stop participating in CAN communication on the bus. If such an +error condition occurs the device informs the driver about the +unsolicited CAN controller state change by setting the +VIRTIO_CAN_S_CTRL_BUSOFF bit in the configuration \field{status} field. + +After bus-off detection the CAN controller is in STOPPED state. The CAN +controller does not participate in bus communication any more so all CAN +messages pending for transmission are put into the used queue with +\field{result} VIRTIO_CAN_RESULT_NOT_OK. diff --git a/device-types/can/device-conformance.tex b/device-types/can/device-conformance.tex new file mode 100644 index 0000000..3725164 --- /dev/null +++ b/device-types/can/device-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{CAN Device Conformance}\label{sec:Conformance / Device Conformance / CAN Device Conformance} + +A CAN device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / CAN Device / Device Operation / CAN Message Transmission} +\end{itemize} diff --git a/device-types/can/driver-conformance.tex b/device-types/can/driver-conformance.tex new file mode 100644 index 0000000..32e3e87 --- /dev/null +++ b/device-types/can/driver-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{CAN Driver Conformance}\label{sec:Conformance / Driver Conformance / CAN Driver Conformance} + +A CAN driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / CAN Device / Device Operation / Initialization} +\end{itemize} diff --git a/device-types/crypto/description.tex b/device-types/crypto/description.tex index 5705e26..e053cc7 100644 --- a/device-types/crypto/description.tex +++ b/device-types/crypto/description.tex @@ -424,11 +424,11 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Crypto Device / Devic \field{header} is a general header (see above). -\field{op_flf} is the opcode (in \field{header}) specific fixed-length paramenters. +\field{op_flf} is the opcode (in \field{header}) specific fixed-length parameters. \field{flf_len} depends on the VIRTIO_CRYPTO_F_REVISION_1 feature bit (see below). -\field{op_vlf} is the opcode (in \field{header}) specific variable-length paramenters. +\field{op_vlf} is the opcode (in \field{header}) specific variable-length parameters. \field{vlf_len} is the size of the specific structure used. \begin{note} @@ -509,7 +509,7 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Crypto Device / Devic \subparagraph{Session operation: HASH session}\label{sec:Device Types / Crypto Device / Device Operation / Control Virtqueue / Session operation / Session operation: HASH session} -The fixed-length paramenters of HASH session requests is as follows: +The fixed-length parameters of HASH session requests is as follows: \begin{lstlisting} struct virtio_crypto_hash_create_session_flf { @@ -1386,7 +1386,7 @@ \subsubsection{Symmetric algorithms Operation}\label{sec:Device Types / Crypto D \end{itemize*} The length of \field{op_type_flf} is fixed to 40 bytes, the data of unused -part (if has) will be ingored. +part (if has) will be ignored. \field{op_type_vlf} is the \field{op_type} specific parameters, it MUST starts with or be one of the following structures: @@ -1536,7 +1536,7 @@ \subsubsection{Symmetric algorithms Operation}\label{sec:Device Types / Crypto D \end{itemize*} The length of \field{op_type_flf} is fixed to 72 bytes, the data of unused -part (if has) will be ingored. +part (if has) will be ignored. \field{op_type_vlf} is the \field{op_type} specific parameters, it MUST starts with or be one of the following structures: diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex index 4435248..c5706bc 100644 --- a/device-types/gpu/description.tex +++ b/device-types/gpu/description.tex @@ -128,7 +128,7 @@ \subsubsection{Device Operation: Create a framebuffer and configure scanout} \item Allocate a framebuffer from guest ram, and attach it as backing storage to the resource just created, using VIRTIO_GPU_CMD_RESOURCE_ATTACH_BACKING. Scatter lists are - supported, so the framebuffer doesn't need to be contignous in guest + supported, so the framebuffer doesn't need to be contiguous in guest physical memory. \item Use VIRTIO_GPU_CMD_SET_SCANOUT to link the framebuffer to a display scanout. @@ -166,7 +166,7 @@ \subsubsection{Device Operation: Multihead setup} \devicenormative{\subsubsection}{Device Operation: Command lifecycle and fencing}{Device Types / GPU Device / Device Operation / Device Operation: Command lifecycle and fencing} -The device MAY process controlq commands asyncronously and return them +The device MAY process controlq commands asynchronously and return them to the driver before the processing is complete. If the driver needs to know when the processing is finished it can set the VIRTIO_GPU_FLAG_FENCE flag in the request. The device MUST finish the @@ -190,7 +190,7 @@ \subsubsection{Device Operation: Configure mouse cursor} \subsubsection{Device Operation: Request header}\label{sec:Device Types / GPU Device / Device Operation / Device Operation: Request header} -All requests and responses on the virt queues have a fixed header +All requests and responses on the virtqueues have a fixed header using the following layout structure and definitions: \begin{lstlisting} @@ -345,7 +345,7 @@ \subsubsection{Device Operation: controlq}\label{sec:Device Types / GPU Device / display). The \field{enabled} field is set when the user enabled the display. -It is roughly the same as the connected state of a phyiscal display +It is roughly the same as the connected state of a physical display connector. \item[VIRTIO_GPU_CMD_GET_EDID] Retrieve the EDID data for a given diff --git a/device-types/net/description.tex b/device-types/net/description.tex index 76585b0..b2a0d39 100644 --- a/device-types/net/description.tex +++ b/device-types/net/description.tex @@ -88,6 +88,9 @@ \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits \item[VIRTIO_NET_F_CTRL_MAC_ADDR(23)] Set MAC address through control channel. +\item[VIRTIO_NET_F_DEVICE_STATS(50)] Device can provide device-level statistics + to the driver through the control virtqueue. + \item[VIRTIO_NET_F_HASH_TUNNEL(51)] Device supports inner header hash for encapsulated packets. \item[VIRTIO_NET_F_VQ_NOTF_COAL(52)] Device supports virtqueue notification coalescing. @@ -119,6 +122,8 @@ \subsection{Feature bits}\label{sec:Device Types / Network Device / Feature bits device with the same MAC address. \item[VIRTIO_NET_F_SPEED_DUPLEX(63)] Device reports speed and duplex. + +\item[VIRTIO_NET_F_RSS_CONTEXT(64)] Device supports multiple RSS contexts. \end{description} \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device / Feature bits / Feature bit requirements} @@ -150,6 +155,7 @@ \subsubsection{Feature bit requirements}\label{sec:Device Types / Network Device \item[VIRTIO_NET_F_RSS] Requires VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_VQ_NOTF_COAL] Requires VIRTIO_NET_F_CTRL_VQ. \item[VIRTIO_NET_F_HASH_TUNNEL] Requires VIRTIO_NET_F_CTRL_VQ along with VIRTIO_NET_F_RSS or VIRTIO_NET_F_HASH_REPORT. +\item[VIRTIO_NET_F_RSS_CONTEXT] Requires VIRTIO_NET_F_CTRL_VQ and VIRTIO_NET_F_RSS. \end{description} \subsubsection{Legacy Interface: Feature bits}\label{sec:Device Types / Network Device / Feature bits / Legacy Interface: Feature bits} @@ -395,6 +401,38 @@ \subsection{Device Initialization}\label{sec:Device Types / Network Device / Dev A truly minimal driver would only accept VIRTIO_NET_F_MAC and ignore everything else. +\subsection{Device and driver capabilities}\label{sec:Device Types / Network Device / Device and driver capabilities} + +The network device has the following capabilities. + +\begin{tabularx}{\textwidth}{ |l||l|X| } +\hline +Identifier & Name & Description \\ +\hline \hline +0x0800 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-RESOURCE-CAP]{VIRTIO_NET_FF_RESOURCE_CAP} & Flow filter resource capability \\ +\hline +0x0801 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP]{VIRTIO_NET_FF_SELECTOR_CAP} & Flow filter classifier capability \\ +\hline +0x0802 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP]{VIRTIO_NET_FF_ACTION_CAP} & Flow filter action capability \\ +\hline +\end{tabularx} + +\subsection{Device resource objects}\label{sec:Device Types / Network Device / Device resource objects} + +The network device has the following resource objects. + +\begin{tabularx}{\textwidth}{ |l||l|X| } +\hline +type & Name & Description \\ +\hline \hline +0x0200 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-GROUP]{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP} & Flow filter group resource object \\ +\hline +0x0201 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-CLASSIFIER]{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER} & Flow filter mask object \\ +\hline +0x0202 & \hyperref[par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-RULE]{VIRTIO_NET_RESOURCE_OBJ_FF_RULE} & Flow filter rule object \\ +\hline +\end{tabularx} + \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation} Packets are transmitted by placing them in the @@ -431,11 +469,11 @@ \subsection{Device Operation}\label{sec:Device Types / Network Device / Device O \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Network Device / Device Operation / Legacy Interface: Device Operation} When using the legacy interface, transitional devices and drivers -MUST format the fields in struct virtio_net_hdr +MUST format the fields in \field{struct virtio_net_hdr} according to the native endian of the guest rather than (necessarily when not using the legacy interface) little-endian. -The legacy driver only presented \field{num_buffers} in the struct virtio_net_hdr +The legacy driver only presented \field{num_buffers} in the \field{struct virtio_net_hdr} when VIRTIO_NET_F_MRG_RXBUF was negotiated; without that feature the structure was 2 bytes shorter. @@ -525,6 +563,9 @@ \subsubsection{Packet Transmission}\label{sec:Device Types / Network Device / De \drivernormative{\paragraph}{Packet Transmission}{Device Types / Network Device / Device Operation / Packet Transmission} +For the transmit packet buffer, the driver MUST use the size of the +structure \field{struct virtio_net_hdr} same as the receive packet buffer. + The driver MUST set \field{num_buffers} to zero. If VIRTIO_NET_F_CSUM is not negotiated, the driver MUST set @@ -654,10 +695,15 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi If the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 features are used, the maximum incoming packet -will be to 65550 bytes long (the maximum size of a -TCP or UDP packet, plus the 14 byte ethernet header), otherwise -1514 bytes. The 12-byte struct virtio_net_hdr is prepended to this, -making for 65562 or 1526 bytes. +will be 65589 bytes long (14 bytes of Ethernet header, plus 40 bytes of +the IPv6 header, plus 65535 bytes of maximum IPv6 payload including any +extension header), otherwise 1514 bytes. +When VIRTIO_NET_F_HASH_REPORT is not negotiated, the required receive buffer +size is either 65601 or 1526 bytes accounting for 20 bytes of +\field{struct virtio_net_hdr} followed by receive packet. +When VIRTIO_NET_F_HASH_REPORT is negotiated, the required receive buffer +size is either 65609 or 1534 bytes accounting for 12 bytes of +\field{struct virtio_net_hdr} followed by receive packet. \drivernormative{\paragraph}{Setting Up Receive Buffers}{Device Types / Network Device / Device Operation / Setting Up Receive Buffers} @@ -666,18 +712,25 @@ \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Devi \begin{itemize} \item If VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6, VIRTIO_NET_F_GUEST_UFO, VIRTIO_NET_F_GUEST_USO4 or VIRTIO_NET_F_GUEST_USO6 are negotiated, the driver SHOULD populate - the receive queue(s) with buffers of at least 65562 bytes. + the receive queue(s) with buffers of at least 65609 bytes if + VIRTIO_NET_F_HASH_REPORT is negotiated, and of at least 65601 bytes if not. \item Otherwise, the driver SHOULD populate the receive queue(s) - with buffers of at least 1526 bytes. + with buffers of at least 1534 bytes if VIRTIO_NET_F_HASH_REPORT + is negotiated, and of at least 1526 bytes if not. \end{itemize} \item If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer MUST be at -least the size of the struct virtio_net_hdr. +least size of \field{struct virtio_net_hdr}, +i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. \end{itemize} \begin{note} Obviously each buffer can be split across multiple descriptor elements. \end{note} +When calculating the size of \field{struct virtio_net_hdr}, the driver +MUST consider all the fields inclusive up to \field{padding_reserved}, +i.e. 20 bytes if VIRTIO_NET_F_HASH_REPORT is negotiated, and 12 bytes if not. + If VIRTIO_NET_F_MQ is negotiated, each of receiveq1\ldots receiveqN that will be used SHOULD be populated with receive buffers. @@ -714,7 +767,7 @@ \subsubsection{Processing of Incoming Packets}\label{sec:Device Types / Network chains them together to form a single packet in a way similar to how it would store it in a single buffer spread over multiple descriptors. - The other buffers will not begin with a struct virtio_net_hdr. + The other buffers will not begin with a \field{struct virtio_net_hdr}. \item If \field{num_buffers} is one, then the entire packet will be @@ -1156,6 +1209,7 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi u8 command; u8 command-specific-data[]; u8 ack; + u8 command-specific-result[]; }; /* ack values */ @@ -1164,9 +1218,12 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \end{lstlisting} The \field{class}, \field{command} and command-specific-data are set by the -driver, and the device sets the \field{ack} byte. There is little it can -do except issue a diagnostic if \field{ack} is not -VIRTIO_NET_OK. +driver, and the device sets the \field{ack} byte and optionally +\field{command-specific-result}. There is little the driver can +do except issue a diagnostic if \field{ack} is not VIRTIO_NET_OK. + +The command VIRTIO_NET_CTRL_STATS_QUERY and VIRTIO_NET_CTRL_STATS_GET contain +\field{command-specific-result}. \paragraph{Packet Receive Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} \label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Setting Promiscuous Mode}%old label for latexdiff @@ -1606,6 +1663,88 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi \item If the destination receive queue is being reset (See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Reset}), the device MUST drop the packet. \end{itemize} +\paragraph{RSS Context}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} + +An RSS context consists of configurable parameters specified by \ref{sec:Device Types / Network Device +/ Device Operation / Control Virtqueue / Receive-side scaling (RSS)}. + +The RSS configuration supported by VIRTIO_NET_F_RSS is considered the default RSS configuration. + +The device offers the feature VIRTIO_NET_F_RSS_CONTEXT if it supports one or multiple RSS contexts +(excluding the default RSS configuration) and configurable parameters. + +\subparagraph{Querying RSS Context Capability}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context / Querying RSS Context Capability} + +\begin{lstlisting} +#define VIRTNET_RSS_CTX_CTRL 9 + #define VIRTNET_RSS_CTX_CTRL_CAP_GET 0 + #define VIRTNET_RSS_CTX_CTRL_ADD 1 + #define VIRTNET_RSS_CTX_CTRL_MOD 2 + #define VIRTNET_RSS_CTX_CTRL_DEL 3 + +struct virtnet_rss_ctx_cap { + le16 max_rss_contexts; +} +\end{lstlisting} + +Field \field{max_rss_contexts} specifies the maximum number of RSS contexts \ref{sec:Device Types / Network Device / +Device Operation / Control Virtqueue / RSS Context} supported by the device. + +The driver queries the RSS context capability of the device by sending the command VIRTNET_RSS_CTX_CTRL_CAP_GET +with the structure virtnet_rss_ctx_cap. + +For the command VIRTNET_RSS_CTX_CTRL_CAP_GET, the structure virtnet_rss_ctx_cap is write-only for the device. + +\subparagraph{Setting RSS Context Parameters}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context / Setting RSS Context Parameters} + +\begin{lstlisting} +struct virtnet_rss_ctx_add_modify { + le16 rss_ctx_id; + u8 reserved[6]; + struct virtio_net_rss_config rss; +}; + +struct virtnet_rss_ctx_del { + le16 rss_ctx_id; +}; +\end{lstlisting} + +RSS context parameters: +\begin{itemize} +\item \field{rss_ctx_id}: ID of the specific RSS context. +\item \field{rss}: RSS context parameters of the specific RSS context whose id is \field{rss_ctx_id}. +\end{itemize} + +\field{reserved} is reserved and it is ignored by the device. + +If the feature VIRTIO_NET_F_RSS_CONTEXT has been negotiated, the driver can send the following +VIRTNET_RSS_CTX_CTRL class commands: +\begin{enumerate} +\item VIRTNET_RSS_CTX_CTRL_ADD: use the structure virtnet_rss_ctx_add_modify to + add an RSS context configured as \field{rss} and id as \field{rss_ctx_id} for the device. +\item VIRTNET_RSS_CTX_CTRL_MOD: use the structure virtnet_rss_ctx_add_modify to + configure parameters of the RSS context whose id is \field{rss_ctx_id} as \field{rss} for the device. +\item VIRTNET_RSS_CTX_CTRL_DEL: use the structure virtnet_rss_ctx_del to delete + the RSS context whose id is \field{rss_ctx_id} for the device. +\end{enumerate} + +For commands VIRTNET_RSS_CTX_CTRL_ADD and VIRTNET_RSS_CTX_CTRL_MOD, the structure virtnet_rss_ctx_add_modify is read-only for the device. +For the command VIRTNET_RSS_CTX_CTRL_DEL, the structure virtnet_rss_ctx_del is read-only for the device. + +\devicenormative{\subparagraph}{RSS Context}{Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} + +The device MUST set \field{max_rss_contexts} to at least 1 if it offers VIRTIO_NET_F_RSS_CONTEXT. + +Upon reset, the device MUST clear all previously configured RSS contexts. + +\drivernormative{\subparagraph}{RSS Context}{Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} + +The driver MUST have negotiated the VIRTIO_NET_F_RSS_CONTEXT feature when issuing the VIRTNET_RSS_CTX_CTRL class commands. + +The driver MUST set \field{rss_ctx_id} to between 1 and \field{max_rss_contexts} inclusive. + +The driver MUST NOT send the command VIRTIO_NET_CTRL_MQ_VQ_PAIRS_SET when the device has successfully configured at least one RSS context. + \paragraph{Offloads State Configuration}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Offloads State Configuration} If the VIRTIO_NET_F_CTRL_GUEST_OFFLOADS feature is negotiated, the driver can @@ -1805,12 +1944,1088 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi Upon reset, a device MUST initialize all coalescing parameters to 0. +\paragraph{Device Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} + +If the VIRTIO_NET_F_DEVICE_STATS feature is negotiated, the driver can obtain +device statistics from the device by using the following command. + +Different types of virtqueues have different statistics. The statistics of the +receiveq are different from those of the transmitq. + +The statistics of a certain type of virtqueue are also divided into multiple types +because different types require different features. This enables the expansion +of new statistics. + +In one command, the driver can obtain the statistics of one or multiple virtqueues. +Additionally, the driver can obtain multiple type statistics of each virtqueue. + +\subparagraph{Query Statistic Capabilities}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Query Statistic Capabilities} + +\begin{lstlisting} +#define VIRTIO_NET_CTRL_STATS 8 +#define VIRTIO_NET_CTRL_STATS_QUERY 0 +#define VIRTIO_NET_CTRL_STATS_GET 1 + +struct virtio_net_stats_capabilities { + +#define VIRTIO_NET_STATS_TYPE_CVQ (1 << 32) + +#define VIRTIO_NET_STATS_TYPE_RX_BASIC (1 << 0) +#define VIRTIO_NET_STATS_TYPE_RX_CSUM (1 << 1) +#define VIRTIO_NET_STATS_TYPE_RX_GSO (1 << 2) +#define VIRTIO_NET_STATS_TYPE_RX_SPEED (1 << 3) + +#define VIRTIO_NET_STATS_TYPE_TX_BASIC (1 << 16) +#define VIRTIO_NET_STATS_TYPE_TX_CSUM (1 << 17) +#define VIRTIO_NET_STATS_TYPE_TX_GSO (1 << 18) +#define VIRTIO_NET_STATS_TYPE_TX_SPEED (1 << 19) + + le64 supported_stats_types[1]; +} +\end{lstlisting} + +To obtain device statistic capability, use the VIRTIO_NET_CTRL_STATS_QUERY +command. When the command completes successfully, \field{command-specific-result} +is in the format of \field{struct virtio_net_stats_capabilities}. + +\subparagraph{Get Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Get Statistics} + +\begin{lstlisting} +struct virtio_net_ctrl_queue_stats { + struct { + le16 vq_index; + le16 reserved[3]; + le64 types_bitmap[1]; + } stats[]; +}; + +struct virtio_net_stats_reply_hdr { +#define VIRTIO_NET_STATS_TYPE_REPLY_CVQ 32 + +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_BASIC 0 +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_CSUM 1 +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_GSO 2 +#define VIRTIO_NET_STATS_TYPE_REPLY_RX_SPEED 3 + +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_BASIC 16 +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_CSUM 17 +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_GSO 18 +#define VIRTIO_NET_STATS_TYPE_REPLY_TX_SPEED 19 + u8 type; + u8 reserved; + le16 vq_index; + le16 reserved1; + le16 size; +} +\end{lstlisting} + +To obtain device statistics, use the VIRTIO_NET_CTRL_STATS_GET command with the +\field{command-specific-data} which is in the format of +\field{struct virtio_net_ctrl_queue_stats}. When the command completes +successfully, \field{command-specific-result} contains multiple statistic +results, each statistic result has the \field{struct virtio_net_stats_reply_hdr} +as the header. + +The fields of the \field{struct virtio_net_ctrl_queue_stats}: +\begin{description} + \item [vq_index] + The index of the virtqueue to obtain the statistics. + + \item [types_bitmap] + This is a bitmask of the types of statistics to be obtained. Therefore, a + \field{stats} inside \field{struct virtio_net_ctrl_queue_stats} may + indicate multiple statistic replies for the virtqueue. +\end{description} + +The fields of the \field{struct virtio_net_stats_reply_hdr}: +\begin{description} + \item [type] + The type of the reply statistic. + + \item [vq_index] + The virtqueue index of the reply statistic. + + \item [size] + The number of bytes for the statistics entry including size of \field{struct virtio_net_stats_reply_hdr}. + +\end{description} + +\subparagraph{Controlq Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Controlq Statistics} + +The structure corresponding to the controlq statistics is +\field{struct virtio_net_stats_cvq}. The corresponding type is +VIRTIO_NET_STATS_TYPE_CVQ. This is for the controlq. + +\begin{lstlisting} +struct virtio_net_stats_cvq { + struct virtio_net_stats_reply_hdr hdr; + + le64 command_num; + le64 ok_num; +}; +\end{lstlisting} + +\begin{description} + \item [command_num] + The number of commands received by the device including the current command. + + \item [ok_num] + The number of commands completed successfully by the device including the current command. +\end{description} + + +\subparagraph{Receiveq Basic Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq Basic Statistics} + +The structure corresponding to the receiveq basic statistics is +\field{struct virtio_net_stats_rx_basic}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_BASIC. This is for the receiveq. + +Receiveq basic statistics do not require any feature. As long as the device supports +VIRTIO_NET_F_DEVICE_STATS, the following are the receiveq basic statistics. + +\begin{lstlisting} +struct virtio_net_stats_rx_basic { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_notifications; + + le64 rx_packets; + le64 rx_bytes; + + le64 rx_interrupts; + + le64 rx_drops; + le64 rx_drop_overruns; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_notifications] + The number of driver notifications received by the device for this + receiveq. + + \item [rx_packets] + This is the number of packets passed to the driver by the device. + + \item [rx_bytes] + This is the bytes of packets passed to the driver by the device. + + \item [rx_interrupts] + The number of interrupts generated by the device for this receiveq. + + \item [rx_drops] + This is the number of packets dropped by the device. The count includes + all types of packets dropped by the device. + + \item [rx_drop_overruns] + This is the number of packets dropped by the device when no more + descriptors were available. + +\end{description} + +\subparagraph{Transmitq Basic Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq Basic Statistics} + +The structure corresponding to the transmitq basic statistics is +\field{struct virtio_net_stats_tx_basic}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_BASIC. This is for the transmitq. + +Transmitq basic statistics do not require any feature. As long as the device supports +VIRTIO_NET_F_DEVICE_STATS, the following are the transmitq basic statistics. + +\begin{lstlisting} +struct virtio_net_stats_tx_basic { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_notifications; + + le64 tx_packets; + le64 tx_bytes; + + le64 tx_interrupts; + + le64 tx_drops; + le64 tx_drop_malformed; +}; +\end{lstlisting} + +The packets described below are all for a specific virtqueue. +\begin{description} + \item [tx_notifications] + The number of driver notifications received by the device for this + transmitq. + + \item [tx_packets] + This is the number of packets sent by the device (not the packets + got from the driver). + + \item [tx_bytes] + This is the number of bytes sent by the device for all the sent packets + (not the bytes sent got from the driver). + + \item [tx_interrupts] + The number of interrupts generated by the device for this transmitq. + + \item [tx_drops] + The number of packets dropped by the device. The count includes all + types of packets dropped by the device. + + \item [tx_drop_malformed] + The number of packets dropped by the device, when the descriptors are + malformed. For example, the buffer is too short. +\end{description} + +\subparagraph{Receiveq CSUM Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq CSUM Statistics} + +The structure corresponding to the receiveq checksum statistics is +\field{struct virtio_net_stats_rx_csum}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_CSUM. This is for the receiveq. + +Only after the VIRTIO_NET_F_GUEST_CSUM is negotiated, the receiveq checksum +statistics can be obtained. + +\begin{lstlisting} +struct virtio_net_stats_rx_csum { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_csum_valid; + le64 rx_needs_csum; + le64 rx_csum_none; + le64 rx_csum_bad; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_csum_valid] + The number of packets with VIRTIO_NET_HDR_F_DATA_VALID. + + \item [rx_needs_csum] + The number of packets with VIRTIO_NET_HDR_F_NEEDS_CSUM. + + \item [rx_csum_none] + The number of packets without hardware checksum. The packet here refers + to the non-TCP/UDP packet that the device cannot recognize. + + \item [rx_csum_bad] + The number of packets with checksum mismatch. + +\end{description} + +\subparagraph{Transmitq CSUM Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq CSUM Statistics} + +The structure corresponding to the transmitq checksum statistics is +\field{struct virtio_net_stats_tx_csum}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_CSUM. This is for the transmitq. + +Only after the VIRTIO_NET_F_CSUM is negotiated, the transmitq checksum +statistics can be obtained. + +The following are the transmitq checksum statistics: + +\begin{lstlisting} +struct virtio_net_stats_tx_csum { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_csum_none; + le64 tx_needs_csum; +}; +\end{lstlisting} + +The packets described below are all for a specific virtqueue. +\begin{description} + \item [tx_csum_none] + The number of packets which do not require hardware checksum. + + \item [tx_needs_csum] + The number of packets which require checksum calculation by the device. + +\end{description} + +\subparagraph{Receiveq GSO Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq GSO Statistics} + +The structure corresponding to the receivq GSO statistics is +\field{struct virtio_net_stats_rx_gso}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_GSO. This is for the receiveq. + +If one or more of the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6 +have been negotiated, the receiveq GSO statistics can be obtained. + +GSO packets refer to packets passed by the device to the driver where +\field{gso_type} is not VIRTIO_NET_HDR_GSO_NONE. + +\begin{lstlisting} +struct virtio_net_stats_rx_gso { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_gso_packets; + le64 rx_gso_bytes; + le64 rx_gso_packets_coalesced; + le64 rx_gso_bytes_coalesced; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_gso_packets] + The number of the GSO packets received by the device. + + \item [rx_gso_bytes] + The bytes of the GSO packets received by the device. + This includes the header size of the GSO packet. + + \item [rx_gso_packets_coalesced] + The number of the GSO packets coalesced by the device. + + \item [rx_gso_bytes_coalesced] + The bytes of the GSO packets coalesced by the device. + This includes the header size of the GSO packet. +\end{description} + +\subparagraph{Transmitq GSO Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq GSO Statistics} + +The structure corresponding to the transmitq GSO statistics is +\field{struct virtio_net_stats_tx_gso}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_GSO. This is for the transmitq. + +If one or more of the VIRTIO_NET_F_HOST_TSO4, VIRTIO_NET_F_HOST_TSO6, +VIRTIO_NET_F_HOST_USO options have been negotiated, the transmitq GSO statistics +can be obtained. + +GSO packets refer to packets passed by the driver to the device where +\field{gso_type} is not VIRTIO_NET_HDR_GSO_NONE. +See more \ref{sec:Device Types / Network Device / Device Operation / Packet +Transmission}. + +\begin{lstlisting} +struct virtio_net_stats_tx_gso { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_gso_packets; + le64 tx_gso_bytes; + le64 tx_gso_segments; + le64 tx_gso_segments_bytes; + le64 tx_gso_packets_noseg; + le64 tx_gso_bytes_noseg; +}; +\end{lstlisting} + +The packets described below are all for a specific virtqueue. +\begin{description} + \item [tx_gso_packets] + The number of the GSO packets sent by the device. + + \item [tx_gso_bytes] + The bytes of the GSO packets sent by the device. + + \item [tx_gso_segments] + The number of segments prepared from GSO packets. + + \item [tx_gso_segments_bytes] + The bytes of segments prepared from GSO packets. + + \item [tx_gso_packets_noseg] + The number of the GSO packets without segmentation. + + \item [tx_gso_bytes_noseg] + The bytes of the GSO packets without segmentation. + +\end{description} + +\subparagraph{Receiveq Speed Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Receiveq Speed Statistics} + +The structure corresponding to the receiveq speed statistics is +\field{struct virtio_net_stats_rx_speed}. The corresponding type is +VIRTIO_NET_STATS_TYPE_RX_SPEED. This is for the receiveq. + +The device has the allowance for the speed. If VIRTIO_NET_F_SPEED_DUPLEX has +been negotiated, the driver can get this by \field{speed}. When the received +packets bitrate exceeds the \field{speed}, some packets may be dropped by the +device. + +\begin{lstlisting} +struct virtio_net_stats_rx_speed { + struct virtio_net_stats_reply_hdr hdr; + + le64 rx_packets_allowance_exceeded; + le64 rx_bytes_allowance_exceeded; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [rx_packets_allowance_exceeded] + The number of the packets dropped by the device due to the received + packets bitrate exceeding the \field{speed}. + + \item [rx_bytes_allowance_exceeded] + The bytes of the packets dropped by the device due to the received + packets bitrate exceeding the \field{speed}. + +\end{description} + +\subparagraph{Transmitq Speed Statistics}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics / Transmitq Speed Statistics} + +The structure corresponding to the transmitq speed statistics is +\field{struct virtio_net_stats_tx_speed}. The corresponding type is +VIRTIO_NET_STATS_TYPE_TX_SPEED. This is for the transmitq. + +The device has the allowance for the speed. If VIRTIO_NET_F_SPEED_DUPLEX has +been negotiated, the driver can get this by \field{speed}. When the transmit +packets bitrate exceeds the \field{speed}, some packets may be dropped by the +device. + +\begin{lstlisting} +struct virtio_net_stats_tx_speed { + struct virtio_net_stats_reply_hdr hdr; + + le64 tx_packets_allowance_exceeded; + le64 tx_bytes_allowance_exceeded; +}; +\end{lstlisting} + +The packets described below were all presented on the specified virtqueue. +\begin{description} + \item [tx_packets_allowance_exceeded] + The number of the packets dropped by the device due to the transmit packets + bitrate exceeding the \field{speed}. + + \item [tx_bytes_allowance_exceeded] + The bytes of the packets dropped by the device due to the transmit packets + bitrate exceeding the \field{speed}. + +\end{description} + +\devicenormative{\subparagraph}{Device Statistics}{Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} + +When the VIRTIO_NET_F_DEVICE_STATS feature is negotiated, the device MUST reply +to the command VIRTIO_NET_CTRL_STATS_QUERY with the +\field{struct virtio_net_stats_capabilities}. \field{supported_stats_types} +includes all the statistic types supported by the device. + +If \field{struct virtio_net_ctrl_queue_stats} is incorrect (such as the +following), the device MUST set \field{ack} to VIRTIO_NET_ERR. Even if there is +only one error, the device MUST fail the entire command. +\begin{itemize} + \item \field{vq_index} exceeds the queue range. + \item \field{types_bitmap} contains unknown types. + \item One or more of the bits present in \field{types_bitmap} is not valid + for the specified virtqueue. + \item The feature corresponding to the specified \field{types_bitmap} was + not negotiated. +\end{itemize} + +The device MUST set the actual size of the bytes occupied by the reply to the +\field{size} of the \field{hdr}. And the device MUST set the \field{type} and +the \field{vq_index} of the statistic header. + +The \field{command-specific-result} buffer allocated by the driver may be +smaller or bigger than all the statistics specified by +\field{struct virtio_net_ctrl_queue_stats}. The device MUST fill up only upto +the valid bytes. + +The statistics counter replied by the device MUST wrap around to zero by the +device on the overflow. + +\drivernormative{\subparagraph}{Device Statistics}{Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} + +The types contained in the \field{types_bitmap} MUST be queried from the device +via command VIRTIO_NET_CTRL_STATS_QUERY. + +\field{types_bitmap} in \field{struct virtio_net_ctrl_queue_stats} MUST be valid to the +vq specified by \field{vq_index}. + +The \field{command-specific-result} buffer allocated by the driver MUST have +enough capacity to store all the statistics reply headers defined in +\field{struct virtio_net_ctrl_queue_stats}. If the +\field{command-specific-result} buffer is fully utilized by the device but some +replies are missed, it is possible that some statistics may exceed the capacity +of the driver's records. In such cases, the driver should allocate additional +space for the \field{command-specific-result} buffer. + +\subsubsection{Flow filter}\label{sec:Device Types / Network Device / Device Operation / Flow filter} + +A network device can support one or more flow filter rules. Each flow filter rule +is applied by matching a packet and then taking an action, such as directing the packet +to a specific receiveq or dropping the packet. An example of a match is +matching on specific source and destination IP addresses. + +A flow filter rule is a device resource object that consists of a key, +a processing priority, and an action to either direct a packet to a +receive queue or drop the packet. + +Each rule uses a classifier. The key is matched against the packet using +a classifier, defining which fields in the packet are matched. +A classifier resource object consists of one or more field selectors, each with +a type that specifies the header fields to be matched against, and a mask. +The mask can match whole fields or parts of a field in a header. Each +rule resource object depends on the classifier resource object. + +When a packet is received, relevant fields are extracted +(in the same way) from both the packet and the key according to the +classifier. The resulting field contents are then compared - +if they are identical the rule action is taken, if they are not, the rule is ignored. + +Multiple flow filter rules are part of a group. The rule resource object +depends on the group. Each rule within a +group has a rule priority, and each group also has a group priority. For a +packet, a group with the highest priority is selected first. Within a group, +rules are applied from highest to lowest priority, until one of the rules +matches the packet and an action is taken. If all the rules within a group +are ignored, the group with the next highest priority is selected, and so on. + +The device and the driver indicates flow filter resource limits using the capability +\ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-RESOURCE-CAP} specifying the limits on the number of flow filter rule, +group and classifier resource objects. The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP} specifies which selectors the device supports. +The driver indicates the selectors it is using by setting the flow +filter selector capability, prior to adding any resource objects. + +The capability \ref{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP} specifies which actions the device supports. + +The driver controls the flow filter rule, classifier and group resource objects using +administration commands described in +\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device resource objects}. + +\paragraph{Packet processing order}\label{sec:sec:Device Types / Network Device / Device Operation / Flow filter / Packet processing order} + +Note that flow filter rules are applied after MAC/VLAN filtering. Flow filter +rules take precedence over steering: if a flow filter rule results in an action, +the steering configuration does not apply. The steering configuration only applies +to packets for which no flow filter rule action was performed. For example, +incoming packets can be processed in the following order: + +\begin{itemize} +\item apply steering configuration received using control virtqueue commands + VIRTIO_NET_CTRL_RX, VIRTIO_NET_CTRL_MAC and VIRTIO_NET_CTRL_VLAN. +\item apply flow filter rules if any. +\item if no filter rule applied, apply steering configuration received using command + VIRTIO_NET_CTRL_MQ_RSS_CONFIG or as per automatic receive steering. +\end{itemize} + +Some incoming packet processing examples: +\begin{itemize} +\item If the packet is dropped by the flow filter rule, RSS + steering is ignored for the packet. +\item If the packet is directed to a specific receiveq using flow filter rule, + the RSS steering is ignored for the packet. +\item If a packet is dropped due to the VIRTIO_NET_CTRL_MAC configuration, + both flow filter rules and the RSS steering are ignored for the packet. +\item If a packet does not match any flow filter rules, + the RSS steering is used to select the receiveq for the packet (if enabled). +\item If there are two flow filter groups configured as group_A and group_B + with respective group priorities as 4, and 5; flow filter rules of + group_B are applied first having highest group priority, if there is a match, + the flow filter rules of group_A are ignored; if there is no match for + the flow filter rules in group_B, the flow filter rules of next level group_A are applied. +\end{itemize} + +\paragraph{Device and driver capabilities} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities} + +\subparagraph{VIRTIO_NET_FF_RESOURCE_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-RESOURCE-CAP} + +The capability VIRTIO_NET_FF_RESOURCE_CAP indicates the flow filter resource limits. +\field{cap_specific_data} is in the format +\field{struct virtio_net_ff_cap_data}. + +\begin{lstlisting} +struct virtio_net_ff_cap_data { + le32 groups_limit; + le32 selectors_limit; + le32 rules_limit; + le32 rules_per_group_limit; + u8 last_rule_priority; + u8 selectors_per_classifier_limit; +}; +\end{lstlisting} + +\field{groups_limit}, and \field{selectors_limit} represent the maximum +number of flow filter groups and selectors, respectively, that the driver can create. + \field{rules_limit} is the maximum number of +flow fiilter rules that the driver can create across all the groups. +\field{rules_per_group_limit} is the maximum number of flow filter rules that the driver +can create for each flow filter group. + +\field{last_rule_priority} is the highest priority that can be assigned to a +flow filter rule. + +\field{selectors_per_classifier_limit} is the maximum number of selectors +that a classifier can have. + +\subparagraph{VIRTIO_NET_FF_SELECTOR_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP} + +The capability VIRTIO_NET_FF_SELECTOR_CAP lists the supported selectors and the +supported packet header fields for each selector. +\field{cap_specific_data} is in the format \field{struct virtio_net_ff_cap_mask_data}. + +\begin{lstlisting}[label={lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / virtio-net-ff-selector}] +struct virtio_net_ff_selector { + u8 type; + u8 flags; + u8 reserved[2]; + u8 length; + u8 reserved1[3]; + u8 mask[]; +}; + +struct virtio_net_ff_cap_mask_data { + u8 count; + u8 reserved[7]; + struct virtio_net_ff_selector selectors[]; +}; + +#define VIRTIO_NET_FF_MASK_F_PARTIAL_MASK (1 << 0) +\end{lstlisting} + +\field{count} indicates number of valid entries in the \field{selectors} array. +\field{selectors[]} is an array of supported selectors. Within each array entry: +\field{type} specifies the type of the packet header, as defined in table +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / flow filter selector types}. \field{mask} specifies which fields of the +packet header can be matched in a flow filter rule. + +Each \field{type} is also listed in table +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / flow filter selector types}. \field{mask} is a byte array +in network byte order. For example, when \field{type} is VIRTIO_NET_FF_MASK_TYPE_IPV6, +the \field{mask} is in the format \hyperref[intro:IPv6-Header-Format]{IPv6 Header Format}. + +If partial masking is not set, then all bits in each field have to be either all 0s +to ignore this field or all 1s to match on this field. If partial masking is set, +then any combination of bits can bit set to match on these bits. +For example, when a selector \field{type} is VIRTIO_NET_FF_MASK_TYPE_ETH, if +\field{mask[0-12]} are zero and \field{mask[13-14]} are 0xff (all 1s), it +indicates that matching is only supported for \field{EtherType} of +\field{Ethernet MAC frame}, matching is not supported for +\field{Destination Address} and \field{Source Address}. + +The entries in the array \field{selectors} are ordered by +\field{type}, with each \field{type} value only appearing once. + +\field{length} is the length of a dynamic array \field{mask} in bytes. +\field{reserved} and \field{reserved1} are reserved and set to zero. + +\begin{table}[H] +\caption{Flow filter selector types} +\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / flow filter selector types} +\begin{tabularx}{\textwidth}{ |l|X|X| } +\hline +Type & Name & Description \\ +\hline \hline +0x0 & - & Reserved \\ +\hline +0x1 & VIRTIO_NET_FF_MASK_TYPE_ETH & 14 bytes of frame header starting from destination address described in \hyperref[intro:IEEE 802.3-2022]{IEEE 802.3-2022} \\ +\hline +0x2 & VIRTIO_NET_FF_MASK_TYPE_IPV4 & 20 bytes of \hyperref[intro:Internet-Header-Format]{IPv4: Internet Header Format} \\ +\hline +0x3 & VIRTIO_NET_FF_MASK_TYPE_IPV6 & 40 bytes of \hyperref[intro:IPv6-Header-Format]{IPv6 Header Format} \\ +\hline +0x4 & VIRTIO_NET_FF_MASK_TYPE_TCP & 20 bytes of \hyperref[intro:TCP-Header-Format]{TCP Header Format} \\ +\hline +0x5 & VIRTIO_NET_FF_MASK_TYPE_UDP & 8 bytes of UDP header described in \hyperref[intro:UDP]{UDP} \\ +\hline +0x6 - 0xFF & & Reserved for future \\ +\hline +\end{tabularx} +\end{table} + +When VIRTIO_NET_FF_MASK_F_PARTIAL_MASK (bit 0) is set, it indicates that +partial masking is supported for all the fields of the selector identified by \field{type}. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_IPV4, if a partial mask is unsupported, +then matching on an individual bit of \field{Flags} in the +\field{IPv4: Internet Header Format} is unsupported. \field{Flags} has to match as a whole +if it is supported. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_IPV4, \field{mask} includes fields +up to the \field{Destination Address}; that is, \field{Options} and +\field{Padding} are excluded. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_IPV6, the \field{Next Header} field +of the \field{mask} corresponds to the \field{Next Header} in the packet +when \field{IPv6 Extension Headers} are not present. When the packet includes +one or more \field{IPv6 Extension Headers}, the \field{Next Header} field of +the \field{mask} corresponds to the \field{Next Header} of the last +\field{IPv6 Extension Header} in the packet. + +For the selector \field{type} VIRTIO_NET_FF_MASK_TYPE_TCP, \field{Control bits} +are treated as individual fields for matching; that is, matching individual +\field{Control bits} does not depend on the partial mask support. + +\subparagraph{VIRTIO_NET_FF_ACTION_CAP} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP} + +The capability VIRTIO_NET_FF_ACTION_CAP lists the supported actions in a rule. +\field{cap_specific_data} is in the format \field{struct virtio_net_ff_cap_actions}. + +\begin{lstlisting} +struct virtio_net_ff_actions { + u8 count; + u8 reserved[7]; + u8 actions[]; +}; +\end{lstlisting} + +\field{actions} is an array listing all possible actions. +The entries in the array are ordered from the smallest to the largest, +with each supported value appearing exactly once. Each entry can have the +following values: + +\begin{table}[H] +\caption{Flow filter rule actions} +\label{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP / flow filter rule actions} +\begin{tabularx}{\textwidth}{ |l|X|X| } +\hline +Action & Name & Description \\ +\hline \hline +0x0 & - & reserved \\ +\hline +0x1 & VIRTIO_NET_FF_ACTION_DROP & Matching packet will be dropped by the device \\ +\hline +0x2 & VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ & Matching packet will be directed to a receive queue \\ +\hline +0x3 - 0xFF & & Reserved for future \\ +\hline +\end{tabularx} +\end{table} + +\paragraph{Resource objects} +\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects} + +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_GROUP}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-GROUP} + +A flow filter group contains between 0 and \field{rules_limit} rules, as specified by the +capability VIRTIO_NET_FF_RESOURCE_CAP. For the flow filter group object both +\field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_net_resource_obj_ff_group}. + +\begin{lstlisting} +struct virtio_net_resource_obj_ff_group { + le16 group_priority; +}; +\end{lstlisting} + +\field{group_priority} specifies the priority for the group. Each group has a +distinct priority. For each incoming packet, the device tries to apply rules +from groups from higher \field{group_priority} value to lower, until either a +rule matches the packet or all groups have been tried. + +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-CLASSIFIER} + +A classifier is used to match a flow filter key against a packet. The +classifier defines the desired packet fields to match, and is represented by +the VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER device resource object. + +For the flow filter classifier object both \field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_net_resource_obj_ff_classifier}. + +\begin{lstlisting} +struct virtio_net_resource_obj_ff_classifier { + u8 count; + u8 reserved[7]; + struct virtio_net_ff_selector selectors[]; +}; +\end{lstlisting} + +A classifier is an array of \field{selectors}. The number of selectors in the +array is indicated by \field{count}. The selector has a type that specifies +the header fields to be matched against, and a mask. +See \ref{lst:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-SELECTOR-CAP / virtio-net-ff-selector} +for details about selectors. + +The first selector is always VIRTIO_NET_FF_MASK_TYPE_ETH. When there are multiple +selectors, a second selector can be either VIRTIO_NET_FF_MASK_TYPE_IPV4 +or VIRTIO_NET_FF_MASK_TYPE_IPV6. If the third selector exists, the third +selector can be either VIRTIO_NET_FF_MASK_TYPE_UDP or VIRTIO_NET_FF_MASK_TYPE_TCP. +For example, to match a Ethernet IPv6 UDP packet, +\field{selectors[0].type} is set to VIRTIO_NET_FF_MASK_TYPE_ETH, \field{selectors[1].type} +is set to VIRTIO_NET_FF_MASK_TYPE_IPV6 and \field{selectors[2].type} is +set to VIRTIO_NET_FF_MASK_TYPE_UDP; accordingly, \field{selectors[0].mask[0-13]} is +for Ethernet header fields, \field{selectors[1].mask[0-39]} is set for IPV6 header +and \field{selectors[2].mask[0-7]} is set for UDP header. + +When there are multiple selectors, the type of the (N+1)\textsuperscript{th} selector +affects the mask of the (N)\textsuperscript{th} selector. If +\field{count} is 2 or more, all the mask bits within \field{selectors[0]} +corresponding to \field{EtherType} of an Ethernet header are set. + +If \field{count} is more than 2: +\begin{itemize} +\item if \field{selector[1].type} is, VIRTIO_NET_FF_MASK_TYPE_IPV4, then, all the mask bits within +\field{selector[1]} for \field{Protocol} is set. +\item if \field{selector[1].type} is, VIRTIO_NET_FF_MASK_TYPE_IPV6, then, all the mask bits within +\field{selector[1]} for \field{Next Header} is set. +\end{itemize} + +If for a given packet header field, a subset of bits of a field is to be matched, +and if the partial mask is supported, the flow filter +mask object can specify a mask which has fewer bits set than the packet header +field size. For example, a partial mask for the Ethernet header source mac +address can be of 1-bit for multicast detection instead of 48-bits. + +\subparagraph{VIRTIO_NET_RESOURCE_OBJ_FF_RULE}\label{par:Device Types / Network Device / Device Operation / Flow filter / Resource objects / VIRTIO-NET-RESOURCE-OBJ-FF-RULE} + +Each flow filter rule resource object comprises a key, a priority, and an action. +For the flow filter rule object, +\field{resource_obj_specific_data} and +\field{resource_obj_specific_result} are in the format +\field{struct virtio_net_resource_obj_ff_rule}. + +\begin{lstlisting} +struct virtio_net_resource_obj_ff_rule { + le32 group_id; + le32 classifier_id; + u8 rule_priority; + u8 key_length; /* length of key in bytes */ + u8 action; + u8 reserved; + le16 vq_index; + u8 reserved1[2]; + u8 keys[][]; +}; +\end{lstlisting} + +\field{group_id} is the resource object ID of the flow filter group to which +this rule belongs. \field{classifier_id} is the resource object ID of the +classifier used to match a packet against the \field{key}. + +\field{rule_priority} denotes the priority of the rule within the group +specified by the \field{group_id}. +Rules within the group are applied from the highest to the lowest priority +until a rule matches the packet and an +action is taken. Rules with the same priority can be applied in any order. + +\field{reserved} and \field{reserved1} are reserved and set to 0. + +\field{keys[][]} is an array of keys to match against packets, using +the classifier specified by \field{classifier_id}. Each entry (key) comprises +a byte array, and they are located one immediately after another. +The size (number of entries) of the array is exactly the same as that of +\field{selectors} in the classifier, or in other words, \field{count} +in the classifier. + +\field{key_length} specifies the total length of \field{keys} in bytes. +In other words, it equals the sum total of \field{length} of all +selectors in \field{selectors} in the classifier specified by +\field{classifier_id}. + +For example, if a classifier object's \field{selectors[0].type} is +VIRTIO_NET_FF_MASK_TYPE_ETH and \field{selectors[1].type} is +VIRTIO_NET_FF_MASK_TYPE_IPV6, +then selectors[0].length is 14 and selectors[1].length is 40. +Accordingly, the \field{key_length} is set to 54. +This setting indicates that the \field{key} array's length is 54 bytes +comprising a first byte array of 14 bytes for the +Ethernet MAC header in bytes 0-13, immediately followed by 40 bytes for the +IPv6 header in bytes 14-53. + +When there are multiple selectors in the classifier object, the key bytes +for (N)\textsuperscript{th} selector are set so that +(N+1)\textsuperscript{th} selector can be matched. + +If \field{count} is 2 or more, key bytes of \field{EtherType} +are set according to \hyperref[intro:IEEE 802 Ethertypes]{IEEE 802 Ethertypes} +for VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6 respectively. + +If \field{count} is more than 2, when \field{selector[1].type} is +VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6, key +bytes of \field{Protocol} or \field{Next Header} is set as per +\field{Protocol Numbers} defined \hyperref[intro:IANA Protocol Numbers]{IANA Protocol Numbers} +respectively. + +\field{action} is the action to take when a packet matches the +\field{key} using the \field{classifier_id}. Supported actions are described in +\ref{table:Device Types / Network Device / Device Operation / Flow filter / Device and driver capabilities / VIRTIO-NET-FF-ACTION-CAP / flow filter rule actions}. + +\field{vq_index} specifies a receive virtqueue. When the \field{action} is set +to VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ, and the packet matches the \field{key}, +the matching packet is directed to this virtqueue. + +Note that at most one action is ever taken for a given packet. If a rule is +applied and an action is taken, the action of other rules is not taken. + +\devicenormative{\paragraph}{Flow filter}{Device Types / Network Device / Device Operation / Flow filter} + +When the device supports flow filter operations, +\begin{itemize} +\item the device MUST set VIRTIO_NET_FF_RESOURCE_CAP, VIRTIO_NET_FF_SELECTOR_CAP +and VIRTIO_NET_FF_ACTION_CAP capability in the \field{supported_caps} in the +command VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY. +\item the device MUST support the administration commands +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY for the resource types +VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER and +VIRTIO_NET_RESOURCE_OBJ_FF_RULE. +\end{itemize} + +When any of the VIRTIO_NET_FF_RESOURCE_CAP, VIRTIO_NET_FF_SELECTOR_CAP, or +VIRTIO_NET_FF_ACTION_CAP capability is disabled, the device SHOULD set +\field{status} to VIRTIO_ADMIN_STATUS_Q_INVALID_OPCODE for the commands +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_OBJ_QUERY, +and VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY. These commands apply to the resource +\field{type} of VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, and +VIRTIO_NET_RESOURCE_OBJ_FF_RULE. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_EINVAL for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the resource \field{type} +is VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, if a flow filter group already exists +with the supplied \field{group_priority}. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the resource \field{type} +is VIRTIO_NET_RESOURCE_OBJ_FF_GROUP, if the number of flow filter group +objects in the device exceeds the lower of the configured driver +capabilities \field{groups_limit} and \field{rules_per_group_limit}. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE when the resource \field{type} is +VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, if the number of flow filter selector +objects in the device exceeds the configured driver capability +\field{selectors_limit}. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_EBUSY for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY for a flow filter group when +the flow filter group has one or more flow filter rules depending on it. + +The device SHOULD set \field{status} to VIRTIO_ADMIN_STATUS_EBUSY for the +command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY for a flow filter classifier when +the flow filter classifier has one or more flow filter rules depending on it. + +The device SHOULD fail the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE for the +flow filter rule resource object if, +\begin{itemize} +\item \field{vq_index} is not a valid receive virtqueue index for +the VIRTIO_NET_FF_ACTION_DIRECT_RX_VQ action, +\item \field{priority} is greater than or equal to + \field{last_rule_priority}, +\item \field{id} is greater than or equal to \field{rules_limit} or + greater than or equal to \field{rules_per_group_limit}, whichever is lower, +\item the length of \field{keys} and the length of all the mask bytes of + \field{selectors[].mask} as referred by \field{classifier_id} differs, +\item the supplied \field{action} is not supported in the capability VIRTIO_NET_FF_ACTION_CAP. +\end{itemize} + +When the flow filter directs a packet to the virtqueue identified by +\field{vq_index} and if the receive virtqueue is reset, the device +MUST drop such packets. + +Upon applying a flow filter rule to a packet, the device MUST STOP any further +application of rules and cease applying any other steering configurations. + +For multiple flow filter groups, the device MUST apply the rules from +the group with the highest priority. If any rule from this group is applied, +the device MUST ignore the remaining groups. If none of the rules from the +highest priority group match, the device MUST apply the rules from +the group with the next highest priority, until either a rule matches or +all groups have been attempted. + +The device MUST apply the rules within the group from the highest to the +lowest priority until a rule matches the packet, and the device MUST take +the action. If an action is taken, the device MUST not take any other +action for this packet. + +The device MAY apply the rules with the same \field{rule_priority} in any +order within the group. + +The device MUST process incoming packets in the following order: +\begin{itemize} +\item apply the steering configuration received using control virtqueue + commands VIRTIO_NET_CTRL_RX, VIRTIO_NET_CTRL_MAC, and + VIRTIO_NET_CTRL_VLAN. +\item apply flow filter rules if any. +\item if no filter rule is applied, apply the steering configuration + received using the command VIRTIO_NET_CTRL_MQ_RSS_CONFIG + or according to automatic receive steering. +\end{itemize} + +When processing an incoming packet, if the packet is dropped at any stage, the device +MUST skip further processing. + +When the device drops the packet due to the configuration done using the control +virtqueue commands VIRTIO_NET_CTRL_RX or VIRTIO_NET_CTRL_MAC or VIRTIO_NET_CTRL_VLAN, +the device MUST skip flow filter rules for this packet. + +When the device performs flow filter match operations and if the operation +result did not have any match in all the groups, the receive packet processing +continues to next level, i.e. to apply configuration done using +VIRTIO_NET_CTRL_MQ_RSS_CONFIG command. + +The device MUST support the creation of flow filter classifier objects +using the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE with \field{flags} +set to VIRTIO_NET_FF_MASK_F_PARTIAL_MASK; +this support is required even if all the bits of the masks are set for +a field in \field{selectors}, provided that partial masking is supported +for the selectors. + +\drivernormative{\paragraph}{Flow filter}{Device Types / Network Device / Device Operation / Flow filter} + +The driver MUST enable VIRTIO_NET_FF_RESOURCE_CAP, VIRTIO_NET_FF_SELECTOR_CAP, +and VIRTIO_NET_FF_ACTION_CAP capabilities to use flow filter. + +The driver SHOULD NOT remove a flow filter group using the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY when one or more flow filter rules +depend on that group. The driver SHOULD only destroy the group after +all the associated rules have been destroyed. + +The driver SHOULD NOT remove a flow filter classifier using the command +VIRTIO_ADMIN_CMD_RESOURCE_OBJ_DESTROY when one or more flow filter rules +depend on the classifier. The driver SHOULD only destroy the classifier +after all the associated rules have been destroyed. + +The driver SHOULD NOT add multiple flow filter rules with the same +\field{rule_priority} within a flow filter group, as these rules MAY match +the same packet. The driver SHOULD assign different \field{rule_priority} +values to different flow filter rules if multiple rules may match a single +packet. + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, when creating a resource +of \field{type} VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, the driver MUST set: +\begin{itemize} +\item \field{selectors[0].type} to VIRTIO_NET_FF_MASK_TYPE_ETH. +\item \field{selectors[1].type} to VIRTIO_NET_FF_MASK_TYPE_IPV4 or + VIRTIO_NET_FF_MASK_TYPE_IPV6 when \field{count} is more than 1, +\item \field{selectors[2].type} VIRTIO_NET_FF_MASK_TYPE_UDP or + VIRTIO_NET_FF_MASK_TYPE_TCP when \field{count} is more than 2. +\end{itemize} + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, when creating a resource +of \field{type} VIRTIO_NET_RESOURCE_OBJ_FF_CLASSIFIER, the driver MUST set: +\begin{itemize} +\item \field{selectors[0].mask} bytes to all 1s for the \field{EtherType} + when \field{count} is 2 or more. +\item \field{selectors[1].mask} bytes to all 1s for \field{Protocol} or \field{Next Header} + when \field{selector[1].type} is VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6, + and when \field{count} is more than 2. +\end{itemize} + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, the resource \field{type} +VIRTIO_NET_RESOURCE_OBJ_FF_RULE, if the corresponding classifier object's +\field{count} is 2 or more, the driver MUST SET the \field{keys} bytes of +\field{EtherType} in accordance with +\hyperref[intro:IEEE 802 Ethertypes]{IEEE 802 Ethertypes} +for either VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6. + +For the command VIRTIO_ADMIN_CMD_RESOURCE_OBJ_CREATE, when creating a resource of +\field{type} VIRTIO_NET_RESOURCE_OBJ_FF_RULE, if the corresponding classifier +object's \field{count} is more than 2, and the \field{selector[1].type} is either +VIRTIO_NET_FF_MASK_TYPE_IPV4 or VIRTIO_NET_FF_MASK_TYPE_IPV6, the driver MUST +set the \field{keys} bytes for the \field{Protocol} or \field{Next Header} +according to \hyperref[intro:IANA Protocol Numbers]{IANA Protocol Numbers} respectively. + +The driver SHOULD set all the bits for a field in the mask of a selector in both the +capability and the classifier object, unless the VIRTIO_NET_FF_MASK_F_PARTIAL_MASK +is enabled. + \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device Types / Network Device / Legacy Interface: Framing Requirements} When using legacy interfaces, transitional drivers which have not negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the -struct virtio_net_hdr on both transmit and receive, with the +\field{struct virtio_net_hdr} on both transmit and receive, with the network data in the following descriptors. Additionally, when using the control virtqueue (see \ref{sec:Device diff --git a/device-types/net/device-conformance.tex b/device-types/net/device-conformance.tex index f88f48b..d88484c 100644 --- a/device-types/net/device-conformance.tex +++ b/device-types/net/device-conformance.tex @@ -15,4 +15,7 @@ \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) / RSS processing} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} \item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} +\item \ref{devicenormative:Device Types / Network Device / Device Operation / Flow filter} \end{itemize} diff --git a/device-types/net/driver-conformance.tex b/device-types/net/driver-conformance.tex index 9d853d9..d346b88 100644 --- a/device-types/net/driver-conformance.tex +++ b/device-types/net/driver-conformance.tex @@ -15,4 +15,7 @@ \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Receive-side scaling (RSS) } \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Notifications Coalescing} \item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Inner Header Hash} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / Device Statistics} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Control Virtqueue / RSS Context} +\item \ref{drivernormative:Device Types / Network Device / Device Operation / Flow filter} \end{itemize} diff --git a/device-types/sound/description.tex b/device-types/sound/description.tex index 54c9c8e..bad4415 100644 --- a/device-types/sound/description.tex +++ b/device-types/sound/description.tex @@ -504,7 +504,9 @@ \subsubsection{PCM Control Messages}\label{sec:Device Types / Sound Device / Dev VIRTIO_SND_PCM_RATE_96000, VIRTIO_SND_PCM_RATE_176400, VIRTIO_SND_PCM_RATE_192000, - VIRTIO_SND_PCM_RATE_384000 + VIRTIO_SND_PCM_RATE_384000, + VIRTIO_SND_PCM_RATE_12000, + VIRTIO_SND_PCM_RATE_24000 }; struct virtio_snd_pcm_info { diff --git a/device-types/spi/description.tex b/device-types/spi/description.tex new file mode 100644 index 0000000..84fd2c9 --- /dev/null +++ b/device-types/spi/description.tex @@ -0,0 +1,286 @@ +\section{SPI Controller Device}\label{sec:Device Types / SPI Controller Device} + +The Virtio SPI (Serial Peripheral Interface) device is a virtual SPI controller that +allows the driver to operate and use the SPI controller under the control of the host, +either a physical SPI controller, or an emulated one. + +The Virtio SPI device has a single virtqueue. SPI transfer requests are placed into +the virtqueue by the driver, and are serviced by the device. + +In a typical host and guest architecture with the Virtio SPI device, the Virtio SPI driver +is the front-end running in the guest, and the Virtio SPI device is the back-end +in the host. + +\subsection{Device ID}\label{sec:Device Types / SPI Controller Device / Device ID} +45 + +\subsection{Virtqueues}\label{sec:Device Types / SPI Controller Device / Virtqueues} + +\begin{description} +\item[0] requestq +\end{description} + +\subsection{Feature bits}\label{sec:Device Types / SPI Controller Device / Feature bits} + +None + +\subsection{Device configuration layout}\label{sec:Device Types / SPI Controller Device / Device configuration layout} + +All fields of this configuration are mandatory and read-only for the driver. +The config space shows the features and settings supported by the device. + +\begin{lstlisting} +struct virtio_spi_config { + u8 cs_max_number; + u8 cs_change_supported; + u8 tx_nbits_supported; + u8 rx_nbits_supported; + le32 bits_per_word_mask; + le32 mode_func_supported; + le32 max_freq_hz; + le32 max_word_delay_ns; + le32 max_cs_setup_ns; + le32 max_cs_hold_ns; + le32 max_cs_inactive_ns; +}; +\end{lstlisting} + +\field{cs_max_number} is the maximum number of chipselect the device supports. + +Note: chipselect is an electrical signal, which is used to select the SPI peripherals connected +to the controller. + +\field{cs_change_supported} indicates if the device supports to toggle chipselect +after each transfer in one message: + 0: unsupported, chipselect will be kept in active state throughout the message transaction; + 1: supported. + +Note: Message here contains a sequence of SPI transfers. + +\field{tx_nbits_supported} and \field{rx_nbits_supported} indicate the different n-bit transfer +modes supported by the device, for writing and reading respectively. SINGLE is always supported. +A set bit here indicates that the corresponding n-bit transfer is supported, otherwise not: + bit 0: DUAL; + bit 1: QUAD; + bit 2: OCTAL; + other bits are reserved and must be set as 0 by the device. + +Note: The commonly used SPI n-bit transfer options are: +\begin{itemize} +\item SINGLE: 1-bit transfer +\item DUAL: 2-bit transfer +\item QUAD: 4-bit transfer +\item OCTAL: 8-bit transfer +\end{itemize} + +\field{bits_per_word_mask} is a mask indicating which values of bits_per_word are supported. +If bit n of \field{bits_per_word_mask} is set, the bits_per_word with value (n+1) is supported. +If \field{bits_per_word_mask} is 0, there is no limitation for bits_per_word. + +Note: bits_per_word corresponds to \field{bits_per_word} in \field{struct virtio_spi_transfer_head}. + +\field{mode_func_supported} indicates whether the following features are supported or not: + bit 0-1: CPHA feature, + 0b00: invalid, must support as least one CPHA setting. + 0b01: supports CPHA=0 only; + 0b10: supports CPHA=1 only; + 0b11: supports CPHA=0 and CPHA=1; + + bit 2-3: CPOL feature, + 0b00: invalid, must support as least one CPOL setting. + 0b01: supports CPOL=0 only; + 0b10: supports CPOL=1 only; + 0b11: supports CPOL=0 and CPOL=1; + + bit 4: chipselect active high feature, 0 for unsupported and 1 for supported, + chipselect active low must always be supported. + + bit 5: LSB first feature, 0 for unsupported and 1 for supported, MSB first must always be + supported. + + bit 6: loopback mode feature, 0 for unsupported and 1 for supported, normal mode + must always be supported. + +Note: CPOL is clock polarity and CPHA is clock phase. If CPOL is 0, the clock idles at the logical +low voltage, otherwise it idles at the logical high voltage. CPHA determines how data is outputted +and sampled. If CPHA is 0, the first bit is outputted immediately when chipselect is active and +subsequent bits are outputted on the clock edges when the clock transitions from active level to idle +level. Data is sampled on the clock edges when the clock transitions from idle level to active level. +If CPHA is 1, the first bit is outputted on the fist clock edge after chipselect is active, subsequent +bits are outputted on the clock edges when the clock transitions from idle level to active level. +Data is sampled on the clock edges when the clock transitions from active level to idle level. + +Note: LSB first indicates that data is transferred least significant bit first, and MSB first +indicates that data is transferred most significant bit first. + +\field{max_freq_hz} is the maximum clock rate supported in Hz unit, 0 means no limitation +for transfer speed. + +\field{max_word_delay_ns} is the maximum word delay supported in ns unit, 0 means word delay +feature is unsupported. + +Note: Just as one message contains a sequence of transfers, one transfer may contain +a sequence of words. + +\field{max_cs_setup_ns} is the maximum delay supported after chipselect is asserted, in ns unit, +0 means delay is not supported to introduce after chipselect is asserted. + +\field{max_cs_hold_ns} is the maximum delay supported before chipselect is deasserted, in ns unit, +0 means delay is not supported to introduce before chipselect is deasserted. + +\field{max_cs_incative_ns} is the maximum delay supported after chipselect is deasserted, in ns unit, +0 means delay is not supported to introduce after chipselect is deasserted. + +\subsection{Device Initialization}\label{sec:Device Types / SPI Controller Device / Device Initialization} + +\begin{enumerate} +\item The Virtio SPI driver configures and initializes the virtqueue. +\end{enumerate} + +\subsection{Device Operation}\label{sec:Device Types / SPI Controller Device / Device Operation} + +\subsubsection{Device Operation: Request Queue}\label{sec:Device Types / SPI Controller Device / Device Operation: Request Queue} + +The Virtio SPI driver enqueues requests to the virtqueue, and they are used by the Virtio SPI device. +Each request represents one SPI transfer and is of the form: + +\begin{lstlisting} +struct virtio_spi_transfer_head { + u8 chip_select_id; + u8 bits_per_word; + u8 cs_change; + u8 tx_nbits; + u8 rx_nbits; + u8 reserved[3]; + le32 mode; + le32 freq; + le32 word_delay_ns; + le32 cs_setup_ns; + le32 cs_delay_hold_ns; + le32 cs_change_delay_inactive_ns; +}; +\end{lstlisting} + +\begin{lstlisting} +struct virtio_spi_transfer_result { + u8 result; +}; +\end{lstlisting} + +\begin{lstlisting} +struct virtio_spi_transfer_req { + struct virtio_spi_transfer_head head; + u8 tx_buf[]; + u8 rx_buf[]; + struct virtio_spi_transfer_result result; +}; +\end{lstlisting} + +\field{chip_select_id} indicates the chipselect index to use for the SPI transfer. + +\field{bits_per_word} indicates the number of bits in each SPI transfer word. + +\field{cs_change} indicates whether to deselect device before starting the next SPI transfer, +0 means chipselect keep asserted and 1 means chipselect deasserted then asserted again. + +\field{tx_nbits} and \field{rx_nbits} indicate n-bit transfer mode for writing and reading: + 0,1: SINGLE; + 2 : DUAL; + 4 : QUAD; + 8 : OCTAL; + other values are invalid. + +\field{reserved} is currently unused and might be used for further extensions in the future. + +\field{mode} indicates some transfer settings. Bit definitions as follows: + bit 0: CPHA, determines the timing (i.e. phase) of the data bits relative to the + clock pulses. + bit 1: CPOL, determines the polarity of the clock. + bit 2: CS_HIGH, if 1, chipselect active high, else active low. + bit 3: LSB_FIRST, determines per-word bits-on-wire, if 0, MSB first, else LSB first. + bit 4: LOOP, if 1, device is in loopback mode, else normal mode. + +\field{freq} indicates the SPI transfer speed in Hz. + +\field{word_delay_ns} indicates delay to be inserted between consecutive words of a transfer, +in ns unit. + +\field{cs_setup_ns} indicates delay to be introduced after chipselect is asserted, in ns unit. + +\field{cs_delay_hold_ns} indicates delay to be introduced before chipselect is deasserted, +in ns unit. + +\field{cs_change_delay_inactive_ns} indicates delay to be introduced after chipselect is +deasserted and before next asserted, in ns unit. + +\field{tx_buf} is the buffer for data sent to the device. + +\field{rx_buf} is the buffer for data received from the device. + +\field{result} is the transfer result, it may be one of the following values: + +\begin{lstlisting} +#define VIRTIO_SPI_TRANS_OK 0 +#define VIRTIO_SPI_PARAM_ERR 1 +#define VIRTIO_SPI_TRANS_ERR 2 +\end{lstlisting} + +VIRTIO_SPI_TRANS_OK indicates successful completion of the transfer. + +VIRTIO_SPI_PARAM_ERR indicates a parameter error, which means the parameters in +\field{struct virtio_spi_transfer_head} are not all valid, or some fields are set as +non-zero values but the corresponding features are not supported by device. +In particular, for full-duplex transfer, VIRTIO_SPI_PARAM_ERR can also indicate that +\field{tx_buf} and \field{rx_buf} are not of the same length. + +VIRTIO_SPI_TRANS_ERR indicates a transfer error, which means that the parameters are all +valid but the transfer process failed. + +\subsubsection{Device Operation: Operation Status}\label{sec:Device Types / SPI Controller Device / Device Operation: Operation Status} + +Fields in \field{struct virtio_spi_transfer_head} are written by the Virtio SPI driver, while +\field{result} in \field{struct virtio_spi_transfer_result} is written by the Virtio SPI device. + +virtio-spi supports three transfer types: +\begin{itemize} +\item half-duplex read; +\item half-duplex write; +\item full-duplex transfer. +\end{itemize} + +For half-duplex read and full-duplex transfer, \field{rx_buf} is filled by the Virtio SPI device +and consumed by the Virtio SPI driver. For half-duplex write and full-duplex transfer, \field{tx_buf} +is filled by the Virtio SPI driver and consumed by the Virtio SPI device. + +\drivernormative{\subsubsection}{Device Operation}{Device Types / SPI Controller Device / Device Operation} + +For half-duplex read, the Virtio SPI driver MUST send \field{struct virtio_spi_transfer_head}, +\field{rx_buf} and \field{struct virtio_spi_transfer_result} to the SPI Virtio Device in that order. + +For half-duplex write, the Virtio SPI driver MUST send \field{struct virtio_spi_transfer_head}, +\field{tx_buf} and \field{struct virtio_spi_transfer_result} to the SPI Virtio Device in that order. + +For full-duplex transfer, the Virtio SPI driver MUST send \field{struct virtio_spi_transfer_head}, +\field{tx_buf}, \field{rx_buf} and \field{struct virtio_spi_transfer_result} to the SPI Virtio Device +in that order. + +For full-duplex transfer, the Virtio SPI driver MUST guarantee that the buffer size of \field{tx_buf} +and \field{rx_buf} is the same. + +The Virtio SPI driver MUST not use \field{rx_buf} if the \field{result} returned from the Virtio SPI device is +not VIRTIO_SPI_TRANS_OK. + +\devicenormative{\subsubsection}{Device Operation}{Device Types / SPI Controller Device / Device Operation} + +The Virtio SPI device MUST set all the fields of \field{struct virtio_spi_config} before they are +read by the Virtio SPI driver. + +The Virtio SPI device MUST NOT change the data in \field{tx_buf}. + +The Virtio SPI device MUST verify the parameters in \field{struct virtio_spi_transfer_head} after receiving +the request, and MUST set \field{struct virtio_spi_transfer_result} as VIRTIO_SPI_PARAM_ERR if not all +parameters are valid or some device unsupported features are set. + +For full-duplex transfer, the Virtio SPI device MUST verify that the buffer size of \field{tx_buf} is equal to +that of \field{rx_buf}. If not, the Virtio SPI device MUST set \field{struct virtio_spi_transfer_result} +as VIRTIO_SPI_PARAM_ERR. diff --git a/device-types/spi/device-conformance.tex b/device-types/spi/device-conformance.tex new file mode 100644 index 0000000..4509156 --- /dev/null +++ b/device-types/spi/device-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{SPI Controller Device Conformance}\label{sec:Conformance / Device Conformance / SPI Controller Device Conformance} + +An SPI Controller device MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{devicenormative:Device Types / SPI Controller Device / Device Operation} +\end{itemize} diff --git a/device-types/spi/driver-conformance.tex b/device-types/spi/driver-conformance.tex new file mode 100644 index 0000000..bbd1967 --- /dev/null +++ b/device-types/spi/driver-conformance.tex @@ -0,0 +1,7 @@ +\conformance{\subsection}{SPI Controller Driver Conformance}\label{sec:Conformance / Driver Conformance / SPI Controller Driver Conformance} + +An SPI Controller driver MUST conform to the following normative statements: + +\begin{itemize} +\item \ref{drivernormative:Device Types / SPI Controller Device / Device Operation} +\end{itemize} diff --git a/introduction.tex b/introduction.tex index 44c4ca4..e60298a 100644 --- a/introduction.tex +++ b/introduction.tex @@ -59,6 +59,18 @@ \section{Normative References}\label{sec:Normative References} IEEE Standard for Local and Metropolitan Area Networks: Overview and Architecture, \newline\url{http://www.ieee802.org/}, IEEE\\ + \phantomsection\label{intro:IEEE 802.3-2022}\textbf{[IEEE 802.3-2022]} & + IEEE Standard for Ethernet, + \newline\url{https://doi.org/10.1109/IEEESTD.2022.9844436}, + IEEE 802.3-2022\\ + \phantomsection\label{intro:IEEE 802 Ethertypes}\textbf{[IEEE 802 Ethertypes]} & + IEEE 802 Ethertypes, + \newline\url{https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.xhtml}, + IANA\\ + \phantomsection\label{intro:IANA Protocol Numbers}\textbf{[IANA Protocol Numbers]} & + IANA Protocol Numbers, + \newline\url{https://www.iana.org/assignments/protocol-numbers}, + IANA\\ \phantomsection\label{intro:SAM}\textbf{[SAM]} & SCSI Architectural Model, \newline\url{http://www.t10.org/cgi-bin/ac.pl?t=f&f=sam4r05.pdf}\\ @@ -135,12 +147,23 @@ \section{Normative References}\label{sec:Normative References} \phantomsection\label{intro:IP}\textbf{[IP]} & INTERNET PROTOCOL \newline\url{https://www.rfc-editor.org/rfc/rfc791}\\ + \phantomsection\label{intro:Internet-Header-Format}\textbf{[Internet Header Format]} & + Internet Header Format + \newline\url{https://datatracker.ietf.org/doc/html/rfc791#section-3.1}\\ + \phantomsection\label{intro:IPv6-Header-Format}\textbf{[IPv6 Header Format]} & + IPv6 Header Format + \newline\url{https://www.rfc-editor.org/rfc/rfc8200#section-3}\\ \phantomsection\label{intro:UDP}\textbf{[UDP]} & User Datagram Protocol \newline\url{https://www.rfc-editor.org/rfc/rfc768}\\ \phantomsection\label{intro:TCP}\textbf{[TCP]} & TRANSMISSION CONTROL PROTOCOL \newline\url{https://www.rfc-editor.org/rfc/rfc793}\\ + \phantomsection\label{intro:TCP-Header-Format}\textbf{[TCP Header Format]} & + TCP Header Format + \newline\url{https://www.rfc-editor.org/rfc/rfc9293#name-header-format}\\ + \phantomsection\label{intro:CAN}\textbf{[CAN]} & + ISO 11898-1:2015 Road vehicles -- Controller area network (CAN) -- Part 1: Data link layer and physical signalling\\ \phantomsection\label{intro:rfc8174}\textbf{[RFC8174]} & Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017 diff --git a/main.tex b/main.tex index b1913d6..6d33721 100644 --- a/main.tex +++ b/main.tex @@ -42,6 +42,8 @@ \input{newdevice.tex} +\input{newtransport.tex} + % acknowledgements \input{acknowledgements.tex} diff --git a/make-setup-generated.sh b/make-setup-generated.sh index 2c5c7f8..3380437 100755 --- a/make-setup-generated.sh +++ b/make-setup-generated.sh @@ -1,16 +1,31 @@ #! /bin/sh +# +# Generate version and metadata preamble for the document +# DATESTR=${DATESTR:-`cat REVISION-DATE 2>/dev/null`} -if [ x"$DATESTR" = x ]; then - ISODATE=`git show --format=format:'%cd' --date=iso | head -n 1` - DATESTR=`date -d "$DATE" +'%d %B %Y'` + +# If a second argument is passed we extract what we can from git +# metadata (closest lightweight tag) and local tree status. This +# allows locally generated copies to be tagged appropriately. +# +# The formal build process skips this. +if ! test -z "$2"; then + TAG=$(git describe --dirty --tags) + # base date on now + DATESTR=$(date +'%d %B %Y') + COMMIT=$(git rev-parse --short HEAD) + + # Finally check if we have un-committed changes in the tree + if ! git diff-index --quiet HEAD -- ; then + COMMIT="$COMMIT with local changes" + fi fi case "$1" in *-wd*) STAGE=wd STAGENAME="Working Draft" - WORKINGDRAFT=`basename "$1" | sed 's/.*-wd//'` ;; *-os*) STAGE=os @@ -41,6 +56,14 @@ esac VERSION=`echo "$1"| sed -e 's/virtio-v//' -e 's/-.*//'` +# +# Finally if we are building a local draft copy append the commit +# details to the end of the working draft +# +if ! test -z "$COMMIT" ; then + STAGEEXTRATITLE="$STAGEEXTRATITLE (@ git $COMMIT)" +fi + #Prepend OASIS unless already there case "$STAGENAME" in OASIS*) diff --git a/makeall.sh b/makeall.sh index 37e6c34..5f5d5dc 100755 --- a/makeall.sh +++ b/makeall.sh @@ -3,8 +3,8 @@ export SPECDOC=${SPECDOC:-`cat REVISION`} export DATESTR=${DATESTR:-`cat REVISION-DATE`} ./makezip.sh -./makehtml.sh -./makepdf.sh +./makehtml.sh $1 +./makepdf.sh $1 zip $SPECDOC.zip $SPECDOC.pdf echo Generated file $SPECDOC.zip echo To change output file name, set SPECDOC environment variable diff --git a/makediff.sh b/makediff.sh index 830a226..e068506 100755 --- a/makediff.sh +++ b/makediff.sh @@ -18,10 +18,11 @@ cd "${cur}/old" git checkout $oldrev while read -r rev; do echo "Applying $rev" - git cherry-pick --keep-redundant-commits --allow-empty `git rev-list -1 -F --grep "$rev" $newrev` || exit 1 + git cherry-pick --keep-redundant-commits --allow-empty `git rev-list -1 --grep "^$rev" $newrev` || exit 1 done << 'EOF' -content.tex Fix Driver notifications label -editorial: update "Computer Language Definitions" URL +editorial: allow for longer device id table: makediff 1.3 +admin: Prepare table for multipage listing +admin: switch to tabularx EOF #mv specvars.tex specvars-orig.tex diff --git a/makehtml.sh b/makehtml.sh index 45b7080..cf1a8d7 100755 --- a/makehtml.sh +++ b/makehtml.sh @@ -1,7 +1,7 @@ #!/bin/sh SPECDOC=${SPECDOC:-`cat REVISION`} -./make-setup-generated.sh "$SPECDOC" +./make-setup-generated.sh "$SPECDOC" $1 cp virtio-html.tex $SPECDOC.tex diff --git a/makepdf.sh b/makepdf.sh index 9cae903..bdfb8e5 100755 --- a/makepdf.sh +++ b/makepdf.sh @@ -1,7 +1,7 @@ #!/bin/sh SPECDOC=${SPECDOC:-`cat REVISION`} -./make-setup-generated.sh "$SPECDOC" +./make-setup-generated.sh "$SPECDOC" $1 rm $SPECDOC.aux $SPECDOC.pdf $SPECDOC.out xelatex --jobname $SPECDOC virtio.tex diff --git a/newdevice.tex b/newdevice.tex index ed0124b..4a71beb 100644 --- a/newdevice.tex +++ b/newdevice.tex @@ -65,4 +65,26 @@ \section{Device Improvements}\label{sec:Creating New Device Types / Device Impro others they should not be gratuitously grouped together to conserve feature bits. - +\section{How to define a new device part?}\label{sec:Creating New Device Types or Extending the Device / How to define a new device part?} +Few considerations are necessary when creating new device part or +when extending the device part structure. +If the new field is generic for all the device types or most of the device types, +a new device part should be defined as common device part by claiming a new \field{type} value. +If the new field is unique to a device type, a new device specific device part should +be added. +range. + +\section{When to define a new device part?}\label{sec:Creating New Device Types or Extending the Device / When to define a new device part?} +When the device part for a specific field does not exists, one should +define a new device part. + +\section{How to avoid device part duplication with existing structure?}\label{sec:Creating New Device Types or Extending the Device / How to avoid device part duplication with existing structure?} +Each device should reuse any existing field definition that may exists as part +of device control virtqueue or any other existing structure definition. + +\section{How to extend the existing device part definition?}\label{sec:Creating New Device Types or Extending the Device / How to extend the existing device part definition?} + +When a field is missing in already defined device part, a new field should be added at +the end of the existing device part. New field MUST not be added at beginning or in +the middle of the device part structure. Any field which is already present MUST NOT +be removed. diff --git a/newtransport.tex b/newtransport.tex new file mode 100644 index 0000000..b3e0df4 --- /dev/null +++ b/newtransport.tex @@ -0,0 +1,43 @@ +\chapter{Creating New Transports}\label{sec:Creating New Transports} + +Devices and drivers utilize various transport methods to facilitate +communication, such as PCI, MMIO, or Channel I/O. These transport +methods determine aspects of the interaction between the device and the +driver, including device discovery, capability exchange, interrupt +handling, and data transfer. For instance, in a host/guest architecture, +the host might expose a device to the guest via a virtual PCI bus, and +the guest would use a PCI device driver to interface with the device. + +This section outlines the mandatory requirements that a transport method +implements. + +A transport provides a mechanism to implement configuration space for +the device. + +A transport provides a mechanism for the driver to identify the device +type. + +A transport provides a mechanism for the driver to read the device's +FEATURES_OK and DEVICE_NEEDS_RESET status bits. + +A transport provides a mechanism for the driver to modify the device's +status. + +A transport provides a mechanism for the driver to read and modify the +device's feature bits. + +A transport allows one or more virtqueues to be implemented by the +device. The number of virtqueues is device specific and not specified by +the transport. + +A transport provides a mechanism for the driver to communicate virtqueue +configuration and memory location to the device. + +A transport provides a mechanism for the device to send device +notifications to the driver, such as used buffer notifications. + +A transport provides a mechanism for the driver to send driver +notifications to the device, such as available buffer notifications. + +A transport provides a mechanism for the driver to initiate a device +reset. diff --git a/packed-ring.tex b/packed-ring.tex index 9eeb382..3ee55a1 100644 --- a/packed-ring.tex +++ b/packed-ring.tex @@ -2,7 +2,7 @@ \section{Packed Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Pack Packed virtqueues is an alternative compact virtqueue layout using read-write memory, that is memory that is both read and written -by both host and guest. +by both the device and the driver. Use of packed virtqueues is negotiated by the VIRTIO_F_RING_PACKED feature bit. @@ -194,7 +194,7 @@ \subsection{Scatter-Gather Support} The device limits the number of descriptors in a list through a transport-specific and/or device-specific value. If not limited, -the maximum number of descriptors in a list is the virt queue +the maximum number of descriptors in a list is the virtqueue size. \subsection{Next Flag: Descriptor Chaining} diff --git a/transport-pci.tex b/transport-pci.tex index a5c6719..95b08b8 100644 --- a/transport-pci.tex +++ b/transport-pci.tex @@ -252,8 +252,8 @@ \subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Option \begin{lstlisting} struct virtio_pci_cap64 { struct virtio_pci_cap cap; - u32 offset_hi; - u32 length_hi; + le32 offset_hi; + le32 length_hi; }; \end{lstlisting} diff --git a/virtio.tex b/virtio.tex index 37e49b1..748df96 100644 --- a/virtio.tex +++ b/virtio.tex @@ -35,9 +35,11 @@ \usepackage{xltxtra} \usepackage{etoolbox} \usepackage{tabularx} +\usepackage{ltablex} \usepackage{underscore} \usepackage{xstring} \usepackage{enumitem} +\usepackage{float} \IfFileExists{ellipsis.sty}{\usepackage{ellipsis}}{ \message{!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!} \message{LaTeX Warning: Missing ellipsis.sty: dots (...) will look ugly}