Starting and stopping smmuman

Updated: October 28, 2024

Typically, you start the smmuman service by including the instructions in your system startup script.

When the smmuman service is included in the bootable OS image, it can be started as part of the system startup procedure. For example, the following snippets are for a buildfile that includes smmuman in a build for a hypervisor host on a fictional x86 board (“myx86”), and starts the service:

# 
[image=0x2000000]
[virtual=x86_64,kpi +compress] boot = {
    startup-intel-MX86 -D8250_mmio.0xFC000000^2.115200 -v 
[+keeplinked module=aps module=qvm] \
	PATH=/sbin:/bin:/usr/sbin:/usr/bin:/opt/sbin:/opt/bin:/proc/boot \
	LD_LIBRARY_PATH=/lib:/usr/lib:/lib/dll:/lib/dll/pci:/proc/boot procnto-smp-instr \
}

[+script] startup-script = {
    display_msg Welcome to the QNX Neutrino RTOS on my x86_64 board.

... 

#Concatenate above, the BSP build file of your choosing

[+script] myx86-startup-script = {
    
    ...
    
    #Start smmuman and point it to the configuration file.
    smmuman @/etc/myx86.smmu
}

# My board binaries #

[perms=0444] /root/envset.sh {
export PCI_HW_MODULE=/lib/dll/pci/pci_hw-Intel_x86_MX86.so
}

...

#Include smmuman configuration file in build.
/etc/myx86.smmu = ${MY_TARGET}/etc/myx86.smmu

...

#Include smmuman in build.
/bin/smmuman = smmuman
/lib/dll/smmu-vtd.so = smmu-vtd.so
CAUTION:
You should start the smmuman service before you start any DMA-enabled drivers.

Determining where the smmuman service is running

A smmuman service may run at the host layer or as part of a guest in a QNX Hypervisor VM. When it runs at the host layer, the service may need to load a support library. If it is running in a guest in a VM, it needs the vdev-smmu virtual device.

When the smmuman service processes its configuration information, it looks for the vdev-smmu virtual device:

If the smmuman service doesn't find the vdev-smmu virtual device and is unable to load the specified support library or none is specified, it reports that the required hardware isn't present and moves to its DSS (see Design Safe State (DSS) in the SMMUMAN Architecture chapter).

Startup in a QNX Hypervisor guest

To use the smmuman service in a QNX guest running in a QNX Hypervisor VM, start it as you would the smmuman service for a system running directly on the hardware (see above). When the smmuman service is implemented in a guest in a QNX Hypervisor VM it proceeds with startup as described above, with the following differences:

  1. The smmuman service doesn’t load a support library, but communicates directly with the IOMMU/SMMU virtual device (vdev-smmu vdev).

    If it doesn’t find a vdev-smmu in its hosting VM (qvm process instance), the smmuman service in the guest reports that the required hardware isn't present and moves to its DSS.

  2. When it parses its configuration information, the smmuman service ignores any reserved, smmu, unit, or use options it finds in its configuration, because these options are relevant only to the corresponding smmuman service running in the hypervisor host.
  3. The smmuman service queries the vdev-smmu vdev, which confirms that a smmuman service is running in the QNX Hypervisor host and that the hosting VM is attached as a client of the host-level smmuman service, and provides the safety-certification status of all the components on which the guest's smmuman service relies:

    • the host-level microkernel and process manager (procnto*)
    • the host-level SMMUMAN components (smmuman, libsmmu.a, and the smmu-*.so support library)
    • the hypervisor components (qvm and the vdev-*.so virtual devices)
Note: The vdev-smmu.so virtual device shared object is a QNX Hypervisor component. For more information about this vdev and how to use it, see the QNX Hypervisor documentation.

Component safety-certification status

By default, if the smmuman service running in the guest is a smmuman for safety variant (smmuman-safety) all the SMMUMAN and all the QNX Hypervisor components must be safety-certified variants. If the required components are not safety-certified variants, the smmuman service in the guest moves to its DSS.

Note: The behavior described above is the default behavior for smmuman-safety. This behavior may be modified with the safety option (see safety in Global options).

Stopping the smmuman service

Warning:

You should never stop the smmuman service after it has started. If you have implemented SMMUMAN in your system, the integrity of your system depends on the smmuman service running continuously.

If for whatever reason the smmuman service moves to its DSS (see Design Safe State (DSS)), your system should move to its DSS.