Real-Time API v5.1.1

This page describes how to make use of the real-time extension in your Android applications.
Please up the development environment to work for Windows and Linux first by following this guide.
Please take a look at the Benchmark application for a real-world example.

Declaring Real-Time Applications


This section describes how to declare applications such that the Android system is able to identify them as real-time applications. It does not mean that the application will run with real-time priority, but it will prevent the system from killing the application (during a long-term operation or in dangerous out-of-memory situations). Developers may flag whole applications or just selected components to be persistent using the flag <meta-data android:name=”realtime-flag” android:value=”true” /> in the manifest file.

The following manifest file belongs to an application with two activities and two services.

<manifest>
 <application>
    <activity android:name=".Activity1" />

    <activity android:name=".Activity2">
      <meta-data android:name="realtime-flag" android:value="true" />
    </activity>

    <service android:name=".Service1" android:process=":ServiceProcess">
      <meta-data android:name="realtime-flag" android:value="true" />
    </service>  

    <service android:name=".Service2" />
  </application>
</manifest>

As soon as one component of an application process is marked as real-time, all other components of the same process will implicitly be treated real-time. In the example above the main process (encapsulating both activities and the second service), as well as the separated process for the first service are marked as real-time. All application components can be marked as real-time at once by adding the tag to the <application> tag of the manifest file:

<manifest>
  <application>
    <meta-data android:name="realtime-flag" android:value="true" />
  </application>
</manifest>

 

Accessing the Proxy Object


All features of the RTAndroid platform are encapsulated by the RealTimeProxy class. Import the following packages in order to use this class:

import rtandroid.RealTimeConstants;
import rtandroid.RealTimeProxy;

Now you can create the proxy and check the platform’s version:

RealTimeProxy proxy = new RealTimeProxy();
Log.d("MyRTApp", "RTAndroid platform version is: " + proxy.getVersion());

The proxy is the main interface for manipulating properties of the calling process.

Using Real-Time permissions


Add the following lines to your manifest file in order to authorize the application to use the real-time features:

<uses-permission android:name="rtandroid.permission.USE_RT_PROCESSES"/>
<uses-permission android:name="rtandroid.permission.USE_RT_CPU"/>

The USE_RT_CPU permissions allows the app to read and write the cpu state:

  • online / offline
  • power level

While USE_RT_PROCESSES allows the app to change scheduling-related properties of active processes:

  • nice value
  • scheduling policy
  • priority
  • cpu affinity
  • persistency

Scheduling Strategy


By involking the following command you can set the scheduling policy:

proxy.setSchedulingPolicy(RealTimeConstants.SCHED_POLICY_FIFO);

To read the current policy make use of the getSchedulingPolicy() function.

Available strategies are:

  • SCHED_POLICY_NORMAL: The linux default
  • SCHED_POLICY_FIFO: First-in – first-out
  • SCHED_POLICY_RR: Round-robin

You have to set one of the real-time scheduling strategies (RR or FIFO) in before setting a new real-time priority.

Real-Time Priority


The priority is the process’s actual priority used by the Linux kernel. The priority ranges from 0 to 99.

Execute the following commands to raise the priority of the calling thread to real-time:

int prio = 60; // priority value between THREAD_MIN_PRIORITY and THREAD_MAX_PRIORITY
proxy.setPriority(prio);
prio = proxy.getPriority();
Log.d("MyRTApp", "Priority is now " + prio +"\n");

 

Nice value


The niceness value defines how much (userspace) CPU time a certain process will get. The niceness can be changed in the interval of -20 to +19 , where the lower the niceness the higher the priority.

Execute the following commands to lock the niceness of the calling thread:

int nice= 10;
proxy.setNiceValue(nice);
nice = proxy.getNiceValue();
Log.d("MyRTApp", "Niceness is now " + prio +"\n");

 

CPU Power


In order to save/extend battery power, Android reduces the CPU power consumption whenever the device load is low or the display is turned off. This is problematic for applications which require deterministic execution. RTAndroids API offers the lockCpuPower function, which allows you to lock the CPU to a certain power level.

To lock the CPU to the desired powerlevel in percent:

int powerLevel = 50;
proxy.lockCpuPower(powerLevel);
// do work ...
proxy.unlockCpuPower();

The invocation of this method will return the control of the CPU power level to Android.

Working with CPU Cores


The proxy offers three different functions to gather information about the number of CPU cores:

int totalCpuCount  = proxy.getConfiguredProcessors(); // Number of installed cpus
int bootedCpuCount = proxy.getAvailableProcessors();  // Number of active cpus
int[] isolatedCpus = proxy.getIsolatedProcessors();   // Cpus reserved for real-time apps

To check the state of the desired core use:

int cpuCore = 0;
int state = proxy.getCpuState(cpuCore);

All functions take an integer identifier as argument, representing the number of the core.
To ensure the desired CPU is booted use this command:

if (state == RealTimeConstants.CPU_STATE_OFFLINE)
{
    proxy.setCpuState(cpuCore, RealTimeConstants.CPU_STATE_ONLINE);
}

Now you can set the affinity:

int mask = (1 << cpuCore);
proxy.setAffinity(mask);

  • Andreas Urbschat

    Pls, can you clarify what will happen to this project? I am trying to build a front end for children education.
    The Link to your API-Guide is missing…maybe on purpose?!