// Copyright (c) 2017-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

:uri-xdg-basedir: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

[[runtime-interaction]]
== Runtime Interaction

This section discusses the various requirements for the loader and an OpenXR
runtime to properly interact.


[[runtime-discovery]]
=== Runtime Discovery

OpenXR may have a choice of multiple runtimes on a user's system.
The selection of the active runtime is handled external to the loader.
The loader is responsible for discovering only the active OpenXR runtime on
the system, and loading it properly.
The standard process in which the loader discovers the active runtime on a
system is platform dependent.


[[active-runtime-information]]
==== Active Runtime Information

The means of identifying the active runtime used by an OpenXR application
vary based on the underlying operating system and is detailed in the
sub-sections below.
This information is also important if the active runtime needs to be changed
by an external entity (on those platforms that support updating).

[[linux-active-runtime-location]]
===== Linux Active Runtime Location

On Linux, the active runtime information is contained inside a
JSON-formatted file located in a standard {uri-xdg-basedir}[XDG
configuration directory] or the system's standard global configuration
directory (typically `/etc`), under the relative path:

```
openxr/<major_api_version>
```

`__<major_api_version>__` should be replaced with the integer value for the
corresponding OpenXR API version.

Two JSON file names are checked in each directory.
First, the loader looks for `active_runtime.__<arch>__.json`, where
`__<arch>__` is an architecture and ABI specifier from the
<<architecture-identifiers>> table.
If no such file is found, `active_runtime.json` is then checked.
The JSON file contains the necessary information on how OpenXR components
can load the appropriate runtime library.

For example, a globally-configured OpenXR 1.x active runtime file on an
x86_64 PC might be at:

```
/etc/xdg/openxr/1/active_runtime.x86_64.json
```

When multiple such files exist, `XDG_CONFIG_HOME` is preferred, followed by
the elements of `XDG_CONFIG_DIRS` in order, followed by the system's global
configuration directory.
Both filenames are tested in a given directory before moving on.
This allows the user's preference to easily override a global default.

[NOTE]
.NOTE
====
`active_runtime` filenames may be a symbolic link to a file with a
runtime-specific name, for ease of runtime switching and enumeration by the
user or system tools.
See <<linux-installed-runtimes-enumeration>> for more information.
====

[[windows-active-runtime-location]]
===== Windows Active Runtime Location

The Windows OpenXR active runtime information is located in the Windows
Registry (not to be confused with the OpenXR registry) under the key:

```
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\<major_api_version>
```

Where `__<major_api_version>__` should be replaced with the integer value
for the corresponding OpenXR API version.

[NOTE]
.Important
====
If using a 32-bit application on a 64-bit Windows install, "WOW6432Node" is
added before "SOFTWARE" in the preceding path as follows:

```
HKEY_LOCAL_MACHINE\WOW6432Node\SOFTWARE\Khronos\OpenXR\<major_api_version>
```
====

This means that the complete registry path to the OpenXR 1.x active runtime
registry value is:

```
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1
```

Under that registry key, the value "ActiveRuntime" is defined as a string
value and should be defined to full directory path of the runtime's JSON
file.

An example "ActiveRuntime" value might look something like the following:

```
C:\windows\system32\my_system_runtime.json
```

[[android-active-runtime-location]]
===== Android Active Runtime Location

The Android OpenXR active runtime data, equivalent to the contents of a
runtime manifest JSON file, is determined by a ContentProvider.
Vendors producing Android-based devices where only a single runtime would
make sense may consider implementing the "System" content provider directly.
Others can use a working-group-provided installable "RuntimeBroker"
implementation of the content provider and associated preference UI, and
will only need to add metadata to their manifest file as described in
<<android-runtime-metadata>>.
The RuntimeBroker package's responsibility is to externalize runtime finding
logic and the runtime state user preferences.

An OpenXR runtime selection ContentProvider responds to one of two
authorities:

* `org.khronos.openxr.runtime_broker` - For use only by the
  working-group-provided package with the user preferences activity.
  This should not be installed or modified by vendors: it will be
  distributed through typical end-user channels for application packages and
  is intended for user-controlled installable (e.g. plug-in) devices.
  Read access is guarded by a permission of "normal" protection level named
  `org.khronos.openxr.permission.OPENXR`.
