Documentation/driver-api/generic_pt.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/generic_pt.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/generic_pt.rst
Extension
.rst
Size
5372 bytes
Lines
138
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

========================
Generic Radix Page Table
========================

.. kernel-doc:: include/linux/generic_pt/common.h
	:doc: Generic Radix Page Table

.. kernel-doc:: drivers/iommu/generic_pt/pt_defs.h
	:doc: Generic Page Table Language

Usage
=====

Generic PT is structured as a multi-compilation system. Since each format
provides an API using a common set of names there can be only one format active
within a compilation unit. This design avoids function pointers around the low
level API.

Instead the function pointers can end up at the higher level API (i.e.
map/unmap, etc.) and the per-format code can be directly inlined into the
per-format compilation unit. For something like IOMMU each format will be
compiled into a per-format IOMMU operations kernel module.

For this to work the .c file for each compilation unit will include both the
format headers and the generic code for the implementation. For instance in an
implementation compilation unit the headers would normally be included as
follows:

generic_pt/fmt/iommu_amdv1.c::

	#include <linux/generic_pt/common.h>
	#include "defs_amdv1.h"
	#include "../pt_defs.h"
	#include "amdv1.h"
	#include "../pt_common.h"
	#include "../pt_iter.h"
	#include "../iommu_pt.h"  /* The IOMMU implementation */

iommu_pt.h includes definitions that will generate the operations functions for
map/unmap/etc. using the definitions provided by AMDv1. The resulting module
will have exported symbols named like pt_iommu_amdv1_init().

Refer to drivers/iommu/generic_pt/fmt/iommu_template.h for an example of how the
IOMMU implementation uses multi-compilation to generate per-format ops structs
pointers.

The format code is written so that the common names arise from #defines to
distinct format specific names. This is intended to aid debuggability by
avoiding symbol clashes across all the different formats.

Exported symbols and other global names are mangled using a per-format string
via the NS() helper macro.

The format uses struct pt_common as the top-level struct for the table,
and each format will have its own struct pt_xxx which embeds it to store
format-specific information.

The implementation will further wrap struct pt_common in its own top-level
struct, such as struct pt_iommu_amdv1.

Format functions at the struct pt_common level
----------------------------------------------

.. kernel-doc:: include/linux/generic_pt/common.h
	:identifiers:
.. kernel-doc:: drivers/iommu/generic_pt/pt_common.h

Iteration Helpers

Annotation

Implementation Notes