Getting Started

Installation

To install TEMU, the best approach is to use the RPM or DEB files. The latest versions can be downloaded from https://temu.terma.com/.

The following table illustrates which packages should be used on which operating system. Normally generic packages are available. For some older systems specific packages may be available.

Table 1. Installation Package Suggestions
OS	Package Type
CentOS	.rpm
Debian	.deb
RedHat Enterprise Linux (RHEL)	.rpm
SUSE Linux for Enterprises (SLES)	.rpm
Ubuntu	.deb
Others	.tar.bz2

The following commands can be used to install the different types of packages (where x.y.z is the version number):

# Install RPM
$ rpm -ivh temu-x.y.z-x86_64-Linux.rpm

# Install DEB
$ dpkg -i temu-x.y.z-x86_64-Linux.deb

# Install Tarball (.tar.bz2)
$ bunzip2 temu-x.y.z-x86_64-Linux.tar.bz2
$ tar xvf temu-x.y.z-x86_64-Linux.tar

By default, the packages install TEMU in /opt/temu/latest. The packages have also been created and bundled with all the normal dependencies they need. This include the standard C++ libraries, so there should be no problem to install and run the emulator on any Linux system. Note that testing is normally done on stable Debian (currently Jessie/8.0), RHEL7 and SLES11.

TEMU consist of a set of libraries and a command line tool. The libraries are normally installed in /opt/temu/latest/lib and the tools in /opt/temu/latest/bin/. The binaries and libraries have been liked with the RPATH option, so there is no need to set LD_LIBRARY_PATH.

There are also packages for a build which has asserts enabled. Asserts have a performance penalty, which at times can be heavy. Therefore, assert builds are opt-in. These packages installs under: /opt/temu/latest+asserts/

TEMU Setup

Before you start, you need to setup TEMU. The TEMU setup command, will create a temu-group on the system and add the current user to the group.

TEMU setup is using the temu command line tool:

$ sudo temu --setup

This command should preferably run using sudo. Using sudo, will ensure that the current user (the one invoking sudo) is added to the temu-group. If running the command as root, the root user will be added to the temu-group instead.

In case sudo is not available for your user, a sysadmin with root or sudo access needs to run the command.

In this case, the system administrator should add the user to the temu-group manually.

This can be done by running the following command as root:

usermod -a -G temu jdoe

Licenses

License Files

See https://temu.terma.com/ for more information on licenses. Note that you must have a valid license to run TEMU.

Making Sure the TEMU Group is Available

If the setup command was just executed, it is likely that license installation detailed in Installing a License will fail as the current shell will not be aware of the newly created temu-group.

To ensure that the newly created temu-group, where the user has been added, is made available to the current user it is possible to either logout and login, or one can run the following commands in the current shell:

exec newgrp temu (1)
exec newgrp - (2)

1	Replace the current shell with one using temu as the primary group.
2	Replace the shell using temu as the primary group with one using the default group.

Installing a License

Do not run the commands in this section as root. They are intended to be executed by a user in the temu-group. See TEMU Setup and Making Sure the TEMU Group is Available for more info.

A TEMU license is installed using the temu command line tool:

# DO NOT RUN THIS AS ROOT
$ temu --install-license my-license-file.json

It is possible to install multiple license files for the same user (e.g. to enable multiple machines).

Revoking a License

To revoke a license in case of e.g. hardware migration, you should issue the revoke command on a license. To get the license ID, use the --list-licenses option to TEMU:

$ temu --list-licenses
| License ID       | Status
|------------------|----------------------------------------
| 123456789abcedf0 | hardware address error, installed
| abcdef0123456789 | valid, installed

Above you can see two licenses, one which does not match the current computer (hardware address error). To revoke a license for the current computer you should revoke a valid license. Typically, invalid licenses will be either marked as hardware address error or expired for time bounded licenses.

Next step is to revoke the license using the relevant license ID as listed above:

$ temu --revoke-license abcdef0123456789
------------------------- IMPORTANT NOTICE -------------------------
You are about to revoke a license, a revoked license invalidates the
license from use on your machine. A response code will be generated that
should be sent to Terma in order to be credited one license activation
NOTE: License revokations are only intended for use when retiring hardware
Revocations cannot be used to simulate a floating license, revocatiosn are
limited in numbers and excessive use is not allowed.
NOTE: In case of catastrophic failure of hardware, it may not be
possible to revoke the license, in that case you need to contact Terma
for an activation credit

Are you sure you wish to revoke the license (yes|no)?

Answer yes if you wish to proceed:

Revokation key: '123456789abcdef0...:abcdef0123456789...'
Send the key to Terma in order to be credited with one license activation
NOTE: You cannot use revocations as floating licenses, they are intended for
      hardware migration only.

Then copy the key and send it to Terma to be credited with one license activation.

License Server

An alternative to the node-locked licenses described in License Files, are floating licenses.

Floating licenses require a license server to be running locally. The license server can be downloaded at https://tgss.terma.com/. Installation instructions for the license server are available here.

To use the license server from TEMU, create a file here (this is a per user setting): ~/.config/tgss/app/lm/config.yaml

The file should look like the following:

server: "my-license-server.example.com:8080"
user: admin
password: password

In this case we use the default license manager user name and password, that should be changed using the license server web interface.

Now a license can be checked out from the server as follows with the TEMU command line:

License Checkout with TEMU Command Line

license-checkout pool='68728ED0-09D6-4732-BE8B-E51D426BC08B'

Licenses are checked out on a per-user-machine combination, and only one license can be the current one.

The command above can of-course be run using the temu_execCommand() function.

The pool-id is a UUID string, which can be determined using the license server web interface.

A checked out license can be released manually as follows:

License Checkout with TEMU Command Line

license-release

Floating licenses are automatically released after 24 hours.

Running the Emulator

To start the command line interface (CLI), simply run: /opt/temu/latest/bin/temu or /opt/temu/latest+asserts/bin/temu. The command line interface exists to run the emulator in stand alone mode.

Creating a New Machine

When TEMU is running it will normally display the temu>-prompt. This is the command prompt.

To create a new machine, it is possible to use one of the bundled CPU configurations in /opt/temu/latest/share/temu/sysconfig/. Common configurations that instantiate different types of systems are available. The command line scripts can be executed using the exec command. This can be done as illustrated in the following examples:

Create a LEON2 System

temu> exec leon2.temu

Create a Dual Core LEON3 System

temu> exec leon3-dual-core.temu

Loading and Running Software

When a system has been created, it is time to load and run software in the emulator. The example here assumes that the system was created as in the previous example. To load software which may be in ELF or SREC format the load-command can be used.

When running application software directly, as in contrast to have it loaded by boot software. Then the user needs to ensure that the boot software is simulated. This includes initializing the stack and frame pointers. On some systems timer registers must be initialized.

Execution of software in a single core system can be done by the run and step commands. The run-command runs the software for a given time (either cycles or seconds), while the step-command single steps the software instruction by instruction. The run and step commands can run and step both machines, clocks and CPUs.

Load and Run Software Image

temu> load obj=cpu0 file=rtems-hello.elf
info: cpu0 : loading section 1/1 0x40000000 - 0x4001ec20 pa = 0x40000000
temu> set-reg cpu=cpu0 reg="%fp" value=0x407ffff0
temu> set-reg cpu=cpu0 reg="%sp" value=0x407fff00
temu> run obj=cpu0 pc=0x40000000 time=10.0

It is assumed that the user have access to application software and / or cross compilers and is familiar with how to use these tools.