* `org.khronos.openxr.system_runtime_broker` - This may be provided by
  vendors in system-installed packages.
  Read access is guarded by a permission of "normal" protection level named
  `org.khronos.openxr.permission.OPENXR_SYSTEM`.

The installable RuntimeBroker content provider defines the permission group
`org.khronos.openxr.permission-group.OPENXR`, containing the above two
permissions.
The runtime brokers may use their respective permissions to guard read
access to the ContentProvider.
Write permission should not be allowed, or should be limited to explicit
choices by the device user.
The defined URIs for the ContentProvider authorities are as follows:

* `/openxr/__major_ver__/abi/__abi__/runtimes/active` - This URI represents
  a "table" containing at most one item, the currently active runtime.
  The policy of which runtime is chosen to be active (if more than one is
  installed) is left to the content provider.
  No sort order is required to be honored by the content provider.
  Available columns include:
** `package_name` - Name of the package providing the runtime
** `native_lib_dir` - ABI-specific directory containing the runtime's shared
   library
** `so_filename` - The filename to load as the runtime: Combines with
   `native_lib_dir` to provide the absolute path of the shared object.
** `has_functions` - Boolean, if true, it indicates the loader should query
   the `functions/` URI to identify the names of entry points it should
   query.
* `/openxr/__major_ver__/abi/__abi__/runtimes/__package__/functions` - This
  URI is for package-specific function name remapping.
  Since this is an optional field in the corresponding JSON manifests for
  OpenXR, it is optional here as well.
  If the active runtime contains "true" in its "has_functions" column, then
  this table must exist and be queryable.
  No sort order is required to be honored by the content provider.
  __package__ is the package name containing the active runtime.
  Available columns include:
** `function_name` - Corresponds to the "key" in the JSON manifest field.
** `symbol_name` - Corresponds to the "value" in the JSON manifest field.

Within the loader, the results from either content provider are used to
construct an object corresponding to an equivalent JSON runtime manifest
file as used on other platforms.

If no runtime is found this way, as a fall-back, a similar process as on
Linux takes place, searching for `active_runtime.__<arch>__.json` and
`active_runtime.json` files in the following locations in priority order:

1. `/product/etc/openxr/__major_ver__`
2. `/odm/etc/openxr/__major_ver__`
3. `/oem/etc/openxr/__major_ver__`
4. `/vendor/etc/openxr/__major_ver__`
5. `/system/etc/openxr/__major_ver__`

`__<major_api_version>__` should be replaced with the integer value for the
corresponding OpenXR API version, and `__<arch>__` is an architecture and
ABI specifier from the <<architecture-identifiers>> table.
Both filenames are checked in each directory before moving on to the next.

[[android-ipc]]
====== Android IPC and Runtime Access
As Android is a permission-limited environment, additional constraints are
placed on runtimes and applications.
In modern versions of Android, applications cannot query arbitrary packages
for arbitrary services that are not pre-declared in the manifest.
To avoid needing to update application manifests for each OpenXR runtime's
requirements, the intent service name
`org.khronos.openxr.OpenXRRuntimeService` (same as used by installable
runtime discovery) is reserved for use by OpenXR runtimes and their
components.
Similarly, the intent service name
`org.khronos.openxr.OpenXRApiLayerService` is reserved for use by OpenXR API
layers and their components.
To target an API level higher than 29, applications must: include provisions
in their manifest to allow them to query for services with these intent
names.
In turn, runtimes and their components that need to locate their originating
package should: query first for packages providing a service for the
relevant intent, then traverse the list of resolutions to find their own
package.
There is no set API provided by an intent service of this name: it exists
solely as a marker of an OpenXR runtime and as a key for retrieving OpenXR
runtime component packages without needing to perform arbitrary package
queries.
This does pose the risk that an application can view all OpenXR runtimes
installed, rather than only the active one.
However, the number of runtimes per device is likely to be very small, and
this opens the smallest weakness possible to achieve the required
functionality.

