Installing SMMUMAN

This section describes how to get SMMUMAN or SMMUMAN for Safety and add it to a QNX Neutrino OS or QNX OS for Safety (QOS) system.

SMMUMAN for Safety

Two variants of SMMUMAN are available:

SMMUMAN
SMMUMAN for Safety

If you are building a safety-related system (i.e., you are using QNX OS for Safety (QOS), QNX Platform for Instrument Clusters (QPIC), QNX Hypervisor for Safety (QHS), or any other safety product from QNX), remember that the functional safety of your system depends on your usage of the correct implementation of SMMUMAN.

This means that:

You must use SMMUMAN for Safety.
You must use SMMUMAN for Safety in accordance with the requirements and restrictions stated in the QNX SMMUMAN for Safety Safety Manual.

Warning: SMMUMAN for Safety components include the “-safety” suffix. If you are building a safety-related system, do not use any SMMUMAN components that don't have this suffix.

Assumptions

These instructions assume that:

You have the appropriate development environment installed and configured on your development host (see the QNX SDP 7.n and QOS 2.n documentation).
You know how to build a QNX Neutrino system (see Building Embedded Systems in the QNX SDP 7.n documentation).
You know how to use the QNX Software Center (see the myQNX License Manager and QNX Software Center User's Guide).

Warning: If you are building a safety-related system, don't use macOS as a development host. Only the Windows and Linux development hosts identified in the QOS 2.n documentation are qualified for ISO26262-based safety system development. Although the QNX Software Development Platform supports macOS as a development host, the tool chain on macOS isn't qualified for ISO26262-based safety system development.

Adding SMMUMAN to a system

To implement SMMUMAN on your system, assuming that all the SMMUMAN components were included in your QNX SDP package, in your development environment:

Modify your BSP buildfile to include the SMMUMAN components:
- smmuman or smmuman-safety, as required
- for a system running directly on hardware as the hypervisor host, the architecture-specific or board-specific library for your board: smmu-* or smmu-*-safety, as required (see “The smmu-*.so libraries”), and the *.smmu configuration file for the board, as required (see “Configuring smmuman”)
- for a QNX Hypervisor for Safety (QHS) system that will be running the safety variant (smmuman-safety) on an x86 platform, the pci_server-qvm_support.so support file (see “Safety variant support for PCI (x86)” below)
- for a QNX Hypervisor (QH) or QHS system, the vdev-smmu.so IOMMU/SMMU virtual device shared library, so that it will be available for guests that need to use the smmuman service
For a system running as a QNX guest in a hypervisor VM, in addition to adding the SMMUMAN components in your guest build, add the vdev smmu option in the configuration for the hypervisor VM that will host the guest (see “The vdev-smmu virtual device”).
Run make to rebuild your system with the SMMUMAN components.

Note:

Note the following about SMMUMAN component locations:

smmuman can be placed in any standard path for $PATH (e.g., /bin or /sbin).
The shared libraries smmuman uses (*.so files) can be under any $LD_LIBRARY_PATH path (e.g., /lib/dll or /usr/dll).

Example of entries to add to the buildfile

Below are some examples of how the buildfile might be modified to include SMMUMAN.

x86 for an ordinary system

For a non-safety system running on a supported x86 board, the buildfile might include the following:

/bin/smmuman = smmuman
/lib/dll/smmu-vtd.so = smmu-vtd.so

where smmuman is the SMMUMAN service, and smmu-vtd.so is the SMMUMAN support library for x86 platforms.

ARM Renesas R-Car H3 for a safety-related system

For a safety-related system running directly on a supported Renesas R-Car H3 board, the buildfile might include the following:

/sbin/smmuman-safety = smmuman-safety
/usr/dll/smmu-rcar3-safety.so = smmu-rcar3-safety.so
/etc/smmuman-safety/rcar-h3-safety.smmu = ./smmuman-safety-config/rcar-h3-safety.smmu

where smmuman-safety is the SMMUMAN for Safety service, smmu-rcar3-safety.so is the SMMUMAN support library, and rcar-h3-safety.smmu is your safety smmuman configuration file for Renesas R-Car H3 platforms.

Guest in a QNX Hypervisor for Safety VM

For a safety-related system running as a guest in a QHS VM, the guest's buildfile might include the following:

/bin/smmuman-safety = smmuman-safety

where smmuman-safety is the SMMUMAN for Safety service.

Note: The host buildfile will have to include the vdev-smmu-safety.so virtual device, and the configuration for the VM hosting the guest will have to include the vdev smmu-safety option.

ARM Renesas R-Car H3 for an ordinary system

For a system running on a supported Renesas R-Car H3 board, the buildfile might include the following:

/bin/smmuman = smmuman
/bin/dll/smmu-rcar3.so = smmu-rcar3.so
/etc/smmuman/rcar-h3.smmu = ./smmuman-config/rcar-h3.smmu

where smmuman is the (non-safety) SMMUMAN service, smmu-rcar.so is the SMMUMAN support library, and rcar-h3.smmu is your smmuman configuration file for Renesas R-Car H3 platforms.

QNX guest in a QNX Hypervisor system

For a system running as a guest in a QH VM, the guest's buildfile might include the following:

/bin/smmuman = smmuman

where smmuman is the (non-safety) SMMUMAN service.

Note: The host buildfile will have to include the vdev-smmu.so virtual device, and the configuration for the VM hosting the guest will have to include the vdev smmu option.

Safety variant support for PCI (x86)

If you are using the safety variant of the VTD support library (smmu-vtd-safety.so) in a QHS system, in which the QNX OS for Safety runs on the host, you must include the PCI server support file, pci_server-qvm_support.so, in your system.

To load this file, add the configuration information to one of:

an inline file in your buildfile
a separate configuration file

Including the PCI server support file is not necessary for non-hypervisor systems that run QNX OS for Safety and use the safety variant of the VTD library.

Inline file in buildfile

You can use your buildfile to configure your startup to load the pci_server-qvm_support.so support file. For example, you can add the following inline file to your buildfile:

pci_server.cfg = {
    [runtime]
    PCI_SERVER_MODULE_LIST=pci_server-qvm_support.so
}

Because no paths are specified, this will use the default locations: pci_server.cfg in /proc/boot, and pci_server-qvm_support.so in /lib/dll/pci, the directory where pci-server expects to find all its *.so files.

Separate configuration file

You can add the configuration information to a separate file and point pci-server to it at startup:

pci-server --config=pathto/pci_server.cfg

where pathto is the path to the directory with your configuration file.

Note: Whichever method you use, if you put the server module in its default location (/lib/dll/pci), you don't need to specify the full path to the module in your configuration. If you place the server module in another location, you need to specify the full path.

After your system has booted, you can use pidin or slog2info to confirm that the server module has loaded; for example:

pidin -ppci-server libs

For more information about including configuration information in your buildfile, see “OS Image Buildfiles” in Building Embedded Systems. For more information about configuring pci-server, see “pci-server” in the QNX Neutrino Utilities Reference.