Commit b047c064 authored by Nicolin Chen's avatar Nicolin Chen Committed by Jason Gunthorpe
Browse files

Documentation: userspace-api: iommufd: Update vDEVICE 

With the introduction of the new object and its infrastructure, update the
doc and the vIOMMU graph to reflect that.

Link: https://patch.msgid.link/r/e1ff278b7163909b2641ae04ff364bb41d2a2a2e.1730836308.git.nicolinc@nvidia.com


Reviewed-by: default avatarJason Gunthorpe <jgg@nvidia.com>
Reviewed-by: default avatarKevin Tian <kevin.tian@intel.com>
Signed-off-by: default avatarNicolin Chen <nicolinc@nvidia.com>
Reviewed-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: default avatarJason Gunthorpe <jgg@nvidia.com>
parent 49ad1277

Documentation/userspace-api/iommufd.rst

+32 −9
Original line number Diff line number Diff line
@@ -96,6 +96,19 @@ Following IOMMUFD objects are exposed to userspace: 
     backed by corresponding vIOMMU objects, in which case a guest OS would do

     the "dispatch" naturally instead of VMM trappings.



- IOMMUFD_OBJ_VDEVICE, representing a virtual device for an IOMMUFD_OBJ_DEVICE

  against an IOMMUFD_OBJ_VIOMMU. This virtual device holds the device's virtual

  information or attributes (related to the vIOMMU) in a VM. An immediate vDATA

  example can be the virtual ID of the device on a vIOMMU, which is a unique ID

  that VMM assigns to the device for a translation channel/port of the vIOMMU,

  e.g. vSID of ARM SMMUv3, vDeviceID of AMD IOMMU, and vRID of Intel VT-d to a

  Context Table. Potential use cases of some advanced security information can

  be forwarded via this object too, such as security level or realm information

  in a Confidential Compute Architecture. A VMM should create a vDEVICE object

  to forward all the device information in a VM, when it connects a device to a

  vIOMMU, which is a separate ioctl call from attaching the same device to an

  HWPT_PAGING that the vIOMMU holds.



All user-visible objects are destroyed via the IOMMU_DESTROY uAPI.



The diagrams below show relationships between user-visible objects and kernel
@@ -135,16 +148,16 @@ creating the objects and links:: 
                         |____________|     |____________|     |______|



  _______________________________________________________________________

 |                      iommufd (with vIOMMU)                            |

 |                      iommufd (with vIOMMU/vDEVICE)                    |

 |                                                                       |

 |                             [5]                                       |

 |                        _____________                                  |

 |                       |             |                                 |

 |      |----------------|    vIOMMU   |                                 |

 |      |                |             |                                 |

 |      |                |             |                                 |

 |      |      [1]       |             |          [4]             [2]    |

 |      |     ______     |             |     _____________     ________  |

 |                             [5]                [6]                    |

 |                        _____________      _____________               |

 |                       |             |    |             |              |

 |      |----------------|    vIOMMU   |<---|   vDEVICE   |<----|        |

 |      |                |             |    |_____________|     |        |

 |      |                |             |                        |        |

 |      |      [1]       |             |          [4]           | [2]    |

 |      |     ______     |             |     _____________     _|______  |

 |      |    |      |    |     [3]     |    |             |   |        | |

 |      |    | IOAS |<---|(HWPT_PAGING)|<---| HWPT_NESTED |<--| DEVICE | |

 |      |    |______|    |_____________|    |_____________|   |________| |
@@ -217,6 +230,15 @@ creating the objects and links:: 
   the vIOMMU object and the HWPT_PAGING, then this vIOMMU object can be used

   as a nesting parent object to allocate an HWPT_NESTED object described above.



6. IOMMUFD_OBJ_VDEVICE can be only manually created via the IOMMU_VDEVICE_ALLOC

   uAPI, provided a viommu_id for an iommufd_viommu object and a dev_id for an

   iommufd_device object. The vDEVICE object will be the binding between these

   two parent objects. Another @virt_id will be also set via the uAPI providing

   the iommufd core an index to store the vDEVICE object to a vDEVICE array per

   vIOMMU. If necessary, the IOMMU driver may choose to implement a vdevce_alloc

   op to init its HW for virtualization feature related to a vDEVICE. Successful

   completion of this operation sets up the linkages between vIOMMU and device.



A device can only bind to an iommufd due to DMA ownership claim and attach to at

most one IOAS object (no support of PASID yet).
@@ -230,6 +252,7 @@ User visible objects are backed by following datastructures: 
- iommufd_hwpt_paging for IOMMUFD_OBJ_HWPT_PAGING.

- iommufd_hwpt_nested for IOMMUFD_OBJ_HWPT_NESTED.

- iommufd_viommu for IOMMUFD_OBJ_VIOMMU.

- iommufd_vdevice for IOMMUFD_OBJ_VDEVICE.



Several terminologies when looking at these datastructures: