PicoAssembler user manual and syntax reference - Revision history

Karljans at 13:52, 24 November 2015

2015-11-24T13:52:38Z

Karljans: /* Output format */

2015-11-24T13:52:23Z

‎Output format

Karljans at 13:48, 24 November 2015

2015-11-24T13:48:52Z

Siavoosh: /* Using the program */

2014-12-16T14:49:19Z

‎Using the program

Siavoosh at 08:44, 15 December 2014

2014-12-15T08:44:27Z

Siavoosh: Created page with " =Using the program= The standard command line to run the program is: java -jar picoAssembler -a -i -o
2014-12-11T09:25:51Z

Created page with " =Using the program= The standard command line to run the program is: java -jar picoAssembler -a <path to assembler file> -i <path to instruction set file> -o <path to output..."

New page

=Using the program=
The standard command line to run the program is:
java -jar picoAssembler -a <path to assembler file> -i <path to instruction set file> -o <path to output file>

'''Assembler file''' is the file with assembler code to be compiled.
'''Instruction set file''' is the file that maps instructions to their codes (defaults to intructions.txt).
*'''Output file''' is the file, where the machinecode is saved (defaults to machinecode.txt).

It is only necessary to specify the assembler file, the other two have default values that will be used if they are not specified on the command line.
It is also possible to force the program to not to write the output code into a file at all and just display the output on the screen using the '''-no''' flag.

==Instruction set file syntax==
The instruction set file is a text file that maps the higher level instruction names to the opcodes.
The instructions are defined as follows:
instruction_name : opcode
Every instruction has to be defined on a new line.

Example:
ADD : 00000
SUB : 00001

The leading zeros are automatically added, you do not have to include them in your assembly code.
Negative numbers are also supported and automatically decoded into their complement:

Decimal: -5 -> 11111011
Hexadecimal: -0x5 -> 11111011
Binary: -0b101 -> 11111011

==Assembler syntax==
===Operations===
Each operation is defined by opcode and operand that are separated by a whitespace
OPCODE <operand>
Specifying the operand is optional, if it is not specified, the assembler automatically adds 0x00 as the operand.
Operand can be either in decimal, hexadecimal or binary format:
Decimal: 5
Hexadecimal: 0x5
Binary: 0b101

===Comments===
Comments start with ' # ' symbol
# An awesome example comment
Multi-line comments are not supported.
===Labels===
GOTO style labels are also supported.
====Declaration====
To declare a label label, it has to be put on a separate line and end with the ' : ' symbol
AnExampleLabel:
====Usage====
To branch to the label use it with your branching operation as an operand.
Also, notice that the ' : ' symbol has to be in the beginning of the label when it is used as an operand
for an instruction:
GOTO :AnExampleLabel
This gets replaced by the program memory address of the operation that follows the label.

Example:
The following program first loads number 5 to the accumulator, then decrements the number in the
accumulator by one, then checks the zero flag (the BRNZ instruction). If the flag is not up (the
answer in the accumulator is not zero), then the code will branch to the address or label in the
operand. In this case that means branching to the address defined by the Decrement: label. In the
comments are shown the addresses in the program memory for every instruction.
In case the zero flag is up (the answer is zero), there is no branching and the CPU halts.

LOADN 5 #0x0

Decrement:
DEC #0x1
BRNZ :Decrement #0x2
HALT #0x3

This gets resolved by the assembler into the following:

LOADN 5 #0x0
DEC #0x1
BRNZ 0x1 #0x2
HALT #0x3

