STMicroelectronics

ST200 VLIW series

ST200 cross
development manual
User manual

7521642 Rev L

November 2006

BLANK

User manual
ST200 VLIW series
ST200 cross development manual

Overview
The ST200 development system is a set of tools used to create programs for the ST200
family of VLIW cores. It is a cross-development environment, in that the target machine for
which the code is developed (for example, ST220) is distinct from the host machine on
which the development tools run. As there are many situations in which the availability of a
target is not possible, a software simulator is provided on which to run and evaluate code.
This has the advantage of allowing software to be developed in parallel with the detailed
design of the hardware, as well as permitting software considerations to exert a reciprocal
effect on hardware design (in cases where the hardware architecture has not been
finalized).

November 2006

7521642 Rev L

1/170
www.st.com

Contents

ST200

Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
ST200 document identification and control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
ST200 documentation suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Conventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.1

Testing the compiler installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.2

Supported targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3

Connecting to a target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.4

Target address space usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.5

st200run tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.6

Targets and target options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.7

1.8

1.9

2/170

1.6.1

Simulator options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.6.2

Board options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

st200gdb debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.7.1

GDI target command option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.7.2

GDI st200gdb commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1.7.3

New startup configuration commands . . . . . . . . . . . . . . . . . . . . . . . . . . 33

1.7.4

Emulated system calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Using the graphical user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

1.8.1

Running a simple debugging session . . . . . . . . . . . . . . . . . . . . . . . . . . 35

1.8.2

Accessing other st200gdb functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

1.8.3

Using the ST2x0 Statistics window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

1.8.4

Using the Performance Monitoring window . . . . . . . . . . . . . . . . . . . . . . 38

1.8.5

Displaying multiple Memory windows . . . . . . . . . . . . . . . . . . . . . . . . . . 39

1.8.6

Watch and local variables window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

1.8.7

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Configuring the program execution startup . . . . . . . . . . . . . . . . . . . . . . . 42

1.9.1

Initialization sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

1.9.2

Initialization hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7521642

ST200

Contents

1.10

1.11

Configuring the run-time and boot code for a target . . . . . . . . . . . . . . . . . 44

1.10.1

The sysconf and boot code modules . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

1.10.2

Generating code for a board target . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Using a custom board target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

1.11.1

Defining a custom board target and compiling a program . . . . . . . . . . . 46

1.11.2

Debug a program on a custom hardware board target . . . . . . . . . . . . . 47

1.12

Modifying the memory protection settings . . . . . . . . . . . . . . . . . . . . . . . . 47

1.13

Rebuilding the run-time libraries and target modules . . . . . . . . . . . . . . . . 48

1.13.1

Rebuilding the target BSP tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

1.13.2

Rebuilding the lib tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

1.13.3

Rebuilding the OS21 libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

The STWorkbench and related plug-ins . . . . . . . . . . . . . . . . . . . . . . . . 50

2.1

STWorkbench installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.1.1

2.2

2.3

Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Getting started with STWorkbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

2.2.1

Configuring STWorkbench to work with the ST200 toolset . . . . . . . . . . 52

2.2.2

Creating and building a Hello World project . . . . . . . . . . . . . . . . . . . . . . 53

2.2.3

Debugging Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

STWorkbench customizations for ST200 . . . . . . . . . . . . . . . . . . . . . . . . . 55

2.3.1

ST200 preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

2.3.2

ST Profiler preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

2.3.3

Creating a new project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

2.3.4

Library names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

2.3.5

Project properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

2.3.6

Building, cleaning, rebuilding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

2.3.7

Running a program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

2.3.8

Analyzing a program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

2.3.9

Running and analyzing a program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

2.3.10

Debugging a program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

2.3.11

Debugging tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

ST200 simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.1

Target configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

3.2

The sample device plug-in for the ST200 simulator . . . . . . . . . . . . . . . . . 71

3.2.1

Callbacks into the simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

3.2.2

Building and running the plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

7521642

3/170

Contents

ST200

3.3

The ST200 simulator plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

3.3.1

Setting up a board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.1

Introduction to setting up a board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.2

Understanding target dependent settings . . . . . . . . . . . . . . . . . . . . . . . . 75

4.3

4.4

4.5

4.6

4.2.1

Toolset partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.2.2

Toolset configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

4.2.3

Configuration matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Supported configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.3.1

ST220 and ST231 cores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

4.3.2

SoC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

4.3.3

Example of mb428_host and mb428_audio boards . . . . . . . . . . . . . . . 83

Integrating a new board in the toolset . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

4.4.1

Add a board file into the ST200 toolset . . . . . . . . . . . . . . . . . . . . . . . . . 84

4.4.2

Critical test suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Using the tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

4.5.1

Initialization sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

4.5.2

st200gdb commands for bring up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

4.5.3

Debug facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Bring up operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.6.1

Define an alias for the silicon connection settings . . . . . . . . . . . . . . . . . 87

4.6.2

Connect to the target through the ST Micro Connect . . . . . . . . . . . . . . 87

4.6.3

Perform the DSU register accesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

4.6.4

Perform the RAM accesses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

4.6.5

Execute the generated critical test suite . . . . . . . . . . . . . . . . . . . . . . . . 88

4.6.6

Compile and execute a C program . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Relocatable loader library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

5.1

Introduction to the relocatable loader library . . . . . . . . . . . . . . . . . . . . . . 90

5.1.1

5.2

Run-time model overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Relocatable run-time model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

5.2.1

4/170

ST200 simulator plug-ins usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

The relocatable code generation model . . . . . . . . . . . . . . . . . . . . . . . . . 93

5.3

Relocatable loader library API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

5.4

Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
5.4.1

Memory allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

5.4.2

File management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

7521642

ST200

Contents

5.5

Building a relocatable library or main module . . . . . . . . . . . . . . . . . . . . 108

5.5.1

Importing and exporting symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

5.5.2

Optimization options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

5.6

Debugging support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

5.7

Profiling support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

5.8

Memory protection support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

5.9

Load time decompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Appendix A ST200 board support package (BSP). . . . . . . . . . . . . . . . . . . . . . . 114

A.1

A.2

A.3

A.4

A.5

A.6

Introduction to board support packages . . . . . . . . . . . . . . . . . . . . . . . . . 114

A.1.1

Backward compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

A.1.2

Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
A.2.1

Managing the caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

A.2.2

Cache header file: machine/bsp/cache.h . . . . . . . . . . . . . . . . . . . . . . . 116

Instruction and data protection unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

A.3.1

IPU/DPU support functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

A.3.2

Initializing the IPU/DPU support system . . . . . . . . . . . . . . . . . . . . . . . . 116

A.3.3

Managing the IPU/DPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

A.3.4

OS21 BSP for DPU/IPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

A.4.1

Initial memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

A.4.2

Managing the MMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

A.4.3

MMU header file: machine/bsp/mmu.h . . . . . . . . . . . . . . . . . . . . . . . . . 118

A.4.4

Speculative control unit (SCU) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
A.5.1

Input clock frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

A.5.2

Tick duration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

A.5.3

Reading the current time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

A.5.4

ST200 timer assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

A.5.5

Timer header file: machine/bsp/timer.h. . . . . . . . . . . . . . . . . . . . . . . . . 122

Performance monitor (PM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

A.6.1

A.7

Hardware abstraction layer for the PM module. . . . . . . . . . . . . . . . . . . 124

Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

A.7.1

Exceptions types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

A.7.2

Exceptions header file: machine/bsp/core.h . . . . . . . . . . . . . . . . . . . . . 127

7521642

5/170

Contents

ST200

A.8

Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
A.8.1

Interrupt handler installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

A.8.2

Interrupts header file: machine/bsp/interrupt.h . . . . . . . . . . . . . . . . . . . 127

A.9

OScalls and debug events suspension . . . . . . . . . . . . . . . . . . . . . . . . . . 128

A.10

Flash file system handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

A.11

User handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

A.12

BSP function definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

6/170

7521642

ST200

Preface

Preface
ST200 document identification and control
Each book in the ST200 documentation suite carries a unique ADCS identifier of the form:
ADCS nnnnnnnx
where nnnnnnn is the document number, and x is the revision.
Whenever making comments on an ST200 document, the complete identification
ADCS nnnnnnnx should be quoted.

ST200 documentation suite

The ST200 documentation suite comprises the following volumes:

ST200 Micro Toolset Compiler Manual

(ADCS 7508723) This manual describes the software provided as part of the ST200 tools. It
supports the development of ST200 applications for embedded systems. Applications may
be developed in either a stand-alone environment, or under the OS21 real-time operating
system.
This manual also contains reference material relating to the ST200 Micro Toolset.

ST200 Cross Development Manual

(ADCS 7521642) This manual describes the cross development tools and platforms.

ST200 Run-time Architecture Manual

(ADCS 7521848) This manual describes the common software conventions for the ST200
processor run-time architecture.

ST200 ELF Specification

(ADCS 7932400) This document describes the use of the ELF file format for the ST200
processor. It provides information needed to create and interpret ELF files and is specific to
the ST200 processor.

OS21 for ST200 User Manual

(ADCS 7410372) This manual describes the use of OS21 on ST200 platforms. It describes
how specific ST200 facilities are exploited by the OS21 API. It also describes the OS21
board support packages for ST200 platforms.

ST220 Core and Instruction Set Architecture

(ADCS 7395369) This manual describes the architecture and the instruction set of the
ST220 core as used by STMicroelectronics.

ST231 Core and Instruction Set Architecture

(ADCS 7645929) This manual describes the architecture and the instruction set of the
ST231 core as used by STMicroelectronics.
7521642

7/170

Preface

ST200

Conventions used in this guide

General notation
The notation in this document uses the following conventions:

sample code, keyboard input and file names,

variables and code variables,

code comments,

screens, windows and dialog boxes,

instructions.

Hardware notation
The following conventions are used for hardware notation:

REGISTER NAMES and FIELD NAMES,

PIN NAMES and SIGNAL NAMES.

Software notation
Syntax definitions are presented in a modified Backus-Naur Form (BNF). Briefly:
1.

Terminal strings of the language, that is, strings not built up by rules of the language,
are printed in teletype font. For example, void.

2.

Nonterminal strings of the language, that is, strings built up by rules of the language,
are printed in italic teletype font. For example, name.

3.

If a nonterminal string of the language starts with a nonitalicized part, it is equivalent to

the same nonterminal string without that nonitalicized part. For example, vspacename.

4.

Each phrase definition is built up using a double colon and an equals sign to separate
the two sides (::=).

5.

Alternatives are separated by vertical bars (|).

6.

Optional sequences are enclosed in square brackets ([ and ]).

7.

Items which may be repeated appear in braces ({ and }).

Mathematical notation
A range of values can be shown using square braces, [], and round braces, (). Square
braces mean the nearest value is included, and round braces mean the nearest value is not
included.
For example:

8/170

[1 .. 3]

is the values 1, 2, 3,

[1 .. 3)

is the values 1, 2,

(1 .. 3]

is the values 2, 3,

(1 .. 3)

is the value 2 only.

7521642

ST200

Preface

Acknowledgements
Microsoft, Visual Studio and Windows are registered trademarks of Microsoft
Corporation in the United States and/or other countries.
SolarisTM is a trademark of Sun Microsystems, Inc. in the US and other countries.
CygwinTM and InsightTM are trademarks of Red Hat Software, Inc.
Linux is a registered trademark of Linus Torvalds.

7521642

9/170

Getting started

ST200

Getting started

1.1

Testing the compiler installation

On Solaris and Linux, the following simple test can be executed to check that the compiler is
correctly installed.
cp -r <tools-dir>/samples/hello .
cd hello
make
where <tools-dir> is the installation directory.
The string Hello World !! is displayed after the compilation and execution in the
simulator target.
On a Windows PC, the same test can be carried out by entering the following commands
through the console:
xcopy /I /Y <tools-dir>\samples\hello .\hello
cd hello
make

1.2

Supported targets
Different versions of the ST200 Micro Toolset support different targets.
The R5.0 toolset supports the ST220 and ST231 cores on the following targets: ST220 and
ST231 Simulator, STm8000-Demo Board (mb379), STm5700-Demo Board (mb385),
ST230EMU-PCI Board (mb388a), STm8010-Mboard (mb421), ST231-EVAL board
(mb424), STm8010-REF Traviata (mb426), STb5525-Mboard (mb428) and STb7100/09-Ref
board (mb442).

1.3

Connecting to a target
Figure 1 shows how to connect to a target from an ethernet based host via an ST Micro
Connect(a).

a. The ST Micro Connect required is the ST40-Connect.

10/170

7521642

ST200

Getting started
Figure 1.

Connecting to a target

ST Micro Connect

Solaris, Linux or Windows host

Ethernet
network
(working at 10 MBaud)
Silicon target

1.4

Target address space usage

By default, the toolset is configured for the program to load and execute in 8 Mbytes of LMI
RAM memory (from 0x08000000 to 0x08800000). Figure 2 explains how the toolset uses
the ST200 address space to load and execute a C program when the program is compiled
and executed with the default options.
In order to change the memory location where the program is loaded and executed, memory
settings must be changed in the board.ld linker script located in
<tools-dir>/target/board/<my_board>.
Once DEFAULT_RAMEND, DEFAULT_TEXT_BASE and memory mapping have been
modified, compile and run the program as usual. This is shown in the example provided in
<tools-dir>/samples/hello. See the README file for more information.
Board configuration has been designed to be flexible, so that it is possible to add a custom
board with different memory and run-time settings. Guidelines are provided in Section 1.11:
Using a custom board target on page 46.

7521642

11/170

Getting started
Figure 2.

ST200

ST200 address space usage

Memory Space

0x00000000
RESET_ADDRESS
.bootreset

0x00010000
BOOT_ADDRESS

0x08000000
TEXT_BASE

Comments
Section loaded, and executed only if reset
mode is specified from st200run or st200gdb.
This is the section where execution starts after
RESET signal is released.

.boot

Section loaded, and executed only if reset mode

is specified from st200run or st200gdb.
The default boot code executes external memory
initialization, initializes the start parameters to the
default ones then jumps to 0x08000000.

.text

Section loaded.
It contains the __start() entry point of the program.

.data

Section loaded. Initialized C global variables are

directly mapped at these addresses.

.bss

Not loaded, initialized to 0 at __start() execution,

unless st200run --no_clear_bss is set or
st200gdb startbss is set to no.
During the execution, the stack grows toward the
default area where sections are loaded and the
heap for malloc grows from the end of the .bss
section towards the stack.

stack_pt -->
scratch area

16 bytes aligned area to setup the stack.

copy of args

This area (before RAMEND) is used by st200run or

st200gdb to pass arg and env information to the
program.

kernel stack

16 Kbytes reserved for the kernel stack.

scratch area
RAMEND

16 bytes aligned area to setup the kernel stack

copy of env var

kstack_pt -->
0x08800000
_ramend

This base address is configurable through the

board.ld script link dedicated to the target.

0xffffffff

12/170

7521642

ST200

1.5

Getting started

st200run tool
st200run enables the connection of an execution target, and enables an ST200 program to
load and execute. Moreover, while the program is executing on the target, st200run is able
to emulate some system calls (syscall) on the host machine.
The system calls emulated are:

All C standard I/O:

inputs and outputs are read from and written to the console where the st200run
command is executed.

All C file I/O:

files are opened, written to and closed in the host environment.

exit() process termination:

the exit() function is called on the host side, terminating the st200run process or
making the debugged program exit under st200gdb.

The program is invoked as follows:

st200run [OPTIONS] [FILES]
The valid [OPTIONS] are described in Table 1 on page 14. [FILES] must specify the
program name and its arguments.
Note:

If the - character precedes a program argument, it must be back-slashed twice (\\-) in order
to not be interpreted by st200run and sent to the target program.
Binary files are checked at load time to ensure they match one of the core versions
supported by the target. An error is displayed if they do not match.
A complete example of how to operate the st200run tool is provided in
<tools-dir>/samples/hello.
The --target (or -t) option is a compulsory option and should specify the alias name of a
predefined target. The predefined targets are configured in the target description file. See
Section 1.6 on page 19 for a full description of targets.
Two types of target are supported by the toolset: the simulator targets, based on the ST200
cycle accurate reference simulator models, and real silicon targets. Section 1.2: Supported
targets on page 10 details the targets supported by each toolset release.
There are three basic modes that can be used to run a simulation. They reflect the trade off
in simulation accuracy against simulation speed.

In Reference (or cycle accurate) mode, the pipeline is modelled, and by default, the
caches are configured to be at the highest level of detail. The memory subsystem/bus
is also faithfully modelled (including the write buffer and prefetch buffer), as are all the
relevant protection/translation units (for example, IPU, DPU on the earlier ST200 cores
and the UTLB + micro TLBs on the ST231 cores onwards). This mode is guaranteed to
execute code in a similar manner to the hardware, that is, it behaves as expected in all
exceptional circumstances. This includes the modelling of all types of bus errors,
interrupts, debug interrupts and exceptions. Consequently, it has the lowest
performance of the three modes.

In ISS (or instruction set accurate) mode, each instruction is run to completion before
the next instruction begins (that is, it does not model the pipeline, latencies, interlocking
and so on). It does model the caches (basic versions) and the protection/translation
units (IPU/DPU/UTLB), so (as with reference mode) in terms of exceptional
circumstances, it behaves in a manner similar to the hardware.

7521642

13/170

Getting started

ST200
In Fast (functional) mode, only the minimal set of components required to run correct
code correctly are modelled. This mode does not model any of the memory
subsystem, caches, protection units (the UTLB however is present in the ST231
model), bus errors, external interrupts or provide the device plug-in functionality.
Therefore, it has the highest performance, but the lowest accuracy.

The simulator configuration options are described in Table 2 on page 20.

Table 1.

st200run options

Option

14/170

Short form

Description
Display the st200run help and exit.
For example:
st200run -h
st200run --help

--help

-h

--after_exec=
<STRING>

This option submits a direct command(1) to the target, via

the GDI function DiDirectCommand(), after the program
has exited.
For example:
st200run -astatistics -tsim hello
st200run --after_exec=statistics -tsim hello
In the case above, st200run calls
-a<STRING>
DiDirectCommand("statistics") after the hello
program has exited.
If the direct command contains several parameters, it must
be enclosed in double quotes. For example:
st200run a"statistics file" tsim hello
See Table 5 on page 28 for a list of all the available
simulator direct commands.

--before_exec=
<STRING>

This option submits a direct command(1) to the target,

before program execution, via the GDI function
DiDirectCommand().
For example:
st200run -bstatistics -tsim hello
st200run --before_exec=statistics -tsim
hello
-b<STRING> In the case above, st200run calls
DiDirectCommand("statistics") before starting
execution of the hello program.
If the direct command contains several parameters, it must
be enclosed in double quotes. For example:
st200run b"statistics file" tsim hello
See Table 5 on page 28 for a list of all the available
simulator direct commands.

7521642

ST200

Getting started
Table 1.

st200run options (continued)

Option

Short form

Description

-D

st200run displays a variety of debug information during

load and run. This is stored in the run.log file. Debug
information covers the following:
module versions,
DLL parameters,
various information about GDI functions,
system call information.
For example:
st200run -D -tsim hello
st200run --debug -tsim hello

--detach

-P

This option detaches st200run from application execution

on the silicon target (the default is off). No polling is
performed by st200run on the board to get the status on
application execution. The applications oscalls are not
serviced with this option.
For example:
st200run -P -tboard hello
st200run --detach -tboard hello

--dll=<STRING>

This option is used to specify a GDI dynamic target dll

name and associated target options.
The search strategy for the dynamic library is explained in
Search strategy for dynamic libraries on page 18.
Appropriate file extensions are completed automatically
(.dll on Windows, .so on Solaris and Linux).
This facility can be used to patch an existing toolset with a
new version of a target dynamic linked library.
-d<STRING>
For example:
st200run -dst200sim hello
st200run --dll=st200sim hello
If the dll is called with options, it must be enclosed in double
quotes. For example:
st200run d"st200sim 220" hello
Details of the available target options for the simulator
target are defined in Section 1.6 on page 19.

--debug

--env

-e

Pass the host environment to the target. By default, the host

environment is not passed.
For example:
st200run -tsim hello
In this case, if the hello program uses the getenv
function, for example:
printf("PATH=%s\n",getenv("PATH"));
the environment variable value is not displayed.
st200run -e -tsim hello
st200run --env -tsim hello
In these cases, if the hello program uses the getenv
function, for example:
printf("PATH=%s\n",getenv("PATH"));
the environment variable value is displayed.

7521642

15/170

Getting started

ST200

Table 1.

st200run options (continued)

Option

Description

--force

-f

Specifying this option bypasses any checks made on

memory, architecture or endianness at load time.
The following checks are carried out:
check presence of memory before loading a section,
check RAMEND address is located in a memory area,
check if the execution engine is compatible with the core
for which the binary is generated,
check if the target endianness is compatible with binary
endianness.
This option is useful while working with a new board or core
environment that is not fully integrated in the toolset.

--ignore_cache

-c

Execute the system calls ensuring that parameters passed

to the st200run tool are synchronized with the external
RAM (and not left in ST200 internal caches).

--loaded

-l

With this option st200run assumes the program has

already been loaded into memory. By default, st200run
considers that the program is not loaded.
For example:
st200run -tsim hello
The hello program is not loaded in memory. st200run
must load it.
st200run -l -tsim hello
st200run --loaded -tsim hello
The hello program is already loaded in memory. st200run
does not load the program.

--mtargetdir=
<STRING>

Defines the path for the target to use.

For example:
-m<STRING> st200run -tmyboard -m/home/xx/mytarget hello
The program uses all description files (for example,
targets.cfg and board.txt) defined in the
/home/xx/mytarget directory.

-B

This option prevents the .bss section from being initialized

during the startup execution. This is useful for testing
programs with large C global variables on slow execution
targets. Beware, the user must ensure that the memory
content at the address to which the bss is mapped has
been initialized to 0.
By default, the .bss is cleared by the program during the
startup phase.

--noncacheable_
size=<INT>

-n<INT>

This option has been deprecated.

Specify the size of the noncacheable memory area (in
bytes). If the size is not defined, it defaults to 16 Kbytes.
For example:
st200run -c -n0x1000 -tsim hello
st200run -c --noncacheable_size=0x1000 -tsim
hello

--pc=<INT>

-p<INT>

This is used to specify the PC start value.

--no_clear_bss

16/170

Short form

7521642

ST200

Getting started
Table 1.

st200run options (continued)

Option

--ramend=<INT>

--reset

Short form

Description

-r<INT>

Define the address of the end of the RAM. This base

address is configurable with this option. The default value of
the RAM end is the value defined in board.ld file for the
current target selected.
<INT> value can be in hexadecimal or decimal.
For example:
st200run -tsim hello
The RAM end is 0x08800000 for the simulator target.
st200run -tsim -r0x03800000 hello
st200run -tsim --ramend=0x03800000 hello
The RAM end is 0x03800000.
When using a simulator target, any changes made to
RAMEND must be matched by a change to the configuration
option EXTERNAL_MEMORY_SIZE, see Table 7: Target
configuration options on page 67.
If the -reset option is used, the -ramend option is
ignored.

-R

By default, execution is started at the __start symbol in

the binary file. When reset mode is specified, execution
starts at the hardware reset address. This allows execution
of boot code.
For example:
st200run -R -tsim hello
st200run --reset -tsim hello

Specify the name of a predefined target. The predefined

targets are configured in a target description file.
--target=<STRING> -t<STRING> For example:
st200run -tsim hello
st200run --target=sim hello

--timeout=<INT>

-o<INT>

st200run will be stopped after the agreed delay (INT

seconds)
For example:
st200run -tsim -o5 hello
st200run -tsim --timeout=5 hello
The program will be stopped after 5 seconds if it doesn't
stop before.

7521642

17/170

Getting started

ST200

Table 1.

st200run options (continued)

Option

--verbose

--version

Short form

Description

-v

Provide additional information on st200run, including:

target description file used,
dynamic library used,
st200run version,
GDI version supported,
target version (dll version used),
progress loading sections,
transfer rate (bytes per second),
run-time version used.
For example:
st200run -v -tsim hello
st200run --verbose -tsim hello

-V

Display the st200run version and exit.

For example:
st200run -V
st200run --version

1. The full list of direct commands can be obtained by typing gdi help at the gdb command prompt after
connecting to the dll.

Search strategy for dynamic libraries

The search algorithm defined below is used by st200run or st200gdb, to locate the
corresponding execution engine:
if(engine_library found in . ) {
engine_library = ./engine_library
}
else if ($ST200ROOT_ENGINE exists && engine_library found in
$ST200ROOT_ENGINE) {
engine_library = $ST200ROOT_ENGINE/engine_library
}
else if(engine_library found in
<tools-dir>/lib/engine/<core>/<endianness>) {
engine_library =
<tools-dir>/lib/engine/<core>/<endianness>/
engine_library
}
else engine_library not found

18/170

7521642

ST200

Getting started

1.6

Targets and target options

st200run is designed to be compatible with a variety of execution models (for example,
simulator and silicon boards) as well as an effectively unlimited number of parameterized
variants. These are referred to as targets and are defined in a file, targets.cfg, which is
supplied with the standard toolset release. When invoking either st200run or st200gdb,
the execution target must be specified on the command line using the option
-t<target_name>. The location of the target specified by <target_name> is determined
in accordance with the strategy defined below:
if (-mtargetdir=<mytarget-dir> option defined &&
targets.cfg in the path defined by this option &&
<target_name> is in this targets.cfg )
{
target = <target_name> as found in <mytarget-dir>/targets.cfg
}
else if (target.cfg found in <tools-dir>/target &&
<target_name> is in this targets.cfg)
{
target = <target_name> as found in
<tools-dir>/target/targets.cfg
}
else
target not found

Note:

1.6.1

$ST200ROOT_TARGET is now deprecated. Use the -mtargetdir option instead.

For the Windows toolset, the path defined with the -mtargetdir option must be set using
the format DRIVE:\Directory\ (for example C:\mytarget\).

Simulator options
By default, two simulator targets are predefined in <tools-dir>/target/targets.cfg.
They are:

sim: the default simulator target,

simprof: the simulator target, generating profiling data files in gprof format.

The following syntax is used in the targets file:

<target name> <dll name> [dll options ...]
For example:
sim st200sim MODE FAST
This defines a target called sim which uses the st200sim.dll file to simulate the program
in FAST_MODE. Core and simulator endianness are deduced from the programs binary.
The intention is for the user to modify this file (or a copy of it) in order to define specific
execution contexts. For example, if it is necessary to assess the performance of the
processor in the context of a system with specific bus latency and external memory
characteristics, the following target might be added to the file:
sim_SoCx st200sim BUS_LATENCY 30 EXTERNAL_MEMORY_SIZE 0x600000
This defines a target called sim_SoCx which uses the st200sim.dll to simulate the core
defined within the program binary, specified in a system context in which the latency on the
bus is 30 bus cycles and the external memory size is 6 Mbytes.
7521642

19/170

Getting started

ST200

The first item after the target identifier is the name of the dynamic library (.dll or .so)
used to specify the execution model. st200sim indicates the simulator. The remaining
items are referred to as target options and are specific to the target concerned.
There are three ways to specify target options:

include the options on a line defining a distinct target in the targets.cfg file,

list the options in double quotes, along with the dynamic library name, as an argument
to the st200run dll option (see Table 1 on page 14),

list the options in a textual configuration file and specify the filename using a single
CONFIG_FILE option.

The basic simulator options are listed in Table 2, further options are given in Section 3.1 on
page 67. The first two target options are used to control the use of the configuration file
itself.
Table 2.

Simulator target configuration options

Option

Description

Default value

CONFIG_FILE
<filename>

Read options from the specified CONFIG_FILE (see

DUMP_CONFIG_FILE).

DUMP_CONFIG_FILE
<filename>

Dump all user definable options to the specified file.

MODE [FAST|ISS
|REFERENCE|REF]

The operation mode, the options are FAST, ISS and

REFERENCE (or REF). See Section 1.5 on page 13.

REFERENCE

EXTERNAL_MEMORY_
SIZE <number>

Size of external memory (in bytes).(1)

Beware that, by default, the toolset generates programs
that use only 0x800000 bytes of memory size. To specify
a larger or smaller memory usage for the program, either
use the --ramend option of st200run (see Table 1 on
page 14) or adjust the board.ld parameter and rebuild
the program (see Section 1.11.1 on page 46).

0x800000 for
ST220
0x4000000 for
ST231

EXTERNAL_MEMORY_
BASE <number>

Byte address of the base of external memory.(1)

0x08000000

The size (in bytes) of noncacheable memory. Buffers

NONCACHEABLE_MEM_
0x4000
associated with a number of I/O related system calls are
(2)
SIZE <number>
(16 Kbytes)
copied into this area.

TRACING_ON <bool>

This item only takes effect when TRACING_ON is set to

OUTPUT_TRACE_FILE true. Its effect is to output the trace to the specified
<"filename">
filename. If the string is empty or the file cannot be
opened, the trace is output to stdout.

""

TRACE_START_CYCLE
Cycle on which to start tracing.
<number>

TRACE_END_CYCLE
<number>

20/170

This determines whether or not the simulator produces a

code execution trace. If set to true, the default operation
is to output a textual trace to stdout. An alternative
false
location can be specified by setting the
OUTPUT_TRACE_FILE configuration item.

Cycle on which to end tracing.

7521642

ST200

Getting started
Table 2.

Simulator target configuration options (continued)

Option

PROFILING <bool>

Description
When this is set to true the simulator will produce the
following (gprof-style) output files(3):
gmon.out - standard execution profile.
gmon.outDCACHE - time spent in each function waiting
on dcache stalls.
gmon.outICACHE - time spent in each function waiting
on icache stalls.

Default value

false

By default, profiler information is recorded in a file in

which the last part of the filename is an incrementing
PROFILING_OUTPUT_ integer (for example, 0042). The width of this numeric
"gmon****"
FILE <"filename"> field is determined by the form of the filename. For
example gmon**** results in a succession of filenames:
gmon0000, gmon0001, and so on.
1. EXTERNAL_MEMORY_SIZE and EXTERNAL_MEMORY_BASE can be used to model additional blocks
of memory if desired.
2. The st200run and st200gdb tools are insensitive to this option. This option is only meaningful for
cosimulation environments.
3. The gmon format employs 16-bit numbers to represent time intervals. As this gives insufficient dynamic
range for typical simulations, time values have had to be scaled. In consequence, the column headers
produced by gprof (specifying the underlying unit of time) are incorrect. It is recommended that analysis of
execution profiles is restricted to consideration of relative times.
See the gprof documentation for information on the interpretation of the output files.

1.6.2

Board options
Silicon targets are predefined in <tools-dir>/target/targets.cfg, for example,
mb379. By default this is commented out in the targets.cfg file. When a silicon target is
connected, the definition must be uncommented and the IP address must be modified.
The following syntax is used in the targets file:
<target name> <dll name> [dll options ...]
For example:
mb379 st200emu HTI_ID tcp:<IP address>
The first item after the target identifier is the name of the dynamic library (.dll or .so)
used to specify the execution model. st200emu indicates a silicon target. The remaining
items are referred to as target options and are specific to the target concerned.
There are two ways to specify target options:

include the options on a line defining a distinct target in the targets.cfg file,

list the options in double quotes, along with the dynamic library name, as an argument
to the st200run dll option (see --dll in Table 1 on page 14).

The available board specific options are listed in Table 3.

7521642

21/170

Getting started
Table 3.

ST200
Silicon target configuration options
Option

22/170

Description

Default value

BOARD <boardname>

This option is necessary for a board connection unless

DSU_TEST is specified. <boardname> indicates the
name of the directory in
<tools-dir>/target/board that contains the
board.txt and board.ld files for the board.
The board.txt file (or the file referred by the
BOARD_TXT_FILE option, if present) describes the
connection initialization sequence and the board.ld
file describes the RAM location in the memory mapping.

BOARD_TXT_FILE
<filename>

Specify an alternate name for the board configuration

file containing the connection initialization sequence.
The file is searched relatively from the directory
specified by the BOARD option.

BOOTRAM= <address>

This specifies the RAM area used at connection, reset,

load and at run time for running some utility routines.
The RAM content is safely restored after use.
If there are several ST200 cores sharing the same RAM
space under concurrent debug access, it is necessary
to specify a different address for each core. An
alternative method to define this area is to specify a
reserved debug memory region in the board.ld file.

CLOCK_D= <num>

ST200 clock divider. Setting <num> to 1 means the full

HTI(1) clock (50 MHz).
Note that the semantic of the CLOCK_D option changes 1
in the case of a pure JTAG connection, see the
description of the PURE_JTAG option.

CONFIG_FILE
<boarddir>

This option is deprecated but kept for compatibility

reasons. It should be replaced by the BOARD
<boardname> option.

CPU_RESET_ADDRESS=
<address>

This specifies the value of the CPU reset address.

DISABLE_MPOKE

This is a simplified connection mode. At connection

time, a physical core reset and taplink reset are
performed. The board.txt memory initialization file is
then executed. This state prevents some utility routines
from being installed and so introduces the following
discrepancies:
the core endianness is not tested so that it remains in
assumed little-endian mode by default, and
the downloading speed remains at the default poke
slow rate.
This connection mode is used as an intermediate step
during new board tests.

7521642

board.txt

0x0

ST200

Getting started
Table 3.

Silicon target configuration options (continued)

Option

Description

Default value

DSU_TEST

This sets the mode for hardware board testing. At

connection time, only a physical core reset and taplink
reset are performed. In this state, the memory access is
not setup but the ST200 DSU can be accessed through
the boards low level commands. This connection mode
is required for executing the DSU critical test suite.
This connection mode is dedicated to initial silicon bring
up tests and is not suitable to execute any toolset
generated program.

EMU_SAFE_TRACE

Set low level communication trace in safest but slowest

mode.

EMU_TRACE

Set low level communication trace.

HTI_ID tcp:
<IP_ADDRESS>

Host Target Interface(1) (HTI) connection identification.

HTI_MODE
[st200|tap|st20]

HTI(1) connection mode.

st200

ID2KEY_FILE
<filename>

Specify an alternate name for the file containing the

identifier-key mapping list used by the id2key board
command.
The file is searched relatively from the directory
specified by the BOARD option.

id2key.txt

This option specifies a pure jtag connection instead of

taplink and enables the remote clock for the connection
speed.
The JTAG signal is set to ARM like pinout.
The option NO_TAP_CTRL must not be used in
conjunction with this option. For this option, CLOCK_D
has no meaning.
JTAG_REMOTE_CLOCK(2)
The feature is available for the ST230EMU-PCI board
only and the option must be specified in the
corresponding alias within the target.cfg file. For
example:
mb388 st200emu HTI_ID tcp:xxx.yyy.zzz.kkk
CONFIG_FILE mb388 NO_CHIP_RESET
JTAG_REMOTE_CLOCK

NO_CHIP_RESET

This sets the mode where no physical reset is executed

during the board reset sequence performed at
connection time, load time or execution time. All of the
usual reset actions are done (for example, taplink reset
and memory initialization) except for the physical chip
reset.

NO_TAP_CTRL

This sets the mode where the tap controller is not used
to access taplink.
This option does not have to be used for ST220 cores
with taplink.

7521642

The CLOCK_D
option is used
to specify the
connection
speed.

23/170

Getting started
Table 3.

ST200
Silicon target configuration options (continued)
Option

OS21_OSCALL

24/170

Description

Default value

This option configures the oscall behavior versus the

execution of OS21 tasks.
By default, when OS21_OSCALL is not specified, any
oscall made inside a task locks the ST200 CPU until the
oscall emulation has been completed on the host
machine. When OS21_OSCALL option is set, the ST200
CPU is not locked (in fact, it is stalled for periods less
than 30 s) while the oscall emulation is being
performed, and high priority OS21 tasks can execute.
This option is typically useful when data streaming (for
example, file I/O) or trace display oscalls need to be
performed by the program while the program ensures
that high priority tasks remain executed with strong
timing constraints.
Using this option can lead to st200emu errors in the
following cases.
If the high priority tasks do not leave the CPU to the
task performing the oscall, after around 5 seconds the
oscall emulation issues a time-out error and the
program fails.
With st200gdb, breakpoints must not be used when
the OS21_OSCALL mode is activated on a board
target. This would break the synchronization between
the debugger and the program, and lead to
unpredictable connection loss. For this reason, it is
recommended to use the OS21_OSCALL mode only
with the st200run tool to execute the program.
The usage of this option is not compatible with the
usage of the CONF_DEBUG flags version of the
libos21.a library.

OS21 tasks are

locked while
executing
oscalls.

7521642

ST200

Getting started
Table 3.

Silicon target configuration options (continued)

Option

Description

Default value

PURE_JTAG(2)

This option specifies a pure jtag connection instead of

taplink. The feature is available for the ST230EMU-PCI
board only and the option must be specified in the
corresponding alias within the target.cfg file. For
example:
mb388 st200emu HTI_ID tcp:xxx.yyy.zzz.kkk
CONFIG_FILE mb388 NO_CHIP_RESET PURE_JTAG
The option NO_TAP_CTRL must not be used in
conjunction with this option.
The default frequency value is 16.7 MHz. Further
frequency values are available and can be set assigning
corresponding index to the CLOCK_D option:
1
"100 kHz"
2
"25 MHz"
Pure jtag
3
"16.7 MHz"
connection is
4
"12.5 MHz"
not enabled.
5
"3.125 MHz"
6
"6.25 MHz"
7
"10 MHz".
Indexes of 0 or greater than 8, default to 16.7 MHz.
Note that, when pure jtag is enabled, the CLOCK_D
option semantic changes. In this case, it is not used as
clock divider but rather reused to specify the pure jtag
connection frequency. Below is an example of CLOCK_D
usage.
mb388 st200emu HTI_ID tcp:xxx.yyy.zzz.kkk
CONFIG_FILE mb388 NO_CHIP_RESET PURE_JTAG
CLOCK_D=4
This performs a connection to an mb388 with a jtag link
at 12.5 MHz.

ST231_CUT6(2)

The new protocol for message in JTAG connection

available in ST231 cut 6 is enabled. This feature is only
available in a pure jtag connection. The feature is
available for the ST230EMU-PCI board only and the
option must be specified in the corresponding alias
within the target.cfg file. For example:
a) pure jtag with remote clock and ST231 cut 6 protocol:
mb388 st200emu HTI_ID tcp:xxx.yyy.zzz.kkk The ST231
CONFIG_FILE mb388 NO_CHIP_RESET
cut 5 protocol is
JTAG_REMOTE_CLOCK ST231_CUT6
used.
b) pure jtag with the frequency set using CLOCK_D
option and ST231 cut6 protocol:
mb388 st200emu HTI_ID tcp:xxx.yyy.zzz.kkk
CONFIG_FILE mb388 NO_CHIP_RESET PURE_JTAG
CLOCK_D=4 ST231_CUT6
(CLOCK_D=4 implies a jtag link at 12.5 MHz see the
PURE_JTAG description)

