Home

SB-Assembler
News
Download
Quick Start
Source Files
Running SBASM
Expressions
Labels
Directives
Macros
Error Messages
How To?
History
Known Bugs

Cross-Overlays

Labels are mainly used to hold numerical values. This comes in handy because we humans are better in remembering names than meaningless values. For this reason labels play a very important role in assemblers.

Labels can hold different types of values like constants, addresses, offsets, SFRs, bit patterns etc. The SB-Assembler only remembers the label's value, not what type of value it is holding. This means that you can use these values for any purpose without bothering about type conversion. This not only gives you as programmer more freedom, but it also gives you more responsibility.
The value is always stored as a 32 bit value regardless of the original data size. The actual size used while referencing the label depends of the operand type used.

Label declarations always start at column 0 of the program line. An optional colon may follow the label name. This colon is only accepted for compatibility reasons with other assemblers and serves no particular purpose. The label name should be followed by a white space, which is a space, a TAB or an EOL.

The label can get its value in several different ways:

• The .EQ directive (or = ) can be used to assign the value of an expression to the label. The expression must evaluate without errors or forward references to other labels.
• The .SE directive is used to assign a variable value to the label. The .SE directive works exactly the same as the .EQ directive. The only difference is that the value may be changed as often as you want if you declare the label using the .SE directive. Whereas the label's value is read only when it's declared with the .EQ directive.
• In all other declarations the current Program Counter value is stored as the label's value. That value becomes then read only and may not be changed anymore.

Labels may be declared only once. The value they get is fixed and may not be changed anymore. The only exception to this rule are labels that get their value from the .SE directive, their value is variable and may be changed as often as you like.
If the assembler tries to declare a label that already exists it checks if the value assigned to that label is the same as the first time. If it is the new declaration will be ignored. The SB-Assembler reports an "Extra definition" error if the new declaration value differs from the original one.

In a 2-pass assembler, like the SB-Assembler, labels can be used (referenced) before they are declared. The label values should all be resolved at the end of the 1st pass though. Their actual values are used in the 2nd pass. Using labels that are not declared yet is called forward referencing.
Forward referencing may sometimes result in unexpected behaviour. Some instructions or directives don't allow the use of forward referenced labels in their operands. E.g. forward referencing is not allowed while assigning a value to another label. Sometimes the addressing mode of an operand is variable, depending on the size of its value. The assembler can pick the most appropriate addressing mode if the value is known. With forward referencing the value is not known and the assembler must expect the worst case and use the longest addressing mode available.

Note: Most Crosses which support variable addressing modes allow you to force the use of the shortest addressing mode by preceding the expression by the < symbol.

Label names should not be the same as reserved names. To begin with there are no reserved names known to the SB-Assembler, so any names can be given to your labels.
But some Crosses do have reserved names! They usually are names of registers like A, R1, SP, IX etc. Even though you can use these names for your labels it is better to avoid doing so to prevent confusion. Unpredictable behaviour may be the result if you do use reserved names. Some Crosses may interpret the reserved names before your labels, others may interpret them the other way around. The assembler will not warn you if you use reserved names.
The best way to avoid using reserved names is making your label names longer than 2 characters because most of the reserved names are 1 or 2 characters long.

The SB-Assembler knows 3 types of labels:

• Global labels, which can be referenced from within the entire program.
• Local labels, which "live" from the previous Global label until the next Global label.
• Macro labels, which also "live" from the previous Global label until the next Global label.

Label names are case insensitive which means that there's no difference between upper and lower case characters. The label name may be of any length, up to 255 characters. But only the first 32 characters are actually remembered by the assembler. This means that the assembler will not notice differences in names beyond the 32nd character.

A Global label name starts with a character from A to Z and may contain any characters from A to Z, the digits 0 to 9, the underscore _ and a dot . for all subsequent characters. The SB-assembler stops parsing the label name if any other character is encountered. Some assemblers require a colon behind the label name when it is declared. With the SB-Assembler this colon is optional and serves no particular purpose.

Examples:

RESET
CharOut
KEY_IN
SAMPLE.LABEL

A Local label name starts with a dot and follows the same rules as Global labels for all subsequent characters. The character following the dot doesn't necessarily have to be a character from A to Z. The dot is also counted as character as it comes to name length.

Examples:

.1
.LOOP
.Again
.SKIP

A Macro label name starts with a colon, which is the only difference from Local label names when it comes to syntax.

Examples:

:3
:LOOP
:Again
:Skip

The Local labels are one of the most interesting features of the SB-Assembler. Strangely enough most assemblers must do without them.

Label names should be as descriptive as possible to keep the program readable for us humans. But inventing unique and meaningful names becomes more and more difficult when our program grows longer and longer. Especially if you have to use unique names for loops and skips throughout a long program too. In many assembly programs you see label names like LOOP217, SKIP_XXX, or even more meaningful names like XXXX and X127.
Local labels take away a large burden from the programmer for they can be re-used again and again. E.g. you can use the Local label .LOOP as often as you want.
Every time you define a new Global label, all previous Local labels are discarded, so you can start with a clean slate.

DELAY100   MOV   R1,#100
.LOOP      DEC   R1
           JNZ   .LOOP
           RET

; The next line makes the SB-Assembler forget all Local labels
		   
DELAY10    MOV   R1,#10
.LOOP	   DEC   R1
           JNZ   .LOOP
           RET

As you can see the Local label .LOOP is declared twice. This is perfectly legal because the first instance only "lives" from DELAY100 until but not including DELAY10. The first JNZ instruction jumps back to the first instance of the Local label .LOOP. The second JNZ jumps back to the second Local label .LOOP because the first one is not accessible anymore.

Local labels may not be used until at least one Global label is declared, otherwise the SB-Assembler will report a "Missing global label error".

Macro labels are very similar like local labels, in fact outside Macros they work exactly the same. However there is a small but significant difference in operation within Macro expansions.

What is the problem with normal Global and Local labels within a Macro? Suppose I declare a normal Global label within a Macro. Then I could use (expand) this Macro only once because the Global label would be declared again if I want to expand the Macro for a second time. But the label will probably will get a different value the second time. This is not acceptable and we have to think of another way of handling this.
Local labels give a slight improvement because we can re-use them every time a Global label is declared. But what if we want to expand the Macro twice or more without declaring new Global labels in between?
That's where Macro labels come in. Every time a Macro is expanded it is automatically assigned a new Macro number internally. It's this Macro number that is added to the Macro label names to make them unique. Therefore Macro labels "live" only in the current expansion of the Macro. You can't reference Macro labels from outside its current expansion.
The Macro number is reset every time a new Global label is declared. Up to 254 different Macro numbers may be used before a new Global label must be declared to reset the Macro number again.

Macro labels may not be used until at least one Global label is declared, otherwise the SB-Assembler will report a "Missing global label error".

More detailed information about Macro labels can be found in the special chapter about Macros.