Raisonance versus

COSMIC
Porting STM8/ST7 applications
from Cosmic to
Raisonance tools
Application Note AN55

Document version
28 May 2013

AN55 porting Cosmic to Raisonance

Contents
1. INTRODUCTION................................................................................................................4
1.1 Purpose of this manual.................................................................................................................... 4
1.2 Scope of this manual....................................................................................................................... 4
1.3 Additional help or information.......................................................................................................... 4
1.4 Raisonance brand microcontroller application development tools....................................................4
1.5 Conventions used in this manual..................................................................................................... 5

2. STM8/ST7 APPLICATIONS..............................................................................................6

3. SUMMARY OF RAISONANCE-COSMIC DIFFERENCES...............................................7

3.1 Toolchain directives......................................................................................................................... 7
3.2 C language extensions summary..................................................................................................... 8

4. SEPARATING COSMIC AND RAISONANCE CODE.......................................................9

5. MEMORY MODELS.........................................................................................................10
5.1 Near/far functions call sequence (STM8).......................................................................................10
5.2 Qualifiers....................................................................................................................................... 10
5.3 Default memory spaces................................................................................................................. 11
5.4 Automatic variables relocation....................................................................................................... 11
5.5 Static local variables...................................................................................................................... 11
5.6 Pointer size control........................................................................................................................ 12
5.7 C libraries selection........................................................................................................................ 12
5.7.1 Floating-point libraries............................................................................................................. 12

6. MEMORY MAPPING.......................................................................................................13

-2-

AN55 porting Cosmic to Raisonance

6.1 Absolute variables.......................................................................................................................... 13
6.2 Constants in ROM......................................................................................................................... 13

7. IMPLEMENTATION DETAILS.........................................................................................14
7.1 Global variables initialization.......................................................................................................... 14
7.1.1 Uninitialized global variables................................................................................................... 14
7.2 main() arguments and return value................................................................................................14
7.3 Bit variables................................................................................................................................... 15

8. INTERRUPT HANDLERS................................................................................................16
8.1 Cosmic interrupts........................................................................................................................... 16
8.2 Raisonance interrupts.................................................................................................................... 17

9. INLINE ASSEMBLY AND C/ASSEMBLER INTERFACE................................................18

9.1 Rewriting inline assembler blocks in C........................................................................................... 18
9.2 Using intrinsic functions................................................................................................................. 18
9.3 Writing functions in separate assembler files.................................................................................20
9.4 Using inline assembler statements................................................................................................21
9.5 Function parameters passing......................................................................................................... 21

10. CONCLUSION...............................................................................................................22

11. ANNEX A: ST7-SPECIFIC DIRECTIVES AND OPTIONS............................................23

12. INDEX............................................................................................................................24

13. HISTORY.......................................................................................................................25

-3-

1. Introduction

AN55 porting Cosmic to Raisonance

1. Introduction
This document guides you through the migration of STM8/ST7 projects originally developed using the
Cosmic compiler chain that you want to port to the Raisonance development suite.
The Raisonance STM8/ST7 compiler chain uses semantics, directives and keywords that are strongly
influenced by the 8051 toolchain, and are very similar to the Keil compiler.
Differences between the project architectures for Cosmic and Raisonance STM8/ST7 compiler suites
will be explained, as well as directives and command-line options for the tools and the C syntax specific
to both toolchains.
Although your applications could be developed without any Integrated Development Environment (IDE)
using only C files and compiler command-line, we strongly recommend using an IDE such as Ride7,
which will take care about lots of various settings and options, which could be tedious to handle
manually.

1.1 Purpose of this manual

This manual explains how to port existing STM8/ST7 projects to the Raisonance development suite.

1.2 Scope of this manual

This document assumes that the user is familiar with the STM8/ST7 microcontroller families and that
Ride7 and its RKit-STM8 plug-in are already installed on your PC. If this is not the case, please
download a free evaluation version from the Raisonance web site.
Cosmic compiler version 4.2.8 and Raisonance toolchain RKit-STM8 version 2.16.0903 were used to
write this document. Later versions of the compiler toolchains may show some differences.

1.3 Additional help or information

If you want additional help or information, if you find any errors or omissions, or if you have suggestions
for improving this manual, go to the KEOLABS' site for Raisonance microcontroller development tools
www.raisonance.com, or contact the microcontroller support team.
Microcontroller website: www.raisonance.com
Support extranet site: support-raisonance.com (software updates, registration, bugs database, etc.)
Support Forum:
forum.raisonance.com/index.php
Support Email:
support@raisonance.com

1.4 Raisonance brand microcontroller application development tools

January 1, 2012, Raisonance became the brand under which the company KEOLABS sells its
microcontroller hardware and software application development tools.
All Raisonance branded products regardless of their date of purchase or distribution are licensed to
users, supported and maintained by KEOLABS in accordance with the companies' standard licensing
maintenance and support agreements for its microcontroller application development tools. For
information about these standard agreements, go to:
Support and Maintenance Agreement: http://www.raisonance.com/warranty.html
End User License Agreement:
http://www.raisonance.com/software-license.html

-4-

AN55 porting Cosmic to Raisonance

1. Introduction

1.5 Conventions used in this manual

File | New

Refers to the menu item New on the File menu.

(bold, monospaced type) User input
filename
Replace the italicized text with the item it represents
[]
Items inside [ and ] are optional.
[]
Represents a list of optional items that are the same as the preceding item.
while(1);
(monospaced type) Code, Directives and software generated output
01234H
A hexadecimal value (assembly format)
0x1234
A hexadecimal value (C language format)
The Ride installation directory will be referred as %ridedir% in this document.
For instance, if you installed Ride in the default C:\Program Files\Raisonance\Ride directory,
%ridedir%\lib will refer to the C:\Program Files\Raisonance\Ride\lib directory.
While(1);

-5-

2. STM8/ST7 applications

AN55 porting Cosmic to Raisonance

2. STM8/ST7 applications
The STM8/ST7 families of microcontrollers from STMicroelectronics, support applications developed
using the C language. Originally only the Cosmic C compiler toolchain was available for ST7.
Note: The Raisonance C compiler supports all ST7 and STM8 derivatives with a single product.
The Cosmic C compilers for STM8/ST7 are separate products, sold individually.
In the remainder of this document we explain porting differences from Cosmic compilers to the
Raisonance C compiler.
This document primarily focuses on STM8 projects, although ST7-specific details are available from
Annex A.

Users may find that older applications developed with the Cosmic compiler toolchain would benefit
from a port to the Raisonance Compiler toolchain. The C language is inherently portable hence the
Cosmic-Raisonance transition is easy. However, some parts of the 8-bit microcontrollers are handled
in a non-standard way and require some adaptation in user applications:

Code memory model. In applications that handle more than 64KB of memory, a specific model
must be handled that enables far functions call/ret sequences. Also the function local variables
memory placement.

Memory mapping. This describes the memory (RAM and ROM) placement of variables, stack,
peripherals, code, constants and reset vectors.

Peripherals and I/O access. Accessing peripherals from C is usually done using non-standard
extensions.

Global variables initialization. The C standard mandates that global variables should always be
initialized. However, in microcontroller code this constraint is usually lowered in order to favor a
smaller ROM footprint.

Interrupt handlers. Hardware interrupts serviced by C code require specific declarations.

Specific startup files. Some applications requirements such as early reset conditions handling or
clock control may require some specific code to be executed before the main() function is entered.

Inline assembly and C/assembler interface. In cases where inline assembly must be used within
the application, the C compiler specifics must be adapted to match user requirements.

-6-

AN55 porting Cosmic to Raisonance 3. Summary of Raisonance-Cosmic differences

3. Summary of Raisonance-Cosmic differences

3.1 Toolchain directives
Cosmic

Raisonance

STM8 memory models

Select the memory model in your linker options:

Select the compiler options that match your needs:

mods0

STM8(SMALL) DEFAULTGC(page0)

modsl0

STM8(SMALL) DEFAULTGC(data)

mods

STM8(LARGE) DEFAULTGC(page0)

modsl

STM8(LARGE) DEFAULTGC(data)
The linker automatically selects appropriate
libraries.

Automatic variables relocation

Manual location of variables is necessary.

Auto-relocation mode automatically locates the most

used variables in short range memory ([0x00-0xFF]
address range)

Global variables initialization

Select the appropriate startup file in your linker
script:
crtsi.s
crtsx.s
crtsif.s

Use the "NOINITSTATICVAR" compiler directive to

leave uninitialized global variables uninitialized, or
"INITSTATICVAR" if you want them to be initialized to
0.
The appropriate startup file is automatically selected
by the linker.

crtsxf.s

-7-

3. Summary of Raisonance-Cosmic differences AN55 porting Cosmic to Raisonance

3.2 C language extensions summary

Cosmic

Raisonance

Global variables
@0x80 char a;

at 0x80 char a;

// Absolute variable

@0x81:1 _Bool mybit;

at 0x81^1 bit mybit; // Absolute bit

@tiny int i = 3;

page0 int i = 3;

// zero-page location

@near unsigned u;

data unsigned u;

// zero-section

Absolute functions
Must be handled through a specific segment and a
linker script directive on the Cosmic toolchain.

at 0x8402 void absolutefct(unsigned u);

main() function
void main(void)
{
...
return;
// main() can return
}

void main(void)
{
...
while(1); // main() must not return
}

Interrupts and trap

@interrupt void irqhandler(void);

void irqhandler(void) interrupt 0;

A vector table C file is required.

A specific linker option must be provided to map
the vector table at the appropriate address.

All the vector mapping burden is automatically

