BeebAsm

= BeebAsm =

Licence
This software is licensed under the GNU GPLv3 license and can be used for commercial or non-commercial purposes.

Downloads
Never mind all the waffle! Where can I download this thing?!

Windows
The latest version of BeebAsm (1.09) for Windows is available from the BeebAsm project page on the Stardot GitHub account.

The direct link to the file is: https://github.com/stardot/beebasm/archive/refs/tags/v1.09.zip

Programming Editor BeebAsm Language Syntax Files
Use the files below to add syntax highlighting for BeebAsm and BBC BASIC files to popular Windows editor Notepad++ or shareware editor TextPad (BeebAsm only).

TextPad [[Media:TextPad_BeebAsm_Syn.zip|BeebAsm syntax definition file]] by Rich Talbot-Watkins

Notepad++ [[Media:BeebAsm.zip|BeebAsm UDL File]] by Rich Talbot-Watkins with contributions by David Lodge

Notepad++ [[Media:BBC_Basic.zip‎|BBC BASIC UDL File]] contributed by Stephen Coombes

For the Notepad++ UDL files, download and unzip them, then open the User Defined Language panel in Notepad++ and click Import... Choose the appropriate downloaded XML file to import them to your installation.

Linux
v1.04 Download the BeebAsm 1.04 release zip archive above and extract it. Download and unzip this patch to the same directory:

In a console, change to that working directory and apply the patch with:

Then change to the src sub-directory and compile with:

The executable will be built into the parent BeebAsm working directory.

v1.01 Linux version of BeebAsm 1.01 can be downloaded here.

Mac OS X
Mac OS X version of BeebAsm 1.08 can be downloaded here.

RISC OS
The latest version of BeebAsm (1.02) for RISC OS is available here:

Previous versions are available here, should you wish to try them for some reason:



About BeebAsm
BeebAsm is a 6502 assembler designed specially for developing assembler programs for the BBC Micro. It uses syntax reminiscent of BBC BASIC's built-in assembler, and is able to output its object code directly into emulator-ready DFS disc images.

Many of the luxuries which come from assembling within the BBC BASIC environment on a real BBC Micro are also available here, including FOR...NEXT loops, conditional assembly (IF...ELSE...ENDIF), and all of BASIC's numerical functions, including SIN, COS and SQR - very useful for building lookup tables directly within a source file.

BeebAsm is distributed with source code, and should be easily portable to any platform you wish.

BeebAsm 'philosophy'
BeebAsm is not like most modern assemblers, in that it doesn't just accept a source file, and output the corresponding object code file - after all, what use is a raw 6502 executable file on a PC, outside of an emulated BBC Micro environment?

Although BeebAsm is able to do this, this isn't the way it was intended to be used. Instead, BeebAsm can be pointed at a BBC Micro DFS disc image (.ssd or .dsd file), and can save blocks of assembled object code directly onto the 'disc', as many or as few as you wish. It is up to the source code to specify which blocks of assembled code to save, and with which name, just as if you were assembling from within BBC BASIC itself.

