Directives Index

Here's a list of all the directives which are supported by the SB-Assembler, grouped by their functions. Each directive is described on its own page. Once you're on such a page you can browse forward and backwards through all the directives pages, in alphabetical order, using the menu in the top right hand corner of the page. The index button there will bring you back to this index page.
If you start with .AS, you can work your way through all the directives until .XM, which is the last one.

Directives

A directive is a command to the assembler and thus it is not an instruction for the target microprocessor. Directives are often called pseudo instructions because they appear in the instruction field of the source line. Directives are always placed in the instruction field on program lines and may be followed by one or more operands.
The SB-Assembler uses a special notation for directives. All directives start with a dot, followed by 2 characters. This means that existing code must be changed to represent the SB-Assembler convention when it comes to directives. However this can easily be done with the replace command found in many text editors.

SB-Assembler directives always begin with a dot which is followed by two or more characters. This makes it easier to distinguish directives from mnemonics and avoids name clashes with future mnemonics on new Crosses.
All directives consist of 2 characters, which are usually an abbreviation or acronym of the full directive's name. The SB-Assembler only checks the first 2 characters following the dot to see if it is a legal directive. All other characters following the first 2 are ignored until the next space, TAB or EOL.
Most directives are common to all Cross Overlays. But each Cross Overlay can have its own set of additional directives, e.g. the 6809 Cross knows its own unique .DP directive which sets the Direct Page.
Some Cross Overlays may also change the behaviour of some of the standard directives to suit the needs or peculiarities of the serviced processor type. Some directives may even be disabled by Cross Overlays if their use may cause problems for that particular Cross Overlay.
In any case such Cross specific directives only exist as long as the Cross Overlay is loaded into memory.

Some directives must or may be followed by one or more parameters. Those parameters may not contain space or TAB characters because that will signal the end of the parameter. Only literal strings may contain spaces as long as they are properly enclosed in delimiters.
Parameters must be separated from each other by a comma. The SB-Assembler stops interpreting parameters as soon as it finds a space, TAB or EOL character.
Only Version 3 of the SB-Assembler allows the use of one optional space directly following a comma to improve readability.

Document Conventions

I use some common document conventions in the following description of the directives.
Optional parameters that may follow the directives are enclosed in square brackets [ ]. For example [-]string means that the - sign is an optional part of the parameter.

Text printed in Italic font should not be typed literally but indicates the type of the expected parameter. For example filename should be replaced by the real file name, possibly including drive and path. In Version 2 of the SB-Assembler file names and paths are restricted to the normal MS-DOS 8.3 file names. For Version 3 of the SB-Assembler file and path names must follow the rules of your operating system.
Directives which use file names sometimes assume a default extension suitable for the function. For example the .IN directive assumes the extension to be .asm if it is omitted. This doesn't mean that you are not able to use other extensions. If the extension you want to use differs from the default extension it must be given explicitly.
Please note that file and path names are case sensitive on Unix like operating systems. This also applies to the default file extensions, which will always be lower case. This only applies to Version 3 of the SB-Assembler, because other versions don't run on Unix like operating systems.
With Version 2 of the SB-Assembler some directives also allow you to use device names in stead of file names like LPT1: COM1: or PRT:. Device names must always end in a colon.

Sometimes you can use one of several options. These options are separated by a pipe | symbol in this document. For example on | off means you may either use on or off. Notice that on and off are not printed in Italic, therefore they should be typed literally.

Strings should be delimited. This means that a legal delimiting character must be used to enclose the string. All characters in between the two delimiters are treated literally, spaces and upper and lower case are retained.
Almost any character may be used as delimiter. Only the characters dash - , a comma , , a dot . , a colon : and the character A to Z are not allowed to be used as delimiter. Often used delimiters are " ' / \ ! | .
The delimiter itself may not be used inside the string because that would end the string literal. The full standard ASCII character set with values between $32 and $126 can be used as string characters. Characters from the extended IBM character set are not allowed in strings and can have unpredictable results.

Expressions can be composed of constant values in any of the available radixes, labels and expressions. These expressions always result in a 32 bit value. The directive decides how many of the 32 bits are actually used.

Please note that I sometimes uses spaces in the Syntax example to make the different options of a set of parameters more readable. These spaces are not allowed in your source code of course!

Boundary Sync

Version 3 of the SB-Assembler is better prepared for processors which use multi byte instructions. The problem with multi byte instructions is that the target file pointer will grow faster than the instruction pointer. For normal program instructions this is not really a problem because each instruction will generate the same amount of bytes.
However when we start using directives to generate data bytes this may become a problem because we may generate single bytes, or an odd number of bytes, leaving the instruction pointer somewhere in the middle of two instructions. Therefore each generated instruction will automatically be forced to start at the next instruction boundary, even when we previously generated an odd number of data bytes. No problem so far.
But what if we want to write a block of text lines to memory for instance? If we allow each directive to automatically sync the program pointer to the next instruction boundary, we might end up with unwanted padding bytes in our block of text. These fill bytes have the value $00, which might be mistaken for the end of string marker by your program.
Therefore most data generating directives will NOT perform an automatic boundary sync. Some directives however will perform a boundary sync, simply for logical reasons. For instance the .OR directive will always start the instruction pointer on an instruction boundary. Not doing so would make not much sense.
A special directive .EV is provided for you in case you want to force the assembler to do a boundary sync. You may want to do that for instance to align the next data block with the instruction pointer, to allow proper label assignment. Please note that you can't assign a label to a fractional part of the instruction pointer with multi byte processor types like the AVR and PIC series.

A boundary sync, when executed by the directive, is always executed before the actual function of the directive kicks in. With the description of each directive I will mention whether it performs a boundary sync or not.

In version 2 of the SB-Assembler there was no such thing as a boundary sync. This caused many problems when using multi-byte processors. Therefore I have redesigned the behaviour of the SB-Assembler in version 3.