ST9+ V6
Software Toolchain
—
V4 to V6 Migration Notes
Release 6.1
March 2001
Ref: DOC-ST9V6-MN
USE IN LIFE SUPPORT DEVICES OR SYSTEMS MUST BE EXPRESSLY AUTHORIZED.
STMicroelectronics PRODUCTS ARE NOT AUTHORIZED FOR USE AS CRITICAL COMPONENTS IN
LIFE SUPPORT DEVICES OR SYSTEMS WITHOUT THE EXPRESS WRITTEN APPROVAL OF
STMicroelectronics. As used herein:
1. Life support devices or systems are those
which (a) are intended for surgical implant into
the body, or (b) support or sustain life, and whose
failure to perform, when properly used in
accordance with instructions for use provided
with the product, can be reasonably expected to
result in significant injury to the user.
2. A critical component is any component of a life
support device or system whose failure to
perform can reasonably be expected to cause the
failure of the life support device or system, or to
affect its safety or effectiveness.
Table of Contents
Chapter 1:
1.1
1.2
1.3
Chapter 2:
2.1
2.2
2.3
2.4
2.5
Chapter 3:
3.1
3.2
3.3
Chapter 4:
4.1
4.2
4.3
Chapter 5:
5.1
5.2
5.3
5.4
Chapter 6:
6.1
Chapter 7:
7.1
7.2
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
About the ST9+ toolchain documentation set ............................................... 5
About this manual... ...................................................................................... 6
Legal ............................................................................................................. 6
C Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Interrupt servicing ......................................................................................... 7
Register file ................................................................................................... 7
Include files ................................................................................................... 9
asm statements ............................................................................................ 9
Page Pointer Register PPR ........................................................................ 11
tr9 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Symbols and expressions ........................................................................... 13
Pseudo-instructions .................................................................................... 15
Pseudo-macros ........................................................................................... 17
Assembly Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Interface between C and assembler code .................................................. 19
Comments .................................................................................................. 22
New assembler directives ........................................................................... 22
Linker Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Output sections ........................................................................................... 25
Input sections .............................................................................................. 25
Memory initialization ................................................................................... 26
Initial values ................................................................................................ 26
Startup Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Customizing crtbegin.spp ........................................................................... 29
Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Executables ................................................................................................ 31
Options ....................................................................................................... 31
3/39
Table of Contents
Appendix A: Migration Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Product Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Software Updates ..................................................................................................... 35
Contact list ................................................................................................................ 35
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4/39
ST9+ V4 to V6 Migration Notes
1
1 - Introduction
INTRODUCTION
Before using these notes the user must be familiar with the new features and
concepts of the ST9+ Software Toolchain V6. These features and concepts are not
explained in this document (see the ST9+ Software Toolchain V6 User Manual, the
ST9+ gcc9, Libraries & Startup Files Reference Manual and the ST9+ ELF, as9,
ld9 & Binutils Reference Manual for the relevant information).
Globally, the ST9+ Software Toolchain V6 is compatible at the source level with
the ST9+ Software Toolchain V4 with a few exceptions which are outlined in this
document. In particular, for an application completely written in the C language, the
changes necessary to migrate from V4 to V6 are very few and straightforward.
This document focuses on a straightforward migration of each individual input file,
this dictates the structure of the document such that each section is dedicated to
the necessary changes to be made to a particular file type in order to successfully
migrate from V4 to V6. These file types are organized in the following order:
•
C files.
•
tr9 files.
•
Assembly files.
•
Linker script file.
•
Startup files.
•
Makefile.
Where possible examples of code written for both the ST9+ Software Toolchain V4
and the ST9+ Software Toolchain V6 are given in order to highlight the differences
between the two toolchains.
To take full advantage of the new features of the ST9+ Software Toolchain V6,
more complicated architectural changes may be required (this is the case in
particular if the user wants to benefit from the new memory segmentation features
of the ST9+ Software Toolchain V6). Refer to the ST9+ Software Toolchain V6
User Manual for in-depth guidelines detailing how to design and develop
applications.
1.1
About the ST9+ toolchain documentation set
The ST9+ toolchain documentation set is comprised of the following:
•
ST9+ gcc9, Libraries & Startup Files Reference Manual.
•
ST9+ ELF, as9, ld9 & Binutils Reference Manual.
5/39
1 - Introduction
1.2
•
ST9+ User Manual.
•
ST9+ V4 to V6 Migration Notes.
•
ST9+ gmake Reference Manual.
•
STVD On-line Help.
ST9+ V4 to V6 Migration Notes
About this manual...
The following conventions are used in this manual:
Bold type: Used to emphasize new or special terminology, tool names and
product names.
Teletype: Used to distinguish command line examples, code fragments, and
program listings from normal text.
Blue italicized: Used to indicate a cross-reference—you can link directly to the
reference by clicking on it while viewing with Acrobat Reader.
Italic type: Used to indicate book titles.
Braces {}: Used to denote optional items in command syntax.
Brackets []: Used in command syntax to denote optional items on the command
line.
Ellipsis ...: In general terms, used to denote the continuation of a series. For
example, in syntax definitions denotes a list of one or more items.
l: In command syntax, separates two mutually exclusive alternatives.
1.3
Legal
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software
Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on all
copies.
Permission is granted to copy and distribute modified versions of this manual
under the conditions for verbatim copying, provided that the entire resulting derived
work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into
another language, under the above conditions for modified versions.
6/39
ST9+ V4 to V6 Migration Notes
2
2 - C Files
C FILES
Code written in ANSI C for the ST9+ Software Toolchain V4 is compatible with the
ST9+ Software Toolchain V6 with a few exceptions which are outlined below.
2.1
Interrupt servicing
The syntax of the pragma interrupt has changed slightly in the V6 compiler; the
new syntax is as follows:
#pragma INTERRUPT <function_name> [group_nb]
Example 1:
To declare my_function as an interrupt handler without group switching.
Code for ST9+ Software Toolchain V4:
#pragma interrupt (my_function)
Code for ST9+ Software Toolchain V6:
#pragma interrupt my_function
Example 2:
To declare my_function as an interrupt handler with automatic group switching.
Code for ST9+ Software Toolchain V4:
#pragma interrupt (my_function, 2)
Code for ST9+ Software Toolchain V6:
#pragma interrupt my_function 2
2.2
Register file
From the ST9+ Software Toolchain V4 to the ST9+ Software Toolchain V6 there
are two changes in the use of the register file:
2.2.1
•
The syntax used to specify that a variable in the register file has changed.
•
Registers are used to support floating point operations.
Syntax
The syntax to specify a variable in the register file has changed in the V6 compiler;
the new syntax is as follows:
#pragma REGISTER_FILE <variable_name> [register #]
When no register name is provided, automatic allocation of the variable in the
register file is performed by the linker.
This pragma should be followed by the usual C definition of the variable. In
particular, if the variable is considered as volatile by the compiler, the C definition
should contain the volatile qualifier. Also, this pragma should be repeated each
7/39
2 - C Files
ST9+ V4 to V6 Migration Notes
time the variable is made visible through an extern declaration. Thus, if it is not
already the case, it might be helpful to group all the register file pragmas and the
extern register declarations into a single .h file to be included where necessary.
Example 1:
To declare an automatically allocated variable in the register file.
Code for ST9+ Software Toolchain V4:
/* not really possible */
register int my_register1 (“RR68”);
Code for ST9+ Software Toolchain V6:
#pragma REGISTER_FILE my_register1
int my_register1;
Example 2:
To declare a manually allocated variable in the register file.
Code for ST9+ Software Toolchain V4:
register long my_register2 (“RR68”);
Code for ST9+ Software Toolchain V6:
#pragma REGISTER_FILE my_register2 68
long my_register2;
Example 3:
To declare a volatile and manually allocated variable in the register file.
Code for ST9+ Software Toolchain V4:
volatile register char my_register3 (“R68”);
Code for ST9+ Software Toolchain V6:
#pragma REGISTER_FILE my_register3 68
volatile char my_register3;
2.2.2
Register usage
With the ST9+ Software Toolchain V4, the stack was used to manage floating point
operations. With the ST9+ Software Toolchain V6, in the case of an application
using floating point operations, 16 direct register pairs must be reserved for these
operations. By default, the first 16 register pairs are used, but the user may select
any other set of 16 contiguous direct register pairs by using the V6 driver option mfp-on.
8/39
ST9+ V4 to V6 Migration Notes
2.3
2 - C Files
Include files
With the ST9+ Software Toolchain V6, the location and structure of the set of
include files has changed. Standard ANSI C include files are all available in a top
level include directory. Include files related to the whole family of ST9+
microcontrollers are in a first level of subdirectories called sys. Include files related
to a specific ST9+ microcontroller are in a second level of subdirectories (See the
libraries and startup files section of theST9+ gcc9, Libraries & Startup Files
Reference Manual for more information).
Only the top level directory is automatically searched by the preprocessor when an
include directive is encountered. Files located in any of the two levels of
subdirectories should be prefixed by the names of these subdirectories.
Alternatively, the -I option can be used in the makefile.
Example 1:
To include a string management header.
Code for ST9+ Software Toolchain V4:
#include <string.h>
Code for ST9+ Software Toolchain V6:
#include <string.h>
Example 2:
To include headers with system registers and I/O port registers definitions.
Code for ST9+ Software Toolchain V4:
#include <system.h>
#include <io_port.h>
Code for ST9+ Software Toolchain V6:
#include <sys/system.h>
#include <sys/io_port.h>
Example 3:
To include a header with ST90158 microcontroller register definitions.
Code for ST9+ Software Toolchain V4:
#include <st90158.h>
Code for ST9+ Software Toolchain V6:
#include <sys/st90158/st90158.h>
2.4
asm statements
Between the ST9+ Software Toolchain V4 and the ST9+ Software Toolchain V6
the following changes have occurred in the use of asm statements:
9/39
2 - C Files
2.4.1
ST9+ V4 to V6 Migration Notes
•
Some of the operator constraints, operator modifiers and operand extraction
codes have changed.
•
Changes in register usage may affect asm statements.
Syntax
The syntax of the asm statement remains unchanged, but due to major
enhancements inside the compiler some of the operator constraints, operator
modifiers and operand extraction codes have changed. The changes are as
follows:
2.4.1.1
Operator constraints
r : remains unchanged.
m : remains unchanged.
g : remains as g, but the ST9+ Software Toolchain V6 does not exclude RR
registers from this category.
R : becomes t (t specifies a register operand of the form R or RR).
a : becomes r or t.
S : means that the operand must be SSP or USP in the ST9+ Software Toolchain
V4. This constraint has been suppressed in the ST9+ Software Toolchain V6,
because its usage was too restricted.
i : remains unchanged.
2.4.1.2
Operator modifiers
= : remains unchanged.
2.4.1.3
Operator extraction codes
%L : becomes %b.
%H : becomes %B.
%Q : becomes %O.
%D : becomes %w.
%A : becomes %p.
%B : becomes %P.
Example 1:
To define a macro PUSHRR to push a direct register pair x.
10/39
ST9+ V4 to V6 Migration Notes
2 - C Files
Code for ST9+ Software Toolchain V4:
#define PUSHRR(x)
asm ("pushw %0" :: "R" (x) );
Code for ST9+ Software Toolchain V6:
#define PUSHRR(x)
asm ("pushw %0" :: "t" (x) );
Example 2:
To load the ST9 flags into an integer i.
Code for ST9+ Software Toolchain V4:
int i;
asm ( “xorw %0, %0\n\tld %L0, R231” : “=r” (i));
Code for ST9+ Software Toolchain V6:
int i;
asm ( “xorw %0, %0\n\tld %b0, R231” : “=r” (i));
It should be noted that the macro assembler tr9 is no longer supported with the
ST9+ Software Toolchain V6. Thus, all asm statements must be written in
assembly language. For further details about how to convert tr9 macro assembler
into assembly language, see Section 3: tr9 Files on page 13.
Note:
Moreover, due to major enhancements inside the compiler, potential problems may happen in
the case the asm statement contains part of the expression related to an operand. For
example the statement asm ("ld r0, #seg(%0)"::"m"(f)); where f is a function of the application
does not assemble with the V6 assembler as9. The correct V6 syntax is: asm ("ld r0,
#seg(%O1)"::"p"(f));.
2.4.2
Register usage
The other change which might affect asm statements is register usage. With the
ST9+ Software Toolchain V6, the scratch and callee saved registers and the
register used as the frame pointer have changed.
An asm statement which explicitly uses the working register pair rr14, a normal
working register for the V4 compiler, is very likely to destroy the current function
frame pointer for the V6 compiler. For more details, refer to Section 4: Assembly
Files on page 19.
2.5
Page Pointer Register PPR
With the ST9+ Software Toolchain V6, by default the C compiler, in order to
facilitate the writing of interrupt handler routines, saves / restores the PPR register
in the prologue / epilogue of the interrupt handler routine.
11/39
2 - C Files
ST9+ V4 to V6 Migration Notes
A command line option -mno-save-restore-ppr-in-it disables this save /
restore feature.
12/39
ST9+ V4 to V6 Migration Notes
3
3 - tr9 Files
TR9 FILES
Given the major enhancements of the V6 assembler, the tr9 macro-processor has
been suppressed in the ST9+ Software Toolchain V6. Most features previously
provided by tr9 are now available in the V6 assembler.
This section outlines the features of the V6 preprocessor and assembler that can
be used to translate the different tr9 macro processor features. These features can
be divided into three main groups:
3.1
•
Symbols and expressions.
•
Pseudo-instructions.
•
Pseudo-macros.
Symbols and expressions
Symbols and expressions can be further broken down into the following
subgroups:
•
Symbols.
•
Register symbols.
•
Service symbols.
•
Numbers.
•
Unary and binary operators.
•
Assignment operators.
How the ST9+ Software Toolchain V6 handles these tr9 macro processor features
is described below.
3.1.1
Symbols
The V6 assembler supports tr9 symbol syntax with the restriction that a symbol
cannot start with a digit.
3.1.2
Register symbols
The V6 assembler uses the same convention as tr9 to specify the 16 working
group registers and the 256 direct registers of the ST9+ microcontroller.
The V6 assembler does support specification of registers using expressions, but
the syntax is slightly modified, the leading # sign has been suppressed.
Code for ST9+ Software Toolchain V4:
inc r#3+3
13/39
3 - tr9 Files
ST9+ V4 to V6 Migration Notes
Code for ST9+ Software Toolchain V6:
inc r3+3
3.1.3
Service symbols
The V6 assembler supports tr9 service symbols of the form N$ (where N is a
number).
3.1.4
Numbers
The V6 assembler supports only prefix notations whereas tr9 allows both prefix
and postfix notations to specify the base of a number.
3.1.5
Unary and binary operators
The V6 assembler supports the following tr9 unary operators: - and ~.
The V6 assembler supports the following tr9 binary operators: +, -, *, /, &, | and ^.
In V6 the tr9 shift left operator -> is replaced with >> and the tr9 shift right operator
<- is replaced with <<.
3.1.6
Assignment operators
Table 1 shows the mapping between tr9 assignment operators and V6 assembler
assignment operators/directives.
tr9
V6 Assembler
=
=, .set or .equ
==
=, .set or .equ and .global
:=
.equiv
:==
.equiv and .global
Table 1: Assignment operators/directives mapping
14/39
ST9+ V4 to V6 Migration Notes
3.2
3 - tr9 Files
Pseudo-instructions
Table 2 shows how tr9 pseudo-instructions can be replaced by V6 assembler
directives:
tr9 Pseudo-instructions
V6 Assembler Directives
.ascii
.ascii
.asciz
.asciz
.blkb x
.fill x, 1, 0xff
.blkbw x
.fill x, 2, 0xffff
.bss
.lcomm symbol, length (for each symbol)
.byte
.byte
.data
.section .data
.defstr
#define (external preprocessor—see ST9+ V6 Software
Toolchain—ELF, as9, ld9 and Binutils Reference Manual,
Section 3.3.2).
.error str
.err
.extern
.extern
.far
.desc symbol, far
.fillto loc, pat1, pat2...
.org loc, pat1 (only 1 byte value)
.global
.global, .globl
.include
.include
.interrupt
.desc symbol, interrupt
.library
.include
.mcall
No longer necessary.
.list
.list
.nlist
.nolist
Table 2: tr9 pseudo-instructions to V6 assembler directives mapping
15/39
3 - tr9 Files
ST9+ V4 to V6 Migration Notes
tr9 Pseudo-instructions
V6 Assembler Directives
.ifc eq expr .endc
.ifeq expr .endif
.ifc ne expr .endc
.ifne expr (or .if expr) .endif
.ifc gt expr .endc
.ifgt expr .endif
.ifc lt expr .endc
.iflt expr .endif
.ifc le expr .endc
.ifle expr .endif
.ifc ge expr .endc
.ifge expr .endif
.ifc df symbol .endc
.ifdef symbol .endif
.ifc ndf symbol .endc
.ifndef symbol .endif
b
nb
These instructions have been replaced by the more flexible
possibility of defining default arguments to macros.
.macro
.macro
.endm
.endm
.mexit
.mexit
.org
.org
.mnarg
Can be replaced by an additional macro argument which
specifies the number of parameters used.
.page
.eject
.pl
.psize
.sbttl
.sbttl
.text
.section .text
.tittle
.tittle
.word
.word
.xfar
.desc symbol, far
Table 2: tr9 pseudo-instructions to V6 assembler directives mapping
16/39
ST9+ V4 to V6 Migration Notes
3.3
3 - tr9 Files
Pseudo-macros
The V6 assembler supports the following tr9 pseudo-macros:
•
jxcc.
•
djxnz.
•
dwjxnz.
The V6 assembler does not support any of the other pseudo-macros features
supported by tr9, they are as follows:
•
if... else, ifw... else.
•
while, whilew.
•
do, loop.
•
switch, break.
•
begin, proc, return.
•
Condition symbols (SETC, CLC, SETV, CLV, SETZ, CLZ, MINUS, PLUS).
•
Logical and relational operators (==, >, >=, <=, !=, >>, <<, <<=, >>=).
All of these features have a syntax very close to the C language, thus they should
be replaced by the appropriate C code and eventually associated to asm
statements if necessary.
17/39
3 - tr9 Files
18/39
ST9+ V4 to V6 Migration Notes
ST9+ V4 to V6 Migration Notes
4
4 - Assembly Files
ASSEMBLY FILES
Code written in assembly for the ST9+ Software Toolchain V4 is compatible with
the ST9+ Software Toolchain V6 with the following few exceptions:
•
Interface between C and assembler code.
•
Comments.
•
New assembler directives.
These differences are described below.
4.1
Interface between C and assembler code
This section concerns the interface between C and assembler code, notably
register usage and parameter passing.
4.1.1
Register usage
The major change concerns register usage. To summarize briefly:
4.1.2
•
The register used as frame pointer was rr12 for the V4 compiler; rr14 is used
for the V6 compiler.
•
rr0, rr2 and rr4 were the set of scratch registers used for the V4 compiler; rr0,
rr2, rr4 and rr6 are used for the V6 compiler.
•
rr6, rr8, rr10, rr12 and rr14 were the set of callee saved registers used for the
V4 compiler; rr8, rr10, rr12 and rr14 are used for the V6 compiler.
•
The V4 compiler used the stack exclusively for floating point operations, the V6
compiler uses a set of 16 contiguous direct register pairs first.
Parameter passing
These changes mainly impact function parameter passing and value returning.
Parameter passing:
•
If possible in terms of space, the V6 compiler uses rr4 and rr6 for parameter
passing instead of the stack as used for the V4 compiler.
•
If possible in terms of space, the V6 compiler uses a set of 16 contiguous
register pairs for floating point parameter passing instead of the stack as used
for the V4 compiler.
•
If possible in terms of space, the V6 compiler uses any register from the range
r0 to r7 for byte parameter passing, instead of only r1 and r3 as used for the V4
compiler.
19/39
4 - Assembly Files
ST9+ V4 to V6 Migration Notes
Value returning:
4.1.3
•
For a floating point return value, the V6 compiler uses a set of 4 or 8
contiguous register pairs, instead of the stack as used for the V4 compiler.
•
For composite type return values, the V6 compiler uses the stack at an address
pointed to by rr0, instead of rr4 as used for the V4 compiler.
Example: calling an assembler function from C code
An assembler function call from C code is usually done through an external C
declaration of the assembler function. Thus the call to the assembler function is
processed by the compiler like a standard C function call. In particular, the compiler
sets up the parameters to the called function and expects return values according
to the conventions detailed above.
Example 1:
/* c interface of assembly function asm_foo with five 2 byte
parameters*/
extern int asm_foo(int a, int b, int c, int d, int e);
Assembler code written for ST9+ Software Toolchain V4:
;;assembly code for asm_foo exploiting parameters set up by the C
compiler
asm_foo :
...
ldw rr8, rr0 ; load a into rr8
ldw rr8, rr2 ; load b into rr8
ldw rr8, 4(rr12) ; load c into rr8
ldw rr8, 6(rr12) ; load d into rr8
ldw rr8, 8(rr12) ; load e into rr8
...
Assembler code written for ST9+ Software Toolchain V6:
;;assembly code for asm_foo exploiting parameters set up by the C
compiler
asm_foo :
...
ldw rr8, rr0 ; load a into rr8
ldw rr8, rr2 ; load b into rr8
ldw rr8, rr4 ; load c into rr8
ldw rr8, rr6 ; load d into rr8
ldw rr8, 4(rr14) ; load e into rr8
...
Example 2:
/* c interface of assembly function asm_bar with five 1 byte
parameters*/
extern void asm_bar(char a, char b, char c, char d, char e);
20/39
ST9+ V4 to V6 Migration Notes
4 - Assembly Files
Assembler code written for ST9+ Software Toolchain V4:
asm_bar:
...
ld r5,r1; load
ld r5,r3; load
ld r5,4(rr12);
ld r5,5(rr12);
ld r5,6(rr12);
...
a into
b into
load c
load d
load e
r5
r5
into r5
into r5
into r5
Assembler code written for ST9+ Software Toolchain V6:
asm_bar:
...
ld
r5,r0;
ld
r5,r1;
ld
r5,r2;
ld
r5,r3;
ld
r5,r4;
...
4.1.4
load
load
load
load
load
a
b
c
d
e
into
into
into
into
into
r5
r5
r5
r5
r5
Example: calling a C function from assembler code
When calling a C function from assembler code, the assembler code has to
manually set up the parameters to the called function and to manually access the
return values according to the conventions detailed above.
Example:
/* c interface of c function c_foo with five 2 byte parameters */
extern int c_foo (int a, int b, int c, int d, int e);
Assembler code for ST9+ Software Toolchain V4:
;; assembly code setting up parameters for
...
pushw #5 ; set up immediate value 5
pushw #4 ; set up immediate value 4
pushw #3 ; set up immediate value 3
ldw rr2,#2 ; set up immediate value
ldw rr0,#1 ; set up immediate value
call c_foo
...
a C function c_foo
for parameter e
for parameter d
for parameter c
2 for parameter b
1 for parameter a
Assembler code for ST9+ Software Toolchain V6:
;; assembly code setting
...
pushw
#5 ; set
ldw
rr6,#4 ;
ldw
rr4,#3 ;
ldw
rr2,#2 ;
ldw
rr0,#1 ;
call
@c_foo
up parameters for a C function c_foo
up immediate value 5 for
set up immediate value 4
set up immediate value 3
set up immediate value 2
set up immediate value 1
parameter e
for parameter
for parameter
for parameter
for parameter
d
c
b
a
21/39
4 - Assembly Files
ST9+ V4 to V6 Migration Notes
...
It is worthwhile noting that the V6 compiler considers rr6 as a scratch register.
Thus the assembler code cannot assume that the value of this register remains
unchanged across the C function call. If this was the case, the assembler code
should save the register before the function call and restore it afterwards.
4.2
Comments
For the V4 assembler, the % character was used as the start of a comment. With
the V6 assembler, the % character is used to specify the modulo operation. Thus
the % character should systematically be replaced by the ; character.
Assembler code for ST9+ Software Toolchain V4:
;; anything following the % character is considered as a comment
ldw rr0, 64 % coucou
Assembler code for ST9+ Software Toolchain V6:
;; 64 % coucou would be considered as an expression
ldw rr0, 64 ; coucou
4.3
New assembler directives
The V6 compiler introduces a set of new directives as follows:
•
.assume
•
.proc and .endproc
•
.desc
Adding these new directives is not compulsory for the correct execution of the
code, but it avoids warning messages being displayed during the link stage and
enables additional functionalities during the debugging sessions.
4.3.1
.assume directive
The .assume directive is used to declare the programming model (i.e. the memory
model, the stack model and the floating point model) assumed to assemble the file.
Example:
;;The file is assembled assuming the compact programming model, with
the
;;floating point mode turned on and using the user stack to pass
;;parameters.
.assume compact, fp-on, parmusp
These flags are used by the linker to check whether the different files linked
together are coherent and to emit warnings in case of incoherencies.
22/39
ST9+ V4 to V6 Migration Notes
4.3.2
4 - Assembly Files
.proc and .endproc directives
The .proc directive is used to declare the beginning of a procedure or a function.
The .endproc directive is used to declare the end of this procedure or function.
Example:
.proc foo
foo:
...foo core...
.endproc
These directives are mandatory for debugging at the source level because the
debugger needs to know the procedure boundaries.
4.3.3
.desc directive
The .desc directive is used to set a symbol descriptor. In the case of migration
from the ST9+ Software Toolchain V4 to the ST9+ Software Toolchain V6, only the
near, far and interrupt descriptors are meaningful on a function symbol
Example:
.desc myfunc, near
.desc myfunc, interrupt
These directives are mandatory for debugging at the source level because it allows
the debugger to recognize the prologue and the epilogue of functions.
23/39
4 - Assembly Files
24/39
ST9+ V4 to V6 Migration Notes
ST9+ V4 to V6 Migration Notes
5
5 - Linker Script File
LINKER SCRIPT FILE
Due to the use of the ELF format in the ST9+ Software Toolchain V6, both object
files and executables can contain more sections than was possible with the ST9+
Software Toolchain V4. As a consequence, the .bk9 files are no longer used. In
addition the V6 linker offers new features such as the CREATE_SECINFO_TABLE
and the AT mechanism, which in the case of a number of sections provide
additional programming comfort. These changes mean that the linker script must
be modified when migrating from V4 to V6
The recommended method of migration is to start with the default linker script
provided by the ST9+ Software Toolchain V6 and adapt it to the context of the
application, rather than starting from an old linker script. This methodology in
particular helps the user to preserve the natural coherence between the linker
script and the startup files. This section outlines some important points to be taken
into account when performing this migration.
5.1
Output sections
The .bk9 files no longer exist with the ST9+ Software Toolchain V6. An unlimited
number of output sections can be created instead, using the section command.
It is recommended to create a separate output section for each contiguous
memory region of the ST9+ microcontroller.
Linker script for ST9+ Software Toolchain V4:
/* a .bk9 file is generated for each additional segment */
code0.bk9 : {
code0.o(.text)
}> CODE0_REGION
Linker script for ST9+ Software Toolchain V6:
/* a different output section is generated in the executable file for
each segment */
.code0 : {
code0.o(.text)
}> CODE0_REGION
5.2
Input sections
Apart from the sections which were already used by the V4 compiler, the V6
compiler also generates .secinfo, .contrib, .rodata, .reg8_data,
.reg16_data, .reg8_bss and .reg16_bss sections at the object file level.
These new input sections should be taken into account when writing the output
section descriptions.
25/39
5 - Linker Script File
Note:
ST9+ V4 to V6 Migration Notes
.rodata sections are generated only in the case of constant data. As the const qualifier did
not exist in the V4 toolchain, the V6 compiler will not generate a .rodata section unless the
const qualifier is explicitly added to the C code.
Linker script for ST9+ Software Toolchain V4:
/* constant data is mapped in .data section along with non constant
data */
Linker script for ST9+ Software Toolchain V6:
/* the .rodata section is used by the compiler */
.rodata
:
{ *(.rodata)
} > ROM
5.3
Memory initialization
The ST9+ Software Toolchain V6 introduces a fully automatic memory initialization
capability. Memory initialization is based on the content of a table called the section
information table (secinfo table) and is generated by the linker. This table informs
startup files what memory region must be initialized and how this region must be
initialized. The CREATE_SECINFO_TABLE keyword allows selection of the output
section where the secinfo table is put. The _has_secinfo_table symbol
specifies whether or not such a secinfo table has been generated. The
_secinfo_table symbol specifies the address of the beginning of the table.
Both symbols are used exclusively by the startup files.
Linker script for ST9+ Software Toolchain V4:
/* not possible */
Linker script for ST9+ Software Toolchain V6:
/* section ’.secinfo’ is a special linker section used to put
the secinfo table. */
.secinfo
:
{ CREATE_SECINFO_TABLE } > ROM
5.4
Initial values
The DO_OPTION_I command enables the V4 linker to know where to place the
initial values of the single data section of an executable. As the ST9+ Software
Toolchain V6 allows the creation of an unlimited number of data sections, this
command has been replaced by the more general AT keyword. The AT keyword
allows the Load Memory Address (LMA) to be set to a value different than the
Virtual Memory Address (VMA).
Linker script for ST9+ Software Toolchain V4:
/* the keyword DO_OPTION_I allows the V4 linker to know where to
place initial values of the ’.data’ section */
.text
:
26/39
ST9+ V4 to V6 Migration Notes
5 - Linker Script File
{ *(.text)
DO_OPTION_I } > ROM
.data
:
{ *(.data)
} > ROM
Linker script for ST9+ Software Toolchain V6
/* the keyword AT specifies that the initial values of the ’.data’
section will be loaded at the end of the “secinfo table”, but data in
it will be referenced at run time at the beginning of the RAM memory
region. */
.data
: AT(LOADADDR(.secinfo) + SIZEOF(.secinfo))
{ *(.data)
} > RAM
/* sections ’.reg16_data’ and ’.reg8_data’ are register file regions
that handle data. The keyword AT specifies that the initial values of
these sections will be loaded at the end of the initial values of the
’.data’ section, but will be referenced at the beginning of the
REGFILE_REGION at run time. */
.reg16_data : AT(LOADADDR(.data) + SIZEOF(.data))
{ *(.reg16_data) } > REGFILE_REGION
.reg8_data : AT(LOADADDR(.reg16_data) + SIZEOF(.reg16_data))
{ *(.reg8_data) } > REGFILE_REGION
Another alternative is to use the --auto-at option of the linker. This option avoids
the usage of the AT command in the linker script. Instead, the linker automatically
detects all of the different data sections of the application and inserts their initial
values at the end of the text section of the executable (see the linker section of the
ST9+ ELF, as9, ld9 & Binutils Reference Manual for more details about the
limitations of this option).
27/39
5 - Linker Script File
28/39
ST9+ V4 to V6 Migration Notes
ST9+ V4 to V6 Migration Notes
6
6 - Startup Files
STARTUP FILES
Due to major enhancements in startup files between the ST9+ Software Toolchain
V4 and the ST9+ Software Toolchain V6, it is highly recommended to start from the
startup files provided by the toolchain and to adapt them to the context of the
application, rather than starting from an old startup file. It is of course assumed that
the user has followed the same methodology for the linker script file (see Section 5:
Linker Script File on page 25) because of the strong dependencies between these
two files.
6.1
Customizing crtbegin.spp
It should be noted that the ST9+ Software Toolchain V6 provides two startup files,
crtbegin.spp and crtend.spp. Usually, only crtbegin.spp requires
customization, it is organized into eight parts as described below:
Part 1: macros definition
Defines and describes C preprocessor macros to be used later in the
implementation part of the startup.
Part 2: interrupt vector declaration
Defines the default interrupt vectors.
Part 3: default handlers definition
Defines the following default handlers:
Divide by zero trap.
Interrupt handler (just doing iret).
Part 4: system setup
Resets some registers to be up to date according to the programming model to be
used. This part does not include the MMU setup.
Part 5: memory/register file initialization
Initializes all memory and register file areas using the secinfo table mechanism
(see the Libraries and Startup Files section of the ST9+ gcc9, Libraries & Startup
Files Reference Manual for more details on this mechanism).
Part 6: MMU setup
Initializes DPRs and sets MMU registers according to the programming models
used.
29/39
6 - Startup Files
ST9+ V4 to V6 Migration Notes
Part 7: call main
Calls the main routine after having enabled interruption.
Part 8: termination
Terminates the program by looping indefinitely.
The usual areas of customization are parts 2 and 4:
Part 2 is the place where the interrupt vector table is defined though a series of
.word directives followed by the addresses of the interrupt handlers. This table
can be customized in a straightforward manner by adding any other interrupt
vector entry required by the application.
Part 4 is the place where all system registers are initialized. This part can be
customized in a straightforward manner by adding any other system register
initialization required by the application. When doing so, care should be taken to
stay compliant with the basic hardware assumptions of the chosen programming
model.
30/39
ST9+ V4 to V6 Migration Notes
7
7 - Makefile
MAKEFILE
The changes required by the makefile reflect both:
•
Modifications of the set of executables delivered.
•
Modifications of the options for these executables.
The basic dependencies mechanism remains unchanged, thus if macros have
been used, very few changes are required.
7.1
Executables
This section highlights the executable utilities that no longer exist in the ST9+
Software Toolchain V6, and where applicable the utilities that they have been
replaced by.
7.1.1
gecho and redir utilities
The major difference between the ST9+ Software Toolchain V6 and the ST9+
Software Toolchain V4 makefiles is that the gecho and redir utilities no longer
exist; in fact the 127 character length limit of the internal buffer used by the shell
has been removed, thus there is no longer a need to provide these utilities.
7.1.2
Intel9 utility
The Intel9 utility has been replaced by the more powerful objcopy9 utility (see the
objdump9 section of the ST9+ ELF, as9, ld9 & Binutils Reference Manual for more
details).
To generate an Intel 32 format file.
Makefile for ST9+ Software Toolchain V4:
intel9 -e ex1.u seg1.bk9 seg2.bk9 seg3.bk9 > ex1.hex
Makefile for ST9+ Software Toolchain V6:
# note that there are no longer bk9 files,
# everything is contained in the final executable
objcopy9 --input-target=st9-elf --output-target=ihex ex1.u ex1.hex
7.1.3
tr9 macro assembler
The tr9 macro assembler does not exist in the ST9+ Software Toolchain V6.
7.2
Options
This section highlights the options that do not exist in the ST9+ Software Toolchain
V6, and where applicable the options that they have been replaced by.
31/39
7 - Makefile
7.2.1
ST9+ V4 to V6 Migration Notes
Compiler options
It is worthwhile noting that the following compiler options do not exist in the ST9+
Software Toolchain V6:
•
miret, msrp, mgrpxx : the pragma INTERRUPT must be used instead.
•
mlink, mst9 : it is no longer possible to generate code for the old ST9
microcontroller. Thus the link instruction is automatically used.
•
mpd, samepd : it is no longer possible to generate code for different spaces.
•
mfar : this option has been replaced by the different memory models.
•
mregparm : this is the default, the -mnoregparm option no longer exists.
•
mtr9, -S9 : the macro assembler tr9 no longer exists.
•
nocrt9 : this option has been replaced by the -nostartfiles option.
It is also worthwhile noting that in the case of an application using floating point, the
-mfp-on option must be used.
7.2.2
Assembler options
It is worthwhile noting that the following assembler options do not exist in the ST9+
Software Toolchain V6:
7.2.3
•
-G : it is no longer possible to include symbols from a GDB file.
•
-g : this option no longer exists since the gnop pseudo-instruction no longer
exists.
Linker options
It is worthwhile noting that the following linker options do not exist in the ST9+
Software Toolchain V6:
32/39
•
-i : it is no longer possible to generate code for different spaces.
•
-I : this option has been replaced by the more powerful AT command in the
linker script, or alternatively by the --auto-at linker option; both of these
trigger the inclusion of the initial values in the final executable.
ST9+ V4 to V6 Migration Notes
Appendix A: Migration Summary
APPENDIX A:MIGRATION SUMMARY
A possible (but by no means unique) method of progressively eliminating all
incompatible points is to work through the different file types of the application as
listed in this document. Then, for each file type, it is recommended to progress
feature by feature. In most cases, basic search utilities can be used to find where
changes are required. The different points are independent, thus the order chosen
is not important.
Table 3 can be used as a general reminder of the different points to go through
during the migration. It also indicates if and where errors are generated if changes
have been forgotten.
Required Changes
C files
Generated Error
Comment
Interrupt Servicing
Compiler error
-
Register file
Compiler error
An error is generated only in the case
of a volatile register variable.
Include files
Preprocessor error
-
asm statement
Compiler or
assembler error
An error is generated only in the case
of operator constraints or extraction
codes that no longer exist. In a case
where the meaning has changed (%B
for instance), no error is generated.
Gmake error
-
Interface between C
and assembler code
No error generated
-
Comments
Assembler error
-
New assembler
directives
Linker warning
Not compulsory for correct code execution.
Startup file and linker script file
Linker warning or
error
-
Makefile
Executables
Gmake error
-
Options
Gmake and executable error
-
tr9 files
Assembler
files
Table 3: Suggested method of migration
33/39
Appendix A: Migration Summary
34/39
ST9+ V4 to V6 Migration Notes
ST9+ V4 to V6 Migration Notes
Product Support
PRODUCT SUPPORT
Software Updates
You can get software updates from the ST Internet web site:
http://mcu.st.com
For information on firmware and hardware revisions, call your distributor or ST
using the contact list given above.
If you experience any problems with a software tool, contact the distributor or ST
sales office nearest you.
Contact list
Note:
For American and Canadian customers seeking technical support the US/Canada is split
in 3 territories. According to your area, contact the following sales office and ask to be
transferred to an 8-bit microcontroller Field Applications Engineer (FAE).
Canada and East Coast
STMicroelectronics
Lexington Corporate Center
10 Maguire Road, Building 1, 3rd floor
Lexington, MA 02421
Phone: 781-402-2650
Mid West
STMicroelectronics
1300 East Woodfield Road, Suite 410
Schaumburg, IL 60173
Phone: 847-585-3000
West coast
STMicroelectronics, Inc.
28202 Cabot Road
Suite 650
Laguna Niguel, CA
Phone: (949) 347-0717
Europe
France (33-1) 47407575
Germany (49-89) 460060
U.K. (44-1628) 890800
35/39
Product Support
Asia/Pacific Region
Japan (81-3) 3280-4120
Hong-Kong (852) 2861 5700
Sydney (61-2) 9580 3811
Taipei (886-2) 2378-8088
36/39
ST9+ V4 to V6 Migration Notes
Index
Symbols
D
% character ....................................................... 22
.assume ............................................................ 22
.bk9 files ............................................................ 25
.desc ................................................................. 23
.endproc ............................................................ 23
.proc .................................................................. 23
_has_secinfo_table ........................................... 26
_secinfo_table ................................................... 26
Directives.......................................................... 22
.assume .................................................... 22
.desc ......................................................... 23
.endproc.................................................... 23
.proc.......................................................... 23
DO_OPTION_I ................................................. 26
A
Executable options ........................................... 31
Executables ...................................................... 31
Expressions ...................................................... 13
asm statements
operator constraints .................................. 10
operator extraction codes ......................... 10
operator modifiers ..................................... 10
register usage ........................................... 11
syntax........................................................ 10
Assembler code
interface with C code ................................ 19
Assembler directives ......................................... 22
Assembler options ............................................ 32
-G .............................................................. 32
-g............................................................... 32
Assembly files ................................................... 19
Assignment operators ....................................... 14
AT ..................................................................... 25
--auto-at ............................................................ 27
B
Binary operators................................................ 14
C
C code
interface with assembly code.................... 19
C files .................................................................. 7
Callee saved registers ...................................... 19
Comments......................................................... 22
Compiler options ............................................... 32
CREATE_SECINFO_TABLE ...................... 25, 26
crtbegin.spp ...................................................... 29
crtend.spp ......................................................... 29
E
F
Floating point operations .............................. 8, 19
Frame pointer register ...................................... 19
G
-G...................................................................... 32
-g ...................................................................... 32
Gecho ............................................................... 31
gnop.................................................................. 32
I
Include files
location ....................................................... 9
structure...................................................... 9
Intel9................................................................. 31
Interrupt servicing ............................................... 7
L
link instruction................................................... 32
Linker options ................................................... 32
Linker script file................................................. 25
Linker script files
input sections............................................ 25
memory initialisation ................................. 26
output sections ......................................... 25
LMA .................................................................. 26
Load memory address ...................................... 26
37/39
Index
M
Makefile......................................................... 9, 31
mfar ................................................................... 32
-mfp-on.......................................................... 8, 32
mgrpxx .............................................................. 32
miret .................................................................. 32
mlink.................................................................. 32
-mnoregparm .................................................... 32
mpd ................................................................... 32
mregparm.......................................................... 32
msrp .................................................................. 32
mst9 .................................................................. 32
mtr9 ................................................................... 32
Register file
syntax ......................................................... 7
use of.................................................... 7, 19
Register symbols .............................................. 13
Registers
asm statements ........................................ 11
S
nocrt9 ................................................................ 32
-nostartfiles ....................................................... 32
Numbers ........................................................... 14
-S9 .................................................................... 32
samepd ............................................................. 32
Scratch registers............................................... 19
section command ............................................. 25
Service symbols ............................................... 14
Startup files....................................................... 29
crtbegin.spp .............................................. 29
crtend.spp................................................. 29
support
contact numbers for.................................. 35
for development kit ................................... 35
Symbols............................................................ 13
O
T
N
objcopy9............................................................ 31
Operator constraints ......................................... 10
Operator extraction codes................................. 10
Operator modifiers ............................................ 10
P
Parameter passing ............................................ 19
Pseudo-instructions .......................................... 15
Pseudo-macros ................................................. 17
tr9
pseudo-instructions .................................. 15
pseudo-macros......................................... 17
tr9 files .............................................................. 13
TR9 macro-processor....................................... 13
U
Unary operators................................................ 14
V
R
redir ................................................................... 31
38/39
Virtual memory address.................................... 26
VMA .................................................................. 26
3
9
Information furnished is believed to be accurate and reliable. However, STMicroelectronics assumes no responsibility for the
consequences of use of such information nor for any infringement of patents or other rights of third parties which may result f rom its use.
No license is granted by implication or otherwise under any patent or patent rights of STMicroelectronics. Specifications mentioned in this
publication are subject to change without notice. This publication supersedes and replaces all information previously supplied.
STMicroelectronics products are not authorized for use as critical components in life support devices or systems without the express written
approval of STMicroelectronics.
The ST logo is a registered trademark of STMicroelectronics.
Intel® is a U.S. registered trademark of Intel Corporation.
Microsoft®,
Windows ® and Windows NT® are U.S. registered trademarks of Microsoft Corporation.
2001 STMicroelectronics - All Rights Reserved.
Purchase of I2C Components by STMicroelectronics conveys a license under the Philips I2C Patent. Rights to use these components in an
I2C system is granted provided that the system conforms to the I2C Standard Specification as defined by Philips.
STMicroelectronics Group of Companies
Australia - Brazil - China - Finland - France - Germany - Hong Kong - India - Italy - Japan - Malaysia - Malta - Morocco - Singapore - Spain
Sweden - Switzerland - United Kingdom - U.S.A.
http://www.st.com