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 .included file).