Assembler Directives

The integrated assembler in WinAPE is fully backwards compatible with Maxam 1.5, but provides some extensions to the syntax.

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.
brkGenerates 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.
closeCloses the output from a write or write direct directive.
codeEnables 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 valueEquivalent 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.
dumpNot currently implemented. Maxam used it to write symbol information.
dw value{,value...}Alternative short form of defw.
elseConditionally 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 condtionConditionally 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.
endMarks 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.
endifMarks the end of a conditional code section.
endmEquivalent to mend.
label equ valueDefines 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 condtionConditionally assembles the following section up until an else,elseif or endif if the given condition evaluates to a non-zero value.
ifdef symbolConditionally assemblers the following section up until an else,elseif or endif if the given symbol has already been defined.
ifndef symbolConditionally assemblers the following section up until an else,elseif or endif if the given symbol has not already been defined.
ifnot condtionConditionally 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 = valueThe 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 addressSets 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.
listEnables 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.
mendMarks the end of a macro definition.
nocodeDisables 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.
nolistDisables 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.
pauseCurrently 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 filenameIncludes 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.
rendMarks the end of a repeat loop
repeat countAssembles the following code up until a rend directive count times. repeat directives are similar to macros, and can contain local (@) labels.
relocate_endMark the end of a relocatable section of code.
relocate_startMark 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.
stopStops assembly immediately, producing an Assembly Stopped error.
strThe 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.
titleNot currently implemented. Maxam used it to set the title for printed output.
word value{,value...}Equivalent to defw.
wendMarks the end of a while loop
while conditionAssembles 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_rangeAllows 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_countThe number of entries in the relocation table.
relocate_sizeThe 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
ld hl,break

;Emulator will stop at the following NOP instruction
relocate_end          ;End of relocatable code section