Skip to content

Commit e2d8fe9

Browse files
nicolincjgunthorpe
nicolinc
authored and
jgunthorpe
committed
Documentation: userspace-api: iommufd: Update HWPT_PAGING and HWPT_NESTED
The previous IOMMUFD_OBJ_HW_PAGETABLE has been reworked to two separated objects: IOMMUFD_OBJ_HWPT_PAGING and IOMMUFD_OBJ_HWPT_NESTED in order to support a nested translation context. Corresponding to the latest iommufd APIs and uAPIs, update the doc so as to reflect the new design. Link: https://patch.msgid.link/r/[email protected] Reviewed-by: Kevin Tian <[email protected]> Signed-off-by: Nicolin Chen <[email protected]> Reviewed-by: Bagas Sanjaya <[email protected]> Signed-off-by: Jason Gunthorpe <[email protected]>
1 parent 9852d85 commit e2d8fe9

File tree

1 file changed

+87
-47
lines changed

1 file changed

+87
-47
lines changed

‎Documentation/userspace-api/iommufd.rst

Lines changed: 87 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -41,46 +41,65 @@ Following IOMMUFD objects are exposed to userspace:
4141
- IOMMUFD_OBJ_DEVICE, representing a device that is bound to iommufd by an
4242
external driver.
4343

44-
- IOMMUFD_OBJ_HW_PAGETABLE, representing an actual hardware I/O page table
45-
(i.e. a single struct iommu_domain) managed by the iommu driver.
46-
47-
The IOAS has a list of HW_PAGETABLES that share the same IOVA mapping and
48-
it will synchronize its mapping with each member HW_PAGETABLE.
44+
- IOMMUFD_OBJ_HWPT_PAGING, representing an actual hardware I/O page table
45+
(i.e. a single struct iommu_domain) managed by the iommu driver. "PAGING"
46+
primarly indicates this type of HWPT should be linked to an IOAS. It also
47+
indicates that it is backed by an iommu_domain with __IOMMU_DOMAIN_PAGING
48+
feature flag. This can be either an UNMANAGED stage-1 domain for a device
49+
running in the user space, or a nesting parent stage-2 domain for mappings
50+
from guest-level physical addresses to host-level physical addresses.
51+
52+
The IOAS has a list of HWPT_PAGINGs that share the same IOVA mapping and
53+
it will synchronize its mapping with each member HWPT_PAGING.
54+
55+
- IOMMUFD_OBJ_HWPT_NESTED, representing an actual hardware I/O page table
56+
(i.e. a single struct iommu_domain) managed by user space (e.g. guest OS).
57+
"NESTED" indicates that this type of HWPT should be linked to an HWPT_PAGING.
58+
It also indicates that it is backed by an iommu_domain that has a type of
59+
IOMMU_DOMAIN_NESTED. This must be a stage-1 domain for a device running in
60+
the user space (e.g. in a guest VM enabling the IOMMU nested translation
61+
feature.) As such, it must be created with a given nesting parent stage-2
62+
domain to associate to. This nested stage-1 page table managed by the user
63+
space usually has mappings from guest-level I/O virtual addresses to guest-
64+
level physical addresses.
4965

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

52-
The diagram below shows relationship between user-visible objects and kernel
68+
The diagrams below show relationships between user-visible objects and kernel
5369
datastructures (external to iommufd), with numbers referred to operations
5470
creating the objects and links::
5571

56-
_________________________________________________________
57-
| iommufd |
58-
| [1] |
59-
| _________________ |
60-
| | | |
61-
| | | |
62-
| | | |
63-
| | | |
64-
| | | |
65-
| | | |
66-
| | | [3] [2] |
67-
| | | ____________ __________ |
68-
| | IOAS |<--| |<------| | |
69-
| | | |HW_PAGETABLE| | DEVICE | |
70-
| | | |____________| |__________| |
71-
| | | | | |
72-
| | | | | |
73-
| | | | | |
74-
| | | | | |
75-
| | | | | |
76-
| |_________________| | | |
77-
| | | | |
78-
|_________|___________________|___________________|_______|
79-
| | |
80-
| _____v______ _______v_____
81-
| PFN storage | | | |
82-
|------------>|iommu_domain| |struct device|
83-
|____________| |_____________|
72+
_______________________________________________________________________
73+
| iommufd (HWPT_PAGING only) |
74+
| |
75+
| [1] [3] [2] |
76+
| ________________ _____________ ________ |
77+
| | | | | | | |
78+
| | IOAS |<---| HWPT_PAGING |<---------------------| DEVICE | |
79+
| |________________| |_____________| |________| |
80+
| | | | |
81+
|_________|____________________|__________________________________|_____|
82+
| | |
83+
| ______v_____ ___v__
84+
| PFN storage | (paging) | |struct|
85+
|------------>|iommu_domain|<-----------------------|device|
86+
|____________| |______|
87+
88+
_______________________________________________________________________
89+
| iommufd (with HWPT_NESTED) |
90+
| |
91+
| [1] [3] [4] [2] |
92+
| ________________ _____________ _____________ ________ |
93+
| | | | | | | | | |
94+
| | IOAS |<---| HWPT_PAGING |<---| HWPT_NESTED |<--| DEVICE | |
95+
| |________________| |_____________| |_____________| |________| |
96+
| | | | | |
97+
|_________|____________________|__________________|_______________|_____|
98+
| | | |
99+
| ______v_____ ______v_____ ___v__
100+
| PFN storage | (paging) | | (nested) | |struct|
101+
|------------>|iommu_domain|<----|iommu_domain|<----|device|
102+
|____________| |____________| |______|
84103

