The compiler understands several pragmas that — thought they are not Z80 instructions — they influence the emitted code. Each pragma has two alternative syntax, one with a dot prefix and another without it.
For example, you can write
.ORG to use the ORG pragma.
I prefer using the dot-prefixed versions of pragmas.
The ORG pragma
With the ORG pragma, you define where to place the compiled Z80 code when you run it. For example, the following line sets this location to the 0x6000 address:
If you do not use ORG, the default address is 0x8000.
You can apply multiple ORG pragmas in your source code. Each usage creates a new segment in the assembler output. Take a look at this code:
ld h,a .org #8100 ld d,a .org #8200 ld b,a
This code generates three output segment, each with one emitted byte that represents the
LD operation. The first segment will start at 0x8000 (default),
the second at 0x8100, whilst the third at 0x8200.
The XORG pragma
With the XORG pragma, you define the start address of a specific code section (the section started with the previous
.ORG) to use when exporting to Intel HEX format.
For example, the following line sets this location to the 0x0000 address; however, the code section starts at 0x6000.
.org #6000 .xorg #0
If you try to use multiple
.XORG within a code section, the assembler raises an error:
.org #6000 .xorg #0 ld a,b ; ... .xorg #1000 ; This line will casue an error message
The ENT pragma
The ENT pragma defines the entry code of the program when you run it from Visual Studio. If you do not apply ENT in your code, the entry point will be the first address of the very first output code segment. Here’s a sample:
.org #6200 ld hl,#4000 .ent $ jp #6100 .org #6100 call MyCode ...
.ent $ pragma will sign the address of the
jp #6100 isntruction as the entry
address of the code. Should you omit the ENT pragma from this code, the entry point would be
0x6200, for this is the start of the very first output segment, even though there is another
segment starting at 0x6100.
The XENT pragma
The IDE provides a command, Export Z80 Program, which allows you to create a LOAD block
that automatically starts the code. The Run Z80 Program and Debug Z80 Program command
simply jump to the address you specify with the ENT pragma. However, the auto LOAD block uses
RANDOMIZE USR address pattern where you need to define a different entry address that
can be closed with a
RET statement. The XENT pragma sets this address.
Here’s a sample:
start: .org #8000 .ent #8000 call SetBorder jp #12ac SetBorder: .xent $ ld a,4 out (#fe),a ret
The IDE will use #8000 — according to the
.ent #8000 pragma — when starting
the code with the Run Z80 Program. Nonetheless, the Export Z80 Program will offer #8006
— according to the
.xent $ pragma — as the startup code address.
The DISP pragma
The DISP pragma allows you to define a displacement for the code. The value affects the
$ token that represents the current assembly address. Your code is placed according
to the ORG of the particular output segment, but the assembly address is always displaced
with the value according to DISP. Take a look at this sample:
.org #6000 .disp #1000 ld hl,$
ld hl,$ instruction will be placed to the 0x6000 address, but it will be equivalent
ld hl,#7000 statement due to the
.disp #1000 displacement.
Of course, you can use negative displacement, too.
The BANK pragma
The ZX Spectrum 128K/2A/+2A/+3/+3E models handle 16K memory pages (banks) that can be paged into particular memory slots. (You can find more information about this here.)
The BANK pragma allows you to declare that you want to put the Z80 Assembly code in a specific memory bank. When you export the compiled output, the Export program function of SpectNetIDE creates a loader that reads the code and places it on the specified memory page.
The BANK pragma accepts two parameters. The first is the bank number (so it must be between 0 and 7). The second one is
an optional offset value (between 0 and 16383), which indicates the start offset within the bank. If you omit this, the default
value is zero. By default, the SpectNetIDE assembler assumes that the start address of the code in the bank is
you can specify any other value.
Note: You need to apply the
.model Spectrum128pragma at the top of your code so that you can use
Using BANK without an offset
Let’s assume you have this code:
.model Spectrum128 ; ... .bank 3 call yellow ret yellow: ld a,6 out (#fe),a ret
The compiler emits this code (and later, the loader takes care that it goes to bank #3):
0000: call #C004 ; yellow 0003: ret 0004: ld a,#06 ; this is yellow (#C004) 0006: out (#FE),a
The offset values at the beginning of the lines show the byte offset within the 16K memory bank.
Using BANK with an offset
Let’s modify the previous code adding an offset value:
.model Spectrum128 ; ... .bank 3, #100 call yellow ret yellow: ld a,6 out (#fe),a ret
Now, the compiler emits similar code, but its starts address is #C100 (#100 away from the default #C000):
0100: call #C104 ; yellow 0103: ret 0104: ld a,#06 ; this is yellow (#C104) 0106: out (#FE),a
Though it seems that we’re wasting the first 256 bytes of the page, the Export program command does not output those bytes. The loader knows that it should load the code from address #C100.
Using BANK with ORG
Though the default address to compile the code is #C000, you can change it. For example, Bank #2 is paged into the #8000-#BFFF memory range (slot 2), so it seems natural to use the #8000 address like this:
.model Spectrum128 ; ... .bank 2 .org #8000 call yellow ret yellow: ld a,6 out (#fe),a ret
As you expect, this is the output:
0000: call #8004 ; yellow 0003: ret 0004: ld a,#06 ; this is yellow (#8004) 0006: out (#FE),a
Using BANK with offset, and ORG
You can combine the offset of the bank with ORG:
.bank 2, #100 .org #8000 call yellow ret yellow: ld a,6 out (#fe),a ret
The output is probably different from the one you expect:
0100: call #8004 ; yellow 0103: ret 0104: ld a,#06 ; this is yellow (#8004) 0106: out (#FE),a
As you can see, the code stream is the same as in the previous case; however, here, the code starts at offset #100.
Using multiple BANK directives
As you may need multiple memory banks in your program, you can use multiple
BANK pragmas, like in this example:
.bank 1 ; Here goes the code for bank #1 ; ... .bank 3 ; Here goes the code for bank #3 ; ...
Restrictions with BANK
BANKcannot have a label.
BANKcannot be used with the ZX Spectrum 48 model type.
BANKvalue must be between 0 and 7
- The offset must be between 0 and 16383
- You can use the
BANKpragma for a particular bank page only once, so, for example, the following code raises an error message:
.bank 1 ; ... .bank 3 ; ... .bank 1 ; This line raises the error ; ...
Note: This is a temporary restriction. In the future, it may be removed.
The EQU pragma
The EQU pragma allows you assign a value to an identifier. The label before EQU is the name of the identifier (or symbol), the exression used in EQU is the value of the variable. This is a short sample:
.org #6200 ld hl,Sym1 Sym1: .equ #4000 ld bc,Sym2 Sym2: .equ $+4
This sample is equivalent with this one:
.org #6200 ld hl,#4000 ; Sym1 <-- #4000 ld bc,#620a ; Sym2 <-- #620a as an ld bc,NNNN operation and an ld hl,NNNN each takes 3 bytes
The VAR pragma
The VAR pragma works similarly to EQU. However, while EQU does not allow using the same symbol with mulitple value assignments, VAR assigns a new value to the symbol every time it is used.
The VAR pragma accepts extra syntax alternatives:
The INJECTOPT pragma
When you run the ZX Spectrum virtual machine from the IDE with the Run program command, it injects the machine code into the memory and sets up the system as if you started the code from BASIC with the RUN command. By default, it sets the cursor to “L” mode. However, in several cases, you’d like to keep the cursor in “K” mode, for example, when you intend to start the code with the RANDOMIZE USER addr command (here, addr is the entry address). In this case, you can add the INJECTOP pragma to the code:
The INJECTOPT pragma expects an identifier-like option tag after the starting pragma keyword, such as
cursork above. Omitting that tag will cause a syntax error.
Though right now INJECTOPT supports only the
cursorktag, it does not raise an exception with other tags, ignores them.
The DEFB pragma
The DEFB pragma emits 8-bit expressions (bytes) from the current assembly position. here is a sample:
.org #6000 .defb #01, #02, $, #04
The DEFB pragma will emit these four bytes starting at 0x6000: 0x01, 0x02, 0x03, 0x04.
$ expression will emit 0x03, because at the emission point the current assembly
address is 0x6003. The DEFB program takes into account only the rightmost 8 bits of any
expression: this is how
$ results in 0x03.
DEFB has extra syntax variants:
.DBare accepted, too.
The DEFW pragma
The DEFW pragma is similar to DEFB, but it emits 16-bit values with LSB, MSB order.
.defw #1234, #abcd
This simple code above will emit these four bytes: 0x34, 0x12, 0xcd, 0xab.
DEFW has extra syntax variants:
.DWare accepted, too.
The DEFM pragma
The DEFM pragma emits the byte-array representation of a string. Each character in the string is replaced with the correcponding byte. Take a look at this code:
.defm "\C by me"
Here, the DEFM pragma emits 7 bytes for the seven characters (the first escape sequence represents the copyrigh sign) : 0x7f, 0x20, 0x62, 0x69, 0x20, 0x6d, 0x65.
DEFM has extra syntax variants:
.DMare accepted, too.
The DEFN pragma
The DEFN pragma works just like the
DEFM pragma but it emits an additional
byte to terminate the string. Look at this code:
.defn "\C by me"
Here, the DEFN pragma emits 8 bytes for the seven characters (the first escape sequence represents the copyrigh sign) plus the terminating zero: 0x7f, 0x20, 0x62, 0x69, 0x20, 0x6d, 0x65, 0x00.
DEFN has extra syntax variants:
.DNare also accepted.
The DEFC pragma
The DEFC pragma works just like the
DEFM pragma but it sets Bit 7 of the last
emitted character. Look at this code:
.defc "\C by me"
Here, the DEFC pragma emits 7 bytes for the seven characters (the first escape sequence represents the copyrigh sign) with Bit 7 of the last character (0x65) set (so it become 0xE5): 0x7f, 0x20, 0x62, 0x69, 0x20, 0x6d, 0xE5.
DEFC has extra syntax variants:
.DCare also accepted.
The DEFH pragma
The DEFH pragma uses a string with even number of hexadecimal digits to emits a byte-array representation of the input. Each character pair in the string is replaced with the correcponding byte. Take a look at this code:
Here, the DEFH pragma emits 4 bytes: 0x12, 0xe4, 0xaf, 0xd2.
DEFH has extra aliases:
The DEFS pragma
You can emit zero (
0x00) bytes with this pragma. It accepts a single argument,
the number of zeros to emit. This code sends 16 zeros to the generated output:
DEFS has extra syntax variants:
.DSare also accepted.
The FILLB pragma
With FILLB, you can emit a particular count of a specific byte. The first argument
of the pragma sets the count, the second specifies the byte to emit. This code emits 24
The FILLW pragma
With FILLW, you can emit a particular count of a specific 16-bit word. The first argument
of the pragma sets the count, the second specifies the word to emit. This code emits 8
words (16 bytes) of
Of course, the bytes of a word are emitted in LSB/MSB order.
The SKIP pragma
The SKIP pragma — as its name suggests — skips the number of bytes as specified in its argument. It fills up the skipped bytes with 0xFF.
The EXTERN pragma
The EXTERN pragma is kept for future extension. The current compiler accepts it, but does not do any action when observing this pragma.
The MODEL pragma
This pragma is used when you run or debug your Z80 code within the emulator. With Spectrum 128K, Spectrum +3,
and Spectrum Next models, you can run the Z80 code in differend contexts. The MODEL pragma lets you
specify on which model you want to run the code. You can use the
NEXT identifiers to choose the model (identifiers are case-insensitive):
.model Spectrum48 .model Spectrum128 .model SpectrumP3 .model Next
For example, when you create code for Spectrum 128K, and add the
.model Spectrum48 pragma to the code,
the Run Z80 Code command will start the virtual machine, turns the machine into Spectrum 48K mode, and ignites
the code just after that.
Note: With the
#ifnmod directives, you can check the model type. For example, the following
Z80 code results green background on Spectrum 48K, cyan an Spectrum 128K:
.model Spectrum48 #ifmod Spectrum128 BorderColor: .equ 5 RetAddr: .equ #2604 #else BorderColor: .equ 4 RetAddr: .equ #12a2 #endif Start: .org #8000 ld a,BorderColor out (#fe),a jp RetAddr
The ALIGN pragma
This pragma allows you to align the current assembly counter to the specified byte boundary. You can use this pragma with an optional expression. Look at these samples:
.org #8000 nop .align 4 nop .align
The first pragma aligns the assembly counter to #8004, as this one is the next 4-byte boundary.
With no value specified,
.align uses #100, and thus the second
.align in the sample sets
the current assembly counter to the next page boundary, #8100.
The TRACE and TRACEHEX pragmas
These pragmas send trace information to the assembler output. In the Visual Studio IDE, these
messages are displayed in the Z80 Build Output window pane. You can list one or more expressions
separated by a comma after the
.trace token. TRACEHEX works just like TRACE, but id displays
integer numbers and strings in hexadecimal format.
Let’assume, you add these lines to the source code:
.trace "Hello, this is: ", 42 .tracehex "Hello, this is: ", 42
When you compile the source, the lines above display these messages:
TRACE: Hello, this is: 42 TRACE: 48656C6C6F2C20746869732069733A20002A
The RNDSEED pragma
rnd() function, you can generate random numbers. The RNDSEED pragma sets the seed
value to use for random number generation. If you use this pragma with an integer expression,
the seed is set to tha value of that expression. If you do not provide the expression, the compiler
uses the system clock to set up the seed.
.rndseed ; sets the seed according to the system clock .rndseed 123 ; sets the seed to 123
The DEFGX pragma
This pragma helps you define bitmaps in the code. This pragma excepts a string expression and utilizes that string as a pattern to generate bytes for the bitmap.
DEFGX has extra syntax variants:
.DGXare accepted, too.
If the very first character of the string pattern is
<, the pattern is left aligned,
and starts with the second character. Should the first character be
>, the pattern is
right aligned and starts with the second character. By default, (if no
> is used)
the pattern is left-aligned.
Any space within the pattern are ignored, taken into account as helpers. Other characters are converted into bits one-by-one.
Before the conversion, the pragma checks if the pattern constitutes multiples of 8 bits. If not, it uses zero bit prefixes (right-aligned), or zero-bit suffixes (left-aligned) so that the pattern would be adjusted to contain entire bytes.
- (dash), and
_ (underscore) sign 0, any other characters stand for 1.
Every 8 bits in the pattern emit a byte.
Here are a few samples:
.dg "....OOOO" ; #0F .dg ">....OOOO" ; #0F .dg "<----OOOO" ; #0F .dg "___OOOO" ; #1E .dg "....OOOO ..OO" ; #0F, #30 .dg ">....OO OO..OOOO" ; #03, #CF
The DEFG pragma
This pragma helps you define bitmaps in the code. This pragma excepts a string pattern (note: not a string expression!) and utilizes that string as a pattern to generate bytes for the bitmap.
DEFG has extra syntax variants:
.DGare also accepted.
Any space within the pattern are ignored, taken into account as helpers. Other characters are converted into bits one-by-one. The pixels in a byte are planted with the LHS as the most-significant bit, and multiple bytes are planted LHS byte first.
- (dash), and
_ (underscore) sign 0, any other characters stand for 1.
Every 8 bits in the pattern emit a byte.
Here are a few samples:
.dg ....OOOO ; #0F .dg ___OOOO ; #1E .dg ....OOOO ..OO" ; #0F, #30 .dg ....OO OO..OOOO ; #0F, #3C
Please note, unlinke in the pattern used with
DEFGX, here, the leading
<characters are taken as bit 1. They do not specify bit alignment.
The ERROR Pragma
You can raise custom error messages with this pragma. ERROR accepts an expression
and displays an error message with code
Z0500 using the text you provide. Here is a sample:
.error "The value must be greater than" + str(minvalue)
The INCLUDEBIN Pragma
You can include a binary file into the source code to emit all bytes just as if you used the
.defb pragma. You can include the entire file, or a single segment of it. The pragma has a
mandatory argument — the name of the binary file to include — and two optional
ones, the start offset of the segment, and its length, respectively. Let’s see a few examples:
.includebin "./myfile.bin" .includebin "./myfile.bin" 2 .includebin "./myfile.bin" 2, 3
This snippet loads the
myfile.bin file from the same directory that contains the source
Let’s assume that
myfile.bin contains these bytes:
#00, #01, #02, #03, #04, #05, #06, #07
The three lines of code above are the same as if we had written these code lines:
.defb #00, #01, #02, #03, #04, #05, #06, #07 ; .includebin "./myfile.bin" .defb #02, #03, #04, #05, #06, #07 ; .includebin "./myfile.bin" 2 .defb #02, #03, #04 ; .includebin "./myfile.bin" 2, 3
Of course, the compiler does not allow negative file offset or length. It alse raises an error if you define a segment that does not fit into the binary file.
You can use alternative syntax for
.includebin. The compiler accepts these tokens and their uppercase versions, too:
The COMPAREBIN pragma
When you are re-engineering a Z80 program from an exported disassembly, it is good to know that you do not break the original code. The
.comparebin pragma helps you to check that you still compile what you expect. It loads a binary file and compares that file with the output of the current code segment.
The pragma has a mandatory argument — the name of the binary file to include — and two optional ones, the start offset of the segment, and its length, respectively. Let’s see a few examples:
.comparebin "./myfile.bin" .comparebin "./myfile.bin" 2 .comparebin "./myfile.bin" 2, 3
Of course, the compiler does not allow negative file offset or length. It also raises an error if you define a segment that does not fit into the binary file.
You can use alternative syntax for
.comparebin. The compiler accepts these tokens, too:
When you compile the code, every
.org pragma opens a new segment that starts from the point defined by
You can put it into the code in as many places as you want. As the compiler parses the code, it records the positions of
.comparebin pragmas, the current output segment and its length at the point where
.comparebin is used. When the code compilation is ready — and there are no errors —, the compiler executes a check.
This check compares the emitted bytes with the recorded length to the bytes in the binary file.
- If the length of the segment is greater than the size of the file, the compiler raises an error.
- The comparison checks only the as many bytes as are in the output segment; if there are more bytes in the binary file, the remaining data is ignored.
- If the compared data do not match, the assembler raises an error with the first unmatching position.
Let’s assume, we have the
origin.bin file that contains these six bytes:
#00, #01, #02, #03, #04, #05
Take a look at this code:
.org #8000 .defb #00, #01, #02 .comparebin "origin.bin" .org #8100 .defb #03, #04, #05 .comparebin "origin.bin" .comparebin "origin.bin", 3
This code contains two segments (it has two
.org pragmas) and three
origin.binhas six bytes, the first comparison succeeds, as it utilizes only the three bytes emitted in the first segment.
- The second comparison fails, as the file starts with #00, #01, #02, while the segment emits #03, #04, and #05.
- The third comparison succeeds, as it starts the examination from the 4th byte (offset 3) of the binary file.