Labels included to your original source will help Disark to know if a “region” or “area” contains code, bytes, words, or pointers.
You can also specify more semantics, please check the examples below.
The labels are spotted by Disark via their inner tag. The tag can have a prefix, and must have a postfix:
MyCode_DisarkCodeRegionStart_Stuff DisarkCodeRegionStart1 DisarkCodeRegionEnd1
YeahDisarkCodeRegionStart ;No postfix!
One opened region must also have an end. They can overlap!
ld hl,0 MyGame_DisarkByteRegionStart_1 db ... MyGame_DisarkByteRegionEnd_1 ;Closing the Byte region "_1". MyGame_DisarkWordRegionStart_1 dw ... ;Error! MyGame_DisarkWordRegionStart_1 was not closed!
Disark tries to link pointers to the best/closest reference it knows. However, it only tries to match references that are +/- 10 bytes in vicinity, as it appears to be what is the most practical. If this behavior does not suit you, you can use the “force reference” labels below.
Labels understood by Disark
These are default and you shouldn’t really have to use them.
To be used for declaring bytes (DB 1, 2, 3, etc.).
Use this to declare words (DW 1, 2, 3, etc.). Reference will not be inferred for such regions. So they will not be modified in case of relocation.
Use these to declare an array of pointers. References will be found if possible.
When used, this will force a reference to be used. For example, if you want a Word or a Pointer to use a reference, you can use such labels. Even if a label is far away, it will be used because you forced a reference!
On the opposite, this forces the non-use of a reference. For example, your code is addressing an input/ouput port (out (#a0),a or ld bc,#7f00)). This must not be changed when the code is relocated! (for a simpler use, check the next labels).
Forces the referencing for an area composed of X bytes. X must be between 1 and 9, inclusive. Simpler than declaring an area like above! An example:
LABEL equ #1000 DisarkForceReferenceDuring3_Hello ;ld hl,xxxx takes 3 bytes. ld hl,LABEL + #3000
Normally, the LD instruction should not be referencing LABEL because too far from it. By forcing the reference, Disark will use the closed label, no matter how far it is.
On the opposite, this forces the non-use of a reference during X bytes (from 1 to 9 inclusive). Example:
org #7f00 START ld hl,#7f00 ;This is an IO port on CPC! We don't want it to be changed by relocation! out (c),c So... DisarkForceReferenceDuring3_1 ld hl,#7f00 ;Safe! Will not be using the START reference. out (c),c
Force reference for next word
The following Word will be using a reference, no matter how far it is. No need to declare a Word Region, which can be bothersome! Example:
org #1000 Label1 ld hl,0 ... ret DisarkWordForceReference_HiMum dw Label1 ;This declares a Word Region, using a reference.
Force-non-reference for next word
The following Word will not be using a reference. No need to declare a Word Region. Example:
org #1000 Label1 ld hl,0 ... ret DisarkWordForceNonReference_HiDad dw #7f00 ;This declares a Word Region, and it will never reference any label.
Some assemblers (to my knowledge, only SDCC) will require some labels to be marked in a special way for C code to be able to reach Z80 labels. This is doable with Disark! Duplicate your external label and mark it with a special tag:
MyLabelDisarkGenerateExternalLabel MyLabel ld hl,0 ...
All that is before the DisarkGenerateExternalLabel tag will be used to generate an external label.
If the SDCC profile is not used, only MyLabel is generated. If the SDCC profile is used, two labels are generated:
_MyLabel:: MyLabel ld hl,0 ...
For now, external labels are only used in the SDCC profile, and the prefix (“_”) and postfix (“::”) can not be modified. If this is needed, please contact me and I’ll generalize the concept.