How to use the assembler, assembler syntax, and your first program

For the purposes of this guide, we will assume you have downloaded/built RR16X_EMULATOR.cpp and hybrid_assembler.c STEP ZERO: Open up a text editor, it needs to have either the extension .txt or .asm. Type out your assembly source in the file, then place it someplace sensible with a sensible name. STEP ONE: Run hybrid_assembler.c. When prompted, enter the filepath to the assembly source you made. When it prompts you again, enter a filepath with a name for the binary output. You can use .txt, .bin, or .hex as the extension. STEP TWO: Review the trace it generates. STEP THREE: Open RR16X_EMULATOR.cpp, and when prompted, enter the absolute path to the binary the assembler generated. You will be prompted again to determine if a trace is desired. Type Y for Yes, N for No.

ASSEMBLER FEATURES: Semi-automatic include system: You may wish to have an assembly file with dependencies. If that is the case, put on a line on it's own .include "absolute\path\to\include.asm". make sure the path is absolute. (Or if the dependency is nearby, relative is fine). it will automatically treat the include as though it was part of the source assembly.

Labels: labels are a text-based way to organize an assembly program. To declare a label, simply type a label's name, then end it with a :. To use a label, simply substitute an argument of an instruction for the label's name. BE SURE TO OMIT THE ':'. example:

label:
STJ label
JMP 

HEX keyword: If a line starts with this, it declares a list of comma-separated 16-bit hexadecimal values. Make sure each entry is exactly four (4) hexadecimal digits.

HEX 0001,0002,0003

Comments: Assembler will ignore comments. Start comments with a ; or #. Comments may be at the beginning or end of a line.

define keyword: will set up a named integer value. Value may not exceed 0x07FFFFFF (Or if you expanded the address space to 32 bit, 0xFFFF'FFFF). there must be a space between the define, the name, and the value. If it sees the name of a define, the assembler will substitute the name for the definition.

example:

define example 0x1234

NOTE: LITERALS MUST BE WRITTEN IN HEXADECIMAL, AND PREFIXED WITH 0x. For a list of available instructions, see ISA reference.

A SUGGESTED FIRST ASSEMBLY PROGRAM:

STJ start
JMP
text:
HEX 0048,0065,006C,006C,006F,0020,0057,006F,0072,006C,0064,0021,0000 ; "Hello World!\0" as ascii values 
start:
LDM R3 M$[text]
RET

.stream_loop:
LDM R0 M$[R3]
STJ .string_done
JEQ R0 0x0000 ; Break stream loops at terminating null byte word
EAM.SET 0x07FF
STM M$[0xFFFF] R0 ; Output hardware character byte to UART Tx port matrix line
EAM.SET 0x0000
ADD R3 R3 0x0001 ; Increment string buffer offset tracker index pointer
STJ .stream_loop
JMP
.string_done:

HLT