Skip to contentSkip to conversation

flow filter using basic facilities of capabilities and resources

PATCH Superseded Parav Pandit 1 participant 14 messages Jan 30, 2024

v8 of 11 Superseded Latest is v11 →

lore
Share & tools
lore
#0 lore raw

v8 cover flow filter using basic facilities of capabilities and resources

Summary:
========
This series improves virtio net receive packet steering to forward/steer packets to a specific RQ.

This basic functionality will enable Linux ethtool steering, accelerated receive flow steering (ARFS) as starting point, and more use cases in future.

It is using new virtio basic facilities of capabilities and resources described later in this cover letter.

Those interested only in the capabilities and resources facilities can go straight to section "Overview of capabilities and resources".

Net device problem statement:
=============================
Currently packet allow/drop interface has few limitations.

1. Driver cannot add or delete an individual entry for mac and vlan.
2. Driver cannot select mac+vlan combination for which
to allow/drop packet.
3. Driver cannot not set other commonly used packet match fields such as IP header fields, TCP, UDP, SCP header fields.
4. Driver cannot steer specific packets based on the match fields to specific receiveq.
5. Driver do not have multiple or dedicated virtqueues to perform flow filter requests in accelerated manner in the device.

Solution:
=========
Flow filter as a generic framework to overcome above limitations.

Overview:
=========
A flow filter defines the flow based on one or more match fields of the packet, defines an action like drop/forward to RQ.

The flow filters are organized in flow filter groups so that their processing can be ordered when multiple applications wants to use it. For example, user supplied flow filter rules to take precedence over kernel stack created rules.

Flow filters are handled as resources and managed via administration commands. Flow filters current usage is in-between of control path and data path. i.e.
a. ethtool will operate at few hundred cmds/sec.
b. ARFS at few thousands cmds/sec.
c. In future connection tracking(CT) may do few millions/sec.

For b and c in future, few options are present.
1. Dedicated flow filter rules management to a specific AQ so that it can be accelerated by fast path
2. Define different admin command format for fast path
3. Special type of new virtqueue for CT driven requests

While a general BPF offload might be a superset of this functionality and might be desirable, it does not look feasible, in particular, from discussions with multiple hardware vendors it is clear that hardware will not have such capability in short to medium term.

Flow filter requirements addressed by this series is worked by virtio community at [1].

[1] https://lists.oasis-open.org/archives/virtio-comment/202308/msg00263.html

Overview of capabilities and resources:
=======================================
Config space has few advantages as below.
1. extendible
2. common way for each device to keep expanding it
3. provisioning to supply offset, value to set fields

However, the combination of feature bits + common config space + device config space + cvq creates four different communication channel between driver and device, each with a varied degree of limitations and complexities listed below.

1. Feature bits cannot be modified at later stage in the driver.
2. Feature bits are boolean; it cannot communicate amount of resources and configuration details. For this yet another config space or cvq is needed.
3. Making configuration space writable and also synchronizing it with device operation is very hard.
4. Modifying and controlling the device operation using cvq largely works but limited to specific device type and requires per device type cvq.
5. To provision features, resources, functionalities from the owner device, one still needs new admin commands.
6. It is hard to maintain and access variable length array in config space. We have to add the fields at the tail, this means if we start with foo1
bar1
later, to add foo2 it becomes
foo1
bar1
foo2
We end up with structure with mix of unrelated fields spoiling the readability/aestethics/maintainability.
7. Any writeable config space is a problem; for example very inefficient on pci as you have to read after write. It also lacks atomicity across multiple fields. So to avoid writable config space, and to use VQ, things spread around read_only config space and VQ, creating more mess.
8. It is not uncommon to have some driver resource and number
of resources would normally be in config space. But to write them to use VQ, and without proper resource definition it leads to overflow for example, the overflow we experience with mac table.
9. Extending config space and having it accessible even before negotiating features when the device does not know if it will be used or not makes it hard to build the devices.

Above limitations are overcome using new basic facilities as:
a. capabilities
b. resources

Capabilities and resources are an evolution of the (a) feature bits, (b, c) common and device configuration space and (d) controlvq mechanism; this new basic facilities are intended for managing a large number of diverse functionality in a uniform and extensible manner.

a. Capabilities:
=================
(1) It consist of device and driver functionalities, resource limits.
(2) It can be modified anytime using admin command.
(3) owner and member follows same format to read/write using a selector; simplifying the provisioning and migration commands.
(4) Accessing capabilities via command interface makes it friendly to both software and hardware based devices; possibly to operate even without admin vq.

b. Resources:
==============
(1) Define device functioning in a unified way instead of ad-hoc cvq commands.
(2) Can create diverse type of resources dynamically.
(3) Ability to define common and device specific resources and hence behavior.

This series defines flow filter related capabilities. This series defines two resources as flow filter group and rules to implement receive packet steering facility.

Limitations/Disadvantages:
===========================
1. Device side configuration change notifications are not covered in capabilities and resources yet as both are driven by the driver; however in future we should be able to add it to query the changes. In an alternative when notifications are frequent or multiple outstanding, it is better to come up with generic eventq or notificationq like how it is needed for alarm feature of RTC in [2].

2. It can be used only after DRIVER_OK phase at present, but when needed it can be extended to have admin command interface to be accessible after FEATURE_OK and before DRIVER_OK.
So presently capabilities cannot affect features, but any attempt will probably run in some corner case.

3. It is more plumbing than config space and cvq; however it is one time generic work that paves the road for mulitiple device types to use in common manner, reuse for provisioning and migration.

Future uses of resources:
=========================
1. Dynamically create VQs much after DRIVER_OK phase with multiple attributes such as multiple page addresses, header data split queues for net, with PASID, inline header size.

2. Create dynamic counter resources for specific usage

3. RSS context creation

4. RTC timer capabilities and clock resources query and its configuration for [3]

5. RDMA device resources

6. May be more.

[2] https://lists.oasis-open.org/archives/virtio-comment/202312/msg00110.html
[3] https://lists.oasis-open.org/archives/virtio-comment/202312/msg00112.html

Patch summary:
==============
Patches 1 to 6 cover capabilities and resources.

patch-1 adds self group for admin commands
patch-2 adds new status codes for admin commands
patch-3 adds theory of operation for capabilities
patch-4 adds capabilities admin commands
patch-5 adds theory of operation for resources
patch-6 adds resources admin commands

Patches 7 to 11 uses capabilities and resources to introduce flow filters.

patch-7 adds theory of operation for flow filter patch-8 adds device capabilities
patch-9 adds flow filter group resource
patch-10 adds flow filter rule resource, match keys, actions patch-11 adds flow filter device and driver requirements

patch-12 clarifies the newdevice section
patch-13 describes the use of capabilities and resource extension

Please review.

Changelog:
==========
v7->v8:
- updated commit messages
- updated newdevice.tex for more Q&A around capabilities, resources, administration queues
- updated resource text as non data path operations
v6->v7:
- fixed plenty of grammar suggestions from Cornelia
- introduced device/driver capabilities and device resources generic framework
- rebased flow filter to use capabilities and resources
v5->v6:
- pick next unique bit 65 as to avoid conflict with rss context feature
- fixed missing conformance links
- removed white spaces at end of line
v3->v5:
- removed left over dependencies of flow filter virtqueues
- removed partial sentence
v2->v3:
- removed dependency on dynamic queue infrastucture which is
not yet ready
v1->v2:
- addressed comments from Satananda
- squashed with match fields definition patch of v1
- added length to the flexible array definition struct to benefit from future runtime length bound checkers listed in
https://people.kernel.org/kees/bounded-flexible-arrays-in-c
- renamed value to key
- addressed comments from Satananda
- merged destination and action to one struct
- added vlan type match field
- kept space for types between l2, l3, l4 header match types
- renamed mask to mask_supported with shorter width
- made more fields reserved for future
- addressed comments from Heng
- grammar correction
- added field to indicate supported number of actions per flow filter match entry
- added missing documentation for max_flow_priorities_per_group
- fixed comments from Heng
- grammar corrections
- spelling corrections
- fixed spelling from initializaton to initialization
- added more requirements for multiple actions

v0->v1:
- addressed comments from Satananda
- added device requirement to return non zero value in fields_bmap
- added device requirement to not repeat filter type in response
- added driver requirement to order filter match field as it appears in the packet
- added device requirement to fail group delete command on existing flow entries
- added mask field in the type to indicate supported mask by device and also in later patch to use it to indicate mask on adding flow filter. As a result removed the mask_supported capability field

