Showing changes from revision #6 to #7: Added | Removed | Changed

Contents

• Introduction & “Hello world!” (this page)
• Structure of ObjAsm source files
• Constants, literal pools, and structure/workspace definitions
• Macros and conditional assembly
• Variables and repetitive assembly
• Multiple source files
• objasm command line args
• Adding assembler to C programs
• ???
• Profit!

Introduction

This series of articles aims to be a beginner’s guide to the ObjAsm assembler, suitable for people who are already familiar with BASIC assembler. The guide should also be suitable for people who are interested in learning how to use asasm (the free clone of ObjAsm that comes with the RISC OS port of GCC).

ObjAsm’s place in the world

ObjAsm is an ARM assembler that first appeared in the Acorn Desktop Development Environment. Development of the DDE is now managed by ROOL and the latest version can be purchased from the ROOL store. However, there are several other assemblers available which have a similar assembler syntax and feature set to ObjAsm. One of these is asasm, the free ObjAsm clone that comes with the RISC OS port of GCC. Another assembler which is similar to ObjAsm is ARM’s armasm, which forms part of ARM’s official compiler suite, and has a shared history with ObjAsm.

Documentation held elsewhere

Currently, the only way of getting hold of a copy of the latest ROOL ObjAsm manual is to buy one of the appropriate products from the ROOL store, such as the DDE or the DDE manuals box set. This is fine for users of ObjAsm, but leaves users of asasm a bit out in the cold.

asasm users, or people on the go, are encouraged to check out these other sources of documentation for ObjAsm-like assemblers:

• RISCOS Ltd’s Acorn Assembler manual – This is for an old version of ObjAsm (circa 1994), but the basic information about the assembler syntax and directives is still applicable to modern versions.
• The armasm User Guide – The user guide for the latest version of ARM’s armasm. ObjAsm generally lags behind armasm a bit when it comes to implementing new features, however most of the content should still be applicable to both ObjAsm and asasm.

Hello world!

As a seasoned BASIC assembler user, if you wanted to write a simple standalone “Hello, world!” app then you would probably write something similar to the following:

ON ERROR PRINT REPORT$;" at ";ERL : END
DIM code% 256

FOR pass=12 TO 14 STEP 2
O%=code%
P%=&8000
L%=code%+256

[ OPT pass
SWI "OS_WriteS"
EQUS "Hello, world!"
EQUB 0
ALIGN
SWI "OS_NewLine"
MOV R0,#0
LDR R1,abex
MOV R2,#0
SWI "OS_Exit"
.abex
EQUD &58454241 ; "ABEX"
]

NEXT pass
SYS "OS_File",10,"helloworld",&ff8,,code%,O%

Running the above BASIC file would then save a “helloworld” absolute file in the current directory, which when run will output a familiar “Hello, world!” message.

The same thing, converted to objasm, would look roughly as follows:

OS_WriteS * &01
OS_NewLine * &03
OS_Exit * &11

    AREA helloworld, CODE, READONLY

    ENTRY

    SWI OS_WriteS
    = "Hello, world!"
    DCB 0
    ALIGN
    SWI OS_NewLine
    MOV R0,#0
    LDR R1,abex
    MOV R2,#0
    SWI OS_Exit
abex
    DCD &58454241 ; "ABEX"

    END

If you save this as the file “source” then you should be able to assemble it to an equivalent “helloworld” Absolute file by entering the following two commands:

objasm source -o object
link object -o helloworld

By comparing the two versions we can start to see places where objasm differs from BASIC assembler:

• When assembling an Absolute file in BASIC, you must use P% to specify that the code should be assembled for running at &8000. With ObjAsm, although you can use the ORG directive to specify the base address of an AREA, you’d usually want to leave it unspecified and allow the linker to fix up the code so that it will work at the target address.
• The binary produced by objasm/link is larger than the one produced by BASIC – the linker will have automatically added a 128 byte AIF header to the file. For a simple example like this the addition of the header may feel like overkill, but for real projects the addition of a standard header far outweighs the cost of the increased binary size.
• SWI instructions in BASIC use quoted strings to specify the SWI name. With ObjAsm, they must be numeric expressions (and in the case of this example we use symbolic constants to map SWI names to numbers)
• All instructions and data must be within an “area”, the start of which is indicated by the use of the AREA directive. Each area has a name (e.g. “helloworld”) and a list of attributes (e.g. “CODE” and “READONLY”), the significance of which will be covered in the next section.
• With ObjAsm, instructions, data, and most directives must be indented (spaces or tabs are fine). This differentiates them from label and constant/variable definitions which always appear at the start of the line.
• BASIC has two identical sets of directives for declaring data – the “EQU” set (EQUS, EQUB, EQUD, etc.) and the “DC” set (DCS, DCB, DCD, etc.). Since the two sets are identical, you’ll typically either stick to using the one you were first taught or the one you prefer. On the other hand, ObjAsm only supports the directives which start “DC”. Also there’s no EQUS/DCS, you must use = to declare strings.