Running and usage

The Emul8 framework provides an API which allows the user to create, assemble and run software models of the hardware to be emulated.

The models are mostly written in C# (although other mono runtime languages can also be used).

Using the framework - including assembling new platforms - does not, however, require the knowledge of programming languages, as assembling and manipulating platforms and emulating them can be done through emulation scripts and configuration files, as described in the Emulation files section.

Note

For experienced users, the possibility to write models in C# is a good means to implement things beyond the scope of emulation scripts (which can do what the API provides). However, the scripts are the preferred way to achieve most goals.

Running Emul8

To run Emul8, use the run.sh script, with the optional file parameter and following options:

-p

Run in plain mode (do not output colours).

-d

Run in Debug mode (more debug information, but slower). Remember to use build.sh -d first.

-e command

Execute the given command on startup. This option cannot be used together with the file parameter.

-P port

Instead of opening a Monitor window, listen on a specified port for commands.

--disable-xwt

Disable XWT GUI support (requires -P). This is useful when running Emul8 on machines that does not provide X11 server.

--hide-monitor

Do not show a monitor window on startup.

--hide-log

Do not show log messages in a console.

-h

Display usage & help information.

file is an optional argument - path to a script that should be loaded on startup.

Monitor

The monitor (CLI) exposes the Emul8 API in the form of objects and methods which can be used like a scripting language. There are also some special helper commands.

After running the CLI (see Running Emul8) you will see the git branch and version denotation of the build you are using, copyright and prompt:

Emul8 Framework, version X.X.X.X (branchname-xxxxxxxxxxxxxxxxxxxxx)

(monitor)

The (monitor) part denotes the Context you are in.

The <TAB> key provides auto-completion - you can use it whenever you are unsure what to type. Hitting <TAB> on an empty terminal will just list all available commands and objects at that moment.

If you want to manipulate a machine/peripheral or object, write <object_name> and press <TAB> to see all available options.

Typing any command with incorrect parameters will print a help string, so do not be afraid to experiment.

Issuing help will print all available helper commands with a short description. You can get further help for any command using help <command_name>.

Some more commonly used commands also have short, usually single-letter, aliases.

Apart from typing commands interactively, you can also execute them from a script - see the include command and the Emulation files section.

Context

The monitor is contextual with regard to machines, i.e. if you want to manipulate any peripheral which is part of a given machine, you have to enter its context, which is always shown in the prompt. The initial context after turning on the CLI is always (monitor).

Changing the context can be done using the mach set <machine_name> command first.

mach add <machine-name> lets you create a new machine, but note that its context is not entered automatically.

mach create is a shortcut which lets you create a machine with an automatically assigned name and enter its context automatically.

You can use mach to list all available machines.

Once in the context of a given machine, you can access its peripherals. All peripherals are stored in a tree-like structure, with the root being a system bus, available in the machine’s context under the name sysbus. To access them from the Monitor, you can provide their whole path, e.g. sysbus.gpioPortA.led. The Monitor simplifies access to peripherals with tab completion. You may try it by typing sysbus. and pressing <TAB>.

Since it is tiresome to type fully qualified peripheral names every time, a using helper command has been implemented - you will probably find yourself typing using sysbus quite often.

Command descriptions

allowPrivates

allow private fields and properties manipulation.

short: privs

analyzers
shows available analyzers for peripheral.
createPlatform

creates a platform.

short: c

execute
executes a command or the content of a variable.
help

prints this help message or info about specified command.

short: ?, h

include

loads a monitor script, python code or a plugin class.

short: i

log
logs messages.
logFile

sets the output file for logger.

short: logF

logLevel

sets logging level for backends.

Level Name
-1 NOISY
0 DEBUG
1 INFO
2 WARNING
3 ERROR
mach

list and manipulate machines available in the environment.

mach set <name>
Enable the given machine.
mach add <name>
Create a new machine with the given name.
mach rem <name>
Remove a machine.
mach create
Create a new machine with a generic name and switch to it.
mach clear
Clear the current selection.
macro
sets a macro.
numbersMode

sets the way numbers are displayed.

Options:

  • Hexadecimal
  • Decimal
  • Both
path

allows modification of internal ‘PATH’ variable.

path set <PATH>
Set PATH to the given value.
path add <PATH>
Append the given value to PATH.
path reset
Reset PATH to it’s default value.
pause

pauses the emulation.

short: p

peripherals

prints list of registered and named peripherals.

short: peri

python

executes the provided python command.

short: py

quit

quits the emulator.

short: q

require
verifies the existence of a variable.
runMacro
executes a command or the content of a macro.
set
sets a variable.
showAnalyzer

opens a peripheral backend analyzer.

short: sa

start

starts the emulation.

short: s

start <PATH>
just like include <PATH>, but also start the emulation.
string

treat given arguments as a single string.

short: str

using

expose a prefix to avoid typing full object names.

using -
Clear all previous using calls

Example: using sysbus.gpioPortA

verboseMode
controls the verbosity of the Monitor.
version
shows version information.