Parav Pandit (13):
admin: Introduce self group
admin: Add more admin command status error codes
capabilities: Add theory of operation for capabilities
admin-cmds-capabilities: Add capabilities admin commands
resources: Add theory of operation for device resources
admin-cmds-resources: Add device resources admin commands
virtio-net: Add theory of operation for flow filter
virtio-net: Add flow filter capabilities
virtio-net: Add flow filter group resource
virtio-net: Add flow filter rule resource
virtio-net: Add flow filter device and driver requirements
newdevice: Improve the appendix chapter heading to reflect the content
newdevice: Extend informative guidance on capabilities, resources

 admin-cmds-capabilities.tex             | 161 +++++++
 admin-cmds-resources.tex                | 186 ++++++++
 admin.tex                               |  34 +-
 capabilities.tex                        |  43 ++
 conformance.tex                         |   4 +
 content.tex                             |   2 +
 device-types/net/description.tex        | 587 ++++++++++++++++++++++++
 device-types/net/device-conformance.tex |   1 +
 device-types/net/driver-conformance.tex |   1 +
 newdevice.tex                           |  70 ++-
 resources.tex                           |  74 +++
 11 files changed, 1151 insertions(+), 12 deletions(-)
 create mode 100644 admin-cmds-capabilities.tex
 create mode 100644 admin-cmds-resources.tex
 create mode 100644 capabilities.tex
 create mode 100644 resources.tex
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#1 lore raw

PATCH v8 1/13 admin: Introduce self group

Define self group to control the self device itself.

Subsequent patches introduces the concept of device capabilities and device resources which utilizes the self group to access capabilities and uses device resources to refer to the device itself.

---
 admin.tex | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)
admin.tex +7 -1
index 0803c26..00784b3 100644
@@ -1,7 +1,7 @@
 \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 or self control. Terminology used in such cases:
 
 \begin{description}
 \item[Device group]
@@ -37,6 +37,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 refers to the device itself.
+The member identifier for this group has a value of 0x0. This group type
+is used by the driver to control the device itself.
+
 \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 +83,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
          */
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#2 lore raw

PATCH v8 2/13 admin: Add more admin command status error codes

In reply to Parav Pandit

Add more error code values to be used by new administration commands in subsequent patches.

---
 admin.tex | 8 ++++++++
 1 file changed, 8 insertions(+)
admin.tex +8 -0
index 00784b3..fdf25c5 100644
@@ -159,12 +159,20 @@ \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 resource or address present \\
+\hline
 11   & VIRTIO_ADMIN_STATUS_EAGAIN    & try again \\
 \hline
 12   & VIRTIO_ADMIN_STATUS_ENOMEM    & insufficient resources \\
 \hline
+16   & VIRTIO_ADMIN_STATUS_EBUSY     & device or resource busy \\
+\hline
+17   & VIRTIO_ADMIN_STATUS_EEXIST    & device or resource exists \\
+\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}
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#3 lore raw

PATCH v8 3/13 capabilities: Add theory of operation for capabilities

In reply to Parav Pandit

Device capabilities indicate supported functionalities and resources of the device to the driver.

Driver capabilities indicate functionalities and resources which driver will be using. Driver capabilities are subset of the device capabilities.

Add theory of operation describing it.

---
 capabilities.tex | 40 ++++++++++++++++++++++++++++++++++++++++
 content.tex      |  1 +
 2 files changed, 41 insertions(+)
 create mode 100644 capabilities.tex
capabilities.tex new file +40 -0
new file mode 100644
index 0000000..c375089
@@ -0,0 +1,40 @@
+\section{Device and Driver Capabilities}\label{sec:Basic Facilities of a Virtio Device / Device and Driver Capabilities}
+
+Device capabilities indicate supported functionalities and
+resources of the device. Each device capability is identified by its
+unique identifier.The driver uses the administration command to read
+the device capabilities. The device indicates supported capabilities to the
+driver as a bitmap of identifiers. The driver uses the administration command
+to read the supported capabilities bitmap.
+
+The driver writes the capabilities in the device before performing any operation
+related to the capabilities. The driver uses the administration command to write
+the driver capabilities thereby either enable or disable a certain
+device functionality. The driver can write the capabilities at any time
+as long as there is no pending operation in progress at the device level related
+to the capability.
+
+For a defined device capability identifier, the device capability fields do not
+grow. A new capability should be added with a new identifier when a adding a
+device functionality or when extending the existing device functionality.
+This ensures backward and forward compatibility between the driver and the
+device as well as logical separation of related capabilities.
+
+The device capabilities are divided into two ranges by the identifiers
+as listed:
+
+\begin{tabularx}{\textwidth}{ |l|X| }
+\hline
+Identifier & Description  \\
+\hline \hline
+0x0000-0x07ff & Generic capabilities for all device types \\
+\hline
+0x0800-0x0fff & Device type specific capabilities \\
+\hline
+0x1000 - 0xFFFF & Reserved for future \\
+\hline
+\end{tabularx}
+
+Whichever device supports the device specific capabilities, such
+capabilities are described in the respective \field{Device and Driver Capabilities}
+section of the device.
content.tex +1 -0
index 98b9c31..4938fc0 100644
@@ -502,6 +502,7 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo
 types. It is RECOMMENDED that devices generate version 4
 UUIDs as specified by \hyperref[intro:rfc4122]{[RFC4122]}.
 
+\input{capabilities.tex}
 \input{admin.tex}
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#4 lore raw

PATCH v8 4/13 admin-cmds-capabilities: Add capabilities admin commands

In reply to Parav Pandit

Add three capabilities related commands.
First to read the device and driver capabilities. Second to write the driver capabilities.
Third for driver to discover which capabilities can be accessed.

Write capabilities by the owner driver is not currently supported. It will be supported in future by the owner driver to write for the member device.

---
 admin-cmds-capabilities.tex | 161 ++++++++++++++++++++++++++++++++++++
 admin.tex                   |   9 +-
 capabilities.tex            |   3 +
 conformance.tex             |   2 +
 4 files changed, 174 insertions(+), 1 deletion(-)
 create mode 100644 admin-cmds-capabilities.tex
admin-cmds-capabilities.tex new file +161 -0
new file mode 100644
index 0000000..47394c7
@@ -0,0 +1,161 @@
+\subsubsection{Device and Driver Capabilities}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}
+
+The device and driver capabilities commands are currently defined for self group type and for
+SR-IOV group type.
+
+\begin{enumerate}
+\item Device Capabilities Support Query Command
+\item Capabilities Read Command
+\item Capabilities Write Command
+\end{enumerate}
+
+\paragraph{Device Capabilities Support Query Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities / Device Capabilities Support Query Command}
+
+For the command VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY, \field{opcode} is set to 0x7.
+
+This command queries the supported device capabilities identifiers bitmap in
+\field{supported_caps}. Each bit in \field{supported_caps} corresponds to the
+capability identifier. Thus, supported_caps[0] refers to the first 64-bit value
+in this array corresponding to identifiers 0 to 63, supported_caps[1]
+is the second 64-bit value corresponding to identifiers 64 to 127, etc.
+For example, with \field{num_caps = 2}, the array of size 2 including the values
+0x3 in supported_caps[0], and 0x1 in supported_caps[1] indicates that only 
+identifiers 0, 1 and 64 are supported.
+
+The length of the array \field{supported_caps} depends on the supported
+identifiers - it is large enough to include bits set for all supported
+identifiers, that is the length is set by calculating by starting with the
+largest supported opcode adding one, dividing by 64 and rounding up.
+
+The array \field{supported_caps} is also allowed to be larger and to
+additionally include an arbitrary number of all-zero entries.
+
+For each identifier, the driver can read the device capabilities and write
+the driver capabilities. The driver can also read the written capabilities.
+
+This command has no command specific data.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_query_supported_cap_result {
+        le16 num_caps;
+        u8 reserved[6];
+        le64 supported_caps[];
+};
+\end{lstlisting}
+
+When the command completes successfully, \field{command_specific_result}
+is in the format \field{struct virtio_admin_cmd_query_supported_cap_result}
+returned by the device. The number of valid array entries of
+\field{supported_caps} are indicated in \field{num_caps}.
+
+\paragraph{Capabilities Read Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities / Capabilities Read Command}
+
+This command reads the device or driver capabilities. It either reads the
+capability of the own device or the owner device can read the capabilities of
+the member device.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_read_data {
+        le16 cid;
+        u8 type; /* 0 = device cap, 1 = driver cap */
+        u8 reserved[5];
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_CAP_READ, \field{opcode} is set to 0x8.
+
+\field{group_member_id} refers to the device itself or the member device to be accessed.
+\field{cid} refers to the capability identifier listed in
+\ref{sec:Basic Facilities of a Virtio Device / Device and Driver Capabilities}.
+When \field{type} is set to 0, it refers to the device capability, when
+\field{type} is set to 1, it refers to the driver capability, rest of the
+values are reserved.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_read_result {
+        le16 length;
+        u8 reserved[6];
+        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_read_result} responded
+by the device. The \field{length} is set to the length of the
+\field{cap_specific_data}. Each capability uses different capability specific
+\field{cap_specific_data} and is described separately.
+
+\paragraph{Capabilities Write Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities / Capabilities Write Command}
+
+This command writes the driver capabilities indicating to the device which
+capabilities are used by the driver. The driver can write capabilities which
+are smaller or equal in value than the values published by the device
+capabilities.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_cap_write_data {
+        le16 cid;
+        u8 type; /* 1 = driver cap */
+        u8 reserved;
+        le16 length;
+        u8 reserved1[2];
+        u8 cap_specific_data[];
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_CAP_WRITE, \field{opcode} is set to 0x9.
+
+\field{group_member_id} refers to the the device itself. Currently the owner
+device cannot write the member device's capabilities. This will be supported
+in the future.
+\field{cid} refers to the capability identifier listed in
+\ref{sec:Basic Facilities of a Virtio Device / Device and Driver Capabilities}.
+\field{type} is set to 1, refers to the driver capability, when
+\field{length} refers to the length of the \field{cap_specific_data}.
+
+There is no command specific result.
+When the command completes successfully the driver capabilities are
+updated to 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
+VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY, VIRTIO_ADMIN_CMD_CAP_WRITE and
+VIRTIO_ADMIN_CMD_CAP_READ commands.
+
+The device MUST support writing all the driver capabilities in
+VIRTIO_ADMIN_CMD_CAP_WRITE command to same or smaller value than what is reported
+in device capabilities in VIRTIO_ADMIN_CMD_CAP_READ command unless
+otherwise explicitly stated capability fields as non writeable fields.
+
+In VIRTIO_ADMIN_CMD_CAP_WRITE command, if any of the written capability
+field value is larger than the value reported by the device capability,
+the device MUST complete VIRTIO_ADMIN_CMD_CAP_WRITE command with \field{status}
+VIRTIO_ADMIN_STATUS_EINVAL.
+
+The device MUST support VIRTIO_ADMIN_CMD_CAP_READ command for the owner
+device to read capabilities for the member device.
+
+The device MUST complete VIRTIO_ADMIN_CMD_CAP_WRITE command with
+\field{status} VIRTIO_ADMIN_STATUS_EINVAL for the owner device to
+write the capabilities of the member device.
+
+The device MUST complete VIRTIO_ADMIN_CMD_CAP_WRITE command with \field{status}
+VIRTIO_ADMIN_STATUS_EBUSY if the command requested to disable a capability and
+the device has any valid resources related to the capability being disabled.
+
+On device reset, the device MUST reset all the driver capabilities.
+
+\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 VIRTIO_ADMIN_CMD_CAP_WRITE command before using
+any resources related to such capabilities.
+
+The driver SHOULD NOT send VIRTIO_ADMIN_CMD_CAP_WRITE command
+containing values which is larger than
+the device capabilities reported by the device in
+VIRTIO_ADMIN_CMD_CAP_READ command.
+
+The driver SHOULD NOT disable any of the driver capabilities by sending
+VIRTIO_ADMIN_CMD_CAP_WRITE command when any functionality related
+to such capabilities is in use by the device.
admin.tex +8 -1
index fdf25c5..c0ba54e 100644
@@ -133,7 +133,13 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
 \hline
 0x0006 & VIRTIO_ADMIN_CMD_LEGACY_NOTIFY_INFO & Query the notification region information \\
 \hline
-0x0007 - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
+0x0007 & VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY & Query the supported device capabilities bitmap \\
+\hline
+0x0008 & VIRTIO_ADMIN_CMD_CAP_READ & Read the device and driver capabilities \\
+\hline
+0x0009 & VIRTIO_ADMIN_CMD_CAP_WRITE & Write the device and driver capabilities \\
+\hline
+0x000a - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
 \hline
 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure)    \\
 \hline
@@ -311,6 +317,7 @@ \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}
 
 \devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands}
 
