image

Logging Guide

Introduction

VisUAL supports logging the emulator state both via the command line and via the GUI. Logs are saved as XML files to allow easy parsing by external tools. The XML structure is explained below.

While the GUI and the command line modes support logging equally, the command line interface is more powerful in that allows power users to script testing batches of assembly files and logging results.

Logging is disabled by default in the GUI mode, whereas the headless mode has been designed specifically for logging.

Logging Modes

Three logging modes are supported, as described below.

All

In this mode, the emulator state is logged after each line of code executed. This does not include lines that are purely comments or pre-processor directives such as EQU and DCD.

Completion

In this mode, the emulator state is logged only once: when the end of the file is reached, or a STOP opcode is encountered.

Breakpoints Only

In this mode, the emulator state is logged only when a breakpoint is reached. You can place breakpoints on the GUI by clicking in the line number area. The program will pause emulation until 'Step Forwards' or 'Execute All' is clicked.

Log Settings

Log file location

Specifies the directory where the log file will be saved. The log file will be saved in this directory as visual_log.xml.

Items to log

Register values

Logs all register values each time the emulator state is logged. The register name R0-R15 and value is saved as a hexadecimal number.

Status bits

Logs the values of the status bits as a 4-bit binary number of the form 0bNZCV.

Syntax errors

Logs the line number and error message corresponding to all syntax errors. If a syntax error is encountered, emulation is cancelled so the log file will only contain syntax errors in this case.

Runtime errors

Logs the line number and error message corresponding to a runtime fault. The runtime error is appended to the log file at the point when it occurred.

Changed memory locations

Logs words in memory that have been changed by the current instruction. Therefore it logs memory locations when a STR{B} or STM instruction is encountered and the emulator state is saved. Both the memory address and the value are saved as hexadecimal numbers.

Custom memory locations

Logs a user-specified list of words in memory each time the emulator state is saved. Unlike the changed memory locations, this option will unconditionally log memory whenever the state is saved.

Log File Structure

The XML log files are structred as follows:

root
--- line 1
-------- code
-------- register R0 value
-------- register R1 value
-------- ...
-------- register R15 value
-------- status bits value
-------- memory location value
-------- instruction cycle count
--- line 2
-------- code
-------- register R0 value
...
--- line 73
--- runtime error

As an example, the log file for the following program:

MOV R0, #5
SUB R0, R0, #4

in the "All" mode while logging everything would be:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<VisUAL xmlns="http://bitbucket.org/salmanarif/visual">
    <line id="1">
        <code>MOV R0, #5</code>
        <register name="R0">0x5</register>
        <register name="R1">0x0</register>
        <register name="R2">0x0</register>
        <register name="R3">0x0</register>
        <register name="R4">0x0</register>
        <register name="R5">0x0</register>
        <register name="R6">0x0</register>
        <register name="R7">0x0</register>
        <register name="R8">0x0</register>
        <register name="R9">0x0</register>
        <register name="R10">0x0</register>
        <register name="R11">0x0</register>
        <register name="R12">0x0</register>
        <register name="R13">0x0</register>
        <register name="R14">0x0</register>
        <register name="R15">0x4</register>
        <NZCV>0b0000</NZCV>
        <cycles>1</cycles>
    </line>
    <line id="2">
        <code>SUB R0, R0, #4</code>
        <register name="R0">0x1</register>
        <register name="R1">0x0</register>
        <register name="R2">0x0</register>
        <register name="R3">0x0</register>
        <register name="R4">0x0</register>
        <register name="R5">0x0</register>
        <register name="R6">0x0</register>
        <register name="R7">0x0</register>
        <register name="R8">0x0</register>
        <register name="R9">0x0</register>
        <register name="R10">0x0</register>
        <register name="R11">0x0</register>
        <register name="R12">0x0</register>
        <register name="R13">0x0</register>
        <register name="R14">0x0</register>
        <register name="R15">0x8</register>
        <NZCV>0b0000</NZCV>
        <cycles>1</cycles>
    </line>
</VisUAL>

Logging via the Commmand Line

Via the command line, i.e. in "headless" mode, logging can be performed using the following syntax:

java -jar visual_headless.jar --headless inputfile [outputfile] [--t:<threshold_value>] [--td:(abort|ignore)] [--regs] [--statusbits] [--syntax] [--runtime] [--changed] [--cycles] [--cyclemodel:<cycle_model>][--custom:<locations>] [--breakpoints:<linenumbers>] [--mode:(all|completion|breakpoint)] [--meminitval<memory_initialisation_value>] [--autoinstmemsize] [--meminstsize:<instruction_memory_size>] [--sp:<stack_pointer_intialisation_value>] [--memmode:(open|strict)]

An example command is:

java -jar visual_headless.jar --headless str_test.S -t:1000 -td:abort --mode:completion --regs --changed

The JAR file visual_headless.jar is located in VisUAL.app/Contents/MacOS on Mac OS X, and in the content folder in the installation directory for Windows and Linux.

The above parameters are defined as follows: