SAP1Emu Assembly File Format

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

SAP1Emu Files

The SAP1Emu Emulator can either take Assembly files or binary files to import the program to execute. The Assembly language has a one-to-one mapping into binary so it is possible to write your own binary files if you want.

The SAP1Emu Project also contains an Assembler so you can assemble your assembly files into binary and then run them should you want to. For more about SAP1Emu Binary files, visit the Binary File page All SAP1Emu Assembly Files must end with the ".s" extension.

The Assembly File

SAP1Emu Assembly Files are broken up into two different sections: Program and Data, and have at max 16 lines of code.
Note: This does not include whitespace lines or comments.

Program Section

Each line of code must have an instruction and an operand. An example of a proper line of code is the following:

LDA 0xF

This piece of code starts with an instruction and ends with an operand, in this case, a memory address.

Data Section

Data can be entered into the Data Section of the program which occurs after the HLT statement. To input data, simply convert your values into two 4-bit hex values separated by a space. For example:

0xF 0xF    // 255
0xA 0x8    // 168
0x0 0x1    // 1

Comments

The SAP1Emu Emulator supports #-style comments. Anything after a '#' will be ignored until a '\n'.
For example, here is a picture of comments being used in the GUI:

Example SAP1Emu Program

Here we have a SAP1Emu Assembly Program with its pseudocode below it:

LDA 0xD
ADD 0xE
ADD 0xF
OUT 0x0
HLT 0x0
NOP 0x0
NOP 0x0
NOP 0x0
NOP 0x0
NOP 0x0
NOP 0x0
NOP 0x0
NOP 0x0
0x2 0x8
0x0 0xF
0x0 0xD

A = RAM[0xD]
A = A + RAM[0xE]
A = A + RAM[0xF]
Print(A)
Exit()

Solving for the references and converting the hex to decimal, the pseudocode would look like the following:

A = 40
A = A + 15
A = A + 13
Print(A)
Exit()

Note:
This program has 16 lines of code. This is required because the program will be loaded into the RAM and addressed by the program counter in the fetch-decode-execute cycles. To achieve the 16 lines of code, this program is filled with NOP's. A NOP or no-operation will fill that part of the RAM with all zeros.

Macros

To make programming in SAP1Emu Assembly easier, the Assembler supports one macro, the "..." macro. This will fill all the space between the end of the program section and the beginning of the data section with NOP's.

The following is an example of the same program as above. Note how the "..." comes right after the HLT and before the first piece of data. During assembly, the assembler will replace the "..." with the correct amount of NOP's to make the program 16 lines long.

This dramatically increases readability and cuts down on off-by-one errors by eliminating the need to manually insert NOP's into your program.

LDA 0xD
ADD 0xE
ADD 0xF
OUT 0x0
HLT 0x0
...
0x2 0x8
0x0 0xF
0x0 0xD