capabilities.tex +3 -0
index c375089..77d4aa5 100644
@@ -38,3 +38,6 @@ \section{Device and Driver Capabilities}\label{sec:Basic Facilities of a Virtio
 Whichever device supports the device specific capabilities, such
 capabilities are described in the respective \field{Device and Driver Capabilities}
 section of the device.
+
+Device and driver capabilities related administration commands are listed in
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and Driver Capabilities}.
conformance.tex +2 -0
index 863f9c5..4782016 100644
@@ -95,6 +95,7 @@ \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}
 \end{itemize}
 
 \conformance{\subsection}{PCI Driver Conformance}\label{sec:Conformance / Driver Conformance / PCI Driver Conformance}
@@ -175,6 +176,7 @@ \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}
 \end{itemize}
 
 \conformance{\subsection}{PCI Device Conformance}\label{sec:Conformance / Device Conformance / PCI Device Conformance}
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#5 lore raw

PATCH v8 5/13 resources: Add theory of operation for device resources

In reply to Parav Pandit

The device may support device operation by means of resources. The driver creates the device resources and operates the device in a certain way.

These operations include create, query, modify, and destroy the device resources.

---
changelog:
v7->v8:
- added text about administration commands execution rate behavior

---
 content.tex   |  1 +
 resources.tex | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 resources.tex
content.tex +1 -0
index 4938fc0..33d7169 100644
@@ -503,6 +503,7 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo
 UUIDs as specified by \hyperref[intro:rfc4122]{[RFC4122]}.
 
 \input{capabilities.tex}
+\input{resources.tex}
 \input{admin.tex}
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
resources.tex new file +70 -0

70 lines not on this page · raw message

Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#6 lore raw

PATCH v8 6/13 admin-cmds-resources: Add device resources admin commands

In reply to Parav Pandit

Add generic administration commands create, modify, query and destroy device resources.

Each resource defines resource specific attributes for the commands. Once the resource is created by the driver, it can be query/modify or destroyed by the driver.

Each resource is identified using a unique resource identifier per resource type.

Administration commands for managing resources using administration commands are relatively slower operations compared to data path operations of transmitq and receiveq of the network device.

---
 admin-cmds-resources.tex | 186 +++++++++++++++++++++++++++++++++++++++
 admin.tex                |  11 ++-
 conformance.tex          |   2 +
 resources.tex            |   4 +
 4 files changed, 202 insertions(+), 1 deletion(-)
 create mode 100644 admin-cmds-resources.tex
