SMMUMAN components

The SMMUMAN comprises a service, an API library, and support libraries (or drivers):

smmuman: The architecture-agnostic SMMUMAN service itself; it is a resource manager that provides services to SMMUMAN clients through the libsmmu API library (see below, and “The libsmmu.a client-side API”).
smmu-*.so: Architecture-specific and board-specific libraries; these provide the interface between the smmuman service’s architecture-agnostic code and the hardware IOMMU/SMMUs.
libsmmu.a: The API that SMMUMAN clients use to access the SMMUMAN services (see “The libsmmu.a client-side API”).

Warning:

Only SMMUMAN safety components may be used in a systems that require safety certification.

There is only one variant of the libsmmu.a library. This variant is the safety variant, and may be used in systems that require safety certification. All other SMMUMAN components have two variants: standard and safety. The safety components have the suffix “-safety” (e.g., smmuman-safety).

Preferentially, the SMMUMAN safety variant (smmuman-safety) loads the safety variants of support files. For example, for NXP i.MX8 platforms, it loads smmu-armsmmu-safety.so and smmu-cfg-imx8-safety.so (see “Configuration at startup” in the “Configuring smmuman” chapter).

The figure below presents a high-level view of the SMMUMAN components. For the purposes of this illustration, we have used the components for the x86 boards, whose SMMUs are called VT-ds. The architecture-specific SMMUMAN support library is smmu-vtd.so.

Figure 1. A high-level overview of the SMMUMAN.

The smmuman | smmuman-safety service

The smmuman service is architecture-agnostic. It requires architecture-specific or board-specific libraries to interface with board IOMMU/SMMU. The smmuman service looks after the following:

Loading and parsing the user-input configuration information at startup.
Replacing the board configuration information with user-input configuration information, where relevant.
Optionally, using this information to inform the board IOMMU/SMMU units of the DMA devices on the system, and of the permitted memory ranges for each device, as well as the activity permitted for each of these memory ranges and DMA devices (read-only, read-write).
In response to client requests, programming the IOMMU/SMMUs on the board (see “Mapping DMA devices and memory regions”).
Monitoring the IOMMU/SMMUs on the board and recording illegal DMA devices attempts to access memory that have been communicated by the IOMMU/SMMU unit in conjuction with the support code (see “The smmu-*.so libraries”).

The smmu-*.so libraries

The smmu-*.so libraries are architecture-specific and board-specific libraries used by the smmuman service to interface with board IOMMU/SMMU units. These libraries look after the following:

Implement the architecture-specific and board-specific functions the smmuman service needs to be able to communicate with the board IOMMU/SMMU units, including the retrieval from the board firmware configuration information about the presence and locations of DMA devices.

The SMMUMAN includes the following architecture-specific and board-specific support libraries:

smmu-armsmmu.so | smmu-armsmmu-safety.so: Implement the code to communicate with ARM SMMUs as specifed in ARM System Memory Management Unit Architecture Specification: SMMU architecture version 2.0 (2016) ARM IHI 0062D.c (ID070116). The SMMUMAN uses this library on boards such as the NXP i.MX8.; To support configurable StreamIDs on NXP i.MX8 platforms, the SMMUMAN also provides the smmu-cfg-imx8.so | smmu-cfg-imx8-safety.so libraries; these libraries set the StreamIDs according to the configuration specified in the smmuman service configuration (see “Board-specific configuration libraries”).
smmu-rcar3.so | smmu-rcar3-safety.so: Implement the code to communicate with Renesas R-Car H3 IPMMUs, as specified in Chapter 16 of Renesas R-Car Series, 3rd Generation User’s Manual: Hardware, Nov. 2018 (Rev. 1.50).
smmu-vtd.so | smmu-vtd-safety.so: Implement the code to communicate with Intel x86 VT-ds, as specified in Intel Virtualization Technology for Directed I/O Architecture Specification, Nov. 2017 (D51397-009, Rev. 2.5).; If you are using the safety variant of this support library (smmu-vtd-safety.so), you must include the pci_server-qvm_support.so in your system (see “Safety variant support for PCI (x86)” in the “smmuman” chapter).

SMMUMAN in a guest OS running in a QNX Hypervisor VM uses the vdev-smmu virtual device, and doesn't require a smmu-*.so library (see “SMMUMAN in a QNX Hypervisor guest”).

Note: If you need to use the SMMUMAN on another board, you will need an appropriate support library. For more information, contact your QNX representative.

The libsmmu.a client-side API

Processes that need to use the SMMUMAN services can use the API presented in the libsmmu library. For a description of the API, see “SMMUMAN Client API Reference”; for instructions on how a SMMUMAN client should use it, see “Mapping DMA devices and memory regions.”