7521642

25/170

Getting started

ST200

Table 3.

Silicon target configuration options (continued)

Option

Description

Default value

VERBOSITY=n

Set verbosity to n for debug purposes.

VIRTUAL_DEBUG

This option configures the mode (physical or virtual) of

the address space seen by the debugger.
By default, when VIRTUAL_DEBUG is not specified, any
request sent by the debugger directly accesses the
physical address space.
When the VIRTUAL_DEBUG option is set, the debugger
accesses the virtual address space, as currently set in
the TLB by the program being debugged.
In most cases (and by default), the TLB is set so that
the addresses of the virtual space matches the
addresses of the physical space. This option is
therefore unnecessary.
As soon as the TLB is set with unmatching address
translation, this option is necessary to enable the
debugger to access correctly the objects mapped in
memory through their virtual address. This is the case
when the bare run-time service
bsp_mmu_memory_map() is used with unmatching
address and phaddr parameters, or when the OS21
run-time service mmap_create() is used instead of
mmap_create_identity().

The debugger
accesses the
physical
address space.

1. The ST Micro Connect (ST40-Connect).

2. These options are explained in more detail in Table 4.

Table 4.

JTAG connection options

JTAG

PURE_JTAG

JTAG_REMOTE_
X
CLOCK
ST231_CUT6

Note:

JTAG
signal

JTAG
signal

ST20

ARM

CLOCK_D
as index

Remote
clock

CLOCK_D
as divider

N-2
response

X
X

X
X

All the three options enable the pure jtag connection.

PURE_JTAG uses the JTAG signal st20 and CLOCK_D as an index to specify the frequency
of the connection.
JTAG_REMOTE_CLOCK uses the JTAG signal ARM pinout and enables the remote clock.
ST231_CUT6 enables the ST231 cut 6 protocol and has to be used in conjunction with one
of the previous two options.

26/170

7521642

ST200

1.7

Getting started