admin-cmds-resources.tex new file +186 -0
new file mode 100644
index 0000000..da4e576
@@ -0,0 +1,186 @@
+\subsubsection{Device Resources}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
+
+The device resource operates the device as described in
+\ref{sec:Basic Facilities of a Virtio Device / Device Resources}.
+
+Following device resource commands are currently defined only for the self
+group type:
+
+\begin{enumerate}
+\item Device Resource Create Command
+\item Device Resource Modify Command
+\item Device Resource Query Command
+\item Device Resource Destroy Command
+\end{enumerate}
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_cmd_hdr {
+        le16 type;
+        u8 reserved[2];
+        le32 rid; /* Indicates unique resource id per resource type */
+};
+\end{lstlisting}
+
+\field{type} refers to the device resource type.
+\field{rid} uniquely identifies the resource of a specified \field{type}.
+
+\paragraph{Device Resource Create Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources / Device Resource Create Command}
+
+This command creates the specified resource of \field{type} identified by the
+resource identifier \field{rid}. The valid range of \field{rid} is defined by the
+device in the related device capabilities. The driver assigns the unique \field{rid}
+for the resource for the specified \field{type}.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_create_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+        le16 length;
+        u8 reserved[6];
+        u8 resource_specific_data[];
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_CREATE, \field{opcode} is set to 0xa.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{length} refers to the length of the \field{resource_specific_data}.
+\field{resource_specific_data} refers to the resource specific data. Each resource
+uses a different \field{resource_specific_data} and is described separately.
+
+When the command completes successfully, the resource is created in the
+device and in use by the device. This command has no command specific result.
+
+\paragraph{Device Resource Modify Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources / Device Resource Modify Command}
+
+This command modifies the existing resource of \field{type} identified
+by \field{rid}, which is previously created using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_modify_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+        le16 length;
+        le16 reserved[6];
+        u8 resource_specific_data[];
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, \field{opcode} is set to 0xb.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{type} refers to the device resource type.
+\field{rid} uniquely identifies the resource of type \field{type} to be created.
+\field{length} refers to the length of the \field{data}.
+
+When the command completes successfully, the resource is modified with
+updated \field{resource_specific_data}.
+This command has no command specific result.
+
+\paragraph{Device Resource Query Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group
+administration commands / Device Resources / Device Resource Query Command}
+
+This command reads the existing resource of \field{type} identified
+by \field{rid}, which is previously created using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_read_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+};
+\end{lstlisting}
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_read_result {
+        le16 length;
+        le16 reserved[6];
+        u8 resource_specific_data[];
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_QUERY, \field{opcode} is set to 0xc.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{type} refers to the device resource type.
+\field{rid} identifies the existing resource of type \field{type}.
+\field{length} refers to the length of the \field{data}.
+
+When the command completes successfully, the resource information is returned
+to the driver in \field{resource_specific_data}.
+
+\paragraph{Device Resource Remove Command}\label{par:Basic Facilities of a Virtio Device / Device groups / Group
+administration commands / Device Resources / Device Resource Destroy Command}
+
+This command reads the specified resource of \field{type} identified
+by \field{rid}, which is previously created using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE.
+
+\begin{lstlisting}
+struct virtio_admin_cmd_resource_destroy_data {
+        struct virtio_admin_cmd_resource_cmd_hdr hdr;
+};
+\end{lstlisting}
+
+For the command VIRTIO_ADMIN_CMD_RESOURCE_DESTROY, \field{opcode} is set to 0xd.
+
+\field{group_member_id} refers to the device itself to be accessed.
+\field{type} refers to the device resource type.
+\field{rid} identifies the existing resource of type \field{type} to be destroyd.
+
+When the command completes successfully, the resource is destroyd from the device.
+This command has no command specific result.
+
+\devicenormative{\paragraph}{Device Resources}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
+
+The device MUST set VIRTIO_ADMIN_STATUS_EEXIST for the command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE if a resource already exists with supplied
+resource \field{rid} for the specified \field{type}.
+
+The device MUST complete the command with status \field{status}
+VIRTIO_ADMIN_STATUS_ENXIO for the commands
+VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_QUERY and
+VIRTIO_ADMIN_CMD_RESOURCE_DESTROY if the specified resource does not exist.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE if the device fail to create the
+resource.
+
+The device MUST complete the command with \field{status}
+VIRTIO_ADMIN_STATUS_EBUSY if the resource
+modified or destroyd is linked to other resource and if the device cannot perform
+the requested VIRTIO_ADMIN_CMD_RESOURCE_MODIFY or VIRTIO_ADMIN_CMD_RESOURCE_DESTROY
+commands.
+
+The device MUST allow recreating the resource using
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE command which was previously created
+and destroyed using VIRTIO_ADMIN_CMD_RESOURCE_CREATE and
+VIRTIO_ADMIN_CMD_RESOURCE_DESTROY command respectively without undergoing
+a device reset.
+
+The device MUST allow creating the resource using
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE command with any resource
+identifier as long as the resource does not exist and if the resource
+identifier is less than the device and driver capabilities published resource
+limit \field{max_limit}.
+
+The device MAY fail VIRTIO_ADMIN_CMD_RESOURCE_CREATE command even if the
+resources within the device have not reached upto the \field{max_limit}
+but the device MAY have reached an internal limit.
+
+On device reset, the device MUST destroy all the resources which driver MAY
+have created.
+
+\drivernormative{\paragraph}{Device Resources}{Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}
+
+The driver SHOULD NOT create the resource with the \field{rid} which is
+already created previously by the driver.
+
+The driver SHOULD NOT create the resource using command
+VIRTIO_ADMIN_CMD_RESOURCE_CREATE when maximum resource limit has reached.
+
+The driver SHOULD NOT modify, read and destroy the resource which is
+already destroyd previously by the driver.
+
+The driver MUST NOT destroy the resource which is in use by other
+linked resource; the driver MUST destroy all the linked resources before
+removing the resource which is used by the linked resources by using
+command VIRTIO_ADMIN_CMD_RESOURCE_DESTROY.
admin.tex +10 -1
index c0ba54e..aa4ff59 100644
@@ -139,7 +139,15 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
 \hline
 0x0009 & VIRTIO_ADMIN_CMD_CAP_WRITE & Write the device and driver capabilities \\
 \hline
-0x000a - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
+0x000a & VIRTIO_ADMIN_CMD_RESOURCE_CREATE & Create a device resource \\
+\hline
+0x000c & VIRTIO_ADMIN_CMD_RESOURCE_MODIFY & Modify a device resource \\
+\hline
+0x000b & VIRTIO_ADMIN_CMD_RESOURCE_QUERY & Query a device resource \\
+\hline
+0x000d & VIRTIO_ADMIN_CMD_RESOURCE_DESTROY & Destroy a device resource \\
+\hline
+0x000e - 0x7FFF & - & Commands using \field{struct virtio_admin_cmd}    \\
 \hline
 0x8000 - 0xFFFF & - & Reserved for future commands (possibly using a different structure)    \\
 \hline
@@ -318,6 +326,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
 
 \input{admin-cmds-legacy-interface.tex}
 \input{admin-cmds-capabilities.tex}
+\input{admin-cmds-resources.tex}
 
 \devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands}
 
conformance.tex +2 -0
index 4782016..fbf63e3 100644
@@ -96,6 +96,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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 Resources}
 \end{itemize}
 
 \conformance{\subsection}{PCI Driver Conformance}\label{sec:Conformance / Driver Conformance / PCI Driver Conformance}
@@ -177,6 +178,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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 Resources}
 \end{itemize}
 
 \conformance{\subsection}{PCI Device Conformance}\label{sec:Conformance / Device Conformance / PCI Device Conformance}
resources.tex +4 -0
index 307308c..4b0efb6 100644
@@ -9,6 +9,10 @@ \section{Device Resources}\label{sec:Basic Facilities of a Virtio Device / Devic
 sends the device resource related administration commands, thereby
 instructing the device to operate in a certain way.
 
+The device supports resource control using the administration commands
+described in
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}.
+
 Each device resource is identified by a unique resource identifier. The driver
 assigns the resource identifier when creating a device resource. Once the resource
 successfully created, subsequent operations of modifying, querying or destroying
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#7 lore raw

PATCH v8 7/13 virtio-net: Add theory of operation for flow filter

In reply to Parav Pandit

Currently packet allow/drop interface has following limitations.

1. Driver can either select which MAC and VLANs to consider for allowing/dropping packets, here, the driver has a limitation that driver needs to supply full mac table or full vlan table for each type. Driver cannot add or delete an individual entry.

2. Driver cannot select mac+vlan combination for which to allow/drop packet.

3. Driver cannot not set other commonly used packet match fields such as IP header fields, TCP, UDP, SCP header fields.

4. Driver cannot steer specific packets based on the match fields to specific receiveq.

5. Driver do not have multiple or dedicated virtqueues to perform flow filter requests in accelerated manner in the device.

Flow filter as a generic framework overcome above limitations.

As starting point it is useful to support at least two use cases. a. ARFS
b. ethtool ntuple steering

In future it can be further extended for usecases such as switching device, connection tracking or may be more.

The flow filter has following properties.

1. It is an extendible object that driver can create, destroy.
2. It belongs to a flow filter group (group has priority).
3. Each flow filter is identified using a unique identifier(id), has priority, match fields, destination(rq) and action(allow/drop).
4. Flow filter has optionally mask too.

This patch adds theory of operation for flow filter functionality.

---
changelog:
v6->v7:
- addressed comments from Cornelia
- plenty of grammar corrections suggested by Cornelia
- removed stale reference to flow filter virtqueue
- removed incorrect stale hunk of a label
- removed dependency on feature bit and control vq
- rebased to use device capabilities and device resources v4->v5:
- to avoid feature bit overlap with rss context patch, pick next unique bit 65
v3->v4:
- removed flow filter virtqueue section as dynamic queues are not supported currently
v2->v3:
- removed dependency on the dynamic queue creation as the infrastructure is not yet ready
v1->v2:
- fixed comments from Heng
- grammar corrections
- spelling corrections

---
 device-types/net/description.tex | 79 ++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
device-types/net/description.tex +79 -0
index 0cc03fc..407139b 100644
@@ -2325,6 +2325,85 @@ \subsubsection{Control Virtqueue}\label{sec:Device Types / Network Device / Devi
 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}
+
+To forward a received packet to a specific receiveq or to drop the packet based
+on one or more fields of the packet, the device supports flow filter
+functionality. The flow filter rule can match the packet for a flow, take
+an action such as forward the packet to the specific receiveq or drop the packet.
+For example, the driver can request the device to forward received packets
+which match to a specific source and destination IP addresses and
+TCP ports to a specific receiveq.
+
+Each flow filter rule is a combination of one or more match keys,
+rule processing priority, a rule identifier and an action to forward
+a packet to the destination or to drop the packet.
+
+The match fields also optionally consist of a match mask. When a mask is
+specified for the flow filter rule, first the packet fields are masked before
+matching with the fields of the flow filter rule.
+
+Each flow filter rule is independent of each other. The driver can create,
+modify, query and destroy a flow filter rule. A flow filter rule is
+a device resource that the driver can operate using device resource
+administration commands described in
+\ref{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device Resources}.
+
+The device indicates the flow filter capabilities to the driver. These
+capabilities include various maximum device limits and
+supported packet match fields.
+
+Flow filter rules are grouped using a flow filter group. A flow filter
+group is a device resource. Each flow filter group has a priority.
+The device first applies the flow filter rules of the highest
+priority group to the received packet. If there is no match for the
+rules of such a group for the packet, the rules of the next
+priority group are applied, until there is a match for the packet from such
+a group or the last group has reached.
+
+A flow filter group can have one or more flow filters rules. Within a flow
+filter group, a packet may match to multiple flow filters rules. In such a scenario,
+of the matching flow filters rules, the rule with the highest priority is applied,
+skipping any matching filter rules with a lower priority; if there is no match,
+the next higher priority flow filter rule is applied.
+
+\paragraph{Packet Processing Order}\label{sec:sec:Device Types / Network Device / Device Operation / Flow Filter / Packet Processing Order}
+
+If enabled, filtering and steering functionalities are applied to the received
+packet in the following order:
+
+\begin{itemize}
+\item apply device configuration done using control virtqueue commands
+      VIRTIO_NET_CTRL_RX, VIRTIO_NET_CTRL_MAC and VIRTIO_NET_CTRL_VLAN.
+\item apply flow filter configuration done using flow filter rules.
+\item apply device configuration done using command
+      VIRTIO_NET_CTRL_MQ_RSS_CONFIG.
+\end{itemize}
+
+While processing a received packet, if the packet is dropped at any stage,
+the following levels of processing is omitted.
+
+If a flow filter rule is matched for the packet, the following levels of
+processing are omitted as well.
+
+A few examples are:
+\begin{itemize}
+\item If the packet is dropped by the flow filter configuration, RSS
+      configuration is not applied to such a packet.
+\item If the packet is forwarded to a specific receiveq using flow filter rule,
+      RSS configuration is not applied to such a packet due to a match on the
+      flow filter rule.
+\item If the packet is dropped due to VIRTIO_NET_CTRL_MAC configuration,
+      neither flow filters nor RSS configuration are applied to such a packet.
+\item If the packet does not find any match in any of the flow filter groups,
+      next level RSS device configuration is applied if its exists.
+\item If there are three flow filter groups configured as group_A, group_B
+      and group_C with respective priorities as 4, 5, and 6; flow filters of
+      group_C is applied first having highest group priority, if there is a match,
+      the flow filter rules of group_B and group_A are skipped; if there is no match for
+      the flow filter rules in group_C, the flow filter rules of next level group_B are applied.
+\end{itemize}
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#8 lore raw