Features

 * Uses standard 6502 syntax
 * Supports 65C02 instruction set
 * Denote hex literals with '&' or '$'
 * Denote binary literals with '%'
 * Multiple statement lines, statements separated by colons
 * Define labels with .label, like BBC BASIC
 * Assign variables with addr=&70, like BBC BASIC
 * Add bytes, words and strings with EQUB, EQUW, EQUD and EQUS - as an extension to BBC BASIC, these can take a comma-separated list
 * FOR...NEXT
 * IF...ELIF...ELSE...ENDIF
 * Supports all of the BBC BASIC functions and operators in expressions, e.g. SIN, COS, SQR, DIV, MOD, etc etc
 * Save object code to a disc image or to a standalone file
 * INCLUDE "file" to include another source file
 * Ability to set a guard on a memory address so it will warn you if it is assembled over
 * Use braces { } to enclose blocks of code so that all labels and variables defined within will be local to that block.
 * INCBIN command to include a binary file in the object code.
 * SKIPTO to move the address pointer to the specified address, generating an error if we are already beyond this address.
 * MAPCHAR command to allow strings to be assembled using non-ASCII codes (this is maybe more useful than it sounds; there's an example in the documentation).
 * Warns if there is no SAVE command in the source code.

Example
Rather than trying to explain anything about BeebAsm now, let's leap straight into an example, as it can probably illustrate more about how BeebAsm should be used than a thousand lines of text.

Take the following highly contrived source file: simple.asm

 \ Simple example illustrating use of BeebAsm oswrch = &FFEE osasci = &FFE3 addr = &70 ORG &2000        ; code origin (like P%=&2000) .start LDA #22: JSR oswrch LDA #7: JSR oswrch LDA #mytext MOD 256: STA addr LDA #mytext DIV 256: STA addr+1 LDY #0 .loop LDA (addr),Y BEQ finished JSR osasci INY BNE loop .finished RTS .mytext EQUS "Hello world!" , 13, 0 .end SAVE "MyCode", start, end 

...and then build it with the following command:

 beebasm -i simple.asm -do test.ssd -boot MyCode -v 

This will do the following:


 * create a new disc image called test.ssd, set to *OPT 4,3
 * assemble the 6502 code and create an executable on the disc called 'MyCode'
 * create a !Boot file containing '*RUN MyCode'
 * output a listing of the assembled code

Note how the syntax in the source file is very much like BBC BASIC, with a few small differences which we'll look at in detail later.

Note also that the source code tells the assembler what should be saved - in this example, all of the assembled code (from .start to .end), with the filename 'MyCode'. This might at first seem strange, but it's actually very simple and powerful: you have absolute control over what gets saved. If we wished, we could assemble more code elsewhere and save it as a separate file, whilst all the defined labels remained visible to both chunks of code.

Command line options
At its very most basic, you need know only one command line option:

 -i 

This specifies the name of the source file for BeebAsm to process. In the absence of any switches specifying disc image filenames, SAVE commands in the source code will write out object files directly to the current directory.

 -o 

If this is specified, then the SAVE command can be used without supplying a filename, and this one will be used instead. This allows BeebAsm to be used like a conventional assembler, specifying both input and output filenames from the command line.

 -do 

This specifies the name of a new disc image to be created. All object code files will be saved to within this disc image.

 -boot  

If specifed, BeebAsm will create a !Boot file on the new disc image, containing the command '*RUN '. The new disc image will already be set to *OPT 4,3 (*EXEC !Boot).

 -opt 

If specified, the *OPT 4 disc option of the generated disc image will be set to the specified value.

 -di </tt>

If specified, BeebAsm will use this disc image as a template for the new disc image, rather than creating a new blank one. This is useful if you have a BASIC loader which you want to run before your executable. Note this cannot be the same as the -do filename!

 -v </tt>

Verbose output. Assembled code will be output to the screen.

 -d </tt>

Dumps all global symbols in Swift-compatible format after assembly. This is used internally by Swift, and is just documented for completeness.

Source file syntax
Assembler instructions are written with the standard 6502 syntax, using either upper- or lower-case.

A label is defined by preceding it with a ".", as per the BBC Micro assembler, e.g. .loop

Instructions can be written one-per-line, or many on one line, separated by colons. A label need not be followed by a colon.

Comments are introduced by a semicolon or backslash. Unlike the BBC Micro assembler, these continue to the end of the line, and are not terminated by a colon (because this BBC Micro feature is horrible!).

Numeric literals are in decimal by default, and can be integers or reals.

Hex literals are prefixed with "&", like BBC BASIC, or with "$", like other assemblers.

A binary literal can be written prefixed with "%", e.g. %01010101

A character in single quotes (e.g. 'A') returns its ASCII code. To express the single quote character, write '''

BeebAsm can accept complex expressions, using a wide variety of operators and functions. Here's a summary:

Also, some constants are defined:

Note that all of the above must be written in upper-case.

Variables can be defined at any point using the BASIC syntax, i.e. addr = &70.

Note that it is not possible to reassign variables once defined. However FOR...NEXT blocks have their own scope (more on this later).

Assembler directives
These are keywords which control the assembly of the source file.

Here's a summary:

 ORG </tt>

Set the address to be assembled from. This can be changed multiple times during a source file if you wish (for example) to assemble two separate blocks of code at different addresses, but share the labels between both blocks. This is exactly equivalent to BBC BASIC's 'P%= '.

 CPU <n> </tt>

Selects the target CPU, which determines the range of instructions that will be accepted. The default is 0, which provides the original 6502 instruction set. The only current alternative is 1, which provides the 65C02 instruction set (including PLX, TRB etc, but not the Rockwell additions like BBR).

 SKIP </tt>

Moves the address pointer on by the specified number of bytes. Use this to reserve a space of a fixed size in the code.

 SKIPTO </tt>

Moves the address pointer to the specified address. An error is generated if this address is behind the current address pointer.

 ALIGN </tt>

Used to align the address pointer to the next boundary, e.g. use ALIGN &100 to move to the next page (useful perhaps for positioning a table at a page boundary so that index accesses don't incur a "page crossed" penalty.

 INCLUDE "filename" </tt>

Includes the specified source file in the code at this point.

 INCBIN "filename" </tt>

Includes the specified binary file in the object code at this point.

 EQUB a [, b, c, ...] </tt>

Insert the specified byte(s) into the code. Note, unlike BBC BASIC, that a comma-separated sequence can be inserted.

 EQUW a [, b, c, ...] </tt>

Insert the specified 16-bit word(s) into the code.

 EQUD a [, b, c, ...] </tt>

Insert the specified 32-bit word(s) into the code.

 EQUS "string" [, "string", byte, ...] </tt>

Inserts the specified string into the code. Note that this can take a comma-separated list of parameters which may also include bytes. So, to zero-terminate a string, you can write:

 EQUS "My string", 0 </tt>

In fact, under the surface, there is no difference between EQUS and EQUB, which is also able to take strings!

 MAPCHAR, </tt> <tt> MAPCHAR, , </tt>

By default, when EQUS "string" is assembled, the ASCII codes of each character are written into the object code. MAPCHAR allows you to specify which value should be written to the object code for each character. Suppose you have a font which contains the following symbols - space, followed by A-Z, followed by digits 0-9, followed by .,!?-'

You could specify this with MAPCHAR as follows:

<tt> MAPCHAR ' ', 0 MAPCHAR 'A', 'Z' , 1 MAPCHAR '0', '9' , 27 MAPCHAR '.', 37 MAPCHAR ',', 38 MAPCHAR '!', 39 MAPCHAR '?', 40 MAPCHAR '-', 41 MAPCHAR ''' , 42 </tt>

Now, when writing strings with EQUS, these codes will be written out instead of the default ASCII codes.

<tt> GUARD </tt>

Puts a 'guard' on the specified address which will cause an error if you attempt to assemble code over this address.

<tt> CLEAR, </tt>

Clears all guards between the and addresses specified. This can also be used to reset a section of memory which has had code assembled in it previously. BeebAsm will complain if you attempt to assemble code over previously assembled code at the same address without having CLEARed it first.

<tt> SAVE ["filename"], start, end [, exec [, reload] ] </tt>

Saves out object code to either a DFS disc image (if one has been specified), or to the current directory as a standalone file. A source file must have at least one SAVE statement in it, otherwise nothing will be output. BeebAsm will warn if this is the case.

If no filename is specified, the filename specified in the command line by -o will be used.

'exec' can be optionally specified as the execution address of the file when saved to a disc image. 'reload' can additionally be specified to save the file on the disc image to a different address to that which it was saved from. Use this to assemble code at its 'native' address, but which loads at a DFS-friendly address, ready to be relocated to its correct address upon execution. There is an example of this in the distribution, called 'relocdemo.asm'.

<tt> PRINT </tt>

Displays some text. PRINT takes a comma-separated list of strings or values. To print a value in hex, prefix the expression with a '~' character.

Examples:

<tt> PRINT "Value of label 'start' =", ~start PRINT "numdots =", numdots, "dottable size =" , dotend-dotstart </tt>

<tt> ERROR "message" </tt>

Causes BeebAsm to abort assembly with the provided error message. This can be useful for enforcing certain constraints on generated code, for example:

<tt> .table FOR n, 1, 32 EQUB 255 / n    NEXT IF HI (P%) <> HI (table) ERROR "Table crosses page boundary" ENDIF </tt>

<tt> FOR, start, end [, step] ... NEXT </tt>

I wanted this to have exactly the same syntax as BASIC, but I couldn't without rewriting my expression parser, so we're stuck with this for now.

It works exactly like BASIC's FOR...NEXT. For example:

<tt> FOR n, 0, 10, 2   ; loop with n = 0, 2, 4, 6, 8, 10 PRINT n    LDA #0: STA &900+n LDA #n: STA &901+n NEXT </tt>

The variable n only exists for the scope of the FOR...NEXT loop. Also, any labels or variables defined within the loop are only visible within it. However, unlike BBC BASIC, forward references to labels inside the loop will work properly, so, for example, this little multiply routine is perfectly ok:

<tt> .multiply \\ multiplies A*X, puts result in product/product+1 CPX #0: BEQ zero DEX : STX product+1 LSR A: STA product: LDA #0 FOR n, 0, 7 BCC skip: ADC product+1:.skip  \\ would break BBC BASIC! ROR A: ROR product NEXT STA product+1: RTS .zero STX product: STX product+1: RTS </tt>

<tt> IF...ELIF...ELSE...ENDIF </tt>

Use to assemble conditionally. Like anything else in BeebAsm, these statements can be placed on one line, separated by colons, but even if they are, ENDIF must be present to denote the end of the IF block (unlike BBC BASIC).

Examples of use:

<tt> \\ build a rather strange table FOR n, 0, 9 IF (n AND 1) = 0 a = n*n ELSE a = -n*n ENDIF EQUB a NEXT

IF debugraster: LDA #3: STA &FE21: ENDIF

IF rom ORG &8000 GUARD &C000 ELIF tube ORG &B800 GUARD &F800 ELSE ORG &3C00 GUARD &7C00 ENDIF </tt>

<tt> { ... } </tt>

Curly braces can be used to specify a block of code in which all symbols and labels defined will exist only within this block. Effectively, this is a mechanism for providing 'local labels' without the slightly cumbersome syntax demanded by some other assemblers. These can be nested. Any symbols defined within a block will override any of the same name outside of the block, exactly like C/C++ - not sure if I like this behaviour, but for now it will stay.

Example of use:

<tt> .initialise {    LDY #31 LDA #0 .loop             ; label visible only within the braces STA buffer,Y DEY BPL loop RTS } .copy {    LDY #31 .loop             ; perfectly ok to define .loop again in a new block LDA source,Y STA dest,Y DEY BPL loop RTS } </tt>

<tt> PUTFILE "host filename", ["beeb filename",] [, ] </tt>

This provides a convenient way of copying a file from the host OS directly to the output disc image. If no "beeb filename" is provided, the host filename will be used (and must therefore be 7 characters or less in length). A start address must be provided (and optionally an execution address can be provided too).

<tt> PUTBASIC "host filename" [, "beeb filename"] </tt>

This takes a BASIC program as a plaintext file on the host OS, tokenises it, and outputs it to the disc image as a native BASIC file. Credit to Thomas Harte for the BASIC tokenising routine.

<tt> MACRO [,<parameter list...>] ... ENDMACRO </tt>

This pair of commands is used to define assembler macros. Their use is best illustrated by an example:

<tt> MACRO ADDI8 addr, val IF val=1 INC addr ELIF val>1 CLC LDA addr ADC #val STA addr ENDIF ENDMACRO </tt>

This defines a macro called ADDI8 ("ADD Immediate 8-bit") whose function is to add a constant to a memory address. It expects two parameters: the memory address and the constant value. The body of the macro contains an IF block which will generate the most appropriate code according to the constant value passed in.

Then, at any point afterwards, the macro can be used as follows:

<tt> ADDI8 &900, 1        ; increment address &900 by 1 ADDI8 bonus, 10     ; add 10 to the memory location 'bonus' ADDI8 pills, pill_add ; pills += pill_add </tt>

Macros can also be called from other macros, as demonstrated by this somewhat contrived example:

<tt> MACRO ADDI16 addr, val IF val=0 ; do nothing ELIF val=1 INC addr BNE skip1 INC addr+1 .skip1 ELIF HI (val)=0 ADDI8 addr, val BCC skip2 INC addr+1 .skip2 ELSE CLC LDA addr ADC # LO (val) STA addr LDA addr+1 ADC # HI (val) STA addr+1 ENDIF ENDMACRO </tt>

Care should be taken with macros, as the details of the assembled code are hidden. In the above ADDI16 example, the C flag is not set consistently, depending on the inputs to the macro (e.g. it remains unchanged if val=0 or 1, and will not be correct if val<256).

Tips and tricks
BeebAsm's approach of treating memory as a canvas which can be written to, saved, and rewritten if desired makes it very easy to create certain types of applications.

Imagine wanting to create a program which used the BBC Micro's main RAM, plus 2 sideways RAM banks. If there was executable code in main RAM and in both banks, it's quite likely that you'd want to share label names amongst all of these blocks of code, so that main RAM routines could page in the appropriate RAM bank and call a routine in it, and likewise sideways RAM banks could call routines in main RAM.

Here's one way you could do that in BeebAsm:

<tt> \\ Declare origin of main RAM code ORG &1100 \\ Put a guard at the start of screen GUARD &5800 .mainstart LDA #5: STA &F4: STA &FE30  ; page in RAM bank 2 JSR bank2routine ...    .mainroutine ...    .mainend SAVE "Main", mainstart, mainend, mainentry \\ Declare origin of bank 1 code ORG &8000 \\ Put a guard after the RAM bank so we don't stray over our boundary GUARD &C000 .bank1start ...      JSR mainroutine ...    .bank1end SAVE "Bank1", bank1start, bank1end \\ Clear memory used by previous bank CLEAR &8000, &C000 \\ Declare origin of bank 2 code ORG &8000 \\ Put a guard after the RAM bank so we don't stray over our boundary GUARD &C000 .bank2start ...    .bank2routine RTS ...    .bank2end SAVE "Bank2", bank2start, bank2end </tt>

Because all of this code is assembled in one session, label and variable names persist across the assembly of all blocks of code.

For tidiness, you could move the source code for each block of code into a different file, and then just INCLUDE these in your main source file:

<tt> INCLUDE "main.asm" INCLUDE "bank1.asm" INCLUDE "bank2.asm" </tt>



Demo
There's a little assembler demo included called "demo.asm".

Build it with something like:

<tt> beebasm -i demo.asm -do demo.ssd -boot Code -v </tt>

and it will create a bootable disc image.

As well as demonstrating some of the features of BeebAsm (including building lookup tables), it's also a fairly good demo of pushing the hardware to its limits, in terms of creating a flicker-free animation, updating at 50Hz. (This is not to say that it's particularly impressive, but nonetheless, it really is pushing the hardware!!). Use 'Z' and 'X' to change the rotation speed and direction of the star globe.

There is also a demo called "relocdemo.asm", which shows how the 'reload address' feature of SAVE can be used to write self-relocating code. This is based on the above demo, but it runs at a low address (&300).

Reporting bugs
There are bound to be loads. I wrote it quickly! Please help me zap all the problems by reporting any bugs to me, Rich Talbot-Watkins, here or via email.

Thank you!

Richtw 13:10, 28 July 2009 (BST)