Skip to content

Latest commit

 

History

History
166 lines (137 loc) · 7.06 KB

CLI.md

File metadata and controls

166 lines (137 loc) · 7.06 KB
Raw

Table of Contents

Command Line Tools

The command line tools include an assembler executable, a simulator executable, and a static library that is used by both tools as well as the GUI and unit tests. More information about unit tests can be found in the unit test document.

Assuming you have followed the build document, the assembler and simulator executables will be under build/bin/ on *NIX systems and build/Release/bin/ on Windows systems. The static library will be under build/lib/ on *NIX systems and build/Release/lib/ on Windows systems.

Assembler

The assembler executable accepts one or more assembly or binary files as arguments and generates machine code files that the simulator executable can use. If the filename has a .asm extension, the assembler will treat the input file as an assembly program. If the filename has a .bin extension, the "assembler" will treat the input file as a binary program (technically this is just a conversion and not actually an assembly). Regardless of the input file format, the assembler executable will produce an object file (extension .obj) with the same name and in the same directory as the input file.

Full operation of the assembler executable is as follows:

usage: bin/assembler [OPTIONS] FILE [FILE...]

  -h,--help              Print this message
  --print-level=N        Output verbosity [0-9]
  --enable-liberal-asm   Enable liberal assembly mode

Print Levels

The following is a description of the type of output each print level enables for the assembler. Levels are cumulative, so, for example, setting print level to 8 will print messages from all preceding levels (i.e. 0-8).

  • None (0): Do not print any output
  • Fatal Error (2): Print fatal errors
  • Error (3): Print assembly errors
  • Warning (4): Print assembly warnings
  • Note (5): Print helpful notes to correct errors and warnings
  • Info (6): Print light information about the assembly process
  • Extra (8): Print detailed information about the assembly process

Liberal Assembly Mode

Other versions of LC-3 assemblers are sometimes more loose with the ISA's rules than this assembler. Liberal assembly mode loosens the requirements and should only be used as a compatibility mode.

Simulator

The simulator executable accepts one or more object files (extension .obj) and loads them into an emulated LC-3 system. The first object file in the argument list will determine the initial PC, although it is trivial to change the PC within the simulator itself.

Once the object files are loaded, the simulator is controlled with an interactive shell-like interface. Details on the interface can be found by typing in help at the simulator prompt. Full operation of the simulator executable is as follows:

usage: bin/simulator [OPTIONS] FILE [FILE...]

  -h,--help              Print this message
  --print-level=N        Output verbosity [0-9]
  --ignore-privilege     Ignore access violations
  --log=file             Output to log file

Print Levels

The following is a description of the type of output each print level enables for the simulator. Levels are cumulative, so, for example, setting print level to 8 will print messages from all preceding levels (i.e. 0-8).

  • None (0): Do not print any output
  • Simulated Output (1): Print output generated by the simulated program
  • Fatal Error (2): Print fatal errors
  • Error (3): Print errors
  • Warning (4): Print simulator warnings
  • Debug (7): Print debugging information about the simulator, including a stack trace when entering subroutines, exception handlers, etc.
  • Extra (8): Print detailed information about the simulation, including every event that the simulation executes and a breakdown of micro-ops for each instruction.

Ignore Privilege

LC-3 privilege modes may be an advanced topic that is not covered in class. Enabling this mode suppresses access violation exceptions.

Log File

Providing a log file will redirect output from the simulation to a file while still enabling interaction with the simulator shell. Useful when the print level is set to 9.

Unit Tests

A unit test executables accepts one or more assembly (*.asm) or binary (*.bin) files as arguments, assembles them, and then runs the unit test, which is effectively one or more executions of the simulator.

usage: bin/unittest [OPTIONS] FILE [FILE...]

  -h,--help              Print this message
  --print-output         Print program output
  --asm-print-level=N    Assembler output verbosity [0-9]
  --sim-print-level=N    Simulator output verbosity [0-9]
  --ignore-privilege     Ignore access violations
  --tester-verbose       Output tester messages
  --seed=N               Optional seed for randomization
  --test-filter=TEST     Only run TEST (can be repeated)

Print Levels and Ignore Privilege

The assembly and simulator print levels are separate arguments and are forwarded to the assembler and simulator modules, respectively. The ignore privilege flag is forwarded to the simulator module.

Tester Verbose

Include messages in the report that are generated by the output function in a unit test.

Random Seed

A uint64_t that seeds the random number generator. The seed that was used to randomize the machine is printed in the report and can be supplied to this argument to reproduce the unit test results exactly.

Test Filter

Only run test cases whose name matches the filter exactly. For example, if a unit test provides the test cases 'Simple Test', 'Advanced Test', 'Advanced Test (Randomized)', then supplying the argument --test-filter="Advanced Test" will only run the 'Advanced Test'. Additionally, to run the randomized version as well, another filter argument can be provided as --test-filter="Advanced Test (Randomized)".

Static Library

The static library is not directly accessible through the command line but is built alongside the command line tools. The name of the static library depends on the platform it is compiled for, but will be similar to liblc3tools.a. This static library is referred to as "the backend" for this project. On *NIX systems, the static library is in build/lib and on Windows it is in build/Release/lib.

The command line tools, unit tests, and GUI use the same static library to perform all tasks, thus guaranteeing consistent behavior. These components are all referred to as "frontends" for this project. Other frontends can also be created by utilizing the API provided by the static library. For more details on the API, see the API document.

Debugging

The command line tools offer significantly more debugging features than the GUI frontend does. For more details on these features, see the debugging document.

Copyright Notice

Copyright 2020 © McGraw-Hill Education. All rights reserved. No reproduction or distribution without the prior written consent of McGraw-Hill Education.