This is the user manual for the standard assembler of the Bedrock computer system.
This document is aimed at people who are learning about or writing programs for the Bedrock system. For people who are implementing the assembler from scratch, the assembler specification will provide more relevant information.
Overview
The assembler converts readable source code into a program that can run on a Bedrock system. Assembled programs are binary files, containing a sequence of bytes that represent instructions and program data.
Bedrock source code can be written using any regular text editor, such as Notepad or TextEdit, or other more specialised editors. The file extension used for Bedrock source code files is .brc, which is short for ‘bedrock code’, and the file extension used for assembled Bedrock programs is .br, which is short for bedrock.
Names
Names are used to identify labels and macros. A name must be unique in the program, it cannot be shared by another label or macro definition.
Each name can be at most 63 characters long, and can contain any character other than (, ), {, }, [, ], ;, or whitespace. The : character can only be used at the end of a name, and allows the name to be followed by another piece of syntax without an intervening space.
Syntax
Instruction
An instruction tells the processor to perform an operation. Each instruction has a three letter name followed optionally by r, *, or :, and assembles down to a single byte. See the instruction set manual for a full list of instruction names and effects.
PSH:01 DUP INC SWP OVR ADD ( 21 01 04 12 06 05 10 )
Comment
A comment is a note for a person reading the program. Comments start with a ( character and end with a ) character. They are ignored by the assembler.
( This is a comment. )
The characters [ and ] are called marks and act as single-character comments.
PSH*:[01 FF] ( 61 01 FF )
Literal
A literal value is a byte or double written directly into the program. A byte literal is a two digit hexadecimal number that assembles to a single byte, and a double literal is a four digit hexadecimal number that assembles to a double. Both uppercase and lowercase letters can be used.
00 F0 f7 01fc ( 00 F0 F7 01 FC )
Spacer
A spacer is a run of zero bytes. A spacer is a # character followed by two or four hexadecimal digits, and assembles to that many zero bytes. Both uppercase and lowercase letters can be used.
#02 ( 00 00 ) #000A ( 00 00 00 00 00 00 00 00 00 00 )
String
A string is a sequence of characters. A raw string starts and ends with a ' character, and assembles to a UTF-8 byte sequence. A terminated string starts and ends with a " character, and assembles to a UTF-8 byte sequence, followed by a zero byte.
'ABC' ( 41 42 43 ) "ABC" ( 41 42 43 00 )
Label
A label is a pointer to an address. A global label is a @ character followed by a name, and associates the current address of the program with that name. Every time the name is used in the program, it will assemble to the address of that label, as a double:
@start JMP:end @end JMP:start ( 21 00 03 21 00 00 )
A local label is a & character followed by a name, and belongs to the most recent global label. The name of the local label will be prefixed with the name of the global label, in the format global-name/local-name, which makes it possible to reuse common names. Every time the name is used in the program, it will assemble to the address of that label, as a double:
@main JMP:main/end &end JMP:main ( 21 00 03 21 00 00 )
A local label can also be used inside the same global label by prefixing the name with a ~ character, in the format ~local-name. The ~ character will automatically be expanded to the name of the global label:
@main JMP:~end &end JMP:main ( 21 00 03 21 00 00 )
Block
A block is an anonymous label, and is made up of a { character called a block start and a } character called a block end. The block start assembles to the address of the matching block end, as a double.
JMP:{ 01 02 03 } ( 21 00 06 01 02 03 )
This can be replicated with named labels, but would require a unique name and is less concise:
JMP:end 01 02 03 @end ( 21 00 06 01 02 03 )
Macro
A macro is a name that expands to a piece of code. A macro definition is a % character followed by a name, followed by a piece of code called the macro body, and ending with a ; character. Every time the name is used in the program, it will be replaced with the contents of the macro body. A macro can only be used after it has been defined, and a macro body cannot contain a label or a macro definition.
%A 01 ; %B 02 ; %C A B ; A B C ( 01 02 01 02 )