Label semantics

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.

Label format

The labels are spotted by Disark via their inner tag. The tag can have a prefix, and must have a postfix:

Correct:

MyCode_DisarkCodeRegionStart_Stuff
DisarkCodeRegionStart1
DisarkCodeRegionEnd1

Incorrect:

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! 

References distance

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

Code region

...DisarkCodeRegionStart...
...DisarkCodeRegionEnd...

These are default and you shouldn’t really have to use them.

Byte region

...DisarkByteRegionStart...
...DisarkByteRegionEnd...

To be used for declaring bytes (DB 1, 2, 3, etc.).

Word region

...DisarkWordRegionStart...
...DisarkWordRegionEnd...

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.

Pointer region

...DisarkPointerRegionStart...
...DisarkPointerRegionEnd...

Use these to declare an array of pointers. References will be found if possible.

Force-reference area

...DisarkForceReferenceAreaStart...
...DisarkForceReferenceAreaEnd...

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!

Force-non-reference area

...DisarkForceNonReferenceAreaStart...
...DisarkForceNonReferenceAreaEnd...

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

Force-reference during…

...DisarkForceReferenceDuring<X>...

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.

Force-non-reference during…

...DisarkForceNonReferenceDuring<X>...

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...

DisarkForceNonReferenceDuring3_1 ld hl,#7f00   ;Safe! Will not be using the START reference.
     out (c),c

Force reference for next word

...DisarkWordForceReference...

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

...DisarkWordForceNonReference...

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.

External labels

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.