Documentation

Introduction

Accelerate is a cross-assembler that runs on modern computers. It translates programs for retro computers written in assembly language into binaries that can run on those computers. It supports a variety of computers and CPU families, and adding support for even more is relatively easy and can be done without changing and recompiling the assemlber itself.

All source, definition, and intermediary files are text files, although the latter are not meant to be edited by hand.

The program is organized into source files and libraries, which contain objects, constants, macros, and functions. The assembly process is directed by a target definition, which references a CPU definition.

Assembler Soruce File

A source file contains definitions that will be translated to a library or a binary program.

It consists of a list of elements and directives, separated by newlines. Instructions, labels, and assignments within an object or macro are also separated by newlines.

Directives

.section

.section <section-name>

The .section directive specifies which section the following objects will be placed in. This determines where in memory they will be placed, and whether they will be included in the binary program (data objects) or not (reservation objects).

.scope

.scope [public|private]

The .scope directive specifies the visibility of the following elements. private elements are only visible within the same module (library or the main program). public elements are also visible to modules using a library.

.target

.target "<target-name>"

The .target directive specifies which target definition file will be used in translating the file.

Elements

Objects

There are two kinds of objects:

Data objects contain code or other data and are saved in the resulting program binary:

[.private|.public] <name> [.align <alignment>] [.address <address>] {
    <body>
}

Reservation objects only reserve a certain amount of memory, which will not be initialized and is usually not saved in the resulting program binary:

[.private|.public] <name> [.align <alignment>] [.address <address>] .reserve <length>

Constants

Constants define values that can be used in other parts of the program. They can refer to other constants or objects (which results in their address).

[.private|.public] <name> = <value>

Macros

[.private|.public] .macro <name> [<argument>[=<default-value>], ...] {
    <body>
}

Functions

[.private|.public] <name> ([<argument>[=<default-value>, ...]) = <value>

Library

A library is a collection of objects, constants, macros, and functions.

When importing a library, only the objects actually used will be included in the resulting binary program. This gives you flexibility in how you organize your code: even using only a small portion of a large library does not sacrifice efficiencey.

Target Definition

CPU Definition

Expressions

Expressions are used in various places in a program.

Types

Boolean

A boolean is either true or false. Numbers and strings can be implicitly converted to boolean, with 0 and the empty string being false and all others being true.

Signed Integers

A signed integer with a maximum precision of 64 bits, giving a value range of -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

Unsigned Integer

An unsigned integer with a maximum precision of 64 bits, giving a value range of 0 to 18,446,744,073,709,551,615.

For hexadecimal numbers, prefix them with $, for binary numbers with %.

Floating Point Number

A floating point number expressed as a double.

Scientific notation (including an exponent) is not supported yet.

String

Strings are enclosed in " and support Unicode characters.

Operators

Unary Operators

All unary operators are followed by their operand and have higher precedence than binary operators.

! (Logical Not)

Converts its operand to boolean and negates it. The result is always boolean.

+ (Unary Plus)

The operand must be a number, the result is the operand unchanged.

- (Unary Minus)

The operand must be a number, the result is the negative operand.

^ (Bank Byte)

The operand must be an unsigned integer, the result is the third lowest byte of the operand.

< (Low Byte)

The operand must be an unsigned integer, the result is the lowest byte of the operand.

> (Hight Byte)

The operand must be an unsigned integer, the result is the second lowest byte of the operand (high byte of a 16-bit value).

~ (Bitwise Not)

The operand must be an unsigned integer, the result is the operand with each bit inverted.

Binary Operators

All binary operators are left associative. The following list shows their relative precedence from high to low; operands on one line have the same precedence:

<< (Shift Left)

Both operands must be integers. The left operand is shifted to the left by the number of bits of the value of the right operand. The result has the same type as the left operand.

>> (Shift Right)

Both operands must be integers. The left operand is shifted to the left by the number of bits of the value of the right operand. The result has the same type as the left operand.

* (Multiply)

Both operands must be numbers. The result is the product of the two operands. If both operands are integers, the result is an integer, otherwise a float point number.

/ (Divide)

Both operands must be numbers. If both operands are integers, the result is the quotient of the two operands, otherwise a floating point division is performed.

& (Bitwise And)

Both operands must be unsigned integers. The result is the bitwise and of the two operands.

+ (Add)

Both operands must be numbers. The result is the sum of the two operands. If both operands are integers, the result is an integer, otherwise a float point number.

- (Subtract)

Both operands must be numbers. The result is the difference of the two operands. If both operands are integers, the result is an integer, otherwise a float point number.

| (Bitwise Or)

Both operands must be unsigned integers. The result is the bitwise or of the two operands.

^ (Bitwise Exclusive Or)

Both operands must be unsigned integers. The result is the bitwise exclusive or of the two operands.

== (Equal)

Both operands must be either booleans, numbers, or strings. The result is true if both operands are the same, false otherwise.

!= (Not Equal)

Both operands must be either booleans, numbers, or strings. The result is false if both operands are the same, true otherwise.

< (Less)

Both operands must be either numbers or strings. The result is false if the left operand is less than the right, true otherwise.

<= (Less Equal)

Both operands must be either numbers or strings. The result is false if the left operand is grelessater than or equal to the right, true otherwise.

> (Greater)

Both operands must be either numbers or strings. The result is false if the left operand is greater than the right, true otherwise.

>= (Greater Equal)

Both operands must be either numbers or strings. The result is false if the left operand is greater than or equal to the right, true otherwise.

&& (Logical And)

Both operands are converted to boolean. The result is true if both operands are true, false otherwise.

|| (Logical Or)

Both operands are converted to boolean. The result is true if at least one operand is true, false otherwise.