Installation

This section describes how to get SMMUMAN or SMMUMAN for Safety and add it to a QNX Neutrino OS, QNX for Safety (QOS), or other QNX 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 for Safety (QOS), QNX Platform for Instrument Clusters (QPIC), QNX Hypervisor for Safety (QHS), or any other QNX for Safety product) remember that the functional safety of your system depends on 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 for your safety system. 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.so or smmuman-safety.so, as required
- for a system running on the hardware (i.e, a 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 system that will be running the smmuman service safety variant (smmuman-safety.so) on an x86 platform, the pci_server-qvm_support.so support shared object (see “Safety variant support for PCI (x86)” below)
- for a QNX Hypervisor or QNX Hypervisor for Safety (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 QNX Hypervisor or QHS 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 = smmuman
/usr/dll/smmu-rcar3.so = smmu-rcar3.so
/etc/smmuman/rcar-h3.smmu = ./smmuman-config/rcar-h3.smmu

where smmuman-safety is the SMMUMAN for Safety service, smmu-rcar-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 QNX Hypervisor for Safety

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

/bin/smmuman-safety = smmuman-safety

where smmuman-safety is the SMMUMAN for Safety service, and vdev-smmu-safety is the QNX Hypervisor virtual IOMMU/SMMU device in the hosting VM.

ARM Renesas R-Car H3

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 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 QNX Hypervisor system

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

/bin/smmuman = smmuman

where smmuman is the 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), you must include the pci_server-qvm_support.so support file in your system.

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

an in-line file in your buildfile
a separate configuration file

In-line 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 in-line file to your buildfile:

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

which, because no paths are specified, 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, 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.