ArdEx "Assembler"

Download aasm Perl code.

aasm is a Perl script which takes a text file of symbolic ArdEx code, converts all symbols into numbers and assigns a slot number for each instruction. If there are no errors, the output should be suitable to upload to ArdEx.

This makes writing ArdEx code much more convenient, but it's optional. You're still free to work out slot numbers as you go and make space with the RELO command.

To be able run aasm, you'll have to have Perl on your computer. Perl is available for free, but comes already installed in Linux and recent releases of and Mac OS X. I'll leave installing Perl for you to investigate.

With luck it will work by just typing aasm filename.txt, but it should definitely work if you type perl aasm filename.txt (assuming aasm and filename.txt are both in the current directory).

Command Line Options

There is only one command line option: -s. This tells aasm to minimise the size of the upload to the Arduino by "stripping" comments from the output.

The usual usage is something like:

aasm -s input.adx > out.txt

You might instead send out.txt to a temporary directory. Either way, out.txt should be ready to upload to ArdEx using your terminal's file upload command.

Symbolic Code

The most useful feature is labelling. When aasm runs, it assigns the next slot number to each instruction. Any line that starts with a word followed by a colon (e.g. mylabel: will have the current slot number associated with that word. Any line that includes that word as one of its arguments (e.g. JMP mylabel) will replace the word with its associated value.

The assembler defines a few special operations depending on how each line starts. Lines of the form

• !instruction
  
  won't assign a slot number, but will output instruction for immediate execution. This is typically used for pre-loading RAM or registers with values.
• set symbol,expr
  
  evaluates expr and assigns the result to symbol which will, in turn, be substituted in instruction arguments.
• org num
  
  next instruction will be assigned to slot num. The value has to be a simple number, not a symbol or expression.

Expressions

Instruction arguments can contain simple arithmetic expressions involving addition and subtraction (e.g. sym+4, sym2-sym1, etc.). Nothing sophisticated and no parentheses.

A special symbol $ evaluates to the current slot number. This can be useful for relative jumps (e.g. JMP $-4).

Example

Here is blinky in over-the-top symbolic form:

set ledptn,0x21         ; Top and bottom LEDs
set dest,PORTB          ; might send it somewhere else someday
set rate,5000           ; half second
;
; Blink for eternity
;
forever:
        MOV     #ledptn,dest    ; on
        WAIT    rate
        MOV     #0,dest         ; off
        WAIT    rate
        JMP     forever

If we run aasm -s on this file we get:

0       MOV     #33,37
1       WAIT    5000
2       MOV     #0,37
3       WAIT    5000
4       JMP     0

As you see, all symbols have been converted into unfriendly decimal numbers. Don't worry though, when it's listed in ArdEx, well known addresses like PORTB will still list as symbols.

Try it for yourself. You can pop an org 60 somewhere before the forever label and everything relocates to higher slot numbers. If you put the org after the label the loop will jump all the way back to slot 0.

A Quibble

This assembler isn't really an assembler. It takes in code that is very like a normal assembler's input, but it outputs stuff that still looks like assembly language code. A normal assembler outputs object code which is made up of binary machine instructions and various symbols for later expansion by the linker.

In truth, I'm not sure what to call it since it combines some of the work of both the assembler and linker. It's because ArdEx is an interpreter and expects assembly language instructions in text form which a real machine couln't make head or tail of. Some thought was given to having a binary input mode, but that seemed like needless complexity.