Command Line Interface
The command line interface (CLI) is easy to use and provides built in help for different commands. To start the command line tool do the following (assuming you are running bash).
# Set the PATH to include the temu command line application
$ PATH=/opt/temu/bin:$PATH
# Start TEMU
$ temu
no such file: '~/.config/temu/init'
no such file: './temu-init'
temu>As can be seen above, the command line tool complains about two
missing files. These are nothing to bother about at the moment. But
the files are used to automatically run a set of commands when you
start the temu tool.
It is possible to get a list of commands by typing help. Help for
an individual command (including lists of arguments the command takes)
can be produced by typing help CMDNAME.
Command Line Interface Options
The command line interface support the execution of non-interactive batch sessions via the` --run-*` flags. Multiple run flags can be given to have scripts executed in order. On the first error in a script, TEMU will terminate and not proceed with the next script.
--run-commands [filename]-
Run the temu command-script (CLI-script) in the given file in non-interactive mode. You can provide this option multiple times to execute multiple scripts in sequence. When the last script finishes, the emulator will quit.
--run-command-string [cmd]-
Run [cmd] as a single command as if typed in the interactive command line.
--run-script [filename]-
Run the Python script in the given file in a non-interactive temu-session. The option can be provided multiple times, and scripts will be executed in the sequence they are given on the command line.
--interactive-
Enter interactive mode after processing '--run*' flags. Note that any failed scripts will still terminate TEMU before the interactive mode is entered.
--install-license [filename]-
Install a license file.
--revoke-license [license-id]-
Revoke an installed license.
--list-licenses-
List all installed licenses
When running both CLI scripts and Python scripts, the order will be as specified in the arguments to temu. It is possible to run a Python script first, followed by a CLI script or the other way around.
It is also possible to specify a list of scripts without the
--run-commands`/--run-script` flags above, in that case the file type is
inferred by the file extension, where the extension .temu will be
treated as a temu script and the .py extension as a Python
script. Passing file names this way will also result in a
non-interactive session.
Command Syntax
Normally commands are named by a noun-verb format (but there are abbreviations as well). Commands take either a set of named arguments, but some (like the help command) also take positional arguments. In the named format, each argument is separated by a space, and defined using key-value pairs as e.g. help command=memory-assemble.
Variables
The command line allows for variables to be set. These can be set
using the var-set command. Variables are expanded if they are
given as argument values to commands. When used, variables are
referenced as $var or ${var}.
Help Command
Each command is self-documenting, typing help will show a list of
available commands. Typing help command=memory-assemble will show
the detailed help for the memory-assemble command, including all
arguments and their types.
Commands
This section list some of the commands provided in the CLI. A full list can be generated by running the help command.
Checkpointing Commands
There are two commands for working with checkpoints, the save and restore command.
- checkpoint-restore
-
This command restores a serialised checkpoint from a file. The read file should be a JSON file written by the save command.
- checkpoint-save
-
The save function writes a checkpoint in JSON format to disk. Memory content is typically dumped as raw data in a binary blob (in an auxiliary file). The endianess of this blob is for RAM and ROM contents in the standard models is in host order where the unit size is the word size of the target. For the SPARCv8 target on an x86-64 host this means that the data is stored as sequence of little endian 32-bit words.
Memory Commands
- memory-assemble
-
This command assembles a string into memory.
- memory-disassemble
-
This command disassembles memory contents. As assemblers are target dependent the command takes a CPU object as a parameter.
- memory-load
-
Load executable file (srec or elf). The Command automatically detects the format of the file by both extension and binary analysis.
- memory-read
-
Read memory and write it to the console.
- memory-write
-
Modify memory content.
- memory-map
-
Map object to memory space. The command assigns an object to an address range in the memory space.
Object Commands
When dealing with the emulator object system in the CLI, there are a number of commands that are useful. These include the following.
- object-create
-
Creates an object, the command takes two or three parameters. The class parameter indicates the class of the object to be created, name indicates the object name (this name should be unique) and the third optional parameter args allows you to list a number of arguments formatted as name:value pairs in a comma separated list. The arguments are class specific, consult the class documentation on the allowed arguments.
Example:
object-create class=Leon3 name=cpu0 args=cpuid:0- object-connect
-
Connect two objects together. The command connects an object reference property to an interface provided by another object. The command takes two parameters, parameter a is the property formed as
objname.propname, parameter b is the interface reference that the property should refer to, this is formed asobjname:ifacename.
Example:
connect a=cpu0.memAccess b=cpu0:MmuMemAccessIface
connect a=cpu0.memAccessL2 b=mem0:MemAccessIface- object-info
-
This command prints the properties in an object.
- object-list
-
List the names of all objects created with object-create.
- object-prop-write
-
In order to assign property values using the property read and write mechanism this command provides that functionality. Depending on the model, a write may have side-effects (by invoking a write handler), side-effects are documented in the model manuals.
Plugin Commands
There are several commands in the CLI that helps you deal with and to
load plugins. All of these commands have the prefix plugin-.
- plugin-append-path
-
Add path to plugin search paths
- plugin-load
-
Load a plugin
- plugin-remove-path
-
Remove path from plugin search path
- plugin-show-paths
-
Print the search paths for plugins
- plugin-unload
-
Unload a plugin