The OnBoard Asm User's Guide


The OnBoard Asm User's Guide

0.1

Copyright 2004, Steve Little. Permission is granted to copy and redistribute this document so long as it is unmodified (including the section that describes where to get this document for free) and the copyright remains intact. This should really be copyrighted by the OnBoard C group (both Yahoo! and SourceForge) since much of this has been gleaned from that discussion group but I don't know if that would be legally binding. The purpose of the copyright, anyway, is just to make sure that no one charges for the information, such as it is, that we're giving away for free.

Location. The latest version of this document can be obtained (for free) from http://onboardc.sourceforge.net/OnBAUsersManual.html. If you have any questions, comments, corrections or suggestions, please don't hesitate to send them to onba@boz.org.uk.

Thanks. A special thanks goes to the incredible legion of talented individuals who have contributed to this document. The list (in alphabetical order) can be found at the end of this document. If I've left anyone out, please contact me at the above address.



Table Of Contents

1. Introduction
1.1 Quickstart
1.2 Licensing
1.3 Why Use OnBoard Asm?
1.4 A Little History
1.5 Requirements
1.6 Where To Go For Help

2. Installation
2.1 The OnBoard Asm Distribution
2.2 Other Stuff You Might Need
2.3 Install OnBoard Asm

3. User's Tutorial
3.1 If You're Not Already A Palm Programmer (in assembler). . .
3.2 If You're An Old Hand At Writing Palm Code in m68k assembler. . .
3.3 A complete example

4. About The Language
4.1 How is OnBoard Asm Different From Pila?
4.2 OnBA Syntax
4.3 OnBA Directives
4.4 Useful Stuff
4.5 Limits

8. To Do

9. Thanks!

Appendix

A. Startup code



1. Introduction

This document is a user's guide for OnBoardAsm, part of the OnBoard Suite The whole suite was originally written by Roger Lawrence of Individeo. It runs on, as well as builds for the Palm handheld platform You can always get the latest version of the tools from the following address:

	http://sourceforge.net/projects/onboardc/