handled by the linker.

Reentrant / recursive functions

@stack int fib(int I)
{
if(i < 2) return 1;
return fib(i-1) + fib(i-2);
}

int fib(int I) reentrant

{
if(i < 2) return 1;
return fib(i-1) + fib(i-2);
}

Useful for ST7 only: Raisonance compiler is always

reentrant in STM8 mode.
Constants in ROM
const unsigned lut[] = {0x1234, 0x5678};

code unsigned lut[] = {0x1234, 0x5678};

The "const" qualifier will not locate any variables in

ROM with the Raisonance compiler. The specific
"code" qualifier is required for that.
Inline assembly
Please refer to chapter 9. Inline assembly and C/assembler interface of this document for full details.

-8-

AN55 porting Cosmic to Raisonance

4. Separating Cosmic and Raisonance code

4. Separating Cosmic and Raisonance code

In the process of porting applications from Cosmic to Raisonance, you often need to "hide" some code
from the compilers.
The Raisonance compiler offers a facility that eases this: some predefined macros are automatically
generated by the Raisonance compiler:
Macro

Description

__RCSTM8__

Produces the (non-null) RCSTM8 version number.

__ROM_MODEL__

Produces the constant "0" for small ROM model (limited to 64kB), and "1" for
LARGE models. Note that LARGE model is available only for STM8.

__ST7__

Produces the constant "1" when compiling for ST7, and "0" when compiling for
STM8.

__STM8__

Produces the constant "0" when compiling for ST7, and "1" when compiling for
STM8.

These macros can be used to separate Cosmic Code from Raisonance code as follows:
#if defined(__RCSTM8__)
page0 char var = 2;

// Raisonance-specific code

#else
@tiny char var = 2;

// Cosmic-specific code

#endif

-9-

5. Memory models

AN55 porting Cosmic to Raisonance

5. Memory models
The memory model that applies to an application defines the type of call/ret sequence depending on
whether far calls (24-bit addressing) should be used or near calls (16-bit addressing). It also handles
the memory placement of local variables and function parameters.
Cosmic

Raisonance

Select the memory model in your linker options:

Select the compiler options that match your needs:

mods0

STM8(SMALL) DEFAULTGC(page0)

modsl0

STM8(SMALL) DEFAULTGC(data)

mods

STM8(LARGE) DEFAULTGC(page0)

modsl

STM8(LARGE) DEFAULTGC(data)
The linker automatically selects appropriate
libraries.

5.1 Near/far functions call sequence (STM8)

The STM8 supports ROM addresses higher than 64 KB. If your projects require a ROM than spans
above address 0xFFFF, the CALLF/RETF (far CALL/RET sequence) must be used.
On the Raisonance compiler, the STM8(LARGE) directive can be used to activate CALLF/RETF in your
applications. The STM8(SMALL) or just bare STM8 activates the standard CALL/RET sequence.

5.2 Qualifiers
Cosmic

Raisonance

@tiny int i = 3;

page0 int i = 3;

// zero-page location

@near unsigned u;

data unsigned u;

// zero-section

@far long l;

far data long l;

// 24-bit addressing

Memory (RAM or ROM) can be accessed by STM8/ST7 microcontrollers using different ranges:
1. 8-bit address ([0x00-0xFF] memory range) This is the most efficient way to store variables, as only 1
byte is necessary to address the variables, and pointers are only 1-byte. However, the memory range
is limited, as only 256 memory bytes are available.
Cosmic defines 8-bit memory as "short range", variables are located there by the "@tiny" qualifier.
Raisonance defines 8-bit memory as "page0 memory", variables are located there by the "page0"
qualifier.
2. 16-bit address ([0x0000-0xFFFF] memory range). This addresses 64 KB of memory.
Cosmic defines 16-bit memory as long range and variables are located there by the @near
qualifier.
Raisonance defines 16-bit memory as data memory and variables are located there by the data
qualifier.
3. 24-bit address (full memory range). This is used for addressing constants only, as the memory space
above address 0x10000 is for ROM only.
Cosmic locates variables or functions in 24-bit memory range using the @far qualifier.
Raisonance defines 24-bit memory as far memory and variables are located there using the far
qualifier.

- 10 -

AN55 porting Cosmic to Raisonance

5. Memory models

Note: The C language stores local variables and function parameters on the CPU stack. However,
8-bit microcontrollers have a constrained memory and the stack cannot be used extensively for
storage, so 8-bit C compilers can transparently store local variables and function parameters in RAM
(page0 or data) instead of stack.
The Cosmic C compiler documentation uses the stack denomination for the local variables storage
area (hence the stack short or stack large terms in the Cosmic documentation).
The Raisonance C compiler documentation uses the Default local class denomination for the local
variables storage area.
We refer to these storage areas as local variables storage. The function parameters are always
stored in the same area as the local variables, except when they can be held in CPU registers.

