Command Line Interface

It is recommended that TEMU is added to your PATH variable, e.g.:

$ PATH=/opt/temu/2.2.0/bin:$PATH

Then create a directory for the rest of the tutorial:

$ mkdir tutorial && cd tutorial

TEMU is started by running the temu command:

$ temu
:info:: no such file: '/home/johndoe/.config/temu/init.temu' (1)
:info:: no such file: './temu-init.temu' (2)
temu>
1 Missing user-global start-script, can be added by user.
2 Missing directory local start script, can be added by user.

As can be seen, two messages are printed about missing start up scripts.

For now, simply type in the quit command and then return. Now, lets create a simple TEMU start-up script in the tutorial directory:

$ echo 'echo "Hello Emulator"' > temu-init.temu
$ cat temu-init.temu
echo "Hello Emulator"
$ temu
:info:: no such file: '/home/maho/.config/temu/init.temu'
Hello Emulator
temu>

As can be seen, the TEMU start-up script is now executed. We can now create a LEON3 device by executing the leon3.temu script in /opt/temu/latest/share/temu/sysconfig. The sysconfig directory is automatically available for the exec command in TEMU:

temu>
exec leon3.temu
:info: rom0 : map device at 0x00000000 – 0x00100000
:info: ram0 : map device at 0x40000000 – 0x48000000
:info: ftmctrl0 : map device at 0x80000000 – 0x80000100
:info: apbuart0 : map device at 0x80000100 – 0x80000200
:info: irqMp0 : map device at 0x80000200 – 0x80000300
:info: gpTimer0 : map device at 0x80000300 – 0x80000400
:info: ahbstat0 : map device at 0x80000f00 – 0x80001000
:info: apbctrl0 : map device at 0x800ff000 – 0x80100000
:info: ahbctrl0 : map device at 0xfffff000 – 0x00000000
0.000000: warning: cpu0 : sanity check: dCache not connected
0.000000: warning: cpu0 : sanity check: iCache not connected
0.000000: warning: cpu0 : sanity check: machine not connected
:warning: mem0 : sanity check: faultyHandlers not connected
:warning: mem0 : sanity check: postTransaction not connected
:warning: mem0 : sanity check: preTransaction not connected
:warning: mem0 : sanity check: upsetHandlers not connected
:warning: mem0 : sanity check: user1Handlers not connected
:warning: mem0 : sanity check: user2Handlers not connected
:warning: mem0 : sanity check: user3Handlers not connected

As can be seen above, when creating the LEON3, a number of messages are printed. The first sequence of info messages tell you that a device has been mapped into simulated memory. The next number of messages are warnings. They are emitted due to non-connected interface references in some device models.

As the default LEON3 script does not connect any cache models, the warnings are nothing to worry about in this case.

<time>: <severity> : <object> : <message>

The timestamp is the current time of the objects time source if it has one. The severity is one of several severity levels, including: debug, info, warning, error and fatal.

The fatal message type is combined with an abort call. Hence, the emulator will terminate after emitting the message. These messages are of great use when debugging models.

The object is the name of the object that emits the message. The message is any text string.

The warnings above are emitted by the objsys-check-sanity command. We can get help for this command by using the help command:

temu> help objsys-check-sanity
Command 'objsys-check-sanity'
    Check sanity of object system
Options:
    NONE
Aliases:
    objsys-check-sanity

If you type the objsys-check-sanity command, the same warnings will be printed. You can also use tab completion for commands.

Try:

objs Tab c Tab

And you will see that the command is completed.

You can get a full list of commands by typing help without any arguments.

Two interesting commands are: class-list, and object-list. These will list classes and objects that are registered with the TEMU object system. Another command, which is useful is the class-info command. The class-info command takes the argument class=ClassName. It prints out properties, interfaces and ports that the class provides. Go ahead, try out class-info class=Leon3.

Correspondingly, an object can be inspected by using the object-info command. Try object-info obj=cpu0.

As you may notice, argument names for commands, and certain argument values.

Although, commands are often shortened with nicer to type aliases, most commands have a full noun-verb name. Thus, it is possible to to get all CPU related commands by typing cpu-Tab.

temu> cpu-<TAB>
Completions:
  cpu-disable-trap-events
  cpu-enable-trap-events
  cpu-reset
  cpu-run
  cpu-set-pc
  cpu-set-reg
  cpu-show-regs
  cpu-step
temu> cpu-show-regs cpu=cpu0
%g0 = 0x00000000
%g1 = 0x00000000
%g2 = 0x00000000
%g3 = 0x00000000
%g4 = 0x00000000

Commands in TEMU are structured around the form:

noun-verb-command-name arg=value arg2=value

Note that arguments are typed (e.g. object name, string, file name, integer, real number et.c.). This means that if you type tab for completing an object argument, the object name will be completed. The same goes for file names.

Now, let us try something more fun. Copy the rtems-hello.c file to your tutorial directory. Compile it and convert it to a ROM image.

$ cp /opt/rtems-4.10/src/samples/rtems-hello.c ./
$ PATH=/opt/rtems-4.10/bin:$PATH
$ PATH=/opt/mkprom2:$PATH
$ sparc-rtems-gcc rtems-hello.c -o rtems-hello.elf
$ mkprom2 rtems-hello.elf -o rtems-hello.prom
$ temu
temu> exec leon3.temu
temu> load obj=mem0 file=./rtems-hello.prom
:info: mem0 : loading big-endian sparc 32-bit
:info: mem0 : loading segment 1/1 0x00000000 - 0x00015de0 pa = 0x00000000
temu> run time=10.0
MkProm2 boot loader v2.0
Copyright Gaisler Research - all rights reserved
system clock : 50.0 MHz
baud rate : 19171 baud
prom : 512 K, (2/2) ws (r/w)
sram : 2048 K, 1 bank(s), 0/0 ws (r/w)
decompressing .text to 0x40000000
decompressing .data to 0x40022200
decompressing .jcr to 0x400233c0
starting rtems-hello.elf
:target/warning: irqMp0 : read unknown register @ 0x80000220
Hello World
Hello World over printk() on Debug console
1.276503: info: cpu0 : error mode due to 'trap_instruction' trap
(tt = 0x80) @ 0x40004a74

As you see, the output on the serial port is displayed on the console output. There are two items to note in the output above. Firstly, an error message about a read from an unknown register. This is expected behaviour, as there are two IRQ controllers from Cobham Gaisler, but in RTEMS (and Linux), the same driver is used for both the controllers. The message can be ignored in this case. Secondly, at 1.276503 seconds, cpu0 enters error mode (which means the CPU halts execution due to a trap being raised while traps are disabled), the type of trap is 'trap_instruction', with the %tbr.tt field being 0x80. The instruction causing the trap is located at address 0x40004a74. As the emulator comes with an embedded assembler and disassembler, we can disassemble this instruction:

temu> disassemble cpu=cpu0 addr=0x40004a74
40004a74 040004a74 91d02000 ta %g0 + 0

If you disassemble the hello binary with the objdump tool, we can locate the function that executes the trap instruction:

$ sparc-rtems-objdump -d rtems-hello.elf | less

In less you can search by typing /<search string>, so typing /40004a74 gives us a hit in the syscall function and will display the same code you can see with the built-in TEMU disassembler. The trap here is actually fully expected, as the rtems-hello application call the exit(0) at the end. To simulate the normal behaviour of exit(), RTEMS ensures that the CPU enters error mode.