diff options
| author | John Levon <john.levon@nutanix.com> | 2021-05-25 16:01:20 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-05-25 16:01:20 +0100 |
| commit | 29d91682128b26482c55a7f87b4849cd05d8ca88 (patch) | |
| tree | b6a00871c6c5488e0da9082bdd81e57442ff1c0c /docs | |
| parent | df72df510f4696fb4835fd42e8f4de2dcb7cf428 (diff) | |
| download | libvfio-user-29d91682128b26482c55a7f87b4849cd05d8ca88.zip libvfio-user-29d91682128b26482c55a7f87b4849cd05d8ca88.tar.gz libvfio-user-29d91682128b26482c55a7f87b4849cd05d8ca88.tar.bz2 | |
more spec updates (#491)
update spec to v0.9.1
Changes include:
- reply message includes the command number
- split out message definitions into request/reply sections, and
skip the repeated standard header definitions
- lots of markup fixes
- re-organization for clarity
- further documentation of argsz
- remove VFIO_USER_VM_INTERRUPT until we have a working implementation
- dirty page tracking is optional
- fix implementations to match the spec
Signed-off-by: John Levon <john.levon@nutanix.com>
Reviewed-by: Thanos Makatos <thanos.makatos@nutanix.com>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/vfio-user.rst | 1773 |
1 files changed, 850 insertions, 923 deletions
diff --git a/docs/vfio-user.rst b/docs/vfio-user.rst index 46b2081..8d8d676 100644 --- a/docs/vfio-user.rst +++ b/docs/vfio-user.rst @@ -4,9 +4,9 @@ vfio-user Protocol Specification ******************************** ------------- -Version_ 0.9 ------------- +-------------- +Version_ 0.9.1 +-------------- .. contents:: Table of Contents @@ -18,25 +18,18 @@ of a generic VFIO device type, living inside the VMM, which we call the client, and the core device implementation, living outside the VMM, which we call the server. -The `Linux VFIO ioctl interface <https://www.kernel.org/doc/html/latest/driver-api/vfio.html>`_ -been chosen as the base for this protocol for the following reasons: - -1) It is a mature and stable API, backed by an extensively used framework. -2) The existing VFIO client implementation in QEMU (qemu/hw/vfio/) can be - largely reused. - -.. Note:: - In a proof of concept implementation it has been demonstrated that using VFIO - over a UNIX domain socket is a viable option. vfio-user is designed with - QEMU in mind, however it could be used by other client applications. The - vfio-user protocol does not require that QEMU's VFIO client implementation - is used in QEMU. +The vfio-user specification is partly based on the +`Linux VFIO ioctl interface <https://www.kernel.org/doc/html/latest/driver-api/vfio.html>`_. -None of the VFIO kernel modules are required for supporting the protocol, -neither in the client nor the server, only the source header files are used. +VFIO is a mature and stable API, backed by an extensively used framework. The +existing VFIO client implementation in QEMU (``qemu/hw/vfio/``) can be largely +re-used, though there is nothing in this specification that requires that +particular implementation. None of the VFIO kernel modules are required for +supporting the protocol, on either the client or server side. Some source +definitions in VFIO are re-used for vfio-user. The main idea is to allow a virtual device to function in a separate process in -the same host over a UNIX domain socket. A UNIX domain socket (AF_UNIX) is +the same host over a UNIX domain socket. A UNIX domain socket (``AF_UNIX``) is chosen because file descriptors can be trivially sent over it, which in turn allows: @@ -45,23 +38,19 @@ allows: * Efficient sharing of eventfd's for triggering interrupts. Other socket types could be used which allow the server to run in a separate -guest in the same host (AF_VSOCK) or remotely (AF_INET). Theoretically the -underlying transport does not necessarily have to be a socket, however we do -not examine such alternatives. In this protocol version we focus on using a -UNIX domain socket and introduce basic support for the other two types of -sockets without considering performance implications. +guest in the same host (``AF_VSOCK``) or remotely (``AF_INET``). Theoretically +the underlying transport does not necessarily have to be a socket, however we do +not examine such alternatives. In this protocol version we focus on using a UNIX +domain socket and introduce basic support for the other two types of sockets +without considering performance implications. While passing of file descriptors is desirable for performance reasons, support is not necessary for either the client or the server in order to implement the protocol. There is always an in-band, message-passing fall back mechanism. -Specification conventions -========================= +Overview +======== -Unless otherwise specified, all sizes should be presumed to be in bytes. - -VFIO -==== VFIO is a framework that allows a physical device to be securely passed through to a user space process; the device-specific kernel driver does not drive the device at all. Typically, the user space process is a VMM and the device is @@ -78,30 +67,33 @@ kernel-based VFIO for one device, and vfio-user for another device. VFIO Device Model ----------------- + A device under VFIO presents a standard interface to the user process. Many of -the VFIO operations in the existing interface use the ioctl() system call, and -references to the existing interface are called the ioctl() implementation in +the VFIO operations in the existing interface use the ``ioctl()`` system call, and +references to the existing interface are called the ``ioctl()`` implementation in this document. -The following sections describe the set of messages that implement the VFIO -interface over a socket. In many cases, the messages are direct translations of -data structures used in the ioctl() implementation. Messages derived from -ioctl()s will have a name derived from the ioctl() command name. E.g., the -VFIO_GET_INFO ioctl() command becomes a VFIO_USER_GET_INFO message. The -purpose of this reuse is to share as much code as feasible with the ioctl() -implementation. +The following sections describe the set of messages that implement the vfio-user +interface over a socket. In many cases, the messages are analogous to data +structures used in the ``ioctl()`` implementation. Messages derived from the +``ioctl()`` will have a name derived from the ``ioctl()`` command name. E.g., the +``VFIO_DEVICE_GET_INFO`` ``ioctl()`` command becomes a +``VFIO_USER_DEVICE_GET_INFO`` message. The purpose of this reuse is to share as +much code as feasible with the ``ioctl()`` implementation``. Connection Initiation ^^^^^^^^^^^^^^^^^^^^^ + After the client connects to the server, the initial client message is -VFIO_USER_VERSION to propose a protocol version and set of capabilities to +``VFIO_USER_VERSION`` to propose a protocol version and set of capabilities to apply to the session. The server replies with a compatible version and set of capabilities it supports, or closes the connection if it cannot support the advertised version. Device Information ^^^^^^^^^^^^^^^^^^ -The client uses a VFIO_USER_DEVICE_GET_INFO message to query the server for + +The client uses a ``VFIO_USER_DEVICE_GET_INFO`` message to query the server for information about the device. This information includes: * The device type and whether it supports reset (``VFIO_DEVICE_FLAGS_``), @@ -111,19 +103,21 @@ information about the device. This information includes: Region Information ^^^^^^^^^^^^^^^^^^ -The client uses VFIO_USER_DEVICE_GET_REGION_INFO messages to query the server -for information about the device's regions. This information describes: + +The client uses ``VFIO_USER_DEVICE_GET_REGION_INFO`` messages to query the +server for information about the device's regions. This information describes: * Read and write permissions, whether it can be memory mapped, and whether it supports additional capabilities (``VFIO_REGION_INFO_CAP_``). * Region index, size, and offset. When a device region can be mapped by the client, the server provides a file -descriptor which the client can mmap(). The server is responsible for polling -for client updates to memory mapped regions. +descriptor which the client can ``mmap()``. The server is responsible for +polling for client updates to memory mapped regions. Region Capabilities """"""""""""""""""" + Some regions have additional capabilities that cannot be described adequately by the region info data structure. These capabilities are returned in the region info reply in a list similar to PCI capabilities in a PCI device's @@ -132,7 +126,7 @@ configuration space. Sparse Regions """""""""""""" A region can be memory-mappable in whole or in part. When only a subset of a -region can be mapped by the client, a VFIO_REGION_INFO_CAP_SPARSE_MMAP +region can be mapped by the client, a ``VFIO_REGION_INFO_CAP_SPARSE_MMAP`` capability is included in the region info reply. This capability describes which portions can be mapped by the client. @@ -141,67 +135,66 @@ which portions can be mapped by the client. that accesses to the NVMe registers (found in the beginning of BAR0) are trapped (an infrequent event), while allowing direct access to the doorbells (an extremely frequent event as every I/O submission requires a write to - BAR0), found right after the NVMe registers in BAR0. + BAR0), found in the next page after the NVMe registers in BAR0. Device-Specific Regions """"""""""""""""""""""" A device can define regions additional to the standard ones (e.g. PCI indexes -0-8). This is achieved by including a VFIO_REGION_INFO_CAP_TYPE capability in -the region info reply of a device-specific region. Such regions are reflected in -``struct vfio_user_device_info.num_regions``. Thus, for PCI devices this value -can be equal to, or higher than, VFIO_PCI_NUM_REGIONS. +0-8). This is achieved by including a ``VFIO_REGION_INFO_CAP_TYPE`` capability +in the region info reply of a device-specific region. Such regions are reflected +in ``struct vfio_user_device_info.num_regions``. Thus, for PCI devices this +value can be equal to, or higher than, ``VFIO_PCI_NUM_REGIONS``. Region I/O via file descriptors ------------------------------- For unmapped regions, region I/O from the client is done via -VFIO_USER_REGION_READ/WRITE. As an optimization, ioeventfds or ioregionfds may -be configured for sub-regions of some regions. A client may request information -on these sub-regions via VFIO_USER_DEVICE_GET_REGION_IO_FDS; by configuring the -returned file descriptors as ioeventfds or ioregionfds, the server can be -directly notified of I/O (for example, by KVM) without taking a trip through the -client. +``VFIO_USER_REGION_READ/WRITE``. As an optimization, ioeventfds or ioregionfds +may be configured for sub-regions of some regions. A client may request +information on these sub-regions via ``VFIO_USER_DEVICE_GET_REGION_IO_FDS``; by +configuring the returned file descriptors as ioeventfds or ioregionfds, the +server can be directly notified of I/O (for example, by KVM) without taking a +trip through the client. Interrupts ^^^^^^^^^^ -The client uses VFIO_USER_DEVICE_GET_IRQ_INFO messages to query the server for -the device's interrupt types. The interrupt types are specific to the bus the -device is attached to, and the client is expected to know the capabilities of -each interrupt type. The server can signal an interrupt either with -VFIO_USER_VM_INTERRUPT messages over the socket, or can directly inject + +The client uses ``VFIO_USER_DEVICE_GET_IRQ_INFO`` messages to query the server +for the device's interrupt types. The interrupt types are specific to the bus +the device is attached to, and the client is expected to know the capabilities +of each interrupt type. The server can signal an interrupt by directly injecting interrupts into the guest via an event file descriptor. The client configures -how the server signals an interrupt with VFIO_USER_SET_IRQS messages. +how the server signals an interrupt with ``VFIO_USER_SET_IRQS`` messages. Device Read and Write ^^^^^^^^^^^^^^^^^^^^^ + When the guest executes load or store operations to an unmapped device region, -the client forwards these operations to the server with VFIO_USER_REGION_READ or -VFIO_USER_REGION_WRITE messages. The server will reply with data from the device -on read operations or an acknowledgement on write operations. +the client forwards these operations to the server with +``VFIO_USER_REGION_READ`` or ``VFIO_USER_REGION_WRITE`` messages. The server +will reply with data from the device on read operations or an acknowledgement on +write operations. See `Read and Write Operations`_. Client memory access -------------------- -The client uses VFIO_USER_DMA_MAP and VFIO_USER_DMA_UNMAP messages to inform the -server of the valid DMA ranges that the server can access on behalf of a device -(typically, VM guest memory). DMA memory may be accessed by the server via -VFIO_USER_DMA_READ and VFIO_USER_DMA_WRITE messages over the socket. In this -case, the "DMA" part of the naming is a misnomer. +The client uses ``VFIO_USER_DMA_MAP`` and ``VFIO_USER_DMA_UNMAP`` messages to +inform the server of the valid DMA ranges that the server can access on behalf +of a device (typically, VM guest memory). DMA memory may be accessed by the +server via ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` messages over the +socket. In this case, the "DMA" part of the naming is a misnomer. Actual direct memory access of client memory from the server is possible if the -client provides file descriptors the server can mmap(). Note that mmap() +client provides file descriptors the server can ``mmap()``. Note that ``mmap()`` privileges cannot be revoked by the client, therefore file descriptors should only be exported in environments where the client trusts the server not to corrupt guest memory. -Protocol Specification -====================== -To distinguish from the base VFIO symbols, all vfio-user symbols are prefixed -with vfio_user or VFIO_USER. In revision 0.1, all data is in the little-endian -format, although this may be relaxed in future revision in cases where the -client and server are both big-endian. The messages are formatted for seamless -reuse of the native VFIO structs. +See `Read and Write Operations`_. + +Client/server interactions +========================== Socket ------ @@ -220,7 +213,8 @@ version of the protocol. Authentication -------------- -For AF_UNIX, we rely on OS mandatory access controls on the socket files, + +For ``AF_UNIX``, we rely on OS mandatory access controls on the socket files, therefore it is up to the management layer to set up the socket as required. Socket types than span guests or hosts will require a proper authentication mechanism. Defining that mechanism is deferred to a future version of the @@ -228,6 +222,7 @@ protocol. Command Concurrency ------------------- + A client may pipeline multiple commands without waiting for previous command replies. The server will process commands in the order they are received. A consequence of this is if a client issues a command with the *No_reply* bit, @@ -245,6 +240,11 @@ if concurrent accesses are performed to command or status registers. Note that unrelated messages sent from the server to the client can appear in between a client to server request/reply and vice versa. +Implementers should be prepared for certain commands to exhibit potentially +unbounded latencies. For example, ``VFIO_USER_DEVICE_RESET`` may take an +arbitrarily long time to complete; clients should take care not to block +unnecessarily. + Socket Disconnection Behavior ----------------------------- The server and the client can disconnect from each other, either intentionally @@ -290,8 +290,15 @@ client memory mappings. If anything happens to the client (such as qemu really did exit), the control stack will know about it and can clean up resources accordingly. +Security Considerations +----------------------- + +Speaking generally, vfio-user clients should not trust servers, and vice versa. +Standard tools and mechanisms should be used on both sides to validate input and +prevent against denial of service scenarios, buffer overflow, etc. + Request Retry and Response Timeout -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------- A failed command is a command that has been successfully sent and has been responded to with an error code. Failure to send the command in the first place (e.g. because the socket is disconnected) is a different type of error examined @@ -305,6 +312,32 @@ earlier in the disconnect section. Defining a retry and timeout scheme is deferred to a future version of the protocol. +Message sizes +------------- + +Some requests have an ``argsz`` field. In a request, it defines the maximum +expected reply payload size, which should be at least the size of the fixed +reply payload headers defined here. For messages that don't have a reply +payload, it defines the size of the incoming request (not including the standard +header); otherwise it's not related to the request message size. + +In a reply, the server sets ``argsz`` field to the size needed for a full +payload size. This may be less than the requested maximum size. This may be +larger than the requested maximum size: in that case, the full payload is not +included in the reply, but the ``argsz`` field in the reply indicates the needed +size, allowing a client to allocate a larger buffer for holding the reply before +trying again. + +Protocol Specification +====================== + +To distinguish from the base VFIO symbols, all vfio-user symbols are prefixed +with ``vfio_user`` or ``VFIO_USER``. In this revision, all data is in the +little-endian format, although this may be relaxed in future revisions in cases +where the client and server are both big-endian. + +Unless otherwise specified, all sizes should be presumed to be in bytes. + .. _Commands: Commands @@ -312,48 +345,30 @@ Commands The following table lists the VFIO message command IDs, and whether the message command is sent from the client or the server. -+------------------------------------+---------+-------------------+ -| Name | Command | Request Direction | -+====================================+=========+===================+ -| VFIO_USER_VERSION | 1 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DMA_MAP | 2 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DMA_UNMAP | 3 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DEVICE_GET_INFO | 4 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DEVICE_GET_REGION_INFO | 5 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DEVICE_GET_REGION_IO_FDS | 6 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DEVICE_GET_IRQ_INFO | 7 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DEVICE_SET_IRQS | 8 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_REGION_READ | 9 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_REGION_WRITE | 10 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DMA_READ | 11 | server -> client | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DMA_WRITE | 12 | server -> client | -+------------------------------------+---------+-------------------+ -| VFIO_USER_VM_INTERRUPT | 13 | server -> client | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DEVICE_RESET | 14 | client -> server | -+------------------------------------+---------+-------------------+ -| VFIO_USER_DIRTY_PAGES | 15 | client -> server | -+------------------------------------+---------+-------------------+ - - -.. Note:: Some VFIO defines cannot be reused since their values are - architecture-specific (e.g. VFIO_IOMMU_MAP_DMA). +====================================== ========= ================= +Name Command Request Direction +====================================== ========= ================= +``VFIO_USER_VERSION`` 1 client -> server +``VFIO_USER_DMA_MAP`` 2 client -> server +``VFIO_USER_DMA_UNMAP`` 3 client -> server +``VFIO_USER_DEVICE_GET_INFO`` 4 client -> server +``VFIO_USER_DEVICE_GET_REGION_INFO`` 5 client -> server +``VFIO_USER_DEVICE_GET_REGION_IO_FDS`` 6 client -> server +``VFIO_USER_DEVICE_GET_IRQ_INFO`` 7 client -> server +``VFIO_USER_DEVICE_SET_IRQS`` 8 client -> server +``VFIO_USER_REGION_READ`` 9 client -> server +``VFIO_USER_REGION_WRITE`` 10 client -> server +``VFIO_USER_DMA_READ`` 11 server -> client +``VFIO_USER_DMA_WRITE`` 12 server -> client +``VFIO_USER_DEVICE_RESET`` 13 client -> server +``VFIO_USER_DIRTY_PAGES`` 14 client -> server +====================================== ========= ================= Header ------ + All messages, both command messages and reply messages, are preceded by a -header that contains basic information about the message. The header is +16-byte header that contains basic information about the message. The header is followed by message-specific data described in the sections below. +----------------+--------+-------------+ @@ -386,7 +401,8 @@ followed by message-specific data described in the sections below. message. Message IDs belong entirely to the sender, can be re-used (even concurrently) and the receiver must not make any assumptions about their uniqueness. -* *Command* specifies the command to be executed, listed in Commands_. +* *Command* specifies the command to be executed, listed in Commands_. It is + also set in the reply header. * *Message size* contains the size of the entire message, including the header. * *Flags* contains attributes of the message: @@ -395,62 +411,66 @@ followed by message-specific data described in the sections below. * *Command* (value 0x0) indicates a command message. * *Reply* (value 0x1) indicates a reply message acknowledging a previous command with the same message ID. - * *No_reply* in a command message indicates that no reply is needed for this command. - This is commonly used when multiple commands are sent, and only the last needs - acknowledgement. + * *No_reply* in a command message indicates that no reply is needed for this + command. This is commonly used when multiple commands are sent, and only + the last needs acknowledgement. * *Error* in a reply message indicates the command being acknowledged had an error. In this case, the *Error* field will be valid. * *Error* in a reply message is an optional UNIX errno value. It may be zero even if the Error bit is set in Flags. It is reserved in a command message. -Each command message in Commands_ must be replied to with a reply message, unless the -message sets the *No_Reply* bit. The reply consists of the header with the *Reply* -bit set, plus any additional data. +Each command message in Commands_ must be replied to with a reply message, +unless the message sets the *No_Reply* bit. The reply consists of the header +with the *Reply* bit set, plus any additional data. If an error occurs, the reply message must only include the reply header. -VFIO_USER_VERSION ------------------ +As the header is standard in both requests and replies, it is not included in +the command-specific specifications below; each message definition should be +appended to the standard header, and the offsets are given from the end of the +standard header. + +``VFIO_USER_VERSION`` +--------------------- + +.. _Version: This is the initial message sent by the client after the socket connection is -established: - -Message format -^^^^^^^^^^^^^^ - -+--------------+-------------------------------------------+ -| Name | Value | -+==============+===========================================+ -| Message ID | <ID> | -+--------------+-------------------------------------------+ -| Command | 1 | -+--------------+-------------------------------------------+ -| Message size | 16 + version header + version data length | -+--------------+-------------------------------------------+ -| Flags | Reply bit set in reply | -+--------------+-------------------------------------------+ -| Error | 0/errno | -+--------------+-------------------------------------------+ -| Version | version header | -+--------------+-------------------------------------------+ - -Version Header Format -^^^^^^^^^^^^^^^^^^^^^ +established; the same format is used for the server's reply. + +Upon establishing a connection, the client must send a ``VFIO_USER_VERSION`` +message proposing a protocol version and a set of capabilities. The server +compares these with the versions and capabilities it supports and sends a +``VFIO_USER_VERSION`` reply according to the following rules. + +* The major version in the reply must be the same as proposed. If the client + does not support the proposed major, it closes the connection. +* The minor version in the reply must be equal to or less than the minor + version proposed. +* The capability list must be a subset of those proposed. If the server + requires a capability the client did not include, it closes the connection. + +The protocol major version will only change when incompatible protocol changes +are made, such as changing the message format. The minor version may change +when compatible changes are made, such as adding new messages or capabilities, +Both the client and server must support all minor versions less than the +maximum minor version it supports. E.g., an implementation that supports +version 1.3 must also support 1.0 through 1.2. + +When making a change to this specification, the protocol version number must +be included in the form "added in version X.Y" -+---------------+--------+------------------------------------------------+ -| Name | Offset | Size | -+===============+========+================================================+ -| version major | 16 | 2 | -+---------------+--------+------------------------------------------------+ -| version minor | 18 | 2 | -+---------------+--------+------------------------------------------------+ -| version data | 22 | variable (including terminating NUL | -| | | character). Optional. | -+---------------+--------+------------------------------------------------+ +Request +^^^^^^^ -Version Data Format -^^^^^^^^^^^^^^^^^^^ +============== ====== ==== +Name Offset Size +============== ====== ==== +version major 0 2 +version minor 2 2 +version data 4 variable (including terminating NUL). Optional. +============== ====== ==== The version data is an optional UTF-8 encoded JSON byte array with the following format: @@ -493,65 +513,26 @@ The migration capability contains the following name/value pairs: | | | between the client and the server is used. | +--------------+--------+-----------------------------------------------+ +Reply +^^^^^ -.. _Version: - -Versioning and Feature Support -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Upon establishing a connection, the client must send a VFIO_USER_VERSION message -proposing a protocol version and a set of capabilities. The server compares -these with the versions and capabilities it supports and sends a -VFIO_USER_VERSION reply according to the following rules. - -* The major version in the reply must be the same as proposed. If the client - does not support the proposed major, it closes the connection. -* The minor version in the reply must be equal to or less than the minor - version proposed. -* The capability list must be a subset of those proposed. If the server - requires a capability the client did not include, it closes the connection. - -The protocol major version will only change when incompatible protocol changes -are made, such as changing the message format. The minor version may change -when compatible changes are made, such as adding new messages or capabilities, -Both the client and server must support all minor versions less than the -maximum minor version it supports. E.g., an implementation that supports -version 1.3 must also support 1.0 through 1.2. - -When making a change to this specification, the protocol version number must -be included in the form "added in version X.Y" - - -VFIO_USER_DMA_MAP ------------------ +The same message format is used in the server's reply with the semantics +described above. -Message Format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 2 | -+--------------+------------------------+ -| Message size | 16 + table size | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| Table | array of table entries | -+--------------+------------------------+ +``VFIO_USER_DMA_MAP`` +--------------------- This command message is sent by the client to the server to inform it of the memory regions the server can access. It must be sent before the server can perform any DMA to the client. It is normally sent directly after the version handshake is completed, but may also occur when memory is added to the client, or if the client uses a vIOMMU. -The table is an array of the following structure: -Table entry format -^^^^^^^^^^^^^^^^^^ +Request +^^^^^^^ + +The request payload for this message is an array of table entries of the +following format: +-------------+--------+-------------+ | Name | Offset | Size | @@ -576,9 +557,9 @@ Table entry format * *Address* is the base DMA address of the region. * *Size* is the size of the region. * *Offset* is the file offset of the region with respect to the associated file - descriptor. + descriptor, or zero if the region is not mappable * *Protections* are the region's protection attributes as encoded in - ``<sys/mman.h>``; only PROT_READ and PROT_WRITE are supported + ``<sys/mman.h>``; only ``PROT_READ`` and ``PROT_WRITE`` are supported * *Flags* contains the following region attributes: * *Mappable* indicates that the region can be mapped via the mmap() system @@ -589,58 +570,44 @@ This structure is 32 bytes in size, so the message size is: If a DMA region being added can be directly mapped by the server, an array of file descriptors must be sent as part of the message meta-data. Each mappable -region entry must have a corresponding file descriptor. On AF_UNIX sockets, the -file descriptors must be passed as SCM_RIGHTS type ancillary data. Otherwise, -if a DMA region cannot be directly mapped by the server, it can be accessed by -the server using VFIO_USER_DMA_READ and VFIO_USER_DMA_WRITE messages, explained -in `Read and Write Operations`_. A command to map over an existing region must -be failed by the server with ``EEXIST`` set in error field in the reply. +region entry must have a corresponding file descriptor. On ``AF_UNIX`` sockets, +the file descriptors must be passed as ``SCM_RIGHTS`` type ancillary data. +Otherwise, if a DMA region cannot be directly mapped by the server, it can be +accessed by the server using ``VFIO_USER_DMA_READ`` and ``VFIO_USER_DMA_WRITE`` +messages, explained in `Read and Write Operations`_. A command to map over an +existing region must be failed by the server with ``EEXIST`` set in error field +in the reply. Adding multiple DMA regions can partially fail. The response does not indicate which regions were added and which were not, therefore it is a client implementation detail how to recover from the failure. .. Note:: - The server can optionally remove succesfully added DMA regions making this + The server can optionally remove successfully added DMA regions making this operation atomic. The client can recover by attempting to unmap one by one all the DMA regions - in the VFIO_USER_DMA_MAP command, ignoring failures for regions that do not - exist. + in the ``VFIO_USER_DMA_MAP`` command, ignoring failures for regions that do + not exist. +Reply +^^^^^ -VFIO_USER_DMA_UNMAP -------------------- +There is no payload in the reply message. -Message Format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 3 | -+--------------+------------------------+ -| Message size | 16 + table size | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| Table | array of table entries | -+--------------+------------------------+ +``VFIO_USER_DMA_UNMAP`` +----------------------- This command message is sent by the client to the server to inform it that one -or more DMA regions, previously made available via a VFIO_USER_DMA_MAP command -message, are no longer available for DMA. It typically occurs when memory is -subtracted from the client or if the client uses a vIOMMU. If the client does -not expect the server to perform DMA then it does not need to send to the -server VFIO_USER_DMA_UNMAP commands. If the server does not need to perform DMA -then it can ignore such commands but it must still reply to them. Each DMA +or more DMA regions, previously made available via a ``VFIO_USER_DMA_MAP`` +command message, are no longer available for DMA. It typically occurs when +memory is subtracted from the client or if the client uses a vIOMMU. Each DMA region is described by a table entry in an array of the following structure: -Table entry format -^^^^^^^^^^^^^^^^^^ +Request +^^^^^^^ + +The request payload for this message is an array of table entries of the +following format: +--------------+--------+---------------------------------------+ | Name | Offset | Size | @@ -661,34 +628,28 @@ Table entry format | | | 0 | VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP | | | | +-----+--------------------------------------+ | +--------------+--------+---------------------------------------+ -| VFIO Bitmap | 32 | 24 | -+--------------+--------+---------------------------------------+ * *Address* is the base DMA address of the DMA region. * *Size* is the size of the DMA region. -* *Offset*: is ignored for unmap -* *Protections* is ignored for unmap +* *Offset* must be zero (ignored) +* *Protections* must be zero (ignored) * *Flags* contains the following DMA region attributes: - * *VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP* indicates that a dirty page bitmap + * ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` indicates that a dirty page bitmap must be populated before unmapping the DMA region. The client must provide - a ``struct vfio_user_bitmap`` (explained below) in the VFIO bitmap field - for the DMA region, with the ``pgsize`` and ``size`` fields initialized. - -* *VFIO Bitmap* contains a ``struct vfio_user_bitmap`` for the DMA region if - ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` is set in Flags. + a ``struct vfio_user_bitmap`` immediately following this table entry. The position of the next DMA region in the table is therefore dependent on whether or not the previous DMA region has the ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` bit set in its Flags. -The size of the command message is: -16 + (# of table entries * 32) + (# number of table entries with ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` set Flags * 24). +The size of the total request message is: +16 + (# of table entries * 32) + (# number of table entries with ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` set Flags * 16). .. _VFIO bitmap format: VFIO bitmap format -^^^^^^^^^^^^^^^^^^ +"""""""""""""""""" +--------+--------+------+ | Name | Offset | Size | @@ -697,70 +658,69 @@ VFIO bitmap format +--------+--------+------+ | size | 8 | 8 | +--------+--------+------+ -| data | 16 | 8 | -+--------+--------+------+ * *pgsize* is the page size for the bitmap, in bytes. * *size* is the size for the bitmap, in bytes, excluding the VFIO bitmap header. -* *data* This field is unused in vfio-user. - - -.. Note:: - The size of the bitmap can be larger than necessary. The server must still - respond with the same bitmap size, zeroing the unused part. Reply ^^^^^ -The server responds with the standard vfio-user header. For each DMA region -that has the ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` bit set in Flags in the -command message, the server must append to the header the -``struct vfio_user_bitmap`` received in the command message followed by the -dirty page bitmap, where each bit in the dirty page bitmap represents one page -of size ``struct vfio_user_bitmap.pgsize``. +Upon receiving a ``VFIO_USER_DMA_UNMAP`` command, if the file descriptor is +mapped then the server must release all references to that DMA region before +replying, which potentially includes in-flight DMA transactions. Removing a +portion of a DMA region is possible. -The size of the response message is: -16 + (# of table entries with ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` in flags * 24) + size of all bitmaps. +The server responds with a payload such that there is one ``struct +vfio_user_bitmap`` for each region that had the +``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` bit set in Flags in the request. Each +``struct vfio_user_bitmap`` is followed by the corresponding dirty page bitmap, +where each bit in the dirty page bitmap represents one page of size ``struct +vfio_user_bitmap.pgsize``. -Upon receiving a VFIO_USER_DMA_UNMAP command, if the file descriptor is mapped -then the server must release all references to that DMA region before replying, -which includes potentially in flight DMA transactions. Removing a portion of a -DMA region is possible. +The size of the total reply message is: +16 + (# of table entries with ``VFIO_DMA_UNMAP_FLAG_GET_DIRTY_BITMAP`` in flags * 16) + size of all bitmaps. -VFIO_USER_DEVICE_GET_INFO -------------------------- - -Message format -^^^^^^^^^^^^^^ - -+--------------+----------------------------+ -| Name | Value | -+==============+============================+ -| Message ID | <ID> | -+--------------+----------------------------+ -| Command | 4 | -+--------------+----------------------------+ -| Message size | 32 | -+--------------+----------------------------+ -| Flags | Reply bit set in reply | -+--------------+----------------------------+ -| Error | 0/errno | -+--------------+----------------------------+ -| Device info | VFIO device info | -+--------------+----------------------------+ +``VFIO_USER_DEVICE_GET_INFO`` +----------------------------- This command message is sent by the client to the server to query for basic information about the device. -VFIO device info format -^^^^^^^^^^^^^^^^^^^^^^^ +Request +^^^^^^^ + ++-------------+--------+--------------------------+ +| Name | Offset | Size | ++=============+========+==========================+ +| argsz | 0 | 4 | ++-------------+--------+--------------------------+ +| flags | 4 | 4 | ++-------------+--------+--------------------------+ +| | +-----+-------------------------+ | +| | | Bit | Definition | | +| | +=====+=========================+ | +| | | 0 | VFIO_DEVICE_FLAGS_RESET | | +| | +-----+-------------------------+ | +| | | 1 | VFIO_DEVICE_FLAGS_PCI | | +| | +-----+-------------------------+ | ++-------------+--------+--------------------------+ +| num_regions | 8 | 4 | ++-------------+--------+--------------------------+ +| num_irqs | 12 | 4 | ++-------------+--------+--------------------------+ + +* *argsz* is the maximum size of the reply payload +* all other fields must be zero. + +Reply +^^^^^ +-------------+--------+--------------------------+ | Name | Offset | Size | +=============+========+==========================+ -| argsz | 16 | 4 | +| argsz | 0 | 4 | +-------------+--------+--------------------------+ -| flags | 20 | 4 | +| flags | 4 | 4 | +-------------+--------+--------------------------+ | | +-----+-------------------------+ | | | | Bit | Definition | | @@ -770,20 +730,17 @@ VFIO device info format | | | 1 | VFIO_DEVICE_FLAGS_PCI | | | | +-----+-------------------------+ | +-------------+--------+--------------------------+ -| num_regions | 24 | 4 | +| num_regions | 8 | 4 | +-------------+--------+--------------------------+ -| num_irqs | 28 | 4 | +| num_irqs | 12 | 4 | +-------------+--------+--------------------------+ -* *argsz* is the size of the VFIO device info structure. This is the only field -that should be set to non-zero in the request, identifying the client's expected -size. This must be at least the size of the struct above; it will be set to -actual size filled in in the reply. +* *argsz* is the size required for the full reply payload (16 bytes today) * *flags* contains the following device attributes. - * VFIO_DEVICE_FLAGS_RESET indicates that the device supports the - VFIO_USER_DEVICE_RESET message. - * VFIO_DEVICE_FLAGS_PCI indicates that the device is a PCI device. + * ``VFIO_DEVICE_FLAGS_RESET`` indicates that the device supports the + ``VFIO_USER_DEVICE_RESET`` message. + * ``VFIO_DEVICE_FLAGS_PCI`` indicates that the device is a PCI device. * *num_regions* is the number of memory regions that the device exposes. * *num_irqs* is the number of distinct interrupt types that the device supports. @@ -791,41 +748,46 @@ actual size filled in in the reply. This version of the protocol only supports PCI devices. Additional devices may be supported in future versions. -VFIO_USER_DEVICE_GET_REGION_INFO --------------------------------- - -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 5 | -+--------------+------------------------+ -| Message size | 48 + any caps | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| Region info | VFIO region info | -+--------------+------------------------+ +``VFIO_USER_DEVICE_GET_REGION_INFO`` +------------------------------------ This command message is sent by the client to the server to query for information about device regions. The VFIO region info structure is defined in ``<linux/vfio.h>`` (``struct vfio_region_info``). -VFIO region info format -^^^^^^^^^^^^^^^^^^^^^^^ +Request +^^^^^^^ + ++------------+--------+------------------------------+ +| Name | Offset | Size | ++============+========+==============================+ +| argsz | 0 | 4 | ++------------+--------+------------------------------+ +| flags | 4 | 4 | ++------------+--------+------------------------------+ +| index | 8 | 4 | ++------------+--------+------------------------------+ +| cap_offset | 12 | 4 | ++------------+--------+------------------------------+ +| size | 16 | 8 | ++------------+--------+------------------------------+ +| offset | 24 | 8 | ++------------+--------+------------------------------+ + +* *argsz* the maximum size of the reply payload +* *index* is the index of memory region being queried, it is the only field + that is required to be set in the command message. +* all other fields must be zero. + +Reply +^^^^^ +------------+--------+------------------------------+ | Name | Offset | Size | +============+========+==============================+ -| argsz | 16 | 4 | +| argsz | 0 | 4 | +------------+--------+------------------------------+ -| flags | 20 | 4 | +| flags | 4 | 4 | +------------+--------+------------------------------+ | | +-----+-----------------------------+ | | | | Bit | Definition | | @@ -839,26 +801,27 @@ VFIO region info format | | | 3 | VFIO_REGION_INFO_FLAG_CAPS | | | | +-----+-----------------------------+ | +------------+--------+------------------------------+ -| index | 24 | 4 | +------------+--------+------------------------------+ -| cap_offset | 28 | 4 | +| index | 8 | 4 | +------------+--------+------------------------------+ -| size | 32 | 8 | +| cap_offset | 12 | 4 | +------------+--------+------------------------------+ -| offset | 40 | 8 | +| size | 16 | 8 | ++------------+--------+------------------------------+ +| offset | 24 | 8 | +------------+--------+------------------------------+ -* *argsz* is the size of the VFIO region info structure plus the - size of any region capabilities returned. +* *argsz* is the size required for the full reply payload (region info structure + plus the size of any region capabilities) * *flags* are attributes of the region: - * *VFIO_REGION_INFO_FLAG_READ* allows client read access to the region. - * *VFIO_REGION_INFO_FLAG_WRITE* allows client write access to the region. - * *VFIO_REGION_INFO_FLAG_MMAP* specifies the client can mmap() the region. + * ``VFIO_REGION_INFO_FLAG_READ`` allows client read access to the region. + * ``VFIO_REGION_INFO_FLAG_WRITE`` allows client write access to the region. + * ``VFIO_REGION_INFO_FLAG_MMAP`` specifies the client can mmap() the region. When this flag is set, the reply will include a file descriptor in its - meta-data. On AF_UNIX sockets, the file descriptors will be passed as - SCM_RIGHTS type ancillary data. - * *VFIO_REGION_INFO_FLAG_CAPS* indicates additional capabilities found in the + meta-data. On ``AF_UNIX`` sockets, the file descriptors will be passed as + ``SCM_RIGHTS`` type ancillary data. + * ``VFIO_REGION_INFO_FLAG_CAPS`` indicates additional capabilities found in the reply. * *index* is the index of memory region being queried, it is the only field @@ -872,17 +835,9 @@ VFIO region info format regions with the MMAP attribute. It is also used as the base offset when mapping a VFIO sparse mmap area, described below. -The client sets the ``argsz`` field to indicate the maximum size of the -response that the server can send, which must be at least the size of the -response header plus the size of VFIO region info. If the region contains -capabilities whose size exceeds ``argsz``, then the server must respond only with -the response header and VFIO region info, omitting the region capabilities, and -setting in ``argsz`` the buffer size required to store the initial response -*plus* the region capabilities. The client then retries the operation with a -larger receive buffer. - -VFIO Region capabilities -^^^^^^^^^^^^^^^^^^^^^^^^ +VFIO region capabilities +"""""""""""""""""""""""" + The VFIO region information can also include a capabilities list. This list is similar to a PCI capability list - each entry has a common header that identifies a capability and where the next capability in the list can be found. @@ -890,7 +845,7 @@ The VFIO capability header format is defined in ``<linux/vfio.h>`` (``struct vfio_info_cap_header``). VFIO cap header format -^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""" +---------+--------+------+ | Name | Offset | Size | @@ -907,8 +862,8 @@ VFIO cap header format * *next* specifies the offset of the next capability in the capability list. It is relative to the beginning of the VFIO region info structure. -VFIO sparse mmap -^^^^^^^^^^^^^^^^ +VFIO sparse mmap cap header +""""""""""""""""""""""""""" +------------------+----------------------------------+ | Name | Value | @@ -924,10 +879,12 @@ VFIO sparse mmap This capability is defined when only a subrange of the region supports direct access by the client via mmap(). The VFIO sparse mmap area is defined in -``<linux/vfio.h>`` (``struct vfio_region_sparse_mmap_area``). +``<linux/vfio.h>`` (``struct vfio_region_sparse_mmap_area`` and ``struct +vfio_region_info_cap_sparse_mmap``). VFIO region info cap sparse mmap -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""" + +----------+--------+------+ | Name | Offset | Size | +==========+========+======+ @@ -944,15 +901,15 @@ VFIO region info cap sparse mmap * *nr_areas* is the number of sparse mmap areas in the region. * *offset* and size describe a single area that can be mapped by the client. - There will be nr_areas pairs of offset and size. The offset will be added to - the base offset given in the VFIO_USER_DEVICE_GET_REGION_INFO to form the + There will be *nr_areas* pairs of offset and size. The offset will be added to + the base offset given in the ``VFIO_USER_DEVICE_GET_REGION_INFO`` to form the offset argument of the subsequent mmap() call. The VFIO sparse mmap area is defined in ``<linux/vfio.h>`` (``struct vfio_region_info_cap_sparse_mmap``). -VFIO Region Type -^^^^^^^^^^^^^^^^ +VFIO region type cap header +""""""""""""""""""""""""""" +------------------+---------------------------+ | Name | Value | @@ -968,8 +925,8 @@ VFIO Region Type This capability is defined when a region is specific to the device. -VFIO region info type -^^^^^^^^^^^^^^^^^^^^^ +VFIO region info type cap +""""""""""""""""""""""""" The VFIO region info type is defined in ``<linux/vfio.h>`` (``struct vfio_region_info_cap_type``). @@ -983,206 +940,15 @@ The VFIO region info type is defined in ``<linux/vfio.h>`` +---------+--------+------+ The only device-specific region type and subtype supported by vfio-user is -VFIO_REGION_TYPE_MIGRATION (3) and VFIO_REGION_SUBTYPE_MIGRATION (1). - -VFIO Device Migration Info -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The beginning of the subregion must contain -``struct vfio_device_migration_info``, defined in ``<linux/vfio.h>``. This -subregion is accessed like any other part of a standard vfio-user PCI region -using VFIO_USER_REGION_READ/VFIO_USER_REGION_WRITE. - -+---------------+--------+-----------------------------+ -| Name | Offset | Size | -+===============+========+=============================+ -| device_state | 0 | 4 | -+---------------+--------+-----------------------------+ -| | +-----+----------------------------+ | -| | | Bit | Definition | | -| | +=====+============================+ | -| | | 0 | VFIO_DEVICE_STATE_RUNNING | | -| | +-----+----------------------------+ | -| | | 1 | VFIO_DEVICE_STATE_SAVING | | -| | +-----+----------------------------+ | -| | | 2 | VFIO_DEVICE_STATE_RESUMING | | -| | +-----+----------------------------+ | -+---------------+--------+-----------------------------+ -| reserved | 4 | 4 | -+---------------+--------+-----------------------------+ -| pending_bytes | 8 | 8 | -+---------------+--------+-----------------------------+ -| data_offset | 16 | 8 | -+---------------+--------+-----------------------------+ -| data_size | 24 | 8 | -+---------------+--------+-----------------------------+ +``VFIO_REGION_TYPE_MIGRATION`` (3) and ``VFIO_REGION_SUBTYPE_MIGRATION`` (1). -* *device_state* defines the state of the device: - - The client initiates device state transition by writing the intended state. - The server must respond only after it has successfully transitioned to the new - state. If an error occurs then the server must respond to the - VFIO_USER_REGION_WRITE operation with the Error field set accordingly and - must remain at the previous state, or in case of internal error it must - transition to the error state, defined as - VFIO_DEVICE_STATE_RESUMING | VFIO_DEVICE_STATE_SAVING. The client must - re-read the device state in order to determine it afresh. +``VFIO_USER_DEVICE_GET_REGION_IO_FDS`` +-------------------------------------- - The following device states are defined: +Clients can access regions via ``VFIO_USER_REGION_READ/WRITE`` or, if provided, by +``mmap()`` of a file descriptor provided by the server. - +-----------+---------+----------+-----------------------------------+ - | _RESUMING | _SAVING | _RUNNING | Description | - +===========+=========+==========+===================================+ - | 0 | 0 | 0 | Device is stopped. | - +-----------+---------+----------+-----------------------------------+ - | 0 | 0 | 1 | Device is running, default state. | - +-----------+---------+----------+-----------------------------------+ - | 0 | 1 | 0 | Stop-and-copy state | - +-----------+---------+----------+-----------------------------------+ - | 0 | 1 | 1 | Pre-copy state | - +-----------+---------+----------+-----------------------------------+ - | 1 | 0 | 0 | Resuming | - +-----------+---------+----------+-----------------------------------+ - | 1 | 0 | 1 | Invalid state | - +-----------+---------+----------+-----------------------------------+ - | 1 | 1 | 0 | Error state | - +-----------+---------+----------+-----------------------------------+ - | 1 | 1 | 1 | Invalid state | - +-----------+---------+----------+-----------------------------------+ - - Valid state transitions are shown in the following table: - - +-------------------------+---------+---------+---------------+----------+----------+ - | |darr| From / To |rarr| | Stopped | Running | Stop-and-copy | Pre-copy | Resuming | - +=========================+=========+=========+===============+==========+==========+ - | Stopped | \- | 0 | 0 | 0 | 0 | - +-------------------------+---------+---------+---------------+----------+----------+ - | Running | 1 | \- | 1 | 1 | 1 | - +-------------------------+---------+---------+---------------+----------+----------+ - | Stop-and-copy | 1 | 0 | \- | 0 | 0 | - +-------------------------+---------+---------+---------------+----------+----------+ - | Pre-copy | 0 | 0 | 1 | \- | 0 | - +-------------------------+---------+---------+---------------+----------+----------+ - | Resuming | 0 | 1 | 0 | 0 | \- | - +-------------------------+---------+---------+---------------+----------+----------+ - - A device is migrated to the destination as follows: - - * The source client transitions the device state from the running state to - the pre-copy state. This transition is optional for the client but must be - supported by the server. The source server starts sending device state data - to the source client through the migration region while the device is - running. - - * The source client transitions the device state from the running state or the - pre-copy state to the stop-and-copy state. The source server stops the - device, saves device state and sends it to the source client through the - migration region. - - The source client is responsible for sending the migration data to the - destination client. - - A device is resumed on the destination as follows: - - * The destination client transitions the device state from the running state - to the resuming state. The destination server uses the device state data - received through the migration region to resume the device. - - * The destination client provides saved device state to the destination - server and then transitions the device to back to the running state. - -* *reserved* This field is reserved and any access to it must be ignored by the - server. - -* *pending_bytes* Remaining bytes to be migrated by the server. This field is - read only. - -* *data_offset* Offset in the migration region where the client must: - - * read from, during the pre-copy or stop-and-copy state, or - - * write to, during the resuming state. - - This field is read only. - -* *data_size* Contains the size, in bytes, of the amount of data copied to: - - * the source migration region by the source server during the pre-copy or - stop-and copy state, or - - * the destination migration region by the destination client during the - resuming state. - -Device-specific data must be stored at any position after -`struct vfio_device_migration_info`. Note that the migration region can be -memory mappable, even partially. In practise, only the migration data portion -can be memory mapped. - -The client processes device state data during the pre-copy and the -stop-and-copy state in the following iterative manner: - - 1. The client reads `pending_bytes` to mark a new iteration. Repeated reads - of this field is an idempotent operation. If there are no migration data - to be consumed then the next step depends on the current device state: - - * pre-copy: the client must try again. - - * stop-and-copy: this procedure can end and the device can now start - resuming on the destination. - - 2. The client reads `data_offset`; at this point the server must make - available a portion of migration data at this offset to be read by the - client, which must happen *before* completing the read operation. The - amount of data to be read must be stored in the `data_size` field, which - the client reads next. - - 3. The client reads `data_size` to determine the amount of migration data - available. - - 4. The client reads and processes the migration data. - - 5. Go to step 1. - -Note that the client can transition the device from the pre-copy state to the -stop-and-copy state at any time; `pending_bytes` does not need to become zero. - -The client initializes the device state on the destination by setting the -device state in the resuming state and writing the migration data to the -destination migration region at `data_offset` offset. The client can write the -source migration data in an iterative manner and the server must consume this -data before completing each write operation, updating the `data_offset` field. -The server must apply the source migration data on the device resume state. The -client must write data on the same order and transaction size as read. - -If an error occurs then the server must fail the read or write operation. It is -an implementation detail of the client how to handle errors. - -VFIO_USER_DEVICE_GET_REGION_IO_FDS ----------------------------------- - -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 6 | -+--------------+------------------------+ -| Message size | 32 + subregion info | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| Region info | Region IO FD info | -+--------------+------------------------+ - -Clients can access regions via VFIO_USER_REGION_READ/WRITE or, if provided, by -mmap()ing a file descriptor provided by the server. - -VFIO_USER_DEVICE_GET_REGION_IO_FDS provides an alternative access mechanism via +``VFIO_USER_DEVICE_GET_REGION_IO_FDS`` provides an alternative access mechanism via file descriptors. This is an optional feature intended for performance improvements where an underlying sub-system (such as KVM) supports communication across such file descriptors to the vfio-user server, without needing to @@ -1197,55 +963,70 @@ two mechanisms supported in this specification are ioeventfds and ioregionfds. The server in addition returns a file descriptor in the ancillary data; clients are expected to configure each sub-region's file descriptor with the requested notification method. For example, a client could configure KVM with the -requested ioeventfd via a KVM_IOEVENTFD ioctl(). +requested ioeventfd via a ``KVM_IOEVENTFD`` ``ioctl()``. + +Request +^^^^^^^ + ++-------------+--------+------+ +| Name | Offset | Size | ++=============+========+======+ +| argsz | 0 | 4 | ++-------------+--------+------+ +| flags | 4 | 4 | ++-------------+--------+------+ +| index | 8 | 4 | ++-------------+--------+------+ +| count | 12 | 4 | ++-------------+--------+------+ + +* *argsz* the maximum size of the reply payload +* *index* is the index of memory region being queried +* all other fields must be zero + +The client must set ``flags`` to zero and specify the region being queried in +the ``index``. -Region IO FD info format -^^^^^^^^^^^^^^^^^^^^^^^^ +Reply +^^^^^ +-------------+--------+------+ | Name | Offset | Size | +=============+========+======+ -| argsz | 16 | 4 | +| argsz | 0 | 4 | +-------------+--------+------+ -| flags | 20 | 4 | +| flags | 4 | 4 | +-------------+--------+------+ -| index | 24 | 4 | +| index | 8 | 4 | +-------------+--------+------+ -| count | 28 | 4 | +| count | 12 | 4 | +-------------+--------+------+ -| sub-regions | 32 | ... | +| sub-regions | 16 | ... | +-------------+--------+------+ * *argsz* is the size of the region IO FD info structure plus the total size of the sub-region array. Thus, each array entry "i" is at offset i * ((argsz - 32) / count). Note that currently this is 40 bytes for both IO - FD types, but this is not to be relied on. + FD types, but this is not to be relied on. As elsewhere, this indicates the + full reply payload size needed. * *flags* must be zero * *index* is the index of memory region being queried * *count* is the number of sub-regions in the array * *sub-regions* is the array of Sub-Region IO FD info structures -The client must set ``flags`` to zero and specify the region being queried in -the ``index``. - -The client sets the ``argsz`` field to indicate the maximum size of the response -that the server can send, which must be at least the size of the response header -plus space for the sub-region array. If the full response size exceeds ``argsz``, -then the server must respond only with the response header and the Region IO FD -info structure, setting in ``argsz`` the buffer size required to store the full -response. In this case, no file descriptors are passed back. The client then -retries the operation with a larger receive buffer. - The reply message will additionally include at least one file descriptor in the ancillary data. Note that more than one sub-region may share the same file descriptor. +Note that it is the client's responsibility to verify the requested values (for +example, that the requested offset does not exceed the region's bounds). + Each sub-region given in the response has one of two possible structures, -depending whether *type* is `VFIO_USER_IO_FD_TYPE_IOEVENTFD` or -`VFIO_USER_IO_FD_TYPE_IOREGIONFD`: +depending whether *type* is ``VFIO_USER_IO_FD_TYPE_IOEVENTFD`` or +``VFIO_USER_IO_FD_TYPE_IOREGIONFD``: Sub-Region IO FD info format (ioeventfd) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""" +-----------+--------+------+ | Name | Offset | Size | @@ -1271,18 +1052,20 @@ Sub-Region IO FD info format (ioeventfd) not relevant, which may allow for optimizations * *fd_index* is the index in the ancillary data of the FD to use for ioeventfd notification; it may be shared. -* *type* is `VFIO_USER_IO_FD_TYPE_IOEVENTFD` +* *type* is ``VFIO_USER_IO_FD_TYPE_IOEVENTFD`` * *flags* is any of: - * `KVM_IOEVENTFD_FLAG_DATAMATCH` - * `KVM_IOEVENTFD_FLAG_PIO` - * `KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY` (FIXME: makes sense?) + + * ``KVM_IOEVENTFD_FLAG_DATAMATCH`` + * ``KVM_IOEVENTFD_FLAG_PIO`` + * ``KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY`` (FIXME: makes sense?) + * *datamatch* is the datamatch value if needed -See https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt 4.59 -KVM_IOEVENTFD for further context on the ioeventfd-specific fields. +See https://www.kernel.org/doc/Documentation/virtual/kvm/api.txt, *4.59 +KVM_IOEVENTFD* for further context on the ioeventfd-specific fields. Sub-Region IO FD info format (ioregionfd) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""""""""""" +-----------+--------+------+ | Name | Offset | Size | @@ -1305,14 +1088,16 @@ Sub-Region IO FD info format (ioregionfd) * *offset* is the offset of the start of the sub-region within the region requested ("physical address offset" for the region) * *size* is the length of the sub-region. This may be zero if the access size is - not relevant, which may allow for optimizations; `KVM_IOREGION_POSTED_WRITES` + not relevant, which may allow for optimizations; ``KVM_IOREGION_POSTED_WRITES`` must be set in *flags* in this case * *fd_index* is the index in the ancillary data of the FD to use for ioregionfd messages; it may be shared -* *type* is `VFIO_USER_IO_FD_TYPE_IOREGIONFD` +* *type* is ``VFIO_USER_IO_FD_TYPE_IOREGIONFD`` * *flags* is any of: - * `KVM_IOREGION_PIO` - * `KVM_IOREGION_POSTED_WRITES` + + * ``KVM_IOREGION_PIO`` + * ``KVM_IOREGION_POSTED_WRITES`` + * *user_data* is an opaque value passed back to the server via a message on the file descriptor @@ -1321,41 +1106,22 @@ https://lore.kernel.org/kvm/cover.1613828726.git.eafanasova@gmail.com/ (FIXME: update with final API docs.) -VFIO_USER_DEVICE_GET_IRQ_INFO ------------------------------ - -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 7 | -+--------------+------------------------+ -| Message size | 32 | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| IRQ info | VFIO IRQ info | -+--------------+------------------------+ +``VFIO_USER_DEVICE_GET_IRQ_INFO`` +--------------------------------- This command message is sent by the client to the server to query for information about device interrupt types. The VFIO IRQ info structure is defined in ``<linux/vfio.h>`` (``struct vfio_irq_info``). -VFIO IRQ info format -^^^^^^^^^^^^^^^^^^^^ +Request +^^^^^^^ +-------+--------+---------------------------+ | Name | Offset | Size | +=======+========+===========================+ -| argsz | 16 | 4 | +| argsz | 0 | 4 | +-------+--------+---------------------------+ -| flags | 20 | 4 | +| flags | 4 | 4 | +-------+--------+---------------------------+ | | +-----+--------------------------+ | | | | Bit | Definition | | @@ -1369,64 +1135,74 @@ VFIO IRQ info format | | | 3 | VFIO_IRQ_INFO_NORESIZE | | | | +-----+--------------------------+ | +-------+--------+---------------------------+ -| index | 24 | 4 | +| index | 8 | 4 | +-------+--------+---------------------------+ -| count | 28 | 4 | +| count | 12 | 4 | +-------+--------+---------------------------+ -* *argsz* is the size of the VFIO IRQ info structure. +* *argsz* is the maximum size of the reply payload (16 bytes today) +* index is the index of IRQ type being queried (e.g. ``VFIO_PCI_MSIX_IRQ_INDEX``) +* all other fields must be zero + +Reply +^^^^^ + ++-------+--------+---------------------------+ +| Name | Offset | Size | ++=======+========+===========================+ +| argsz | 0 | 4 | ++-------+--------+---------------------------+ +| flags | 4 | 4 | ++-------+--------+---------------------------+ +| | +-----+--------------------------+ | +| | | Bit | Definition | | +| | +=====+==========================+ | +| | | 0 | VFIO_IRQ_INFO_EVENTFD | | +| | +-----+--------------------------+ | +| | | 1 | VFIO_IRQ_INFO_MASKABLE | | +| | +-----+--------------------------+ | +| | | 2 | VFIO_IRQ_INFO_AUTOMASKED | | +| | +-----+--------------------------+ | +| | | 3 | VFIO_IRQ_INFO_NORESIZE | | +| | +-----+--------------------------+ | ++-------+--------+---------------------------+ +| index | 8 | 4 | ++-------+--------+---------------------------+ +| count | 12 | 4 | ++-------+--------+---------------------------+ + +* *argsz* is the size required for the full reply payload (16 bytes today) * *flags* defines IRQ attributes: - * *VFIO_IRQ_INFO_EVENTFD* indicates the IRQ type can support server eventfd + * ``VFIO_IRQ_INFO_EVENTFD`` indicates the IRQ type can support server eventfd signalling. - * *VFIO_IRQ_INFO_MASKABLE* indicates that the IRQ type supports the MASK and - UNMASK actions in a VFIO_USER_DEVICE_SET_IRQS message. - * *VFIO_IRQ_INFO_AUTOMASKED* indicates the IRQ type masks itself after being - triggered, and the client must send an UNMASK action to receive new + * ``VFIO_IRQ_INFO_MASKABLE`` indicates that the IRQ type supports the ``MASK`` + and ``UNMASK`` actions in a ``VFIO_USER_DEVICE_SET_IRQS`` message. + * ``VFIO_IRQ_INFO_AUTOMASKED`` indicates the IRQ type masks itself after being + triggered, and the client must send an ``UNMASK`` action to receive new interrupts. - * *VFIO_IRQ_INFO_NORESIZE* indicates VFIO_USER_SET_IRQS operations setup + * ``VFIO_IRQ_INFO_NORESIZE`` indicates ``VFIO_USER_SET_IRQS`` operations setup interrupts as a set, and new sub-indexes cannot be enabled without disabling the entire type. - -* index is the index of IRQ type being queried, it is the only field that is - required to be set in the command message. +* index is the index of IRQ type being queried * count describes the number of interrupts of the queried type. -VFIO_USER_DEVICE_SET_IRQS -------------------------- - -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 8 | -+--------------+------------------------+ -| Message size | 36 + any data | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| IRQ set | VFIO IRQ set | -+--------------+------------------------+ +``VFIO_USER_DEVICE_SET_IRQS`` +----------------------------- This command message is sent by the client to the server to set actions for device interrupt types. The VFIO IRQ set structure is defined in ``<linux/vfio.h>`` (``struct vfio_irq_set``). -VFIO IRQ set format -^^^^^^^^^^^^^^^^^^^ +Request +^^^^^^^ +-------+--------+------------------------------+ | Name | Offset | Size | +=======+========+==============================+ -| argsz | 16 | 4 | +| argsz | 0 | 4 | +-------+--------+------------------------------+ -| flags | 20 | 4 | +| flags | 4 | 4 | +-------+--------+------------------------------+ | | +-----+-----------------------------+ | | | | Bit | Definition | | @@ -1444,310 +1220,279 @@ VFIO IRQ set format | | | 5 | VFIO_IRQ_SET_ACTION_TRIGGER | | | | +-----+-----------------------------+ | +-------+--------+------------------------------+ -| index | 24 | 4 | +| index | 8 | 4 | +-------+--------+------------------------------+ -| start | 28 | 4 | +| start | 12 | 4 | +-------+--------+------------------------------+ -| count | 32 | 4 | +| count | 16 | 4 | +-------+--------+------------------------------+ -| data | 36 | variable | +| data | 20 | variable | +-------+--------+------------------------------+ -* *argsz* is the size of the VFIO IRQ set structure, including any *data* field. -* *flags* defines the action performed on the interrupt range. The DATA flags - describe the data field sent in the message; the ACTION flags describe the - action to be performed. The flags are mutually exclusive for both sets. +* *argsz* is the size of the VFIO IRQ set request payload, including any *data* + field. Note there is no reply payload, so this field differs from other + message types. +* *flags* defines the action performed on the interrupt range. The ``DATA`` + flags describe the data field sent in the message; the ``ACTION`` flags + describe the action to be performed. The flags are mutually exclusive for + both sets. - * *VFIO_IRQ_SET_DATA_NONE* indicates there is no data field in the command. + * ``VFIO_IRQ_SET_DATA_NONE`` indicates there is no data field in the command. The action is performed unconditionally. - * *VFIO_IRQ_SET_DATA_BOOL* indicates the data field is an array of boolean + * ``VFIO_IRQ_SET_DATA_BOOL`` indicates the data field is an array of boolean bytes. The action is performed if the corresponding boolean is true. - * *VFIO_IRQ_SET_DATA_EVENTFD* indicates an array of event file descriptors + * ``VFIO_IRQ_SET_DATA_EVENTFD`` indicates an array of event file descriptors was sent in the message meta-data. These descriptors will be signalled when - the action defined by the action flags occurs. In AF_UNIX sockets, the - descriptors are sent as SCM_RIGHTS type ancillary data. + the action defined by the action flags occurs. In ``AF_UNIX`` sockets, the + descriptors are sent as ``SCM_RIGHTS`` type ancillary data. If no file descriptors are provided, this de-assigns the specified previously configured interrupts. - * *VFIO_IRQ_SET_ACTION_MASK* indicates a masking event. It can be used with - VFIO_IRQ_SET_DATA_BOOL or VFIO_IRQ_SET_DATA_NONE to mask an interrupt, or - with VFIO_IRQ_SET_DATA_EVENTFD to generate an event when the guest masks + * ``VFIO_IRQ_SET_ACTION_MASK`` indicates a masking event. It can be used with + ``VFIO_IRQ_SET_DATA_BOOL`` or ``VFIO_IRQ_SET_DATA_NONE`` to mask an interrupt, + or with ``VFIO_IRQ_SET_DATA_EVENTFD`` to generate an event when the guest masks the interrupt. - * *VFIO_IRQ_SET_ACTION_UNMASK* indicates an unmasking event. It can be used - with VFIO_IRQ_SET_DATA_BOOL or VFIO_IRQ_SET_DATA_NONE to unmask an - interrupt, or with VFIO_IRQ_SET_DATA_EVENTFD to generate an event when the + * ``VFIO_IRQ_SET_ACTION_UNMASK`` indicates an unmasking event. It can be used + with ``VFIO_IRQ_SET_DATA_BOOL`` or ``VFIO_IRQ_SET_DATA_NONE`` to unmask an + interrupt, or with ``VFIO_IRQ_SET_DATA_EVENTFD`` to generate an event when the guest unmasks the interrupt. - * *VFIO_IRQ_SET_ACTION_TRIGGER* indicates a triggering event. It can be used - with VFIO_IRQ_SET_DATA_BOOL or VFIO_IRQ_SET_DATA_NONE to trigger an - interrupt, or with VFIO_IRQ_SET_DATA_EVENTFD to generate an event when the + * ``VFIO_IRQ_SET_ACTION_TRIGGER`` indicates a triggering event. It can be used + with ``VFIO_IRQ_SET_DATA_BOOL`` or ``VFIO_IRQ_SET_DATA_NONE`` to trigger an + interrupt, or with ``VFIO_IRQ_SET_DATA_EVENTFD`` to generate an event when the server triggers the interrupt. * *index* is the index of IRQ type being setup. * *start* is the start of the sub-index being set. * *count* describes the number of sub-indexes being set. As a special case, a - count (and start) of 0, with data flags of VFIO_IRQ_SET_DATA_NONE disables + count (and start) of 0, with data flags of ``VFIO_IRQ_SET_DATA_NONE`` disables all interrupts of the index. * *data* is an optional field included when the - VFIO_IRQ_SET_DATA_BOOL flag is present. It contains an array of booleans + ``VFIO_IRQ_SET_DATA_BOOL`` flag is present. It contains an array of booleans that specify whether the action is to be performed on the corresponding index. It's used when the action is only performed on a subset of the range specified. Not all interrupt types support every combination of data and action flags. The client must know the capabilities of the device and IRQ index before it -sends a VFIO_USER_DEVICE_SET_IRQ message. +sends a ``VFIO_USER_DEVICE_SET_IRQ`` message. + +In typical operation, a specific IRQ may operate as follows: + +1. The client sends a ``VFIO_USER_DEVICE_SET_IRQ`` message with + ``flags=(VFIO_IRQ_SET_DATA_EVENTFD|VFIO_IRQ_SET_ACTION_TRIGGER)`` along + with an eventfd. This associates the IRQ with a particular eventfd on the + server side. + +#. The client may send a ``VFIO_USER_DEVICE_SET_IRQ`` message with + ``flags=(VFIO_IRQ_SET_DATA_EVENTFD|VFIO_IRQ_SET_ACTION_MASK/UNMASK)`` along + with another eventfd. This associates the given eventfd with the + mask/unmask state on the server side. + +#. The server may trigger the IRQ by writing 1 to the eventfd. + +#. The server may mask/unmask an IRQ which will write 1 to the corresponding + mask/unmask eventfd, if there is one. + +5. A client may trigger a device IRQ itself, by sending a + ``VFIO_USER_DEVICE_SET_IRQ`` message with + ``flags=(VFIO_IRQ_SET_DATA_NONE/BOOL|VFIO_IRQ_SET_ACTION_TRIGGER)``. + +6. A client may mask or unmask the IRQ, by sending a + ``VFIO_USER_DEVICE_SET_IRQ`` message with + ``flags=(VFIO_IRQ_SET_DATA_NONE/BOOL|VFIO_IRQ_SET_ACTION_MASK/UNMASK)``. + +Reply +^^^^^ + +There is no payload in the reply. .. _Read and Write Operations: -Read and Write Operations +Note that all of these operations must be supported by the client and/or server, +even if the corresponding memory or device region has been shared as mappable. + +``VFIO_USER_REGION_READ`` ------------------------- -Not all I/O operations between the client and server can be done via direct -access of memory mapped with an mmap() call. In these cases, the client and -server use messages sent over the socket. It is expected that these operations -will have lower performance than direct access. +If a device region is not mappable, it's not directly accessible by the client +via ``mmap()`` of the underlying file descriptor. In this case, a client can +read from a device region with this message. -The client can access server memory with VFIO_USER_REGION_READ and -VFIO_USER_REGION_WRITE commands. These share a common data structure that -appears after the message header. +Request +^^^^^^^ -REGION Read/Write Data -^^^^^^^^^^^^^^^^^^^^^^ ++--------+--------+----------+ +| Name | Offset | Size | ++========+========+==========+ +| Offset | 0 | 8 | ++--------+--------+----------+ +| Region | 8 | 4 | ++--------+--------+----------+ +| Count | 12 | 4 | ++--------+--------+----------+ + +* *Offset* into the region being accessed. +* *Region* is the index of the region being accessed. +* *Count* is the size of the data to be transferred. + +Reply +^^^^^ +--------+--------+----------+ | Name | Offset | Size | +========+========+==========+ -| Offset | 16 | 8 | +| Offset | 0 | 8 | +--------+--------+----------+ -| Region | 24 | 4 | +| Region | 8 | 4 | +--------+--------+----------+ -| Count | 28 | 4 | +| Count | 12 | 4 | +--------+--------+----------+ -| Data | 32 | variable | +| Data | 16 | variable | ++--------+--------+----------+ + +* *Offset* into the region accessed. +* *Region* is the index of the region accessed. +* *Count* is the size of the data transferred. +* *Data* is the data that was read from the device region. + +``VFIO_USER_REGION_WRITE`` +-------------------------- + +If a device region is not mappable, it's not directly accessible by the client +via mmap() of the underlying fd. In this case, a client can write to a device +region with this message. + +Request +^^^^^^^ + ++--------+--------+----------+ +| Name | Offset | Size | ++========+========+==========+ +| Offset | 0 | 8 | ++--------+--------+----------+ +| Region | 8 | 4 | ++--------+--------+----------+ +| Count | 12 | 4 | ++--------+--------+----------+ +| Data | 16 | variable | +--------+--------+----------+ * *Offset* into the region being accessed. * *Region* is the index of the region being accessed. * *Count* is the size of the data to be transferred. -* *Data* is the data to be read or written. +* *Data* is the data to write + +Reply +^^^^^ + ++--------+--------+----------+ +| Name | Offset | Size | ++========+========+==========+ +| Offset | 0 | 8 | ++--------+--------+----------+ +| Region | 8 | 4 | ++--------+--------+----------+ +| Count | 12 | 4 | ++--------+--------+----------+ + +* *Offset* into the region accessed. +* *Region* is the index of the region accessed. +* *Count* is the size of the data transferred. -The server can access client memory with VFIO_USER_DMA_READ and -VFIO_USER_DMA_WRITE messages. These also share a common data structure that -appears after the message header. +``VFIO_USER_DMA_READ`` +----------------------- -DMA Read/Write Data -^^^^^^^^^^^^^^^^^^^ +If the client has not shared mappable memory, the server can use this message to +read from guest memory. + +Request +^^^^^^^ +---------+--------+----------+ | Name | Offset | Size | +=========+========+==========+ -| Address | 16 | 8 | -+---------+--------+----------+ -| Count | 24 | 8 | +| Address | 0 | 8 | +---------+--------+----------+ -| Data | 32 | variable | +| Count | 8 | 8 | +---------+--------+----------+ -* *Address* is the area of client memory being accessed. This address must have - been previously exported to the server with a VFIO_USER_DMA_MAP message. +* *Address* is the client DMA memory address being accessed. This address must have + been previously exported to the server with a ``VFIO_USER_DMA_MAP`` message. * *Count* is the size of the data to be transferred. -* *Data* is the data to be read or written. -VFIO_USER_REGION_READ ---------------------- +Reply +^^^^^ -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 9 | -+--------------+------------------------+ -| Message size | 32 + data size | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| Read info | REGION read/write data | -+--------------+------------------------+ - -This command message is sent from the client to the server to read from server -memory. In the command messages, there is no data, and the count is the amount -of data to be read. The reply message must include the data read, and its count -field is the amount of data read. - -VFIO_USER_REGION_WRITE ----------------------- - -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 10 | -+--------------+------------------------+ -| Message size | 32 + data size | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| Write info | REGION read/write data | -+--------------+------------------------+ - -This command message is sent from the client to the server to write to server -memory. The command message must contain the data to be written, and its count -field must contain the amount of write data. The count field in the reply -message must be zero. - -VFIO_USER_DMA_READ ------------------- - -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 11 | -+--------------+------------------------+ -| Message size | 28 + data size | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| DMA info | DMA read/write data | -+--------------+------------------------+ - -This command message is sent from the server to the client to read from client -memory. In the command message, there is no data, and the count must will be -the amount of data to be read. The reply message must include the data read, -and its count field must be the amount of data read. - -VFIO_USER_DMA_WRITE -------------------- ++---------+--------+----------+ +| Name | Offset | Size | ++=========+========+==========+ +| Address | 0 | 8 | ++---------+--------+----------+ +| Count | 8 | 8 | ++---------+--------+----------+ +| Data | 16 | variable | ++---------+--------+----------+ -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 12 | -+--------------+------------------------+ -| Message size | 28 + data size | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ -| DMA info | DMA read/write data | -+--------------+------------------------+ - -This command message is sent from the server to the client to write to client -memory. The command message must contain the data to be written, and its count -field must contain the amount of write data. The count field in the reply -message must be zero. - -VFIO_USER_VM_INTERRUPT ----------------------- - -Message format -^^^^^^^^^^^^^^ - -+----------------+------------------------+ -| Name | Value | -+================+========================+ -| Message ID | <ID> | -+----------------+------------------------+ -| Command | 13 | -+----------------+------------------------+ -| Message size | 20 | -+----------------+------------------------+ -| Flags | Reply bit set in reply | -+----------------+------------------------+ -| Error | 0/errno | -+----------------+------------------------+ -| Interrupt info | <interrupt> | -+----------------+------------------------+ - -This command message is sent from the server to the client to signal the device -has raised an interrupt. - -Interrupt info format -^^^^^^^^^^^^^^^^^^^^^ +* *Address* is the client DMA memory address being accessed. +* *Count* is the size of the data transferred. +* *Data* is the data read. -+-----------+--------+------+ -| Name | Offset | Size | -+===========+========+======+ -| Sub-index | 16 | 4 | -+-----------+--------+------+ +``VFIO_USER_DMA_WRITE`` +----------------------- + +If the client has not shared mappable memory, the server can use this message to +write to guest memory. + +Request +^^^^^^^ + ++---------+--------+----------+ +| Name | Offset | Size | ++=========+========+==========+ +| Address | 0 | 8 | ++---------+--------+----------+ +| Count | 8 | 8 | ++---------+--------+----------+ +| Data | 16 | variable | ++---------+--------+----------+ + +* *Address* is the client DMA memory address being accessed. This address must have + been previously exported to the server with a ``VFIO_USER_DMA_MAP`` message. +* *Count* is the size of the data to be transferred. +* *Data* is the data to write + +Reply +^^^^^ + ++---------+--------+----------+ +| Name | Offset | Size | ++=========+========+==========+ +| Address | 0 | 8 | ++---------+--------+----------+ +| Count | 8 | 4 | ++---------+--------+----------+ + +* *Address* is the client DMA memory address being accessed. +* *Count* is the size of the data transferred. -* *Sub-index* is relative to the IRQ index, e.g., the vector number used in PCI - MSI/X type interrupts. - -VFIO_USER_DEVICE_RESET ----------------------- - -Message format -^^^^^^^^^^^^^^ - -+--------------+------------------------+ -| Name | Value | -+==============+========================+ -| Message ID | <ID> | -+--------------+------------------------+ -| Command | 14 | -+--------------+------------------------+ -| Message size | 16 | -+--------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------+------------------------+ -| Error | 0/errno | -+--------------+------------------------+ +``VFIO_USER_DEVICE_RESET`` +-------------------------- This command message is sent from the client to the server to reset the device. +Neither the request or reply have a payload. -VFIO_USER_DIRTY_PAGES ---------------------- +``VFIO_USER_DIRTY_PAGES`` +------------------------- -Message format -^^^^^^^^^^^^^^ - -+--------------------+------------------------+ -| Name | Value | -+====================+========================+ -| Message ID | <ID> | -+--------------------+------------------------+ -| Command | 15 | -+--------------------+------------------------+ -| Message size | 16 | -+--------------------+------------------------+ -| Flags | Reply bit set in reply | -+--------------------+------------------------+ -| Error | 0/errno | -+--------------------+------------------------+ -| VFIO Dirty bitmap | <dirty bitmap> | -+--------------------+------------------------+ - -This command is analogous to VFIO_IOMMU_DIRTY_PAGES. It is sent by the client +This command is analogous to ``VFIO_IOMMU_DIRTY_PAGES``. It is sent by the client to the server in order to control logging of dirty pages, usually during a live migration. The VFIO dirty bitmap structure is defined in ``<linux/vfio.h>`` (``struct vfio_iommu_type1_dirty_bitmap``). -VFIO Dirty Bitmap Format -^^^^^^^^^^^^^^^^^^^^^^^^ +Dirty page tracking is optional for server implementation; clients should not +rely on it. + +Request +^^^^^^^ +-------+--------+-----------------------------------------+ | Name | Offset | Size | @@ -1773,14 +1518,14 @@ VFIO Dirty Bitmap Format * *flags* defines the action to be performed by the server: - * *VFIO_IOMMU_DIRTY_PAGES_FLAG_START* instructs the server to start logging + * ``VFIO_IOMMU_DIRTY_PAGES_FLAG_START`` instructs the server to start logging pages it dirties. Logging continues until explicitly disabled by - VFIO_IOMMU_DIRTY_PAGES_FLAG_STOP. + ``VFIO_IOMMU_DIRTY_PAGES_FLAG_STOP``. - * *VFIO_IOMMU_DIRTY_PAGES_FLAG_STOP* instructs the server to stop logging + * ``VFIO_IOMMU_DIRTY_PAGES_FLAG_STOP`` instructs the server to stop logging dirty pages. - * *VFIO_IOMMU_DIRTY_PAGES_FLAG_GET_BITMAP* requests from the server to return + * ``VFIO_IOMMU_DIRTY_PAGES_FLAG_GET_BITMAP`` requests from the server to return the dirty bitmap for a specific IOVA range. The IOVA range is specified by "VFIO dirty bitmap get" structure, which must immediately follow the "VFIO dirty bitmap" structure, explained next. This operation is only valid @@ -1792,10 +1537,10 @@ VFIO Dirty Bitmap Format These flags are mutually exclusive with each other. -* *data* This field is unused in vfio-user. +* *data* unused, must be zero VFIO Dirty Bitmap Get Format -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""" +--------+--------+------+ | Name | Offset | Size | @@ -1814,22 +1559,204 @@ VFIO Dirty Bitmap Get Format * *bitmap* is the VFIO bitmap (``struct vfio_bitmap``). This field is explained in `VFIO bitmap format`_. +Reply +^^^^^ + +For ``VFIO_IOMMU_DIRTY_PAGES_FLAG_START`` or +``VFIO_IOMMU_DIRTY_PAGES_FLAG_STOP``, there is no reply payload. + +For ``VFIO_IOMMU_DIRTY_PAGES_FLAG_GET_BITMAP``, the reply payload is the +corresponding set of dirty bitmaps. + +VFIO Device Migration Info +-------------------------- + +A device may contain a migration region (of type +``VFIO_REGION_TYPE_MIGRATION``). The beginning of the region must contain +``struct vfio_device_migration_info``, defined in ``<linux/vfio.h>``. This +subregion is accessed like any other part of a standard vfio-user region +using ``VFIO_USER_REGION_READ``/``VFIO_USER_REGION_WRITE``. + ++---------------+--------+-----------------------------+ +| Name | Offset | Size | ++===============+========+=============================+ +| device_state | 0 | 4 | ++---------------+--------+-----------------------------+ +| | +-----+----------------------------+ | +| | | Bit | Definition | | +| | +=====+============================+ | +| | | 0 | VFIO_DEVICE_STATE_RUNNING | | +| | +-----+----------------------------+ | +| | | 1 | VFIO_DEVICE_STATE_SAVING | | +| | +-----+----------------------------+ | +| | | 2 | VFIO_DEVICE_STATE_RESUMING | | +| | +-----+----------------------------+ | ++---------------+--------+-----------------------------+ +| reserved | 4 | 4 | ++---------------+--------+-----------------------------+ +| pending_bytes | 8 | 8 | ++---------------+--------+-----------------------------+ +| data_offset | 16 | 8 | ++---------------+--------+-----------------------------+ +| data_size | 24 | 8 | ++---------------+--------+-----------------------------+ + +* *device_state* defines the state of the device: + + The client initiates device state transition by writing the intended state. + The server must respond only after it has successfully transitioned to the new + state. If an error occurs then the server must respond to the + ``VFIO_USER_REGION_WRITE`` operation with the Error field set accordingly and + must remain at the previous state, or in case of internal error it must + transition to the error state, defined as + ``VFIO_DEVICE_STATE_RESUMING | VFIO_DEVICE_STATE_SAVING``. The client must + re-read the device state in order to determine it afresh. + + The following device states are defined: + + +-----------+---------+----------+-----------------------------------+ + | _RESUMING | _SAVING | _RUNNING | Description | + +===========+=========+==========+===================================+ + | 0 | 0 | 0 | Device is stopped. | + +-----------+---------+----------+-----------------------------------+ + | 0 | 0 | 1 | Device is running, default state. | + +-----------+---------+----------+-----------------------------------+ + | 0 | 1 | 0 | Stop-and-copy state | + +-----------+---------+----------+-----------------------------------+ + | 0 | 1 | 1 | Pre-copy state | + +-----------+---------+----------+-----------------------------------+ + | 1 | 0 | 0 | Resuming | + +-----------+---------+----------+-----------------------------------+ + | 1 | 0 | 1 | Invalid state | + +-----------+---------+----------+-----------------------------------+ + | 1 | 1 | 0 | Error state | + +-----------+---------+----------+-----------------------------------+ + | 1 | 1 | 1 | Invalid state | + +-----------+---------+----------+-----------------------------------+ + + Valid state transitions are shown in the following table: + + +-------------------------+---------+---------+---------------+----------+----------+ + | |darr| From / To |rarr| | Stopped | Running | Stop-and-copy | Pre-copy | Resuming | + +=========================+=========+=========+===============+==========+==========+ + | Stopped | \- | 0 | 0 | 0 | 0 | + +-------------------------+---------+---------+---------------+----------+----------+ + | Running | 1 | \- | 1 | 1 | 1 | + +-------------------------+---------+---------+---------------+----------+----------+ + | Stop-and-copy | 1 | 0 | \- | 0 | 0 | + +-------------------------+---------+---------+---------------+----------+----------+ + | Pre-copy | 0 | 0 | 1 | \- | 0 | + +-------------------------+---------+---------+---------------+----------+----------+ + | Resuming | 0 | 1 | 0 | 0 | \- | + +-------------------------+---------+---------+---------------+----------+----------+ + + A device is migrated to the destination as follows: + + * The source client transitions the device state from the running state to + the pre-copy state. This transition is optional for the client but must be + supported by the server. The source server starts sending device state data + to the source client through the migration region while the device is + running. + + * The source client transitions the device state from the running state or the + pre-copy state to the stop-and-copy state. The source server stops the + device, saves device state and sends it to the source client through the + migration region. + + The source client is responsible for sending the migration data to the + destination client. + + A device is resumed on the destination as follows: + + * The destination client transitions the device state from the running state + to the resuming state. The destination server uses the device state data + received through the migration region to resume the device. + + * The destination client provides saved device state to the destination + server and then transitions the device to back to the running state. + +* *reserved* This field is reserved and any access to it must be ignored by the + server. + +* *pending_bytes* Remaining bytes to be migrated by the server. This field is + read only. + +* *data_offset* Offset in the migration region where the client must: + + * read from, during the pre-copy or stop-and-copy state, or + + * write to, during the resuming state. + + This field is read only. + +* *data_size* Contains the size, in bytes, of the amount of data copied to: + + * the source migration region by the source server during the pre-copy or + stop-and copy state, or + + * the destination migration region by the destination client during the + resuming state. + +Device-specific data must be stored at any position after +``struct vfio_device_migration_info``. Note that the migration region can be +memory mappable, even partially. In practise, only the migration data portion +can be memory mapped. + +The client processes device state data during the pre-copy and the +stop-and-copy state in the following iterative manner: + + 1. The client reads ``pending_bytes`` to mark a new iteration. Repeated reads + of this field is an idempotent operation. If there are no migration data + to be consumed then the next step depends on the current device state: + + * pre-copy: the client must try again. + + * stop-and-copy: this procedure can end and the device can now start + resuming on the destination. + + 2. The client reads ``data_offset``; at this point the server must make + available a portion of migration data at this offset to be read by the + client, which must happen *before* completing the read operation. The + amount of data to be read must be stored in the ``data_size`` field, which + the client reads next. + + 3. The client reads ``data_size`` to determine the amount of migration data + available. + + 4. The client reads and processes the migration data. + + 5. Go to step 1. + +Note that the client can transition the device from the pre-copy state to the +stop-and-copy state at any time; ``pending_bytes`` does not need to become zero. + +The client initializes the device state on the destination by setting the +device state in the resuming state and writing the migration data to the +destination migration region at ``data_offset`` offset. The client can write the +source migration data in an iterative manner and the server must consume this +data before completing each write operation, updating the ``data_offset`` field. +The server must apply the source migration data on the device resume state. The +client must write data on the same order and transaction size as read. + +If an error occurs then the server must fail the read or write operation. It is +an implementation detail of the client how to handle errors. + Appendices ========== -Unused VFIO ioctl() commands ----------------------------- +Unused VFIO ``ioctl()`` commands +-------------------------------- The following VFIO commands do not have an equivalent vfio-user command: -* VFIO_GET_API_VERSION -* VFIO_CHECK_EXTENSION -* VFIO_SET_IOMMU -* VFIO_GROUP_GET_STATUS -* VFIO_GROUP_SET_CONTAINER -* VFIO_GROUP_UNSET_CONTAINER -* VFIO_GROUP_GET_DEVICE_FD -* VFIO_IOMMU_GET_INFO +* ``VFIO_GET_API_VERSION`` +* ``VFIO_CHECK_EXTENSION`` +* ``VFIO_SET_IOMMU`` +* ``VFIO_GROUP_GET_STATUS`` +* ``VFIO_GROUP_SET_CONTAINER`` +* ``VFIO_GROUP_UNSET_CONTAINER`` +* ``VFIO_GROUP_GET_DEVICE_FD`` +* ``VFIO_IOMMU_GET_INFO`` However, once support for live migration for VFIO devices is finalized some of the above commands may have to be handled by the client in their |