Assembler Directives
The integrated assembler in WinAPE is fully backwards compatible with Maxam 1.5, but provides some extensions to the syntax.
| Command | Description |
| align boundary[,fill] | Align code to a given boundary
and fill the space with the given fill. If fill is not specified it will
be filled with 0 bytes. eg. align 256,#ff will insert #ff bytes up
to the next 256 byte page boundary. If the code is already aligned, no bytes will be
generated. |
| brk | Generates an rst #30 Maxam style breakpoint. |
| byte value{,value...} | Equivalent to defb. |
| charset [string,value|byte,value|start,end,value] | Allows the value of characters or characters in strings to be assigned alternative values. There are 4 forms of this directive. charset on its own defines all 256 characters to have their original ASCII values. charset string,value allows each character in the given string to be assigned consecutive values starting at value. charset byte,value allows a single character to be redefined, and finally charset start,end,value allows the characters starting with start to and ending at end to be assigned consecutive values starting at value. For more information see Redefining Characters. |
| checksum reset [initial value] | Reset checksum generation with the given initial value or 0 if not specified. |
| close | Closes the output from a write or write direct directive. |
| code | Enables code generation. See nocode below. |
| db value{,value...} | Alternative short form of defb. |
| defb value{,value...} | Takes a list of byte or string
values and generates a byte for each value or for each character in a string.
Strings may be enclosed in double or single quotes. eg. defb
"Hello",32,"t" - 32,'here',10 would generate the bytes (hexadecimal)
48 65 6C 6C 6F 20 54 68 65 72 65 0A |
| label defl value | Equivalent to equ. |
| defm value{,value...} | Equivalent to defb. |
| defs size[,fill]{,size[,fill]...} | Generate size bytes
of fill or 0 bytes if fill is not specified. A number of consecutive
regions can be specified with individual fill bytes. eg. defs
3,#ff,4,0,5,#80,2 would generate the bytes (hexadecimal)
FF FF FF 00 00 00 00 80 80 80 80 80 00 00 |
| defw value,{value...} | Takes a list of values which are
written out as 16 bit little-endian words. eg. defw #1234, #abcd, 1,
2000 would generate the bytes (hexadecimal)
34 12 CD AB 01 00 D0 07 |
| dm value{,value...} | Equivalent to defb. |
| ds size[,fill]{,size[,fill]...} | Alternative short form of defs. |
| dump | Not currently implemented. Maxam used it to write symbol information. |
| dw value{,value...} | Alternative short form of defw. |
| else | Conditionally assembles the following section up until another else, elseif or endif if another previous if or elseif at the same depth has not been assembled. |
| elseif condtion | Conditionally assembles the following section up until another else, elseif or endif if another previous if or elseif at the same depth has not been assembled and the condition evaluates to a non-zero value. |
| end | Marks the end of an assembler program. All following code will be ignored. An end directive found inside a file included with read also causes all following code to be ignored both inside the include file, and every parent file. |
| endif | Marks the end of a conditional code section. |
| endm | Equivalent to mend. |
| label equ value | Defines a symbol label and
assigns it a value. The value must be fully able to be evaluated on the
second pass of the assembler. eg. MC_WAIT_FLYBACK equ &BD19
|
| if condtion | Conditionally assembles the following section up until an else,elseif or endif if the given condition evaluates to a non-zero value. |
| ifdef symbol | Conditionally assemblers the following section up until an else,elseif or endif if the given symbol has already been defined. |
| ifndef symbol | Conditionally assemblers the following section up until an else,elseif or endif if the given symbol has not already been defined. |
| ifnot condtion | Conditionally assembles the following section up until an else,elseif or endif if the given condition evaluates to zero. |
| incbin filename[,offset[,size[,offset_high]]] | Includes the file with the given filename in the assembly as binary data. The offset within the file is calculated as offset_high * 65536 + offset, and the size can be up to 65535 (#ffff) bytes. Multiple incbin directives can be used to read more of the file. The file may contain any binary data and is simply output byte by byte to the generated output. See Including other source files for more information. |
| let symbol = value | The let directive is similar to equ except it allows symbols to be redefined. Most assembler symbols should only ever have a single value and should usually be defined with equ. Do not redefine symbols with let unless you are aware of the way the assembler will treat the symbol in all parts of the code where it is used. |
| limit address | Sets the maximum code address to the value specified by address. If the generated code address goes beyond the limit an error will be raised. This can help ensure sections of your program remain within a certain region of memory and don't get too big to fit. The address is the code address, not the output address, and emulator memory beyond that point will be protected. |
| list | Enables output listing in the assembly output window. See nolist below for more information. |
| macro name [parameter{,parameter...}] | Defines a Macro with the given name taking the given optional list of parameters. A macro is a re-usable section of code that can be passed parameters. For more information see Assembler Macros. |
| mend | Marks the end of a macro definition. |
| nocode | Disables code generation. For all instructions and assembler directives which generate data, the output code is normally written to the current output (emulator memory or file). The nocode directive allows code output to be switched off, producing no output until the next code directive. The source is still assembled, and this can be useful for testing, or for including another file in order to determine its symbol values without generating code. |
| nolist | Disables output listing in the assembly output window. Large assembly language programs can contain thousands of lines each of which generate quite verbose output showing line numbers, symbol values, generated output bytes and the line of source code itself. For most larger programs, it is usually better to see only the important sections of code you are currently working on listed or important symbols, so most larger assembly programs have nolist near the start, and important sections enclosed in list and nolist directives. |
| org code_address[,output_address] | Sets the current assembly origin to code_address. The origin is the base address used to determine the value of labels, and code is normally written to memory starting at that address unless the output_address is specified, allowing the actual generated code to be stored in a different region of emulator memory. |
| pause | Currently not implemented. In Maxam the assembly is paused so you can read the output, but WinAPE has all the output in a scrolling window so you can go back at any time to read it. |
| print [string|value] | Outputs a string or evaluated
value to the assembly output window. When output is a string the syntax
has been extended from Maxam to allow other symbol values to be displayed in decimal
(using &) or hexadecimal (using $). eg. print "Start: $start,
Count: &count" with start = 500 and count = 10 would output
Start: 01F4, Count: 10 |
| read filename | Includes the file with the given filename in the assembly. The file may contain symbol definitions, macro definitions and/or assembly code. See Including other source files for more information. |
| rend | Marks the end of a repeat loop |
| repeat count | Assembles the following code up until a rend directive count times. repeat directives are similar to macros, and can contain local (@) labels. |
| relocate_end | Mark the end of a relocatable section of code. |
| relocate_start | Mark the start of a relocatable section of code. |
| relocate_table [byte|word] [base_address] | Generate a relocation table. By default a table of word sized offsets is generated, override this by specifying byte for small code sections. The base_address specifies the relative origin for the values in the table. |
| rmem size[,fill]{,size[,fill]...} | Equivalent to defs. |
| run address[,breakpoint] | The run directive allows the program to be executed immediately after successful assembly starting execution at the given address. An optional breakpoint can be set at address given by breakpoint. |
| save [direct] filename{,address,size...}[,exec_address] | Saves regions of emulator memory to a file with the given filename. The direct option allows data to be saved directly to a disc image. Each of the regions starting at address with the given size are appended to the file, then optionally the execution address is set to exec_address for files on disc images. |
| stop | Stops assembly immediately, producing an Assembly Stopped error. |
| str | The str directive allows a list of strings to be generated
with each character of the string except the last output as a single byte character and
the last character of each string output as its character byte value with bit 7 set. eg.
str "ABC", "def" will generate the bytes (hexadecimal)
41 42 C3 44 45 C6 |
| text value{,value...} | Equivalent to defb. |
| title | Not currently implemented. Maxam used it to set the title for printed output. |
| word value{,value...} | Equivalent to defw. |
| wend | Marks the end of a while loop |
| while condition | Assembles the following code (up until a wend directive while the condition evaluates to non-zero. while directives are similar to macros, and can contain local (@) labels. |
| write [direct] filename[,exec_address] | Direct generated code output to a file. For write direct the output is sent to a file on a disc image, and an optional execution address exec_address can be specified. For write without direct the output is sent to a file in the Windows file system. |
| write direct [lower_rom[, upper_rom[, ram_bank]]] | Allows direct output to emulator memory. The current emulator write memory is used by default but the optional parameters allow ROMs to be enabled or RAM banks to be selected. lower_rom should be -1 to disable or 0 to enable the Lower ROM, upper_rom should be -1 to disable, or an upper ROM number, and ram_bank can be an expansion bank number #C0 to #FF (or #8C0 to #EFF for Yarek 4MB style bank mapping). |
| write direct sectors sector_range | Allows the assembler to
write its output directly to a range of sectors on a disc image. The sector range is a
string and must be of the form [A:|B:]{ track[-last_track]:sector[-last_sector]...}
where track specifies a single track, or a range of tracks with last_track,
and sector specifies a single sector, or a range of sectors with
last_sector. Tracks are decimal and sectors are always hexadecimal. eg.
write direct sectors "10:c4-c9 11-20:c1-c9 21:c1-c3" could be used to
write the generated output to the sectors starting at track 10 sector C4 and ending at
track 21 sector C3. |
The WinAPE assembler contains a few reserved symbols and functions with special meanings. These can be used inside any expression, including defb and defw values. They are:
| checksum([start,count]) | Evaluate the sum of either generated bytes since the last checksum reset directive or of a region of emulator memory starting at address start for count bytes. |
| checksum(style[,poly,initial,reverse][,start,count]) |
Evaluate a sum or Cyclic Redundancy Check (CRC) or either generated bytes since the last
checksum_reset directive or a region of emulator memory starting at address
start for count bytes. The style parameter is a string specifying
one of the following defined CRC styles: crc-8, crc-8-ccitt, crc-8-darc,
crc-8-i-code, crc-8-itu, crc-8-maxim, crc-8-rohc, crc-8-wcdma, crc-8-custom, crc-16,
crc-16-buypass, crc-16-ccitt, crc-16-dds-110, crc-16-dect, crc-16-dnp, crc-16-en-13757,
crc-16-genibus, crc-16-maxim, crc-16-mcrf4xx, crc-16-riello, crc-16-t10-dif,
crc-16-teledisk, crc-16-usb, x-25, xmodem, modbus, kermit, crc-ccitt, crc-ccitt-false,
crc-aug-ccitt, crc-16-custom.The poly, initial and reverse parameters are only used with crc-8-custom or crc-16-custom and specify the polynomial,
initial value and reversal (reversed if not zero). |
| memory(address) | Reads a word value from emulator memory at the given address. The Lower ROM, Upper ROM and RAM Bank can be previously defined by a write direct directive. Be aware that if this location is inside the assembly output range its value may be determined by the assembly output itself on the last pass. |
| relocate_count | The number of entries in the relocation table. |
| relocate_size | The size of the relocation table, assuming the table is using word entries. |
The following code will write directly to the emulator memory, run when assembled and break when the instruction at the .break label is reached.
org #4000
write direct
run start, break
relocate_start ;Start relocatable code section
dw relocate_count ;Number of entries in the relocation table
relocate_table start ;Generate a relocation table relative to start
ld de,#40
;Emulator will start running from the ld hl,break instruction
.start
ld hl,break
;Emulator will stop at the following NOP instruction
.break
nop
relocate_end ;End of relocatable code section