User documentation

Version 0.39

1. Introduction

emuStudio is a toy-computer emulation platform and framework. A platform, because it supports full emulation "life-cycle". From writing and compiling programs for emulated machine, to running and debugging. A framework, because it provides Java API and documentation which encourages to implement any custom toy-computer, either real or abstract.

It’s free software, released under GNU GPL v2 license. The source code is freely available online. Implementation language is Java SE 8, which makes emuStudio a naturally cross-platform application. The implementation technology of visual components (GUI) is Java Swing.

2. Brief description

Various computers can be emulated. Real computers are assembled using hardware components, which are in the virtual environment represented by plug-ins. All virtual computers in emuStudio can have a compiler, must have one CPU and memory. Devices are optional. The virtual computer model is very similar to von Neumann model.

Plug-ins combinations and computer settings are written in configuration files. Each file represents one single computer. These configurations can be created manually (they’re Java properties files), but more convenient is the abstract schema editor.

Source code editor enables users to write programs for emulated computer. Very related part is compiler, which provides lexical and syntax analysis of the source code for the syntax highlighting. Most compiler plug-ins enable direct transfer of the written code into emulated computer.

Memory plug-ins allow modification of its content, which is immediately seen by CPU.

There exist command line interface which allows automation of emulation. It is useful for running programs without graphical interface - some devices allow gathering input and writing output from/to files.

Errors, and other messages are written in log file. If there is some problem, user can check the log file, or pass it to the issue for analysis by developers of emuStudio.

3. Installation and run

At first, please download emuStudio distribution. It is a ZIP file in the form emuStudio-[VERSION].zip. Unpack the file where you want to have emuStudio installed.

please don’t forget to install Java Runtime Environment (JRE) of version 8 and later.

After unzipping, go to the directory where emuStudio.jar is located, and run it with command from command line:

java -jar emuStudio.jar

3.1. Directory structure

emuStudio has very conservative and strict directory structure, as can be seen in the following list:

  • config/: location of configuration files. Each file represents abstract schema of one virtual (emulated) computer.[1] The files are human-readable.[2]

  • compilers/: location of compiler plug-ins.

  • cpu/: location of CPU plug-ins.

  • devices/: location of device plug-ins.

  • mem/: location of memory plug-ins.

  • lib/: location of shared libraries.

If you want to use a custom virtual computer in emuStudio, it’s plug-ins and shared libraries must be put into appropriate subdirectories. Then, the abstract schema editor will find new plug-ins right after fresh start of emuStudio, and they can be used immediately.

4. Command line arguments

emuStudio accepts several command line arguments. Their description is accessible with --help argument:

$ java -jar emuStudio.jar --help
emuStudio will accept the following command line parameters:
--config name : load configuration with file name
--input name  : use the source code given by the file name
--output name : output compiler messages into this file name
--auto        : run the emulation automation
--nogui       : try to not show GUI in automation
--help        : output this message

Most of these arguments are self-explanatory. Some of them have meaning only when emulation automation is turned on (--nogui). For more information, please refer to section Automatic emulation.

5. Automatic emulation

Automatic emulation is a feature in which user should be able to run the emulation in a non-interactive mode, i.e. without any intervention. The emulation is being run from the command line and user just watches until it finishes. At the end, he collects logs and/or output files generated by plug-ins. He can then parse them and analyze them.

The feature has to be supported by individual plug-ins, so they will respect the settings from command line. Please refer to the plug-ins' documentation for these details.

Every input must be prepared before the run and passed by command line. Example of running automatic emulation is as follows:

java -jar emuStudio.jar --auto --nogui --config "MITS Altair8800" --input example.asm --output compiler.txt

Command line argument --auto turns on the automatic emulation. If no other argument is provided, emuStudio will start as usual by asking to open a virtual computer. But after this step it will run the emulation with the settings as they appear in the computer configuration file (no source code compilation is performed).

The --nogui parameter tells to emuStudio that we don’t want to use GUI (graphical user interface) at all. In that case, we must provide a virtual computer in the command line (using --config argument).

The plug-ins get the --nogui (as well as --auto) setting in the initialization phase, but it’s up to them if they will respect it. Whether they do or not should be in the documentation for the plug-ins you use.

5.1. Analyzing the results