[NOTE]
.Note
====
Applications will require the following `<queries>` statements in their
manifest for the loader to locate and load the runtime correctly.
(If building an application using the loader AAR provided by the working
group, beginning with version 1.0.28, these items are included in the AAR
manifest and will be merged into your application manifest automatically.)

[source,xml]
```
<uses-permission android:name="org.khronos.openxr.permission.OPENXR_SYSTEM" />

<queries>
  <provider android:authorities="org.khronos.openxr.runtime_broker;org.khronos.openxr.system_runtime_broker" />
  <intent>
    <action android:name="org.khronos.openxr.OpenXRRuntimeService" />
  </intent>
  <intent>
    <action android:name="org.khronos.openxr.OpenXRApiLayerService" />
  </intent>
</queries>
```

The permission is needed to contact a system broker.
The provider query is to be able to contact system and installable brokers.
The intent query is for runtimes to look up their own package, which is
required when targeting API levels higher than 29.
It is also recommended to include the following, which could be needed for
haptic feedback:

[source,xml]
```
<uses-permission android:name="android.permission.VIBRATE" />
```

Earlier versions of the installable broker also wanted the following
permission, but this is no longer required.
It is harmless to leave it in place, but the broker no longer requires it.

[source,xml]
```
<uses-permission android:name="org.khronos.openxr.permission.OPENXR" />
```
====

[[architecture-identifiers]]
===== Architecture/ABI Identifiers

On platforms such as <<linux-active-runtime-location,Linux>> and
<<android-active-runtime-location,Android>> where the active runtime
manifest may be found by filename, the following table of known
architectures and ABIs is used.

:url-android-ndk-abis: https://developer.android.com/ndk/guides/abis
:url-debian-ports: https://www.debian.org/ports/

[cols="1,1,1,4"]
|===
|Architecture/ABI Identifier |{url-android-ndk-abis}[Android NDK ABI] Name | {url-debian-ports}[Debian Port] Name |Description

|`x32`
  |
  | `x32`
  | 64-bit x86 instructions, using an ILP32 model (32-bit pointers)

|`x86_64`
  | `x86_64`
  | `x86_64`
  | 64-bit x86

|`i686`
  | `x86`
  | `i386`
  | 32-bit x86

|`aarch64`
  | `arm64-v8a`
  | `aarch64`
  | 64-bit ARM architecture, little endian

|`armv7a-vfp`
  | `armeabi-v7a` (See <<android-arm32-note,note>>.)
  | `armhf`
  | 32-bit ARMv7-A architecture, little endian, with hardware floating point and VFP PCS ABI

|`armv5te`
  |
  | `armel`
  | 32-bit ARMv5TE architecture or compatible, little endian

|`mips64`
  |
  | `mips64el`
  | 64-bit MIPS architecture, little endian

|`mips`
  |
  | `mipsel`
  | 32-bit MIPS architecture, little endian

|`ppc64`
  |
  | `ppc64`
  | 64-bit PowerPC architecture, big endian

|`ppc64el`
  |
  | `ppc64el`
  | 64-bit POWER8/POWER9 architecture, little endian (OpenPOWER ELF ABI v2)

|`s390x`
  |
  | `s390x`
  | 64-bit S390/z-Series architecture, big endian

|`hppa`
  |
  | `hppa`
  | 32-bit HP PA-RISC architecture, big endian

|`alpha`
  |
  | `alpha`
  | 64-bit Alpha architecture

|`ia64`
  |
  | `ia64`
  | 64-bit IA-64 architecture

|`m68k`
  |
  | `m68k`
  | 32-bit Motorola 68000-based architecture, big endian

|`riscv64`
  |
  | `riscv64`
  | 64-bit RISC-V architecture, little endian

|`sparc64`
  |
  | `sparc64`
  | 64-bit SPARC architecture

|===

[[android-arm32-note]]
Note: The preceding table defines `armv7a-vfp` as the architecture/ABI
identifier for 32-bit ARM in Android.
While the Android ABI called `armeabi-v7a` does not use VFP PCS as the
__system__ ABI, a definition in `openxr_platform_defines.h` enables the VFP
PCS calling convention for all OpenXR API calls and function pointers.

