generic_pt.rst

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