...
- Hypervisors can fulfill the specification, with local optimizations / advantages
- Similarly, guests VMs can be engineered to match the specification.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119].
2. Architecture
Assumptions made about the architecture, use-cases...
...
REQ-5: The implementation MUST follow the initialisation guideline according to chapter 2.5 in [VIRTIO-IOMMU].
REQ-5.1: As for chapter When implementing device initialization requirements from chapter 2.5.2, the requirement regarding the non accepted a stricter requirement takes place:
a. If the driver does not accept the VIRTIO_IOMMU_F_BYPASS feature
...
, the device SHALL NOT let endpoints access the guest-physical address space.
Device Operation.
REQ-6: The implementation MUST suport the device operation concept (the command set and the operation flow) according to chapter 2.6 in [VIRTIO-IOMMU].
REQ-6.1: As for When implementing support for device operation requirements from chapter 2.6.2, stricter requirements take place:
a. The device SHALL NOT set status to VIRTIO_IOMMU_S_OK if a request didn’t succeedMAY and SHOULD are to be read as MUST, SHOULD NOT is to be read as SHALL NOT.
...
...
b. If a request type is not recognized, the device MUST return the buffers on the used ring and set the len field of the used element to zero.
c. If the VIRTIO_IOMMU_F_INPUT_RANGE feature is offered and the range described by fields virt_start and virt_end doesn’t fit in the range described by input_range, the device MUST set status to VIRTIO_IOMMU_S_RANGE and ignore the request.
d. If the VIRTIO_IOMMU_F_DOMAIN_BITS is offered and bits above domain_bits are set in field domain, the device MUST set status to VIRTIO_IOMMU_S_RANGE and ignore the request.
REQ-6.2: When implementing a handler for the ATTACH request as described in chapter 2.6.3.2, stricter requirements take place:
a. If the reserved field of an ATTACH request is not zero, the device MUST set the request status to VIRTIO_IOMMU_S_INVAL and SHALL NOT attach the endpoint to the domain.
b. If the endpoint identified by endpoint doesn’t exist, then the device MUST set the request status to VIRTIO_IOMMU_S_NOENT.
c. If another endpoint is already attached to the domain identified by domain, then the device MUST attempt to attach the endpoint identified by endpoint to the domain. If it cannot do so, the device MUST set the request status to VIRTIO_IOMMU_S_UNSUPP.
d. If the endpoint identified by endpoint is already attached to another domain, then the device MUST first detach it from that domain and attach it to the one identified by domain. In that case the device behaves as if the driver issued a DETACH request with this endpoint, followed by the ATTACH request. If the device cannot do so, it MUST set the request status to VIRTIO_IOMMU_S_UNSUPP.
e. If properties of the endpoint (obtained with a PROBE request) are incompatible with properties of other endpoints already attached to the requested domain, the device SHALL NOT attach the endpoint and MUST set the request status to VIRTIO_IOMMU_S_UNSUPP.
REQ-6.3: When implementing a handler for the DETACH request as described in chapter 2.6.4.2, stricter requirements take place:
a. If the reserved field of a DETACH request is not zero, the device MUST set the request status to VIRTIO_IOMMU_S_INVAL, in which case the device SHALL NOT perform the DETACH operation.
b. If the endpoint identified by endpoint doesn’t exist, then the device MUST set the request status to VIRTIO_IOMMU_S_NOENT.
c. If the domain identified by domain doesn’t exist, or if the endpoint identified by endpoint isn’t attached to this domain, then the device MUST set the request status to VIRTIO_IOMMU_S_INVAL.
REQ-6.4: When implementing a handler for the MAP request as described in chapter 2.6.5.2, stricter requirements take place:
a. If virt_start, phys_start or (virt_end + 1) is not aligned on the page granularity, the device MUST set the request status to VIRTIO_IOMMU_S_RANGE and SHALL NOT create the mapping.
b. If the device doesn’t recognize a flags bit, it MUST set the request status to VIRTIO_IOMMU_S_INVAL. In this case the device SHALL NOT create the mapping.
c. If a flag or combination of flag isn’t supported, the device MUST set the request status to VIRTIO_IOMMU_S_UNSUPP.
d. The device SHALL NOT allow writes to a range mapped without the VIRTIO_IOMMU_MAP_F_WRITE flag. However, if the underlying architecture does not support write-only mappings, the device MAY allow reads to a range mapped with VIRTIO_IOMMU_MAP_F_WRITE but not VIRTIO_IOMMU_MAP_F_READ.
e. If domain does not exist, the device MUST set the request status to VIRTIO_IOMMU_S_NOENT.
REQ-6.5: When implementing a handler for the UNMAP request as described in chapter 2.6.6.2, stricter requirements take place:
a. If the reserved field of an UNMAP request is not zero, the device MUST set the request status to VIRTIO_IOMMU_S_INVAL, in which case the device SHALL NOT perform the UNMAP operation.
b. If domain does not exist, the device MUST set the request status to VIRTIO_IOMMU_S_NOENT.
c. If a mapping affected by the range is not covered in its entirety by the range (the UNMAP request would split the mapping), then the device MUST set the request status to VIRTIO_IOMMU_S_RANGE, and SHALL NOT remove any mapping.
d. If part of the range or the full range is not covered by an existing mapping, then the device MUST remove all mappings affected by the range and set the request status to VIRTIO_IOMMU_S_OK.
REQ-6.6: When implementing a handler for the PROBE request as described in chapter 2.6.7.2, stricter requirements take place:
a. If the reserved field of a PROBE request is not zero, the device MUST set the request status to VIRTIO_IOMMU_S_INVAL.
b. If the endpoint identified by endpoint doesn’t exist, then the device SHOULD set the request status to VIRTIO_IOMMU_S_NOENT.
c. If the device does not offer the VIRTIO_IOMMU_F_PROBE feature, and if the driver sends a VIRTIO_IOMMU_T_PROBE request, then the device MUST return the buffers on the used ring and set the len field of the used element to zero.
d. The device MUST set bits [15:12] of property type to zero.
e. If the properties list is smaller than probe_size, then the device SHALL NOT write any property and MUST set the request status to VIRTIO_IOMMU_S_INVAL.
f. If the device doesn’t fill all probe_size bytes with properties, it MUST terminate the list with a property of type NONE and size 0. The device MAY fill the remaining bytes of properties, if any, with zeroes. If there isn’t enough space remaining in properties to terminate the list with a complete NONE property (4 bytes), then the device MUST fill the remaining bytes with zeroes.
REQ-6.7: When implementing support for RESV_MEM property as described in chapter 2.6.8.2.2, stricter requirements take place:
a. The device MUST set reserved to zero.
b. The device SHALL NOT present more than one VIRTIO_IOMMU_RESV_MEM_T_MSI property per endpoint.
c. The device SHALL NOT present RESV_MEM properties that overlap each others for the same endpoint
REQ-6.3: As for chapter 2.6.4.2, when implementing a handler for the DETACH request, SHOULD is to be read as MUST, SHOULD NOT is to be read as SHALL NOT.
REQ-6.4: As for chapter 2.6.5.2, when implementing a handler for the MAP request, SHOULD is to be read as MUST, SHOULD NOT is to be read as SHALL NOT.
REQ-6.5: As for chapter 8: When implementing support for fault reporting as described in chapter 2.6.69.2, when implementing a handler for the UNMAP request, SHOULD is to be read as MUST, SHOULD NOT is to be read as SHALL NOT.
REQ-6.6: As for chapter 2.6.7.2, when implementing a handler for the PROBE request, MAY and SHOULD are to be read as MUST, SHOULD NOT is to be read as SHALL NOT.
REQ-6.7: As for chapter 2.6.8.2.2, when implementing support for the RESV_MEM property, SHOULD is to be read as MUST, SHOULD NOT is to be read as SHALL NOT.
stricter requirements take place:
a. The device MUST set reserved and reserved1 to zero.
b. The device MUST set undefined flags to zero.
c. The device MUST write a valid endpoint ID in endpoint.
d. If a buffer is too small to contain the fault report (this would happen for example if the device implements a more recent version of this specification than the driver, whose fault report contains additional fields) , the device SHALL NOT use multiple buffers to describe it. The device MUST fall back to using an older fault report format that fits in the buffer REQ-6.8: As for chapter 2.6.9.2, when implementing support for fault reporting, SHOULD is to be read as MUST, SHOULD NOT is to be read as SHALL NOT.
4. Supplemental Virtual Device categories
4.1 9pfs and host-to-vm filesystem sharing
...
References:
A set of man pages seemingly defining P9? intro, others QEMU instruction how to set up a VirtFS (P9). Example/info how to natively mount a 9P network filesystem, Source code for 9pfs FUSE driver
3. References
[RFC 2119] https://www.ietf.org/rfc/rfc2119.txt
[VIRTIO] Virtual I/O Device (VIRTIO) Version 1.0, Committee Specification 04, release 03 March 2016.
...