5.3 Default memory spaces

Cosmic toolchain defines memory models by mods0, modsl0, mods or modl compiler directives.
Raisonance toolchain sets the default memory space used for global variables to either zero page or
data using the DEFAULTGC compiler directive. Local variables are always stored on stack.

5.4 Automatic variables relocation

When using the Raisonance toolchain in auto-relocation mode, memory space mapping is automatic:
RCSTM8, in coordination with the RLSTM8 linker, allows automatic selection of the global variables
which should be assigned to the zero page segment, depending on their size and their usage count
within the whole application. The most used variables are relocated to zero page, producing the
smallest code.
To select the " Auto Relocation Mode":

Ensure your project is functional (compiles and links without error).

If you are using Ride7, select "Project | Properties, then select "Advanced STM8/ST7
options | Build development tools | Automatic variables relocation" and set it to active.
If you are using ST Visual Develop, right-click your project and select "Settings...". In the "C
Compiler" tab, select the "Optimizations" category, then activate the "Automatic variables
relocation" box.

Upon next build, a specific (and silent) compilation and link pass will be performed, that
produces the "best list" of variables to be relocated to the zero page.

The list of relocated variables will be passed to the compiler.

Subsequent builds of the project automatically relocate the variables according to the produced
Auto Relocation File.
Tip: Reduce your code footprint using auto-relocation mode
Auto-relocation mode is a project-wide optimization that reduces your code footprint. Make sure
you activate auto-relocation mode for your large projects to automatically benefit from this feature.

5.5 Static local variables

In both Raisonance and Cosmic toolchains, static local variables are treated as if they were actually
global variables, except that their scope is limited to the local block or function.
Consequently, the memory space applied to static local variables is the default global memory space
(unless explicitly specified otherwise).

- 11 -

5. Memory models

AN55 porting Cosmic to Raisonance

5.6 Pointer size control

The generic pointer size on the Raisonance compiler is 16-bit. It can address an object anywhere in the
[0x0000-0xFFFF] memory address range (section 0). However, if you handle objects that will always be
in zero page (in the [0x00-0xFF] memory address range), you can benefit from optimized code by
qualifying your pointers with the "page0" keyword, which makes them 8-bit.
If your project uses an STM8 device with ROM above the section 0, you can use the " far" pointer
qualifier. For example, as "ptab" in the example is 8-bit, the resulting code will be more optimized:
page0 char table[] = {0, 1, 1, 2, 3};

// This table is in zero page

char * page0 ptab;

// ptab is an 8-bit pointer

far * p24bits;

// 24-bit pointer. Can point anywhere

ptab = &table[2];

// Later in your code

It is also possible to specify more complex declarations, such as:

data char * page0 ptr8to16;

// 16-bit pointer itself located in zero page

Note: The pointer qualifiers "data", "far" and "page0" should be considered the same as standard
"volatile" or "const" qualifiers. Reading (or writing) complex variables declarations using such
qualifiers can therefore be done by applying standard procedures.

5.7 C libraries selection

The Cosmic toolchain requires a specific linker script, which contains the list of C libraries required by
the linker (to find the C library functions that fit the project). Using the Raisonance toolchain, the C
libraries are automatically linked in according to the project requirements (large/small model, float
library). It is therefore not necessary to worry about C libraries with the Raisonance toolchain.

5.7.1 Floating-point libraries

Raisonance offers 2 versions of the float libraries. The standard float library is fully checked and
handles all the IEEE-754 specific issues . The fast float library offers much faster operation (typically
40 to 70% speed improvement). However, it does not perform the same checks as the standard library:

Infinities are not handled. For instance, 1.0 / 0.0 returns 1.0 with the fast float library.

Overrun/underrun is not checked. For instance, 1e20 / 1e-20 leads to an result which is not
representable, and should be reported as INF. This is properly handled by the standard (checked)
float library, but gives an invalid result with fast float.

NaN are not handled in the fast float library.

IEEE rounding is NOT the same as the 8087 FPU, but is a truncate instead. This means that
transcendental operations +, -, * and / may report a slightly different result than standard float.

The "-0.0" value is not supported as input. Most noticeably, comparing 2 floats respectively holding
the 0.0 and -0.0 values will report the floats as being different.

X / 0.0 returns X, for any X value.

