User manual

ManualsBrandsMotorola ManualsMarine RadioLD-W-1

November 2009 Doc ID 11392 Rev 4 1/89

UM0144

User Manual

ST Assembler-Linker

Introduction

This manual describes using the ST Assembler-Linker to develop applications for the ST7

and STM8 microcontrollers. The assembly tools described in this book form a development

system that assembles, links and formats your source code.

Purpose and scope

This manual provides information about producing an application executable for the ST7

and STM8 microcontrollers from your application source code in assembler language. It

includes:

● An overview of assembly language for the ST7 and STM8 microcontrollers

● Instructions for running the ST Assembler-Linker

● Descriptions of the assembler output

For information on related subjects refer to the following documentation:

● ST7xxxx Datasheet – full description of the ST7 xxxxmicrocontroller

● STM8xxxx Datasheet – full description of the STM8xxxx microcontroller

● ST7 Programming Manual – a complete reference to the ST7 assembly language

● STM8 Programming Manual – a complete reference to the STM8 assembly language

Figure 1. Schematic overview of the assembler toolset

LY N

Obsend

Source files

Objects (*.obj)

Listings (*.lsr) with relative addresses

*.cod

*.map

Listings (*.lst) with

Programmable binary

file (*.s19 or *.hex)

ABSLIST

ASM

Stored object

files (*.lib)

LIB

absolute addresses

www.st.com

Summary of content (89 pages)

