Installation

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:

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 your usage of the correct implementation of SMMUMAN.

This means that:

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:

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:

  1. Modify your BSP buildfile to include the SMMUMAN components:

    • smmuman or smmuman-safety, 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) 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
  2. 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).
  3. 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 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.

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 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 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:

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
}

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.