PATCH v8 8/13 virtio-net: Add flow filter capabilities

In reply to Parav Pandit

Add flow filter capabilities, the first one indicates device limits such as number of flow filters, number of flow filter groups, support or multiple transports etc.

The second capability indicates supported match types, and fields of the packet.

---
changelog:
v6->v7:
- plenty of grammar corrections suggested by Cornelia
- using generic device capabilities framework
- renamed max_flow_priorities_per_group to max_ff_rules_priorities_per_group to make it more clear
v2->v3:
- rebased on virtio-1.4 branch
- removed reference for flow filter virtqueue
v1->v2:
- addressed comments from Satananda
- added vlan type match field
- kept space for types between l2, l3, l4 header match types
- renamed mask to mask_supported with shorter width
- made more fields reserved for future
- addressed comments from Heng
- grammar correction
- added field to indicate supported number of actions per flow filter match entry
- added missing documentation for max_flow_priorities_per_group v0->v1:
- added mask field in the type to indicate supported mask by device and also in later patch to use it to indicate mask on adding flow filter. As a result removed the mask_supported capability field

---
 device-types/net/description.tex | 205 ++++++++++++++++++++++++++++++-
 1 file changed, 204 insertions(+), 1 deletion(-)
device-types/net/description.tex +204 -1
index 407139b..efe363b 100644
@@ -398,6 +398,88 @@ \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}
+
+\begin{tabularx}{\textwidth}{ |l||l|X| }
+\hline
+Identifier & Name & Description \\
+\hline \hline
+0x0800 & VIRTIO_NET_FF_RESOURCE_CAP & Provides Flow filter resources capabilities \\
+\hline
+0x0801 & VIRTIO_NET_FF_MATCH_CAP & Provide Flow filter match capabilities \\
+\hline
+\end{tabularx}
+
+\subsubsection{Flow Filter Resources Capabilities}\label{sec:Device Types / Network Device / Device Capabilities / Flow Filter Resources Capabilities}
+\label{sec:Device Types / Network Device / Device Capabilities / Flow Filter Resources Capabilities}
+
+VIRTIO_NET_FF_RESOURCE_CAP capability indicates various flow filter resource limits.
+
+\begin{lstlisting}
+struct virtio_net_ff_resource_cap_data {
+        struct virtio_resource_limit groups;
+        struct virtio_resource_limit rules;
+        le16 max_match_fields;
+        le16 max_actions;
+        u8 max_rules_priorities_per_group;
+};
+\end{lstlisting}
+
+\field{cap_specific_data} for VIRTIO_NET_FF_RESOURCE_CAP is in format of
+\field{struct virtio_net_ff_resource_cap_data}.
+
+\field{groups} indicates maximum number of flow filter groups.
+
+\field{rules} indicates the maximum number of flow filter rules
+across all the flow filter groups.
+
+\field{max_match_fields} indicates maximum number of fields of a packet
+which can be matched by the device in a flow filter rule.
+
+\field{max_actions} indicates maximum number of actions per flow filter
+rule.
+
+A flow filter rule within a group can have any
+priority in range of zero to \field{max_rules_priorities_per_group - 1}.
+
+\subsubsection{Flow Filter Match Capabilities}\label{sec:Device Types / Network Device / Device Capabilities / Flow Filter Match Capabilities}
+\label{sec:Device Types / Network Device / Device Capabilities / Flow Filter Match Capabilities}
+
+VIRTIO_NET_FF_MATCH_CAP capability indicates which fields of the packet can be
+matched.
+
+\begin{lstlisting}
+struct virtio_net_ff_match_type_cap {
+        le16 type;
+        u8 mask_supported;
+        u8 reserved[5];
+        le64 fields_bmap;
+};
+
+struct virtio_net_ff_match_types_cap_data {
+        le32 num_types;
+        struct virtio_net_ff_match_type_cap types[];
+};
+\end{lstlisting}
+
+\field{cap_specific_data} for VIRTIO_NET_FF_RESOURCE_CAP is in format of
+\field{struct virtio_net_ff_match_types_cap_data}.
+
+For each \field{type}, supported match fields are listed in
+\ref{par:Device Types / Network Device / Device Operation / Flow Filter / Match Types and Keys}.
+
+\field{mask_supported} indicates if for a given \field{type} if the filter mask
+is supported or not.
+
+\field{num_types} indicates the length of the array \field{types}.
+Each array entry of \field{types} represents the fields of the packet
+which are supported for matching by the device.
+
+Each array entry of \field{types} represents packet match fields.
+
+For each \field{type} the \field{fields_bmap} indicates supported fields
+of the packet header which can be matched.
+
 \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation}
 
 Packets are transmitted by placing them in the
@@ -2351,7 +2433,10 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 
 The device indicates the flow filter capabilities to the driver. These
 capabilities include various maximum device limits and
-supported packet match fields.
+supported packet match fields. These capabilities are:
+\ref{sec:Device Types / Network Device / Device Capabilities / Flow Filter Resources Capabilities}
+and
+\ref{sec:Device Types / Network Device / Device Capabilities / Flow Filter Match Capabilities}.
 
 Flow filter rules are grouped using a flow filter group. A flow filter
 group is a device resource. Each flow filter group has a priority.
@@ -2404,6 +2489,124 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
       the flow filter rules in group_C, the flow filter rules of next level group_B are applied.
 \end{itemize}
 
+\paragraph{Match Types and Keys}\label{par:Device Types / Network Device / Device Operation / Flow Filter / Match Types and Keys}
+
+The \field{type} for \field{struct virtio_net_ff_match_type_cap} corresponds to following table:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Type & Name & Description \\
+\hline \hline
+0   & VIRTIO_NET_FF_ETH_HDR & Ethernet header of the packet \\
+\hline
+0x1   & VIRTIO_NET_FF_VLAN_TAG_HDR & VLAN tag of the packet \\
+\hline
+0x200   & VIRTIO_NET_FF_IPV4_HDR & IPv4 header of the packet \\
+\hline
+0x300   & VIRTIO_NET_FF_IPV6_HDR & IPv6 header of the packet \\
+\hline
+0x400   & VIRTIO_NET_FF_TCP_HDR & TCP header of the packet \\
+\hline
+0x500   & VIRTIO_NET_FF_UDP_HDR & UDP header of the packet \\
+\hline
+other   & -    & reserved \\
+\hline
+\end{tabular}
+
+When \field{mask_supported} is set, for the specific \field{type}, the
+device can mask packet fields with the mask supplied in the flow
+filter match entry.
+
+For the \field{type} of VIRTIO_NET_FF_ETH_HDR, header fields
+are represented by a bitmap in \field{fields_bmap} as follows:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Bit & Name & Description \\
+\hline \hline
+0   & VIRTIO_NET_FF_DST_MAC & Destination MAC address in the packet \\
+\hline
+1   & VIRTIO_NET_FF_SRC_MAC & Source MAC address in the packet \\
+\hline
+2   & VIRTIO_NET_FF_ETHER_TYPE & Ether type in the packet \\
+\hline
+other   & -    & reserved \\
+\hline
+\end{tabular}
+
+For the \field{type} of VIRTIO_NET_FF_VLAN_TAG_HDR, VLAN tag fields
+are represented by a bitmap in \field{fields_bmap} as follows:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Bit & Name & Description \\
+\hline \hline
+0   & VIRTIO_NET_FF_VLAN_TAG_TCI & Vlan tag TCI 16-bit field \\
+\hline
+other   & -    & reserved \\
+\hline
+\end{tabular}
+
+For the \field{type} of VIRTIO_NET_FF_IPV4_HDR, header fields
+are represented by a bitmap in \field{fields_bmap} as follows:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Bit & Name & Description \\
+\hline \hline
+0   & VIRTIO_NET_FF_SRC_IPV4 & Source IPV4 address in the packet \\
+\hline
+1   & VIRTIO_NET_FF_DST_IPV4 & Destination IPV4 address in the packet \\
+\hline
+other   & -    & reserved \\
+\hline
+\end{tabular}
+
+For the \field{type} of VIRTIO_NET_FF_IPV6_HDR, header fields
+are represented by a bitmap in \field{fields_bmap} as follows:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Bit & Name & Description \\
+\hline \hline
+0   & VIRTIO_NET_FF_SRC_IPV6 & Source IPV6 address in the packet \\
+\hline
+1   & VIRTIO_NET_FF_DST_IPV6 & Destination IPV6 address in the packet \\
+\hline
+other   & -    & reserved \\
+\hline
+\end{tabular}
+
+For the \field{type} of VIRTIO_NET_FF_TCP_HDR, header fields
+are represented by a bitmap in \field{fields_bmap} as follows:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Bit & Name & Description \\
+\hline \hline
+0   & VIRTIO_NET_FF_SRC_TCP_PORT & Source TCP port in the packet \\
+\hline
+1   & VIRTIO_NET_FF_DST_TCP_PORT & Destination TCP port in the packet \\
+\hline
+other   & -    & reserved \\
+\hline
+\end{tabular}
+
+For the \field{type} of VIRTIO_NET_FF_UDP_HDR, header fields
+are represented by a bitmap in \field{fields_bmap} as follows:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Bit & Name & Description \\
+\hline \hline
+0   & VIRTIO_NET_FF_SRC_UDP_PORT & Source UDP port in the packet \\
+\hline
+1   & VIRTIO_NET_FF_DST_UDP_PORT & Destination UDP port in the packet \\
+\hline
+other   & -    & reserved  \\
+\hline
+\end{tabular}
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#9 lore raw