PAGE 1
UM0144 User Manual ST Assembler-Linker Introduction This manual describes using the ST Assembler-Linker to develop applications for the ST7 and STM8 microcontrollers. The assembly tools described in this book form a development system that assembles, links and formats your source code. Purpose and scope This manual provides information about producing an application executable for the ST7 and STM8 microcontrollers from your application source code in assembler language.
PAGE 2
Contents ST Assembler-Linker Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.1 ST7 and STM8 incompatibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3 Host PC system requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.4 Getting assistance . .
PAGE 3
ST Assembler-Linker 4.4 4.5 5 Segmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.4.1 Segments explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.4.2 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 4.5.1 Defining macros . . . . . . .
PAGE 4
Contents ST Assembler-Linker 6.2.8 7 8 9 GP binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 ABSLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.2 Invoking the list file post processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 7.3 Limitations . . . .
PAGE 5
ST Assembler-Linker List of tables List of tables Table 1. Table 2. Table 3. Table 4. Table 5. Table 6. Table 7. Table 8. Table 9. Table 10. Table 11. Table 12. Table 13. Table 14. Table 15. Table 16. Table 17. Table 18. Table 19. Table 20. Table 21. Table 22. Table 23. Table 24. Table 25. Table 26. Table 27. Table 28. Table 29. Table 30. Table 31. Table 32. Table 33. Table 34. Table 35. Table 36. Table 37. Table 38. Table 39. Table 40. Table 41. Table 42. Table 43. Table 44. Table 45. Table 46. Table 47.
PAGE 6
List of tables Table 49. Table 50. Table 51. Table 52. Table 53. Table 54. Table 55. Table 56. Table 57. Table 58. Table 59. Table 60. Table 61. Table 62. Table 63. Table 64. Table 65. Table 66. Table 67. Table 68. Table 69. Table 70. Table 71. Table 72. Table 73. Table 74. Table 75. Table 76. Table 77. Table 78. Table 79. Table 80. Table 81. Table 82. Table 83. Table 84. 6/89 ST Assembler-Linker #INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 7
ST Assembler-Linker List of figures List of figures Figure 1. Figure 2. Figure 3. Schematic overview of the assembler toolset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Assembler source code format example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Error message format example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 8
Introduction ST Assembler-Linker 1 Introduction 1.1 ST7 and STM8 incompatibilities The new ST7/STM8 assembler development toolchain supports both the new STM8 core and the old ST7 core. By placing a trigger (st7/ or stm8/) in the first line of your code, you tell the assembler which set of rules to apply. The STM8 assembler is not compatible with the ST7 assembler. STM8 assembler (16-bit) features that are not compatible with the ST7 assembler (8-bit): 1.
PAGE 9
ST Assembler-Linker Introduction Generally, the instruction sets are similar, with the following notable differences: ● The STM8 instruction set supports several new addressing modes. – The Stack Pointer (SP) can be used as an index. – Long pointers have been added. – There is a new 3-byte addressing mode called extended.
PAGE 10
Introduction ST Assembler-Linker For assistance on all ST microcontroller subjects, or for help developing applications that use your microcontroller’s MSCI peripheral, refer to the contact list provided in Product Support. We’ll be glad to help you. 1.5 Conventions The following conventions are used in this document: ● Bold text highlights key terms and phrases, and is used when referring to names of dialog boxes and windows, as well as tabs and entry fields within windows or dialog boxes.
PAGE 11
ST Assembler-Linker 2 Getting started Getting started Installing the ST Assembler-Linker The ST Assembler-Linker is delivered as part of the STVD toolset. A free installation package is available at www.st.com. To install it: Note: ● either select ST7/STM8>ST toolset from the main menu of the Microcontroller Development Tools CD-ROM, ● or run the installation executable that you have downloaded from the internet. See the release notes for more guidance on installing the software components.
PAGE 12
ST7 and STM8 addressing modes ST Assembler-Linker 3 ST7 and STM8 addressing modes 3.1 Overview of ST7 and STM8 addressing modes The ST7/STM8 assembler instruction set incorporates the following addressing modes: Table 2.
PAGE 13
ST Assembler-Linker ST7 and STM8 addressing modes www.st.com. This chapter only gives a brief explanation of the main addressing mode types. 3.2 General instruction syntax The ST7 and STM8 instruction sets provide a single source-coding model regardless of which components are operands. ● ● For the ST7 the operands may be: – the accumulator (A), – an 8-bit index register (X or Y) – an 8-bit stack pointer (S) – the condition code register (CC), or a memory location.
PAGE 14
ST7 and STM8 addressing modes push memory ST Assembler-Linker addressing mode, while STM8 instruction accepts both modes ; STM8 accepts only long addressing mode, push memory does not exist for ST7 For ST7 instructions supporting both short and long formats, when external symbols are referenced, long mode is chosen by the assembler. For example: symb1 ...
PAGE 15
ST Assembler-Linker ST7 and STM8 addressing modes An indirect addressing mode means that the data byte(s) required to do the operation is found by its memory address which is located in memory (pointer). The pointer address follows the op-code. A short pointer is one byte long. A long pointer is two bytes long. This last group consists of memory indirect variants: ● Short pointer to short data, for ST7 only [shortpointer .b] ● Short pointer to long data [shortpointer .
PAGE 16
ST7 and STM8 addressing modes 3.7 ST Assembler-Linker Indexed modes The ST7 supports the following types of indexed mode: ● indexed without offset, ● indexed with an 8-bit unsigned offset (range [0:255]), ● indexed with a 16-bit offset. In addition to these modes, the STM8 also supports the following indexed mode: ● indexed with a 24-bit offset. The source code syntax is: ● (X) or (Y) for no-offset indexing. ● (offset,X) or (offset,Y) for indexed with offset.
PAGE 17
ST Assembler-Linker ST7 and STM8 addressing modes nop ld A,#lab12.h; load A with $00 ld A,#lab12.l; load A with $12 In the STM8, symbols .H and .L are not available.
PAGE 18
ST assembler ST Assembler-Linker 4 ST assembler 4.1 Overview The ST assembler program is a cross-assembler, meaning that it produces code for a target machine (an ST7 or STM8 microprocessor) which is different from the host machine. The assembler turns the source code files into re-locatable object modules ready for linking. During the process, it checks for many different types of errors. These errors are recorded in an ASCII file called cbe.err (Note that the linker also writes to this file).
PAGE 19
ST Assembler-Linker ST assembler For example: Figure 2. Assembler source code format example examp ld A,$ffff ; long addressing mode separator opcode comments operand label The next sections describe the main components of a source code file. 4.3.1 Label structure Labels must start in column one.
PAGE 20
ST assembler ST Assembler-Linker The suffix is not used when the label is referred to. Using of any suffixes other than .b, .w and .l results in an error upon assembly. For example: lab equ 0 ; word-size label (default) label1.b equ 5 ; byte-size label label2.l equ 123 ; long label segment byte at: 80 ‘ram’ bytes ; force the size of the label to bytes count ds.b ; byte-size label pointer ds.w ; byte-size label with a word-size ; space reserved at this address 4.3.
PAGE 21
ST Assembler-Linker 4.3.4 ST assembler Label scope Often, in multi-module programs, a piece of code needs to refer to a label that is actually defined in another module. To do this, the module that exports the label must declare it PUBLIC, and the module which imports the label must declare it EXTERN. The two directives EXTERN and PUBLIC go together as a pair.
PAGE 22
ST assembler 4.3.5 ST Assembler-Linker Opcodes The Opcode field may serve three different purposes. It may contain: ● The opcode mnemonic for an assembly instruction. ● The name of a directive. ● The name of a macro to be invoked. Opcodes must be separated from the preceding field (that is, label, if there is one) by a space or a tab. A comprehensive Opcode description can be found in the ST programming manual. Macros are discussed in Section 4.5 on page 30.
PAGE 23
ST Assembler-Linker Table 5. ST assembler Numeric constants and radix formats Format Hex Binary Octal Current PC Motorola $ABCD or &ABCD Intel 0ABCDh 100b 665o or 665q $ Texas >ABCD ?100 ~665 $ Zilog %ABCD %(2)100 %(8)665 $ %100 ~665 *(use MULT for MULTIPLY) String constants String constants are strings of ASCII characters surrounded by double quotes.
PAGE 24
ST assembler ST Assembler-Linker Table 6.
PAGE 25
ST Assembler-Linker Table 9. ST assembler Level 4 operators Operation Result, level #4 a-b a minus b a+b a plus b Operator names longer than one character must be followed by a space character. For example, '1 AND 2' is correct, '1AND2' is not. Place curly braces { } around arithmetic expressions. Always use curly braces at the top-level, when defining a numeric expression. Not doing so may produce unexpected results. Wrong syntax: #define SIZE 128 DS.
PAGE 26
ST assembler ST Assembler-Linker 4.4 Segmentation 4.4.1 Segments explained Segments are very important. You have to understand segments before you can use the assembler. Take the time to understand them now and you will save yourself a lot of puzzling later. Segmentation is a way of 'naming' areas of your code and making sure that the linker collates areas of the same name together in the same memory area, whatever the order of the segments in the object files.
PAGE 27
ST Assembler-Linker 4.4.2 ST assembler Parameters Possible arguments are: ● Name ● Align ● Combine ● cod parameter, output file control The following paragraphs describe each argument in detail, and the final paragraph describes Copying code. Name The argument is optional; it can contain a name of up to 12 characters. If it does, then all segments with the same name are grouped together within their class, in the order that new names are defined.
PAGE 28
ST assembler ST Assembler-Linker Combine The argument tells the assembler and linker how to treat the segment. There are three types to handle it: Table 11. Combine types Type Description at:X[-Y] Starts a new class from address X [to address Y] common All common segments that have the same class name will start at the same address. This address is determined by the linker. Follows on from end of last segment of this class.
PAGE 29
ST Assembler-Linker ST assembler cod parameter, output file control The last field of a SEGMENT directive controls where the linker places the code for a given class. When introducing a class, if this field is not specified, the code for this class is sent to the normal, default.COD file by the linker. If the [cod] file is given a number between 0 and 9 then all code generated under the class being introduced will be sent to a different '.COD' file by the linker.
PAGE 30
ST assembler 4.5 ST Assembler-Linker Macros Macros are assembly-time subroutines. When you call an execution-time subroutine you have to go through several time-consuming steps: loading registers with the arguments for the subroutine, having saved and emptied out the old contents of the registers if necessary, pushing registers used by the subroutine (with its attendant stack activity) and returning from the subroutine (more stack activity) then popping off preserved registers and continuing.
PAGE 31
ST Assembler-Linker ST assembler There is one further problem: because a macro may be called several times in the same module, any labels defined in the macro will be duplicated. The LOCAL directive gets around this problem: For example: getio MACRO LOCAL loop ld A,$C000 jra loop MEND loop This macro creates the code for a loop to await IO port at $C000 to go low.
PAGE 32
ST assembler 4.6 ST Assembler-Linker Conditional assembly #IF, #ELSE and #ENDIF directives Conditional assembly is used to choose to ignore or select whole areas of assembler code. This is useful for generating different versions of a program by setting a particular variable in an INCLUDE file that forces the use of certain pieces of code instead of others. There are three main directives used to perform conditional assembly, as shown in Table 13. Table 13.
PAGE 33
ST Assembler-Linker Table 14. ST assembler Other special #IF directives Directive Usage #IFB Checks for empty argument (that is, empty, or containing spaces / tabs), useful for testing macro parameter existence. #IFF (IF False) is similar to #IF, but checks the negation of the condition argument. #IFIDN Tests for string equality between two arguments separated by a space. This is useful for testing macro parameters against fixed strings. #IFLAB Checks if the argument is a predefined label. 4.
PAGE 34
ST assembler ST Assembler-Linker Table 15. Command line options Function Option -D <1> <2> #define <1> <2> (see page 36) -I Specify paths for included or loaded files (see page 36) -M Output make rule (see page 37) -PA Enable pass-1 listing (see page 37) -NP Disable phase errors (seepage 37) SYM option Description: Allows the generation of a symbol table. Format: ASM -sym Example: ASM prog -sym The output is the file prog.
PAGE 35
ST Assembler-Linker ST assembler FI option Note: Instead of using ASM -fi, it is advised to use the list file post processor ABSLIST which guarantees that the final list file is consistent with the executable code generated by the linker. Description: One side effect of using a linker is that all modules are assembled separately, leaving inter modules' cross-references to be fixed up by the linker.
PAGE 36
ST assembler ST Assembler-Linker D option Description: Allows to specify a string that is to be replaced by another during the assembly. A blank space or = is required between the string to be replaced and the replacement string. For example -D 2 is the same as -D =2. It is possible to specify only one argument (-D ). In which case, is replaced with 1.
PAGE 37
ST Assembler-Linker ST assembler M option Description: Tells the ST assembler to output a rule suitable for make, describing the dependencies to make an object file. For a given source file, the ST assembler outputs one make rule whose target is the object file name for that source file and whose dependencies are all the included (#include) source files and loaded (#load) binary files it uses. The rule is printed on the standard output.
PAGE 38
Linker ST Assembler-Linker 5 Linker 5.1 What the linker does After having separately assembled all the component modules in your program, the next step is to link them together into a .COD file which can then be sent on to its final destination using OBSEND. This linking process is not just as a simple concatenation of the object modules. It resolves all the external references. If a referenced label is not defined as PUBLIC, an error is detected.
PAGE 39
ST Assembler-Linker Linker Some examples: Linking together the modules game.obj, scores.obj, key.obj, game1.obj, game2.obj and game3.obj without using any libraries and generating a .COD file named game.cod, requires the following command line: LYN game+scores+keys+game1+game2+game3; Linking the same modules in the same environment, but generating a .cod file named prog.cod requires the following command line: LYN game+scores+keys+game1+game2+game3,prog; 5.3.
PAGE 40
Linker ST Assembler-Linker 5.4 Linking in detail 5.4.1 PUBLICs and EXTERNs All labels declared external in the modules being linked together must have a corresponding PUBLIC definition in another module. If it does not, it may be an error. Similarly, there must only be one PUBLIC definition of a given label. The bulk of the linker's job is filling those relative or external blanks left by the assembler in the .
PAGE 41
ST Assembler-Linker Linker For example: grafix cursor_buf segment byte at: 100-027F 'RAM1' ds.b 64 ; buffer for map under cursor segment byte at: 8000-BFFF 'ROM' show_page nop segment 'RAM1' field-buf ds.b {{256 mult 256}/8} segment 'ROM' dump_buf ld A,field_buffer grafix segment 'RAM1' cursor_temp ds.b 64 This complex sequence of segments shows now instances of the class RAM1 being used with a segment name of grafix.
PAGE 42
Linker ST Assembler-Linker 5.5 The linker in more detail 5.5.1 The composition of the .OBJ files The .OBJ files produced by the assembler contain an enormous amount of overhead, mostly as coded expressions describing exactly what needs to go into the 'blank spaces' the assembler has been so liberal with.
PAGE 43
ST Assembler-Linker Linker Class list: 0 ‘RAM0' byte from 0 to 78 (lim FF) 45% D 0 ‘RAM1' byte from 100 to 138 (lim 27F) 50% D 0 ‘eprom' byte from 8000 to 875B (lim BFFF) 21% C 0 ‘rom' byte from C000 to FFF9 (lim FFDF) C*Overrun* 0 ‘vectors' byte from FFEE to FFFF (lim FFFF) 100% D The external label list only includes labels that were declared PUBLIC: labels used internally to the module are not included.
PAGE 44
OBSEND ST Assembler-Linker 6 OBSEND 6.1 What OBSEND does for you After your program has been assembled and linked to form a .COD file it must be sent to the place where it will be executed. Right now, your code is just stored as a file on a disk where the target system cannot get at it. OBSEND is a general purpose utility for .COD files in various ways using various formats. 6.
PAGE 45
ST Assembler-Linker Table 16. OBSEND Output formats Output format 6.2.
PAGE 46
OBSEND ST Assembler-Linker The next two characters are the record type for this line: 00 is a data line, and 01 signals EOF. The following characters, until the last two, are the 16 data bytes for this line, the last two are a checksum for the line, calculated by starting with $00 subtracting the real value of all characters sent after the ':' until the checksum itself. 'Real value' means that for example, the two characters 3 and 0 should subtract $30 from the checksum, not 51 and 48.
PAGE 47
ST Assembler-Linker OBSEND S113001AFF120094FF130094D08AFF390094FF1250 S20801C004FFC0000073 = x The extended S-record format, selected by format x, sends code as described above, except that after the S9, it sends a list of SX records, one after the other, in the format: SX 0000 LABEL where 0000 are four ASCII zeroes, and LABEL is five ASCII characters. There are two spaces after the SX and one space after the 0000. 0000 represents the hexadecimal value of the label.
PAGE 48
ABSLIST ST Assembler-Linker 7 ABSLIST 7.1 Overview As the list file with absolute addresses generated by the assembler from the source file and the map file (ASM ex1.asm -fi=ex.map) may show differences with the actually generated code, a post processor has been written to be sure that the list file will be coherent with the executable file.
PAGE 49
ST Assembler-Linker 7.2 ABSLIST Invoking the list file post processor Here is the full command syntax of the list file post processor: abslist -o -exe .(s19|hex) -map .map ::= .lsr ::= .lst -o precedes the output list file. -exe precedes the executable file name. The executable format can be Motorola S-Record format or Intel Hex format.
PAGE 50
ABSLIST 7.3 50/89 ST Assembler-Linker Limitations 1. There is one main limitation. The update of the relative address is based on the search of the last declared segment. If the search cannot succeed because of the use of .NOLIST directives which hide segment declarations, the absolute file cannot be properly generated. There is the same problem with .XALL and .SALL for macro expansions. If a segment is declared in a macro, these directives should not be used.
PAGE 51
ST Assembler-Linker 8 Librarian 8.1 Overview Librarian If you do a lot of work on similar boards especially those with the same processor, it makes a great deal of sense to reuse lumps of code you have already written to do the same task in a different program. At the simplest level, you could just copy the source code as a block of text into the new program.
PAGE 52
Librarian ST Assembler-Linker Table 17. Library file options Operation 8.3 Description +filename Add/update object module to/in library -filename Delete object module from library !filename Update object module in library *filename Copy object module to separate file from library ? List contents of library x Exit to DOS Adding modules to a library Typing for example: +user1\board would look for a file, called user1\board.obj, and add it to the library.
PAGE 53
ST Assembler-Linker 8.5 Librarian Copying modules from a library To make a copy of a .OBJ module located in a library back to your hard disk, use, for example: *board This checks the existence of board.obj in the current library, if not it reports the failure and aborts the operation prompt. If it does find it, it invites you to give it the name of the hard disk file to create to contain the copy of the .OBJ module. Copy into .obj file [board.
PAGE 54
Definitions ST Assembler-Linker 9 Definitions Table 18. Acronyms and terms used in this document Name Definition Application board This is the printed circuit board onto which you wish to connect the target ST MCU. It should include a socket or footprint so that you can connect the application board to your emulator or development kit using the probe and the appropriate device adapter.
PAGE 55
ST Assembler-Linker Appendix A A.1 Assembler directives Assembler directives Introduction Each directive is described in a table. ● The name of the directive is given in the table title (and always appears in the Format). ● The Format shows the arguments allowed (if any) for this directive. ● The Description describes the action of the directive and the format and nature of the argument specified in the Format. ● The Example gives one or more example of the directive in use.
PAGE 56
Assembler directives A.2 ST Assembler-Linker Directives Table 20. .BELL Purpose Ring bell on console. Format .BELL This directive simply rings the bell at the console; it can be used to signal the end of Description pass-1 or pass-2 with #IF1 or #IF2. This directive does not generate assembly code or data. Example .BELL See also Table 21. BYTE Purpose Define byte in object code. Format BYTE ,[,...
PAGE 57
ST Assembler-Linker Table 23. Assembler directives CEQU Purpose Equate pre-existing label to expression. Format label Description This directive is similar to EQU, but allows to change the label's value. Used in macros and as counter for REPEAT / UNTIL. Example lab1 See also EQU, REPEAT, UNTIL Table 24. CEQU CEQU {lab1+1} ; inc lab1 .CTRL Purpose Send control codes to the printer. Format .CTRL [,]...
PAGE 58
Assembler directives Table 26. ST Assembler-Linker DC.B DC.B 1,2,3 ; generates 01,02,03 DC.B “HELLO” ; generates 48,45,4C,4C,4F DC.B “HELLO”,0 ; generates 48,45,4C,4C,4F,00 Example See also Table 27. DC.W Purpose Define word(s) in object code. Format DC.W[, ...] This directive forces the word(s) in its argument list into the object code at the current address. The arguments may be composed of complex expressions, which may even include external labels.
PAGE 59
ST Assembler-Linker Table 29. Assembler directives #DEFINE The benefits of using labels in assembler level programming are obvious and well known. Sometimes, though, values other than the straight numerics allowed in labels are used repeatedly in programs and are ideal candidates for special labelling. The #DEFINE directive allows you to define special labels called 'manifest constants'. These are basically labels that contain strings instead of numeric constants.
PAGE 60
Assembler directives Table 31. ST Assembler-Linker DS.W This directive is used to 'space out' label definitions. For example let's say we need a set of word-sized temporary storage locations to be defined in RAM, starting at address $4000. We could write: segment byte at 4000 'RAM' temp1 equ $4000 temp2 equ $4002 which would work fine, however, we recommend you to write: segment byte at 4000 'RAM' Description temp1 DS.W temp2 DS.W which does the same job.
PAGE 61
ST Assembler-Linker Table 33. Assembler directives END Purpose End of source code. Format END This directive marks the end of the assembly on the main source code file. If no END Description directive is supplied in a source-code file then an illegal EOF error will be generated by the assembler. Include files do not require an END directive. Example END See also Table 34. EQU Purpose Equate the label to expression.
PAGE 62
Assembler directives Table 36. ST Assembler-Linker #ELSE Purpose Conditional ELSE. Format #ELSE Forces execution of the statements until the next #ENDIF if the last #IF statement was found false or disables execution of the statements until the next #ENDIF if the last #IF Description statement was found true. The #ELSE is optional in #IF / #ENDIF structures. In case of nested #ELSE statements, a #ELSE refers to the last #IF. #IF {1 eq 0} ; ; block A ... not assembled Example #ELSE ; block B ...
PAGE 63
ST Assembler-Linker Table 39. Assembler directives FCS Purpose Form constant string. Format FCS <"string"> | [<“string”> |]... This directive works in the same way as the common STRING directive, except that Description the last character in any string argument has bit 7 (for example MSB) forced high. Numeric arguments in the same list are left untouched. FCS “ALLO” STRING “ALLO” Example See also Table 40. ; 41,4C,4C,CF ; 41,4C,4C,4F STRING .
PAGE 64
Assembler directives Table 42. ST Assembler-Linker #IF Sometimes it is necessary to have different versions of a program or macro. This can be achieved by completely SEPARATE programs / macros, but this solution has the associated problem that changes to any part of the program common to all the versions requires all of them being changed, which can be tedious.
PAGE 65
ST Assembler-Linker Table 45. Assembler directives #IFB Purpose Conditional on argument being blank. Format #IFB Description This directive works just like #IF except it doesn't evaluate its argument: it simply checks to see if it is empty or blank. Spaces count as blank. check Example See also Table 46. MACRO param1 #IFB param1 %OUT “No param1” #ELSE %OUT param1 #ENDIF MEND ... check , check 5 #IF2, #ELSE, #IF, #END #IFIDN Purpose Conditional on arguments being identical.
PAGE 66
Assembler directives Table 48. ST Assembler-Linker #IFLAB Purpose Conditional on argument being a label. Format #IFLAB Description This directive works just like #IF except it tests that its argument is a valid, predefined label. check Example See also Table 49. MACRO param1 #IFLAB param1 %OUT “LABEL” #ENDIF MEND #IF2, #ELSE, #IF, #END #INCLUDE Purpose Insert external source code file.
PAGE 67
ST Assembler-Linker Table 50. Assembler directives INTEL INTEL ld X,0FFFFh Example See also Table 51. MOTOROLA, TEXAS, ZILOG INTERRUPT Purpose Specifies to the debugger that a routine is an interrupt rather than a function. Format INTERRUPT Description This directive is used with interrupt handlers and so aids the debugger in correctly searching the stack for return address of the interrupted function.
PAGE 68
Assembler directives Table 54. ST Assembler-Linker #LOAD segment byte at 8000-C000 'EPROM1' #LOAD “table.bin” Example See also Table 55. LOCAL Purpose Define labels as local to macro. Format LOCAL A macro that generates loop code gives rise to an assembly problem since the loop label would be defined as many times as the macro is called. The LOCAL directive enables you to overcome this difficulty.
PAGE 69
ST Assembler-Linker Table 57. Assembler directives LONGS Purpose Default new label length long. Format LONGS When a label is defined, four SEPARATE attributes are defined with it: scope (internally or externally defined), value (actual numerical value of the label), relativity (absolute or relative), and lastly, length (BYTE, WORD or LONG).
PAGE 70
Assembler directives Table 59. ST Assembler-Linker MEND cmp16 Example trylow See also Table 60. MACRO first,second,result LOCAL trylow ld A,first add A,second cp A,#0 jreq trylow cpl A ld result,A MEND MACRO MOTOROLA Purpose Force Motorola-style radix specifier. Format MOTOROLA The Motorola style: $AB Hexadecimal ~17 Octal %100 Binary Description 17 Decimal (default) * Current program counter This directive forces the Motorola format to be required during the assembly.
PAGE 71
ST Assembler-Linker Table 62. Assembler directives .NOCHANGE Strings named in the first argument of a #DEFINE directive will be changed to the second argument of the #DEFINE: the default is that the changed strings will be listed. Description If you want the original source code to be listed instead, place a .NOCHANGE directive near the start of your source code. This directive does not generate assembly code or data. Example See also Table 63. .NOCHANGE #DEFINE .NOLIST Purpose Turn off listing.
PAGE 72
Assembler directives Table 66. ST Assembler-Linker PUBLIC This directive marks out given labels defined during an assembly as 'PUBLIC', accessible by other modules. This directive is related to EXTERN; if one module wants to use a label defined in another, then the other module must have that label Description declared PUBLIC. A label may also be declared PUBLIC as its definition by preceding the label name with a dot; it won't need to be declared in a PUBLIC directive then. Example module1.
PAGE 73
ST Assembler-Linker Table 69. Assembler directives SEGMENT Example byte no alignment; can start on any byte boundaries word aligned to next word boundaries if necessary, i.e., 8001=8002 para aligned to the next paragraph (=16 bytes) boundary, i.e., 8001=8010 64 aligned to the next 64-byte boundary, i.e., 8001=8040 128 aligned to the next 128-byte boundary, i.e., 8001=8080 page aligned to the next page (=256 bytes) boundary, i.e., 8001=8100 long aligned to the next long-word(=4 bytes) boundary, i.e.
PAGE 74
Assembler directives Table 72. ST Assembler-Linker STRING Purpose Define a byte-level string. Format STRING ,[,...] This directive forces the byte(s) in its argument list into the object code at the current address. The arguments may be composed of complex expressions, which may even include external labels. If the argument was an expression and had a value greater Description than 255 the lower 8 bits of the expression are used and no errors are generated.
PAGE 75
ST Assembler-Linker Table 75. Assembler directives TEXAS The Motorola style: >AB Hexadecimal ~17 Octal Binary Description ?100 17 Decimal (default) $ Current program counter This directive forces the Texas Instruments format to be required during the assembly. TEXAS ld X,>FFFF Example See also Table 76. INTEL, MOTOROLA, ZILOG TITLE Purpose Define main title for listing.
PAGE 76
Assembler directives Table 78. ST Assembler-Linker WORD This directive forces the word(s) in its argument list into the object code at the current address. The arguments may be composed of complex expressions that may even include external labels. If the argument was an expression and had a value greater Description than FFFF then the lower 16 bits of the expression are used and no errors are generated. WORD sends the words with the least significant byte first.
PAGE 77
ST Assembler-Linker Table 81. Assembler directives ZILOG The Motorola style: %AB Hexadecimal Octal %(8)17 Binary Description %(2)100 17 Decimal (default) $ Current program counter This directive forces the Zilog format to be required during the assembly.
PAGE 78
Error messages ST Assembler-Linker Appendix B B.1 Error messages Format of error messages There are two classes of error trapped by the assembler ● fatal ● recoverable A fatal error stops the assembly there and then, returning you to the caller (which may or may not be DOS; CBE can also invoke the assembler) with a message and error number describing the problem. The format of the error messages is as follows: file.asm(line): as : Error : '' Figure 3.
PAGE 79
ST Assembler-Linker B.3 Assembler errors Table 82. Assembler errors Error Error messages Definition 1 Empty file: The assembler could not read even the first line of the given source code file. 2 EOF while in Macro Definition: The file ended while a macro was being defined; you should end the last macro definition properly with a MEND statement. 3 Could not return to old place in source file 'X.asm': This error should never occur; it implies you have a disk fault of some kind.
PAGE 80
Error messages Table 82. ST Assembler-Linker Assembler errors (continued) Error Definition 26 Illegal external suffix: Only the suffixes .b, .B, .w, .W, .l, .L are legal after an external label in an external directive. If the suffix is left out then the default label size is used (as set by BYTES, WORDS or LONGS; default is WORDS). 27 Bad character in public line.
PAGE 81
ST Assembler-Linker Table 82. Error messages Assembler errors (continued) Error Definition 51 Phase inconsistency (P1=X,P2=Y) 'label': Reports that the named label was allocated different values from pass-1 and pass-2, implies awful things. It's generally caused when for some reason the assembler has generated different lengths for the same instruction between pass-1 and pass-2.
PAGE 82
Error messages Table 82. ST Assembler-Linker Assembler errors (continued) Error Definition 67 Improper characters: Unusual characters have been spotted in the source file, of value >127. 68 Label used before its EXTERN definition: Labels must be declared EXTERNAL before use, preferably in a group at the top of the file. 69 Ambiguous label name: The label name in the single-quotes at the end of the error-line can be confused with a register name in this instruction set. Change the name.
PAGE 83
ST Assembler-Linker Table 82. Error messages Assembler errors (continued) Error Definition 101 Label defined as NEAR and INTERRUPT 102 Label defined as FAR and INTERRUPT 103 Label defined as NEAR twice 104 Label defined as FAR twice 105 Label defined as INTERRUPT twice B.4 Linking errors Table 83. Linking errors Error Definition 1 File list must be supplied 2, 3, 11, 13 Incomplete object file. Fatal error - the linker has identified that the given object file has been truncated.
PAGE 84
Revision history ST Assembler-Linker Revision history Table 84. 84/89 Document revision history Date Revision Changes 01-Jul-2001 1 Initial release. 30-Jun-2005 2 Updated Introduction Updated Getting started installation procedure Added Revision history 05-June-2008 3 Reformatted document Added information on STM8 microcontroller support 20-Nov-2009 4 Added Chapter 7: ABSLIST Modified Figure 1, Section 1.2, Table 1, Table 15, and LI and FI options in Section 4.7.
PAGE 85
Index ST Assembler-Linker Index Symbols .asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 .cod . . . . . . . . . . . . . . . . . . . . . . . . 9, 29, 38, 44 .fin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 .lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 .map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 .obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9 .rsp . . . . . . . . . . . .
PAGE 86
ST Assembler-Linker Index %OUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 .CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 .FORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 .LALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 .LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 .NOCHANGE . . . . . . . . . . . . . . . . . . . . . 70-71 .NOLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 .PAGE . . . . . .
PAGE 87
Index ST Assembler-Linker no closing single quote . . . . . . . . . . . . . . . . .81 no info on start address of class ’class’ . . . . .83 no lvalue in expression . . . . . . . . . . . . . . . . .80 no more than 12 numerics allowed on one line . 81 no REPEAT for this UNTIL . . . . . . . . . . . . . .80 no string given on FCS line? . . . . . . . . . . . . .82 no string in Long . . . . . . . . . . . . . . . . . . . . . .80 no strings in DC.L . . . . . . . . . . . . . . . . . . . . .79 no strings in DC.W .
PAGE 88
ST Assembler-Linker Index f . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 i32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 ix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 x . . . . . . . . . . . . . . . . . . . . . . .
PAGE 89
ST Assembler-Linker Please Read Carefully: Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any time, without notice. All ST products are sold pursuant to ST’s terms and conditions of sale.