Programming with Ophis
<<< Previous | Ophis Command Reference |

# Assembler directives

Assembler directives are all instructions to the assembler that are not actual instructions. Ophis's set of directives follow.

- `.advance` address: Forces the program counter to be address. Unlike the `.org` directive, `.advance` outputs zeroes until the program counter reaches a specified address. Attempting to `.advance` to a point behind the current program counter is an assemble-time error.

- `.alias` label value: The .alias directive assigns an arbitrary value to a label. This value may be an arbitrary argument, but cannot reference any label that has not already been defined (this prevents recursive label dependencies).

- `.byte` arg [ , arg, ... ]: Specifies a series of arguments, which are evaluated, and strings, which are included as raw ASCII data. The final results of these arguments must be one byte in size. Seperate constants are seperated by comments.

- `.checkpc` address: Ensures that the program counter is less than or equal to the address specified, and emits an assemble-time error if it is not. This produces no code in the final binary - it is there to ensure that linking a large amount of data together does not overstep memory boundaries.

- `.data` [label]: Sets the segment to the segment name specified and disallows output. If no label is given, switches to the default data segment.

- `.incbin` filename: Inserts the contents of the file specified as binary data. Use it to include graphics information, precompiled code, or other non-assembler data.

- `.include` filename: Includes the entirety of the file specified at that point in the program. Use this to order your final sources.

- `.org` address: Sets the program counter to the address specified. This does not emit any code in and of itself, nor does it overwrite anything that previously existed. If you wish to jump ahead in memory, use `.advance`.

- `.require` filename: Includes the entirety of the file specified at that point in the program. Unlike `.include`, however, code included with `.require` will only be inserted once. The `.require` directive is useful for ensuring that certain code libraries are somewhere in the final binary. They are also very useful for guaranteeing that macro libraries are available.

- `.space` label size: This directive is used to organize global variables. It defines the label specified to be at the current location of the program counter, and then advances the program counter size steps ahead. No actual code is produced. This is equivalent to `label: .org ^+size`.

- `.text` [label]: Sets the segment to the segment name specified and allows output. If no label is given, switches to the default text segment.

- `.word` arg [ , arg, ... ]: Like `.byte`, but values are all treated as two-byte values and stored low-end first (as is the 6502's wont). Use this to create jump tables (an unadorned label will evaluate to that label's location) or otherwise store 16-bit data.

- `.dword` arg [ , arg, ...]: Like `.word`, but for 32-bit values.

- `.wordbe` arg [ , arg, ...]: Like `.word`, but stores the value in a big-endian format (high byte first).

- `.dwordbe` arg [ , arg, ...]: Like `.dword`, but stores the value high byte first.

- `.scope`: Starts a new scope block. Labels that begin with an underscore are only reachable from within their innermost enclosing `.scope` statement.

- `.scend`: Ends a scope block. Makes the temporary labels defined since the last `.scope` statement unreachable, and permits them to be redefined in a new scope.

- `.macro` name: Begins a macro definition block. This is a scope block that can be inlined at arbitrary points with `.invoke`. Arguments to the macro will be bound to temporary labels with names like `_1`, `_2`, etc.

- `.macend`: Ends a macro definition block.

- `.invoke` label [argument [, argument ...]]: invokes (inlines) the specified macro, binding the values of the arguments to the ones the macro definition intends to read. A shorthand for `.invoke` is the name of the macro to invoke, backquoted.

The following directives are deprecated, added for compatibility with the old Perl assembler P65. Use the `-d` option to Ophis to enable them.

- `.ascii`: Equivalent to `.byte`, which didn't used to be able to handle strings.

- `.code`: Equivalent to `.text`.

- `.segment`: Equivalent to `.text`, from when there was no distinction between `.text` and `.data` segments.

- `.address`: Equivalent to `.word`.

- `.link` filename address: Assembles the file specified as if it began at the address specified. This is generally for use in "top-level" files, where there is not necessarily a one-to-one correspondence between file position and memory position. This is equivalent to an `.org` directive followed by an `.include`. With the introduction of the `.org` directive this one is less useful (and in most cases, any `.org` statement you use will actually be at the top of the `.include`d file).

<<< Previous | Home |
Macros | Up |