PATCH v8 9/13 virtio-net: Add flow filter group resource

In reply to Parav Pandit

A flow filter group resource holds the flow filter rules. The device can have one or more flow filter groups. Each flow filter group has its own priority. The group priority defines the packet processing order in the flow filter domain.

Add resource definition for flow filter group.

---
changelog:
v6->v7:
- addressed comments from Cornelia
- reworded the description for group delete command
- rebased the series on top of generic resource framework

---
 device-types/net/description.tex | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)
device-types/net/description.tex +22 -3
index efe363b..05979e7 100644
@@ -472,14 +472,33 @@ \subsubsection{Flow Filter Match Capabilities}\label{sec:Device Types / Network
 is supported or not.
 
 \field{num_types} indicates the length of the array \field{types}.
-Each array entry of \field{types} represents the fields of the packet
-which are supported for matching by the device.
-
 Each array entry of \field{types} represents packet match fields.
 
 For each \field{type} the \field{fields_bmap} indicates supported fields
 of the packet header which can be matched.
 
+\subsection{Device Resources}\label{sec:Device Types / Network Device / Device Resources}
+
+\begin{tabularx}{\textwidth}{ |l||l|X| }
+\hline
+type & Name & Description \\
+\hline \hline
+0x0200 & VIRTIO_NET_RESOURCE_FF_GROUP & Flow filter group \\
+\hline
+\end{tabularx}
+
+\subsubsection{Flow Filter Group}\label{sec:Device Types / Network Device / Device Resources / Flow Filter Group}
+
+For the device resource VIRTIO_NET_RESOURCE_FF_GROUP, the
+\field{resource_specific_data} is in the format of
+\field{struct virtio_net_resource_ff_group}.
+
+\begin{lstlisting}
+struct virtio_net_resource_ff_group {
+        le16 priority;	/* higher priority groups are processed first */
+};
+\end{lstlisting}
+
 \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation}
 
 Packets are transmitted by placing them in the
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#10 lore raw

PATCH v8 10/13 virtio-net: Add flow filter rule resource

In reply to Parav Pandit

Define flow filter rule resource consist of
one or more match key, mask entries and one or more actions.

Currently it covers the most common filter types and value of Ethernet header, IP addresses, TCP and UDP ports.

---
changelog:
v6->v7:
- plenty of grammar corrections suggested by Cornelia
- adapt to generic device resource framework
v2->v3:
- removed references to flow filter virtqueues
- removed one partial sentence
- added text for delete request
- aligned request and opcode values to just say request in the defines v1->v2:
- squashed with match fields definition patch of v1
- added length to the flexible array definition struct to benefit from future runtime length bound checkers listed in
https://people.kernel.org/kees/bounded-flexible-arrays-in-c
- renamed value to key
- addressed comments from Satananda
- merged destination and action to one struct
v0->v1:
- reworded add flow request text to consider optional mask
- replaced respond with set
- added mask flag to the type

---
 device-types/net/description.tex | 165 ++++++++++++++++++++++++++++++-
 1 file changed, 164 insertions(+), 1 deletion(-)