For more information about the rest of the Suite, please see The OnBoard Suite User's Manual.
The OnBoard assembler creates a Palm executable. You can beam your new program or hotsync it to another Palm if you like. It requires nothing but a Palm (w/ the Palm OS in ROM so your code can take advantage of the library that's there). It does not need a separate run-time library.


1.1 Quickstart

If you are fully familiar with Palm programming in assembler, you might want a quick way to get started with OnBoard Asm. That's described here. If you're not an expert at this stuff, however, you might want to check out some of the othersections of this document.

In order to get that quick start we talked about, do the following:

Download the tools.
Install the tools.
Create a source file.
Assemble and run your program.


1.2 Licensing

The OnBoard Assembler, like the rest of the OnBoard Suite, is provided under the GNU General Public License (GPL). There should be a file in your OnBoard Suite distribution entitled 'COPYING.txt' -- this file provides the entire license. If you can't find this file (or if you just want to), feel free to check out the Free Software Foundation website.

A quick note about this license. This license does NOT constrain code that you write and compile with any portion of the OnBoard Suite. You can write a program with SrcEdit, compile it with OnBoard C/OnBoard Asm, and sell the executable all day long. You do not have to give away the source to your code just because you used OnBoard Asm. In fact, the SourceForge OnBoard Suite people (i.e., the people who hold the copyright over this stuff) have agreed not to apply the GPL to the skeleton application that is generated by the OnBoard Suite -- you can start commercial applications with the skeleton.


1.3 Why Use OnBoard Asm?

OnBoard Asm is a C compiler for the Palm. There are other compilers for the Palm (e.g., CodeWarrior, GCC, PocketC) so why use OnBoard Suite? Here are some of the reasons.

OnBoard Asm uses native PalmOS APIs, so most of what you learn can be applied to desktop tools like Pila.
Further, since OnBoard Asm uses native APIs, most of the source code you will find in books written about coding Palms will work with OnBoard Asm, as well as the majority of free samples available online via Palm's website and other websites and Palm programming forums.
OnBoard Asm programs need no runtime and are thus easier to distribute.
OnBoard Asm allows access to native GUI resources.
OnBoard Asm runs on your Palm. Although some find this a bit restrictive, others enjoy being able to code during their daily commute on the train, on lunch breaks, etc. Some people just enjoy being able to get away from the traditional workstation they use every day.
You can assemble and test your code immediately.


1.4 A Little History

The OnBoard Suite was originally produced as a commercial product line (along with the RsrcEdit resource compiler) by Individeo At some point in the Fall of 2000 the developers at IndiVideo went their separate ways and Roger Lawrence, the one who developed OnBoard C, took the source code with him. Later, Roger generously released the binaries for the compiler and assembler to be distributed for free by the members of the OnBoard C community. RsrcEdit went to Quartus.net, developers of an onboard Forth compiler for the Palm, where it continues to be available as commercial software. It remains a key component of the OnBoard C IDE, but if you need support for that you'll have to visit Quartus.

OnBoard C started on it's path to becoming free open source software in March 2002, when Roger released the source to an editor he had built and used personally, but never released. Originally called LED--now renamed SrcEdit to avoid confusion with an existing product--this editor included many features specifically for use with OnBoard C and has been actively developed by the OnBoard C community.

In May, contact was reestablished with Roger, and he was shown the work that had been done on SrcEdit and asked if he might do one last build of OnBoard C for us that would fix a couple of nagging issues we were having. Attached to his email reply was the source code to the compiler and assembler.

That effort resulted in the source to the OnBoard Suite being placed under the GNU Public License (GPL) and put on the SourceForge site as an open source project. Note: a resource compiler (like RsrcEdit) is required to use the OnBoard Suite -- there are currently no GPLed resource editors that work with the OnBoard Suite.


1.5 Requirements

The OnBoard Suite runs on handheld computers running Palm OS >= 3.x. It may run under other versions of the operating system but it has been tested on these.


1.6 Where To Go For Help

There are two main places to go for help with the OnBoard Suite. Users can access the Yahoo OnBoard C discussion group. It was created to support OnBoard Suite users. There's a files section that contains documentation and other support material. Developers (and users, alike) can access the SourceForge site. The latest version of the OnBoard Suite can always be found there. There is a discussion group (available through the 'Lists' link) available to both users and developers. You can also visit the OnBoard Suite task list.

You can always report bugs and request features on the SourceForge site. When you report a bug, please do the following:

go to the bug reporting site and search (there's a search box on the left) to see if someone else has submitted the bug,
include a detailed description including the version number of the assembler,
explain the problem you see -- does the assembler crash, does the assembler generate an error message, does your code crash?
include a piece of code that will allow us to reproduce the problem.

Back to TOC.



2. Installation


2.1 The OnBoard Asm Distribution

For any particular OnBoard Suite release, you can download one of four different files from the SourceForge site. You can download the source or just the executables and, for each of those, you can download a .zip archive or a .tar.gz archive. If you download just a source archive, you'll have to build it (with the PRC tools or one of the other supported environments) to get the PRCs.


2.2 Other Stuff You Might Need

There will be some things other than the OnBoard Suite download that you'll need to be able to create code.


RsrcEdit

RsrcEdit (RsrcEdit.prc). RsrcEdit builds the forms for the user interface. Quartus, by the way, is grandfathering-in previously registered owners of RsrcEdit. You can get it from here.


Documentation

This User's Guide.
The M68000 Programmers Reference Manual
Pila Is a Palm assembler which runs on Windows and *nix. The User Manual contains some very useful information.


Helpful Source Code

Sometimes nothing helps like looking at someone else's code. Here are some resources for Palm source code.


2.3 Install OnBoard Asm


Install OnBoard Asm

In order to install OnBoard Asm, unpack your distribution (e.g., onboard_2_0_1b.zip). On a MS-Windows platform, you can do this with WinZip, StuffIt, or even (with WinME, at least) with MS-Windows, itself. On a Linux (or other Unix) platform, use 'tar' and 'gzip'. Once you get things unpacked, install the following:

OnBoard.prc. This is the assembler.
SrcEdit.prc. SrcEdit is a programmer's editor that allows you to edit DOC files for use as source files for your OnBoard projects.
systraps.inc.pdb. This is an include file (optionally) used by OnBoard Asm, containing definitions of some systrap numbers, which is helpful if you don't want to have to remember them by number.

On MS-Windows, you can do this by double clicking on each of the files (assuming that you've installed the Palm Desktop). There are operating-system-specific ways to install Palm applications for many other host systems -- use whatever is appropriate.


Install the Other Stuff You Need (see above)

Unfortunately, the OnBoard Suite requires a component that's not free (it's shareware). In order to use the OnBoard Suite, you need to create resource files. The software that does that is RsrcEdit.prc. Get a copy of this software and install it like the other prc files. At some point, OnBoard might support the 'res' directive used by Pila, so that you can create resources that way, but as yet this feature has not been added.


Bring It Up

Now that you've installed everything, go to your Palm and tap the OnBoard Asm icon. You will then see the main screen of OnBoard Asm, prompting you to select a file to assemble

Tap either Memo or Doc, depending on what type of source file you wish to assemble
Tap the name of the file.
Tap 'Build'.

If all assembles correctly, a new PRC should be created for you in the Unfiled category. Simple as that...

Back to TOC



3. User's Tutorial


3.1 If You're Not Already A Palm Programmer . . .

Assembling programming is not for the faint of heart, and Palm Assembly probably less so. As such, id you don't have any prior experience with programming for Palm OS, you probably don't want to start here. Instead you might want to consider starting in a higher level language such as C. See The OnBoard Suite User's Manual for more information about programming the Palm in C. Likewise, if you've never done any assembler, this might not be the ideal platform to start with. This manual does not attempt to teach assembler programming, merely the use and eccentricies of OnBoard Asm.

Depending on your current programming knowledge, you may want to attack the learning process differently. Feel free to choose your own route -- the OnBoard community will be happy to help you no matter what your level of experience is. The suggestions, here, are intended only to make your path to programming in OnBoard C as painless as possible.

If you're already programming in assembler for PalmOS using Pila or a similar assembler, you won't have much trouble using OnBoard Asm. Skip to the next section.



3.2 If You're An Old Hand At Writing Palm Code in m68k Assembler. . .

After you install the tools, you need to create source files and get them to assemble. Here's a quick start guide to get you going:

Using SrcEdit or another DOC editor, create a new document. Call it <something>.asm
At the top of the file, you need a few things:
- a directive to tell OnBA what to call the prc:
  prc "prcname"
- a directive to tell OnBA what creator ID to use:
  creator "myAp"
- a directive to tell OnBA that this code segment starts here:
  code
From then on, you just need the rest of the code
Once you've written your assembler document, fire up OnBA
Select 'DOC'. Your assembler document (and any other documents names <something>.asm should show up in the list. Select it and hit Build.
Correct any errors, add more code, rinse and repeat.

OnBA adds bootstrap code to your application automatically. For a complete listing of the bootstrap code that it adds, see Appendix A.



3.3 A complete example

This example is based largely on the 'Minimal Pilot Application' from the Pila User's Manual. Credit and thanks go to Darrin Massena and Wes Cherry, who wrote that manual.

; Simple skeleton app ; ; name of the prc to produce prc "testasm" code ; some equ's of common systrap names include "systraps.inc" proc PilotMain_00(cmd.w, cmdPBP.l launchFlags.w) local err.w local evt.18 beginproc tst.w cmd(a6) bne PmReturn systrap FrmAlert(#1000) PmReturn endproc

Back to TOC



4. About The Language


4.1 How is OnBoard Asm Different From Pila?


4.2 OnBA Syntax


4.3 OnBA Directives

OnBA supports the following directives:

prc "prc name"
The name of the prc file to create.
The combination of this directive and the creator directive (below) are the equivalent of the appl directive in Pila.
creator "creatorID"
The creator ID to use.
code <num>
This puts OnBA into code generation mode. OnBA is always in either code generation or data generation mode, which determines where the output of the assembly will be placed. By specifying a number, you can specify which segment number the code will be placed in.
data
This puts OnBA into data generation mode. See above.
beginproc
Marks the beginning of a procedure. OnBA will automatically generate a link a6,#nnn instruction, where nnn is the negative sum of the size of all locals.
dc.size value
Data Constant. Insert data into the code.
endproc
Marks the end of a procedure. OnBA will automatically generate the required unlk and rts instructions
name equ value
Defines name to be equal to value. Whenever name is used from then on, OnBA will substitute the value in it's place.
include "filename"
Causes OnBA to insert the specified file at the current location.
local localname.size
Declares a local procedure variable. This directive is only valid between a proc and a beginproc directive.
proc (arg1.size, arg2.size, ...)
Declares a procedure, which may have zero or more arguments.
systrap trapname/#trapnum(arg1, arg2, ...)
Calls the specified systrap. OnBA will automatically emit the code to push the arguments onto the stack, invoke the trap, then cleanup the stack. Either use a trapname, previously declared with an equ, or the trap number, prefixed with a #.


4.4 Useful Stuff

systraps.inc
The file systraps.inc is included in the OnBA distribution and contains a list of equs for systraps, so that the symbolic names can be used in your application instead of the trap number. To use, simply add 'include "systraps.inc"' to the top of your source file, inside of a code section



8. To do



8.1 Things to add to this document.

OnBA adds bootstrap code

Useful stuff - systraps.inc

Directives OnBA understands

Instructions OnBA doesn't understand

Don't use 'end'

How to use memo files

Stuff from John's inline asm doc

Explanations of some error messages

Back to TOC



9. Thanks!

I'm going to try to get everyone. If you contributed or know someone who did that's not in here, please let me know.

	Keithen and Roger at individeo.net
	"Darrin Massena" <darrin at massena.com>
	"Wes Cherry" <wesc at ricochet.ney>
	"Wade Guthrie" <wade at adventure101.com>
	"John Wilund" <orlando at runbox.com> 
	"Reverend" <reverndi at yahoo.com>

Back to TOC



A. Startup code

For those that are interested, here's a listing of the startup code OnBA atomatically adds to your application:

0x4e56, 0xfff4, // LINK A6,#-12 0x486e, 0xfff4, // PEA -12(A6) 0x486e, 0xfff8, // PEA -8(A6) 0x486e, 0xfffc, // PEA -4(A6) 0x4e4f, // TRAP #15 0xa08f, // DC.W sysTrapSysAppStartup 0x4fef, 0x000c, // LEA 12(A7),A7 0x4a40, // TST.W D0 0x670e, // BEQ L1 0x1f3c, 0x0003, // MOVE.B #3,-(A7) 0x4e4f, // TRAP #15 0xa234, // DC.W sysTrapSndPlaySystemSound 0x548f, // ADDQ.L #2,A7 0x70ff, // MOVEQ #-1,D0 0x603e, // BRA L2 0x206e, 0xfffc, // L1 MOVEA.L -4(A6),A0 0x3f28, 0x0006, // MOVE.W 6(A0),-(A7) 0x2f28, 0x0002, // MOVE.L 2(A0),-(A7) 0x3f10, // MOVE.W (A0),-(A7) 0x6612, // bne.s *+20 -- skip datainit if cmd != normalLaunch 0x7001, // moveq #1,d0 0x204D, // move.l a5,a0 0x4EBA, 0x002C, // jsr *+6 -- call datainit 0x7002, // moveq #2,d0 0x41FA, 0x0090, // lea 90(pc),a0 -- start of startupCode, hence start of CODE #1 0x4EBA, 0x0022, // jsr *+6 -- call datainit 0x4EBA, 0x0000, // jsr main 0x508f, // ADDQ.L #8,A7 0x2f2e, // MOVE.L -12(A6),-(A7) 0xfff4, 0x2f2e, // MOVE.L -8(A6),-(A7) 0xfff8, 0x2f2e, // MOVE.L -4(A6),-(A7) 0xfffc, 0x4e4f, // TRAP #15 0xa090, // DC.W sysTrap SysAppExit 0x4fef, // LEA 12(A7),A7 0x000c, 0x7000, // MOVEQ #0,D0 0x4e5e, // L2 UNLK A6 0x4e75, // RTS // datainit (@54) : 0x4E56, 0x0000, // link a6,#0 0x48E7, 0x1E38, // movem.l d3-d6/a2-a4,-(a7) 0x2A08, // move.l a0,d5 0x3F00, // move.w d0,-(a7) 0x2F3C, 0x6461, 0x7461, // move.l #'data',-(a7) 0x4E4F, // trap #15 0xA05F, // sysTrapDmGetResource 0x2448, // movea.l a0,a2 0x47ED, 0x0000, // lea 0(a5),a3 // this is set to -totalDataSize (i.e. the base of the data block) 0x200A, // move.l a2,d0 0x5C4F, // addq.w #6,a7 0x6740, // beq.s *+64 0x2F0A, // move.l a2,-(a7) 0x4E4F, // trap #15 0xA021, // sysTrapMemHandleLock 0x2848, // movea.l a0,a4 0x7800, // moveq #0,d4 0x584F, // addq.w #4,a7 0x601E, // bra.s *+30 ; 0x00000050 0x1C1C, // move.b (a4)+,d6 0x7607, // moveq #7,d3 0x6012, // bra.s *+18 ; 0x0000004a 0x7001, // moveq #1,d0 0xE768, // lsl.w d3,d0 0x7200, // moveq #0,d1 0x1206, // move.b d6,d1 0xC240, // and.w d0,d1 0x6702, // beq.s *+4 ; 0x00000048 0xDB93, // add.l d5,(a3) 0x548B, // addq.l #2,a3 0x5343, // subq.w #1,d3 0x4A43, // tst.w d3 0x6CEA, // bge.s *-18 ; 0x0000003a 0x5244, // addq.w #1,d4 0x0C44, 0x0000, // cmpi.w #0000,d4 0x6DDC, // blt.s *-32 ; 0x00000034 0x2F0A, // move.l a2,-(a7) 0x4E4F, // trap #15 0xA022, // sysTrapMemHandleUnlock 0x2F0A, // move.l a2,-(a7) 0x4E4F, // trap #15 0xA061, // sysTrapDmReleaseResource 0x504F, // addq.w #8,a7 0x4CDF, 0x1C78, // movem.l (a7)+,d3-d6/a2-a4 0x4E5E, // unlk a6 0x4E75 // rts

This may change in future releases of OnBA, and is correct as of v2.4.

Back to TOC