An important part of the analysis of result of the automatic emulation is the log saying what happened. By default, each run of automatic emulation creates (overwrites) a log file called automation.html, located in the root where emuStudio.jar file is.

The log file is in HTML format as you might suggest and contains common messages organized in a table. By default, each row of the table contains:

  • a start datetime of the emulation,

  • relative time (in milliseconds) since the emulation started,

  • message level

  • the message itself

Usually, the first message is about which computer has been loaded. The second phase is compilation of the source code, if it is provided (by the --input argument in the command line). This should be logged, too. The next phase is the emulation itself and involves not much details in the log. Usually the most important messages are those if everything went fine, and the log file tries to keep it that simple. The final messages just say that the automatic emulation has finished and the state how it finished.

The log file format, and columns of the table can be of course customized, see section Logger configuration for more details.

6. Opening a computer

The first action which emuStudio does is loading a computer to be emulated. Virtual computers are described in abstract schemas, which are stored in configuration files (see Directory structure section).

Computers can be loaded either from command line or manually in GUI (by default). The open dialog is the first thing which appears to a user.

Open a computer

Left part contains a control panel and a list of all available virtual computers. When a user clicks at a computer, it’s abstract schema is displayed on the right. Double-clicking or clicking on the Open button loads selected computer.

6.1. Managing virtual computers

Managing virtual computers
  • A: Adds new computer. The abstract schema editor will be opened.

  • B: Deletes selected computer. Be aware of what you are doing - the action cannot be undone.

  • C: Edits selected computer. The abstract schema editor will be opened.

  • D: Saves the displayed abstract schema into image file.

6.2. Abstract schema editor

Abstract schema editor is a graphical editor for drawing abstract schemas of virtual computers for emulation in emuStudio. Users pick plug-ins which appear as "boxes" or elements on the screen. Then using connection lines those elements can be connected together to express a relation (that they can "see" each other).

When the abstract schema is completed, user must save it and then it will appear in the Managing virtual computers dialog.

Abstract schema editor

Description of the control panel follows.

Control panel in the abstract schema editor
  • A: Save the virtual computer.

  • B: Select a compiler.

  • C: Select a CPU.

  • D: Select a memory.

  • E: Select a device.

  • F: Use a connection line. The line is bidirectional by default.

  • G: Set or unset the connection line to be bidirectional. If the line is not bidirectional, the source direction is the first clicked element and the target direction is the second clicked element.

  • H: Remove an element from the schema.

  • I: This drop-down list is used for selecting specific plug-in (element) in the abstract schema. See icons B, C, D, and E. Those names are just file names of plug-ins located in corresponding directory (see Directory structure section).

  • J: Use / do not use a grid in the editor. Elements are "snapped" to the grid if it is used and it’s easier to draw the schema which looks good. The slider on the right then controls density of the grid. The density is saved in the configuration file of the edited computer.

Virtual computers in emuStudio are following von-Neumann model of computers. It means that each computer must have a CPU, and memory. Optionally one or more devices, and optionally a compiler.[3]

6.2.1. Connection lines

Connection line represents virtual "connection" between computer components. For the abstract schema it’s not important how the connection is realized. It’s safe to say that the connection is similar as if we say that a component "sees" the other component, in the direction of the arrow:

CPU "sees" operating memory

In the previous image, a CPU "sees" the memory, but not vice-versa. It means, CPU can read/write from/to memory, but memory is not seeing it, it can just answer to CPU requests. This connection makes sense in real-world computers.

Drawing connection lines is very easy. Connection line always connects exactly two elements in the schema. At first, user must click on already existing element in the schema. It’s just a click, not a drag.

Then a grey temporary line is being drawn having its end at the mouse position and moving with the mouse move. If the element is not really close, user can make a "path" by clicking somewhere in the schema. At those locations fixed-points are created.

When a user clicks at the second element, the temporary line disappears, and real connection line is created.

User can find the fixed-points later and move them by dragging. They can be removed by clicking at them with right button of the mouse.

6.2.2. Accessing settings of plug-ins

Each plug-in in the abstract schema can have its own "hidden" settings, which are used by particular plug-in. Most of these settings can be set in a "Settings" window accessible from Emulator panel → Peripheral devices window. However, plug-ins save their settings directly into the configuration file. The format of the file is Java properties file.