device-types/net/description.tex +164 -1
index 05979e7..b9d0378 100644
@@ -485,6 +485,8 @@ \subsection{Device Resources}\label{sec:Device Types / Network Device / Device R
 \hline \hline
 0x0200 & VIRTIO_NET_RESOURCE_FF_GROUP & Flow filter group \\
 \hline
+0x0201 & VIRTIO_NET_RESOURCE_FF_RULE & Flow filter rule \\
+\hline
 \end{tabularx}
 
 \subsubsection{Flow Filter Group}\label{sec:Device Types / Network Device / Device Resources / Flow Filter Group}
@@ -499,6 +501,95 @@ \subsubsection{Flow Filter Group}\label{sec:Device Types / Network Device / Devi
 };
 \end{lstlisting}
 
+\subsubsection{Flow Filter Rule}\label{sec:Device Types / Network Device / Device Resources / Flow Filter Rule}
+
+Each flow filter rule resource consist of one or more match entries and
+one or more actions. The packet is matched against one or more match
+entries of type \field{struct virtio_ff_match_entry}. When the packet
+matches to all the match entries of \field{struct virtio_ff_match_entries},
+the device applies one or more actions of \field{struct virtio_ff_actions}.
+
+\begin{lstlisting}
+struct virtio_ff_match_entry {
+        le16 type;
+        u8 key_len; /* length of key */
+        u8 mask_len; /* length of mask */
+        le64 fields_bmap;
+        u8 key[];
+        u8 mask[]; /* optional, only present when mask_len > 0 */
+};
+
+struct virtio_ff_match_entries {
+       u8 num_entries; /* indicates number of valid entries */
+       u8 reserved[7];
+       struct virtio_ff_match_entry entries[];
+};
+\end{lstlisting}
+
+\field{num_entries} indidates the number of valid array entries \field{entries}.
+For each of the valid entry in \field{entries}, fields \field{type}
+and \field{key} are in the format described in
+\ref{par:Device Types / Network Device / Device Operation / Flow Filter / Match Types and Keys}.
+\field{key_len} represents the length of field \field{key}.
+When \field{mask_len} is non zero, \field{mask} is present and has
+exact same format as \field{key} and \field{mask_len} represents the length
+of the field \field{mask}.
+
+\begin{lstlisting}
+#define VIRTIO_NET_FF_DEST_TYPE_RX_VQ 0
+
+struct virtio_ff_action_forward {
+        u8 dest_type;
+        u8 reserved[3];
+        union {
+                le16 vq_index;
+                le32 reserved1;
+        };
+};
+
+#define VIRTIO_NET_FF_ACTION_DROP 0
+#define VIRTIO_NET_FF_ACTION_FORWARD 1
+
+struct virtio_ff_action {
+        u8 action;
+        u8 len; /* indicates the length of value in bytes */
+        u8 value[];
+};
+
+struct virtio_ff_actions {
+        u8 num_actions; /* indicates number of valid actions */
+        u8 reserved[7];
+        struct virtio_ff_action actions[];
+};
+\end{lstlisting}
+
+\field{num_actions} indicates valid number of array entries of \field{actions}
+to apply when the packet matches all the supplied match entries; these
+\field{actions} are applied sequentially to the packet.
+
+For the device resource VIRTIO_NET_RESOURCE_FF_RULE, the
+\field{resource_specific_data} is in the format of
+\field{struct virtio_net_resource_ff_rule}.
+
+When \field{action} is set to VIRTIO_NET_FF_ACTION_DROP, the matching packet
+will be dropped by the device.
+
+When \field{action} is set to VIRTIO_NET_FF_ACTION_FORWARD, \field{value} is
+in format of \field{struct virtio_ff_action_forward} and the matching packet
+will be forwarded to the specified destination, i.e. when \field{dest_type}
+is VIRTIO_NET_FF_DEST_TYPE_RX_VQ, it is forwarded to the specified receive
+virtqueue.
+
+\begin{lstlisting}
+struct virtio_net_resource_ff_rule {
+        le32 group_id;
+        u8 priority;	/* higher priority rules are processed first */
+        u8 reserved[3];
+        struct virtio_ff_match_entries match_entries;
+        struct virtio_ff_actions actions;
+};
+\end{lstlisting}
+
 \subsection{Device Operation}\label{sec:Device Types / Network Device / Device Operation}
 
 Packets are transmitted by placing them in the
@@ -2510,7 +2601,8 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 
 \paragraph{Match Types and Keys}\label{par:Device Types / Network Device / Device Operation / Flow Filter / Match Types and Keys}
 
-The \field{type} for \field{struct virtio_net_ff_match_type_cap} corresponds to following table:
+The \field{type} for \field{struct virtio_net_ff_match_type_cap} and \field{struct virtio_ff_match_entry}
+corresponds to following table:
 
 \begin{tabular}{|l|l|l|}
 \hline
@@ -2553,6 +2645,21 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_ETH_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_net_ff_match_eth_hdr {
+        u8 dmac[6];
+        u8 smac[6];
+        le16 ether_type;
+};
+\end{lstlisting}
+
+\field{dmac} is valid when VIRTIO_NET_FF_DST_MAC is set.
+\field{smac} is valid when VIRTIO_NET_FF_SRC_MAC is set.
+\field{ether_type} is valid when VIRTIO_NET_FF_ETHER_TYPE is set.
+
 For the \field{type} of VIRTIO_NET_FF_VLAN_TAG_HDR, VLAN tag fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2581,6 +2688,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_IPV4_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_net_ff_match_ipv4_hdr {
+        le32 reserved[3];
+        le32 sip;
+        le32 dip;
+};
+\end{lstlisting}
+
+\field{sip} is valid when VIRTIO_NET_FF_SRC_IPV4 is set.
+\field{dip} is valid when VIRTIO_NET_FF_DST_IPV4 is set.
+
 For the \field{type} of VIRTIO_NET_FF_IPV6_HDR, header fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2596,6 +2717,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_IPV4_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_net_ff_match_ipv6_hdr {
+        le32 reserved[2];
+        u8 sip[16];
+        u8 dip[16];
+};
+\end{lstlisting}
+
+\field{sip} is valid when VIRTIO_NET_FF_SRC_IPV6 is set.
+\field{dip} is valid when VIRTIO_NET_FF_DST_IPV6 is set.
+
 For the \field{type} of VIRTIO_NET_FF_TCP_HDR, header fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2611,6 +2746,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_TCP_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_ndr_ff_match_tcp_hdr {
+        le16 sport;
+        le16 dport;
+        le32 reserved[4];
+};
+\end{lstlisting}
+
+\field{sport} is valid when VIRTIO_NET_FF_SRC_TCP_PORT is set.
+\field{dport} is valid when VIRTIO_NET_FF_DST_TCP_PORT is set.
+
 For the \field{type} of VIRTIO_NET_FF_UDP_HDR, header fields
 are represented by a bitmap in \field{fields_bmap} as follows:
 
@@ -2626,6 +2775,20 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \hline
 \end{tabular}
 
+For the \field{type} of VIRTIO_NET_FF_UDP_HDR, the match entries
+\field{key} and \field{mask} are in following format:
+
+\begin{lstlisting}
+struct virtio_ndr_ff_match_udp_hdr {
+        le16 sport;
+        le16 dport;
+        le32 reserved;
+};
+\end{lstlisting}
+
+\field{sport} is valid when VIRTIO_NET_FF_SRC_UDP_PORT is set.
+\field{dport} is valid when VIRTIO_NET_FF_DST_UDP_PORT is set.
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#11 lore raw

PATCH v8 11/13 virtio-net: Add flow filter device and driver requirements

In reply to Parav Pandit

Add device and driver flow filter requirements.

---
changelog:
v6->v7:
- added device normatives for valid ranges
- rebased to use capabilities and resources
v5->v6:
- removed white spaces from end of line
- added missing conformance links
v2->v3:
- removed dependency on the dynamic queue creation as the infrastructure is not yet ready
v1->v2:
- fixed comments from Heng
- fixed spelling from initializaton to initialization
- added more requirements for multiple actions
v0->v1:
- addressed comments from Satananda
- added device requirement to return non zero value in fields_bmap
- added device requirement to not repeat filter type in response
- added driver requirement to order filter match field as it appears in the packet
- added device requirement to fail group delete command on existing flow entries

---
 device-types/net/description.tex        | 123 ++++++++++++++++++++++++
 device-types/net/device-conformance.tex |   1 +
 device-types/net/driver-conformance.tex |   1 +
 3 files changed, 125 insertions(+)
device-types/net/description.tex +123 -0
index b9d0378..268e448 100644
@@ -2789,6 +2789,129 @@ \subsubsection{Flow Filter}\label{sec:Device Types / Network Device / Device Ope
 \field{sport} is valid when VIRTIO_NET_FF_SRC_UDP_PORT is set.
 \field{dport} is valid when VIRTIO_NET_FF_DST_UDP_PORT is set.
 
+\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 and VIRTIO_NET_FF_MATCH_CAP
+capabilities in the \field{supported_caps} in
+VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY command.
+\item the device MUST support VIRTIO_ADMIN_CMD_RESOURCE_ADD,
+VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_QUERY,
+VIRTIO_ADMIN_CMD_RESOURCE_REMOVE administration commands for resource type
+VIRTIO_NET_RESOURCE_FF_GROUP and VIRTIO_NET_RESOURCE_FF_RULE.
+\end{itemize}
+
+When the VIRTIO_NET_FF_RESOURCE_CAP or VIRTIO_NET_FF_MATCH_CAP capability
+is disabled, the device MUST respond \field{status} as
+VIRTIO_ADMIN_STATUS_Q_INVALID_OPCODE for commands
+VIRTIO_ADMIN_CMD_RESOURCE_ADD,
+VIRTIO_ADMIN_CMD_RESOURCE_MODIFY, VIRTIO_ADMIN_CMD_RESOURCE_QUERY,
+and VIRTIO_ADMIN_CMD_RESOURCE_REMOVE for resource \field{type} of
+VIRTIO_NET_RESOURCE_FF_GROUP and VIRTIO_NET_RESOURCE_FF_RULE.
+
+When the command VIRTIO_ADMIN_CMD_CAP_SUPPORT_QUERY completes successfully,
+the device MUST NOT repeat \field{type} in the \field{types}.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_EINVAL for the command
+VIRTIO_ADMIN_CMD_RESOURCE_ADD for the resource \field{type} of
+VIRTIO_NET_RESOURCE_FF_GROUP if a flow filter group already exists
+with supplied \field{priority}.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_ENOSPC for the command
+VIRTIO_ADMIN_CMD_RESOURCE_ADD for the resource \field{type} of
+VIRTIO_NET_RESOURCE_FF_GROUP if the flow filter groups in the device
+exceeds more than the value reported in the device capability
+VIRTIO_NET_RESOURCE_FF_GROUP in field \field{groups.max_limit}.
+
+The device MUST set \field{status} to VIRTIO_ADMIN_STATUS_EBUSY for the command
+VIRTIO_ADMIN_CMD_RESOURCE_REMOVE for flow filter group resource when the flow
+filter group has one or more flow filter rules linked to the flow filter group.
+
+The device MUST fail the command VIRTIO_ADMIN_CMD_RESOURCE_ADD for the
+flow filter rule resource,
+\begin{itemize}
+\item if \field{match} contains duplicate \field{type},
+\item if \field{vq_index} in the \field{dest} is not a valid receive
+      virtqueue index,
+\item if \field{priority} is greater than or equal to
+      \field{max_ff_rules_priorities_per_group},
+\item if \field{id} is greater than or equal to \field{rules.max_limit}.
+\item if \field{num_entries} of \field{match_entries.entries} is greater than
+      \field{max_match_fields}.
+\item if \field{num_actions} of \field{actions} is greater than
+      \field{max_actions}.
+\end{itemize}
+
+When the flow filter forwards the packet to the virtqueue identfied by
+\field{vq_index} and if the receive virtqueue is reset, the device
+MUST drop such packets.
+
+The device MUST apply the actions of \field{struct virtio_flow_action} in same
+order as it is supplied by the driver when \field{num_entries} is greater than 1.
+
+The device MUST follow received packet processing ordering chain as following:
+\begin{itemize}
+\item Device configuration done using control virtqueue commands VIRTIO_NET_CTRL_RX,
+   VIRTIO_NET_CTRL_MAC and VIRTIO_NET_CTRL_VLAN.
+\item Flow filters programmed using flow filters functionality.
+\item Device configuration done using VIRTIO_NET_CTRL_MQ_RSS_CONFIG command.
+\end{itemize}
+
+When processing a packet, if the packet is dropped at any stage, the device
+MUST omit processing of next level.
+
+When the device matches the flow filter rule for the packet and if the match is
+successful, the device MUST STOP the filter processing chain, i.e. next level
+of processing MUST not be done.
+
+For multiple flow filter groups, the device MUST follow
+received packet processing ordering chain as following:
+apply all the flow filter rules of the highest priority group;
+if the match is successful, skip rules of all the lower priority group,
+if there is no match, the next higher priority group's rules are
+applied.
+
+Within a flow filter group, the device MUST apply the rules with the
+highest priority first; if there is a match, skip rules of all the lower
+priorities; if there is no match, the next higher priority rule is applied.
+
+When the driver has added multiple flow filter rules with same \field{priority}
+and for a packet if multiple flow filters MAY match such that it MAY result
+in different \field{action} or different \field{dest}, the device MUST apply
+the flow filter rule which is added first.
+
+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 stop processing this packet for flow filters processing.
+
+When the device perform flow filter match operations and if the operation
+result did not have any match, the receive packet processing continues to next level,
+i.e. to apply configuration done using VIRTIO_NET_CTRL_MQ_RSS_CONFIG command.
+
+\drivernormative{\paragraph}{Flow Filter}{Device Types / Network Device / Device Operation / Flow Filter}
+
+The driver must enable VIRTIO_NET_FF_RESOURCE_CAP and VIRTIO_NET_FF_MATCH_CAP
+capabilities to use flow filter operations.
+
+The driver SHOULD NOT add multiple flow filters with same \field{priority}
+in a flow filter group, with overlapping match values.
+
+The driver SHOULD use different priority for different flow filters
+if multiple of the flow filters MAY match for a packet.
+
+The driver SHOULD set the \field{type} in \field{match_entries} as that of
+the order appears in the packet.
+
+The driver MUST NOT set \field{num_entries} in \field{struct virtio_ff_action}
+to more than \field{max_actions} supplied by the device in the
+\field{virtio_net_ctrl_ff_caps}.
+
+The driver SHOULD NOT remove flow filter group using command
+VIRTIO_ADMIN_CMD_RESOURCE_REMOVE when one or more flow filter rules are linked to
+the flow filter group; the driver SHOULD remove flow filter group only after
+all the flow filter rules are removed.
+
 \subsubsection{Legacy Interface: Framing Requirements}\label{sec:Device
 Types / Network Device / Legacy Interface: Framing Requirements}
 
device-types/net/device-conformance.tex +1 -0
index 52526e4..8da520a 100644
@@ -16,4 +16,5 @@
 \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 / Flow Filter}
 \end{itemize}
device-types/net/driver-conformance.tex +1 -0
index c693c4f..79c3572 100644
@@ -16,4 +16,5 @@
 \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 / Flow Filter}
 \end{itemize}
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#12 lore raw