85104
1. IOMMUFD_OBJ_IOAS is created via the IOMMU_IOAS_ALLOC uAPI. An iommufd can
86105
hold multiple IOAS objects. IOAS is the most generic object and does not
@@ -94,21 +113,41 @@ creating the objects and links::
94113
device. The driver must also set the driver_managed_dma flag and must not
95114
touch the device until this operation succeeds.
96115

97-
3. IOMMUFD_OBJ_HW_PAGETABLE is created when an external driver calls the IOMMUFD
98-
kAPI to attach a bound device to an IOAS. Similarly the external driver uAPI
99-
allows userspace to initiate the attaching operation. If a compatible
100-
pagetable already exists then it is reused for the attachment. Otherwise a
101-
new pagetable object and iommu_domain is created. Successful completion of
102-
this operation sets up the linkages among IOAS, device and iommu_domain. Once
103-
this completes the device could do DMA.
104-
105-
Every iommu_domain inside the IOAS is also represented to userspace as a
106-
HW_PAGETABLE object.
116+
3. IOMMUFD_OBJ_HWPT_PAGING can be created in two ways:
117+
118+
* IOMMUFD_OBJ_HWPT_PAGING is automatically created when an external driver
119+
calls the IOMMUFD kAPI to attach a bound device to an IOAS. Similarly the
120+
external driver uAPI allows userspace to initiate the attaching operation.
121+
If a compatible member HWPT_PAGING object exists in the IOAS's HWPT_PAGING
122+
list, then it will be reused. Otherwise a new HWPT_PAGING that represents
123+
an iommu_domain to userspace will be created, and then added to the list.
124+
Successful completion of this operation sets up the linkages among IOAS,
125+
device and iommu_domain. Once this completes the device could do DMA.
126+
127+
* IOMMUFD_OBJ_HWPT_PAGING can be manually created via the IOMMU_HWPT_ALLOC
128+
uAPI, provided an ioas_id via @pt_id to associate the new HWPT_PAGING to
129+
the corresponding IOAS object. The benefit of this manual allocation is to
130+
allow allocation flags (defined in enum iommufd_hwpt_alloc_flags), e.g. it
131+
allocates a nesting parent HWPT_PAGING if the IOMMU_HWPT_ALLOC_NEST_PARENT
132+
flag is set.
133+
134+
4. IOMMUFD_OBJ_HWPT_NESTED can be only manually created via the IOMMU_HWPT_ALLOC
135+
uAPI, provided an hwpt_id via @pt_id to associate the new HWPT_NESTED object
136+
to the corresponding HWPT_PAGING object. The associating HWPT_PAGING object
137+
must be a nesting parent manually allocated via the same uAPI previously with
138+
an IOMMU_HWPT_ALLOC_NEST_PARENT flag, otherwise the allocation will fail. The
139+
allocation will be further validated by the IOMMU driver to ensure that the
140+
nesting parent domain and the nested domain being allocated are compatible.
141+
Successful completion of this operation sets up linkages among IOAS, device,
142+
and iommu_domains. Once this completes the device could do DMA via a 2-stage
143+
translation, a.k.a nested translation. Note that multiple HWPT_NESTED objects
144+
can be allocated by (and then associated to) the same nesting parent.
107145

108146
.. note::
109147

110-
Future IOMMUFD updates will provide an API to create and manipulate the
111-
HW_PAGETABLE directly.
148+
Either a manual IOMMUFD_OBJ_HWPT_PAGING or an IOMMUFD_OBJ_HWPT_NESTED is
149+
created via the same IOMMU_HWPT_ALLOC uAPI. The difference is at the type
150+
of the object passed in via the @pt_id field of struct iommufd_hwpt_alloc.
112151

113152
A device can only bind to an iommufd due to DMA ownership claim and attach to at
114153
most one IOAS object (no support of PASID yet).
@@ -120,7 +159,8 @@ User visible objects are backed by following datastructures:
120159

121160
- iommufd_ioas for IOMMUFD_OBJ_IOAS.
122161
- iommufd_device for IOMMUFD_OBJ_DEVICE.
123-
- iommufd_hw_pagetable for IOMMUFD_OBJ_HW_PAGETABLE.
162+
- iommufd_hwpt_paging for IOMMUFD_OBJ_HWPT_PAGING.
163+
- iommufd_hwpt_nested for IOMMUFD_OBJ_HWPT_NESTED.
124164

125165
Several terminologies when looking at these datastructures:
126166

0 commit comments

Comments
 (0)