Skip to content

SAP1Emu Emulator

Jump to bottom
Bob Baker edited this page Oct 5, 2020 · 40 revisions

A lot of this is outdated. Documentation is slowly moving over to sap1emu.net/Docs/Docs

The Command-Line Emulator

Table of Contents

The SAP1 Emulator has two interfaces, a Command-Line Interface (CLI) and a Graphical-User Interface (GUI). As of release 1.0.8-beta, only the CLI has been release and the GUI is still under development.
Once the GUI is release, a separate page in the wiki will be created to cover its use.

Calling the Emulator

The only difference between the Windows and Linux/MacOSX versions of the CLI is how to call them from the command line. Note the difference between calling the program from the different OS's.

Make sure the directory (folder) that your command prompt is pointing to is the same directory that you downloaded the SAP1Emu Project to. See the appropriate Getting Started page for more information.

Windows 10:

SAP1Emu.exe <options>

Linux / MacOSX

./SAP1Emu <options>

As you can see only the start of the invocation is different. The part of the command will be the same for all operating systems.

Note, for the rest of this tutorial, we will assume the Windows invocation of the SAP1 program. Linux users please adjust accordingly.

Flags and Options

If you run the SAP1 with the --help flag, you should see the following:

C:\>SAP1Emu.exe --help
SAP1Emu 1.13.0
2020 Bob Baker

ERROR(S):
  Required option 's, source-file' is missing.

  -s, --source-file       Required.
                          <FileName>.s Input file containing assembly code.
                          <FileName>.b Input file containing compilied binary.

  -o, --output-file       (Default: a.txt) Place the output into <file>.

  -f, --fframe            Include final frame in the output file.

  -F, --Fframe            Include all frames in the output file.

  -O, --FOframe           Include Snapshots of the Output Register in the output file.
                          Parameters:
                            std         Outputs with formatting
                            no-format   Outputs wil no formatting

  -d, --debug             Turns on Debug Mode

  -i, --instructionSet    (Default: SAP1Emu) Sets the Instruction Set to use
                          Parameters:
                            SAP1Emu     Uses expanded SAP1EMU Instruction Set (default)
                            Malvino     Uses Malvino's Instruction Set
                            BenEater    Uses Ben Eater's Instruction Set

  --help                  Display this help screen.

  --version               Display version information.

Note: As of the 1.0.8-beta release, some of these options are not implemented yet.

Source File Flag

This is the only required flag for the Emulator. If you do not specify this flag, the Emulator will not run and return an error.

The Source File Flag points the Emulator to the input file that contains your SAP1Emu Program. This file is read-only and will not be modified by the Emulator.

The Emulator can either can SAP1Emu Assembly Files (filename.s) or SAP1Emu Binary Files (filename.b). This being said, it is much easier to write in SAP1Emu Assembly and binary support is only there for educational purposes.

See the Assembly File page for more details on how to properly structure a SAP1Emu Assembly File.

If we had a SAP1Emu Assembly File that we wanted to run located in the same directory as the SAP1Emu.exe program, you would use the following to load it into the Emulator.

SAP1Emu.exe -s <your_file_name>.s

You can also use the long-hand notation:

SAP1Emu.exe --source-file <your_file_name>.s

Output File Flag

The Output File Flag designates the desired location of the output of the emulator.
It has a default value of a.txt. This means if you do not specify an output file, it will put the contents of the output into a.txt.

If you wanted your output to go into a file called myProgramOutput.txt, you would use the following:

SAP1Emu.exe -s <inputFile>.s -o myProgramOutput.txt

You can also use the long-hand notation:

SAP1Emu.exe --source-file <inputFile>.s --output-file myProgramOutput.txt

With no other flags enabled, the contents of myProgramOutput.txt could look like this:

Verbose Flag

The Verbose Flag has not been implemented as of 1.0.8-beta

Very Verbose Flag

The Very Verbose Flag has not been implemented as of 1.0.8-beta

Final Frame Flag

The Final Frame Flag includes the final frame in the output file. A frame is a snapshot of all of the registers on the SAP1 Computer at that State. The Final Frame Flag will include the T6 of your last command.

To use the Final Frame Flag, use the following:

SAP1Emu.exe -s <your_file_name>.s -f

You can also use the long-hand notation:

SAP1Emu.exe --source-file <your_file_name>.s --fframe

An example of a possible output of the Final Frame Flag could be the following:

All Frames Flag

With the All Frames Flag, every frame from every TState will be included in the output file.

To use the All Frames Flag, use the following:

SAP1Emu.exe -s <your_file_name>.s -F

You can also use the long-hand notation:

SAP1Emu.exe --source-file <your_file_name>.s --Fframe

An example of a possible output of the All Frames Flag could be the following:

All Output Register Frames Flag

With the All Output Register Frames Flag, every snapshot of the Output Register from every 6th TState will be included in the output file.

It has two parameters: std and no-format

The std parameter will output the contents of the Output Register at each T6 with formatting: For example:

SAP1Emu.exe -s <your_file_name>.s -O std

You can also use the long-hand notation:

SAP1Emu.exe --source-file <your_file_name>.s --FOframe std

could give the following output:

The no-format parameter will output the contents of the Output Register at each T6 without formatting: For example:

SAP1Emu.exe -s <your_file_name>.s -O no-format

You can also use the long-hand notation:

SAP1Emu.exe --source-file <your_file_name>.s --FOframe no-format

could give the following output:

Debug Flag

The Debug Flag allows the user to single-step through their program and set a breakpoint if needed.
It will show a RAM Dump, the Values of the Registers, and the SAP1 Assembly Code being run.

To use the Debug Flag, use the following

SAP1Emu.exe -s <your_file_name>.s -d

You can also use the long-hand notation:

SAP1Emu.exe --source-file <your_file_name>.s --debug

An example of a possible output of the Debug Flag could be the following:

Instruction Set Flag

The Instruction Set Flag allows the user to choose between different instruction sets.
As of 1.13.0, the supported instruction sets are:

  • SAP1Emu Expanded Set - Default
  • Malvino Restricted Set
  • Ben Eater Set

To use the Debug Flag, use the following

SAP1Emu.exe -s <your_file_name>.s -i SAP1Emu

You can also use the long-hand notation:

SAP1Emu.exe --source-file <your_file_name>.s --instructionSet Malvino

Other Emulator Features

The SAP1Emu Emulator comes with Infinite Loop Detection.
If your program has an infinite loop, the emulator will automatically exit and display an error.

© Bob Baker 2020

SAP1Emu Project

Clone this wiki locally