It is possible to declare one label only once in the code (it can't be re-declared), there are no
limitations to the time one label can be used for branching . It is allowed to branch to the label
before it is defined (earlier in the code).

===Constants===
The picoAssembler also supports constants. You can think of the constants as an alias for a data
memory address, so it is possible to use some meaningful name to them. For example, you can
access your memory address for temporary data as $tmp instead of 0b10101101 .
Constant names begin with the ' $ ' symbol.

====Declaration====
The line for declaring a constant is the following:
$TestConst 52
====Usage====
To use the constant, it has to be given to an instruction as an operand

LOADV $TestConst

It is important to understand, that the constants do not work as variables, it is not possible to get the
value of the memory address they are pointing to. For this it is necessary to use native instructions
for loading and storing data on the CPU. Constants work by reference, similar to pointers in C.
They return the memory address they are assigned. They are basically just aliases to memory
addresses.
Also, as the picoAssembler completely lacks any kind of branch prediction, constants, like labels,
can be declared only once. Afterwards, the value in the address the constant is pointing to can be
changed using loading / storing instructions of the CPU, but the address itself can not. So although
it is possible to access the constant from anywhere in the code (including before it is declared, as
the declarations are taken care by the pre-processor), you will probably want to declare it in the
beginning of the code. Let's call it a good coding practice for picoAssembler.

Example:
#Testing memory operations
$NumMem 0x4
$Index 0x0

LOADN 5 #Load number 5 to AC
STORE $NumMem #STORE 5 to $NumMem

LOADN 0 #Zero the AC
LOADV 0x4 #Load the value of 0x4 ($NumMem) (5)
LOADN 4 #Load 4 to AC

STORE 0x0 #Store 4 in 0x0 ($Index)
LOADN 0 #Zero the AC

LOADV 0x0 #Load memort address from 0x0 ($Index) to AC
LOADA #Load data from address stored on AC (5)
HALT #Halt the cpu

===Output format===
The assembler outputs the machine code as 16-bit binary vectors.
Each line represents one memory address in the program memory, first line = 0x0, second = 0x1
etc. All the vectors are in the following format:

[[File:instructionformat.png|400px]]

(the unused part is represented as zeroes)

@@ Line 144: / Line 144: @@
 (the unused part is represented as zeroes)
- The size of opcode can vary, depending on the CPU architecture. Shorter opcodes are also possible. For example for 5-bit opcodes there would be 3 unused bits of followed by 5 bits of opcaode.
+The size of opcode can vary, depending on the CPU architecture. Shorter opcodes are also possible. For example for 5-bit opcodes there would be 3 unused bits of followed by 5 bits of opcaode.
 = Download =

@@ Line 1: / Line 1: @@
 =Using the program=
 The standard command line to run the program is:
@@ Line 5: / Line 4: @@
 *'''Assembler file''' is the file with assembler code to be compiled.
-*'''Instruction set file''' is the file that maps instructions to their codes (defaults to intructions.txt).
+*'''Instruction set file''' is the file that maps instructions to their codes (defaults to intructions.conf).
-*'''Output file''' is the file, where the machinecode is saved (defaults to machinecode.txt).
+*'''Output file''' is the file, where the machinecode is saved (defaults to machinecode.bin).
 It is only necessary to specify the assembler file, the other two have default values that will be used if they are not specified on the command line.
 It is also possible to force the program to not to write the output code into a file at all and just display the output on the screen using the '''-no''' flag.
 ==Instruction set file syntax==
-The instruction set file is a text file that maps the higher level instruction names to the opcodes.
+The instruction set file is a text file that maps the higher level instruction names to the opcodes. It is used for configuring the assembler.
 The instructions are defined as follows:
-  instruction_name : opcode
+  instruction_name : opcode : is_operand_signed
 Every instruction has to be defined on a new line.
 Example:
-  ADD : 00000
+  ADD  : 00000 : 1
-  SUB : 00001
+  SUB  : 00001 : 1
 The leading zeros are automatically added, you do not have to include them in your assembly code.
@@ Line 39: / Line 48: @@
 ===Comments===
-Comments start with ' # ' symbol
+Comments start with ' ; ' symbol
-  # An awesome example comment
+  ; An awesome example comment
 Multi-line comments are not supported.
 ===Labels===
@@ Line 62: / Line 71: @@
 In case the zero flag is up (the answer is zero), there is no branching and the CPU halts.
-  LOADN 5             #0x0
+  LOADN 5             ;0x0
   Decrement:
-  DEC                 #0x1
+  DEC                 ;0x1
-  BRNZ  :Decrement    #0x2
+  BRNZ  :Decrement    ;0x2
-  HALT                #0x3
+  HALT                ;0x3
 This gets resolved by the assembler into the following:
-  LOADN 5             #0x0
+  LOADN 5             ;0x0
-  DEC                 #0x1
+  DEC                 ;0x1
-  BRNZ  0x1           #0x2
+  BRNZ  0x1           ;0x2
-  HALT                #0x3
+  HALT                ;0x3
 It is possible to declare one label only once in the code (it can't be re-declared), there are no
@@ Line 111: / Line 120: @@
   $Index 0x0
-  LOADN    5          #Load number 5 to AC
+  LOADN    5          ;Load number 5 to AC
-  STORE    $NumMem    #STORE 5 to $NumMem
+  STORE    $NumMem    ;STORE 5 to $NumMem
-  LOADN  0     #Zero the AC
+  LOADN  0     ;Zero the AC
-  LOADV  0x4   #Load the value of 0x4 ($NumMem) (5)
+  LOADV  0x4   ;Load the value of 0x4 ($NumMem) (5)
-  LOADN  4     #Load 4 to AC
+  LOADN  4     ;Load 4 to AC
-  STORE  0x0   #Store 4 in 0x0 ($Index)
+  STORE  0x0   ;Store 4 in 0x0 ($Index)
-  LOADN  0     #Zero the AC
+  LOADN  0     ;Zero the AC
-  LOADV  0x0 #Load memort address from 0x0 ($Index) to AC
+  LOADV  0x0 ;Load memort address from 0x0 ($Index) to AC
-  LOADA  #Load data from address stored on AC (5)
+  LOADA  ;Load data from address stored on AC (5)
-  HALT #Halt the cpu
+  HALT ;Halt the cpu
 ===Output format===
@@ Line 133: / Line 142: @@
 (the unused part is represented as zeroes)