PATCH v8 12/13 newdevice: Improve the appendix chapter heading to reflect the content

In reply to Parav Pandit

Current appendix chapter already covers useful notes for creating new device types and also for extending the device in 'device improvements' section.

The chapter heading was not reflecting the notation for extending the existing device. This sometimes creates confusion/misinterpretation to readers.

Hence fix the heading to reflect the written sections.

While at it, remove the empty lines at the end of the file.

---
 newdevice.tex | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)
newdevice.tex +8 -10
index 28e1c7b..93feb71 100644
@@ -1,9 +1,9 @@
-\chapter{Creating New Device Types}\label{sec:Creating New Device Types}
+\chapter{Creating New Device Types or Extending the Device}\label{sec:Creating New Device Types or Extending the Device}
 
 Various considerations are necessary when creating a new device
-type.
+type or when extending the device functionality.
 
-\section{How Many Virtqueues?}\label{sec:Creating New Device Types / How Many Virtqueues?}
+\section{How Many Virtqueues?}\label{sec:Creating New Device Types or Extending the Device / How Many Virtqueues?}
 
 It is possible that a very simple device will operate entirely
 through its device configuration space, but most will need at least one
@@ -13,7 +13,7 @@ \section{How Many Virtqueues?}\label{sec:Creating New Device Types / How Many Vi
 receive input, and one which the driver places buffers to
 transmit output.
 
-\section{What Device Configuration Space Layout?}\label{sec:Creating New Device Types / What Device Configuration Space Layout?}
+\section{What Device Configuration Space Layout?}\label{sec:Creating New Device Types or Extending the Device / What Device Configuration Space Layout?}
 
 Device configuration space should only be used for initialization-time
 parameters.  It is a limited resource with no synchronization between
@@ -26,14 +26,14 @@ \section{What Device Configuration Space Layout?}\label{sec:Creating New Device
 writable by the driver.  Therefore, no writeable field which triggers an
 action ought to be wider than 32 bits.
 
-\section{What Device Number?}\label{sec:Creating New Device Types / What Device Number?}
+\section{What Device Number?}\label{sec:Creating New Device Types or Extending the Device / What Device Number?}
 
-Device numbers can be reserved by the OASIS committee: email
+Device numbers for the new devices can be reserved by the OASIS committee: email
 [email protected] to secure a unique one.
 
 Meanwhile for experimental drivers, use 65535 and work backwards.
 
-\section{How many MSI-X vectors?  (for PCI)}\label{sec:Creating New Device Types / How many MSI-X vectors?  (for PCI)}
+\section{How many MSI-X vectors?  (for PCI)}\label{sec:Creating New Device Types or Extending the Device / How many MSI-X vectors?  (for PCI)}
 
 Using the optional MSI-X capability devices can speed up
 interrupt processing by removing the need to read ISR Status
@@ -51,7 +51,7 @@ \section{How many MSI-X vectors?  (for PCI)}\label{sec:Creating New Device Types
 number of vectors as possible, or disabling MSI-X capability
 altogether.
 
-\section{Device Improvements}\label{sec:Creating New Device Types / Device Improvements}
+\section{Device Improvements}\label{sec:Creating New Device Types or Extending the Device / Device Improvements}
 
 Any change to device configuration space, or new virtqueues, or
 behavioural changes, should be indicated by negotiation of a new
@@ -63,5 +63,3 @@ \section{Device Improvements}\label{sec:Creating New Device Types / Device Impro
 can use a single bit, but if one feature makes sense without the
 others they should not be gratuitously grouped together to
 conserve feature bits.
-
-
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/
#13 lore raw

PATCH v8 13/13 newdevice: Extend informative guidance on capabilities, resources

In reply to Parav Pandit

Add few informative guidance/notes about which use cases to use device capabilities, and device resources.

---
changelog:
v7->v8:
- improved the examples and text for usage of device capabilities and device resources
- added more Q&A to clarify the resources and capabilities

---
 newdevice.tex | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
newdevice.tex +52 -0
index 93feb71..02e79b5 100644
@@ -13,6 +13,46 @@ \section{How Many Virtqueues?}\label{sec:Creating New Device Types or Extending
 receive input, and one which the driver places buffers to
 transmit output.
 
+\section{When to use Device Resource?}\label{sec:Creating New Device Types or Extending the Device / When to use Device Resource?}
+For a desired device functionality,
+(a) if majority of fields are configured by the
+driver, or
+(b) if device sets majority of fields which are changing often and
+driver wants to query them, in both of those cases, using a device
+resource is preferred.
+
+Even if such functionality is limited to small count as small as one,
+using a device resource can be helpful with large number of devices.
+
+Some examples of implicit device resources for network device are mac
+and vlan table, rtc or PTP clock; examples of explicit resource is virtqueues or
+crypto sessions for crypto device, flow filter counters for network device etc.
+
+\section{How to expose various Device Resource Limit?}\label{sec:Creating New Device Types or Extending the Device / How to expose various Device Resource Limit?}
+If a device supports resource creation to the driver or if the device
+has some implicit resource(s), and device wants to share such resource limits
+to the driver, how should device expose these limits? The device, should
+expose these resource limits using the device capabilities.
+
+\section{When to use the Capabilities?}\label{sec:Creating New Device Types or Extending the Device / When to use the Capabilities?}
+Any field which is more than a bit that a device want to expose to the
+driver, can be exposed as a device capability. Device and driver
+capabilities are not constantly changing fields during the life cycle
+of the driver and device; capabilities are rarely changing parameters
+used during the life time of driver possibly dynamically. Sometimes a
+system may have many similar devices, but each device may have different
+attributes, it is better to use capabilities for such attributes as well.
+Examples of capabilities are resource limits indicating number of RTC clocks
+per device, number of flow filter groups, number of flow filter rules for net
+device, number of data bytes that can be places inline instead of descriptors
+for the transmitq for virtio net device, number of bytes in a header data split
+receive virtqueue etc.
+
+\section{Read only attributes as capabilities?}\label{sec:Creating New Device Types or Extending the Device / Read only attributes as capabilities?}
+If there are one or more device attributes which are read only for the driver,
+they can also be used as device capabilities. Such read only capabilities must
+be documented as read only so that driver do not try to change them.
+
 \section{What Device Configuration Space Layout?}\label{sec:Creating New Device Types or Extending the Device / What Device Configuration Space Layout?}
 
 Device configuration space should only be used for initialization-time
@@ -26,6 +66,18 @@ \section{What Device Configuration Space Layout?}\label{sec:Creating New Device
 writable by the driver.  Therefore, no writeable field which triggers an
 action ought to be wider than 32 bits.
 
+\section{When to use admin virtqueue vs control virtqueue?}\label{sec:Creating New Device Types or Extending the Device / When to use admin virtqueue vs control virtqueue?}
+Any new device which can model its configuration using device capabilities,
+and resources as either implicit or driver created resources, it is preferred
+to use the admin commands using admin virtqueue. This is also helpful
+to do multiple admin virtqueues in future if needed. Even for the existing
+device if a control virtqueue may exist for the existing device, extending new
+functionalities using administration commands is desired as it already
+offers a generic infrastructure for configuration.
+
+Administration virtqueue operations may be relatively slower than the
+data path operations, hence it is not suitable for data path level commands.
+
 \section{What Device Number?}\label{sec:Creating New Device Types or Extending the Device / What Device Number?}
 
 Device numbers for the new devices can be reserved by the OASIS committee: email
Signature · 18 lines
2.34.1


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/