smmuman

Note:

The IOMMU/SMMU Manager (smmuman) is not a QNX Hypervisor component. It is a QNX Neutrino OS component. It is described here for the convenience of hypervisor users.

Correct configuration of smmuman requires careful attention to architecture- and board-specific details. Consult your board manufacturer's documentation for the locations and values you must use for your SoC.

Syntax:

smmuman options

Runs on:

QNX Neutrino

Options:

Options may be specified in the command line, or in a *.smmu configuration file (e.g., apollo_lake.smmu, rcar3-h3.smmu), or both. In a configuration file, anything that follows a # character is considered a comment and ignored.

To use a *.smmu configuration file, in the command line enter an @ followed by the filename. For example:

smmuman @rcar3-h3.smmu

Note: Note that smmuman reads its configuration input in a single pass, from start to finish. If you specify an option more than once, smmuman will in most cases add the new information to the configuration (e.g., allow). In some cases, where only a single instance of the option makes sense, smmuman uses the last instance of the option it encounters (e.g., debug).

allow allow_name start,len[,{s|t}]

Add to the set of addresses DMA may be used to or from. Use the parameters as follows:

allow_name – the name of the allowed DMA address set.
start – the start address of the allowed range.
len – the length, in bytes, of the allowed range.
s – if specified, permit the device to use the allowed range as a source of DMA.
t – if specified, permit the device to use the allowed range as a target of DMA.
If neither s nor t is specified, the default is to assume that both are present: permit the device to use the allowed address range as both a source and target of DMA.

debug 1|2

Output debugging information. Specify 2 for more verbose output.

device device_spec [allow_name]

Set the current device being configured to device_spec.

If allow_name is specified, then the device is restricted to address ranges specifed by the allow options with the same allow_name.

foreground

Leave smmuman running in the foreground after parsing its configuration.

reserved start_paddr, length

Mark the current device (the device specified by the preceeding device option) as having a reserved section of memory starting at start_paddr and continuing for length bytes. For example:

device pci:0:15.1
	reserved 0x7afe0000,0x20000

smmu smmu_type [smmu_type_parm]

Load the smmu-smmu_type.so support file, and call its initialization routine, passing smmu_type_parm to the routine. For example:

smmu rcar3 0xe67b0000,228,0x4f.0x01,0x4f.0x10,0x4f.0x20

will load the smmu-rcar3.so with the specified parameters, while:

smmu vtd ignore

will load smmu-vtd.so with the ignore parameters specified.

For more information about smmu_type_parm, see “Board-specific configuration” below.

unit unit_name [smmu_unit_parm]

Define an individual IOMMU/SMMU unit with name unit_name. The type of the unit will be from the preceeding smmu option. The unit initialization routine will be invoked and passed smmu_unit_parm. For example, for an ARM board:

smmu rcar3 0xe67b0000,228,0x4f.0x01,0x4f.0x10,0x4f.0x20
	unit vi0 0xfebd0000,14	# video IO domain AXI
	unit vi1 0xfebe0000,15	# video IO domain AXI
	...
	unit ir  0xff8b0000,3	# IMP domain AXI
	unit hc  0xe6570000,2	# high communication domain AXI
	...

Or, for an x86 board:

smmu vtd ignore
	unit vtd1 0xfed64000
	unit vtd2 0xfed65000

For more information about smmu_unit_parm, see “Board-specific configuration” below.

use unit_name [smmu_use_parm]

The current device (the preceeding device option) will use the IOMMU/SMMU unit identified by unit_name. The smmu_use_parm provides additional information on the device to the IOMMU/SMMU unit.

For more information about smmu_use_parm, see “Board-specific configuration” below.

Board-specific configuration

The syntax for the smmu_*_parm parameters differs according to the type of IOMMU/SMMU. Below are examples of configurations for two types of IOMMU/SMMU on QNX Hypervisor reference boards.

Renesas R-Car and other boards with the same IPMMU hardware

On these boards the syntax for smmu_type_parm is as follows:

paddr,fault_vector,{,socid.revid}

paddr: The physical address of the main memory IPMMU unit registers.
fault_vector: The interrupt that occurs when an illegal DMA request is attempted.
socid: A SoC identification number supported by the configuration data.
revid: A supported revision number of the SoC supported by the configuration data.

For example:

smmu rcar3 0xe67b0000,228,0x4f.0x01,0x4f.0x10,0x4f.0x20

where 0xe67b0000 is the physical address of the main memory IPMMU unit registers, 228 is the interrupt that occurs when an illegal DMA request is attempted, and 0x4f.0x01, 0x4f.0x10 and 0x4f.0x20 are the ID and revision numbers of SoCs supported by the configuration data.

On these boards the syntax for smmu_unit_parm is as follows:

paddr,intr_status_bit

paddr: The physical address of the IPMMU unit registers.
intr_status_bit: The bit number in the interrupt status register where this unit has encountered a fault condition.

On these boards the syntax for smmu_use_parm is as follows:

utlb

utlb: The micro-translation lookaside buffer (TLB) number to use for the device.

Boards with Intel VT-d IOMMU hardware

On these boards the syntax for smmu_type_parm is as follows:

require | ignore

require: The VT-d information must be present in the ACPI tables.
ignore: Ignore ACPI information.

On these boards the syntax for smmu_unit_parm is as follows:

vtd-paddr

vtd-paddr: The base physical address of the VT-d device registers for the unit.

On these boards no value is required or permitted for smmu_use_parm.

Note:

The most common way to start smmuman for x86 systems is:

smmuman smmu vtd

This startup configures smmuman to use the default ACPI tables, and the default locations for VT-d.

Description:

The SMMU manager (smmuman) works with the IOMMUs or SMMUs on supported hardware platforms to:

manage guest-physical memory to host-physical memory translations and access for non-CPU initiated reads and writes (i.e, for DMA devices).
ensure that no pass-through device can access host-physical memory outside its mapped (permitted) host-physical memory location

Textual substitutions

As it reads through its configuration information, smmuman performs textual substitutions to its configuration information when it encounters the following character sequences:

$env{envvar}: Replace the text string with the contents of the envvar environment variable.
$asinfo_start{asinfo_name}: Replace the text string with the start address of the system page asinfo entry specified by asinfo_name.
$asinfo_length{asinfo_name}: Replace the text string with the length of the system page asinfo entry specified by asinfo_name.

You can use this textual substitution to make your configuration more robust by having the host startup place values in the system page asinfo entry where they can be picked up by smmuman.

For more information about the system page asinfo data structure array, see the “System Page” chapter in Building Embedded Systems.

For information about using smmuman in a QNX Hypervisor system, see “DMA device containment (smmuman)” in the “Using Your Hypervisor System” chapter.