Settings of particular plug-in can be accessed by clicking on the plug-in in the Abstract schema editor with the right mouse button.

For example, the following image shows the settings of the plug-in standard-mem:

Hidden

It is possible to Add, Remove or Save the settings. Please refer for particular plug-ins which settings they support.

7. Main window

7.1. Brief description

Main window the core part of emuStudio application. Users will spend there most of the time while working with emuStudio. It is part of the main module. Main module is a separated application developed independently from plug-ins.

The content of the window is split into two panels or tabs, placeholders for two actions users can do in emuStudio. The first tab is source code editor, second is emulator, used during computer emulation.

7.2. Source code editor

Source code tab

In the source code editor, users can write programs for emulated computer. However, the most important tool which allows translation of the source code into binary program readable by emulated CPU is a compiler. Therefore, users must use the right compiler.

Input language of a compiler is not limited, it can be either a kind of assembler, or even C or Pascal language. It depends on the compiler implementation, there can be many. The only restriction is that compiler must have output which is compatible with CPU which is currently being emulated. This cannot be checked automatically, users must take care of this.

Source code editor supports only the basic features, such as line numbering and syntax highlighting. Also, there is possibility to search/replace text.

Compilation must be run manually. Compiler output window shows all messages which compiler produces. The content is dependant on the used compiler, but most likely it will contain compilation success or errors messages.

Compiled source code can produce output binary file (for example a HEX file), and it’s automatically loaded into the operating memory.[4]. If the emulation is running, user must stop it first manually.

If another program is loaded in memory, it is not removed before loading currently compiled program, but the memory is overwritten at only those locations relevant to the compiled program. All the other content is left unchanged.

7.3. Emulating a computer

Emulator tab is shown in the following image. It is currently open with MITS Altair8800 computer with Intel 8080 CPU, and several devices:

Emulator tab

The tab contains three main parts. The first one is very useful - listing of operating memory, disassembled into instructions. This part is called a debugger window, or "debugger". The other part, below the debugger window is a list of all computer devices used ("peripheral devices").[5]

The last part on the right displays status of the CPU used in this computer. Each CPU has its own implementation of how the status window look and what it displays.

7.3.1. Emulation lifecycle

In real world, users control the power of computer. Computers can be turned on, or turned off if it is running, basically by pressing a button. It’s obvious that we can turn on only not running or stopped computer. The power state is a term which denotes whether the computer is turned on or off. Each of those states define possible transitions to the other power state, executed by the action - pressing a button.

Computer behaves according to the power state in which it is. If it’s in a running state, it runs and we can see something on screen. If not, it is quiet and does nothing.

In emuStudio, emulation of a virtual computer can be controlled very similarly. In addition to basic run (turn on), stop (turn off) actions and stopped/running states, emulation work-flow in emuStudio allows reset and pause actions (plus paused state).

Emulation can be ready to run (the same as paused), running, or stopped. Each state has defined possible transitions to another states, by already mentioned actions. It’s possible to show those transitions in a state diagram, as in the following image:

emulation states
This workflow applies to emulation of a whole computer. Independent emulation of devices or other computer components cannot be controlled. The emulation of a computer starts when the CPU starts interpreting and executing instructions.

7.3.2. Debugger window

Debugging is a process in which a programmer tries to analyze a program, usually with the intent to find bugs.[6] Debugger in emuStudio contains a debugger toolbar and list of few disassembled instructions from memory. In combination with CPU status panel, it’s the most powerful tool for seeing (and checking) all internal behavior of the emulated computer.

7.3.3. Debugger toolbar

Debugger toolbar contains buttons (icons) for controlling the emulation and accessing memory content. Most of these buttons are self-explanatory. If you hover over those icons, a help text is displayed of how to use the icon.