Arithmetic is performed on 24-bit mantissas (instead of 32-bits) for the standard float library. This
may in some cases lead to decreased accuracy (wrong mantissa's lsb).
In order to use the fast floating point libraries in your projects, the FASTLIBRARY directive should be
activated for the linker.
Please refer to the RCSTM8 compiler manual for details between the standard (checked) and fast float
libraries.

- 12 -

AN55 porting Cosmic to Raisonance

6. Memory mapping

6. Memory mapping
6.1 Absolute variables
Variables must sometimes be absolutely located at a specific RAM address. Cosmic tools do this
through the @address qualifier. For bit variables @address:bitnumber can specify the bit number to be
used at the given address. For example (Cosmic syntax):
char MISCR1 @0x20;
_Bool PB3 @0x01:3;

The Raisonance syntax resembles Cosmic. The at address qualifier can locate variables. For bit
variables the at address^bitnumber can specify the bit number to be used at the given address.
The example above can easily be translated to Raisonance code:
at 0x20 char MISCR1;

// The address qualifier is before the variable

at 0x01^3 bit PB3;

// "bit" type replaces Cosmic's "_Bool"

Note: Absolute functions: The Raisonance toolchain enables easy location of functions at given
addresses: Use the at address qualifier as if the function was an absolute variable, for example:
at 0x8402 void absolutefct(unsigned u);
The location in memory is then performed automatically by the linker, without having to specify any
specific linker directive or linker script file.

6.2 Constants in ROM

Some constants may be stored in ROM for best performance. For instance, lookup tables are
inherently constant:
// From SHA-1 algorithm
const long shsTestResults[][ 5 ] =

// This array will be mapped in RAM, not ROM!

{
{ 0x0164B8A9L, 0x14CD2A5EL, 0x74C4F7FFL, 0x082C4D97L, 0xF1EDF880L },
{ 0xD2516EE1L, 0xACFA5BAFL, 0x33DFC1C4L, 0x71E43844L, 0x9EF134C8L },
{ 0x3232AFFAL, 0x48628A26L, 0x653B5AAAL, 0x44541FD9L, 0x0D690603L }
};

When using the Cosmic toolchain, const global variables are always stored in ROM.
For the global variables to be stored in ROM using the Raisonance toolchain, simply place them in the
code memory space. So the example above must be written as follows on Raisonance:
// From SHA-1 algorithm
const code long shsTestResults[][ 5 ] =
{

...

// (rest of the example omitted)

Note: The fcode (far code) qualifier can also be used to locate variables in far code (above address
0xFFFF). This is especially useful if you have large data tables such as web pages or images.
Access to far code is less efficient (24-bit addresses must be handled instead of 16-bit), but some
STM8 derivatives will let you hold as much as 96KB of far code.

- 13 -

7. Implementation details

AN55 porting Cosmic to Raisonance

7. Implementation details
Some application requirements such as early reset conditions handling or clock control may require
some specific code to be executed before the main() function is entered.

7.1 Global variables initialization

The C standard mandates that global variables should always be initialized. However, in microcontroller
code this constraint is usually lowered in order to favor a smaller ROM footprint.
The Cosmic toolchain offers the crtsi.s, crtsx.s, crtsif.s and crtsxf.s startup codes.
The Raisonance toolchain automatically selects the most appropriate startup file from the C
libraries.
However, there are some applications that require full control over the startup procedure (for instance
on a SmartCard that must send an Answer-To-Reset within a fixed number of clock cycles).
In such cases, it is possible to use the %ridedir%\Inc\Sources\ST7-STM8\startup\startup.asm
template. This file contains full documentation about the startup process, and explains how the data
initialization routines should be called.
Cosmic

Raisonance

Select the appropriate startup file in your linker

script:

Use the "NOINITSTATICVAR" compiler directive to

leave uninitialized global variables uninitialized, or
"INITSTATICVAR" if you want them to be initialized to
0.

crtsi.s
crtsx.s
crtsif.s

The appropriate startup file is automatically selected

by the linker.

crtsxf.s

7.1.1 Uninitialized global variables

Global variables that are declared without initialization may be either left uninitialized (unknown value
upon application start) or 0-initialized (which eats up ROM space).
With the Raisonance compiler, the INITSTATICVAR directive assigns a 0 value to all uninitialized
globals. NOINITSTATICVAR (default) does not initialize them.
With the Cosmic compiler, the +nobss directive assigns a 0 value to all uninitialized globals. Such
variables are actually moved from the .bss to the .data section.
Note: Stack initialization: The stack is never initialized by the Raisonance startup file, as the stack
pointer is automatically set by the STM8/ST7 chips upon reset.

7.2 main() arguments and return value

The main() application entry function has the following prototype on freestanding C implementations:

- 14 -

AN55 porting Cosmic to Raisonance

7. Implementation details

void main(void);

Consequently, you cannot have the common argc and argv arguments.
One difference between Cosmic and Raisonance Compilers is that the main function must never return
on the Raisonance toolchain.

7.3 Bit variables

Raisonance uses the bit type name for bit variables.
Cosmic uses the _Bool type name for bit variables.
Both handle bit variables storage and usage in a similar way. The main difference between Cosmic and
Raisonance bits is that the Raisonance linker handles bits transparently: It is not necessary to create a
specific bit segment through the linker in any particular way (no linker scripts, no bit segment directive);
everything is taken care of automatically.

- 15 -

8. Interrupt handlers

AN55 porting Cosmic to Raisonance

8. Interrupt handlers
Hardware interrupts serviced by C code require specific declarations because they are not called
from another function but run asynchronously, they cannot take any arguments, and cannot return a
function return.
Interrupt handlers have a prototype such as:
void irqhandler(void);

8.1 Cosmic interrupts

On Cosmic applications, functions must be declared with the type qualifier
used as an interrupt.

@interrupt

in order to be

@interrupt void irqhandler(void);

An interrupt vector table must then be created that contains all the interrupt vectors (the example
assumes that our interrupt handler is for IRQ0 for STM8):
#pragma section const {vector}
void (* const @vector _vectab[32])() =
{
_stext,

/* RESET */

TRAP_IRQHandler, /* TRAP - Software interrupt */

irqhandler,

/* IRQ0: our irq handler */

...
};

Then a specific option must be provided to the linker to map the interrupt vectors at the appropriate
address 0x8000:
+seg .const -b0x8000 vector.o

- 16 -

AN55 porting Cosmic to Raisonance

8. Interrupt handlers

8.2 Raisonance interrupts

The Raisonance toolchain handles interrupts in an automatic way. In order to be an interrupt handler, a
function must have the interrupt n qualifier. The compiler then automatically generates the interrupt
vector at the appropriate address, and the linker maps it without having to specify anything more!
void irqhandler(void) interrupt 0;

Notes:
- The trap qualifier must be used instead of the interrupt n for a trap handler.
- Registers are saved by interrupt handlers (except for the registers which are untouched, which are
not saved/restored for better performance). There is no need to worry about them.
- There is no need for a specific C file declaring the interrupt functions on the Raisonance
toolchain, as the mapping on interrupt vectors is automatically done by the linker.
- Undefined interrupt vectors are left allocatable for code. So if you do not define any interrupts in
your project, some executable code can be mapped in the interrupt vector table.

- 17 -

9. Inline assembly and C/assembler interface

AN55 porting Cosmic to Raisonance

9. Inline assembly and C/assembler interface

Some projects require the use of assembler for specific needs:
Cycle-accurate code.

Performing some very specific tricks with the stack (context switching, find return address from
current function, get access to the caller's stack frame,...).

Using CPU addressing modes in a particular way not available from C.

When converting Cosmic projects with inline assembler files, you should consider rewriting the
assembler blocks in C using intrinsic functions, writing functions in separate assembler files or keep
the inline assembler statements (in that order of preference).

9.1 Rewriting inline assembler blocks in C

Developers very often feel the need to write blocks of code in assembler for performance reasons. As
stated above, this is generally a bad idea, as inline assembler is very disruptive to optimizers. Even if a
portion of code is well written using inline assembler, the surrounding C code may be degraded by the
fact that inline assembly is activated, hence overall code for the given function may be worse using
inline assembler

9.2 Using intrinsic functions

The Raisonance compiler has some intrinsic functions that meet most of the requirements for inline
assembler. For instance, there is a function _nop_() that helps for writing delay loops.
For instance:
#include <intrins.h>

// This header file defines intrinsic functions

void delay(unsigned char time)

{
do
{
_nop_();

// Use the _nop_ function as if it was external

} while(--time);
}

- 18 -

AN55 porting Cosmic to Raisonance

9. Inline assembly and C/assembler interface

Which produces the optimal code below:

; FUNCTION ?delay (BEGIN)
; Register A is assigned to parameter time
?DO_0001:
; SOURCE LINE # 6
9D

NOP

4A

DEC

26FB

JRNE

?DO_0001

81

RET

; time

unsigned char

; NOP automatically inserted inline

(size=1). Register parameter(A) in PAGE0

; FUNCTION ?delay (END)

As you see, there is no need to write any assembler in such cases, which makes the code more
portable.
Using intrinsic functions only requires that you include the <intrins.h> header file from the Raisonance
Compiler.
The available intrinsic functions are demonstrated in the following example (which does not perform
anything useful though):
#include <intrins.h>
at 0x88 char myport = 0xA5;

// define a specific port at address 88h

int val1=0xBA42;
void main(void)
{
_rsp_();

// Reset stack pointer

_jmp_(0x1234);

// Absolute jump to an address

val1 = _swapbyte_(val1);

// Swap the bytes from val1

_sim_();

// disable interrupts

myport |= 4;

// Raise bit 2

myport = _swapnibble_(myport);

// swaps upper and low nibbles

_nop_();

// "do nothing" instruction

_rim_();

// re-enable interrupts

_halt_();

// Put the micro in halt mode.

_wfi_();

// Wait for interrupt

_trap_();

// Software trap

- 19 -

9. Inline assembly and C/assembler interface

AN55 porting Cosmic to Raisonance

9.3 Writing functions in separate assembler files

Some assembler routines may be isolated into a specific assembler file, which is linked along with your
project. For example, the context switch routines in an RTOS will need to be written in assembler. In
this case, having the routines in a separate assembler file is far better practice than having some inline
assembly in a C file. Following is an example of such an assembler file:
; Function: OS_switch
; Purpose: STM8 Context switch routine
; The current CPU state is saved into the "currenttask" task control block
; (TCB), and the one from "newtask" is set instead.
; This routine is called through the following prototype:
;

void OS_switch(TCB *currenttask, TCB *newtask)

; With:
;

struct TCB

unsigned SP;

// Stack pointer

unsigned char A;

// Accumulator

unsigned Y;

// Y register

;----------------------------------------------------------------------------; Input:

currenttask

SP+3

newtask

; Output:

None

;----------------------------------------------------------------------------$modestm8

; Distinguish STM8 mode from ST7

PUBLIC

?OS_switch

; The leading '?' is required by the compiler

CSEG

; Start a code segment

?OS_switch:
; Let's save current context
LD

(2,X), A

; Save A

LDW

(3,X), Y

; Save Y

LDW

Y, SP

LDW

(X), Y

; Save SP

; Restore the new context

LDW

X, (3,SP)

; Get pointer on new TCB from stack

LD

A, (2,X)

; Restore A

LDW

Y, X

LDW

Y, (3,Y)

LDW

X, (X)

LDW

SP, X

; Restore Y
; Restore SP

_exit:
RET

; Return to caller with the new context

END

- 20 -

AN55 porting Cosmic to Raisonance

9. Inline assembly and C/assembler interface

9.4 Using inline assembler statements

We saw several different methods above that may help you port your applications from Cosmic to
Raisonance for inline assembly conversion. If none of these methods fit your needs, and you still want
inline assembly code, you can refer to the RCSTM8 manual (chapter 4).
You can either include assembly opcodes with the "asm" keyword as follows:
asm { 0x9D }

// NOP opcode, no need for trailing semicolon (;)

Or you can include assembly code with the "ASM/ENDASM" pragmas:

#pragma SRC

// Indicates to the compiler to produce an assembler output file

void main(void)
{
#pragma ASM

// Start inline assembly

NOP
LD

A, #4

...
#pragma ENDASM

(Some other assembly code here)

// End of inline assembly

printf("OK");
}

Details of this mechanism are beyond the scope of the present document. Please refer to the
Raisonance compiler manual for further detail.

9.5 Function parameters passing

To optimize memory usage (both code and data) RCSTM8 passes parameters between functions in
working registers when possible. When passing parameters in registers is not possible (too many
parameters), parameters are passed in memory for non-reentrant functions, or on the stack for reentrant
functions.
Here again, if you just use C, you dont care how parameters are passed because the compiler
manages the whole process, but, if you want to mix C and assembler, you need to know how to get the
parameters in an assembler routine, when this routine is called from C.
If you mix C and assembler functions, specific conventions are used to communicate arguments to
functions and for the functions to return their results. The detail of these conventions go beyond the
scope of this document. Please refer to the Raisonance compiler manual for full details.

- 21 -

10. Conclusion

AN55 porting Cosmic to Raisonance

10. Conclusion
As we have seen in this document, porting applications from the Cosmic to the Raisonance toolchain is
not difficult. Most of the changes occur in the compiler and linker command-line directives, plus some
changes for ROM constants and some syntax changes for memory space qualifiers.
The Raisonance toolchain has been designed with simplicity in mind:

The linker options are very often automatic and do not need any directive, command-line option or
linker script. They just understand what is required by the application and pick the appropriate
libraries or apply specific settings that match the project.

Most noticeably, handling interrupts has never been so easy as with the Raisonance toolchain: The
interrupt handler function prototype is the only specific setting that you have to perform yourself, all
the linker burden of mapping the interrupt vector and the specific function prologue/epilogue (IRET,
register saving) is done automatically.
The STM8/ST7 Raisonance toolchain is nicely integrated into the Ride7 IDE, as well as into the ST
Visual Develop IDE. These can be used for porting your projects in order to bootstrap your projects
quickly and to reach the best time-to-market.

- 22 -

AN55 porting Cosmic to Raisonance

options

11. Annex A: ST7-specific directives and

11. Annex A: ST7-specific directives and options

Following is the list of Cosmic-Raisonance differences concerning ST7 projects.

Cosmic ST7 toolchain memory models

Model name

Option

Local variables
storage

Global variables
storage

Default pointer
size

Memory
Compact

modc

Zero Page

Zero Page

8 Bits

Memory Short

modm

Zero Page

Zero Page

16 Bits

Memory Small

modms

Zero Page

Long Range

16 Bits

Memory Medium

modmm

Long Range

Zero Page

16 Bits

Memory Long

modml

Long Range

Long Range

16 Bits

Stack Short

mods

Physical

Zero Page

16 Bits

Stack Long

modsl

Physical

Long Range

16 Bits

ST7 Memory model selection

Cosmic

Raisonance

Select the memory model in your linker options:

Select the compiler options that match your needs:

modc (same as modm except default pointer size)

DEFAULTLC(page0) DEFAULTGC(page0)

modm

DEFAULTLC(page0) DEFAULTGC(page0)

modms

DEFAULTLC(page0) DEFAULTGC(data)

modmm

DEFAULTLC(data) DEFAULTGC(page0)

modml

DEFAULTLC(data) DEFAULTGC(data)

mods

AUTO DEFAULTGC(page0)

modsl

AUTO DEFAULTGC(data)
The linker automatically selects appropriate
libraries.

- 23 -

12. Index

AN55 porting Cosmic to Raisonance

12. Index
16-bit address......................................................10
24-bit address......................................................10
8-bit address........................................................10
Absolute functions................................................13
Absolute variables................................................13
argc......................................................................15
argv......................................................................15
ASM/ENDASM pragmas......................................21
Assembly opcodes...............................................21
at address............................................................13
auto-relocation mode...........................................11
automatic interrupt generation.............................17
Automatic variables relocation.............................11
Bit type.................................................................15
Bit variables.........................................................15
C language extensions summary...........................8
CALLF/RETF.......................................................10
code memory space............................................13
const....................................................................13
Cosmic ST7 toolchain memory models...............23
crtsi.s...................................................................14
crtsif.s..................................................................14
crtsx.s..................................................................14
crtsxf.s.................................................................14
Declaring interrupt functions................................17
DEFAULTGC.......................................................11
far CALL/RET......................................................10
far code................................................................13
Floating-point libraries..........................................12
function _nop_() ..................................................18
Global variables...................................................14
Hide code...............................................................9
INITSTATICVAR..................................................14
Inline assembly....................................................18
interrupt n qualifier...............................................17
Interrupt qualifier..................................................17
intrinsic functions.................................................19
Large data tables.................................................13
Local variables storage........................................11
Macros...................................................................9
main()..................................................................14
mapping interrupt vectors....................................17
modc....................................................................23
modm...................................................................23
modml..................................................................23
modmm...............................................................23

modms.................................................................23
mods....................................................................23
mods0....................................................................7
modsl...................................................................23
modsl0...................................................................7
NOINITSTATICVAR............................................14
page0...................................................................10
Parameters passed in memory............................21
Parameters passed in stack.................................21
Passing parameters.............................................21
pointer size..........................................................12
Pointer size control..............................................12
ptab......................................................................12
Qualifiers..............................................................10
Reduce your code footprint..................................11
Ride7...................................................................11
Separate assembler files.....................................20
ST Visual Develop...............................................11
ST7 Memory model selection..............................23
Stack initialization................................................14
startup..................................................................14
startup.asm..........................................................14
static....................................................................11
STM8(LARGE......................................................10
STM8(SMALL).....................................................10
Toolchain directives...............................................7
trap......................................................................17
Trap handler........................................................17
Using inline assembler statements......................21
void irqhandler(void)............................................16
volatile..................................................................12
__RCSTM8__........................................................9
__ROM_MODEL__................................................9
__ST7__................................................................9
__STM8__.............................................................9
_Bool type............................................................15
.bss......................................................................14
.data.....................................................................14
@address:bitnumber...........................................13
@far.....................................................................10
@interrupt............................................................16
@near..................................................................10
@tiny....................................................................10
%ridedir%..............................................................5
+nobss.................................................................14

- 24 -

AN55 porting Cosmic to Raisonance

13. History

13. History
Date

Description

Mar 09

Initial version

Apr 09

Document reorganized: Recapitulation table is now in the head of the document.

Added some details about Raisonance floating-point libraries.

Jun 09

Added some details about interrupt vectors mapping and boolean variables.

02 Oct 12

Modified cover page, final page and section 1.3 Additional help or information for KEOLABS

28 May 13

Modified template

- 25 -

Disclaimer
Information in this document is subject to change without notice and does not represent a commitment
on the part of the manufacturer. The software described in this document is provided under license and
may only be used or copied in accordance with the terms of the agreement. It is illegal to copy the
software onto any medium, except as specifically allowed in the license or nondisclosure agreement.
No part of this manual may be reproduced or transmitted in any form or by any means, electronic or
mechanical, including photocopying, recording, or information storage and retrieval systems, for any
purpose other than the purchasers personal use, without prior written permission.
Every effort has been made to ensure the accuracy of this manual and to give appropriate credit to
persons, companies and trademarks referenced herein.
This manual exists both in paper and electronic form (pdf).
Please check the printed version against the .pdf installed on the computer in the installation directory of
the most recent version of the software, for the most up-to-date version.
The examples of code used in this document are for illustration purposes only and accuracy is not
guaranteed. Please check the code before use.
Copyright KEOLABS 2014 All rights reserved