cokedasm

dasm, by Matthew Dillon, is an excellent assembler that works with several Motorola processors. It is certainly the best assembler I have used for the 68HC11.

cokedasm is dasm with certain CokeOS- and Libcoke-specific additions. It can:

generate relocatable modules
generate wrapper functions in c -- a ".c" file with the functions and a ".h" file with the prototypes
generate c header files (".h" files) that "#define" all of the important symbolic constants
accept include statements with pointy brackets ("include <coke.inc>") and look for the files in /usr/local/include and /usr/include

The standard dasm command line options are supported and are described in the dasm documentation. Here are the new options:

-r generate a relocatable module. (It is recommended that the output file ("-o" option) end with the suffix ".rel".) The format of a reloctable module is:

word (lobyte, hibyte) - number of bytes of code that follows

code, referenced to an origin of $0000

word (loybyte, hibyte) - number of entries in the relocation table

relocation table. Each entry is a pointer (lobyte, hibyte), referenced to the start of code, of a hibyte that needs adjustment when the code is loaded into memory. The hibyte of the final memory start address will be added to this byte. The lobyte of the final memory start address should be zero, since code resources should be loaded page-aligned.

-cpath generate ".c" and ".h" files with wrapper functions for the modules in the file. path is where the ".c" file should go; if path is unspecified, the ".c" file is put in the current directory.

-hpath specifies where to put the ".h" file, if the -c option is given. If the -h option is not given, the ".h" file is put in the current directory.

-nfile.h generate a c header file that "#define"s symbols that begin with the following: COKE_, ID_, CMD_, ERROR_, MESSAGE_, and EGFX_.

reldasm

To make things nice and easy, there is a shell script reldasm available that will provide all the command line arguments for assembling user modules. If you enter:

reldasm button

The script will first assemble coke.inc with the -n option, so any changes that you made to user.inc will be reflected in cokedef.h. It will then issue the command:

cokedasm button.asm -r -obutton.rel -lbutton.lst -c

If the assembly fails because of undefined symbols, you can enter

reldasm button -v3

to list undefined symbols. Be sure to note that reldasm's argument is just the module name by itself, without the ".asm" suffix.

The module header format

In order for cokedasm to generate c wrapper functions, it needs to know the commands that it is trying to wrap, and their parameters. It finds this out by reading the comments at the top of the assembly file. This of course means that the comments should be in a certain format.

The header of the file should consist of comment lines that begin with the '!' character. It is similar to ';' but cokedasm may look at it to see if it's interesting. If cokedasm finds a line of the form

! Module name: Blah

it starts generating "blah.c" and "blah.h" files, after closing any wrapper files it was generating before for another module. It then looks for a line of the form

! Commands:

It will then interpret the following lines as command descriptions until a blank line is found. I think. A command description is of the form:

[special] [returnType] CommandName ( [ parameterType parameterName [, ...]] )

where the things in [ ] are optional. If special is specified, cokedasm ignores the rest of the line and does not generate a wrapper function for the command. The wrapper functions for special commands should be written by hand and put in "special.c".

If returnType is given, the command is assumed to return COKE_QUERY when successful. returnType can be one of the following:

byte the query result is one byte, and will be put into a variable of type cokebyte.

word the query result is two bytes (lobyte, hibyte) and will be put into a variable of type cokeword.

string the query result is a variable number of bytes, and will be put into a buffer given by a char*, with a null-terminator.

If the command has parameters, they should be specfied within the parentheses and separated by commas. parameterType must be one of the following:

byte one byte parameter, given as type cokebyte

word two byte parameter (lobyte, then hibyte), given as type cokeword

cstring variable-length parameter that ends with a zero byte, given as type char*

pstring variable-length parameter where the first byte is a length byte and specifies the number of bytes that follow, given as type char*

byte[num] fixed-length parameter of length num, given as type cokebyte*

word[num] fixed-length parameter of num words, given as type cokeword*

Source

Source code for cokedasm can obviously not be publicly distributed, because dasm can only be distributed in unmodified form. The source is on rutabaga somewhere. It's ugly enough to make you vomit.

-r	generate a relocatable module. (It is recommended that the output file ("-o" option) end with the suffix ".rel".) The format of a reloctable module is: word (lobyte, hibyte) - number of bytes of code that follows code, referenced to an origin of $0000 word (loybyte, hibyte) - number of entries in the relocation table relocation table. Each entry is a pointer (lobyte, hibyte), referenced to the start of code, of a hibyte that needs adjustment when the code is loaded into memory. The hibyte of the final memory start address will be added to this byte. The lobyte of the final memory start address should be zero, since code resources should be loaded page-aligned.
-cpath	generate ".c" and ".h" files with wrapper functions for the modules in the file. path is where the ".c" file should go; if path is unspecified, the ".c" file is put in the current directory.
-hpath	specifies where to put the ".h" file, if the -c option is given. If the -h option is not given, the ".h" file is put in the current directory.
-nfile.h	generate a c header file that "#define"s symbols that begin with the following: COKE_, ID_, CMD_, ERROR_, MESSAGE_, and EGFX_.

byte	the query result is one byte, and will be put into a variable of type cokebyte.
word	the query result is two bytes (lobyte, hibyte) and will be put into a variable of type cokeword.
string	the query result is a variable number of bytes, and will be put into a buffer given by a char*, with a null-terminator.

byte	one byte parameter, given as type cokebyte
word	two byte parameter (lobyte, then hibyte), given as type cokeword
cstring	variable-length parameter that ends with a zero byte, given as type char*
pstring	variable-length parameter where the first byte is a length byte and specifies the number of bytes that follow, given as type char*
byte[num]	fixed-length parameter of length num, given as type cokebyte*
word[num]	fixed-length parameter of num words, given as type cokeword*