Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
genpt: Add Documentation/ files
Add some general description and pull in the kdoc comments from the source
file to index most of the useful functions.
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
Reviewed-by: Pasha Tatashin <pasha.tatashin@soleen.com>
Reviewed-by: Samiullah Khawaja <skhawaja@google.com>
Tested-by: Alejandro Jimenez <alejandro.j.jimenez@oracle.com>
Tested-by: Pasha Tatashin <pasha.tatashin@soleen.com>
Signed-off-by: Jason Gunthorpe <jgg@nvidia.com>
Signed-off-by: Joerg Roedel <joerg.roedel@amd.com>
authored by
Jason Gunthorpe
and committed by
Joerg Roedel
ab0b5728
7c5b184d
+143
+142
Documentation/driver-api/generic_pt.rst
+142
Documentation/driver-api/generic_pt.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
========================
4
+
Generic Radix Page Table
5
+
========================
6
+
7
+
.. kernel-doc:: include/linux/generic_pt/common.h
8
+
:doc: Generic Radix Page Table
9
+
10
+
.. kernel-doc:: drivers/iommu/generic_pt/pt_defs.h
11
+
:doc: Generic Page Table Language
12
+
13
+
-----
14
+
Usage
15
+
-----
16
+
17
+
Generic PT is structured as a multi-compilation system. Since each format
18
+
provides an API using a common set of names there can be only one format active
19
+
within a compilation unit. This design avoids function pointers around the low
20
+
level API.
21
+
22
+
Instead the function pointers can end up at the higher level API (i.e.
23
+
map/unmap, etc.) and the per-format code can be directly inlined into the
24
+
per-format compilation unit. For something like IOMMU each format will be
25
+
compiled into a per-format IOMMU operations kernel module.
26
+
27
+
For this to work the .c file for each compilation unit will include both the
28
+
format headers and the generic code for the implementation. For instance in an
29
+
implementation compilation unit the headers would normally be included as
30
+
follows::
31
+
32
+
generic_pt/fmt/iommu_amdv1.c::
33
+
34
+
#include <linux/generic_pt/common.h>
35
+
#include "defs_amdv1.h"
36
+
#include "../pt_defs.h"
37
+
#include "amdv1.h"
38
+
#include "../pt_common.h"
39
+
#include "../pt_iter.h"
40
+
#include "../iommu_pt.h" /* The IOMMU implementation */
41
+
42
+
iommu_pt.h includes definitions that will generate the operations functions for
43
+
map/unmap/etc. using the definitions provided by AMDv1. The resulting module
44
+
will have exported symbols named like pt_iommu_amdv1_init().
45
+
46
+
Refer to drivers/iommu/generic_pt/fmt/iommu_template.h for an example of how the
47
+
IOMMU implementation uses multi-compilation to generate per-format ops structs
48
+
pointers.
49
+
50
+
The format code is written so that the common names arise from #defines to
51
+
distinct format specific names. This is intended to aid debuggability by
52
+
avoiding symbol clashes across all the different formats.
53
+
54
+
Exported symbols and other global names are mangled using a per-format string
55
+
via the NS() helper macro.
56
+
57
+
The format uses struct pt_common as the top-level struct for the table,
58
+
and each format will have its own struct pt_xxx which embeds it to store
59
+
format-specific information.
60
+
61
+
The implementation will further wrap struct pt_common in its own top-level
62
+
struct, such as struct pt_iommu_amdv1.
63
+
64
+
----------------------------------------------
65
+
Format functions at the struct pt_common level
66
+
----------------------------------------------
67
+
68
+
.. kernel-doc:: include/linux/generic_pt/common.h
69
+
:identifiers:
70
+
.. kernel-doc:: drivers/iommu/generic_pt/pt_common.h
71
+
72
+
-----------------
73
+
Iteration Helpers
74
+
-----------------
75
+
76
+
.. kernel-doc:: drivers/iommu/generic_pt/pt_iter.h
77
+
78
+
----------------
79
+
Writing a Format
80
+
----------------
81
+
82
+
It is best to start from a simple format that is similar to the target. x86_64
83
+
is usually a good reference for something simple, and AMDv1 is something fairly
84
+
complete.
85
+
86
+
The required inline functions need to be implemented in the format header.
87
+
These should all follow the standard pattern of::
88
+
89
+
static inline pt_oaddr_t amdv1pt_entry_oa(const struct pt_state *pts)
90
+
{
91
+
[..]
92
+
}
93
+
#define pt_entry_oa amdv1pt_entry_oa
94
+
95
+
where a uniquely named per-format inline function provides the implementation
96
+
and a define maps it to the generic name. This is intended to make debug symbols
97
+
work better. inline functions should always be used as the prototypes in
98
+
pt_common.h will cause the compiler to validate the function signature to
99
+
prevent errors.
100
+
101
+
Review pt_fmt_defaults.h to understand some of the optional inlines.
102
+
103
+
Once the format compiles then it should be run through the generic page table
104
+
kunit test in kunit_generic_pt.h using kunit. For example::
105
+
106
+
$ tools/testing/kunit/kunit.py run --build_dir build_kunit_x86_64 --arch x86_64 --kunitconfig ./drivers/iommu/generic_pt/.kunitconfig amdv1_fmt_test.*
107
+
[...]
108
+
[11:15:08] Testing complete. Ran 9 tests: passed: 9
109
+
[11:15:09] Elapsed time: 3.137s total, 0.001s configuring, 2.368s building, 0.311s running
110
+
111
+
The generic tests are intended to prove out the format functions and give
112
+
clearer failures to speed up finding the problems. Once those pass then the
113
+
entire kunit suite should be run.
114
+
115
+
---------------------------
116
+
IOMMU Invalidation Features
117
+
---------------------------
118
+
119
+
Invalidation is how the page table algorithms synchronize with a HW cache of the
120
+
page table memory, typically called the TLB (or IOTLB for IOMMU cases).
121
+
122
+
The TLB can store present PTEs, non-present PTEs and table pointers, depending
123
+
on its design. Every HW has its own approach on how to describe what has changed
124
+
to have changed items removed from the TLB.
125
+
126
+
PT_FEAT_FLUSH_RANGE
127
+
-------------------
128
+
129
+
PT_FEAT_FLUSH_RANGE is the easiest scheme to understand. It tries to generate a
130
+
single range invalidation for each operation, over-invalidating if there are
131
+
gaps of VA that don't need invalidation. This trades off impacted VA for number
132
+
of invalidation operations. It does not keep track of what is being invalidated;
133
+
however, if pages have to be freed then page table pointers have to be cleaned
134
+
from the walk cache. The range can start/end at any page boundary.
135
+
136
+
PT_FEAT_FLUSH_RANGE_NO_GAPS
137
+
---------------------------
138
+
139
+
PT_FEAT_FLUSH_RANGE_NO_GAPS is similar to PT_FEAT_FLUSH_RANGE; however, it tries
140
+
to minimize the amount of impacted VA by issuing extra flush operations. This is
141
+
useful if the cost of processing VA is very high, for instance because a
142
+
hypervisor is processing the page table with a shadowing algorithm.