st200gdb debugger
The st200gdb debugger provided is an ST200 retargeting of the GNU gdb-6.4 standard
debugger which comes with a GUI. This gdb-6.4 is sometimes called Insight-6.4. Insight is
the name chosen by Red Hat for the software made from gdb plus the added GUI. Refer to
the standard GNU gdb documentation for information about the st200gdb features and
commands. Refer to the Insight home page (http://sources.redhat.com/insight) for additional
information about the GUI.
To launch an st200gdb session in the command line interface, type:
<tools-dir>/bin/st200gdb
The basic gdb commands to perform in command line mode in order to execute a program
are:
file <program_name>
target gdi -t <target_alias_name>
load
run
The file command is not required if <program_name> is specified on the st200gdb
launch line.
The target command connects to a target, either a simulator or a board.
The load command can be omitted if the application is already loaded in memory. In this
case, the pc value has to be initialized before running:
set $pc=__text_start
The load command can also be omitted if the application has been burnt in Flash and the
user wants to start the execution from the reset address located in Flash. In this case a
special debugging mode is required before running:
startmode -set reset
The run command starts the execution of the program.
While the target remains connected, it is possible to restart the execution of the program in
RAM, providing that the .data section has been reinitialized, for example by reloading it:
load
run
The ST200 specific features are described in the following sections.

Note:

The st200gdb debugger supports OS21 threads. If you are using the GUI (see Section 1.8
on page 35) the threads are listed in the Processes window.

7521642

27/170

Getting started

1.7.1

ST200

GDI target command option

The st200gdb target command supports the connection to the same targets as those
supported by the st200run tool. A target is selected using one of the following options:
target gdi -t <target>

where <target> is the same target alias used by

st200run and predefined in the target description file.
The st200gdb execution targets available (simulator or
evaluation board) are inherited from the same
configuration mechanism.

target gdi -t <target> -m <path>

where <target> is the same target alias used by
st200run and predefined in the target description file
and <path> is the location of the targets.cfg file.
The st200gdb execution targets available (simulator or
evaluation board) are inherited from the same
configuration mechanism.
target gdi -dll <string>

where <string> specifies the same GDI dynamic

target dll name and associated target options as used by
st200run.

The targets are defined in the targets.cfg file supplied with the standard toolset release.
The location of the target description file is determined in accordance with the strategy
defined in Search strategy for dynamic libraries on page 18.

1.7.2

GDI st200gdb commands

The st200gdb command language has commands to deal with the GDI target, at two levels.

At the first level, pure st200gdb commands allow access to generic GDI targets.

At the second level, a set of target specific commands are available as soon as the GDI
target has been connected. They are also called the GDI direct access commands.

The available commands are described in Table 5. Additional information is provided in the
online help available within st200gdb using the help st-gdi command.
Note:

All values (for example, address and length) can be an expression using the following
operators:
(, +, -, *, /, ~, &, | or a variable.
Table 5.

Target specific GDI direct commands

Command

Description

st200gdb commands

28/170

gdi

Execute one Direct DI Access command.

mcumap

Display or set the MCU memory mapping.

mcuname

Display or select the MCU name.

reset

Reset the debug instrument.

pmblock

Access the performance monitoring block.

7521642

ST200

Getting started
Table 5.

Target specific GDI direct commands (continued)

Command

Description

Simulator commands
gdi bus-trace-off

Turn off bus traffic tracing.

gdi bus-trace-on

Turn on bus traffic tracing.

gdi flush

Flush the trace output stream.

gdi get_config config_item

Give the value of a specified configuration item.

gdi help

Display the simulator direct command help.

gdi profile-off

Turn profiling off.

gdi profile-on

Turn profiling on.

gdi reset-statistics

Reset the simulator statistics counter to zero.

gdi set-bus-trace-file

Set the current bus tracing file.

gdi set-trace-file

Set the current tracing file.

gdi start-statistics

Start the simulator statistic counters.

gdi statistics

Output the current simulator statistics to screen.

gdi statistics > filename

Output the current simulator statistics to file.

gdi statistics >> filename

Append the current simulator statistics to file.

gdi stop-statistics

Stop the simulator statistic counters.

gdi trace-off

Turn tracing off.

gdi trace-on

Turn tracing on.

Board commands

gdi call address

Call any routine, while keeping the current DSU

context untouched.
It uses the DSU_CALL_OR_RETURN debug ROM
operation case where DSU_ARG1 is not 0, as
described in the ST2xx Core and Instruction Set
Architecture Manuals.
address is the start address of the routine to call.

gdi
gdi
gdi
gdi

The DBREAK_CONTROL registers determine the

comparison operations performed on the breakpoint
addresses.
If the comparison is true then a breakpoint
exception is signaled. For the data breakpoints, the
data effective address of loads and stores are used
for comparison.
Prefetches and purges do not trigger data
breakpoints.

dbreak
dbreak
dbreak
dbreak

either lower upper

in_range lower upper
masked lower upper
out_range lower upper

Read a number of DSU registers. reg is the first

register number to read.
If length is not specified, only one DSU register is
read.
If reg and length parameters are not specified, all
DSU registers are read.

gdi dpeek reg [length]

7521642

29/170

Getting started

ST200

Table 5.

Target specific GDI direct commands (continued)

Command

30/170

Description

gdi dpoke reg DATA [DATA ...]

Write 32-bit word values in consecutive DSU

registers.
reg is the first register number to write.
The number of DATA occurrences must not exceed
32.

gdi enable_mpoke addr

Enable the use of the downloaded monitor when the

DSR7 register is not set to 0 and save the DSU
area.
Disable the use of downloaded monitor when the
DSR7 register is set to 0 and restore the DSU area.

gdi fhalt

Force a target stop even if stopped.

gdi file filename

Execute a list of commands from filename.

gdi file_exit

Exit the current file and close it.

gdi flush low_address high_address

Flush an address range from data and instruction

caches using the DSU_FLUSH debug ROM
operation as described in the ST2xx Core and
Instruction Set Architecture Manuals.
low_address and high_address specify the
inclusive address range and must be aligned to
word addresses.

gdi halt

Send the unmaskable DSU debug interrupt and

trigger the DSU context save operation of the debug
ROM as described in the ST2xx Core and
Instruction Set Architecture Manuals.

gdi help

Display the board direct command help.

gdi
gdi
gdi
gdi

The IBREAK_CONTROLE registers determine the

comparison operations performed on the breakpoint
addresses.
If the comparison is true then a breakpoint
exception is signaled. For the instruction
breakpoints, the currently executing bundle address
(PC) is used for comparison.

ibreak
ibreak
ibreak
ibreak

either lower upper

in_range lower upper
masked lower upper
out_range lower upper

gdi id2key value

Get the key of the board from the identifier value.

gdi id2keyhigh value

Get the upper 32 bits of the 64-bit key of the board

from the identifier value found in the id2key.txt
file.

gdi id2keylow value

Get the lower 32 bits of the 64-bit key of the board

from the identifier value found in the id2key.txt
file.

gdi if exp
gdi command
gdi ....
[gdi else
gdi command
gdi ...]
gdi endif

The expression exp is evaluated. If it is not null, the

first commands group is executed. If the else
command exists and the expression is null, the
second commands group is executed.

7521642

ST200

Getting started
Table 5.

Target specific GDI direct commands (continued)

Command

Description

gdi jtag -get

Read the value on the jtag line.

gdi jtag -off

Set the jtag mode to OFF.

gdi jtag -on

Set the jtag mode to ON.

gdi jtag -set value

Write value to the jtag line.

gdi load filename [addr]

Load the ELF, DISM or BIN file filename, at the

address addr. If addr is not defined, the file is
loaded at 0x0.

gdi peek address [length]

Read 32-bit word values in the memory using

DSU_PEEK debug ROM operations as described in
the ST2xx Core and Instruction Set Architecture
Manuals.
The address is the start address and must be
aligned to word addresses. length is the number
of words.
The integer value reflects the current endianness of
the target for integer value management in memory.

gdi poke address value [value] ...

Write 32-bit word values in the memory using

DSU_POKE debug ROM operations as described in
the ST2xx Core and Instruction Set Architecture
Manuals.
The address parameter is the start address and
must be aligned to word addresses.
The first word value is written to the start address
and the following values are written to the following
word aligned addresses.

gdi print_verified

Display the current value of the error counter.

gdi reset_taplink
-nochipreset|-chipreset

Send the taplink reset sequence to the ST200 DSU

through the jtag link. The taplink reset sequence
may contain the tap controller initialization
sequence on behalf of the NO_TAP_CONTROL
st200emu option flag. During the taplink reset
sequence, a chip reset is sent (-chipreset) or not
(-nochipreset) to the chip through the NOT_RST
ST Micro Connect signal.
Note that the NO_CHIP_RESET st200emu option
flag is ignored.

gdi reset_verified

Reset the counter of verified errors to zero.

gdi restart

Restart the execution from the current DSU context.

It uses the DSU_CALL_RETURN debug ROM
operation case where DSI_ARG1 is 0, as described
in the ST2xx Core and Instruction Set Architecture
Manuals.

gdi rpeek [register]

Read one or all CPU registers. Where register is

the register name to read. If the register
parameter is not specified, all CPU registers are
read (register = (R0-R63,B0-B7,PC,PSW)).

7521642

31/170

Getting started

ST200

Table 5.

Target specific GDI direct commands (continued)

Command

Description

gdi rpoke register value

Write a CPU register. Where register is the

register name to write (register =
(R0-R63,B0-B7,PC,PSW)).

gdi set_timeout value

Set the timeout value (in seconds) for

communication between the host and the
STMicro Connect.

gdi sleep value

Sleep during the value milliseconds.

gdi verbose value

Execute STMicro Connect software in verbosity

mode.
value specifies the level (0 to 5).

gdi verify value

Verify the value versus the value reported by the

last executed command able to return a value and, if
they differ, display an error message on the output
and increment the verify error counter.

gdi version

Get version numbers of components allowing

access to silicon.

gdi
gdi
gdi
gdi

The expression exp is evaluated. If it is not null, all

commands are executed. The expression exp is
re-evaluated and while this expression is not null, all
commands are re-executed.

while exp
command
...
endwhile

gdi write "comment" [format data]

Write a comment only or write a comment with a

variable value.

var = value | result_of_command

Create a variable var and initialize it with value or

the result of a command returning a value.

# any_text

Echo the text as a comment.

The pmblock st200gdb command

The ST200 cores are equipped with a performance monitoring block. This block is capable
of recording core relevant events such as data cache hits, instruction cache hits and several
others (see the Core and Instruction Set Architecture manuals for reference and the
complete list). The pmblock command gives the user access to this block.
Usage
pmblock

32/170

-start
-stop
-reset
-setevent <counter_number> <event_type>
-setcounter <counter_number> <value>
-setclock <value>
-showcounter <counter_number>
-showclock
-show
-resetidle

7521642

ST200

Getting started
Basic parameters

1.7.3

-start

Starts the event counting. During the following execution, events are
counted.

-stop

Stops the event counting. During the following execution, events are
not counted.

-reset

Resets to zero all the event counters and the clock counter.

-setevent

Set the counter <counter_number> to count <event_type>

events.

-setcounter

Sets the counter <counter_number> to <value>.

-setclock

Sets the clock counter to <value> (available on ST231 onward

only).

-showcounter

Displays the <counter_number> value, that is, the number of

counted events.

-showclock

Displays the counted clock ticks.

-show

Displays the complete status of the performance monitoring block.

New startup configuration commands

The following new st200gdb commands dedicated to the run-time configuration have been
added, see Table 6.
Table 6.

Startup configuration commands

Command

Description

startramend

Display or set the startup location of the RAMEND.

startenv

Display or set the setting of the passing of host

environment variables.

startbss

Display or set the setting of the BSS clear variable.

These commands are equivalent respectively to the --ramend, --env and

--no_clear_bss st200run options.

startramend
Display or set the startup location of the RAMEND.
Note:

When using a simulator target, any changes made to the RAMEND must be matched by a
change to the configuration option EXTERNAL_MEMORY_SIZE, see Table 7: Target
configuration options on page 67. If the -reset option is used the -ramend option is
ignored.
Usage
startramend -show
-set <memory description>

7521642

33/170

Getting started

ST200

Basic parameters
-show

Displays the current value of the ramend address taken by a program

at startup. This is the default.

-set

Changes the RAMEND address to a new value.

startenv
Display or set whether host environment variables are passed.
Usage
startenv

-show
-set yes|no

Basic parameters
-show

Displays the current setting for whether the host environment

variables are passed to the program (yes or no).

-set

Changes the setting for whether the host environment variables are
passed to the program (yes or no).

startbss
Display or set the BSS clear variable.
Usage
startbss

-show
-set yes|no

Basic parameters

1.7.4

-show

Displays whether the .bss will be cleared (yes or no).

-set

Changes the setting of BSS clear variable (yes or no).

Emulated system calls

System calls such as printf and fprintf are supported for any st200gdb GDI targets in
a similar way to st200run. See Section 1.5 on page 13.

34/170

7521642

ST200

1.8

Getting started

Using the graphical user interface

The st200gdb debugger automatically starts in command line mode. If you want to use the
GUI, launch st200insight (or enter an additional -w option when you launch st200gdb).
To debug a file called hello.out in graphical mode, type:
<tools-dir>/bin/st200gdb -w hello.out
or
<tools-dir>/bin/st200insight hello.out

1.8.1

Running a simple debugging session

When st200gdb is started the main window is displayed, showing the source file containing
the main function of the program. The first step is to choose the execution target:
1.

Select Target Settings... from the File menu. The Selecting an ST2x0 Target window
is displayed, see Figure 3.
The ST2x0 Target list contains the set of execution targets found by the GUI in the
visible targets.cfg files. The targets.cfg files are searched for successively in:

the directory defined by the -mtargetdir option,

the directory <tools-dir>/target.

The target file defined by the -mtargetdir option could also be selected from the
GUI using the Browse button.
Note:

The search strategy for the target configuration file is shown in Search strategy for dynamic
libraries on page 18.
Figure 3.

Selecting an ST2x0 Target window

When a target is found more than once, the first definition is used. This allows you to
use overridden definitions for some targets. The origin of the used definition is shown
between parentheses in the list. See Section 1.6: Targets and target options on
page 19 for details.

7521642

35/170

Getting started

Note:

ST200

2.

Select the execution target to use and click on OK.

3.

Select Run (R) from the Run menu.

st200gdb connects to the execution target selected,

the program is downloaded to the target,

the program stops on the main breakpoint (unless the Set breakpoint at main
option is deselected in the target selection pane).

If the user runs an application without selecting the target, the Selecting an ST2x0 Target
window is displayed to let the user to choose the target.
Continue the debugging session using the st200gdb commands to which the GUI provides
access. Select Help Topics from the Help menu to access a basic online manual.

Note:

It is possible to enable or disable the printing of the string pointed by an address in the Local
Variables and Watch windows, by selecting the Print the string pointed by an address
box. For example, the address 0xFFFFFFFF cannot be dereferenced as it is out of memory
on ST200 cores. In this case, ensure the box is unchecked.

1.8.2

Accessing other st200gdb functions

Although the GUI encapsulates the most currently used st200gdb commands, it may be
necessary to send command lines directly to the underlying st200gdb, for example, to pass
arguments to the program. To do this:
1.

Select Target Settings from the File menu.

2.

Select the execution target to use and click on OK.

3.

Select Console from the View menu.

4.

Type the set args, st200gdb command. For example (on Windows):
set args D:\myhome\mydata.txt 43

Continue the debugging session using the st200gdb commands to which the GUI provides
access.
Note:

36/170

It is also possible to pass arguments to the program using the GUI. Enter the arguments in
the Parameters to the application field as shown in Figure 4.

7521642

ST200

Getting started

Figure 4.

Selecting an ST2x0 Target window, More options

1.8.3

Using the ST2x0 Statistics window

The GUI provides an ST2x0 Statistics window which displays the results of the gdi
statistics command. It is only useful when this command is available, for example with
the simulator target. The window is updated each time the state of the processor changes.
An example of the ST2x0 Statistics window is shown in Figure 5.
To display the ST2x0 Statistics window, do one of the following:

select ST2x0 Statistics from the View menu,

press Ctrl+I on the keyboard,

click on the

icon.

7521642

37/170

Getting started

ST200

Figure 5.

The ST2x0 Statistics window

The Start button calls the gdi start-statistics command. It starts the statistics
counters for the ST200 processor. By default, the counting is enabled.
The Stop button calls the gdi stop-statistics command. It stops the statistics
counters for the ST200 processor.
The Reset button calls the gdi reset-statistics command. It may typically be used
before executing a sequence of code in order to compute the statistics.

1.8.4

Using the Performance Monitoring window

The Performance Monitoring window gives access to all the features provided by the
ST200 cores performance monitoring block. The counter values are updated whenever their
values change, and it is possible to start and stop the event counting, to set the type of event
counted by the counters and their values. An example of the Performance Monitoring
window is shown in Figure 6.
To display the Performance Monitoring window, do one of the following:

38/170

select Performance Monitoring from the View menu,

press Ctrl+X on the keyboard,

click on the

icon.

7521642

ST200

Getting started
Figure 6.

The Performance Monitoring window

Any changes made in the editable fields become effective whenever the Apply button is
pushed. The buttons in the Switches area of the window are active immediately. The Start
button toggles to Stop when the counting of the events is enabled and vice versa.

1.8.5

Displaying multiple Memory windows

Multiple Memory windows can be simultaneously displayed by either:

clicking on the

selecting Memory from the View menu.

icon, or

7521642

39/170

Getting started

ST200

Figure 7.

Multiple memory windows

1.8.6

Watch and local variables window

The look and feel of the Watch and Local Variables windows were enhanced in Insight 6.1.
The following information is displayed for each item:
<item_name> = <type> <value> <string pointed by value as an address>

40/170

7521642

ST200

Getting started
Figure 8.

1.8.7

Watch window

Troubleshooting
Unexpected failure during a simulation
During a simulation session, in cases where the operating tool (st200gdb or st200run)
crashed, failed unexpectedly, or was killed by the user, a gdiserv process may remain
executing on the host machine. It is recommended that any remaining process is killed
before attempting to run a new tool session with the simulator.

st200gdb initialization file

Some user session parameters are kept by st200gdb across debugging sessions in an
initialization file called ~/.gdbtk200init on Solaris and Linux and ~/gdbtk200.ini on
Windows.
Occasionally, when the version of st200gdb is changed, there are problems with this file.
This can be avoided by deleting or renaming this file before changing the version.

st200gdb README file

Some of the known st200gdb limitations are documented in a file called README.GDBTK
that is found on the st200gdb source tree. It is recommended that this file is read for further
information about st200gdb.

7521642

41/170

Getting started

ST200

1.9

Configuring the program execution startup

1.9.1

Initialization sequence
After the program is loaded and before the program execution is started, a few core registers
and software parameters are expected to be initialized. They are passed as parameters of
the __start() entry point function. This configuration is done according to st200run
options or st200gdb commands and is described below.

Note:

In reset mode, these parameters take the value set up by the boot code, regardless of the
tool options.
After the program is started and before the main() function is called, the program executes
the internal real time run-time initialization.

Start parameters
int argc
char **argv
These are the arguments passed to the st200 program from the st200run command
line (st200run [OPTIONS]) or st200gdb commands (set args). The boot code
setup for these parameters is argc=0, argv=0.
char **env
This is the full system environment variable from the host machine, copied into the
ST200 program (st200run -env option, or st200gdb startenv command). The
boot code setup for this parameter is env=0.
char *ramend
This is an absolute address passed to the program, indicating the end of the RAM
(that is, the first non-RAM address) where some internal data and the stack pointer are
to be initialized. The default value is defined in the board.ld linker script dedicated to
the programs target and can be changed by modifying the DEFAULT_RAMEND_VALUE
in this file (recommended). It can be overridden by the user (st200run --ramend
option or st200gdb startramend command).
From this address, the stack grows toward the program text and data normally loaded
in LMI RAM. The boot code setup for this parameter is ramend=0x08800000.
char *noncacheable_start
This option is a boolean indicating to the run-time the way that the system calls
parameters have to be exchanged with the tool able to emulate the system calls.
If noncacheable_start equals 0, the tool emulating the oscall accesses the
parameters wherever they are provided by the run-time, this could be in ST200 internal
registers or data caches. The st200run and st200gdb tools are designed to work in
this mode by default. This is also the mode setup by default by the boot code.
If noncacheable_start does not equal 0, care is taken by the run-time to have all
the system call parameters accessible in external RAM by the tool able to emulate
system calls. Although this mode is not relevant for the st200run tool, the st200run
option --ignore_cache enables this mode to be setup for test purposes.

42/170

7521642

ST200

Getting started

Other core register initialization

The only core register expected to be initialized, in addition to the previously described start
parameters and the program counter, is the stack pointer. The stack pointer is an ABI
reserved core register, and is initialized by the st200run and st200gdb tools as described in
Section 1.4: Target address space usage on page 11. In reset mode, the stack pointer is
initialized by the boot code.

Internal C run-time initialization

At the execution of the __start() function, the following initialization is performed prior to
the BSP initialization:

the bss section is initialized to zero,

the kernel stack is set up.

The C run-time initialization sequence is located in the crti.o module linked with the
program.
The C run-time initialization invokes the BSP initialization (calling the three hooks
__init_core(), __init_board() and __init_soc()) before calling main().

Board Support Package initialization

The following default initialization is performed in __init_core() prior to calling main():

the ST200 exception handler is setup,

the hardware is initialized for clock function setting,

the memory protection units and dismissible loads behavior are set to a default value.

The setting for the memory protection unit is by default adjusted to your program needs.
This enables the use of the data cache for all memory access between __text_start and
_ramend, and prevents any dismissible load in the peripheral control register area.
The default initialization sequence is located in the libcore.a, libboard.a and
libsoc.a modules linked with the program, and source code for the initialization sequence
is visible in the following directories:
<tools-dir>/target/core/<st2xy>/src
<tools-dir>/target/board/<board>/src
<tools-dir>/target/soc/<soc>/src

1.9.2

Initialization hook
If, for some reason (for example, peripheral initialization or target environment setup), it is
necessary to change the behavior of the init sequence before main(), the recommended
method is to use the hook mechanism put in place in the startup phase of the run-time.
Two types of hooks are available for the user in the run-time to enable user initialization of
hardware or software before executing the main program.
The bsp_user_start_handle() and bsp_user_end_handle() are invoked from the
libcore.a library in the BSP initialization respectively at the start and the end of the BSP
initialization (see Appendix A: ST200 board support package (BSP) on page 114).
The __init_soc() and __init_board() functions are located in the libsoc.a and
libboard.a libraries respectively.

7521642

43/170

Getting started

1.10

ST200

Configuring the run-time and boot code for a target

The configuration of a target is done at three levels.
Core level

This level must contain all the settings which are related to a core
and independent of either the SoC in which the core is embedded, or
the board on which the SoC is used.

SoC level

This level is related to all the settings necessary for a given SoC
independent of any board.

Board level

This level covers all the settings needed to configure a given board
independent of the core or the SoC.

To configure the execution of the user program to be specific for the board target, the
run-time must be aware of the sysconf parameters. These parameters are hardware
parameters (such as the core and bus clock frequency) which, together with the handling of
their access, are found in the sysconf.c module.
By default, the sysconf module linked with the application fits the needs of all simulator
targets. This means that for hardware boards, a dedicated sysconf module specific to
each board must override the default sysconf.
It is exactly the same for the boot code. By default, a boot program is linked with the
application, however, it can be overridden with a boot program dedicated to a given target
board, see Section 1.11.
Caution:

A correct run-time configuration is required to get valid results on the time functions such as
clock(), and for benchmarking purposes.

1.10.1

The sysconf and boot code modules

A set of sysconf and boot code modules are delivered in the toolset. They are located in the
<tools-dir>/target/board directory. Within the board directory there is one
subdirectory for each board.
src/boot.S

The source of the boot section corresponding to a dedicated target.

By default, the boot code provided initializes the minimal board
settings for enabling access to RAM, if necessary. It then sets the
startup parameters to their default values for boot and jumps to the
start of the C program, which is assumed to be loaded in memory.

src/sysconf.c

The module managing sysconf parameters for the corresponding

board.

board.ld

The board-specific linker directives, including memory map

definition. Mapping information is used by the emulator DLL. It helps
to check that a loaded program fits within board memory.

board.txt

The file containing early initialization code (memory, control registers

or peripheral clocks) typically through a sequence of poke or peek
commands. These are the minimal expected actions required to
enable the ST200 core to access the RAM memory area.
This file is used exclusively by the st200run and st200gdb tools for
connecting a board target. It contains commands that replaces some
configuration actions normally done by the boot code.

makefile

44/170

The makefile to rebuild bootboard.o and libboard.a.

7521642

ST200

Getting started
A template directory within the board directory contains a template for sysconf.c and
boot.S in order to demonstrate where code should be added in order to create a new
target board that will be supported in the toolset.
The sysconf parameters can be accessed directly from a user program. For example:
#include <stdio.h>
#include <machine/sysconf.h>
main()
{
unsigned int fclock,pclock,ramsize,rambase;
fclock = sysconf(_SC_LX_CORE_CLOCK_FREQ);
pclock = sysconf(_SC_LX_PERIPH_CLOCK_FREQ);
ramsize = sysconf(_SC_LX_RAMSIZE);
rambase = sysconf(_SC_LX_RAMBASE);
printf("cpu clock %dMhz periph clock %dMhz ramsize 0x%8.8x
rambase 0x%8.8\n", clock/1000000, pclock/1000000, ramsize,
rambase);
}

1.10.2

Generating code for a board target

To target an application for a given board, a specific option must be given at link time when
generating the application.
The -mcore=<core_target> allows the selection of a core target. This option
automatically adds the bootcore.o and libcore.a files located in the
target/core/<core_target>/<endianness>/<run-time> directory to the list of
object files to link together and automatically selects the core-specific core.ld linker file.
When the -mcore option is missing, the driver assumes st220 settings.
The -msoc=<soc_target> allows the selection of a SoC target. This option automatically
adds the bootsoc.o and libsoc.a files located in the
target/soc/<soc_target>/<my_core>/<endianness>/<run-time> directory to
the list of object files to link together and automatically selects the core-specific soc.ld
linker file. When the -msoc option is missing, the driver assumes default settings.
The -mboard=<board_target> allows the selection of a board target. This option
automatically adds the bootboard.o and libboard.a files located in the
target/board/<board_target>/<my_core>/<endianness>/<run-time>
directory to the list of object files to link together, and automatically selects the
board-specific board.ld linker file. When the -mboard option is missing, the driver
assumes default settings.
The default [core, soc, board, endianness] combination chosen by the toolset
corresponds to [st220, stm8000, sim220, LE].
When the linker is invoked, the selected core.ld, soc.ld and board.ld, are
automatically combined through a general platform.ld file to provide an entire and
consistent linker script.
For example, the command:
<tools-dir>/bin/st200cc -o hello -mboard=mb379_audioenc hello.c
is equivalent to:

7521642

45/170

Getting started

ST200

<tools-dir>/bin/st200cc -o hello \
-EL \
-nostdlib \
-Wl,-L<tools-dir>/target/core/st220/le/bare \
-Wl,-L<tools-dir>/target/soc/default/st220/le/bare \
-Wl,-L<tools-dir>/target/board/mb379_audioenc/st220/le/bare \
-Wl,-L<tools-dir>/lib/st220/le/bare \
<tools-dir>/lib/st220/le/bare/crt1.o \
<tools-dir>/lib/st220/le/bare/crti.o \
<tools-dir>/lib/st220/le/bare/crtbegin.o \
<tools-dir>/target/core/st220/le/bare/bootcore.o \
<tools-dir>/target/soc/default/st220/le/bare/bootsoc.o \
<tools-dir>/target/board/mb379_audioenc/st220/le/bare/bootboard.o \
-I<tools-dir>/target/core/st220 \
-I<tools-dir>/target/soc/default \
-I<tools-dir>/target/board/mb379_audioenc hello.c \
-lcore -lsoc -lboard \
-lc -lgloss -lgcc \
<tools-dir>/lib/st220/le/bare/crtend.o \
<tools-dir>/lib/st220/le/bare/crtn.o \
-T <tools-dir>/target/platform.ld

1.11

Using a custom board target

1.11.1

Defining a custom board target and compiling a program

By default the libboard.a, bootboard.o and board.ld files are taken from the
<tools-dir>/target/board/default/<my_board> directory. During a toolset
update the entire <tools-dir>/target directory is overwritten and so any changes that
have been made in this location are lost. Target dependent libraries and boot settings as
well as memory and run-time settings in the board.ld file are no longer available.
To define your own board target and to keep the changes during an update, create a new
target directory (for example, <new_target_dir>) containing a board directory with a
subdirectory for each of your board targets (for example, <my_board>). Recursively copy
the files from the <tools-dir>/target/board/template directory to the newly
created subdirectory. An existing board directory can be used instead of the template
directory.

Note:

Normally the <new_target_dir> directory will be overwritten during a toolset update. To

avoid this, create it outside the <tools-dir> directory.
Modify the mapping settings in board.ld. In board.txt, adjust the memory initialization
for hardware targets (mandatory at ST200 program execution time). The board.ld and
board.txt files are located in <new_target_dir>/board/<my_board>.
Once the boot.S and sysconf.c files have been updated with the board-specific code,
the boot object files can be generated by typing make (beware that the <tools-dir> path
in makefile must have been updated).

46/170

7521642

ST200

Getting started
Assuming that an ST220 core is on <my_board>, the application can then be built from the
boot code object file with the following command:
<tools-dir>/bin/st200cc -mtargetdir=<new_target_dir> -EL
-mcore=st220 -msoc=default -mboard=my_board -o hello hello.c
For ST200 environments where the reset address is not 0, it is possible to ensure that the
boot section is linked at a new address in the program, using the linker RESET_ADDRESS
variable by modifying board.ld and editing the DEFAULT_RESET_ADDRESS value.
Memory map settings and some run-time settings such as DEFAULT_RAMEND or
DEFAULT_TEXT_BASE can also be modified in board.ld (see Section 4.3: Supported
configurations on page 81).

1.11.2

Debug a program on a custom hardware board target

For a simulated target, a generated program can be executed without having to carry out
additional steps.
For a hardware board, define the new custom board <my_board> (see Section 1.11.1),
create the targets.cfg file in your target directory <my_target> and add the definition
of the alias of <my_board>:
my_board_alias st200emu HTI_ID tcp:<IP_address> BOARD my_board
CPU_RESET_ADDRESS=<cpu_reset_addr_of_the_board>
Where, for example, <valid_ram_area_address> = 0x08000000.
The targets.cfg file now contains the required alias and the board/<my_board>
directory where the mapping information is stored. Therefore, the application for the custom
board is ready to be executed:
<tools-dir>/bin/st200run -v -tmy_board_alias -mmy_target hello

1.12

Modifying the memory protection settings

It is possible to override the default setting of the memory protection, so that it is set before
the main() function execution, using the startup initialization hook mechanism described in
Section 1.9.2 on page 43.
In order to check or modify the memory protection setting, the default setting is given in
<tools-dir>/target/core/<core>/src/mmu.c for ST231 core and
<tools-dir>/target/core/<core>/src/xpu.c for ST220 core (function
bsp_memory_init()).
On the ST220 core, the memory protection setting is implemented using the IPU-DPU
described in the ST220 Core and Instruction Set Architecture Manual.
On the ST231 core, the memory protection setting is implemented using the new memory
translation and protection unit described in the ST231 Core and Instruction Set Architecture
Manual.
The memory protection settings for the ST231 are more complex than for the ST220. Two
bare run-time functions, bsp_mmu_memory_map() and bsp_mmu_memory_unmap(),
have been added to simplify the user settings (see Section A.12: BSP function definitions on
page 131).

7521642

47/170

Getting started
Note:

ST200

The default memory protection unit settings differ between ST220 and ST231 onward. For
ST220, all the address space is accessible for data read or write access in supervisor mode.
For ST231 onward, an explicit mapping is required of any address area unknown to the core
and outside the program RAM usage (from __text_start to _ramend). For example,
before accessing the 0x08900000 device address, use the following C code:
int * device_control = 0x08900000;
#if defined (__ST220__)
/* nothing to do */
#else
#include <machine/mmu.h>
bsp_mmu_memory_map(0x08900000, 0x100,
PROT_SUPERVISOR_WRITE|PROT_SUPERVISOR_READ, 0,
0x08900000);
#endif
*device_control = 0 ;

1.13

Rebuilding the run-time libraries and target modules

It may be useful to rebuild the run-time libraries and target modules delivered in the toolset.
For example:

for debug purpose to be able to use st200gdb at source level inside the libc.a to
chase a problem inside a libc call,

for reverse engineering purposes, to follow step by step with st200gdb at source level,
the code that is executed from the entry point until the main() call,

for very advanced users that want to improve or implement new run-time features.

There are three kinds of run-time libraries and target modules, each having their own rebuild
methodology.

1.13.1

Rebuilding the target BSP tree

The target BSP tree covers all the libraries, modules and sources which are located in the
target directory of the toolset installation. They are located in three subdirectories, core,
soc and board. These libraries and modules contain code executed at startup (described
in Section 1.9: Configuring the program execution startup on page 42) and, in addition, the
core subdirectory contains the implementation of the BSP services (described in Appendix
A: ST200 board support package (BSP) on page 114).
Any part of the target BSP tree can be rebuilt from the makefile files located under each
core, soc or board subdirectory.
Modifying the installed toolset is not recommended, therefore a safe way to operate is to
create a new target directory with just a copy of the core, board or SoC to be rebuilt. The
rebuild is carried out under each core, board or soc directory using the command gmake.
In order to link an application with the new libraries and modules, the st200cc option
-mtargetdir should be used to select the new target directory as follows:
st200cc -mtargetdir=<location_of_the_rebuilt_target_tree>
-mcore=<core_name> -mboard=<board_name> -soc=<soc_name>

48/170

7521642

ST200

1.13.2

Getting started

Rebuilding the lib tree

The lib tree under the lib directory of the toolset installation contains the main C run-time
libraries (libc.a, libm.a, libgloss.a) and the C start modules (crtxxx.o). All the
sources corresponding to the lib tree are located in the <tools-dir>/src/newlib
directory except for:

libos21 libraries, for which rebuild is described in the Section 1.13.3,

libgprof, libgcc and libst200-instrC compiler libraries for which rebuild is not
relevant (mainly assembly code),

libstdc++.a libraries, for which rebuild is too complex to be provided.

In order to rebuild the lib tree, the <tools-dir>/src/newlib/HOWTO_BUILD file

describes the operations in detail.
Similarly to the target BSP tree, an st200cc option, -mlibdir, enables an alternate lib tree
to be selected in order to link any application with the new library and modules without
modifying the toolset.

1.13.3

Rebuilding the OS21 libraries

The OS21 libraries are split into the libos21 main OS21 libraries, installed under the lib
directory of the toolset installation, and the board specific OS21 libraries, merged into the
libboard libraries under the <tools-dir>/target/board directory of the toolset
installation.
The sources for rebuilding the OS21 libraries are located in the <tools-dir>/src/os21
directory.
All the rebuild and installation operation are explained in the
<tools-dir>/src/os21/README file.

7521642

49/170

The STWorkbench and related plug-ins

ST200

The STWorkbench and related plug-ins

This chapter describes how to install and use the STWorkbench Integrated Development
Environment (IDE) for the ST200 family of processors.
The STWorkbench is built on the Eclipse IDE. The Eclipse development environment and all
the related information are available at the Eclipse website http://www.eclipse.org.
The following sections also describe two plug-ins used with the STWorkbench for the ST200
toolset:

2.1

ST200 plug-in,

Visual Prof.

STWorkbench installation
The instructions for installing STWorkbench, the ST200 Eclipse plug-in and the Visual Prof
plug-in can be found in the HTML introduction pages (index.htm) of the STWorkbench
installation CD.

2.1.1

Documentation
The STWorkbench installation CD includes several documents.

2.2

The STWorkbench User Manual. This is available online, it is accessible from the Help
drop down menu by selecting Help Contents and then STWorkbench Help.

The Eclipse Workbench user manual is the file

org.eclipse.platform.doc.user_x.y.z.pdf, located in the doc directory.

The CDT user manual is the file

C_C++_Development_toolkit_User_Guide.pdf, located in the doc directory.

The CDT FAQ is provided in html format in the file cdt_faq.html located in the doc
directory.

ST200 plug-in documentation is available online. It is accessible from the Help drop
down menu by selecting Help Contents and then ST200 Embedded Toolset.

Visual Prof documentation is available online. It is accessible from the Help drop down
menu by selecting Help Contents and then ST Profiling and Coverage.

Getting started with STWorkbench

To start STWorkbench, run the stworkbench executable (on Linux and Solaris) or
stworkbench.exe (on Windows).
A clickable desktop icon can be created in Windows by right-clicking the desktop, selecting
New > Shortcut and browsing for the stworkbench.exe executable as the shortcut
target.
STWorkbench should be launched with the -clean command option whenever the plug-ins
for ST200 have been (re)installed. This guarantees their correct behavior. In Windows, this
is done by executing stworkbench.exe -clean in a command prompt window.

50/170

7521642

ST200

The STWorkbench and related plug-ins

When STWorkbench is launched, the Workspace Launcher dialog is displayed (see
Figure 9). Use this dialog to enter or select the location of the workspace. The workspace is
the directory where the project data, files and directories are stored.
Figure 9.

Workspace Launcher

After choosing the workspace location, a single Workbench window is displayed. A

Workbench window offers one or more perspectives. A perspective contains editors and
views, such as the Navigator. Multiple Workbench windows can be opened simultaneously.
Initially, in the first Workbench window that is opened, the Resource perspective is
displayed, with only the Welcome view visible.
Close the Welcome view by clicking on the x symbol as shown in Figure 10. You can return
to the Welcome view at any time by selecting Help | Welcome.
Before continuing the tutorial, it is important to become familiar with the various elements of
the workbench. A workbench consists of:

perspectives,

views,

editors.

A perspective is a group of views and editors in the Workbench window. One or more
perspectives can exist in a single workbench window. Each perspective contains one or
more views and editors. Within a window, each perspective may have a different set of views
but all perspectives share the same set of editors.
A view is a visual component within the workbench. It is typically used to navigate through a
hierarchy of information (such as the resources in the workbench), open an editor, or display
properties for the active editor. Modifications made in a view are saved immediately.
Normally, only one instance of a particular type of view may exist within a Workbench
window.
The title bar of the Workbench window indicates which perspective is active. In Figure 10,
the Resource perspective is in use.

7521642

51/170

The STWorkbench and related plug-ins

ST200

Figure 10. Welcome view

2.2.1

Configuring STWorkbench to work with the ST200 toolset

Use the ST200 Preferences section of the Preferences dialog to configure the ST200
specific preferences for STWorkbench. To access this dialog, select Preferences from the
Windows menu. The options available in this section are described in Section 2.3.1: ST200
preferences on page 55.

52/170

7521642

ST200

2.2.2

The STWorkbench and related plug-ins

Creating and building a Hello World project

1.

Right-click in the Navigator view and select New | Project. The New Project dialog is
displayed.

2.

Select C | Managed Make C and click on Next.

3.

Enter hello as the Project name.

4.

Select the ST200 executable type and click on Next.

5.

Click on Finish.
Because you have just created a C project, the workbench prompts you to switch to the
C/C++ Perspective. Click on Yes.
The hello project is now visible as a folder in the Navigator view.

6.
7.

Right-click on the hello folder and select New | C source file.

Enter hello.c in the Source File field and click on Finish.
The Workbench has an editor capable of editing C files. The editor is automatically
opened with the newly created hello.c file.

8.

In the hello.c editor, enter the following:

#include <stdio.h>
int main()
{
printf("Hello World!\n");
return(0);
}
Notice that the editor displays an asterisk (*) next to the filename to indicate that the
editor has unsaved changes.

9.

Click on the Save button to save the changes.

STWorkbench saves the source file and automatically builds the hello.out
executable for the sim220 simulator (the default target).

The build of the first application for ST200 is complete.

2.2.3

Debugging Hello World

The first time an application is debugged, a debug launch configuration must be created.
1.

Click on the drop-down menu of the Debug icon (symbolized by a bug) and select
Debug. The Debug dialog box is displayed.

2.

Select the C/C++ Local Application configuration.

3.

Click on New.

4.

In the Main tab, select hello.out as the C/C++ Application.

hello.out is displayed in the Debug subfolder of the hello project.

5.

Click on the Debugger tab.

6.

Select ST200 GDB Debugger in the Debugger field.

7.

Enter sim220 in the ST200 GDB Target field.

8.

Click on the Debug button and click on Yes when asked whether to switch to the
Debug perspective.

7521642

53/170

The STWorkbench and related plug-ins

ST200

The Debug perspective (shown in Figure 11) manages debugging or running an application
in the workbench. The execution of the application can be controlled by setting breakpoints,
suspending launched programs, stepping through code and examining the contents of
variables.
The Debug perspective also drives the editor. As an application is stepped through, the
editor highlights the location of the execution pointer.
Figure 11. Debug perspective

54/170

7521642

ST200

2.3

The STWorkbench and related plug-ins

STWorkbench customizations for ST200

This section describes the customizations added to STWorkbench specifically for building
ST200 applications and libraries. It highlights the features that have characteristics specific
to development for ST200 platforms. Refer to the STWorkbench documentation in the doc
directory of the STWorkbench installation CD and to the complete Eclipse documentation
which can be found at http://www.eclipse.org.

2.3.1

ST200 preferences
ST200 preferences are set in the ST200 Preferences section of the Preferences dialog,
see Figure 12. To display this dialog, select Preferences from the Windows menu.
Figure 12. Preferences dialog - ST200 Preferences

Use the ST200 toolchain root path field to enter or browse for the location of the ST200
toolset.
Selecting the Target description file path sets the default path in which STWorkbench
searches for the targets.cfg target description file. This gives STWorkbench a default
location to propose to the user whenever a new run or debug configuration is created. A
specific location can subsequently be chosen in the run or debug configurations.
Check the Do not use --mtargetdir for st200run/st200gdb check box if the ST200 toolset
does not have the --mtargetdir command switch implemented in the st200run and the
st200gdb tools.

7521642

55/170

The STWorkbench and related plug-ins

2.3.2

ST200

ST Profiler preferences
ST Profiler preferences are set in the ST Profiler preferences section of the Preferences
dialog, see Figure 13. To display this dialog, select Preferences from the Windows menu.
Figure 13. Preferences dialog - ST Profiler preferences

From this section, the user can set the progress bar features.

2.3.3

Creating a new project

To create a new project, right click in the Navigator view of the Workbench. For ST200, it is
recommended that when creating a new project, only the following options are used:

Note:

Managed Make C project,

Managed Make C++ project.

When creating a new project, the Next button must be clicked at every step after entering
the project name, otherwise STWorkbench creates a project for the native system instead of
ST200.
The project type must be an ST200 project type, the project types on which the new project
is being created are specified at the last step of the new project creation. The available
project types are ST200 embedded executable, static library and shared library.
Once a project has been created, its source files can be created using the Project button.
To import a tree of source files, select File System. The next stages allow you to select the
file extensions and choose each file in a subdirectory.

2.3.4

Library names
If the project is for an ST200 library, do not use the prefix lib in the project name.
STWorkbench adds a lib prefix to the library filename, also adding a .a suffix in the
traditional POSIX fashion. For example, if the project library name is trig, the output file
created by STWorkbench is libtrig.a.

56/170

7521642

ST200

2.3.5

The STWorkbench and related plug-ins

Project properties
The project properties can be customized and modified in the Properties window. To
display this window, right-click on the project icon in the Navigator view of the Workbench
and select Properties.
Figure 14. Properties window

The C/C++ Build properties are the most important project properties. Different
configurations can be created for Release and Debug.
The Tool Settings tab sets all the switches and commands passed to the ST200 tools,
including:

the compiler,

the assembler,

the linker or the archiver (which appear respectively if the target of the project is an
executable or a library),

the shared options, for consistency, the options passed to the linker are also passed to
every call to the compiler.

The ST200 Shared Options section selects the run-time model (bare mode or OS21) for
the output file to be built.

7521642

57/170

The STWorkbench and related plug-ins

ST200

The Libraries field of the ST200 Linker section is very important. The name of the library to
be linked must be put in the -l space (related to the -l option of the ST200 linker) by entering
only the name of the library in the usual POSIX mode. For example, if the desired library to
be linked in the project is libfoo.a, the name of the library entered in the library name list
should be foo, without the lib prefix, and without the .a extension. Unfortunately
STWorkbench does not handle this well, the file search window does not strip the prefix and
suffix after the file choice. Conversely, the -L switch, which adds a path to the list of paths
searched by the linker for libraries, works as expected, adding the path chosen through the
popup window.
In the Build Settings tab, the name of the output file to be produced can be selected. For
executables, any name and extension can be used. For libraries, the lib prefix is
prepended by STWorkbench whatever name is entered. This is for consistency with the
traditional libmyname.a UNIX naming pattern.
In the Build Step tab, the pre-build and post-build commands can be set.
In the Environment tab, user variables and view system variables can be created, edited
and deleted.
In the Macros tab, user macros and view system macros can be created, edited and
deleted.

2.3.6

Building, cleaning, rebuilding

After the build settings have been applied, STWorkbench starts the build. If no source files
have been added to the project, this has no effect. To add source files to the projects, right
click the project icon and choose the relevant option using the New submenu. The Project
menu provides options to clean the project, to rebuild the project after cleaning and so on.

2.3.7

Running a program
To run a program, select Run... from the Run button drop down menu. The Run dialog is
displayed (see Figure 15). Use this dialog to create a new ST200 Run C/C++ Local
Application by right clicking the corresponding line in the Configurations area.
Three tabs control the execution of the Run configuration.
Main

Select the project and the corresponding executables.

Arguments

Enter the arguments to the ST200 application.

ST200 Run

Enter or select the options to passed to st200run.

When these three tabs have been correctly configured, clicking the Run button starts the
execution of the application. The Console tab can be used to interact with the application.

58/170

7521642

ST200

The STWorkbench and related plug-ins

Figure 15. Run dialog - ST200 Run

2.3.8

Analyzing a program
The Visual Prof plug-in can be used to analyze a program. The features of the Visual Prof
plug-in can be accessed by selecting Run... from the Run button drop down menu. The Run
dialog is displayed (see Figure 16).
Figure 16. Run dialog - ST200 Analysis

7521642

59/170

The STWorkbench and related plug-ins

ST200

The ST200 Analysis configuration allows the user to select in which way the application
must be profiled.
There are two possible choices:

Application Analysis

STgprof is a performance evaluation tool based on the GNU gprof tool. It

provides profiling results integrated into the Eclipse workbench.

STgcov is a refined test coverage program based on the GNU gcov tool. It
provides profiling results integrated into the Eclipse workbench. STgcov explores
a programs test coverage data to provide performance statistics for software
developers.

OS Analysis

Note:

OS21Profiler analysis shows the time a program spent executing each function,
task and interrupt level.

STgprof and OS21Profiler analysis are mutually exclusive. These analysis cannot be
performed together.
To enable the analysis process we have to provide at least one gmon file.
A gmon file is the result of a previously profiled application. To be profiled, an application
must be compiled with the -pg switch and, if the debug information is also required, the -g
switch must also be used.
The result of this stage is a directory located under the analysis directory with the
following template: yy_mm_dd__xxhxxmxxsxxx.
This directory contains the text document AnalysisInfo.txt, and a series of fxml files
which are representations of the flat profile, the function call graph, the function
statistics and so on.
An example of a flat profile diagram is shown in Figure 17.

60/170

7521642

ST200

The STWorkbench and related plug-ins

Figure 17. Flat profiling

The same results displayed as a pie chart as shown in Figure 18.

7521642

61/170

The STWorkbench and related plug-ins

ST200

Figure 18. Flat profiling pie chart

For more detailed information, please, refer to the online Visual Prof documentation.

62/170

7521642

ST200

2.3.9

The STWorkbench and related plug-ins

Running and analyzing a program

This section combines the features described in the two previous sections. The application
involved in this process is both profiled and run.
Figure 19. Flat profiling pie chart

At this point, it is not necessary to explicitly set a gmon file, but the user can set a Source
Lookup Path.
The profiling process is the same as the one described in Section 2.3.8 on page 59.

7521642

63/170

The STWorkbench and related plug-ins

2.3.10

ST200

Debugging a program
To debug a program, select Debug... from the Debug button drop down menu. The Debug
dialog is displayed (see Figure 20). Use this dialog to create a new ST200 Debug C/C++
Local Application by right clicking the corresponding line in the Configurations area.
Figure 20. Debug dialog

Five tabs control the execution of the Debug configuration.

Main

Select the project and the corresponding executables.

Arguments

Enter the arguments to the ST200 application.

Source

Select the source code locations.

Debugger

Select the arguments to pass to the st200gdb debugger.

Common

The default settings in this tab should be used.

When these tabs have been correctly configured, click on the Run button to start debugging
the application. The Console view can be used to interact with the application. If the Debug
perspective is not already set, a message is displayed asking whether it should be used.
Click on Yes to continue.
It is important to choose a target alias coherent with the application to be debugged.
Figure 21 displays the STWorkbench GUI in a debug perspective.

64/170

7521642

ST200

The STWorkbench and related plug-ins

Figure 21. STWorkbench in debug perspective

During debugging, the tabs in the Window | Show view subpanel contain the following
information:
Breakpoints

Add and remove breakpoints.

Console

Open and close the program console.

Expressions

Display the content of expressions and variables.

Disassembly

Step through the assembly code.

Error log

Display errors during debugging.

Memory

Display the target memory content during execution.

ST200 Performance Monitor

Access the ST200 performance monitoring features.
Tasks

Monitor the execution threads.

ST200 Statistics

Read the target executions statistics (only on simulation targets).

ST Profile

Access the file summary view.

STWorkbench

Access the Debug log.

Variables

Read the contents of variables.

A detailed description of the general debugging features available in STWorkbench is

provided in the STWorkbench documentation.

7521642

65/170

The STWorkbench and related plug-ins

2.3.11

ST200

Debugging tips
During a debugging session, the user might want to view the Performance Monitor window
or the Statistics window.
Each of these windows is supported by the GDB console that is accessible through the
Debugger Process item of the ST200 GDB Debugger session, as shown in Figure 22 by
the red ellipse.
There is another type of console, the applications output, that is accessible through the item
inside the blue ellipse.
The user can choose to view one of the mentioned consoles by clicking the Pin console
button, as shown in the green ellipse.
Figure 22. Debugging tips

66/170

7521642

ST200

ST200 simulator

ST200 simulator

3.1

Target configuration options

The complete list of simulator target options is given in Table 7. Information on targets and
using the target options is provided in Section 1.6: Targets and target options on page 19.
The first two target options are used to control the use of the configuration file itself.

Table 7.

Target configuration options

Option
CONFIG_FILE
<filename>

Description

Default value

Read options from the specified CONFIG_FILE (see

DUMP_CONFIG_FILE).

DUMP_CONFIG_FILE
Dump all user definable options to the specified file.
<filename>
MODE [FAST|ISS
|REFERENCE|REF]

The operation mode, the options are FAST, ISS and REFERENCE (or
REF). See Section 1.5 on page 13.

REFERENCE

ICACHE_MODEL
<string>

Valid values are:

NONE
BASIC
DETAILED
For a detailed description, see DCACHE_MODEL.

See Table 8 on
page 71

DCACHE_MODEL
<string>

Although the following explanation refers to DCACHE_MODEL values, it

applies to both data and instruction caches (see ICACHE_MODEL).
NONE indicates cache modelling is not required. In practice this
situation is modelled using a null cache that transmits requests
through to a simple bus model.
BASIC represents a more detailed model that takes account of the
cost of memory transactions via user-configurable latencies. When
basic cache models are specified for both instruction and data caches,
they act independently and do not accurately represent situations
where bus transactions would interact. It will also not model some
parts of the memory subsystem (for example, the write buffer and
See Table 8 on
prefetch buffer).
page 71
DETAILED incorporates a more accurate account of the interaction
between the caches and the bus. In particular, the data cache has an
added write-back buffer. Both caches compete for bus cycles via the
CMC (core memory controller), and the bus itself models the latency
associated with the bus and its attached devices.
Noncached reads and writes bypass the caching mechanism and
generate requests directly.
The CMC is responsible for arbitrating between reads and writes from
the data cache and reads from the instruction cache. This is done
according to a fixed priority scheme, therefore, data reads have
highest priority and data writes have lowest priority.

CORE_MHZ
<number>

Processor clock speed (in MHz).

BUS_MHZ <number> Bus clock speed (in MHz).

400
133

7521642

67/170

ST200 simulator
Table 7.

ST200

Target configuration options (continued)

Option

Description

Default value

MEMSYSTEM_
Internal latency of memory subsystem (in processor cycles).
LATENCY <number>

BUS_LATENCY
<number>

40

Intrinsic latency of the STBus (in bus cycles).

PERIPHERAL_
Memory latency for peripheral register accesses (in bus cycles).
LATENCY <number>

15

BUS_BYTES_PER_
CYCLE <number>

The number of bytes that can be transferred in one bus cycle.

8 bytes

TRANSACTION_
SETUP_CYCLES
<number>

The number of extra processor cycles required for each bus

transaction.

BUS_BYTES_PER_
TRANSACTION
<number>

The number of bytes that can be transferred in one bus transaction.

32

Size of external memory (in bytes).(1)

Beware that, by default, the toolset generates programs that use only
0x800000 bytes of memory size. To specify a larger or smaller
EXTERNAL_MEMORY_
memory usage for the program, either use the --ramend option of
SIZE <number>
st200run (see Table 1 on page 14) or adjust the board.ld parameter
and rebuild the program (see Section 1.11.1: Defining a custom board
target and compiling a program on page 46).

0x800000 for
ST220
0x4000000 for
ST231

EXTERNAL_MEMORY_
Byte address of the base of external memory.(1)
BASE <number>

0x8000000

EXTERNAL_MEMORY_ Size of external memory (in bytes).

SIZEx <number>
Where x is 1, 2 or 3.

0x0

EXTERNAL_MEMORY_ Byte address of the base of external memory.

BASEx <number>
Where x is 1, 2 or 3.

0x0

NONCACHEABLE_
MEM_SIZE
<number> (2)

The size (in bytes) of noncacheable memory. Buffers associated with a 0x4000
number of I/O related system calls are copied into this area.
(16 Kbytes)

KERNEL_STACK_
SIZE <number> (2)

Size of the kernel stack (in bytes)

BOOT_FROM_RESET
<bool> (2)

In a real operational context, the processor will typically execute some

sort of boot program before starting execution of an application code.
By loading bootcode into external memory and specifying the reset
address (see RESET_ADDRESS) the boot sequence can be exercised.
false
In the majority of cases, however, it is sufficient to begin executing
code at the applications start symbol after having placed the
simulator in a state that is equivalent to that achieved by the boot
program. This is the default behavior.

68/170

7521642

0x4000
(16 Kbytes)

ST200

ST200 simulator

Table 7.

Target configuration options (continued)

Option

Description

Default value

(2)

This option is only meaningful when BOOT_FROM_RESET is set to

true.
When BOOT_RTL is set to true, it has the effect of copying ST200
false
program arguments into a specific area of the memory map. The boot
code subsequently uses this to initialize registers (see Section 1.4:
Target address space usage on page 11).

RESET_ADDRESS
<number> (2)

This option is only meaningful when BOOT_FROM_RESET is set to

true.
This is the value of the program counter immediately after reset and
can equivalently be thought of as the entry point to the boot code.

RESET_DELAY_
CYCLES <number>

The number of processor cycles it takes to reset the core.

512

BOOT_ROM_BASE
<number>

Byte address of the base of the boot ROM.

0x0

BOOT_ROM_SIZE
<number>

Size of the boot ROM (in bytes).

0x10000
(64 Kbytes)

PERIPHERAL_BASE
<number>

The addresses of registers associated with the timer, interrupt

controller and DSU are defined relative to a peripheral base address.
The ST220 has a dedicated peripheral base register which is
initialized using this configuration item. All ST200 cores have a
dedicated control register.

0x1F000000

TRACING_ON
<bool>

This determines whether or not the simulator produces a code

execution trace. If set to true, the default operation is to output a
textual trace to stdout. An alternative location can be specified by
setting the OUTPUT_TRACE_FILE configuration item.

false

OUTPUT_TRACE_
FILE
<"filename">

This item only takes effect when TRACING_ON is set to true. Its effect
is to output the trace to the specified filename. If the string is empty or ""
the file cannot be opened, the trace is output to stdout.

TRACE_START_
CYCLE <number>

Cycle on which to start tracing.

TRACE_END_CYCLE
<number>

Cycle on which to end tracing.

BUS_TRAFFIC_
TRACING_ON
<bool>

Enables a textual trace describing all the traffic on the bus to be

output.

false

BUS_TRAFFIC_
OUTPUT_TRACE_
FILE
<"filename">

This item only takes effect when BUS_TRAFFIC_TRACING_ON is set

to true. Its effect is to output the trace to the specified filename. If the ""
string is empty the trace is output to stdout.

BUS_TRAFFIC_
TRACE_START_
CYCLE <number>

Cycle on which to start tracing the bus traffic.

BUS_TRAFFIC_
TRACE_END_CYCLE
<number>

Cycle on which to end tracing the bus traffic.

BOOT_RTL <bool>

7521642

69/170

ST200 simulator
Table 7.

ST200

Target configuration options (continued)

Option

OUTPUT_LOG_FILE
<"filename">

Description

Default value

By default, output from the simulator is recorded in a file in which the

last part of the filename is an incrementing integer (for example,
0042). The width of this numeric field is determined by the form of the
"simlog****"
filename. For example simlog**** results in a succession of
filenames: simlog0000, simlog0001, and so on. If the null string
("") is specified, output is to the console.

If hazard checking is switched on, the instruction stream is checked for

HAZARD_CHECKING_ violation of pipeline latency constraints during simulation.
false
ON <bool>
This is not guaranteed to detect all static hazards.
Setting this item to true enables the simulators bundle-checking
BUNDLE_CHECKING_
mode. This checks that each instruction bundle obeys the rules
ON <bool>
specified in the Core and Instruction Set Architecture manuals.

true

BUNDLE_CHECKING_ Setting this item to true prints an error message to the screen when
RE_ON <bool>
the simulators bundle-checking mode detects an illegal bundle.

false

PROFILING <bool>

When this is set to true the simulator produces the following

(gprof-style) output files(3):
gmon.out - standard execution profile
gmon.outDCACHE - time spent in each function waiting on Dcache
stalls
gmon.outICACHE - time spent in each function waiting on Icache
stalls

PROFILING_
OUTPUT_FILE
"filename"

By default, profiler information is recorded in a file in which the last part

of the filename is an incrementing integer (for example, 0042). The
width of this numeric field is determined by the form of the filename.
"gmon****"
For example gmon**** results in a succession of filenames:
gmon0000, gmon0001, and so on.

DEVICE_PLUGIN_
MODULES
<"filename">
[;"filename"]

Device plug-ins are used to simulate memory mapped devices on the

STBus
Multiple plug-ins can be specified by separating their names with a
semicolon (;).
For example:
st200run 220 DEVICE_PLUGIN_MODULES
c:\plugins\dev1.dll;c:\plugins\dev2.dll -- prog.exe
If an external SDI device also has memory-mapped registers, it can be
modelled by a single plug-in. This plug-in supports both SDI and
""
device plug-in interfaces and is specified against both the
SDI_PLUGIN_MODULE and DEVICE_PLUGIN_MODULES configuration
items.
The sample device plug-in is described in Section 3.2 on page 71. The
source of a sample device plug-in can be found in the standard
release under <tools-dir>/host/st200sim/
src/Plugins/SampleDevice.
Device plug-ins which simulate existing target boards are described in
Section 3.3: The ST200 simulator plug-ins on page 73.

DSU_DEFAULT_
MODULE_ENABLED
<bool>

By default, the debug support handler code is compiled into the

simulator. This option ensures that this code is loaded into memory at true
the beginning of a simulation.

70/170

7521642

false

ST200

ST200 simulator

Table 7.

Target configuration options (continued)

Option

Description

DSU_ROM_IMAGE
<"filename">

Default value

Allows the user to specify their own debug support code module, thus
""
overriding the default one.

STIMULATION_FILE
Path of pin stimulation data file.
<"filename">

""

EXTERNAL_MEMORY_ If set, this option initializes the whole of memory to the 4 byte pattern
PATTERN <number> specified.

0xBADDBABE

CLEAR_MEMORY
<bool>

If set to 1 (and EXTERNAL_MEMORY_PATTERN is set to zero) then

memory is cleared.

true

1. EXTERNAL_MEMORY_SIZE and EXTERNAL_MEMORY_BASE can be used to model additional blocks of memory if desired.
2. Note that the st200run and st200gdb tools are insensitive to these options. These options are only meaningful for
cosimulation environments.
3. The gmon format employs 16-bit numbers to represent time intervals. As this gives insufficient dynamic range for typical
simulations, time values have had to be scaled. In consequence, the column headers produced by gprof (specifying the
underlying unit of time) are incorrect. It is recommended that analysis of execution profiles is restricted to consideration of
relative times.
See the gprof documentation for information on the interpretation of the output files.

Table 8 shows the default values for the architecture dependent options.
Table 8.

Architecture-specific target options (cache models)

Default value

Target option
MODE FAST

MODE ISS

MODE REFERENCE/REF

ICACHE_MODEL

(see Note)

ICACHE_MODEL_BASIC

ICACHE_MODEL_DETAILED

DCACHE_MODEL

(see Note)

DCACHE_MODEL_BASIC

DCACHE_MODEL_DETAILED

Note:

The FAST mode of simulation does not model the caches but accesses the memory directly.
Nevertheless, if the configuration is dumped to file, the cache model options correspond to
those used in reference mode.

3.2

The sample device plug-in for the ST200 simulator

The source of the sample device plug-in is located in the standard release in the
<tools-dir>/host/st200sim/src/Plugins/SampleDevice subdirectory. The
following functions are defined in the SampleDevice.h header file and are used by the
simulator to communicate with the device plug-in.

DevInitialise
DEVICE_API void DevInitialise(
void *pinout,
void *pinoutStruct,
char *args)
This function is called at startup to allow the plug-in to initialize any state it holds. The
CPinout reference (pinout) should be stored so that the other API functions can use it
later. See Section 3.2.1: Callbacks into the simulator for an explanation of the parameters.

7521642

71/170

ST200 simulator

ST200

DevTerminate
DEVICE_API void DevTerminate()
This function is called at shutdown so that the plug-in can release any resources held.

DevClock
DEVICE_API void DevClock()
This function is called once per core clock cycle to allow the plug-in to account for time.

DevRead
DEVICE_API
unsigned
unsigned
unsigned

bool DevRead(
char *to,
int address,
int numBytes)

This function is called whenever a read is requested on the STBus. The plug-in returns
true if a read at the given address is handled. It returns false if it does not map the
address. If the plug-in decides to handle the request, it completes the to array with
numBytes of data. The data should be written in the endianness of the ST200 being
modelled.

DevWrite
DEVICE_API bool DevWrite(
const unsigned char *from,
unsigned int address,
unsigned int numBytes,
const char* byteEnables)
This function is called whenever a write is requested on the STBus. The plug-in returns
true if a write at the given address is handled. It returns false if it does not map the
address. If the plug-in handles the request, it reads numBytes of data from the from array
and deals with it appropriately. If byteEnables is not NULL, then it specifies which of the
numBytes are valid. The data is given in the endianness of the ST200 being modelled.

3.2.1

Callbacks into the simulator

The plug-in can make use of the CPinout object (in a C++ environment) or the SPinout
(in a C environment) object passed into the DevInitialise() function. These enable the
plug-in to have access to the internals of the core. Examples of how to use this functionality
can be found in the SampleDevice code. Details of CPinout and SPinout can be found in
Pinout.h and PinoutC.h respectively.

72/170

7521642

ST200

3.2.2

ST200 simulator

Building and running the plug-in

The sample plug-in shows how to use some of the functions defined in the
SampleDevice.h header file.
To build the sample:
On Windows:

Note:

Note:

nmake CONFIG=ReleaseLE -f MakefilePC.mak

The Windows version requires the Microsoft development environment for Windows.
On Solaris:

make CONFIG=ReleaseLE -f MakefileUnix.mak

On Linux:

make CONFIG=ReleaseLE -f MakefileLinux.mak

The Solaris and Linux versions require the GNU development environment for the host
platform.
LE should be substituted with BE to build a big-endian version. The .dll (or .so) is created
in the ReleaseLE directory.
In order to tell the simulator to use a specific device plug-in, specify a configuration item to
the simulator in the usual way (either on the command line or in a configuration file). The
ST231-EVAL board (mb424) plug-in sources provided with the toolset (see Section 3.3), can
be used as a starting point to customize the sample plug-in.

3.3

The ST200 simulator plug-ins

Based on the sample simulator plug-in described in Section 3.2 on page 71, a set of
plug-ins which mimic the behavior of several ST200 target boards is provided. These
plug-ins allow an application built for the corresponding hardware target (if no peripherals
other that clocks/PLLs are involved) to be run or debugged on the simulator without any
change.
All the plug-ins provided, except for the ST231-EVAL board (mb424) plug-in, are provided
only in binary format.
The ST231-EVAL board plug-in is also provided in source format under the path
<tools-dir>/host/st200sim/src/Plugins/MB424Device. This allows the
customer to understand how the clock and PLL registers of this system are simulated.
Companion target board lines are present in the targets.cfg file (described in
Section 1.6: Targets and target options on page 19) for each of the simulator plug-ins.
These target description lines also model the memory configurations of the simulated target
boards.

3.3.1

ST200 simulator plug-ins usage

For example, consider the <tools-dir>/samples/cpuclock sample application: the
executable cpuclock.out is built for the ST231-EVAL board (mb424) running:
make CORE=st231 SOC=sti5300 BOARD=mb424
and launched as follows:
st200run -t mb424 cpuclock.out
provided that the ST231-EVAL board target IP address has been correctly configured in the
targets.cfg file.

7521642

73/170

ST200 simulator

ST200

The same executable can be run on the simulation target mb424_sim_EXT (which uses the
ST231-EVAL board simulation plug-in), contained in the targets.cfg file, where:

EXT is chosen according to the host platform (see the comments in the targets.cfg
file),

the path containing the simulator plug-in is customized by the user according to the
<tools-dir> location in which the ST200 toolset has been installed.

To run the executable on the simulator, enter:

st200run -t mb424_sim_EXT cpuclock.out
The console output of the application is the same as when the executable is run on the
hardware target board.

74/170

7521642

ST200

Setting up a board

Setting up a board

4.1

Introduction to setting up a board

In the context of the ST200 cross development system, a board identifies a silicon target,
composed by one core processor on a specific SoC on a specific system board, and all the
resources assigned to it, including its assigned (by hardware or software design choices)
RAM address space and peripherals.
For example, the STm8010-Mboard (mb421) is based on one STx8010 SoC, which in turn
contains three ST231 cores and a complex set of on-chip peripherals. Therefore this system
board hosts three boards as intended in the ST200 cross development system terminology,
which are identified as: mb421_host, mb421_audio and mb421_video. The toolset
supports all of these boards.
This chapter describes how to perform the bring up of a new board for an ST200 family core.
It presents the contents of the toolset target dependent structure and how to configure it with
the -mcore, -msoc and -mboard toolset options.
It explains how to set up the environment and tools and provides a step by step explanation
of the procedure used, from carrying out the first DSU register accesses to the first
execution of a simple C program.

4.2

Understanding target dependent settings

The purpose of this section is to describe the target dependent contribution to the toolset,
that is, core, SoC and board contributions. The board/<my_board> directory contains the
majority of the target dependent information.
This section describes the parameters required when adding a new <tools-dir>/
target/board/<my_board> to the toolset. Interaction between <tools-dir>/target
and the -mcore, -msoc and -mboard options is also described.

4.2.1

Toolset partitioning
The toolset contains three distinct levels of target system partition; core, SoC and board
(board is the most commonly used level). The partition information is target dependent and
is located in the directory <tools-dir>/target.

Core level
This level is almost empty as it is provided for future use. Boot contributions and
__init_core routines are the most relevant. It is not possible to add a supplementary core
description at core level (however it is possible for board and SoC).
The core level information is located in the directory <tools-dir>/target/core.

SoC level
This level is almost empty as it is provided for future use. Boot contribution and
__init_soc routines are the most relevant.
The SoC level information is located in the directory <tools-dir>/target/soc.

7521642

75/170

Setting up a board

ST200

Board level
This level contains information specific to a given board, such as:

the memory map available on the board,

the initialization to be performed at the board level (for example, clock generator
settings or board memory initialization),

the boot contribution,

the initialization of the sysconf parameters,

the binary section placement settings.

The board level information is located in the directory <tools-dir>/target/board.

Most of the settings are concentrated at the board level. board/<my_board> content is
attached to one of the ST200 cores available on the board.

4.2.2

Toolset configuration
There are three options to control the executable generation and execution:

-mcore adds the core type specific contribution,

-msoc adds the SoC specific contribution,

-mboard adds the board contribution.

When one of the options is not defined, the default value is used.
The configuration data related to the target configuration is located in the <tools-dir>/
target directory.
Table 9 lists the parameters managed by the toolset and how they interact with each other.
Table 9.

ST200 toolset parameters

Item

76/170

Set-up by

Used by

Core include path

Compiler driver

C Preprocessor

SoC include path

Compiler driver

C Preprocessor

Board include path

Compiler driver

C Preprocessor

Macros

Compiler driver

C Preprocessor

crt1.o

Compiler driver

Linker

crti.o

Compiler driver

Linker

crtn.o

Compiler driver

Linker

crtbegin.o

Compiler driver

Linker

crtend.o

Compiler driver

Linker

Core initialization library

Compiler driver

Linker

Core library search path

Compiler driver

Linker

SoC initialization library

Compiler driver

Linker

SoC library search path

Compiler driver

Linker

Board initialization library

Compiler driver

Linker

Board library search path

Compiler driver

Linker

7521642

ST200

Setting up a board
Table 9.

ST200 toolset parameters (continued)

Item

Set-up by

Used by

DEFAULT_RESET_ADDRESS

linker script

Linker

DEFAULT_BOOT_ADDRESS

linker script

Linker

DEFAULT_TEXT_BASE

linker script

Linker/loader

DEFAULT_RAMEND

linker script

Linker/loader

RESET_ADDRESS

linker script

Linker/Run-time

BOOT_ADDRESS

linker script

Linker/Run-time

TEXT_BASE

linker script

Linker/Run-time

cpuclock

Run-time/simulator

Run-time

busclock

Run-time/simulator

Run-time

.bootreset section address

RESET_ADDRESS

Linker

.boot section address

BOOT_ADDRESS

Linker

Program sections address

(.text, .rodata, .data, .bss)

TEXT_BASE

Linker

bootcore.o

Compiler driver

Linker

bootsoc.o

Compiler driver

Linker

bootboard.o

Compiler driver

Linker

Hardware memory map

linker script

Linker/Loader

Early hardware initialization

board.txt

Loader

The following sections describe the toolset target dependent settings and how and where to
configure them.
In the tables provided, <endianness> is either le or be, <run-time> is either bare or
os21 and <my_core> is the core name.

Core contribution
The core contribution is controlled with the -mcore=<my_core> option. Only cores
delivered in the toolset can be referenced using the -mcore option.
Table 10.

Core contribution

Item

Value

Parameter location

Include search path

-I<tools-dir>/target/
core/<my_core>

Macros

-D__<my_core>__
-D__<MY_CORE>__

crt1.o

crt1.o

<tools-dir>/lib/<my_core>/
<endianness>/<run-time>/crt1.o

crti.o

crti.o

<tools-dir>/lib/<my_core>/
<endianness>/<run-time>/crti.o

7521642

77/170

Setting up a board

ST200

Table 10.

Core contribution (continued)

Item

Value

Parameter location

crtn.o

crtn.o

<tools-dir>/lib/<my_core>/
<endianness>/<run-time>/crtn.o

crtbegin.o

crtbegin.o

<tools-dir>/lib/<my_core>/
<endianness>/<run-time>/crtbegin.o

crtend.o

crtend.o

<tools-dir>/lib/<my_core>/
<endianness>/<run-time>/crtend.o

-L<tools-dir>/lib/
Core library search <my_core>/
path
<endianness>/
<run-time>
Core initialization
library

-lcore
(libcore.a)

<tools-dir>/target/core/<my_core>/
<endianness>/<run-time>
<tools-dir>/target/core/<my_core>/
<endianness>/<run-time>/bootcore.o

bootcore.o
Core initialization

__init_core routine

<tools-dir>/target/core/<my_core>/
<endianness>/<run-time>/libcore.a

SoC contribution
The SoC contribution is controlled with the -msoc=<my_soc> option.
Table 11.

SoC contribution

Item

Value

Include search path

-I<tools-dir>/target/
soc/<my_soc>

SoC library search

path

-L<tools-dir>/target/
soc/<my_soc>/
<my_core>/
<endianness>/
<run-time>

SoC initialization
library

-lsoc
(libsoc.a)

<tools-dir>/target/soc/<my_soc>/
<my_core>/<endianness>/<run-time>
<tools-dir>/target/soc/<my_soc>/
<my_core>/<endianness>/<run-time>/
bootsoc.o

bootsoc.o

SoC initialization

78/170

Parameter location

__init_soc routine

7521642

<tools-dir>/target/soc/<my_soc>/
<my_core>/<endianness>/<run-time>/
libsoc.a

ST200

Setting up a board

Board contribution
The board contribution is controlled with the -mboard=<my_board> option.
Table 12.

Board contribution

Item

Value

Include search path

-I<tools-dir>/target/
board/<my_board>

Board library
search path

-L<tools-dir>/target/
board/<my_board>/
<my_core>/
<endianness>/
<run-time>/

Board initialization
library

-lboard
(libboard.a)

Parameter location

<tools-dir>/target/board/
<my_board>/<my_core>/<endianness>/
<run-time>
<tools-dir>/target/board/
<my_board>/<my_core>/<endianness>/
<run-time>/bootboard.o

bootboard.o

Board initialization

__init_board routine

<tools-dir>/target/board/
<my_board>/<my_core>/<endianness>/
<run-time>/libboard.a

Hardware memory
map

FLASH, RAM area definition

<tools-dir>/target/board/
<my_board>/board.ld

DEFAULT_RESET_
ADDRESS

Definition is mandatory

<tools-dir>/target/board/
<my_board>/board.ld

DEFAULT_BOOT_
ADDRESS

Definition is mandatory

<tools-dir>/target/board/
<my_board>/board.ld

DEFAULT_TEXT_
BASE

Definition is mandatory

<tools-dir>/target/board/
<my_board>/board.ld

DEFAULT_RAMEND

Definition is mandatory

<tools-dir>/target/board/
<my_board>/board.ld

cpuclock

400 MHz

bootboard.o (or simulator parameter)

busclock

133 MHz

bootboard.o (or simulator parameter)

.bootreset section
address

DEFAULT_RESET_ADDRESS

<tools-dir>/target/board/
<my_board>/board.ld

.boot section

DEFAULT_BOOT_ADDRESS

<tools-dir>/target/board/
<my_board>/board.ld

Program sections
address
(.text, .rodata,
.data, .bss)

DEFAULT_TEXT_BASE

<tools-dir>/target/board/
<my_board>/board.ld

Early hardware
initialization

board.txt

<tools-dir>/target/board/
<my_board>/board.txt

7521642

79/170

Setting up a board

4.2.3

ST200

Configuration matrix
Table 13 summarizes the interaction between -mcore, -msoc, -mboard option and the
different level of contribution in the <tools-dir>/target directory.

Table 13.

Configuration matrix
Item

Default

-mcore

-msoc

-mboard

Core include path

N/A

SoC include path

N/A

Board include path

N/A

Macros

ST220

Compiler driver

crt1.o

ST220

Compiler driver

crti.o

ST220

Compiler driver

crtn.o

ST220

Compiler driver

crtbegin.o

ST220

Compiler driver

crtend.o

ST220

Compiler driver

Core initialization library

N/A

libcore.a

Core library search path

N/A

Compiler driver

SoC initialization library

N/A

libsoc.a

SoC library search path

N/A

Compiler driver

Board initialization library

N/A

libboard.a

Board library search path

N/A

Compiler driver

DEFAULT_RESET_
ADDRESS

N/A

board.ld

DEFAULT_BOOT_
ADDRESS

N/A

board.ld

DEFAULT_TEXT_BASE

N/A

board.ld

DEFAULT_RAMEND

N/A

board.ld

RESET_ADDRESS

N/A

platform.ld

BOOT_ADDRESS

N/A

platform.ld

TEXT_BASE

N/A

platform.ld

cpuclock

400 MHz

bootboard.o (or
simulator parameter)

busclock

133 MHz

bootboard.o (or
simulator parameter)

.bootreset section address

N/A

board.ld

.boot section address

N/A

board.ld

Program sections address

(.text, .rodata, .data, .bss)

Start at
0x08000000

board.ld

bootcore.o

N/A

80/170

Location
Compiler driver

Compiler driver
X

Compiler driver

bootcore.o

7521642

ST200
Table 13.

Setting up a board
Configuration matrix (continued)
Item

Default

-mcore

-msoc

-mboard

Location

bootsoc.o

N/A

bootboard.o

N/A

bootboard.o

Hardware memory map

FLASH
(0x00000000 to
0x00010000)
RAM (0x08000000
to 0x0A000000)

board.ld

Early hardware initialization

N/A

board.txt

4.3

Supported configurations

4.3.1

ST220 and ST231 cores

bootsoc.o

Table 14 and Table 15 show the supported configurations for the ST220 and ST231 cores
respectively. In the tables, <endianness> is either le or be and <run-time> is either
bare or os21.
Table 14.

ST220 core supported configuration

Item

Value

Parameter location

Include search path

-I<tools-dir>/target/
core/st220

Macros

-D__st220__
-D__ST220__

crt1.o

crt1.o

<tools-dir>/lib/st220/
<endianness>/<run-time>

crti.o

crti.o

<tools-dir>/lib/st220/
<endianness>/<run-time>

crtn.o

crtn.o

<tools-dir>/lib/st220/
<endianness>/<run-time>

crtbegin.o

crtbegin.o

<tools-dir>/lib/st220/
<endianness>/<run-time>

crtend.o

crtend.o

<tools-dir>/lib/st220/
<endianness>/<run-time>

Core library search

path

-L<tools-dir>/lib/
st220/<endianness>/
<run-time>

Core initialization
library

-lcore
(libcore.a)

<tools-dir>/target/core/st220/
<endianness>/<run-time>
<tools-dir>/target/core/st220/
<endianness>/<run-time>/bootcore.o

bootcore.o
Core initialization

__init_core routine

7521642

<tools-dir>/target/core/st220/
<endianness>/<run-time>/libcore.a

81/170

Setting up a board

ST200

Table 15.

ST231 core supported configuration

Item

Value

Include search path

-I<tools-dir>/target/
core/st231

Macros

-D__st231__
-D__ST231__

crt1.o

crt1.o

<tools-dir>/lib/st231/
<endianness>/<run-time>

crti.o

crti.o

<tools-dir>/lib/st231/
<endianness>/<run-time>

crtn.o

crtn.o

<tools-dir>/lib/st231/
<endianness>/<run-time>

crtbegin.o

crtbegin.o

<tools-dir>/lib/st231/
<endianness>/<run-time>

crtend.o

crtend.o

<tools-dir>/lib/st231/
<endianness>/<run-time>

Core library search

path

-L<tools-dir>/lib/
st231/<endianness>/
<run-time>

Core initialization
library

-lcore
(libcore.a)

<tools-dir>/target/core/st231/
<endianness>/<run-time>
<tools-dir>/target/core/st231/
<endianness>/<run-time>/bootcore.o

bootcore.o
Core initialization

4.3.2

Parameter location

__init_core routine

<tools-dir>/target/core/st231/
<endianness>/<run-time>/libcore.a

SoC
Since SoC level contribution to toolset configuration is almost empty, only the STm8000
supported configuration is presented as an example.
In Table 16, <endianness> is either le or be, <run-time> is either bare or os21 and
<my_core> is the core name.
Table 16.

SoC supported configuration

Item

82/170

Value

Include search path

-I<tools-dir>/target/
soc/stm8000

SoC library search

path

-L<tools-dir>/target/
stm8000/<my_core>/
<endianness>/
<run-time>

SoC initialization
library

-lsoc
(libsoc.a)

Parameter location

<tools-dir>/target/stm8000/
<my_core>/<endianness>/<run-time>/
libsoc.a

7521642

ST200

Setting up a board
Table 16.

SoC supported configuration (continued)

Item

Value

<tools-dir>/target/stm8000/
<my_core>/<endianness>/<run-time>/
bootsoc.o

bootsoc.o

SoC initialization

4.3.3

Parameter location

__init_soc routine

<tools-dir>/target/stm8000/
<my_core>/<endianness>/<run-time>/
libsoc.a

Example of mb428_host and mb428_audio boards

The mb428_host and mb428_audio boards have the same structure, therefore an mb428
host board settings description is presented as an example. The mb428 audio board
parameters are similar to the mb428_hosts parameters.
In Table 17, <run-time> is either bare or os21.
Table 17.

mb428_host board supported configuration

Item
Include search path

Value

Parameter location

-I<tools-dir>/target/
board/mb428_host

-L<tools-dir>/target/
Board library search
mb428_host/st231/le/
path
<run-time>
Board initialization
library

-lboard
(libboard.a)

<tools-dir>/target/mb428_host/
st231/le/<run-time>
<tools-dir>/target/mb428_host/
st231/le/<run-time>

bootboard.o
Board initialization

__init_board routine

<tools-dir>/target/mb428_host/
st231/le/<run-time>/libboard.a

Hardware memory
map

FLASH, RAM area definition.

<tools-dir>/target/mb428_host/
board.ld

DEFAULT_RESET_
ADDRESS

Definition is mandatory

<tools-dir>/target/mb428_host/
board.ld

DEFAULT_BOOT_
ADDRESS

Definition is mandatory

<tools-dir>/target/mb428_host/
board.ld

DEFAULT_TEXT_
BASE

Definition is mandatory

<tools-dir>/target/mb428_host/
board.ld

DEFAULT_RAMEND

Definition is mandatory

<tools-dir>/target/mb428_host/
board.ld

cpuclock

400 MHz

bootboard.o (or simulator parameter)

busclock

170 MHz

bootboard.o (or simulator parameter)

.bootreset section
address

DEFAULT_RESET_ADDRESS

<tools-dir>/target/mb428_host/
board.ld

.boot section

DEFAULT_BOOT_ADDRESS

<tools-dir>/target/mb428_host/
board.ld

7521642

83/170

Setting up a board

ST200

Table 17.

mb428_host board supported configuration (continued)

Item

4.4

Value

Parameter location

Program sections
address
DEFAULT_TEXT_BASE
(.text, .rodata, .data,
.bss)

<tools-dir>/target/mb428_host/
board.ld

Early hardware
initialization

<tools-dir>/target/mb428_host/
board.txt

board.txt

Integrating a new board in the toolset

This section explains how to integrate a new hardware board in the toolset. To modify or
adapt an existing board, see Section 1.11: Using a custom board target on page 46.

4.4.1

Add a board file into the ST200 toolset

A new board file must be added to the toolset in order for the tools to recognize the new
board for code generation, target connection and for critical test suite execution.
1.

Create the directory my_board to contain the target settings. For example:
cd my_target
mkdir my_board

2.

Copy the target information from the template directory, preserving the symbolic
links:
cp -a <tools-dir>/target/board/template/* my_board

3.

In the my_board directory, amend the files to specify the board you are setting up.
a)

b)

The following files are necessary for the first phase of the board bring up.
-

board.ld contains memory mapping information. This mapping is used by

the linker to generate an executable compatible with the memory mapping of
a given board. The mapping information provided in the MEMORY section also
helps the tool to check that the loaded program fits within the defined memory
map (see Board contribution on page 79).

board.txt contains early initialization code (memory, control registers or

peripheral clocks) typically through a sequence of poke or peek commands.
These are the minimal expected actions required to enable the ST200 core to
access the RAM memory area.

testcst.gdb is the critical test suite generated with gentestsuite shell

script and <tools-dir>/template/testcst.gdb.

The following files are necessary in the second phase of the bring up, that is, when
running any C program.
-

84/170

src/sysconf.c specifies the boards hardware configuration. The sysconf

constants, listed in <tools-dir>/include/machine/sysconf.h, have
to be setup in this file with their board specific values. The
int (*_sys_custom_sysconf)(int name) function pointer has to be
initialized and implemented to return the right values for each sysconf
constant.

7521642

ST200

Setting up a board
-

src/boot.S specifies the application needs. This file holds two sections:
.boot_reset and .boot.
The .boot section code is mapped to the boot address. The usage of the
.boot section is application dependent but its primary destination is the flash
memory on the board. It may be set once in order to start any C code
program already loaded in RAM. The default boot.S (<tools-dir>/
target/board/template/src/boot.S) shows how to setup the start
parameters before jumping to the C program. It can be updated with board
specific initialization like RAM access setup.

These two files can be compiled using the makefile provided in the directory.

4.4.2

Critical test suite

The critical test suite carries out step by step checks to ensure that the basic debug features
are working correctly. It tests that:

the DSU register can be accessed (R/W),

the RAM can be accessed (R/W),

the peripheral base address is correct,

the halt command is working,

the exception handler is working.

A template for the critical test suite is delivered in the toolset as well as the shell script
instantiating it.
In order to generate the test suite you need to know:

the 2 most significant bytes (MSB) of the RAM base address,

the 2 most significant bytes (MSB) of the peripheral base address.

For instance, the testcst.gdb test suite can be generated as follows:

> cd my_board
> <tools-dir>/target/template/gentestsuite --ram=0x0800
--periph=0x1410 --src=<tools-dir>/target/board/template/testcst.gdb
--dest=testcst.gdb
This generates a critical test suite, testcst.gdb, where:

<tools-dir>/target/board/template/testcst.gdb is used as the test suite

template,

the peripheral base address is 0x14100000,

the RAM base address is 0x08000000.

The --help option can be used to view detailed help information. For example:
> gentestsuite --help
This script is a bournshell script generating critical testsuite for
ST2XX core from a template file
Usage:
-----gentestsuite --periph=<periph base addr> --ram=<ram base addr>
--src=<template file> --dest=<destination file>

7521642

85/170

Setting up a board

ST200

Parameter description:
---------------------- periph: 2 MSB of peripheral base address (0x1f000000 then
periph_base = 0x1f00 )
- ram: 2 MSB of RAM base address (0x80000000 then ram_base = 0x8000
)
Once this test suite has been generated, modify testcst.gdb so that the expected test
suite version of test 1 (CTS1, gdi dpeek 0) reads the expected core version number
(0x02020202 for ST220).
The critical test suite for my_board is now ready to be executed.

4.5

Using the tools

4.5.1

Initialization sequence
Several default actions are carried out by the silicon back-end component when connecting
to the silicon target. Table 18 shows these default actions together with the options that can
be used to disable them.
Table 18.

Initialization actions
Executed operation

4.5.2

Options that disable actions

Connection to the ST Micro Connect.

None

Physical core reset and DSU taplink reset.

None

Execution of the board.txt content.

DSU_TEST

Executes a logical reset where, for instance, some DSU

registers and internal representations are initialized.

DSU_TEST

Install the load speed-up and endianness check routine, and

retrieve endianness.

DSU_TEST, DISABLE_MPOKE

st200gdb commands for bring up

st200gdb in console mode is used during the bring up phase. It accesses a low level
command line interpreter. This set of commands allows DSU register accesses (dpeek,
dpoke) through the taplink interface, and allows RAM memory accesses (peek, poke) and
ST200 assembly code execution (go, halt) through the DSU monitor.
In the first stage of bring up, silicon back-end connection parameters restrict actions
performed in the initialization sequence (see DSU_TEST in Table 3 on page 22).

4.5.3

Debug facilities
In the targets.cfg file, add EMU_SAFE_TRACE to the option string of the alias defined for
my_board.
This ensures that all commands and answers sent from the host machine to ST Micro
Connect are stored in a log file, emutrace.log, where st200gdb has been launched.

86/170

7521642

ST200

4.6

Setting up a board

Bring up operations
This section describes the procedure leading up to the execution of a simple C program.

4.6.1

Define an alias for the silicon connection settings

For the first phase, executing the DSU critical test suite, the target is connected using
st200gdb. An alias restricts the actions carried out in the initialization phase to a single
physical reset.
In your targets.cfg file, insert the following aliases:
my_board_dsu_test HTI_ID tcp: <ST Micro Connect IP> BOARD my_board
DSU_TEST
where <ST Micro Connect IP> is the IP address of the ST Micro Connect.
The connection to the target can also be configured with a limited speed. The following
example divides the taplink transfer speed by 16 (that is, 50 MHz/16):
my_board_dsu_test HTI_ID tcp: <ST Micro Connect IP> BOARD my_board
CLOCK_D=16 DSU_TEST
For the second phase, executing a C program using the st200gdb or the st200run tool, the
following alias must be added in your targets.cfg file:
my_board HTI_ID tcp: <ST Micro Connect IP> BOARD my_board CLOCK_D=16
BOOTRAM=<Valid_RAM_address>
The BOOTRAM address indicates where the temporary debug code is to be loaded, that is,
saving and restoring the ST200 memory used. This option is necessary only when no
debug or ram area name is present in the board.ld file. The search algorithm for the
BOOTRAM information is carried out in the following order.
1.

BOOTRAM value if the option is mentioned in command line.

2.

The beginning of the debug area in the board.ld file for this target.

3.

The beginning of the ram or RAM area (only ram or RAM, not ramemi) in the
board.ld file for this target.

The recommended way to manage the BOOTRAM information for a target board is to ensure
that a ram area name is present in the board.ld file and to not use the BOOTRAM option
on the target description line. This area can then be used at connection time for temporary
needs and can be safely reused to load and execute the program.

4.6.2

Connect to the target through the ST Micro Connect

Launch st200gdb in command line:
> <tools-dir>/bin/st200gdb
(gdb)
Type:
target gdi -t my_board_dsu_test

7521642

87/170

Setting up a board

4.6.3

ST200

Perform the DSU register accesses

Type:
(gdb) gdi dpeek 0
The ST200 core number value is displayed.
Enter:
(gdb) gdi dpeek 10
(gdb) gdi dpoke 10 0x12345678
(gdb) gdi dpeek 10
The result is 0x12345678.

4.6.4

Perform the RAM accesses

At this stage, the access to the RAM memory must have been initialized. This initialization
sequence must be implemented in the board.txt file in your defined board. To execute
this file type:
(gdb) gdi file board.txt
For convenience, we suppose that 0x8000000 is a valid memory area.
(gdb) gdi peek 0x8000000
(gdb) gdi poke 0x8000000 0x12131415
(gdb) gdi peek 0x8000000
The result is 0x12131415.

4.6.5

Execute the generated critical test suite

Create the st200gdb command file:
# Begin gdb command file
# Connect to the target with the DSU_TEST option
target gdi -tmy_board_dsu_test
# Execute critical test suite present in the current directory
source testcst.gdb
quit
#End gdb command file
The critical test suite provides a results summary at the end of its execution. Execute the
critical test suite and redirect the summary to a file by typing:
> cp <tools-dir>/board/my_board/testcst.gdb .
> <tools-dir>/bin/st200gdb -x cmd.gdb > test.log

88/170

7521642

ST200

4.6.6

Setting up a board

Compile and execute a C program

The following assumes that my_board has an ST220 core.
> <tools-dir>/bin/st200cc -mtargetdir=/my_targets -mcore=st220
-msoc=default -mboard=my_board -g -o hello hello.c
> <tools-dir>/bin/st200gdb hello
(gdb) target gdi -t my_board -m/my_targets
Connect to the GDI debug instrument.
(gdb) load
Loading section .boot, size 0x510 lma 0x0
Loading section .text, size 0x15aa0 lma 0x8001000
Loading section .data, size 0x15a0 lma 0x8016aa0
Start address 0x8002550, load size 95568
Transfer rate: 764544 bits/sec, 8688 bytes/write.
(gdb) run
Starting program: ./hello.emu
Hello World !!
Program exited with code 034.
[Switching to thread 0]
(gdb)

7521642

89/170

Relocatable loader library

ST200

Relocatable loader library

5.1

Introduction to the relocatable loader library

The relocatable loader library (rl_lib) provides support for the creation and loading of
dynamic shared objects (DSOs) in an embedded environment. rl_lib implements DSOs (or
load modules) as defined in the standard for supporting ELF System V Dynamic Linking.

Note:

rl_lib can be used as an alternative to the standard ELF System V Dynamic Loader
(libdl.so) for applications that do not rely on advanced OS features such as file systems,
virtual memory management, and multi process segment sharing.

5.1.1

Run-time model overview

There are several run-time models that can be supported using the ELF System V ABI of
which, only some are suitable for embedded systems without the support of traditional
operating system services. The run-time model for an application dictates the method used
for linking and loading. Table 19 lists the different run-time models and Table 20 summarizes
the features supported by each model.
rl_lib implements only the R_Relocatable run-time model.
Table 19.

Run-time models

Run-time model

90/170

Description

R_Absolute

Absolute run-time model. The whole application is a single module which is

statically linked at a fixed load address.

R_Relocatable

Relocatable run-time model. The application has a main module and several
load modules. The main module is statically linked and loaded as for an
R_Absolute application. The load modules are loaded on demand (by
explicit calls to the loader) at run-time. The load modules are loaded at an
arbitrary address and dynamic symbol binding is applied by the loader for
symbols undefined in the load modules. The dynamic symbol binding
traverses the modules, bottom up in the hierarchy of loaded modules. See
Section 5.2 on page 91 for details.

R_PIC

System V run-time model. The application has a main module and several
load modules. The main module is typically statically linked but may have
references to symbols in the load modules. The main module is loaded with
support from the dynamic loader that also loads load modules and binds
symbols before the application starts. At run-time, the application may also
load other modules on demand. The dynamic symbol binding traverses the
load modules in an order which is defined by the static link order and the
run-time loading order. In addition to dynamic loading and linking, the load
modules segments can be shared between several applications in a
multi-process environment. This model usually relies on file system support
and virtual memory management.

7521642

ST200

Relocatable loader library

Table 20.

Run time models comparison

Supported features

5.2

R_Absolute

R_Relocatable

R_PIC

Application partitioning

1 single program

1 main program +
N load modules

1 main program +
N load modules

Static symbol binding

Yes

Yes

Yes

Dynamic loading

No

Startup time: No
Run-time: Yes

Startup time: Yes

Run-time: Yes

Dynamic symbol
binding

No

Main program: No
Load modules: Yes

Main program: Yes

Load modules: Yes

Explicit module
dependencies

N/A

No

Yes

Dynamic symbol lookup N/A

Bottom up (from loaded

Unrestricted order
to loader)

Symbol preemption

N/A

No

Yes

Segment sharing
(across processes)

N/A

No

Yes

Performance impact

N/A

Minimal

Yes

Code size impact

N/A

Minimal

Yes

Application writer
impact

N/A

Need explicit loading

No change by default

Build system impact

N/A

Compiler options
Load modules build

Compiler options
Load modules build

Relocatable run-time model

The R_Relocatable run-time model as implemented by rl_lib has the following features:

one main module loaded at application startup by the system,

several load modules that can be loaded at run-time and unloaded after use,

several modules can be resident at the same time,

a loaded module, as for the main module, can load and unload other load modules,

load modules can be loaded anywhere,

access to symbols in loaded modules from the loader through a call to the loader
library,

dynamic symbol binding is performed by the loader when loading a module and
symbols are searched in the load modules hierarchy bottom-up (to the main module),

sharing of code and data objects between modules is achieved by linking to the objects
in a common ancestor,

the loader library is statically linked with the main module,

generally, system support archive library should be linked with the main module.

The example in Figure 23 shows an application that has four load modules A, B, C and D.

7521642

91/170

Relocatable loader library

ST200

Figure 23. Example of an application with four load modules

printf
Module B
printf
Module A

*exec_B

malloc

main
printf
malloc

*exec_A

*exec_D

*exec_C
malloc

Module C

printf
malloc

Module D

In Figure 23, curved arrows (from load modules to parent module) represent load time
symbol binding performed while the load module is loaded. Straight arrows (from loader
module to loaded module) represent explicit symbol address resolution performed through
the loader library API.
The following points describe a possible scenario.

92/170

At run-time, the main module loads the module A in to memory through the
rl_load_file() function.

The loader, in the process of loading A into memory, binds the symbol printf
undefined in A to the printf function defined in main.

The main program then retrieves a pointer to the function symbol exec_A in A using
the rl_sym() function.

As for A, the main program loads the module D and references to printf are resolved
to the printf in main. In addition, references to malloc in D are also resolved to the
malloc in main. The main program then retrieves a pointer to exec_D in D using the
rl_sym() function.

The main program then, at some point, invokes the function exec_A.

The exec_A function then loads a further two modules B and C.

The undefined reference to printf in B is resolved to the printf in main (the loader
searches first in A, and then in main).

The undefined reference to malloc in C is resolved to the malloc in A (the loader

searches for and finds it in A). Note that the malloc function called from D (malloc of
main) is then different from the malloc function called from B (or C, or A) which is the
malloc of A.

Module A may in turn indirectly call functions or reference data in B and C after
retrieving symbol addresses using the rl_sym() function.

At any time, the main module or the module A may unload one of the loaded modules.

7521642

ST200

5.2.1

Relocatable loader library

The relocatable code generation model

The relocatable code generation model is the same as the code generation model for the
System V model with the following differences.

5.3

No symbol can be preempted. Dynamic symbol binding always searches the current
module first. This has the effect that a module containing a symbol definition can be
sure that it will use this definition. This allows inlining in load modules for example.

Weak references are treated the same way as undefined references in load modules.
Therefore, when traversing the module tree bottom-up, the first definition seen is taken.

Relocatable loader library API

The relocatable loader library provides support for loading and unloading a module and for
accessing a symbol address in a module by name. The relocatable loader library is provided
as a library librl.a and its associated header file rl_lib.h.
The functions defined in this API are explained in the following sections.

rl_handle_t type
All the functions manipulating a load module use a pointer to the rl_handle_t type. This
is an abstract type for a load module handle.
A load module handle is allocated by the rl_handle_new() function and deallocated by
the rl_handle_delete() function.
The main module handle is statically allocated and initialized in the startup code of the main
module.
A module handle references one loaded module at a time. To load another module from the
same handle, the previous module must first be unloaded.

7521642

93/170

Relocatable loader library

ST200

rl_handle_new
Allocate and initialize a new handle
Definition:

rl_handle_t *rl_handle_new(
const rl_handle_t *parent,
int mode);

Arguments:
parent

The handle of the parent module.

mode

Reserved for future extensions.

Returns:

The newly initialized handle.

Description:

The rl_handle_new() function allocates and initializes a new handle that can be
used for loading and unloading a load module.
The handle of the parent module to which the loaded module will be connected is
specified by the parent argument.
The mode argument is reserved for future extensions and must always be 0.
Generally, a load module will be attached to the module using this function, therefore
a handle will typically be allocated as follows:
rl_handle_t *new_handle = rl_handle_new(rl_this(), 0);

rl_handle_delete
Finalize and deallocate a module handle
Definition:

int rl_handle_delete(
rl_handle_t *handle);

Arguments:
handle

The handle to deallocate.

Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_handle_delete() function finalizes and deallocates a module handle.

The handle must not hold a loaded module. The loaded module must have been first
unloaded by rl_unload() before calling this function. If successful, the value
returned is 0. Otherwise the value returned is -1 and the error code returned by
rl_errno() is set accordingly.

94/170

7521642

ST200

Relocatable loader library

rl_this
Return the handle for the current module
Definition:

rl_handle_t *rl_this(void);

Arguments:

None.

Returns:

The handle for the current module.

Description:

The rl_this() function returns the handle for the current module. If called from the
main module, it returns the handle of the main module. If called from a loaded
module, it returns the handle that holds the loaded module.
This function is used when allocating a handle with rl_handle_new(). It can also
be used, for example, to retrieve a symbol in the current module:
void *symbol_ptr = rl_sym(rl_this(), "symbol");

rl_parent
Return the handle for the parent of the current handle
Definition:

rl_handle_t *rl_parent(void);

Arguments:

None.

Returns:

The handle for the parent of the current handle.

Description:

The rl_parent() function returns the handle for the parent of the current handle
(as returned by rl_this()).
It may be used, for example, to find a symbol in one of the parent modules:
void *symbol_in_parents = rl_sym_rec(rl_parent(), "symbol");

rl_load_addr
Return the memory load address of a loaded module
Definition:

const char *rl_load_addr(

rl_handle_t *handle);

Arguments:
handle

The handle for the loaded module.

Returns:

The memory load address of the loaded module, or NULL.

Description:

The rl_load_addr() function returns the memory load address of a loaded

module. It returns NULL if the handle does not hold a loaded module or if the handle
passed is the main program handle.

7521642

95/170

Relocatable loader library

ST200

rl_load_size
Return the memory load size of a loaded module
Definition:

unsigned int rl_load_size(

rl_handle_t *handle);

Arguments:
handle

The handle for the loaded module.

Returns:

The memory load size of the loaded module, or 0.

Description:

The rl_load_size() function returns the memory load size of a loaded module. It
returns 0 if the handle does not hold a loaded module or if the handle passed is the
main program handle.

rl_file_name
Return the filename associated with the loaded module handle
Definition:

const char *rl_file_name(

rl_handle_t *handle);

Arguments:
handle

The handle for the loaded module.

Returns:

The filename associated with the loaded module handle, or NULL.

Description:

The rl_file_name() function returns the filename associated with the loaded
module handle. It returns NULL if no filename is associated with the current loaded
module, if the handle does not hold a loaded module or if the handle passed is the
main program handle.

rl_set_file_name
Specify a filename for the handle
Definition:

int rl_set_file_name(
rl_handle_t *handle,
const char *f_name);

Arguments:
handle

The handle for the module.

f_name

The filename to specify for the handle.

Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_set_file_name() function is used to specify a filename for a handle. This

filename is attached to the next module that will be loaded. It can be used to specify a
filename for modules loaded from memory or to force a different filename for a
module loaded from a file.
This function returns 0 if the filename was successfully set, or -1 and the error code
returned by rl_errno() is set accordingly if a module is already loaded or if the
application runs out of memory.

96/170

7521642

ST200

Relocatable loader library

rl_load_buffer
Load a relocatable module into memory
Definition:

int rl_load_buffer(
rl_handle_t *handle,
const char *image);

Arguments:
handle

The handle for the module.

image

The image of the load module.

Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_load_buffer() function loads a relocatable module into memory from the
image referenced by image.
It allocates the space for the loaded module in the heap, loads the segments from the
memory image of the loadable module, links the module to the parent module of the
handle and relocates and initializes the loaded module.
This function calls the action callback functions for RL_ACTION_LOAD after loading
and before executing any code in the loaded module.
The value 0 is returned if the loading was successful. The value -1 is returned on
failure and the error code returned by rl_errno() is set accordingly.

rl_load_file
Load a relocatable module into memory from a file
Definition:

int rl_load_file(
rl_handle_t *handle,
const char *f_name);

Arguments:
handle

The handle for the module.

f_name

The file from which to load the relocatable module.

Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_load_file() function loads a relocatable module into memory from the file
specified by f_name.
It opens the specified file with an fopen() call, allocates the space for the loaded
module in the heap, loads the segments from the file, links the module to the parent
module of the handle, relocates and initializes the loaded module. The file is closed
with fclose() before returning. This function calls the action callback functions for
the RL_ACTION_LOAD after loading and before executing any code in the loaded
module.
0 is returned if the load was successful, -1 is returned on failure and the error code
returned by rl_errno() is set accordingly.

7521642

97/170

Relocatable loader library

ST200

rl_load_stream
Load a relocatable module into memory from a byte stream
Definition:

typedef int rl_stream_func_t (

void *cookie,
char *buffer,
int length);
int rl_load_stream(
rl_handle_t *handle,
rl_stream_func_t *stream_func,
void *stream_cookie);

Arguments:
handle

The handle for the module.

stream_func

The user specified callback function.

stream_cookie

The user specified state.

Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_load_stream() function loads a relocatable module into memory from a

byte stream provided via a user specified callback function stream_func and the
user specified state stream_cookie.
The callback function must be of type rl_stream_func_t. It is called multiple times
by the loader to retrieve the load module data in the buffer buffer of length length
until the module is loaded into memory. The loader always calls the callback function
with a buffer length strictly greater than 0. The stream_cookie argument passed to
rl_load_stream is passed to the callback function in its cookie parameter. The
cookie parameter is intended to be used by the callback function to update a private
state.
The callback function must return the number of bytes transferred. If the returned
value is less than the given buffer length or is -1, rl_load_stream() will in turn
return an error and the error code returned by rl_errno() is set accordingly.
The rl_load_stream() function allocates the space for the loaded module from
the heap, loads the segments by calling the callback function, links the module to the
parent module of the handle, relocates and initializes the loaded module. This
function calls the action callback functions for RL_ACTION_LOAD after loading and
before executing any code in the loaded module.
0 is returned if the load was successful, -1 is returned on failure and the error code
returned by rl_errno() is set accordingly.
This function can be used as an alternative to rl_load_buffer() or
rl_load_file() to allow any loading method to be implemented.
The following example illustrates how the rl_load_file() function may be
implemented using the rl_load_stream() function:
/* User implementation of the callback function that read from
a file. */
static int rl_stream_read(FILE *file, char *buffer, int length)
{
int nbytes;

98/170

7521642

ST200

Relocatable loader library

nbytes = fread(buffer, 1, length, file);
return nbytes;
}
...
{
/* Loads the module from a file.*/
FILE *file;
int status;
file = fopen(f_name, "rb");
if (file == NULL) { /* ... error ... */ }
status = rl_load_stream(handle, (rl_stream_func_t
*)rl_stream_read,
file);
if (status == -1) { /* ... error ... */ }
fclose(file);
}
...

rl_unload
Unload a previously loaded relocatable module
Definition:

int rl_unload(
rl_handle_t *handle);

Arguments:
handle

The handle for the module.

Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_unload() function unloads a previously loaded relocatable module. It

finalizes, unlinks, and frees allocated memory for the loaded module. This function
calls the action callback functions for RL_ACTION_UNLOAD before unloading and
after having executed finalization code in the module.
The return value is 0 if the unloading is successful, otherwise the return value is -1
and the error code returned by rl_errno() is set accordingly.

7521642

99/170

Relocatable loader library

ST200

rl_sym
Return a pointer reference to the symbol in the loaded module
Definition:

void *rl_sym(
rl_handle_t *handle,
const char *name);

Arguments:
handle

The handle for the loaded module.

name

The symbol in the loaded module.

Returns:

The pointer reference to the symbol.

Description:

The rl_sym() function returns a pointer reference to the symbol named name in the
loaded module specified by handle. It searches the dynamic symbol table of the
loaded module and returns a pointer to the symbol. The handle parameter can be
the handle of any currently loaded module, or the handle of the main module.
If the symbol is not defined in the loaded module, NULL is returned. It is not generally
an error for this function to return NULL. For example, the user may conditionally call a
specific function only if it is defined in the module.
In this function, as well as in the rl_sym_rec() function, the name parameter must
be the mangled symbol name. For instance, on some targets, C names are mangled
by prefixing the name with an underscore (_). For example, to return a reference to
the printf() function, the symbol name passed to rl_sym() will be _printf.
Also, to access C++ symbols, the fully mangled name must be passed. The C++
mangling scheme is dependent on the processor specific C++ ABI implemented.

100/170

7521642

ST200

Relocatable loader library

rl_sym_rec
Return a pointer reference to the symbol in the loaded module or
one of its ancestors
Definition:

void *rl_sym_rec(
rl_handle_t *handle,
const char *name);

Arguments:
handle

The handle for the loaded module.

name

The symbol in the loaded module.

Returns:

The pointer reference to the symbol.

Description:

The rl_sym_rec() function returns a pointer reference to the symbol named name
in the loaded module specified by handle or one of its ancestors.
This function searches the dynamic symbol table of the loaded module and returns a
pointer to the symbol if found. If the symbol is not found, the function iteratively
searches in the dynamic symbol table of the parent module until the symbol is found.
The handle parameter can be the handle of any currently loaded module, or the
handle of the main module.
If the symbol is not defined in the loaded module or one of its ancestors, NULL is the
returned. It is not generally an error for this function to return NULL.
The name parameter must be the mangled symbol name as for the rl_sym()
function.

7521642

101/170

Relocatable loader library

ST200

rl_foreach_segment
Iterate over all the segments of loaded module and call the
supplied function
Definition:

typedef rl_segment_info_t_ rl_segment_info_t;

typedef int rl_segment_func_t (
rl_handle_t *handle,
rl_segment_info_t *seg_info,
void *cookie);
int rl_foreach_segment(
rl_handle_t *handle,
rl_segment_func_t *callback_fn,
void *callback_cookie);

Arguments:
handle

The handle for the module.

callback_fn

The user specified callback function.

callback_cookie
The argument to pass to the function.
Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_foreach_segment() function iterates over all the segments of the loaded
module handle and calls back the user supplied function. For each segment, the
function callback_fn is called with the following parameters.
handle

The handle passed to the function.

seg_info

The segment information pointer filled with the current

segment information.

cookie

The callback_cookie argument passed to the function.

The segment information returned in seg_info is a pointer to the following structure:

typedef unsigned int rl_segment_flag_t;
#define RL_SEG_EXEC
1
#define RL_SEG_WRITE
2
#define RL_SEG_READ
4
struct rl_segment_info_t_ {
const char *seg_addr;
unsigned int seg_size;
rl_segment_flag_t seg_flags;
};
The user callback function must return 0 on success or -1 on error.
In the case where the callback function returns an error, the
rl_foreach_segment() function returns -1 and the error code returned by
rl_errno is set to RL_ERR_SEGMENTF. Otherwise the function returns 0.

102/170

7521642

ST200

Relocatable loader library

rl_add_action_callback
Add a user action callback function to the user action callback list
Definition:

typedef
#define
#define
#define

unsigned int rl_action_t;

RL_ACTION_LOAD
1
RL_ACTION_UNLOAD
2
RL_ACTION_ALL
((rl_action_t)-1)

typedef int rl_action_func_t (

rl_handle_t *handle,
rl_action_t action,
void *cookie);
int rl_add_action_callback(
rl_action_t action_mask,
rl_action_func_t *callback_fn,
void *callback_cookie);
Arguments:
action_mask

The set of actions for which the callback function must be

called.

callback_fn

The user specified callback function.

callback_cookie
The argument to pass to the function.
Returns:

Returns 0 for success, -1 for failure.

Description:

The rl_add_action_callback() function adds a user action callback function to

the user action callback list. It can be called multiple times with different callback
functions. The same callback function cannot be added more than once.
For each defined action, each callback function is called in the order it was added into
the callback list. The callback functions are not attached to a particular module and
are called for any further loaded/unloaded modules.
This function returns 0 on success and -1 on failure. It does not set any error codes.
This function can fail if a callback function is already in the callback list or if the
program goes out of memory.
The rl_action_t type defines the action flags for module loading/unloading and is
passed to the action function callback. The action flags can be OR-ed to create an
action mask that can be passed to the function rl_add_action_callback(). The
action defined are:
RL_ACTION_LOAD

The callback is called just after the module has been loaded in
memory and cache has been synchronized. No module code
has been executed.

RL_ACTION_UNLOAD The callback is called just before the module is unloaded from
memory. No module code will be executed after this point.
RL_ACTION_ALL

The callback will be called for any action.

7521642

103/170

Relocatable loader library

ST200

The type for the user action callback function is rl_action_func_t. The
parameters passed to the callback function when it is called are:
handle

The handle that performed the action.

action

The action performed.

cookie

The callback_cookie parameter passed to

rl_add_action_callback().

The callback function returns 0 on success and -1 on failure. In the case of failure, the
loading (or unloading) of the module is undone and the error code returned by
rl_errno() is set to RL_ERR_ACTIONF.

rl_delete_action_callback
Remove the given function from the action callback list
Definition:

int rl_delete_action_callback(
rl_action_func_t *callback_fn);

Arguments:
callback_fn

The user specified callback function.

Returns:

Returns 0 for success, -1 if the callback was not present in the callback list.

Description:

The rl_delete_action_callback() function removes the specified callback

function from the action callback list. This function returns 0 if the callback was
removed, or -1 if it was not present in the callback list. No error code is set.

104/170

7521642

ST200

Relocatable loader library

rl_errno
Return the error code for the last failed function
Definition:

int rl_errno(
rl_handle_t *handle);

Arguments:
The handle for the module.

handle
Returns:

The error code for the last failed function.

Description:

The rl_errno() function returns the error code for the last failed function. Table 21
lists the possible codes.
Table 21.

Errors returned by rl_errno()

Error code

Diagnostic

Possible error causing

function

RL_ERR_NONE

No previous call has failed.

RL_ERR_MEM

Ran out of memory (rl_memalign()

failed).

rl_load_buffer(),
rl_load_file(),
rl_load_stream(),
rl_set_file_name()

RL_ERR_ELF

The load module is not a valid ELF file.

rl_load_buffer(),
rl_load_file(),
rl_load_stream(),
rl_set_file_name()

RL_ERR_DYN

rl_load_buffer(),
rl_load_file(),
The load module is not a dynamic library.
rl_load_stream(),
rl_set_file_name()

RL_ERR_SEG

The load module has invalid segment

information.

rl_load_buffer(),
rl_load_file(),
rl_load_stream(),
rl_set_file_name()

RL_ERR_REL

The load module contains invalid

relocations.

rl_load_buffer(),
rl_load_file(),
rl_load_stream(),
rl_set_file_name()

RL_ERR_RELSYM

A symbol was not found a load time.

rl_errarg() returns the symbol
name.

rl_load_buffer(),
rl_load_file(),
rl_load_stream(),
rl_set_file_name()

RL_ERR_SYM

The symbol is not defined in the module.

rl_sym(),
rl_errarg() returns the symbol
rl_sym_rec()
name.

RL_ERR_FOPEN

The file cannot be opened by

rl_fopen().

rl_load_file()

RL_ERR_FREAD

Error while reading the file in

rl_fread().

rl_load_file()

7521642

105/170

Relocatable loader library

Table 21.

ST200
Errors returned by rl_errno() (continued)

Error code

Diagnostic

Possible error causing

function

Error while loading the file from a

stream.

rl_load_stream()

RL_ERR_LINKED

Module handle is already linked.

rl_load_file(),
rl_load_buffer(),
rl_load_stream(),
rl_handle_delete()

RL_ERR_NLINKED

Module handle is not linked

rl_unload(), rl_sym(),
rl_sym_rec(),
rl_foreach_segment()

RL_ERR_SEGMENTF

Error in segment function callback.

rl_foreach_segment()

RL_ERR_ACTIONF

Error in action function callback.

rl_load_file(),
rl_load_buffer(),
rl_load_stream()

RL_ERR_STREAM

rl_errarg
Return the name of the symbol that could not be resolved
Definition:

const char *rl_errarg(

rl_handle_t *handle);

Arguments:
handle

The handle for the module.

Returns:

The name of the symbol that could not be resolved.

Description:

If rl_errno() returns either RL_ERR_RELSYM or RL_ERR_SYM, the rl_errarg()

function returns the name of the symbol that could not be resolved.

106/170

7521642

ST200

Relocatable loader library

rl_errstr
Return a string for an error code
Definition:

const char *rl_errstr(

rl_handle_t *handle);

Arguments:
handle

The handle for the module.

Returns:

A string for the error code.

Description:

The rl_errstr() function returns a readable string for the error code reported by
rl_errno(). For example:
...
void *sym = rl_sym(handle, "symbol");
if (sym == NULL) fprintf(stderr, "failed: %s\n",
rl_errstr(handle));
...
If symbol is not defined in the module referenced by handle then the following
message is displayed:
failed: symbol not found: symbol

7521642

107/170

Relocatable loader library

5.4

ST200

Customization
The relocatable loader library defines a number of functions that it uses internally for
providing services such as heap memory management and file access. These functions
may be overridden by the application in the main module to provide custom implementations
of these functions.

5.4.1

Memory allocation
void *rl_malloc(int size);
void *rl_memalign(int align, int size);
void rl_free(void *ptr);
These functions are used to allocate free space for the load module image and for the
handle objects.
The default behavior for these functions is to call the standard C library functions
malloc(), memalign() and free() respectively.

Note:

All three functions must be overridden if providing a custom implementation.

5.4.2

File management
void *rl_fopen(const char *f_name, const char *mode);
int rl_fclose(void *file);
int rl_fread(char *buffer, int eltsize, int nelts, void *file);
These functions are used by the rl_load_file() function to open, read and close a file
handle.
The default behavior for these functions is to call the standard C library functions fopen(),
fread() and fclose() respectively.

Note:

All three functions must be overridden and linked with the main program if providing a
custom implementation.

5.5

Building a relocatable library or main module

To build a relocatable library that can be loaded by the rl_lib loader, additional compile time
and link time options must be used.
The following is a simple example of building a hello world loadable module:
st200cc -o rl_hello.o -fpic -c rl_hello.c
st200cc -o rl_hello.rl --rlib rl_hello.o
Alternatively, the compile and link phases can be carried out with a single command:
st200cc -o rl_hello.rl -fpic --rlib rl_hello.c
To build a main module suitable for loading a relocatable library, specific link time options
are required. No specific compile time option are required for the main module.
The following is an example of building a main module:
st200cc -o prog.o prog.c
st200cc -o prog.exe --rmain prog.o

108/170

7521642

ST200

Relocatable loader library

The compile and link phases can be carried out with a single command:
st200cc -o prog.exe --rmain prog.c

5.5.1

Importing and exporting symbols

For the relocatable loader system to function, the main module, or a loaded module, must
provide services to the other load modules. In order to avoid a load error when loading a
module, it is usual for the referenced symbols to be linked into the main module. When the
services are present in a library, the corresponding symbols must be imported at the time of
linking the main module. To import symbols, the linker needs to be provided with an import
script.
An import script can be generated by the st200rltool utility. There are two common cases:

when the required services are well defined, the list of symbols can be passed to the
st200rltool utility to generate an import script,

when the list of services is not defined but the load modules are available, the load
modules can be passed to st200rltool so that an import script may be generated from
the set of symbols that are required by the load modules.

To generate an import script from a list of symbols specified in the file prog_import.lst
(one symbol per line):
st200rltool -i -s -o prog_import.ld prog_import.lst
To generate an import script from a list of load modules, liba.rl and libb.rl, that may
be loaded by the main module:
st200rltool -i -o prog_import.ld liba.rl libb.rl
When the import script is created, the main module can then be linked using it, for example:
st200cc -o prog.exe --rmain object_files.o prog_import.ld
In addition to import scripts, the st200rltool utility can also generate export scripts that can
be used to reduce the size of the dynamic symbol table in the main module or the load
modules. The export script defines the set of symbols (and only these) that must be
exported to the other modules through the dynamic symbol table. These symbols are then
accessible by the load time symbol binding process and by the calls to rl_sym() and
rl_sym_rec(). The export script is not mandatory as, by default, all global symbols are
exported.
There are two common cases for generating export scripts.

When an import script is required for the module, the export script can be generated at
the same time. This is because the symbols to export are generally those that are
imported,

For a load module that has a well known external interface, the export script can be
generated from a list of symbols to export.

The following example shows how to generate an export script and import script for a list of
modules that is then used when linking the main module. Only the symbols from liba.rl
and libb.rl are imported into the main module and exported by it.
st200rltool -i -e -o prog_import_export.ld liba.rl libb.rl
st200cc -o prog.exe --rmain object_files.o prog_import_export.ld

7521642

109/170

Relocatable loader library

ST200

To generate an export script for a load module with a well defined interface specified in the
file liba_export.lst (one symbol per line):
st200rltool -e -s -o liba_export.ld liba_export.lst
st200cc -o liba.rl --rlib *.o liba_export.ld

5.5.2

Optimization options
When compiling a load module with the -fpic option, some overhead occurs in the
generated code to access functions and data objects. Compiler options and C language
extensions can be used to reduce this overhead.
As relocatable libraries are not subject to symbol preemption, the
-fvisibility=protected option can be used in addition to -fpic when generating
position independent code. This option allows the inlining of global functions. It can be used
as a default option for compiling relocatable libraries:
st200cc -o a.o -fpic -fvisibility=protected a.c
In addition to this option, fine grain visibility can be specified with the
__attribute__((visibility(...)) GNU C extension at the source code level.
For example, if the external interface of a load module is well defined in a header file, the
__attribute__((visibility("protected")) can be attached to each function of
the external interface and on the command line the -fvisibility=hidden option can be
given to specify that all other defined functions are internal to the load module. The main
effect of this combination of options is that references from the same file to global objects
that are not part of the interface will be optimized.
The -mvisibility-decl=<file> option can be used to specify the visibility of each
symbol externally with the given <file>. In the case where the external services required
by a module (default visibility) and the external services provided by the module (protected
visibility) are known, all other functions or data objects can be declared as internal (hidden
visibility). This option can be used to specify these visibility declarations. In this case, only
the functions that are external have an associated overhead. The other internal functions
have a very reduced overhead.
The -ipa option can be used for a full inter procedural optimization of the relocatable
library. In this case, when combined with the declaration of external functions, the library is
generated with a minimal overhead for the dynamic linking support.
For detailed information on the visibility specification, refer to the compiler options
documentation and to the ELF System V Dynamic Linking ABI.

110/170

7521642

ST200

5.6

Relocatable loader library

Debugging support
The debugging of dynamically loaded modules is possible in the same way as for System V
dynamic shared objects. The main module debugging information is loaded at load time of
the application. The load modules debugging information is loaded at load time of the load
modules.
In order to update debugging information, the loader maintains a list of loaded modules
together with their filenames (the file contains the debugging information) and the load
address of the module. Each time a new module is loaded the loader calls a specific
function. The debugger has to set a breakpoint on this specific function and, when the
breakpoint is hit, traverse the list to find new loaded modules and load the debugging
information.
For the ST200 toolset, the debugger implements the required mechanism for the automatic
debugging of loaded modules.
In order to find the file that contains the debug information, the loader must know the path to
the load module. This is automatic in the case of rl_load_file() as the filename is
specified in the interface. For the rl_load_buffer() and rl_load_stream()
functions, the user must set the filename with a call to the rl_set_file_name()
function.
For example, the following code enables automatic debugging of a load module loaded with
rl_load_buffer():
{
int status;
rl_handle_t *handle = rl_handle_new(rl_this(), 0);
if (handle == NULL) { /* error */ }
#ifdef DEBUG_ENABLED
rl_set_filename(handle, "path_to_the_file_for_the_module");
#endif
status = rl_load_buffer(handle, module_image);
if (status == -1) { /* error */ }
...
}

7521642

111/170

Relocatable loader library

5.7

ST200

Profiling support
The action callbacks may be used with a profiling support library, or alternatively, a user
defined package can be informed that a segment has just been loaded or is on the point of
being unloaded by using the user action callback interface.
Below is an example that iterates over the segment list and declares the executable
segments to a profiling support library on the loading/unloading of a module.
static int segment_profile(rl_handle_t *handle, rl_segment_info_t
*info,
void *cookie)
{
rl_action_t action = *((rl_action_t *)cookie);
const char *file_name = handle_file_name(handle);
if (file_name != NULL && (info->seg_flags & RL_SEG_EXEC) {
if (action == RL_ACTION_LOAD) {
/* Call profiling interface for adding a code region. */
profiler_add_region(file_name, info->seg_addr,
info->seg_size);
}
if (action == RL_ACTION_UNLOAD) {
/* Call profiling interface for removing a code region. */
profiler_remove_region(file_name, info->seg_addr,
info->seg_size);
}
}
return 0;
}
static int module_profile(rl_handle_t *handle, rl_action_t action,
void *cookie)
{
rl_foreach_segment(handle, segment_profile, (void *)&action);
return 0;
}
int main()
{
...
if (rl_add_action_callback(RL_ACTION_ALL, module_profile,
NULL)==-1){
fprintf(stderr, "rl_add_Action_callback failed\n");
exit(1);
}
...
status = rl_load_file(handle, file_name);
...
return 0;
}

112/170

7521642

ST200

5.8

Relocatable loader library

Memory protection support

When a new library segment has been loaded into memory or is on the point of being
unloaded from memory, a memory protection scheme can be installed by a system library
(or by the user) using the user action callback interface.
As for the profiling support, the user action callback can be used to set some kind of user
protection support. Refer to Section 5.7.

5.9

Load time decompression

Currently no load time decompression is performed by the loader. This may change in a
future extension, and the loader may load compressed or uncompressed code without
change to the interface.
For loading a compressed image of a load module into memory, the user can use the
rl_load_stream() interface. In this case, it is the responsibility of the user to implement
the decompression of the stream in the callback function.

7521642

113/170

ST200 board support package (BSP)

Appendix A
A.1

ST200

ST200 board support package (BSP)

Introduction to board support packages

This appendix describes the board support package of the bare machine run-time software
for the STMicroelectronics ST200 family of processors.
The BSP provides a set of function calls that allow the user to command low level
functionalities available on ST200-powered systems, such as cache management, timers
programming, performance monitoring and interrupts installation.
The major part of this BSP is based on (and therefore requires) the OS21 real time
operating system, although some low level functionality works without the presence of
OS21.
The functionality of each call with or without OS21 is specified in detail in the context
information for each function description.

A.1.1

Backward compatibility
The R4.0 toolset is compatible with the run-time calls and BSP provided in previous
releases, however this compatibility will disappear in the R4.1 toolset. The compatibility
change will be announced in an engineering release between the R4.0 and R4.1 toolsets.

Caution:

Any bare run-time functionality not specified as described in this document will not be
available in the releases following the R4.0 toolset.

User handles
_sys_install_debug_stub() has been renamed bsp_debug_stub().
_sys_user_start_stub() has been renamed bsp_user_start_handle() and now
returns an int value (RESUME || OVERWRITE). See Section A.11: User handles on
page 129.

Memory protection setting

The calls _sys_memmap() and _sys_memunmap() have been renamed to
bsp_mmu_memory_map() and bsp_mmu_memory_unmap() respectively.

A.1.2

Error handling
All BSP functions, not directly returning a value, return an error condition that assumes one
of the following values:
BSP_OK

if there are no errors,

BSP_FAILURE

if an error occurred.

When an error is detected the global variable unsigned int bsp_errno is set to the
appropriate value at the exit of each BSP call. If there are no errors, bsp_errno is set to
BSP_OK, otherwise it is set to the appropriate error code, as given in Table 22.

114/170

7521642

ST200

ST200 board support package (BSP)

Table 22.

BSP errors
Error

Description

BSP_OK

No errors.

BSP_FAILURE

General error condition.

BSP_EINVAL

An invalid argument is given.

BSP_ECONTEXT

Context error. The call has been called in the

wrong context (usually under OS21, instead of
bare machine mode).

BSP_EINTR

An error occurred installing an interrupt.

BSP_EBUSY

The resource is not available.

BSP_EMAPFAIL

There is an error mapping memory.

BSP_EMFILE

No TLB is available.

BSP_EINTNOTHNDL

The interrupt was not handled.

BSP_EINTNOTPENDING

No pending bits are set.

The function bsp_print_error() is provided to obtain a short error message

corresponding to the error received.

A.2

Caches
All variants of the ST200 processor use caches to reduce the time taken for the CPU to
access memory and greatly increase system performance.
The ST200 provides an instruction cache (I-cache) and a data or operand cache (D-cache).
The I-cache is read only, while the D-cache is read/write. Writes are performed using a
write-back method.
There is a risk when using a data cache that it can become incoherent with main memory,
meaning that the contents of the cache conflicts with the contents of main memory. For
example, devices that perform direct memory access (DMA) modify the main memory
without updating the contents of the cache, potentially leaving its contents invalid. For this
reason extra care should be taken when performing DMA.
On the ST200, the I-cache cannot be disabled, however the D-cache can be selectively
disabled for specific regions of memory. It is also possible to flush specific blocks of memory
from either cache. In this way, application software can safely manage the cache.

A.2.1

Managing the caches

More information on managing the caches is provided in the ST220 Core and Instruction Set
Architecture and ST231 Core and Instruction Set Architecture manuals.
When the D-cache is enabled, any data written to main memory by the CPU is stored in the
D-cache and marked as dirty so that at some point in the future it can be properly stored to
main memory. The BSP ST200 cache API provides a means to purge (that is, to
simultaneously flush and invalidate) specific D-cache lines.
Purging is required when writing to data structures in memory which are accessed through
the D-cache, but are to be shared with another bus master, for instance another CPU, or

7521642

115/170

ST200 board support package (BSP)

ST200

DMA device. BSP provides the user with the ability to manipulate shared data either
avoiding the cache altogether, or through the cache with software cache coherency support.
This allows users maximum flexibility.
In a similar way, the read-only I-cache can be invalidated in order to safely handle dynamic
code loading.

A.2.2

Cache header file: machine/bsp/cache.h

All the definitions related to the cache are in the header file, machine/bsp/cache.h.
Table 23.

Functions defined in machine/bsp/cache.h

Function

Description

bsp_cache_invalidate_instruction()

Invalidates addresses within the specified range

from the instruction cache

bsp_cache_invalidate_instruction_
all()

Invalidates the entire instruction cache

bsp_cache_purge_data()

Purges addresses within the specified range from

the data cache

bsp_cache_purge_data_all()

Purges the entire data cache

A.3

Instruction and data protection unit

A.3.1

IPU/DPU support functions

Some variants of the ST200 (up to and including ST220) include an IPU and a DPU. The
IPU controls instruction fetches from memory, while the DPU controls data loads and stores
to and from memory.
The IPU allows protection attributes to be specified for instruction fetches for a region of
memory.
The DPU allows protection and cacheability attributes for data loads and stores, and also
allows speculation attributes for data loads to be specified for a region of memory.
Full details of the IPU and DPU can be found in the appropriate hardware manuals.

A.3.2

Initializing the IPU/DPU support system

When the ST200 comes out of reset, both the IPU and the DPU are disabled. Therefore all
data memory accesses are uncached. The C run-time boot sequence programs both the
IPU and the DPU with an appropriate default programming for the given hardware and
then enables them.

116/170

7521642

ST200

A.3.3

ST200 board support package (BSP)

Managing the IPU/DPU

For ST200 variants that support an IPU/DPU, the BSP provides the functions listed in
Table 24 to manipulate the protection units.
Table 24.

Functions defined in machine/bsp/xpu.h

Function

A.3.4

Description

bsp_dpu_enable()

Enable the Data Protection Unit

bsp_dpu_disable()

Disable the Data Protection Unit

bsp_ipu_enable()

Enable the Instruction Protection Unit

bsp_ipu_disable()

Disable the Instruction Protection Unit

bsp_dpu_region_get()

Returns the settings for a region

bsp_dpu_region_set()

Write the settings for a region

bsp_ipu_region_get()

Returns the settings for a region

bsp_ipu_region_set()

Write the settings for a region

OS21 BSP for DPU/IPU

All the OS21 definitions relating to the IPU/DPU are in the header file os21/st200/xpu.h.
See Table 25 and Table 26, these are explained in the OS21 for ST200 User Manual.
Table 25.

Functions defined in os21/st200/xpu.h

Function

Description

dpu_config()

Configures the DPU

ipu_config()

Configures the IPU

Table 26.

Types defined in os21/st200/xpu.h

Type

A.4

Description

protection_list_t

Describes a memory region and its attributes

protection_flags_t

Alters the ipu_config()/dpu_config()

behavior

Memory management
Some variants of the ST200 processor (ST231 onwards) support a memory management
unit (MMU) and a speculative load control unit (SCU). The MMU provides hardware which
controls the D-cache behavior across address ranges, as well as performing the traditional
role of controlling virtual address translation and protection. The MMU contains a fixed
number of translation look aside buffers (TLBs) which describe and control the virtual
address space on the system.
The SCU controls whether or not speculative (sometimes called dismissible) loads from
physical address ranges are allowed. The SCU contains a fixed number of entries which are
used to enable speculative loads for certain physical address ranges.

7521642

117/170

ST200 board support package (BSP)

A.4.1

ST200

Initial memory map

When the ST200 comes out of reset, the MMU is disabled. In this mode all data fetches are
uncached.
The C run-time boot sequence programs the MMU to contain an identity mapping for system
RAM with caching enabled and programs the SCU so that speculation is enabled for this
RAM. It then enables the MMU, and the ST200 starts running from a virtual address space.
Since the mapping set up in the TLBs by the bare run-time is an identity mapping, the
system RAM appears in the virtual address space at the same addresses as it does in the
physical address map.
Table 27.

Initial memory map

Start address

A.4.2

Size

Supervisor /
User priv.

Cacheable

Description

__text_start

8 MBytes

rwx/rwx

Yes

RAM read/write/execute.

0x00000000

8 KBytes

rwx/rwx

No

boot ROM

Peripheral_base

16 KBytes

rw--/----

No

Peripheral registers.

Peripheral_base +
0x4000

8 KBytes

r--x/----

No

DSU ROM

Managing the MMU

More information on managing the MMU is provided in the ST231 Core and Instruction Set
Architecture Manual.
The bare run-time Board Support Package only provides a minimal support for the MMU
and SCU; OS21 BSP will provide a more extended API for MMU and SCU modules. Bare
machine API for MMU can not be invoked after the OS21 run-time start up.

A.4.3

MMU header file: machine/bsp/mmu.h

All the definitions related to the MMU available in bare run-time environment are in the
single header file, machine/bsp/mmu.h, see Table 28.
Table 28.

Functions defined in bsp/mmu.h

Function

Description

bsp_mmu_reset()

Reset TLB settings

bsp_mmu_memory_map()

Map pages of program address space into ST200

physical addresses and set protections

bsp_mmu_memory_unmap()

Unmap pages of memory

bsp_mmu_dump_TLB_Settings()

Write on the stdio a list of TLBs with their

attributes

All the definitions relating to virtual memory accessible using the OS21 BSP are in the
header file os21/st200/mmap.h, see Table 29. These are explained in the OS21 for
ST200 User Manual.

118/170

7521642

ST200

ST200 board support package (BSP)

Table 29.

Functions defined in os21/st200/mmap.h

Function

A.4.4

Description

mmap_create()

Create a mapped address range

mmap_delete()

Remove a mapped address range

mmap_disable_speculation()

Disable speculative loads for a region

mmap_enable_speculation()

Enable speculative loads for a region

mmap_pagesize()

Return an MMU page size

mmap_translate_cached()

Return a cached view of a virtual address

mmap_translate_physical()

Return the physical address for a virtual address

mmap_translate_uncached()

Return an uncached view of a virtual address

mmap_translate_writecombined()

Return a write-combined uncached view of a

virtual address

Speculative control unit (SCU)

The SCU filters physical speculative load addresses (both cached and uncached) and
prefetches that miss the cache to ensure that speculative bus requests are not sent out to
peripherals and unmapped memory regions.
The SCU supports four regions of memory aligned to the smallest TLB page size (8 Kbytes).
If the physical address of the speculative load/prefetch address falls within one of the four
supported regions it will be allowed, otherwise the SCU aborts the speculative load/prefetch
and zero is returned or the prefetch is cancelled.
The regions are configured using the SCU_BASEx and SCU_LIMITx control registers.
The SCU resets so each of the four regions cover the whole of memory. This allows
speculative loads to be issued before the SCU has been initialized.

SCU header file: machine/bsp/mmap.h

All the definitions related to the SCU available in bare run-time environment are in the single
header file, machine/bsp/mmap.h, see Table 30.
Table 30.

Functions defined in bsp/mmap.h

Function

Description

bsp_scu_read()

Read the settings of the region

bsp_scu_write()

Write the start and end address of a region

bsp_scu_disable()

Disable a region

bsp_scu_dump_SCU_Settings()

Write on the stdio a list of SCU regions with their

address and size

The functions bsp_scu_read() and bsp_scu_write() use a struct to define start and
end addresses.

7521642

119/170

ST200 board support package (BSP)

ST200

typedef struct
{
void * start_address;
void * end_address;
} bsp_scu_entry_t;
The two addresses are rounded to be aligned to the smallest TLB page size.

A.5

Timers
The ST200 has three independent timers. Each is capable of running as a free running
auto-reload 32-bit counter, with interrupt on underflow. Each can be programmed to count
some fraction of the input clock. Time is represented in clock ticks, with the bsp_clock_t
type. This is defined to be a signed 64-bit integer.

A.5.1

Input clock frequency

The precise speed of the input clock is determined by the end user; it is a function of the
board design and boot software.

A.5.2

Tick duration
ST200 BSP establishes the period of one tick when it boots. Based on the input clock
frequency it selects an appropriate divisor to yield a tick which is approximately
1 microseconds.

A.5.3

Reading the current time

The value of system time is read using bsp_timer_now().
#include <machine/bsp/timer.h>
bspclock_t bsp_timer_now(void);

A.5.4

ST200 timer assignments

ST200 BSP uses the Timer0 as system timer and Timer1 only if the profiling is enabled,
Timer2 is always free for users (Timer1 is also available for users if the profiling feature is
not enabled).
Table 31.

ST200 timer assignments

Timer name

BSP usage

TIMER_SYSTEM

System timer

TIMER_PROFILER

Profiling timer

TIMER_USER1

User timer 1

TIMER_USER2

User timer 2 (only available if profiler is not

present)

The system timer is left free running and is used by bsp_timer_now() to return the
system time. On ST200, the system time (bsp_clock_t) is a 64-bit value. ST200 BSP
maintains the top 32 bits of the 64-bit time via an interrupt handler which is called each time

120/170

7521642

ST200

ST200 board support package (BSP)

the 32-bit timer reaches zero. The lower 32 bits of the system time are the value in the
system timer.
The profiling timer is programmed to the profiling sampling interval if the profiling feature is
enabled; otherwise it is available for the user (as TIMER_USER2)
The user timer 1 is always available for the user.

Hardware abstraction layer (HAL) for the ST200 timer module

The BSP has a set of functions to help the user to program the timer directly acting on the
timer registers hiding the differences between ST200 cores. These functions are not
checked against conflicts against other timer functions (for example, bsp_timer_now())
and should be only used to program user timer 2 and eventually the user timer 1 if the
profiling is not enabled.
Table 32.

Functions defined in machine/bsp/timer.h

Functions

Description

bsp_timer_start()

Start the timer.

bsp_timer_start_all()

Start all the timers

bsp_timer_stop()

Stop the timer.

bsp_timer_divide_set()

Set the TIMEDIVIDE registry

bsp_timer_divide_get()

Get the TIMEDIVIDE registry

bsp_timer_count_set()

Set the initial value of the counter of the specific

timer

bsp_timer_count_get()

Get the initial value of the counter of the specific

timer

bsp_timer_reload_set()

Set the value to be reloaded into the specific timer

on reaching zero

bsp_timer_reload_get()

Get the reload value of the specific timer

bsp_timer_interrupt_enable()

Enable the timer interrupts the processor

bsp_timer_interrupt_disable()

Disable the timer interrupt

bsp_timer_interrupt_clear()

Clear the timer interrupt

7521642

121/170

ST200 board support package (BSP)

A.5.5

ST200

Timer header file: machine/bsp/timer.h

All the definitions related to the timer available in bare run-time environment are in the single
header file machine/bsp/timer.h, see Table 33 and Table 34.
Table 33.

Functions defined in machine/bsp/timer.h

Function

Description

bsp_timer_now()

Return the current time

bsp_timer_user()

Set a user timer, eventually attach an interrupt

handle and enable the corresponding interrupt.

bsp_timer_ticks_per_sec()

Returns the number of clock ticks per second

bsp_timer_count_mode()

Defines the behavior of the system timer during

oscalls and debug events.

Table 34.

Types defined by machine/bsp/timer.h

Type

Description
Number of processor clock ticks

bspclock_t

All the definitions relating to virtual memory accessible using the OS21 BSP are in the
header file os21/ostime.h, see Table 35. These are explained in the OS21 for ST200
User Manual.
Table 35.

Functions defined in os21/ostime.h

Function

122/170

Description

time_after()

Returns whether one time is after another

time_minus()

Subtracts two clock values

time_now()

Returns the current time

time_plus()

Adds two clock values

time_ticks_per_sec()

Returns the number of ticks per second

7521642

ST200

A.6

ST200 board support package (BSP)

Performance monitor (PM)

The PM module provides a hardware instrumentation system that allows the user to
simultaneously monitor up to four events in a variable set of predefined events.
The events listed in Table 36 can be monitored.
Table 36.

PM HAL macros
Events

Comment

ST220

ST231

DHIT

Data cache hit.

DMISS

Data cache miss.

DMISSCYCLES

The number of cycles the core is stalled due

to the data cache being busy.

PFTISSUED

The number of prefetches that are sent to the

X
bus.

PFTHITS

The number of cached loads that hit the

prefetch buffer.

WBHITS

The number of cached writes that hit the write

X
buffer.

IHIT

The number of accesses the instruction buffer

X
made that hit the instruction cache.

IMISS

The number of accesses the instruction buffer

X
made that missed the instruction cache.

IMISSCYCLES

The number of cycles the instruction cache

was stalled.

IBUFINVALID

Duration where I Buffer is not able to issue

bundles to the pipeline.

BUNDLES

Bundles executed.

LDST

Load/Store instructions executed.

TAKENBR

Number of taken branches (br and brf), rfis,

gotos and calls.

NOTTAKENBR

Number of not taken branches (br and brf).

EXCEPTIONS

Number of exceptions and interrupts.

INTERRUPTS

Number of interrupts.

BUSREADS

Number of architectural read transactions

issued to the bus. This is the number of
uncached reads, I- and D-cache refills and
prefetches issued to the bus.

BUSWRITES

Number of architectural write transactions

issued to the bus. This is the number of write
buffer lines evicted and the number of
uncached writes issued to the bus.

OPERATIONS

Number of completed operations. Includes

nops in the instruction stream but not those
added dynamically. This counter excludes
long immediate.

7521642

123/170

ST200 board support package (BSP)

Table 36.

ST200

PM HAL macros (continued)

Events

A.6.1

Comment

ST220

ST231

WBMISSES

Number of cached writes that missed the

cache and misses the write buffer. This
excludes cache line evictions.

NOPBUNDLES

Number of completed bundles that were

empty or contained only nops. This includes
nop bundles generated by instruction buffer
stalls and interlocking stalls. It excludes
pipeline stalls due to load/stores and control
register/sdi accesses.

LONGIMMEDIATES

Long immediates.

ITLBMISS

ITLB misses.

DTLBMISS

DTLB misses.

UTLBHITS

UTLB hits (number of load/stores that hit the

UTLB).

ITLBWAITCYCLES

Number of cycles the instruction cache

spends waiting for the ITLB to fill.

DTLBWAITCYCLES

Number of cycles the data cache spends

waiting for the DTLB to fill.

UTLBARBITRATIONCYCLES

Number of cycles where the ITLB or DTLB

spends waiting for access to the UTLB
because the UTLB was busy servicing a
request.

Hardware abstraction layer for the PM module

The BSP has a set of functions to help the user to program the performance monitor directly
acting on the registers, see Table 37.
Table 37.

Functions defined in machine/bsp/pm.h

Functions

124/170

Description

bsp_pm_reset()

Reset all counters

bsp_pm_start()

Start all the event counters

bsp_pm_stop()

Stop all the event counters

bsp_pm_clock_get()

Read the PM Clock counter

bsp_pm_clock_set()

Write the PM Clock counter

bsp_pm_count_mode()

Define the PM behavior during oscalls and debug

events

bsp_pm_counter_get()

Read the current value of a PM counter

bsp_pm_counter_set()

Write/change the current value of a PM counter

bsp_pm_event_get()

Returns the event monitored by the PM counter

bsp_pm_event_set()

Set the event being monitored by a PM counter

7521642

ST200

A.7

ST200 board support package (BSP)

Exception handling
Exceptions on the ST200 can occur for the following reasons:

program request (syscall instruction),

external interrupt,

program error (such as, misaligned access, bad instruction, failed protection check).

After the BSP initialization only external interrupts are handled.

The default behavior when an unexpected exception occurs is to print a message detailing
the exception, dump the whole context and then shut down by calling _exit().
The user can provide new handlers for all the exceptions replacing those currently installed
using the function bsp_core_interrupt_install().
All external interrupts are treated as BSP_CORE_EXTERN_INT exceptions; the interrupt
dispatcher is set during the BSP initialization.

A.7.1

Exceptions types
The exceptions that can occur for an ST220 core are given in Table 38 and the exceptions
that can occur for ST231 cores are given in Table 39.
Table 38.

ST220 exceptions defined in machine/bsp/core.h

ST220 exceptions

BSP_CORE_STBUS_IC_ERROR
BSP_CORE_STBUS_DC_ERROR
BSP_CORE_EXTERN_INT
BSP_CORE_IBREAK
BSP_CORE_IPU_NO_TRANSLATION
BSP_CORE_IPU_ACCESS_VIOLATION
BSP_CORE_SBREAK
BSP_CORE_ILL_INST
BSP_CORE_DBREAK
BSP_CORE_MISALIGNED_TRAP
BSP_CORE_CREG_NO_MAPPING
BSP_CORE_CREG_ACCESS_VIOLATION
BSP_CORE_DPU_NO_TRANSLATION
BSP_CORE_DPU_ACCESS_VIOLATION
BSP_CORE_SDI_TIMEOUT

7521642

125/170

ST200 board support package (BSP)

Table 39.

ST200

ST231 exceptions defined in machine/bsp/core.h

ST231 exceptions

BSP_CORE_STBUS_IC_ERROR
BSP_CORE_STBUS_DC_ERROR
BSP_CORE_EXTERN_INT
BSP_CORE_IBREAK
BSP_CORE_ITLB
BSP_CORE_SBREAK
BSP_CORE_ILL_INST
BSP_CORE_SYSCALL
BSP_CORE_DBREAK
BSP_CORE_MISALIGNED_TRAP
BSP_CORE_CREG_NO_MAPPING
BSP_CORE_CREG_ACCESS_VIOLATION
BSP_CORE_DTLB
BSP_CORE_SDI_TIMEOUT

The exception handlers are defined as:

typedef int (*InterruptVector_t)(regcontext *);
For example:
int MySyscallHandle( regcontext *regs)
{
DoSomething();
bsp_errno = BSP_OK;
return (BSP_OK);
}
main ()
{
InterruptVector_t OldHandler;
InterruptVector_t NewHandler;
...
NewHandler = MySyscallHandle;
bsp_core_interrupt_install( &NewHandler,
&OldHandler,
BSP_CORE_MISALIGNED_TRAP);
...
}

126/170

7521642

ST200

A.7.2

ST200 board support package (BSP)

Exceptions header file: machine/bsp/core.h

All the definitions related to the exception handling are in the single header file,
machine/bsp/core.h.
Table 40.

Functions defined in machine/bsp/core.h

Functions

A.8

Description

bsp_core_interrupt_install()

Install an exception handler for a specified

exception cause

bsp_core_interrupt_lock()

Disable external interrupts at core level

bsp_core_interrupt_unlock()

Enable external interrupts at core level

Interrupts
Interrupts are events external to the CPU that are signaled to it via sampled lines. When an
interrupt occurs, an interrupt handler is executed, interrupting the normal flow of execution of
the CPU. The normal execution flow is resumed after the interrupt handler terminates. This
BSP provides means of interrupt management that is intended to be used solely in absence
of the OS21 real time operating system.
The ST200 cores have 64 lines of external interrupts. A subset of these lines can be masked
(that is, disabled) individually. The first three lines are connected to the three system timers
0, 1 and 2. The remaining 61 lines are connected to system specific subsystems.
The system specific (core, SoC, board) datasheets must be referred to for specific
information about the maskable interrupt lines and other information.

A.8.1

Interrupt handler installation

An interrupt handler is a user defined function that is designed to be executed whenever a
particular interrupt line is raised. This API provides the means to specify and install user
defined interrupt handlers. The interrupt handler has to return BSP_OK in case of success
(interrupt correctly installed) or BSP_FAILURE (and bsp_errno set to the corresponding
error number) in case of failure.

A.8.2

Interrupts header file: machine/bsp/interrupt.h

All the definitions related to the interrupts available in bare run-time environment are in the
single header file, machine/bsp/interrupt.h, see Table 41.
Table 41.

Functions defined in machine/bsp/interrupt.h

Function

Description

bsp_itc_interrupt_clear()

Clears an interrupt

bsp_itc_interrupt_disable()

Disable an interrupt

bsp_itc_interrupt_enable()

Enable an interrupt

bsp_itc_interrupt_install()

Installs an interrupt handler

bsp_itc_interrupt_poll()

Polls an interrupt

7521642

127/170

ST200 board support package (BSP)

Table 41.

ST200

Functions defined in machine/bsp/interrupt.h (continued)

Function

A.9

Description

bsp_itc_interrupt_raise()

Raises an interrupt

bsp_itc_interrupt_uninstall()

Uninstalls an interrupt handler

OScalls and debug events suspension

The time spent during oscalls (I/O on the host machine) and during debug events is
unpredictable. For benchmarking purposes it is possible to define the behavior of the
system timer and performance monitor counters during these events. Two functions have
been defined for this purpose bsp_timer_count_mode() and bsp_pm_count_mode().

A.10

Flash file system handling

Dynamic libraries and, in general, all the modules that are stored in the Flash can be
accessed using the bsp_ffs_fopen() and bsp_ffs_fread() functions provided in the
BSP. These functions completely hide the structure of the Flash to the user and the nature of
modules stored.
Table 42.

Functions defined in machine/bsp/ffs.h

Function

Description

bsp_ffs_dir()

Lists the modules stored in Flash

bsp_ffs_fopen()

Open a module stored in Flash

bsp_ffs_fclose()

Close the connection with the file

bsp_ffs_fread()

Read n bytes from the Flash module

bsp_ffs_showboot()

Display boot information

The following fragment of code shows how to use this callback.

file = bsp_ffs_fopen((const char *)Id1, FFS_O_RDONLY);
if ( BSP_FAILURE == (int)file )
{
fprintf(stderr,"Error: bsp_ffs_fopen failed: \n");
exit(-1);
}
res=rl_load_stream(rlHndl,(rl_stream_func_t *) bsp_ffs_fread,
(void *)file);
if (res == -1)
{
fprintf(stderr,"Error: rl_load_stream failed: %s %d\n",
rl_errstr(rlHndl),rl_errno(rlHndl));
exit(-1);
}
bsp_ffs_close(file);

128/170

7521642

ST200

A.11

ST200 board support package (BSP)

User handles
User handles are used to give to the user code the capability to modify the BSP initialization
behavior. These handles are optional and can be omitted if standard behavior is in line with
user expectation.
The available user handles are listed in Table 43.
Table 43.

User handles
User handle

Description

bsp_user_start_handle

User handle called at the start of the BSP

initialization

bsp_user_end_handle

User handle called at the end of the BSP

initialization

bsp_user_start_handle
User handle called at the start of the BSP initialization
Definition:

int (* bsp_user_start_handle)(void);

Arguments:

None.

Returns:
RESUME

The execution continues in the standard BSP

initialization.

OVERWRITE

bsp_user_start_handle() handles all of the BSP

initialization and the standard initialization is skipped.

Description:

If this function is defined by the user it is invoked at the start of the BSP initialization.
At this stage, this function is in supervisor mode and nothing of the BSP has been
initialized (no memory management and timer initialization).

Example:

int user_stub (void)

{
kprintf("At the start of BSP init\n");
Dosomething();
return RESUME; /* Continue with standard BSP init */
}
/*
* Initialize the function pointer defined in the libcore.a
*/
int (* bsp_user_start_handle)(void)=user_stub;

7521642

129/170

ST200 board support package (BSP)

ST200

bsp_user_end_handle
User handle called at the end of the BSP initialization
Definition:

void (* bsp_user_end_handle)(void);

Arguments:

None.

Returns:

None.

Description:

If this function is defined by the user it is invoked at the end of the BSP initialization.
At this stage, this function is in the mode requested (the default is supervisor) and the
BSP has been initialized. This function is called before main().

Note: This function is only invoked in the standard flow of BSP initialization, this means that
if bsp_user_start_handle() has been used it returns the RESUME value.
Example:

void user_stub (void)

{
kprintf("At the end of BSP init\n");
Dosomething();
}
/*
* Initialize the function pointer defined in libcore.a
*/
void (* bsp_user_end_handle)(void)=user_stub;

130/170

7521642

ST200

A.12

ST200 board support package (BSP)

BSP function definitions

bsp_cache_invalidate_instruction
Invalidate addresses within the specified range from the
instruction cache
Definition:

#include <platform.h>
int bsp_cache_invalidate_instruction (
void * base_address,
size_t length);

Arguments:
base_address

The start address of the range to invalidate.

length

The length of the range in bytes.

Returns:

Returns the error condition.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time. In OS21, this function
directly invokes the cache_invalidate_instruction() function provided from
OS21 BSP.

Description:

This function invalidates any valid instruction cache lines that fall within the address
range specified. If it is not possible to flush individual cache lines, then the entire
instruction cache is invalidated.

See also:

bsp_cache_invalidate_instruction_all

bsp_cache_invalidate_instruction_all
Invalidate the entire instruction cache
Definition:

#include <platform.h>
int bsp_cache_invalidate_instruction_all (void);

Arguments:

None.

Returns:

Returns the error condition.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time. In OS21, this function
directly invokes the cache_invalidate_instruction_all() function provided
from OS21 BSP.

Description:

This function invalidates the entire instruction cache.

See also:

bsp_cache_invalidate_instruction

7521642

131/170

ST200 board support package (BSP)

ST200

bsp_cache_purge_data
Purge addresses within the specified range from the data cache
Definition:

#include <platform.h>
int bsp_cache_purge_data(
void * base_address,
size_t length );

Arguments:
base_address

The start address of the range to purge.

length

The length of the range in bytes.

Returns:

Returns the error condition.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time. In OS21, this function
directly invokes the cache_purge_data() function provided from OS21 BSP.

Description:

This function purges any valid data cache lines which fall within the address range
specified. Any dirty cache lines are first written back to memory, and then the cache
lines are invalidated.

See also:

bsp_cache_purge_data_all

bsp_cache_purge_data_all
Purge the entire data cache
Definition:

#include <platform.h>
int bsp_cache_purge_data_all (void);

Arguments:

None.

Returns:

Returns the error condition.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time. In OS21, this function
directly invokes the cache_purge_data_all() function provided from OS21 BSP.

Description:

This function purges any valid data cache lines within the D-cache. Any dirty cache
lines are first written back to memory, and then the cache lines are invalidated.

See also:

bsp_cache_purge_data

132/170

7521642

ST200

ST200 board support package (BSP)

bsp_core_interrupt_install
Install an exception handler for a specified exception cause
Definition:

#include <platform.h>
int bsp_core_interrupt_install (
InterruptVector_t* NewExceptionHandler,
InterruptVector_t* OldExceptionHandler,
int ExceptionNumber );

Arguments:

Returns:

NewExceptionHandler

The exception handler to attach to the specified

exception.

OldExceptionHandler

The previously installed exception handler.

ExceptionNumber

The exception to which the handler has to be attached.

Upon successful completion, bsp_core_interrupt_install() returns BSP_OK;

otherwise, it returns BSP_FAILURE and sets bsp_errno to indicate an error.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

BSP_EINVAL

ExceptionNumber is an invalid exception number.

Context:

Callable only from bare machine run-time. In the OS21 environment, the exceptions
are handled exclusively through the OS21 interface.

Description:

This function installs the exception handler for the exception specified in
ExceptionNumber.

See also:

bsp_core_interrupt_lock, bsp_core_interrupt_unlock

bsp_core_interrupt_lock
Disable external interrupts at core level
Definition:

#include <platform.h>
int bsp_core_interrupt_lock (void);

Arguments:

None.

Returns:

Upon successful completion, bsp_core_interrupt_lock() returns BSP_OK;

otherwise, it returns BSP_FAILURE and sets bsp_errno to indicate an error.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. In the OS21 environment, the exceptions
are handled exclusively through the OS21 interface.

Description:

This function disables all external interrupts at core level.

See also:

bsp_core_interrupt_install, bsp_core_interrupt_unlock

7521642

133/170

ST200 board support package (BSP)

ST200

bsp_core_interrupt_unlock
Enable external interrupts at core level
Definition:

#include <platform.h>
int bsp_core_interrupt_unlock (void);

Arguments:

None.

Returns:

Upon successful completion, bsp_core_interrupt_unlock() returns BSP_OK;

otherwise, it returns BSP_FAILURE and sets bsp_errno to indicate an error.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. In the OS21 environment, the exceptions
are handled exclusively through the OS21 interface.

Description:

This function enables all external interrupts at core level.

See also:

bsp_core_interrupt_install, bsp_core_interrupt_lock

bsp_dpu_disable
Disable the Data Protection Unit
Definition:

#include <platform.h>
int bsp_dpu_disable(void);

Arguments:

None.

Returns:

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time.

Description:

This function disables the data protection unit.

See also:

bsp_dpu_enable

134/170

7521642

ST200

ST200 board support package (BSP)

bsp_dpu_enable
Enable the Data Protection Unit
Definition:

#include <platform.h>
int bsp_dpu_enable(void);

Arguments:

None

Returns:

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time.

Description:

This function enables the data protection unit.

See also:

bsp_dpu_disable

bsp_dpu_region_get
Return the settings for a region
Definition:

#include <platform.h>
int bsp_dpu_region_get(
unsigned int regno,
void **base,
unsigned int *logsize,
unsigned int *mode );

Arguments:

Returns:

regno

The region number.

base

The base address of the region.

logsize

log2 of the size of the data region to be protected integer in the range of 12 to 32 (corresponding to
4 Kbytes to 4 Gbytes).

mode

The region mode, see Table 44.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

BSP_EINVAL

regno is an invalid region number.

Context:

Callable only from bare machine run-time. OS21 run-time uses dpu_config().

Description:

This function returns the settings for a DPU region.

The working mode of a DPU region is given in the mode argument. It consists of
OR-ed values of the defined constants described in Table 44.

7521642

135/170

ST200 board support package (BSP)

Table 44.

ST200

Configuration mode constants of the DPU

Constant

See also:

Description

Notes

DPU_REGION_ENABLED

Region enabled

DPU_SPECULATIVE_RETURN_ZERO

Speculative loads return

zero

DPU_REGION_CACHEABLE

Region cacheable

DPU_SUPERVISOR_RDWR

Supervisor readable and

writable region

If unset, an access
violation exception is
raised on access

DPU_USER_READ

User readable region

Implies
DPU_SUPERVISOR_RDWR

DPU_USER_WRITE

User writable region

Implies DPU_USER_READ
and
DPU_SUPERVISOR_RDWR

bsp_dpu_region_set

bsp_dpu_region_set
Write the settings for a region
Definition:

#include <platform.h>
int bsp_dpu_region_set(
unsigned int regno,
void *base,
unsigned int logsize,
unsigned int mode);

Arguments:

Returns:

regno

The region number.

base

The base address of the region.

logsize

log2 of the size of the data region to be protected integer in the range 12 to 32 (corresponding to 4 Kbytes
to 4 Gbytes).

mode

The region mode, see Table 44 on page 136 for details.

Returns the error condition.

Errors:

Context:

136/170

BSP_ECONTEXT

The function was called in the OS21 environment.

BSP_EINVAL

regno is an invalid region number.

Callable only from bare machine run-time. OS21 run-time uses dpu_config().

7521642

ST200

ST200 board support package (BSP)

bsp_ffs_dir
List the information available for the modules stored in Flash
Definition:

#include <platform.h>
int bsp_ffs_dir(void);

Arguments:

None.

Returns:

Returns BSP_OK.

Context:

Callable from bare and OS21 machine run-time.

Description:

The bsp_ffs_dir() function lists the information available for the modules stored in
Flash.

bsp_ffs_fclose
Deallocates the Flash file descriptor and closes the associated file
Definition:

#include <platform.h>
int bsp_ffs_fclose(
ffsHndl_t stream);

Arguments:
stream

The Flash file descriptor received using

bsp_ffs_open().

Returns:

Returns BSP_OK.

Context:

Callable from bare and OS21 machine run-time.

Description:

The bsp_ffs_fclose() function causes the Flash file descriptor pointed to by

stream to be deallocated and the associated file to be closed. The stream is
disassociated from the file. If the associated buffer was automatically allocated, it is
deallocated.

7521642

137/170

ST200 board support package (BSP)

ST200

bsp_ffs_fopen
Open a file and associate a stream with it
Definition:

#include <platform.h>
ffsHndl_t bsp_ffs_fopen(
constant char *f_name,
unsigned int mode);

Arguments:

Returns:

f_name

The identifier of the file to be opened.

mode

This value indicates the way to access the file. In the

current version only FFS_O_RDONLY is supported.

Returns a Flash file descriptor for the named file or BSP_FAILURE in case of errors.
This descriptor is unique and has to be used in the next calls to bsp_ffs_fread()
and bsp_ffs_fclose().

Errors:
BSP_EINVAL

bsp_ffs_fopen() has been called with an invalid

mode. The identifier f_name has not been found in
Flash.

BSP_FAILURE

There is not enough space for memory allocation of

handle or buffers or an error occurred during inflate
initialization in case of compressed files.

Context:

Callable from bare and OS21 machine run-time.

Description:

The bsp_ffs_fopen() function opens the file whose identifier is the string pointed
to by f_name, and associates a stream with it.

138/170

7521642

ST200

ST200 board support package (BSP)

bsp_ffs_fread
Accesses rl_lib to read an array from the flash file system.
Definition:

#include <platform.h>
int bsp_ffs_fread
void *cookie,
char *buffer,
int nbytes);

Arguments:
cookie

The Flash file descriptor received from

bsp_ffs_fopen() (cast to void *)

buffer

The buffer in which to copy or inflate data extracted from

Flash.

nbytes

The number of bytes to read.

Returns:

Returns the effective number of bytes read or -1 in case of error.

Context:

Callable from bare and OS21 machine run-time.

Description:

The bsp_ffs_fread() function is a callback function defined in the BSP support for
Flash file systems. The format of this function, type and sequence of arguments and
return value, is defined in the relocatable loader library (rl_lib 1.6 onwards), see
Chapter 5: Relocatable loader library on page 90. The bsp_ffs_fread() function
provides a way to access rl_lib for reading in to the array pointed to by buffer,
nbytes of data from the Flash file system regardless if the original file is stored in
flash as compressed or not.
The Flash file descriptor received from the bsp_ffs_fopen() is passed to the
rl_load_stream() function in its cookie argument (cast to a void *); this
function then passes this cookie to the bsp_ffs_fread().
The following fragment of code shows how to use this callback.
file = bsp_ffs_fopen((const char *)Id1, FFS_O_RDONLY);
if ( BSP_FAILURE == (int)file )
{
fprintf(stderr,"Error: bsp_ffs_fopen failed: \n");
exit(-1);
}
res=rl_load_stream(rlHndl,(rl_stream_func_t *) bsp_ffs_fread,
(void *)file);
if (res == -1)
{
fprintf(stderr,"Error: rl_load_stream failed: %s %d\n",
rl_errstr(rlHndl),rl_errno(rlHndl));
exit(-1);
}
bsp_ffs_close(file);

7521642

139/170

ST200 board support package (BSP)

ST200

bsp_ffs_showboot
List the boot information available in Flash
Definition:

#include <platform.h>
int bsp_ffs_showboot(void);

Arguments:

None.

Returns:

Returns BSP_OK.

Context:

Callable from bare and OS21 machine run-time.

Description:

The bsp_ffs_showboot() function lists the boot information available in Flash.

bsp_ipu_disable
Disable the Instruction Protection Unit
Definition:

#include <platform.h>
int bsp_ipu_disable(void);

Arguments:

None.

Returns:

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time.

Description:

This function disables the instruction protection unit.

See also:

bsp_ipu_enable

bsp_ipu_enable
Enable the Instruction Protection Unit
Definition:

#include <platform.h>
int bsp_ipu_enable(void);

Arguments:

None.

Returns:

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time.

Description:

This function enables the instruction protection unit.

See also:

bsp_ipu_disable

140/170

7521642

ST200

ST200 board support package (BSP)

bsp_ipu_region_get
Return the settings for a region
Definition:

#include <platform.h>
int bsp_ipu_region_get(
unsigned int regno,
void **base,
unsigned int *logsize,
unsigned int *mode);

Arguments:

Returns:

regno

The region number.

base

The base address of the region.

logsize

log2 of the size of the data region to be protected integer in the range 12 to 32 (corresponding to 4 Kbytes
to 4 Gbytes).

mode

The region mode, see Table 45.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

BSP_EINVAL

regno is an invalid region number.

Context:

Callable only from bare machine run-time. OS21 run-time uses ipu_config().

Description:

This function returns the settings for an IPU region.

The working mode of an IPU region is given in the mode argument. It consists of
OR-ed values of the defined constants described in Table 45.
Table 45.

Configuration mode constants of the IPU

Constant

Description

IPU_REGION_ENABLED

Region enabled

IPU_REGION_CACHEABLE

Cacheable region

IPU_SUPERVISOR_EXEC

Supervisor executable

IPU_USER_EXEC

User executable

7521642

Notes

Implies
IPU_SUPERVISOR_EXEC

141/170

ST200 board support package (BSP)

ST200

bsp_ipu_region_set
Write the settings for a region
Definition:

#include <platform.h>
int bsp_ipu_region_set(
unsigned int regno,
void *base,
unsigned int logsize,
unsigned int prot );

Arguments:

Returns:

regno

The region number.

base

The base address of the region.

logsize

log2 of the size of the data region to be protected integer in the range 12 to 32 (corresponding to 4 Kbytes
to 4 Gbytes).

mode

The region mode, see Table 45 on page 141.

Returns the error condition.

Errors:

Context:

BSP_ECONTEXT

The function was called in the OS21 environment.

BSP_EINVAL

regno is an invalid region number.

Callable only from bare machine run-time. OS21 run-time uses ipu_config().

bsp_itc_interrupt_clear
Clear a specific interrupt
Definition:

#include <platform.h>
int bsp_itc_interrupt_clear(
int interrupt_number);

Arguments:
interrupt_number
Returns:

The interrupt to clear.

Returns the error condition.

Errors:
BSP_EBUSY

The interrupt is not installed.

BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from simple bare machine run-time. In the OS21 environment, the
interrupts are handled exclusively through the OS21 interface.

Description:

This function clears a specific interrupt.

142/170

7521642

ST200

ST200 board support package (BSP)

bsp_itc_interrupt_disable
Disable a specific interrupt
Definition:

#include <platform.h>
int bsp_itc_interrupt_disable(
int interrupt_number);

Arguments:
interrupt_number
Returns:

The interrupt to enable.

Returns the error condition.

Errors:
BSP_EBUSY

The interrupt is not installed.

BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from simple bare machine run-time. In the OS21 environment, the
interrupts are handled exclusively through the OS21 interface.

Description:

This function disables a specific interrupt.

bsp_itc_interrupt_enable
Enable a specific interrupt
Definition:

#include <platform.h>
int bsp_itc_interrupt_enable(
int interrupt_number);

Arguments:
interrupt_number
Returns:

The interrupt to enable.

Returns the error condition.

Errors:
BSP_EBUSY

The interrupt is not installed.

BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from simple bare machine run-time. In the OS21 environment, the
interrupts are handled exclusively through the OS21 interface.

Description:

This function enables a specific interrupt.

7521642

143/170

ST200 board support package (BSP)

ST200

bsp_itc_interrupt_install
Install an interrupt handler
Definition:

#include <platform.h>
int bsp_itc_interrupt_install(
int interrupt_number,
int (*handler_function)(void* param_ptr),
int (**old_handler_function)(void* param_ptr),
void* stack_base,
int stack_size );

Arguments:
interrupt_number

The interrupt to which the handler is to be linked.

handler_function

The interrupt handler to be installed.

old_handler_function The interrupt handler previously installed.

Returns:

stack_base

The pointer to the location in memory to be used as

stack base. If NULL, the default system stack pointer is
used instead.

stack_size

The stack size to be allocated for the handler; not used if

stack_base is NULL.

Returns the error condition.

Errors:
BSP_EBUSY

The interrupt is not installed.

BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. In the OS21 environment, the interrupts
are handled exclusively through the OS21 interface.

Description:

This function installs a new interrupt handler, returning the handler installed
previously.

144/170

7521642

ST200

ST200 board support package (BSP)

bsp_itc_interrupt_poll
Poll a specific interrupt
Definition:

#include <platform.h>
int bsp_itc_interrupt_poll(
int interrupt_number,
int* value);

Arguments:

Returns:

interrupt_number

The interrupt to poll, in the range from 0 to 63.

value

The pointer to the returned value. If the returned value is

0, the interrupt has not been raised.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from simple bare machine run-time. In the OS21 environment, the
interrupts are handled exclusively through the OS21 interface.

Description:

This function informs the user whether an interrupt has been raised.

bsp_itc_interrupt_raise
Raises a specific interrupt
Definition:

#include <platform.h>
int bsp_itc_interrupt_raise(
int interrupt_number);

Arguments:
interrupt_number
Returns:

The interrupt to be raised.

Returns the error condition.

Errors:
BSP_EBUSY

The interrupt is not installed.

BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from simple bare machine run-time. In the OS21 environment, the
interrupts are handled exclusively through the OS21 interface.

Description:

This function raises a specific interrupt.

7521642

145/170

ST200 board support package (BSP)

ST200

bsp_itc_interrupt_uninstall
Uninstalls an interrupt handler
Definition:

#include <platform.h>
int bsp_itc_interrupt_uninstall(
int interrupt_number);

Arguments:
interrupt_number
Returns:

The interrupt to uninstall.

Returns the error condition.

Errors:
BSP_EBUSY

The interrupt is not installed.

BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from simple bare machine run-time. In the OS21 environment, the
interrupts are handled exclusively through the OS21 interface.

Description:

This function uninstalls a previously installed interrupt handle.

bsp_mmu_dump_TLB_Settings
Write TLBs settings on the stdio
Definition:

#include <platform.h>
int bsp_mmu_dump_TLB_Settings (void);

Arguments:

None.

Returns:

Returns BSP_OK.

Context:

Callable from bare machine and OS21 run-time.

Description:

The bsp_mmu_dump_TLB_Settings() function writes the TLBs settings on the

stdio.
The following example shows the output of the bsp_mmu_dump_TLB_Settings()
function for an ST231 simulation.
Index Asid Shared Sup/Usr
58
0
1
r-x/--59
0
1
rw-/--60
0
1
rw-/--61
0
1
rwx/rwx
62
0
1
rwx/rwx
63
0
1
rwx/rwx

146/170

Size
8KB
8KB
8KB
8KB
4MB
4MB

Vaddr
0x1F004000
0x1F002000
0x1F000000
0x00000000
0x08400000
0x08000000

7521642

Paddr Partition
0x1F004000 WAY0-3
0x1F002000 WAY0-3
0x1F000000 WAY0-3
0x00000000 WAY0-3
0x08400000 WAY0-3
0x08000000 WAY0-3

Policy
UNCACHED
UNCACHED
UNCACHED
UNCACHED
CACHED
CACHED

ST200

ST200 board support package (BSP)

bsp_mmu_memory_map
Create a memory mapping and return a virtual address range
Definition:

#include <platform.h>
void * bsp_mmu_memory_map (void * address,
size_t length,
int prot,
int flags,
void * phaddr);

Arguments:

Returns:

address

The virtual address.

length

The length of region in bytes.

prot

The combination of supervisor and user mode accesses

permitted for the address being mapped.

flags

Other information about the handling of the mapped

data.

phaddr

The physical address of the region to map.

Upon successful completion, the bsp_mmu_memory_map() function returns the

virtual address at which the mapping was placed; otherwise, it returns a value of
BSP_FAILURE and sets bsp_errno to indicate the error.
If bsp_mmu_memory_map() fails for reasons other than BSP_EINVAL, some of the
mappings in the address range starting at address and continuing for length bytes
may be unmapped.

Errors:
BSP_EMAPFAIL

MAP_OVERRIDE was not specified and a region is

already mapped at this virtual address range.

BSP_EINVAL

The field in flags is invalid. The argument length has

a value less than or equal to 0. The address (if
MAP_FIXED was specified) or length arguments are
not multiples of the page size.

BSP_EMFILE

The number of mapped regions exceed an

implementation-dependent limit.

BSP_ECONTEXT

The function was invoked after the OS21 run-time has

been started.

Context:

Callable only from bare machine run-time or before OS21 is started. In OS21, this
function only returns BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

The bsp_mmu_memory_map() function establishes a mapping between a range of

virtual addresses accessed by the program and a range of physical address of the
same size. Protection attributes can be set for the access to this range of address.
The format of the call is as follows:
va = bsp_mmu_memory_map(addr, length, prot, flags, phaddr);
In this example, bsp_mmu_memory_map() establishes a mapping between the
address space of the program at an address va for length bytes to the physical
address phaddr for length bytes. The value of va is exactly where the access at
addr starts and is a function of the addr argument and the value of flags, further
7521642

147/170

ST200 board support package (BSP)

ST200

described below. A successful bsp_mmu_memory_map() call returns va as its

result.
As the result of bsp_mmu_memory_map(), a block of program address space
including the range [va, va + length) is mapped. The limits of this block are
rounded according to the hardware constraints, such as the page size.
The mapping established by bsp_mmu_memory_map() replaces any previous
mappings for those whole pages containing any part of the address space of the
program starting at va and continuing for length bytes.
The prot argument determines all the attributes of the mapping: access rights for
supervisor and user mode, policy related to the cache and partition attributes.
The prot argument should be either PROT_NONE or the bitwise inclusive OR of one
or more of the following attributes defined in the header file
<machine/bsp/mmu.h>.
PROT_USER_READ

The address can be read in user mode.

PROT_SUPERVISOR_READ The address can be read in supervisor mode.

PROT_USER_WRITE

The address can be written in user mode.

PROT_SUPERVISOR_WRITE
The address can be written in supervisor mode.
PROT_USER_EXECUTE

The address can be executed in user mode.

PROT_SUPERVISOR_EXECUTE
The address can be executed in supervisor mode.
PROT_NONE

The data cannot be accessed.

PROT_CACHEABLE

Memory accesses are cached (PROT_CACHEABLE is

equivalent and is kept for backward compatibility).

POLICY_UNCACHEABLE

Memory accesses are uncached.

POLICY_WCUNCACHEABLE Memory accesses are uncached write-combined.

PART_REPLACE

Place as specified by replacement counter and

increment the counter.

PART_WAY1

Place in way 1 only.

PART_WAY2

Place in way 2 only.

PART_WAY3

Place in way 3 only.

PAGE_DIRTY

Page is dirty; write accesses to this page will cause a

TLB_WRITE_TO_CLEAN exception.

PAGE_VALID
Writes to this page are allowed.
If an implementation of bsp_mmu_memory_map() for a specific platform cannot
support the combination of access types specified by prot, the call to
bsp_mmu_memory_map() fails.

148/170

7521642

ST200

ST200 board support package (BSP)

The flags argument provides other information about the handling of the mapped
data. The value of flags is the bitwise inclusive OR of the following options defined
in <machine/bsp/mmu.h>.
MAP_FIXED

Interpret addr exactly.

MAP_LOCKED

Protect this TLB by random TLB replacement.

MAP_OVERRIDE

Override any existing mapping.

MAP_SPARE_RESOURCES

Spare mapping resources.

When MAP_FIXED is set in the flags argument, the system is informed that the
value of va must be addr exactly. If MAP_FIXED is set, bsp_mmu_memory_map()
may return MAP_FAILED and set bsp_errno to BAP_EINVAL. If a MAP_FIXED
request is successful, the mapping established by bsp_mmu_memory_map()
replaces any previous mappings for the programs pages in the range
[va, va + length).
When MAP_FIXED is set and the requested address is the same as previous
mapping, the previous address is unmapped and the new mapping is created on top
of the old one.
When MAP_FIXED is not set, the system uses addr to arrive at va. The va is an area
of the address space that the system deems suitable for a mapping of length bytes
to the physical address phaddr. The value of addr is taken to be a suggestion of a
program address near which the mapping should be placed.
When the system selects a value for va and MAP_OVERRIDE is not set, existing
mappings are not overridden. This includes the mapping set at program initialization
time in BSP-like code.
When MAP_SPARE_RESOURCES is set, the hardware resources are spared so that a
reasonable amount of hardware resources remain available for further
bsp_mmu_memory_map() usage. The implementation of this flag is ST200
architecture dependent.
When MAP_LOCKED is set, the LIMIT field of the TLB REPLACE register is changed.
To avoid this, TLB could be impacted from random TLB replacement routines.

ST200 implementation specifics

The bsp_mmu_memory_map() utility is currently not available for the ST220
architecture. For ST220 cores, the memory protection has to be managed directly
using the IPU-DPU control registers described in the ST220 Core and Instruction Set
Architecture Manual.
The bsp_mmu_memory_map() utility is implemented for the ST231 architecture
using the TLB hardware feature. The policy of the TLB index allocation is to use high
index values first, starting at TLB_SIZE-1, and decreasing toward 0.
The MAP_SPARE_RESOURCES specific allocation policy ensures that no more than
half of the TLB index is used to map a single area. It may also increase the page size
used to cover the area despite the lack of accuracy. This function invalidates any valid
instruction cache lines which fall within the address range specified. If it is not
possible to flush individual cache lines, then the entire instruction cache is invalidated.
See also:

bsp_mmu_memory_unmap()

7521642

149/170

ST200 board support package (BSP)

ST200

bsp_mmu_memory_unmap
Delete a memory mapping
Definition:

#include <platform.h>
int bsp_mmu_memory_unmap (
void *address,
size_t length);

Arguments:

Returns:

address

The virtual start address of the range to invalidate.

length

The length of the range in bytes.

Upon successful completion, bsp_mmu_memory_unmap() returns BSP_OK;

otherwise, it returns BSP_FAILURE and sets bsp_errno to indicate an error.
If the removed TLBs were set as MAP_LOCKED then the LIMIT field of the TLB
REPLACE register is adjusted accordingly.

Errors:
BSP_EINVAL

The addresses in the range [address, address +

length) are outside the valid range for the address
space of a program; or the length argument has a
value less than or equal to 0.

BSP_ECONTEXT

The function was invoked in the OS21 environment.

Context:

Callable only from bare machine run-time. After OS21 start-up, this function only
returns BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

The bsp_mmu_memory_unmap() function removes the mapping and protection for a

block of program address space, including the range [address, address +
length) assumed to have been set by bsp_mmu_memory_map().
If address is not the address of a mapping established by a prior call to
bsp_mmu_memory_map(), the behavior is undefined.
The bsp_mmu_memory_map() function may perform an implicit
bsp_mmu_memory_unmap().

See also:

bsp_mmu_memory_map

bsp_mmu_reset
Reset TLBs settings
Definition:

#include <platform.h>
int bsp_mmu_reset (void);

Arguments:

None.

Returns:

Returns the error condition.

Errors:
BSP_ECONTEXT
Context:

150/170

The function was called in the OS21 environment.

Callable only from bare machine run-time. In OS21, this function only returns
BSP_FAILURE and sets the error to BSP_ECONTEXT.

7521642

ST200

ST200 board support package (BSP)

bsp_pm_clock_get
Read the PM Clock counter
Definition:

#include <platform.h>
unsigned int bsp_pm_clock_get(void);

Arguments:

None.

Returns:

Returns the current value of the Clock counter.

Errors:

None.

Context:

Callable from bare machine and OS21 run-time.

Description:

This function reads the PM Clock counter and returns its current value.

See also:

bsp_pm_clock_set

bsp_pm_clock_set
Write the PM Clock counter
Definition:

#include <platform.h>
int bsp_pm_clock_set(
unsigned int value);

Arguments:
value
Returns:

The initialization value to be loaded in PM clock.

Returns the error condition.

Errors:
BSP_EBUSY

The performance monitoring clock is not writeable in

ST220 cores.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function writes value to the PM Clock counter.

See also:

bsp_pm_clock_get

7521642

151/170

ST200 board support package (BSP)

ST200

bsp_pm_count_mode
Change the suspension behavior of PM counters during oscalls
and debug events
Definition:

#include <platform.h>
int bsp_pm_count_mode(
unsigned int mode);

Arguments:
mode

The suspension behavior.

Returns:

Returns BSP_OK.

Errors:

None.

Context:

Callable from bare machine and OS21 run-time.

Description:

The bsp_pm_count_mode() function defines if PM counters have stopped during

oscalls (I/O) and debug events. The argument mode can assume the following values:

See also:

PM_DEFAULT

All the counters are suspended during oscalls and debug

events.

PM_FREE_RUN

The counters are free running during both oscalls and

debug events.

PM_SUSPEND_OSCALL

The counters are suspended only during oscalls.

PM_SUSPENDED_DEBUG

The counters are suspended only during debug events.

PM_SUSPENDED_ALL

All the counters are suspended during oscalls and debug

events.

bsp_timer_count_mode

bsp_pm_counter_get
Read the current value of a PM counter
Definition:

#include <platform.h>
unsigned int bsp_pm_counter_get(
int counter);

Arguments:
counter
Returns:

The counter to read.

Returns the current value of the counter.

Errors:
BSP_EINVAL

counter is an invalid counter.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function reads the PM counter and returns its current value.

See also:

bsp_pm_counter_set

152/170

7521642

ST200

ST200 board support package (BSP)

bsp_pm_counter_set
Write/change the value of a PM counter
Definition:

#include <platform.h>
int bsp_pm_counter_set(
int counter,
unsigned int value);

Arguments:

Returns:

counter

The counter to write.

value

The value to assign to the counter.

Returns the error condition.

Errors:
BSP_EINVAL

counter is an invalid counter.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function writes value to the PM counter specified in counter.

See also:

bsp_pm_counter_get

bsp_pm_event_get
Returns the event monitored by the PM counter
Definition:

#include <platform.h>
unsigned int bsp_pm_event_get(
int counter);

Arguments:
counter
Returns:

The counter to read.

Returns the event associated with the counter.

Errors:
BSP_EINVAL

counter is an invalid counter.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function reads the PM counter specified in counter and returns the event with
which it is associated.

See also:

bsp_pm_event_set

7521642

153/170

ST200 board support package (BSP)

ST200

bsp_pm_event_set
Set the event being monitored by a PM counter
Definition:

#include <platform.h>
int bsp_pm_event_set(
int counter,
unsigned int event);

Arguments:

Returns:

counter

The counter to set.

event

The event to assign to the counter.

Returns the error condition.

Errors:
BSP_EINVAL

counter is an invalid counter.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function sets the PM counter specified in counter to monitor the event specified
in event.

See also:

bsp_pm_event_get

bsp_pm_reset
Reset all counters
Definition:

#include <platform.h>
int bsp_pm_reset(void);

Arguments:

None.

Returns:

Returns BSP_OK.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function resets all of the PM counters.

bsp_pm_start
Start all the event counters
Definition:

#include <platform.h>
int bsp_pm_start(void);

Arguments:

None.

Returns:

Returns BSP_OK.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function starts all of the event counters.

See also:

bsp_pm_stop

154/170

7521642

ST200

ST200 board support package (BSP)

bsp_pm_stop
Stop all the event counters
Definition:

#include <platform.h>
int bsp_pm_stop(void);

Arguments:

None.

Returns:

Returns BSP_OK.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function stops all of the event counters.

See also:

bsp_pm_start

bsp_scu_disable
Disable an SCU region
Definition:

#include <platform.h>
unsigned int bsp_scu_disable(
unsigned int regno);

Arguments:
regno
Returns:

The SCU region number to be disabled.

Returns the error condition (BSP_OK or BSP_FAILURE).

Errors:

Context:

BSP_ECONTEXT

The function was called after OS21 start-up.

BSP_EINVAL

Wrong region number.

Callable only from bare machine run-time. If OS21 is started, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

bsp_scu_dump_SCU_Settings
Dump on the I/O a list of the SCU regions
Definition:

#include <platform.h>
int bsp_scu_dump_SCU_Settings(void);

Arguments:

None.

Returns:

Returns BSP_OK.

Errors:

None.

Context:

Callable from bare machine run-time and OS21 run-time.

Description:

This function writes the SCU regions settings on the stdio.

7521642

155/170

ST200 board support package (BSP)

ST200

bsp_scu_read
Read the start and stop address of an SCU region
Definition:

#include <platform.h>
unsigned int bsp_scu_read(
unsigned int regno,
bsp_scu_entry_t *sect);

Arguments:

Returns:

regno

The SCU region number to read.

sect

A pointer to an allocated structure of type

bsp_scu_entry_t.

Returns the error condition (BSP_OK or BSP_FAILURE). In case of success, the

structure sect contains the start and end addresses of the region.

Errors:
BSP_EINVAL

Wrong region number.

Context:

Callable from bare machine and OS21 run-time.

Description:

The bsp_scu_read() function reads the start and stop address of the SCU region
specified by regno. The addresses are returned in the structure sect.

bsp_scu_write
Set the start and stop address of an SCU region
Definition:

#include <platform.h>
unsigned int bsp_scu_write(
unsigned int regno,
bsp_scu_entry_t *sect);

Arguments:

Returns:

regno

The SCU region number to be written.

sect

A pointer to an allocated structure of type

bsp_scu_entry_t containing the start and end
addresses.

Returns the error condition (BSP_OK or BSP_FAILURE).

Errors:
BSP_EINVAL

Wrong region number.

BSP_ECONTEXT

The function has been called in OS21 run-time.

Context:

Callable from bare machine run-time.

Description:

The bsp_scu_write() function sets the start and stop address of the SCU region
specified by regno to the addresses specified in the structure sect.

156/170

7521642

ST200

ST200 board support package (BSP)

bsp_timer_count_get
Get the initial value of the counter of the specific timer
Definition:

#include <platform.h>
unsigned int bsp_timer_count_get(
int timer);

Arguments:
timer
Returns:

The timer for which to get the initial counter value, see
Table 31: ST200 timer assignments on page 120.

The value of the counter of the required timer.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function returns the counter of the given timer.

See also:

bsp_timer_count_set

bsp_timer_count_mode
Change the suspension behavior of the timers during oscalls and
debug events
Definition:

#include <platform.h>
int bsp_timer_count_mode(
unsigned int mode);

Arguments:
mode

The suspension behavior.

Returns:

Returns BSP_OK.

Errors:

None.

Context:

Callable from bare machine and OS21 run-time.

Description:

This function defines if timer counters have to stopped during oscalls (I/O) and debug
events. The argument mode can assume any of the following values.
TIMER_DEFAULT

The system timer is free-running during oscalls and

debug events.

TIMER_FREE_RUN

The system timer is free running during both oscalls and

debug events.

TIMER_SUSPEND_OSCALL The system timer is suspended only during oscalls.

TIMER_SUSPENDED_DEBUG The system timer is suspended only during debug
events.
TIMER_SUSPENDED_ALL
See also:

The system timer is suspended during oscalls and

debug events.

bsp_pm_count_mode

7521642

157/170

ST200 board support package (BSP)

ST200

bsp_timer_count_set
Set the initial value of the counter of the specific timer
Definition:

#include <platform.h>
int bsp_timer_count_set(
int timer,
unsiged int value);

Arguments:

Returns:

timer

The timer to initialize, see Table 31: ST200 timer

assignments on page 120.

value

The value to be used for counter initialization.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function initializes the counter of a given timer. It should only be used with
TIMER1 and TIMER2, however TIMER2 should only be used if the profiler is not
enabled. Do not use this function with TIMER_SYSTEM.

bsp_timer_interrupt_clear
Clear the timer interrupt
Definition:

#include <platform.h>
int bsp_timer_interrupt_clear(
int timer);

Arguments:
timer
Returns:

The timer interrupt to clean, see Table 31: ST200 timer

assignments on page 120.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function clears the interrupt of a given timer. It should only be used with TIMER1
and TIMER2, however TIMER2 should only be used if the profiler is not enabled. Do
not use this function with TIMER_SYSTEM.

158/170

7521642

ST200

ST200 board support package (BSP)

bsp_timer_interrupt_enable
Enable the timer interrupt
Definition:

#include <platform.h>
int bsp_timer_interrupt_enable(
int timer);

Arguments:
timer
Returns:

The timer interrupt to enable, see Table 31: ST200 timer

assignments on page 120.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function enables the interrupt for the given timer. It should only be used with
TIMER1 and TIMER2, however TIMER2 should only be used if the profiler is not
enabled. Do not use this function with TIMER_SYSTEM.

bsp_timer_now
Return the current time
Definition:

#include <platform.h>
bspclock_t bsp_timer_now(void);

Arguments:

None.

Returns:

Returns the number of ticks since the system started.

Errors:

None.

Context:

Callable from task or interrupt handler. If OS21 is enabled, this function directly
invokes the corresponding OS21 time_now() function.

Description:

bsp_timer_now() returns the number of ticks since the system started running.
The exact time at which counting starts is implementation specific, but is done in the
core initialization.
The units of ticks is an implementation dependent quantity, but it is approximately
1 microseconds, see bsp_timer_ticks_per_sec on page 162.

7521642

159/170

ST200 board support package (BSP)

ST200

bsp_timer_reload_get
Get the reload value of the specific timer
Definition:

#include <platform.h>
unsigned int bsp_timer_reload_get(
int timer);

Arguments:
timer
Returns:

The timer, see Table 31: ST200 timer assignments on

page 120.

The value to be reloaded into the timer on reaching zero.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function returns the reload value of the given timer.

bsp_timer_reload_set
Set the value to be reloaded into the specific timer on reaching
zero
Definition:

#include <platform.h>
int bsp_timer_reload_set(
int timer,
unsigned int reload);

Arguments:

Returns:

timer

The timer to reload, see Table 31: ST200 timer

assignments on page 120.

value

The value to be used for reload initialization.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function initializes the reload register of a given timer. It should only be used with
TIMER1 and TIMER2, however TIMER2 should only be used if the profiler is not
enabled. Do not use this function with TIMER_SYSTEM.

160/170

7521642

ST200

ST200 board support package (BSP)

bsp_timer_start
Start the timer
Definition:

#include <platform.h>
int bsp_timer_start(
int timer);

Arguments:
timer
Returns:

The timer to start, see Table 31: ST200 timer

assignments on page 120.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from simple bare machine run-time. If OS21 is enabled, this function
returns BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function starts the timer. It should only be used with TIMER1 and TIMER2,
however TIMER2 should only be used if the profiler is not enabled. Do not use this
function with TIMER_SYSTEM.

bsp_timer_stop
Stop the timer
Definition:

#include <platform.h>
int bsp_timer_stop(
int timer);

Arguments:
timer
Returns:

The timer to stop, see Table 31: ST200 timer

assignments on page 120.

Returns the error condition.

Errors:
BSP_ECONTEXT

The function was called in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function stops the timer. It should only be used with TIMER1 and TIMER2,
however TIMER1 should only be used if the profiler is not enabled. Do not use this
function with TIMER_SYSTEM.

7521642

161/170

ST200 board support package (BSP)

ST200

bsp_timer_ticks_per_sec
Return the number of clock ticks per second
Definition:

#include <platform.h>
bspclock_t bsp_time_ticks_per_sec(void);

Arguments:

None.

Returns:

The number of ticks per second.

Errors:

None.

Context:

Callable from task or interrupt handler. If OS21 is enabled, this function directly
invokes the corresponding OS21 function time_ticks_per_sec().

Description:

bsp_timer_ticks_per_sec() returns the number of clock ticks per second.

bsp_timer_user
Set a user timer, attach an interrupt handle and enable the
corresponding interrupt
Definition:

#include <platform.h>
int bsp_timer_user(
int timer,
unsigned int const,
unsigned int reload,
int (* interrupt_handle)(void *param),
int (** old_handler)(void *param));

Arguments:

Returns:

timer

The user timer to set (TIMER1 or TIMER2).

const

The value to load to initialize the timer.

reload

The value to be reloaded when reaching zero.

interrupt_handle

The handle of the interrupt.

old_handle

The interrupt handle previously associated with the

timer.

Returns BSP_OK on success, on failure it returns BSP_FAILURE and sets

bsp_errno to indicate the error.

Errors:
BSP_EINVAL

timer is set to an invalid timer. Only TIMER1 and

TIMER2 are allowed.

BSP_EBUSY

The requested timer is in use. This occurs if TIMER2

is requested and profiling is enabled.

BSP_ECONTEXT

The function was invoked in the OS21 environment.

Context:

Callable only from bare machine run-time. If OS21 is enabled, this function returns
BSP_FAILURE and sets bsp_errno to BSP_ECONTEXT.

Description:

This function set a user timer, attaches an interrupt handle and enables the
corresponding interrupt.

162/170

7521642

ST200

Revision history

Revision history
Table 46.
Date

Document revision history

Revision

Changes

Throughout: Updated for R5.0.

Getting started chapter: The version of GDB is now 6.4. Updated the
table of Silicon target configuration options, including adding the new
options JTAG_REMOTE_CLOCK and ST231_CUT6.

Throughout: Updated for R5.0. References to Cygwin have been

removed.
Getting started chapter: Updated list of supported targets. Added
PURE_JTAG option to list of silicon target configuration options.
The STWorkbench and related plug-ins chapter: Renamed from The
Eclipse plug-ins. Updated all reference of ST Eclipse to
STWorkbench. Updated to describe both the ST200 plug-in and the
Visual Prof plug-in. Added sections on Analysing a program,
Running and analyzing a program and Debugging tips.
ST200 simulator chapter: Updated source location of sample device
plug-in. Added The ST200 simulator plug-ins section.
Setting up a board chapter: Added text explaining a board in the
ST200 cross development system context. Updated mb379 and
mb379_xxx boards section to be Example of mb428_host and
mb428_audio boards.
Relocatable loader library chapter: Renamed st200-rltool to
st200rltool.
ST200 board support package (BSP) appendix: Updated
bsp_timer_count_mode(). Updated Errors in bsp_timer_user().

24-Mar-06

Throughout: Updated for R4.2.

Getting started chapter: Updated list of supported targets. Updated
the st200run options, --pc and --ramend. Updated the Target and
target options section. Added CPU_RESET_ADDRESS and
VIRTUAL_DEBUG to the list of silicon target configuration options
and updated OS21_OSCALL. Updated the description of the basic
gdb commands in the section st200gdb debugger. Added gdi
id2keyhigh and gdi id2keylow to the list of Target specific GDI direct
commands. Removed user mode description.
Removed the chapter The Microsoft Visual Studio .Net add-in.

16-Jul-05

The Eclipse plug-ins chapter: Installation instructions are now on the

ST200 Eclipse installation CD.

Setting up a board chapter: Replaced InitCore with __init_core,

InitBoard with __init_board and InitSoc with __init_soc.
Relocatable loader library chapter: Updated the
rl_add_action_callback(), rl_errno(), rl_errarg() and rl_errstr()
functions.

03-Nov-06

14-Jul-06

24-Jun-05

7521642

163/170

Revision history

ST200

Table 46.
Date

17-Jun-05

28-Nov-04

12-Jun-04

18-Dec-03

164/170

Document revision history (continued)

Revision

Changes

Throughout: Updated for R4.1. Removed references to the ST230.

Updated GDB and Insight versions. Removed references to
ST200ROOT_TARGET.
Getting started chapter: References to the portmapper have been
removed. Updated list of st200run options. Updated search strategy
for the target description file. Updated list of silicon target
configuration options. Updated the GDI commands. Updated the
instructions for using the graphical user interface. Removed the
section on Using the clock for benchmarking.
The Microsoft Visual Studio .Net add-in chapter: Created as a new
chapter from the section previously in the Getting started chapter.
The Eclipse plug-ins chapter: Added as a new chapter.
Relocatable loader library chapter: Added as a new chapter.
ST200 Board Support Package appendix: Updated privileges in the
initial memory map. Added sections on Speculative control unit,
OScalls and debug events suspension and Flash file system
handling. Added and updated several functions.

Throughout: Updated for R4.0.

Getting started chapter: Added notes to say that the user mode has
been deprecated. Updated st200gdb information. Added details of
the Microsoft Visual Studio .Net add-in.
ST200 simulator chapter: Added details of the device plug-in for the
ST200 simulator.
ST200 Board Support Package appendix: Added as new appendix.
Memory protection settings appendix: Removed the appendix.

Throughout: Added details of ST231 support.

Getting started chapter: Updated list of st200run options. Updated
list of supported targets. Updated table of simulator target
configuration options.
ST200 simulator chapter: Updated the list of simulator target
configuration options
Setting up a board chapter: Updated description of BOOTRAM
option in the Bring up operations section.

Throughout: Linux is now supported.

Getting started chapter: Updated list of supported targets. Updated
Target address space usage section. Updated the modes that can be
used to run a simulation. Updated table of st200run options. Updated
tables of target options. Added details of the st200gdb command
pmblock. Added details of Performance Monitoring window. Updated
the names of the initialization files. Updated Using a custom board
target and Modifying the memory protection settings sections.
ST200 simulator chapter: Updated the list of simulator target
configuration options.
Setting up a board chapter: Updated throughout and added
Understanding target dependent settings and Supported
configurations sections.
Memory protection settings appendix: Added as new appendix.

7521642

ST200

Revision history
Table 46.

Document revision history (continued)

Date

Revision

Changes

21-Jun-03

Getting started chapter: Added details of TOOLS200_DIR to the

Testing the compiler section.

02-Jun-03

Getting started chapter: Updated filenames and locations in The

sysconf and boot code modules.
Setting up a board chapter: Updated filenames and locations in Add
a board file into the ST200 toolset.

28-May-03

Initial release.

7521642

165/170

Index

ST200

Index
Symbols
.bss initialization . . . . . . . . . . . . . . . . . . . . . . . .16
.gdbtkinit file . . . . . . . . . . . . . . . . . . . . . . . . . . .41

A
address
end of RAM . . . . . . . . . . . . . . . . . . . . . . . . . .17
address space usage . . . . . . . . . . . . . . . . . . . .11

B
back-end component . . . . . . . . . . . . . . . . . . . .86
Backus-Naur Form . . . . . . . . . . . . . . . . . . . . . . .8
BNF. See Backus-Naur Form.
BOARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
board
bring up . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
board file . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
BOARD_TXT_FILE . . . . . . . . . . . . . . . . . . . . .22
boot code . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
BOOT_FROM_RESET . . . . . . . . . . . . . . . . . .68
BOOT_ROM_BASE . . . . . . . . . . . . . . . . . . . . .69
BOOT_ROM_SIZE . . . . . . . . . . . . . . . . . . . . . .69
BOOT_RTL . . . . . . . . . . . . . . . . . . . . . . . . . . .69
BOOTRAM . . . . . . . . . . . . . . . . . . . . . . . . .22, 87
bring up procedure . . . . . . . . . . . . . . . . . . . . . .87
bsp_cache_invalidate_instruction . . . . . . . . .131
bsp_cache_invalidate_instruction_all . . . . . . .131
bsp_cache_purge_data . . . . . . . . . . . . . . . . .132
bsp_cache_purge_data_all . . . . . . . . . . . . . .132
bsp_core_interrupt_install . . . . . . . . . . . . . . .133
bsp_core_interrupt_lock . . . . . . . . . . . . . . . . .133
bsp_core_interrupt_unlock . . . . . . . . . . . . . . .134
bsp_dpu_disable . . . . . . . . . . . . . . . . . . . . . .134
bsp_dpu_enable . . . . . . . . . . . . . . . . . . . . . . .135
bsp_dpu_region_get . . . . . . . . . . . . . . . . . . .135
bsp_dpu_region_set . . . . . . . . . . . . . . . . . . . .136
bsp_ffs_dir . . . . . . . . . . . . . . . . . . . . . . . . . . .137
bsp_ffs_fclose . . . . . . . . . . . . . . . . . . . . . . . .137
bsp_ffs_fopen . . . . . . . . . . . . . . . . . . . . . . . . .138
bsp_ffs_fread . . . . . . . . . . . . . . . . . . . . . . . . .139
bsp_ffs_showboot . . . . . . . . . . . . . . . . . . . . .140
bsp_ipu_disable . . . . . . . . . . . . . . . . . . . . . . .140
bsp_ipu_enable . . . . . . . . . . . . . . . . . . . . . . .140
bsp_ipu_region_get . . . . . . . . . . . . . . . . . . . .141
bsp_ipu_region_set . . . . . . . . . . . . . . . . . . . .142
bsp_itc_interrupt_clear . . . . . . . . . . . . . . . . . .142

166/170

bsp_itc_interrupt_disable . . . . . . . . . . . . . . . 143
bsp_itc_interrupt_enable . . . . . . . . . . . . . . . . 143
bsp_itc_interrupt_install . . . . . . . . . . . . . . . . . 144
bsp_itc_interrupt_poll . . . . . . . . . . . . . . . . . . 145
bsp_itc_interrupt_raise . . . . . . . . . . . . . . . . . 145
bsp_itc_interrupt_uninstall . . . . . . . . . . . . . . . 146
bsp_mmu_dump_TLB_Settings . . . . . . . . . . 146
bsp_mmu_memory_map . . . . . . . . . . . . . . . . 147
bsp_mmu_memory_unmap . . . . . . . . . . . . . . 150
bsp_mmu_reset . . . . . . . . . . . . . . . . . . . . . . . 150
bsp_pm_clock_get . . . . . . . . . . . . . . . . . . . . 151
bsp_pm_clock_set . . . . . . . . . . . . . . . . . . . . . 151
bsp_pm_count_mode . . . . . . . . . . . . . . . . . . 152
bsp_pm_counter_get . . . . . . . . . . . . . . . . . . . 152
bsp_pm_counter_set . . . . . . . . . . . . . . . . . . . 153
bsp_pm_event_get . . . . . . . . . . . . . . . . . . . . 153
bsp_pm_event_set . . . . . . . . . . . . . . . . . . . . 154
bsp_pm_reset . . . . . . . . . . . . . . . . . . . . . . . . 154
bsp_pm_start . . . . . . . . . . . . . . . . . . . . . . . . . 154
bsp_pm_stop . . . . . . . . . . . . . . . . . . . . . . . . . 155
bsp_scu_disable . . . . . . . . . . . . . . . . . . . . . . 155
bsp_scu_dump_SCU_Settings . . . . . . . . . . . 155
bsp_scu_read . . . . . . . . . . . . . . . . . . . . . . . . 156
bsp_scu_write . . . . . . . . . . . . . . . . . . . . . . . . 156
bsp_timer_count_get . . . . . . . . . . . . . . . . . . . 157
bsp_timer_count_mode . . . . . . . . . . . . . . . . . 157
bsp_timer_count_set . . . . . . . . . . . . . . . . . . . 158
bsp_timer_interrupt_clear . . . . . . . . . . . . . . . 158
bsp_timer_interrupt_enable . . . . . . . . . . . . . . 159
bsp_timer_now . . . . . . . . . . . . . . . . . . . . . . . 159
bsp_timer_reload_get . . . . . . . . . . . . . . . . . . 160
bsp_timer_reload_set . . . . . . . . . . . . . . . . . . 160
bsp_timer_start . . . . . . . . . . . . . . . . . . . . . . . 161
bsp_timer_stop . . . . . . . . . . . . . . . . . . . . . . . 161
bsp_timer_ticks_per_sec . . . . . . . . . . . . . . . . 162
bsp_timer_user . . . . . . . . . . . . . . . . . . . . . . . 162
bsp_user_end_handle . . . . . . . . . . . . . . . . . . 130
bsp_user_start_handle . . . . . . . . . . . . . . . . . 129
BUNDLE_CHECKING_ON . . . . . . . . . . . . . . . 70
BUNDLE_CHECKING_RE_ON . . . . . . . . . . . 70
BUS_BYTES_PER_CYCLE . . . . . . . . . . . . . . 68
BUS_BYTES_PER_TRANSACTION . . . . . . . 68
BUS_LATENCY . . . . . . . . . . . . . . . . . . . . . . . 68
BUS_MHZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
BUS_TRAFFIC_OUTPUT_TRACE_FILE . . . . 69
BUS_TRAFFIC_TRACE_END_CYCLE . . . . . 69
BUS_TRAFFIC_TRACE_START_CYCLE . . . 69
BUS_TRAFFIC_TRACING_ON . . . . . . . . . . . 69

7521642

ST200

Index

C
CLEAR_MEMORY . . . . . . . . . . . . . . . . . . . . . .71
CLOCK_D . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
commands
direct to target . . . . . . . . . . . . . . . . . . . . . . . .14
compile C program . . . . . . . . . . . . . . . . . . . . . .89
CONFIG_FILE . . . . . . . . . . . . . . . . . . 20, 22, 67
connect a target . . . . . . . . . . . . . . . . . . . . . . . .13
core registers . . . . . . . . . . . . . . . . . . . . . . . . . .42
initialization . . . . . . . . . . . . . . . . . . . . . . . . . .43
CORE_MHZ . . . . . . . . . . . . . . . . . . . . . . . . . . .67
CPU_RESET_ADDRESS . . . . . . . . . . . . . . . .22
critical test suite . . . . . . . . . . . . . . . . . . . . .85, 88
cross-development environment . . . . . . . . . . . .1

D
DCACHE_MODEL . . . . . . . . . . . . . . . . . . . . . .67
debug information . . . . . . . . . . . . . . . . . . . . . .15
define an alias . . . . . . . . . . . . . . . . . . . . . . . . .87
device plug-ins . . . . . . . . . . . . . . . . . . . . . . . . .70
DEVICE_PLUGIN_MODULES . . . . . . . . . . . . .70
DiDirectCommand . . . . . . . . . . . . . . . . . . . . . .14
direct command . . . . . . . . . . . . . . . . . . . . . . . .14
DISABLE_MPOKE . . . . . . . . . . . . . . . . . . . . . .22
dll
options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
parameters . . . . . . . . . . . . . . . . . . . . . . . . . .15
specify . . . . . . . . . . . . . . . . . . . . . 15, 20-21, 28
version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
DSU monitor . . . . . . . . . . . . . . . . . . . . . . . . . . .86
DSU register . . . . . . . . . . . . . . . . . . . . . 85-86, 88
DSU_DEFAULT_MODULE_ENABLED . . . . . .70
DSU_ROM_IMAGE . . . . . . . . . . . . . . . . . . . . .71
DUMP_CONFIG_FILE . . . . . . . . . . . . . . . .20, 67
dynamic library . . . . . . . . . . . . . . . . 15, 18, 20-21
dynamic target dll name . . . . . . . . . . . . . . .15, 28

E
EMU_SAFE_TRACE . . . . . . . . . . . . . . . . . . . .23
EMU_TRACE . . . . . . . . . . . . . . . . . . . . . . . . . .23
emulate system calls . . . . . . . . . . . . . . . . .13, 34
environment
pass variables to target . . . . . . . . . . . . . .15, 34
examples
using st200run . . . . . . . . . . . . . . . . . . . . . . . .13

execute C program . . . . . . . . . . . . . . . . . . . . . 89
execute program . . . . . . . . . . . . . . . . . . . . . . . 13
memory location . . . . . . . . . . . . . . . . . . . . . . 11
EXTERNAL_MEMORY_BASE . . . . . . . . . 20, 68
EXTERNAL_MEMORY_PATTERN . . . . . . . . 71
EXTERNAL_MEMORY_SIZE . . . . . . . . . . 20, 68

F
Fast mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
file management . . . . . . . . . . . . . . . . . . . . . . 108

G
gdbtk.ini file . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
GDI
commands . . . . . . . . . . . . . . . . . . . . . . . . . . 37
dynamic target dll name . . . . . . . . . . . . . 15, 28
function information . . . . . . . . . . . . . . . . . . . 15
functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
version information . . . . . . . . . . . . . . . . . . . . 18
GDI Debug Instrument . . . . . . . . . . . . . . . . . . 89
gentestsuite . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
graphical user interface . . . . . . . . . . . . . . . 27, 35
GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27, 35

H
hardware reset address . . . . . . . . . . . . . . . . . . 17
HAZARD_CHECKING_ON . . . . . . . . . . . . . . . 70
help
st200run . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
host environment variables . . . . . . . . . . . . 15, 34
HTI_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
HTI_MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

I
ICACHE_MODEL . . . . . . . . . . . . . . . . . . . . . . 67
ID2KEY_FILE . . . . . . . . . . . . . . . . . . . . . . . . . 23
initialization hook . . . . . . . . . . . . . . . . . . . . . . . 43
initialize bss . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
installation testing . . . . . . . . . . . . . . . . . . . . . . 10
instruction-set accurate mode . . . . . . . . . . . . . 13
internal C run-time initialization . . . . . . . . . . . . 43
ISS mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

7521642

167/170

Index

ST200

K
KERNEL_STACK_SIZE . . . . . . . . . . . . . . . . . .68

L
Linux
installation testing . . . . . . . . . . . . . . . . . . . . .10
LMI RAM memory . . . . . . . . . . . . . . . . . . . . . .11
load program . . . . . . . . . . . . . . . . . . . . . . . . . .13
--loaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
memory location . . . . . . . . . . . . . . . . . . . . . .11

M
memory
change location . . . . . . . . . . . . . . . . . . . . . . .11
LMI RAM . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
load program . . . . . . . . . . . . . . . . . . . . . . . . .16
noncacheable area size . . . . . . . . . . . . . . . .16
memory allocation . . . . . . . . . . . . . . . . . . . . .108
memory protection setting . . . . . . . . . . . . . . . .47
MEMSYSTEM_LATENCY . . . . . . . . . . . . . . . .68
MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . .20, 67
module version . . . . . . . . . . . . . . . . . . . . . . . . .15

N
NO_CHIP_RESET . . . . . . . . . . . . . . . . . . . . . .23
NO_TAP_CTRL . . . . . . . . . . . . . . . . . . . . . . . .23
noncacheable memory area . . . . . . . . . . . . . . .16
NONCACHEABLE_MEM_SIZE . . . . . . . . .20, 68

O
OS21 tick duration . . . . . . . . . . . . . . . . . . . . .120
OS21_OSCALL . . . . . . . . . . . . . . . . . . . . . . . .24
OUTPUT_LOG_FILE . . . . . . . . . . . . . . . . . . . .70
OUTPUT_TRACE_FILE . . . . . . . . . . . . . . .20, 69
override
memory protection setting . . . . . . . . . . . . . . .47

P
passing environment variables . . . . . . . . . . . . .34
peripheral base address . . . . . . . . . . . . . . . . . .85
PERIPHERAL_BASE . . . . . . . . . . . . . . . . . . . .69
PERIPHERAL_LATENCY . . . . . . . . . . . . . . . .68
plug-ins
device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

168/170

predefined target name . . . . . . . . . . . . . . . . . . 17

PROFILING . . . . . . . . . . . . . . . . . . . . . . . . 21, 70
PROFILING_OUTPUT_FILE . . . . . . . . . . . 21, 70
program
compile and execute . . . . . . . . . . . . . . . . . . 89
program execution startup . . . . . . . . . . . . . . . . 42

R
R_Absolute . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
R_PIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
R_Relocatable . . . . . . . . . . . . . . . . . . . . . . . . . 90
RAM memory . . . . . . . . . . . . . . . . . . . . . . 86, 88
RAMEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
startup location . . . . . . . . . . . . . . . . . . . . . . . 33
README.GDBTK . . . . . . . . . . . . . . . . . . . . . . 41
reference mode . . . . . . . . . . . . . . . . . . . . . . . . 13
relocatable loader library . . . . . . . . . . . . . . . . . 90
file management . . . . . . . . . . . . . . . . . . . . . 108
memory allocation . . . . . . . . . . . . . . . . . . . 108
relocatable run-time model . . . . . . . . . . . . . . . 91
reset mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
RESET_ADDRESS . . . . . . . . . . . . . . . . . . . . . 69
RESET_DELAY_CYCLES . . . . . . . . . . . . . . . 69
rl_add_action_callback . . . . . . . . . . . . . . . . . 103
rl_delete_action_callback . . . . . . . . . . . . . . . 104
rl_errarg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
rl_errno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
rl_errstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
rl_file_name . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
rl_foreach_segment . . . . . . . . . . . . . . . . . . . . 102
rl_handle_delete . . . . . . . . . . . . . . . . . . . . . . . 94
rl_handle_new . . . . . . . . . . . . . . . . . . . . . . . . . 94
rl_lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
rl_load_addr . . . . . . . . . . . . . . . . . . . . . . . . . . 95
rl_load_buffer . . . . . . . . . . . . . . . . . . . . . . . . . 97
rl_load_file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
rl_load_size . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
rl_load_stream . . . . . . . . . . . . . . . . . . . . . . . . . 98
rl_parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
rl_set_file_name . . . . . . . . . . . . . . . . . . . . . . . 96
rl_sym . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
rl_sym_rec . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
rl_this . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
rl_unload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
run.log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
run-time configuration . . . . . . . . . . . . . . . . . . . 33
run-time model . . . . . . . . . . . . . . . . . . . . . . . . 90
run-time version . . . . . . . . . . . . . . . . . . . . . . . . 18

7521642

ST200

Index

Selecting an ST2x0 Target window . . . . . . . . .35

silicon connection
alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
sim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
simprof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
simulator
fast mode . . . . . . . . . . . . . . . . . . . . . . . . . . .14
ISS mode . . . . . . . . . . . . . . . . . . . . . . . . . . .13
reference mode . . . . . . . . . . . . . . . . . . . . . . .13
simulator target . . . . . . . . . . . . . . . . . . . . . .1, 13
software parameters . . . . . . . . . . . . . . . . . . . .42
software simulator . . . . . . . . . . . . . . . . . . . .1, 67
Solaris
installation testing . . . . . . . . . . . . . . . . . . . . .10
st200gdb
bring up commands . . . . . . . . . . . . . . . . . . . .86
connect to the ST200 core . . . . . . . . . . . . . .87
debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
other functionalities . . . . . . . . . . . . . . . . . . . .36
startup configuration commands . . . . . . . . . .33
target command . . . . . . . . . . . . . . . . . . . . . .28
st200run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
information . . . . . . . . . . . . . . . . . . . . . . . . . .18
options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
ST2x0 Statistics window . . . . . . . . . . . . . . . . .37
Stack Pointer . . . . . . . . . . . . . . . . . . . . . . . . . .43
start parameter initialization . . . . . . . . . . . . . . .42
startbss . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-34
startenv . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-34
startramend . . . . . . . . . . . . . . . . . . . . . . . . . . .33
startup configuration commands . . . . . . . . . . .33
statistics command . . . . . . . . . . . . . . . . . . . . . .37
STIMULATION_FILE . . . . . . . . . . . . . . . . . . . .71
syntax
used in the targets file . . . . . . . . . . . . . . .19, 21
system call information . . . . . . . . . . . . . . . . . . .15

taplink interface . . . . . . . . . . . . . . . . . . . . . . . . 86
target command . . . . . . . . . . . . . . . . . . . . . . . 28
target information . . . . . . . . . . . . . . . . . . . . . . 84
targets . . . . . . . . . . . . . . . . . . . . . . . . . 13, 19, 28
board file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
description file . . . . . . . . . . . . . . . . . 17-18, 28
dll name . . . . . . . . . . . . . . . . . . . . . . . . . 15, 28
mb379 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
options . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21
sim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
simprof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
specify name . . . . . . . . . . . . . . . . . . . . . . . . 17
specify options . . . . . . . . . . . . . . 15, 20-21, 28
ST220 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
supported . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
syntax in file . . . . . . . . . . . . . . . . . . . . . . 19, 21
version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
targets.cfg . . . . . . . . . . . . . . . . . . . . . . 19, 28, 35
tools
setting up boards . . . . . . . . . . . . . . . . . . . . . 86
TRACE_END_CYCLE . . . . . . . . . . . . . . . . 20, 69
TRACE_START_CYCLE . . . . . . . . . . . . . 20, 69
TRACING_ON . . . . . . . . . . . . . . . . . . . . . . 20, 69
TRANSACTION_SETUP_CYCLES . . . . . . . . 68
transfer rate . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . 41

V
VERBOSITY . . . . . . . . . . . . . . . . . . . . . . . . . . 26
version
st200run . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
VIRTUAL_DEBUG . . . . . . . . . . . . . . . . . . . . . 26

7521642

169/170

ST200

Please Read Carefully:

Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (ST) reserve the
right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any
time, without notice.
All ST products are sold pursuant to STs terms and conditions of sale.
Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no
liability whatsoever relating to the choice, selection or use of the ST products and services described herein.
No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this
document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products
or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such
third party products or services or any intellectual property contained therein.

UNLESS OTHERWISE SET FORTH IN STS TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS
OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
UNLESS EXPRESSLY APPROVED IN WRITING BY AN AUTHORIZED ST REPRESENTATIVE, ST PRODUCTS ARE NOT
RECOMMENDED, AUTHORIZED OR WARRANTED FOR USE IN MILITARY, AIR CRAFT, SPACE, LIFE SAVING, OR LIFE SUSTAINING
APPLICATIONS, NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY,
DEATH, OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE. ST PRODUCTS WHICH ARE NOT SPECIFIED AS "AUTOMOTIVE
GRADE" MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USERS OWN RISK.

Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void
any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any
liability of ST.

ST and the ST logo are trademarks or registered trademarks of ST in various countries.

Information in this document supersedes and replaces all information previously supplied.
The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.

2006 STMicroelectronics - All rights reserved

STMicroelectronics group of companies
Australia - Belgium - Brazil - Canada - China - Czech Republic - Finland - France - Germany - Hong Kong - India - Israel - Italy - Japan Malaysia - Malta - Morocco - Singapore - Spain - Sweden - Switzerland - United Kingdom - United States of America
www.st.com

170/170

7521642