Debugger toolbar
  • A: Reset emulation.

  • B: Set next instruction position to 0. CPU will perform the next instruction from there.

  • C: Set next instruction position to the (current - 1). This action can completely change displaying of instructions, since the new instruction position does not have to be correct in term of executing the current program.

  • D: Stop emulation (which is either running or paused).

  • E: Pause emulation (which is running).

  • F: Run emulation (which is paused).

  • G: Run emulation with timer (which is paused). Instructions are executed after elapsing specified time interval. A dialog will appear to enter the time interval.

  • H: Step emulation (which is paused). CPU will execute only one - the very next - instruction.

  • I: Jump to location. User will manually specify location (address in memory) for the next instruction to execute.

  • J: Set/unset breakpoint. User can set or unset a breakpoint on specific memory location. When CPU reaches the breakpoint, it will pause there, waiting for next user action.

  • K: Show operating memory. If the memory plug-in does not have a GUI, the icon is disabled.

7.3.4. List of instructions

The largest part of the debugger window a list of few disassembled instructions, so-called instructions window.[7] They are arranged in a table. The first column is usually interactive, allowing user to set breakpoints. Red strip is pointing to the very next instruction being executed.

The size of disassembled memory (resulting in the number of disassembled instructions) is not configurable. Also, user cannot change instructions in this place.

Sometimes the instructions shown in the debugger do not have to be disassembled correctly. There are two reasons for that:

  • first, instructions can have various binary sizes (e.g. one byte, two bytes, etc.)

  • second, memory can contain programs on various locations, and emuStudio doesn’t know where. [8]

The implication is that if emuStudio starts to disassemble instructions at wrong location, the instructions will be disassembled incorrectly, or they can appear as invalid.

However, emuStudio is trying hard to find the nearest program start location at which it’s safe to start disassembling. Usually it’s just few instructions back, so it is a fast process.

7.3.5. Controlling of displaying the instructions

It’s possible to change the current instructions view. The window can be moved in a per-page fashion. The amount of instructions displayed in the window is always preserved. With the toolbar below the list it’s possible to change "pages" of the displayed instructions.

Controlling instructions window
  • A: Go to the first page. The very first row corresponds to instruction position 0.

  • B: Go backwards. User will specify the number of pages for going back.

  • C: Go to the previous page.

  • D: Go to the page where current instruction position is.

  • E: Go to the next page.

  • F: Go forwards. User will specify the number of pages for going forward.

  • G: Go to the last page. It can cause incorrectly displaying of instructions.

8. Logger configuration

This is an advanced topic, but you might need it if something goes wrong. No software is bug-free in these days, and not a person is perfect. Sometimes it might happen that emuStudio is not working as expected, either it does not start (with weird message on screen), or it fails while running.

For that purpose, everything important is being logged (by default) in a console. If you encounter some problem and either want to fix it or report it, the logs, except steps to reproduce are the most important thing.

By default, logging is written to the standard output. However, in case of a problem it is a good practice to enable file logging. To enable file logging, open logback.xml file located in the root directory of emuStudio. Find a section named <root ..>, and change appender-ref from STDOUT to FILE as follows:

  <root level="debug">
    <appender-ref ref="FILE" />
  </root>

The log file is named emuStudio.log and should be located in the location where emuStudio.jar is located. Every new run of emuStudio will append log messages into that file until emuStudio is terminated.

By default, a rolling policy is enabled, which deletes logs older than 2 days and keeps the log in maximum size of 1 MB. It is of course configurable.
The log file is the best help about what went wrong for a developer which is trying to analyze or fix the problem. If you have encountered a problem with emuStudio, you should provide the log file for further analysis.

Format, file name and content of the log file can be influenced. EmuStudio is using logback as the logging system. Configuration of the logging mechanism is in the file called logback.xml. For more information about how to configure loggers, please look at the page http://logback.qos.ch/manual/configuration.html.


1. The name of the file is the name of the computer, which is not very good idea.
2. Format of the files is Java properties.
3. The compiler is not really a computer component, but since it also can be interconnected to other components, it is part of the abstract schema.
4. If the used compiler supports it
5. With double-click user can open GUI window of that particular device, if it supports it.
6. The adverb "to debug" has a deep history. Very early computers were having of so-called vacuum tubes, which were core elements acting as electrically controlled switches. From time to time a computer stopped working, and the most usual reason was that a bug (real one) came in a vacuum tube. Maintainers of the computer had to go there and manually remove the bug. It happened that often, so that the process of removing bugs got a name - "to de-bug".
7. Around 15 instructions are shown, but it depends on the CPU
8. Well, if it’s just program compiled from the source code editor, it knows.