[[runtime-enumeration]]
==== Runtime Enumeration

When multiple runtimes are installed on a system, the OpenXR loader will
find the currently active runtime using the mechanism described before.

At that point, the loader will act as if this runtime is currently the only
installed one.

To be able to allow additional tooling to discover other runtimes that are
installed, but currently are not the active runtime on the system, each
runtime should register the path to their manifest in a platform-dependant
way in a list of "available runtimes".

Runtime manifest files may optionally contain a `"name"` field.
Tools that allow users to configure what runtime is currently active should
display this user-friendly name if present when referring to the runtime in
question.

===== Windows Installed Runtimes Enumeration

On Windows, the available runtimes' information is located in the Windows
Registry.

It can be found under the key:

```
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\<major_api_version>\AvailableRuntimes
```

Each installed runtime should add a `DWORD` value under that key.
The `DWORD`'s name is the full path to the runtime's manifest

Similarly to how Implicit API layers can control their activation state in
the registry, as described in <<windows-manifest-registry-usage>>:

* A value of `0` indicates that the runtime can be discovered by tools that
  want to enumerate all installed runtimes.

* A non-zero value may be used if the runtime wants to disable itself from
  enumeration (for example, if hardware configuration, or first time setup
  hasn't been run by the user yet).

For instance, the OpenXR 1.x runtime used as an example in section
<<windows-active-runtime-location>> would add a `DWORD` value in:

```
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenXR\1\AvailableRuntimes
```

With the name:

```
C:\Windows\system32\my_system_runtime.json
```

And set it to `0`.

All considerations for 32 bit platforms mentioned in section
<<windows-active-runtime-location>> still apply.

Tools that want to change the currently `ActiveRuntime` should not modify
the list of `AvailableRuntimes`, but rather copy the path to the correct
location.

[[linux-installed-runtimes-enumeration]]
===== Linux Installed Runtimes Enumeration

As previously defined, the OpenXR configuration on Linux is either stored in
a standard XDG configuration directory, or the system-wide configuration
directory.

Aside from the currently active runtime, installed runtimes that make
themselves available for enumeration should install their runtime manifest
into one of these directories, using any name suitable.

Rules about precedence in different directories for runtime enumeration
follow the same rules as in section <<linux-active-runtime-location>> for
selecting the folder containing the active runtime manifest.

Tools that want to change the current active runtime should only update the
`active_runtime.__<arch>__.json` and/or `active_runtime.json` symlink to the
active runtime, and not move, copy, or delete any other files.

[[runtime-manifest-file-format]]
==== Runtime Manifest File Format

As mentioned before, the OpenXR loader on Windows and Linux uses manifest
files to discover the active runtime.
The loader only loads the actual runtime library when necessary.
Because of this, the manifest files contain important information about the
runtime.
The JSON file itself does not have any requirements for naming, beyond the
requirement of using the ".json" extension.

Here is an example runtime JSON manifest file:

[example]
.Runtime Manifest
====
[source,json]
----
{
   "file_format_version": "1.0.0",
   "runtime": {
      "name": "openxr_sample_runtime",
      "library_path": "./dbuild/src/impl/libopenxr_sample_impl.so"
   }
}
----
====

.Runtime Manifest File Fields

[options="header",cols="20%,10%,70%"]
|====
| Field Name    | Required | Field Value
| "file_format_version"
    | Yes
        | The JSON format major.minor.patch version number of this file.
        Currently supported version is 1.0.0.
| "runtime"
    | Yes
        | The identifier used to group all runtime information together.
| "library_path"
    | Yes
        | The "library_path" specifies either a filename, a relative pathname,
        or a full pathname to the runtime's shared library file.  If
        "library_path" specifies a relative pathname, it is relative to the
        path of the JSON manifest file (e.g. for cases when an application
        provides a runtime that is in the same folder hierarchy as the rest of
        the application files).  If "library_path" specifies a filename, the
        library must live in the system's shared object search path. There
        are no rules about the name of the runtime shared library files other
        than it should end with the appropriate suffix (".DLL" on Windows,
        and ".so" on Linux).
| "functions"
    | No
        | This section can be used to identify a different function name for
        the loader to use in place of standard runtime interface functions. The
        "functions" node is required if the runtime is using an alternative name
        for `xrNegotiateLoaderRuntimeInterface`.
| "name"
    | No
        | An optional user-facing name that can be used by tooling to refer to
        this specific runtime.
|====


Vendors may add non-standard fields to their runtime manifest files.
These vendor specific fields must be prefixed with their vendor id (e.g:
`VENDOR_name_of_field`).

[NOTE]
.Note
====
If the same runtime shared library supports multiple, incompatible versions
of OpenXR API, it must have separate JSON files for each API major version
(all of which may point to the same shared library).
====


[[runtime-manifest-file-version-history]]
===== Runtime Manifest File Version History

The current highest supported runtime manifest file format supported is
1.0.0.
Information about each version is detailed in the following sub-sections:

_Runtime Manifest File Version 1.0.0_

The initial version of the runtime manifest file specified the basic format
and fields of a runtime JSON file.
The fields of the 1.0.0 file format include:

* "file_format_version"
* "runtime"
* "library_path"
* "name"
** This is an optional field, added before the OpenXR 1.0.18 release.
   As it is not used by the loader nor does it introduce incompatibility, it
   was added to the format described here without incrementing the manifest
   file format version number.

[[android-runtime-metadata]]
===== Android Runtime Metadata for Installable Broker

The working-group-provided installable RuntimeBroker provides a
ContentProvider matching the specification of
<<android-active-runtime-location>>.
The returned data is determined by a combination of user settings and
package metadata, rather than a JSON manifest file.
To be identified by the RuntimeBroker as an OpenXR runtime, a package must:

* Specify the `<application>` attribute `android:extractNativeLibs="true"`,
  to allow the runtime .so to be loaded dynamically from another package.
* Provide an exported Service (no specific methods are required)
** With an intent-filter for the action name
   `org.khronos.openxr.OpenXRRuntimeService`
** Exposing a meta-data value named
   `org.khronos.openxr.OpenXRRuntime.SoFilename` with the filename of the
   runtime .so file
** Exposing a meta-data value named
   `org.khronos.openxr.OpenXRRuntime.MajorVersion` with the major version
   number of the OpenXR runtime standard supported.
** Optionally exposing meta-data values named
   `org.khronos.openxr.OpenXRRuntime.Functions.__function_name__` with value
   of the symbol name, if any functions to be loaded do not have symbol
   names matching the specification's function name.

For example, the following markup could be added within the `<application>`
tag to expose a runtime with no function name remapping:

[source,xml]
```
<service
    android:name=".MyOpenXRService"
    android:label="@string/service_name"
    android:exported="true">
    <meta-data
        android:name="org.khronos.openxr.OpenXRRuntime.SoFilename"
        android:value="libopenxr_sample.so" />
    <meta-data
        android:name="org.khronos.openxr.OpenXRRuntime.MajorVersion"
        android:value="1" />

    <intent-filter>
        <action android:name="org.khronos.openxr.OpenXRRuntimeService" />
    </intent-filter>
</service>
```

To find a runtime, the RuntimeBroker first retrieves all services that
advertise the `org.khronos.openxr.OpenXRRuntimeService` intent with the
correct `org.khronos.openxr.OpenXRRuntime.MajorVersion` value.
If exactly one runtime is found (and it is not disabled by user preference
in the broker), it is considered the active OpenXR runtime.
If more than one is found, user preferences are used to identify the
"active" runtime.

The path containing the dynamic library is computed from
`ApplicationInfo.nativeLibraryDir` and the specified ABI, and the filename
is returned using the filename found in the OpenXR metadata value.
The "hasFunctions" column is dynamically generated based on the presence of
any function metadata entries.

Note that system-provided runtimes exposed using the "System" content
provider do not need to expose this same metadata, as the implementation of
the system content provider can be used to store and report this
information.


[[loader-distribution]]
==== Loader Distribution

Any application using the OpenXR API is responsible with making sure it can
properly execute on a user's system.
Some OpenXR environments may not use an OpenXR loader but instead provide
libraries which directly link with their runtime.
Other runtime or platform vendors may choose to provide a separate OpenXR
loader for debug or developmental reasons.
Whatever the scenario, if an application uses an OpenXR loader, then that
application is responsible for packaging the OpenXR loader in a location
that will not interfere with other applications.
If an engine or platform provides an OpenXR loader for applications, it
must: provide documentation on how to properly package the necessary files.


[[overriding-the-default-runtime-usage]]
==== Overriding the Default Runtime Usage

There may be times that a developer wishes to ignore the standard runtime
discovery process and force the loader to use a specific runtime.
This could be for many reasons including:

 * Forcing on a Beta runtime
 * Replacing a problematic runtime in favor of another

In order to support this, the loader can be forced to look at specific
runtime with the `XR_RUNTIME_JSON` environment variable.
In order to use the setting, simply set it to the full global path location
of the desired runtime manifest file.

[NOTE]
.Important
====
If the "XR_RUNTIME_JSON" variable is defined, then the loader will not look
in the standard location for the active runtime.
Instead, the loader will only utilize the filename defined in the
environment variable.
====

[example]
.Setting XR_RUNTIME_JSON Override
====
*Windows*

----
set XR_RUNTIME_JSON=\windows\system32\steam_runtime.json
----

*Linux*

----
export XR_RUNTIME_JSON=/home/user/.config/openxr/1/steamxr.json
----
====


[[loader-runtime-interface-negotiation]]
=== Loader/Runtime Interface Negotiation

The OpenXR symbols exported by a runtime must not clash with the loader's
exported OpenXR symbols.
Because of this, all runtimes must export only the following command with
beginning with the `xr` prefix.
This command is not a part of the OpenXR API itself, only a private
interface between the loader and runtimes for version 1 and higher
interfaces.
In order to negotiate the loader/runtime interface version, the runtime must
implement the fname:xrNegotiateLoaderRuntimeInterface` function (or a
renamed version of this function identified in the manifest file).
fname:xrNegotiateLoaderRuntimeInterface` is defined in `openxr.h`.

fname:xrNegotiateLoaderRuntimeInterface` function should be directly
exported by a runtime so that using "GetProcAddress" on Windows or "dlsym"
on Linux, should return a valid function pointer to it (see
<<runtime-exporting-of-commands, Runtime Exporting of Commands>> for more
information).

[NOTE]
.Important
====
Remember, during the call to fname:xrNegotiateLoaderRuntimeInterface, the
runtime must: grab control of the active runtime manifest file.
Functions that should be used to grab control of the manifest file are
defined in the common code as described in the
<<active-runtime-file-management, Active Runtime File Management>> section
of this document.
The runtime must: also determine when to release control of this file.
This may be due to the last instance an application created is destroyed,
the application is exiting, or some period of inactivity occurs.
====


[[runtime-exporting-of-commands]]
==== Runtime Exporting of Commands

The fname:xrNegotiateLoaderRuntimeInterface should be directly exported by a
runtime so that using "GetProcAddress" on Windows or "dlsym" on Linux,
should return a valid function pointer to it.
However, *all other OpenXR entry points* must: either:

 * NOT be exported directly from the runtime library
 * or NOT use the official OpenXR command names if they are exported

This requirement is especially for runtime libraries that include other
functionality (such as OpenGL) and thus could be loaded by the application
prior to when the OpenXR loader library is loaded by the application.

Beware of interposing by dynamic OS library loaders if the official OpenXR
names are used.
On Linux, if official names are used, the runtime library must be linked
with `-Bsymbolic`.


[[runtime-interface-versions]]
==== Runtime Interface Versions

The current Runtime Interface is at version 1.
The following sections detail the differences between the various versions.


[[runtime-interface-version-1]]
===== Runtime Interface Version 1

* Defined manifest file version 1.0.0.
* Introduced the concept of negotiation.
** Requires runtimes to export `xrNegotiateLoaderRuntimeInterface` function.


[[additional-loader-requirements]]
=== Additional Loader Requirements

* The loader must: not call the runtime for `xrEnumerateApiLayerProperties`
* The loader must: not call the runtime for
  `xrEnumerateInstanceExtensionProperties`, if "layerName" is not equal to
  `NULL`.

