CodeWarrior For Symbian OS

CodeWarrior ™ Development Studio
for Symbian ™ OS
Version 3.1; November 29, 2005
Revised <Date>
Table of Contents
1 Introduction 9
1.1 What is New. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.2 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3 Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.1 For everyone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.2 If you are new to CodeWarrior IDE . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.3.3 For information on the Symbian operating system . . . . . . . . . . . . . . . 11
1.4 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.5 Features Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5.1 SDKs and Development Kits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5.2 Builds Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.5.3 Emulation Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.5.4 Device Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.5.5 Device Debugging in ROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.5.6 Kernel Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.6 Contacting Us . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.7 Legal Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2 Creating Symbian OS Projects 17

2.1 Creating a Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1.1 Importing a Project from a makmake Project File . . . . . . . . . . . . . . . 17
2.1.2 Creating a Project from Stationery . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2 Freezing Exports and Re-importing Projects. . . . . . . . . . . . . . . . . . . . . . . . 32
2.2.1 Freezing Exported Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.2.2 Re-importing Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.2.3 Customizing the Default Import Process . . . . . . . . . . . . . . . . . . . . . . 35
2.3 Using Symbian Project Import Templates . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3 Symbian OS v8.x or v9.x Build Tools Guide 39

3.1 Creating a Symbian OS v8 or v9 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.1.1 CodeWarrior IDE’s Import Platform Support . . . . . . . . . . . . . . . . . . . 40
CodeWarrior for Symbian OS 3

Table of Contents
3.2 Target Settings for Symbian OS v8 or v9 Projects. . . . . . . . . . . . . . . . . . . .40

3.2.1 Build Extras Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
3.2.2 Symbian Compiler Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
3.2.3 Symbian Linker Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
3.2.4 Symbian Common Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
3.3 Precompiled Header Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
3.3.1 Creating Precompiled Header Projects from makmake Projects. . . . .46
3.4 Examining Link Descriptor XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
3.4.1 Link Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
3.4.2 LinkCommand Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
3.5 Creating a Parser DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
3.5.1 Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
3.5.2 Allocating and De-Allocating Memory . . . . . . . . . . . . . . . . . . . . . . . .55
3.5.3 Creating a Custom Parser DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
4 Symbian OS v7 Build Tools Guide 57

4.1 Creating a Symbian OS v7 Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
4.2 Target Settings for Symbian OS v7 Projects . . . . . . . . . . . . . . . . . . . . . . . .58
4.2.1 Preference (.pref) File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
4.2.2 Differences Between Symbian Preference Files and Target Settings .59
4.2.3 Format of The Symbian Preference File . . . . . . . . . . . . . . . . . . . . . . .59
4.2.4 Source Trees Preference Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
4.2.5 Target Settings Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
4.2.6 Symbian Tools Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
4.2.7 Symbian Target Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
4.2.8 Symbian Resources Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
4.2.9 Symbian Installation Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
4.3 Building DLLs with Exports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
4.4 Assembler Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
4.4.1 ARM Assembly Language Programming . . . . . . . . . . . . . . . . . . . . . .73
4.4.2 Intel x86 Assembly Language Programming . . . . . . . . . . . . . . . . . . .73
5 Emulation Debugging 75
5.1 Target Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
5.1.1 Runtime Settings Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
5.1.2 Debugger Settings Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
4 CodeWarrior for Symbian OS

Table of Contents
5.2 Debugging an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

5.3 Debugging an Executable File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.4 Debugging a DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.5 Viewing Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.6 Viewing Symbian OS Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.7 Variable Scoping of Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.7.1 Expression Scoping Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
5.7.2 Limitations of Variable Scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
6 Resource Editor and Resources 85

6.1 Using the Resource Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.2 Resource Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
6.2.1 Resources Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
6.2.2 Bitmaps Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.2.3 AIFs Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
6.3 Building Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.3.1 Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
6.3.2 Kinds of Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.3.3 Tags for Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.3.4 Tags for Bitmaps and AIFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7 Creating Packages 95
7.1 Step 1: Creating .pkg Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.1.1 .pkg Files Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.1.2 .pkg File Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.1.3 Project Files and .pkg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.2 Step 2: Creating .sis Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.2.1 .sis File Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.2.2 Symbian Installer Post-Linker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.2.3 .sis File Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
7.3 Step 3: Uploading .sis Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8 Symbian Environment Editor 103

8.1 Symbian Environments Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8.2 Symbian Environment Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table of Contents
9 Device Debugging 109

9.1 Using Target Resident Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
9.1.1 Starting TRK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
9.2 Target Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.2.1 Runtime Settings Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.2.2 Debugger Settings Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.2.3 Remote Debugging Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.2.4 Remote Download Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.2.5 Remote Connections Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.3 Debugging an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
9.4 Debugging an Executable File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
9.5 Debugging a DLL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
9.6 Debugging via a USB Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
9.7 Viewing Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
9.8 Viewing Symbian OS Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
9.9 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
10 Device Debugging in ROM 145

10.1 Target Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
10.1.1 Symbian Debugging Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
10.2 Debugging in ROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
10.3 Opening Symbolic Files and Setting Breakpoints . . . . . . . . . . . . . . . . . .149
10.3.1 Resuming a Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
10.3.2 Killing a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
10.4 Attaching to a Process or Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
10.4.1 Debugging a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
10.5 Viewing Symbian OS Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
10.6 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
11 Kernel Debugging 153

11.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
11.2 Target Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
11.2.1 Debugger Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
11.2.2 Remote Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
11.2.3 Symbian ARM Debugger Settings . . . . . . . . . . . . . . . . . . . . . . . . .157
11.2.4 Symbian Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161

Table of Contents
11.2.5 Symbian Kernel Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

11.2.6 Remote Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
11.3 Debugging Kernel and Boot-Loaded Device Drivers Example. . . . . . . . 169
11.3.1 Build the Driver Into the ROM Image . . . . . . . . . . . . . . . . . . . . . . 173
11.3.2 Connect the Target Device to the Host Computer. . . . . . . . . . . . . . 173
11.3.3 Configure Target Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
11.3.4 Debugging Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
11.4 Debugging Bare-Board Start-Up Code Example. . . . . . . . . . . . . . . . . . . 183
11.5 Attaching to a Process or Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
11.6 Opening Symbolic Files and Setting Breakpoints . . . . . . . . . . . . . . . . . . 190
11.7 Viewing Processes, Threads, Libraries, and Chunks . . . . . . . . . . . . . . . . 193
11.7.1 Viewing Symbian Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
11.7.2 Viewing Symbian Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
11.7.3 Viewing Symbian Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
11.7.4 Viewing Symbian Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
11.8 Viewing Symbian OS Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
11.9 Supporting Dynamic Targets (OEM only). . . . . . . . . . . . . . . . . . . . . . . . 197
11.9.1 The “Generic”Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
11.9.2 Hardware Configuration Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
11.9.3 Adding a Hardware Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
11.9.4 Modifying an OS Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
12 Kernel Debugging Protocols 205

12.1 Lauterbach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
12.2 Midas RTE for Win32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
12.2.1 Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
12.2.2 RTE for Win32 Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
12.2.3 Remote Connection Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
12.2.4 Debugging Preference Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
12.2.5 Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
12.3 Sophia Target Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
12.3.1 Installation Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
12.3.2 Sophia Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
13 RomBuild Support 213

13.1 Symbian RomBuild Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Table of Contents
13.2 SymbianRomBuild Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
14 Debug Initialization Files 219

14.1 Using Debug Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
14.2 Debug Initialization File Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
14.2.1 Debug Initialization File Command Syntax . . . . . . . . . . . . . . . . . .220
writemem.b . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
writemem.w . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
writemem.l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
writereg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Index 223

1 Introduction
This manual explains how to use the CodeWarrior™ Integrated Development
Environment (IDE) in conjunction with a software development kit (SDK) or
OS development kit (devkit) to create software for the Symbian OS™.
This chapter introduces the CodeWarrior Development Studio for Symbian OS software
and its documentation:
• “What is New”
• “System Requirements”
• “Documentation”
• “Glossary”
• “Features Overview”
• “Contacting Us”
• “Legal Information”
1.1 What is New

This manual covers several new features:
• New standard support includes:
– WINSCW 3.2 support
– RVCT 2.2 support
– DWARF3 support
– GCC-E support
– Symbian SDK 9.1b (Platform Security)
• “Creating a Project” and “Using Symbian Project Import Templates” cover the use
of Symbian Project Templates which enable you to modify a project’s settings and
save it as a template that can be applied to other projects during importing.
• “Re-importing Projects” now uses the Symbian Project Templates which enable you
to re-import a project’s settings with more flexibility.

Introduction
System Requirements
• “Supporting Dynamic Targets (OEM only)” supports dynamic targets, enabling you
to tell the IDE how to support new releases of both hardware and operating systems.
1.2 System Requirements

As mentioned above, you use the CodeWarrior IDE in conjunction with an SDK or devkit
to develop Symbian OS software.
In practice, whether you use an SDK, a devkit, or both depends on the edition of
CodeWarrior for Symbian OS you have (see Table 1.1). Further, if you use an OS devkit,
it must be version 8.1b or higher for EKA2 support, and 9.1b or higher for EKA2 with
Platform Security support.
NOTE This manual describes all the features available for Symbian development.
Access to a specific feature is controlled by the version of the CodeWarrior
Development Studio installed and your licensing agreement.
Table 1.1 Support Package Used for Development with each CodeWarrior Edition
Edition of Support Package

CodeWarrior for Used for Software What You Can Do...
Symbian OS Development
Personal An SDK only (not included) Targets: Series 60, UIQ

Debug: Emulator
Professional An SDK or OS devkit, v7.0s or Targets: Series 60, TechView, UIQ

higher, 8.1b recommended Debug: Emulator, on-device
(not included) debugging
OEM An OS devkit v7.0s or higher Targets: TechView, UIQ SDK

only, 9.0 recommended (not Debug: Emulator, on-device
included) debugging, device debugging in
ROM, kernel debugging
1.3 Documentation
You do not have to read the chapters in this manual sequentially. Use this manual to learn
about using CodeWarrior tools to develop software for the Symbian operating system.
You will find the manuals mentioned in this section on the CodeWarrior Development
Studio for Symbian OS CD.
1.3.1 For everyone

• See the CodeWarrior IDE User's Guide for complete information about the
CodeWarrior Integrated Development Environment (IDE).

Introduction
Glossary
• Read the Release Notes for additional release informaton. To view, choose Help >
CodeWarrior Help from the CodeWarrior menu bar, then click Release Notes in
the Contents list.
1.3.2 If you are new to CodeWarrior IDE

• Read the Quick Start for a fast introduction to using CodeWarrior programming
tools. The Quick Start is installed into the CodeWarrior for Symbian install directory.
1.3.3 For information on the Symbian operating system

• Choose Help > CodeWarrior Help from the CodeWarrior menu bar, then expand
Symbian OS Developement in the Contents list to view the Symbian Developer
Library documentation.
• Read the documentation that comes with the Symbian SDK or development kit you
are using with CodeWarrior Development Studio for Symbian OS software.
1.4 Glossary
The glossary terms in Table 1.2 are used throughout this manual.
Table 1.2 Symbian OS glossary
Glossary Term Description
ABIv1 ABI for ARM Architecture v1.0
ABIv2 ABI for ARM Architecture v2.0
EABI Embedded-Application Binary Interface
EKA1 EPOC Kernel Architecture supporting Symbian OS v6.1, v7.0,

and v8.xa
EKA2 Epoc Kernel Architecture supporting Symbian OS v8.xb and

v9.1
GCC-E GNU Compiler Collection for EABI (ABIv2)
MMP makmake project file
RDI Remote Debug Interface
RVCT RealView Compiler Tools
Symbian Linker CodeWarrior linker used when creating EKA1 projects
Symbian Linker v2 CodeWarrior linker used when creating EKA2 projects
TRK Target Resident Kernel (formerly MetroTRK)

Introduction
Features Overview
Table 1.2 Symbian OS glossary
Glossary Term Description
UDEB Unicode Debug
UDP User Datagram Protocol
UREL Unicode Release
WINSCW Windows CodeWarrior
XSD XML Schema Definition
1.5 Features Overview

The CodeWarrior Development Studio for Symbian OS software is a set of tools for
developing applications for a variety of Symbian OS personal communication devices.
Sony-Ericsson, Nokia, and Motorola are some of the vendors who sell devices that use
Symbian OS.
• SDKs and Development Kits
• Builds Tools
• Emulation Debugging
• Device Debugging
• Device Debugging in ROM
• Kernel Debugging
NOTE Access to a specific feature is controlled by the version of the CodeWarrior

Development Studio installed and your licensing agreement.
1.5.1 SDKs and Development Kits

As mentioned above, you use the CodeWarrior IDE in conjunction with an SDK or devkit
to create Symbian OS software. Whether you can use an SDK, a devkit, or both depends
upon the edition of CodeWarrior for Symbian OS you are using.
Support for SDKs and development kits include:
• Series 60 v3.0 SDK
• Symbian OS v7.x DevKit
• Symbian OS v8.xa DevKit (EKA1)
• Symbian OS v8.xb DevKit (EKA2)
• Symbian OS v9.1 DevKit (EKA2 with Platform Security)

Introduction
Features Overview
Table 1.1 lists each edition of the CodeWarrior for Symbian OS product along with the
SDK or devkit used with each.
1.5.2 Builds Tools

The CodeWarrior IDE for Symbian OS builds applications written in the C/C++
programming language. The applications execute on a Windows® x86-based emulator.
The CodeWarrior IDE also builds applications for devices that run Symbian OS v7.x,
8.xx, and 9.x on ARM® processors. The ARM® compilation tools support both the GNU
Compiler Collection (GCC) and EABI build tools like ARM RVCT 2.2 b435 or later.
Major components of the build tools include:
• Nokia x86 compiler and linker
• ARM command-line tools based on GCC-E v3.4.3. The GCC-E compiler supports
stricter compliance with the ANSI C++ standard and supports only application
creation.
• Support for the Embedded-Application Binary Interface (EABI) build tools, like
ARM RVCT v2.2 b435 or later, GCC-E, and others
For more information, see “Creating Symbian OS Projects”, “Symbian OS v8.x or v9.x
Build Tools Guide”, and “Symbian OS v7 Build Tools Guide”.
NOTE You can download GCC-E from www.codesourcery.com/

gnu_toolchains/arm.
1.5.3 Emulation Debugging

The CodeWarrior Development Studio for Symbian OS product uses the CodeWarrior
compiler, linker, and debugger for Intel x86 processors to build and debug Symbian OS
software that runs on Symbian OS emulators. Use the emulator to quickly build and test
programs on a PC without requiring a physical device.
For more information, see “Emulation Debugging”.
1.5.4 Device Debugging

The CodeWarrior Development Studio for Symbian OS product supports device
debugging in both EKA1 and EKA2 based projects. Use:
• EKA2 projects with both GCC-E and EABI complient tools like RVCT v2.2, GCC-
E, and others
• EKA2 projects with both GCC and EABI complient tools like RVCT v2.1 for ARM
processors
• EKA1 projects with the GCC compiler and linker for ARM processors

Introduction
Features Overview
The CodeWarrior debugger builds and debugs both EKA1 and EKA2 based software
projects that run on Symbian OS hardware devices.
NOTE TRK must be enabled on the target device to support device debugging.
For more information, see “Device Debugging”.
1.5.5 Device Debugging in ROM

The CodeWarrior Development Studio for Symbian OS product supports device
debugging in ROM for both EKA1 and EKA2 based projects. Use:
• EKA2 projects with both GCC-E and EABI complient tools like RVCT v2.2 for
ARM processors
• EKA2 projects with both GCC and EABI complient tools like RVCT v2.2 for ARM
processors
• EKA1 projects with the GCC compiler and linker for ARM processors
The CodeWarrior debugger builds and debugs Symbian OS ROM images for both EKA1
and EKA2 based software projects that run on Symbian OS hardware devices.
NOTE TRK must be enabled on the target device to support device debugging in
ROM.
For more information, see “Device Debugging in ROM”.
1.5.6 Kernel Debugging

The debugger included with the CodeWarrior Development Studio for Symbian OS
product supports stop-mode debugging (also known as kernel debugging) for EKA1 and
EKA2 based projects.
A debugger without stop-mode capability can suspend just your application. The
CodeWarrior stop-mode debugger, in contrast, can halt the target device’s processor.
When the processor is halted, the operating system and all user applications are also
halted. In this state, you can inspect the values of processor registers, memory locations,
and kernel data structures without interference.
For more information, see “Kernel Debugging” and “Kernel Debugging Protocols”.

Introduction
Contacting Us
1.6 Contacting Us
We welcome and consider all comments and suggestions. Please send them to:
Headquarters Nokia
Developer Platform Tools - IDE Solutions
701 Brazos Street, Suite 1000
Austin, Texas, 78701
USA
World Wide Web www.forum.nokia.com/codewarrior
Sales sales.codewarrior@nokia.com
Licensing license.codewarrior@nokia.com
Technical Support www.forum.nokia.com/codewarrior/support
1.7 Legal Information

COPYRIGHTS
Copyright © 2005 Nokia Corporation. All rights reserved. Reproduction, transfer,
distribution or storage of part or all of the contents in this document in any form without
the prior written permission of Nokia is prohibited.
This material, including documentation and any related computer programs, is protected
by copyright controlled by Nokia. All rights are reserved. Copying, including reproducing,
storing, adapting or translating, any or all of this material requires the prior written consent
of Nokia.
TRADEMARKS
Nokia and Nokia Connecting People are registered trademarks of the Nokia Corporation.
Symbian OS is a trademark of Symbian Ltd. CodeWarrior is a trademark or registered
trademark of Metrowerks Corp. in the US and/or other countries. All other tradenames and
trademarks are the property of their respective owners.
DISCLAIMER
NOKIA CORPORATION ("NOKIA") WILL NOT BE RESPONSIBLE IN ANY EVENT
FOR ERRORS IN THIS DOCUMENT OR FOR ANY DAMAGES, INCIDENTAL OR
CONSEQUENTIAL (INCLUDING MONETARY LOSSES), THAT MIGHT ARISE
OUT OF THE USE OF THIS DOCUMENT OR THE INFORMATION IN IT. UNDER
NO CIRCUMSTANCES SHALL NOKIA BE RESPONSIBLE FOR ANY LOSS OF
USE, DATA, OR INCOME, COST OF PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES, PROPERTY DAMAGE, PERSONAL INJURY OR ANY SPECIAL,
INDIRECT, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES
HOWSOEVER CAUSED.

Introduction
Legal Information
THE CONTENTS OF THIS DOCUMENT ARE PROVIDED "AS IS". EXCEPT AS

REQUIRED BY APPLICABLE MANDATORY LAW, NO WARRANTIES OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON-INFRINGEMENT, ARE MADE IN RELATION
TO THE ACCURACY, RELIABILITY OR CONTENTS OF THIS DOCUMENT.
NOKIA RESERVES THE RIGHT TO REVISE THIS DOCUMENT OR WITHDRAW
IT AT ANY TIME WITHOUT PRIOR NOTICE.

2 Creating Symbian OS Projects
This chapter describes the tools and steps needed to create projects targeting Symbian OS
v7.x , v8.x, or v9.x using the CodeWarrior IDE.
• “Creating a Project”
• “Freezing Exports and Re-importing Projects”
• “Using Symbian Project Import Templates”
NOTE Although the CodeWarrior IDE User's Guide describes how to import UNIX-
style make files, this IDE feature is not available with CodeWarrior
Development Studio for Symbian OS software.
2.1 Creating a Project

The CodeWarrior Development Studio for Symbian OS product offers these ways of
creating new projects:
• “Importing a Project from a makmake Project File”
• “Creating a Project from Stationery”
NOTE Projects created using these steps work for Symbian OS v7, v8, and v9 (with
Platform Security) targeted projects.
2.1.1 Importing a Project from a makmake Project File

The CodeWarrior IDE’s Import Project From .mmp File command converts a project
that was created with or copied from a Symbian OS SDK or development kit (version
7.0.7 or higher) to a CodeWarrior project.
Project files in a Symbian SDK or development kit are called makmake files. A makmake
project file ends with the .mmp extension. The CodeWarrior IDE can import a makmake
project (.mmp) file and convert it to a CodeWarrior project (.mcp) file.
This IDE command is convenient because it lets you re-use build information that you
have already defined while using a Symbian OS SDK or development kit. Also, you can

Creating Symbian OS Projects
Creating a Project
copy an example .mmp file from a development kit or SDK and convert to a project for
the IDE. Importing a .mmp file saves you the trouble of creating a new CodeWarrior
project.
Importing an .mmp File

1. Choose File > Import Project From .mmp File on the CodeWarrior menu bar.
The IDE displays the Symbian Importer - SDK Selection window (Figure 2.1).
2. Select vendor and SDK or development kit in the Symbian Importer - SDK Selection
window
The Symbian Importer - SDK Selection window lists the SDKs and development
kits installed on your computer that are compatible with the CodeWarrior IDE. The
SDKs and development kits are grouped by vendor.
a. Select a vendor
The left hand pane in the Symbian Importer - SDK Selection window shows a
list of vendors. The right-hand pane lists all the SDKs or development kits
available from the chosen vendor that are installed on the machine.
NOTE The list of vendors and SDKs that are available varies, depending on which
SDKs are installed on your computer.

Creating a Project
Figure 2.1 Symbian Importer - SDK Selection window
b. Select an SDK or development kit

In the right hand pane of the Symbian Importer - SDK Selection window (Figure
2.1), select the SDK or development kit to use with this project.
c. Click Next
Click the Next button to continue. The Symbian Importer - MMP File Selection
(Figure 2.2) window appears.
NOTE If a message box appears containing the message “No stationery projects found
in selected SDK,” the SDK or devkit you selected does not include
CodeWarrior stationery.
In this case, you cannot use the Symbian Importer to create a CodeWarrior
project that uses the chosen SDK or devkit. You can, however, create a
CodeWarrior project that uses the desired kit by importing one of its makmake
files. See “Importing a Project from a makmake Project File” for instructions.

Creating a Project
Figure 2.2 Symbian Importer - MMP File Selection window
3. Set import file and platform values in the Symbian Importer - MMP File Selection
(Figure 2.2) window
a. Type the file name of .mmp file in the MMP File Selection text field.
You must include the absolute path to the .mmp file. Alternatively, you can click
on the Browse button to locate the .mmp file.
b. In the Platform Selection field, type the names of the platforms for which you
want to build software in the CodeWarrior IDE project, separated by commas (“,”).
For specific platform builds that are different from the default, the Symbian OS
DevKit that is being targeted must support the platform. To determine which
platforms are supported in the DevKit, open a command prompt and type
“makmake /?” (without the quotes). This command shows the specific makmake
version that is currently set as the default target along with the supported platforms.
WARNING! The creation of projects for alternate platforms is only supported by

EKA1-based projects. EKA2 and higher releases no longer support the
use of alternate platforms, or variants.
Some examples of alternate platforms are:

• MINT - Integrator SPP2
• MCOT - Intel Lubbock (PXA-250)

Creating a Project
• MOMAP15xx - Texas Instruments Innovator

For example, to create a project that targets both emulation and a specific platform,
you would enter
WINSCW, MINT
in the Platform Selection field. The IDE then creates the project with build targets
named
• Project WINSCW UDEB
• Project WINSCW UREL
• Project MINT UREL
• Project MINT UDEB
• Build All
where Project is the name of the .mmp file being imported.
Build targets with names ending with “UDEB” build debuggable programs. Build
targets ending with “UREL” build release versions of the same program. The build
target named Build All includes all other build targets in the project.
If the Platform Selection field is empty, the IDE will create a project with build
targets named
• Project WINSCW UDEB
• Project WINSCW UREL
• Project ARMV5 UDEB
• Project ARMV5 UREL
• Project ARM4 UDEB
• Project ARM4 UREL
• Project ARMI UDEB
• Project ARMI UREL
• Project Thumb UDEB
• Project Thumb UREL
• Build All
where Project is the name of the imported .mmp file.
Table 2.1 shows a list of Symbian OS phones and the ABI that you must select to
target a particular phone.

Creating a Project
Table 2.1 Required ARM ABI for Specific Symbian OS Phones
Phone ABI
Sony/Ericsson P800/P900 THUMB
Nokia 7650 ARMI, THUMB
Nokia 3650 ARMI, THUMB
c. Type the makmake file name into the Specify alternate ‘makmake’ name
Enter a script name of no more than 32 characters into this text box if you need to
invoke a makmake script that differs from the default makmake.pl during the
build process. This information is stored into the registry and displayed on the next
project import. Any errors are reported to a new empty editor window.
NOTE Because there is no way to determine what script was used to create a project,
the re-importer option will use the last known makmake name to import a
project.
d. Specify option Create Files in Default Root Directory

Enable the Create Files in Default Root Directory option to tell the IDE to place
all transient project files in the {EPOCROOT}\epoc32\build\
[project]\[platform] directory. If you don’t want to use this default
location, leave this option unchecked. The IDE then creates the files in the same
directory as the .mmp file.
NOTE This is the equivilent of the -D option used by makmake.
e. Click Next
The IDE displays the Symbian Importer - Project Template Selection window
(Figure 2.3).
4. Select the import template to apply to the new project in the Symbian Importer -
Project Template Selection window (Figure 2.3)
a. Select the Symbian Project Import Template to apply to the imported project. The
choices include:
• Enable the Default Symbian Project Import Template option to apply the
default Symbian project template setting. This template provides the default
settings necessary to create a Symbian project.
or
• Enable the Alternate Symbian Project Import Template, and select a
template from the list with the desired template settings. Use this option when

Creating a Project
you import a project that requires special settings or setup. See “Using Symbian
Project Import Templates” for information on how to create your own template
projects.
Figure 2.3 Selecting a Symbian Project Template
b. Click Finish
The CodeWarrior IDE converts the .mmp file to a CodeWarrior project and
displays it in a project window (Figure 2.4).

Creating a Project
Figure 2.4 Project Window After Importing .mmp File
The CodeWarrior IDE creates a project with the same name as the .mmp file that you
imported, except that the CodeWarrior project file ends with the .mcp extension. The
CodeWarrior IDE saves the .mcp file in the same directory where the .mmp file resides.
In addition to the .mcp file, the IDE creates two other files:
• .xml file - used to facilitate the import process
• .pref file - includes information such as the UID, target name, and target type for
EKA1-based projects only. They are not used for EKA2-based projects. For EKA2-
based projects, makmake adds the <project>_uid.cpp file to the project.
The CodeWarrior IDE also creates a directory named ProjectName Data, where
ProjectName is the name of your project. The CodeWarrior IDE uses this directory to
store internal data. Do not modify or move any files in this directory.
The CodeWarrior project contains the source files and other files that were specified in the
.mmp file.
When you import a .mmp file, the CodeWarrior IDE defines the path to project
dependencies. This means that the CodeWarrior project contains the definition of paths to
all libraries and include directories. The project defines these directory paths relative to
the root directory of the SDK or development kit. You can view path definitions in the
Source Trees settings panel. For more information about the Source Trees panel, see the
IDE User’s Guide.
When the CodeWarrior IDE imports a .mmp file, it also adds a preference (.pref) file to
the CodeWarrior project. For more information about the .pref file, see “Preference
(.pref) File”.
Changes that you make to the CodeWarrior project do not affect the original makmake
project (.mmp) file.

Creating a Project
2.1.1.1 XML Project Template Limitations

With the ability to modify default settings you have much more flexibility in how
debugger settings are imported so you can spend much less time setting and resetting
preference panels for target debugging. However, failure to use these templates wisely can
result in many incompatible settings. Here are some general usage tips:
• Only use templates derived from the same SDK. For example, if you set up a project
with an SDK based on OS 7.0, don't try to import projects in other SDKs and/or OS
versions.
• Use the templates only for setting up the debugger settings for protocol plug-ins.
Some things in the import process are flexible and allow you control, while others
are very rigid and give you no control. For example, the Symbian Compiler and
Symbian Linker preferences are always set by the import process and won’t allow
you to create alternate template values. The following preference panels allow you to
set up your own import values. Exceptions for specific items are noted:
Debugger Preferences
– Debugger Settings
– Remote Debugging (except for "Remote download path" edit field)
– Symbian ARM Debugger
– Symbian Debugging
– Symbian Kernel Debugging
Non-Debugging Preferences
– Build Extras
– File Mappings
– Symbian Common (only "Display generated..." option allow you to override)
If you export a project for WINSCW only, you can only import target settings for
WINSCW; other targets will not show up. For example, if you exported only WINSCW
targets and you try to import for GCCE using the exported template, the GCCE target will
not appear because it does not exist in the template.
2.1.2 Creating a Project from Stationery

Stationery is the term the CodeWarrior IDE uses to describe a predefined project file that
you can use as a template to create other similar project files. For more information on
stationery, see the IDE User Guide.
NOTE Before you can create a CodeWarrior project from stationery, you must install
at least one Symbian software development kit (SDK) or OS development kit
(devkit).

Creating a Project
In practice, whether you will use an SDK, a devkit, or both depends on the edition of
CodeWarrior for Symbian OS you are using (see Table 2.2). Further, if you are using an
OS devkit, it must be version 7.0.7 or higher.
Table 2.2 Support Package Used for Project Creation by CodeWarrior Edition
Edition of Support Package

CodeWarrior for Symbian™ OS Used for Project Creation
Personal An SDK only (not included)
Professional An SDK or OS devkit v7.0.7 or higher (not

included)
OEM An OS devkit v7.0.7 or higher only (not

included)
NOTE Many Symbian SDKs and devkits do not include CodeWarrior stationery. If
you are using such a kit, you can still create a CodeWarrior project by
importing any of the kit’s makmake files. See “Importing a Project from a
makmake Project File”.
Creating CodeWarrior Projects using Symbian OS Project Statio-

nery
1. Choose File > New from the CodeWarrior menu bar.
The CodeWarrior IDE displays the New dialog box (Figure 2.5).
2. Select stationery and set project options

Creating a Project
Figure 2.5 New Dialog Box
a. Select stationery from the project stationery list

In the New dialog box, select the stationery for the kind of project you want to
create. For a project targeting the Symbian OS, select Symbian Stationery
Wizard.
It is possible to create a project by selecting Empty Project, but the project that is
created will not contain any files or build settings. You will have to add the files
and configure the settings from scratch.
b. Type a name for the project in the field labeled Project Name.
c. Specify the project directory
Click the Set... button to browse to a directory where the project files will be saved.
The Create New Project... dialog box appears (Figure 2.6).

Creating a Project
Figure 2.6 Create New Project... Dialog Box
d. Create a new folder

Check the Create Folder check box to indicate that you want to create a new
folder that contains all of the project files. The new folder has the same name as the
project file without the file extension.
NOTE The CodeWarrior project manager also creates a directory named ProjectName
Data, where ProjectName is the name of your project. The CodeWarrior IDE
uses this directory to store internal data. Do not modify or move any files in
this directory.
e. Click Save in the Create New Project dialog box

Click the Save button to create the new project directory, and return to the New
dialog box.
f. Click OK in the New dialog box
Once you have selected the stationery, provided a filename, and specified a project
directory, click OK. The IDE displays the Symbian Stationery Wizard - SDK
Selection window.

Creating a Project
Figure 2.7 Symbian Project Wizard - SDK Selection window
3. Select vendor and SDK or development kit in the Symbian Project Wizard - SDK
Selection window
The Symbian Project Wizard - SDK Selection window lists the SDKs and
development kits installed on your computer that are compatible with the CodeWarrior
IDE. The SDKs and development kits are grouped by vendor.
a. Select a vendor
The left hand pane in the Symbian Project Wizard - SDK Selection window
shows a list of vendors. The right-hand pane lists all the SDKs or development kits
available from the chosen vendor.
NOTE The list of vendors and SDKs that are available varies, depending on which
SDKs are installed on your computer.
b. Select an SDK or development kit

In the right hand pane of the Symbian Project Wizard - SDK Selection window
(Figure 2.7), select the SDK or development kit to use with this project.
c. Click Next
Click the Next button to continue to the Symbian Project Wizard - Template
Selection (Figure 2.8) window.

Creating a Project
Figure 2.8 Symbian Project Wizard - Template Selection window
4. Select template in the Symbian Project Wizard - Template Selection window

a. Select template stationery from list
The Symbian Project Wizard - Template Selection (Figure 2.8) window lists the
available template stationery. The list of available stationery varies, depending on
the SDK or development kit chosen in the previous window.
Project stationery contains files and build settings that provide a starting point for
developing your program. Select the stationery that you want to use as the basis for
your new project. Project Stationery is located at: {SDK}\epoc32
\stationery.
b. Enable Generate Platform Security Application (Convert APP to EXE)
Under Symbian OS v9.1, Platform Security provides users with a more secure
mobile environment through the use of secure applications. Activate this option to
convert a standard APP into an EXE that supports the available platform security
features.
See the Symbian OS SDK documentation for more information on using Platform
Security.
c. Click Next
Click the Next button to continue to the Symbian Project Wizard - Target and
File Gen Options (Figure 2.9) window.

Creating a Project
Figure 2.9 Symbian Project Wizard - Target and File Gen Options window
5. Select target and file options in the Symbian Project Wizard - Target and File Gen
Options window
The Symbian Project Wizard - Target and File Gen Options (Figure 2.9) window
shows information about the target application or file.
a. In the Platform Selection field, type the names of the platforms for which you
want to build software in the CodeWarrior IDE project, separated by commas (“,”).
For specific platform builds that are different from the default, the Symbian OS
DevKit that is being targeted must support the platform. To determine which
platforms are supported in the DevKit, open a Command Prompt window and type
“makmake /?” (without the quotes). This command shows the specific makmake
version that is currently set as the default target along with the supported platforms.
b. Enter Application Identifiers information into the Application Title and Unicode
UID text boxes. The application identifiers include:
• Application Title–program title substituted in the Nokia stationery. Not used
anywhere else at this time.
• Unicode UID–enter the UID3 value, the application’s unique identifier. Click
Test UID to generage a temporary value. Permanent values must be requested
from Symbian (uid@symbiandevnet.com, subject = UID Request) to
commercially distribute the program.
c. Enter File Comment Information into the Copyright and Author text boxes

Freezing Exports and Re-importing Projects
• Copyright–enter copyright information for inclusion in source file comments.

• Author–enter author information for inclusion in source file comments.
d. Click Finish
Click the Finish button to create the project. The CodeWarrior IDE creates the
files and project folder based on the stationery that you selected. The CodeWarrior
IDE displays a new Project window (Figure 2.10).
Figure 2.10 Project Window
A project created from stationery contains example source files, a .pref file, and
other files that give you a starting point for your project. You can modify these
files and save them with a new name or replace them with your own files.
2.2 Freezing Exports and Re-importing Projects

This section describes how to use addtional project level capabilities that include:
• “Freezing Exported Projects”
• “Re-importing Projects”
2.2.1 Freezing Exported Projects

You freeze a project, normally a DLL, to ensure backward compatibility of a new release.
The result is a .def file that can be imported into other projects.

NOTE A .def file must be included in the project target to export a project. The IDE
will not create one if it is missing.
Freezing Exported Symbian OS Projects

To freeze an active project:
1. Select Project > Freeze Symbian Exports for <TargetName> from the CodeWarrior
menu bar.
If project needs updating, a dialog box appears with a warning message.
2. Click OK.
The IDE constructs the appropriate command line to update the project files and shows
it in a new editor window, then shows a confirmation dialog box.
3. Click OK in confirmation dialog box.
IDE begins updating the project.
2.2.2 Re-importing Projects

You can now re-import a MMP file into an active project. You would re-import a project’s
MMP file because:
• The MMP file has changed and you want the project to acquire those changes, or
• You want to reset the project’s state back to the original MMP settings
CAUTION All changes made to the .mcp file are lost when the MMP settings are re-
imported.
Before the IDE can re-import an MMP file, the following information is required:
• {SDK Root} must be specified–this enables the plug-in to locate the correct SDK
version of makmake.pl to use when re-importing the MMP file.
• The MMP file must be in the project target.
• Build target–the build targets that makmake.pl understands are part of the
CodeWarrior project's name. To locate the correct target, the IDE uses this naming
convention:
[PROJECT_NAME] <BUILD TARGET> <UDEB | UREL>
Where <BUILD TARGET> is the target list passed to makmake.pl during re-
import. Here are some target name examples that work:
HELLOWORLD WINSCW UDEB
ARM4 UREL

Driver THUMB UDEB

If these conditions are met, the project is ready to re-import the MMP settings.
Re-importing an MMP File to a Project

To re-import a MMP file into an active project:
1. Select Project > Re-Import Symbian Project <ProjectName> from the CodeWarrior
menu bar.
If the three conditions mentioned above are met the Project Re-import Settings
window (Figure 2.11) appears with options for re-importing the project. These options
are identical to those that appear when importing the original MMP file as described in
“Importing an .mmp File” and include:
• Build Targets – Type the names of the platforms for which you want to build
software in the CodeWarrior IDE project, separated by commas (“,”).
• Alternate makmake name – Enter a script name of no more than 32 characters into
this text box if you need to invoke a makmake script than differs from the default
makmake.pl during the build process.
• Add temporary files under \epoc32\ build\[project]\[platform] – Enable this
option to tell the IDE to place all transient project files in the {EPOCROOT}
\epoc32\build\[project]\[platform] directory. If you don’t want to
use this default location, leave this option unchecked.
• Select a CodeWarrior XML Project Template – Select the Symbian Project
Import Template to apply to the imported project. The choices include:
• Enable the Default Symbian Project Import Template option to apply the
default Symbian project template setting. This template provides the default
settings necessary to create a Symbian project.
or
• Enable the Alternate Symbian Project Import Template, and select a
template from the list with the desired template settings. Use this option when
you import a project that requires special settings or setup. See “Using Symbian
Project Import Templates” for information on how to create your own template
projects.

Figure 2.11 Project Re-import Settings window
2. Click OK in the Project Re-import Settings window.

The IDE imports the MMP settings into the project.
2.2.3 Customizing the Default Import Process

You can customize the default settings used during the import process for these preference
panels:
• Debugger Target
• File Mappings
• Remote Connections
• Symbian Debugging
• Symbian Kernel Debugging
Changes made to an XML file that controls a specific EKA import settings causes all
subsequent import operations to use the new settings as the default. For example, one
could change the default Remote Connection setting panel option ConnectionName
value from Symbian TRK to Lauterbach in the XML file.

Using Symbian Project Import Templates
These XML template files contain all the preferences settings for all IDE supported build
types (e.g. WINSCW, ARMV5, THUMB, etc.):
• cw_project_template_v4.xml–the template used for Symbian OS v3.0
• cw_project_template_v3.xml–the template used for Symbian OS v2.8.
• cw_project_template_v2.xml–the template used for Symbian OS v2.0-2.5.
These templates are located in the {SDK Root}\epoc32\tools directory.
TIP When using template files, we recommend simply choosing the latest version and
modify as required.
Modifying Import Default Settings

To modify one of these XML template files:
1. Open the XML file
2. Use the IDE to locate and open the XML to change. The default XML template files
are located in the {SDK ROOT}\epoc32\tools\ directory.
3. Search for the preference panel (example: Remote Connection) to modify
4. Search for the default setting <NAME> option (example: ConnectionName) to change
5. Carefully edit the <NAME> option’s <VALUE> setting
6. Save your changes
7. The next time the modified XML file is used to re-import a MMP file, the new default
settings are used by the IDE.
2.3 Using Symbian Project Import Templates

You can create Symbian Project Import Templates for later use when importing a project
by exporting a current Symbian OS project as an XML file. This enables you to customize
a project’s configuration and settings and use identical ones for other projects.
Templates are stored in the {CW_DIR}\Symbian_Support\
Project_Import_Templates folder.
For more information, see “XML Project Template Limitations.”
Exporting a Symbian Project as a Template

To export a project file as a Symbian Project Import Template:

Troubleshooting
1. Select the File > Manage Symbian Project Template > Export Symbian Template
for Project Project_Name menu item from the CodeWarrior menu bar
The Export Symbian Project Template window appears.
2. Enter a name for Symbian Project Import Template file in the File name text field
The XML file is stored in the default Project_Import_Templates folder. If
you change this default save location the filename does not appear as a template option
when you import a MMP file.
3. Click Save
The IDE saves the Symbian Project Import Template in XML format. The next time
you import a project, the Symbian Project Import Template appears as one of the
alternates.
See “Importing a Project from a makmake Project File” for information on importing a
project.
Importing a Symbian Project Template

To apply a Symbian Project Import Template to a project file:
1. Select the File > Manage Symbian Project Template > Import Symbian Project
Template menu item from the CodeWarrior menu bar
The Select Symbian Project Template window appears.
2. Locate and select the Symbian Project Import Template file to import
3. Click Open
The IDE applies the Symbian Project Import Template settings to the current project.
2.4 Troubleshooting
When attempting to import and make a project, the IDE reports the error:
makmake tool failed to generate the project XML file
What is wrong?
This error indicates that Perl is not installed, or that the wrong version of Perl is present.
To correct, remove the current Perl installation, if any, and rerun the UIQ or Series 60
SDK installer. This installs the correct supported version of ActivePerl version 5.6.1.
How can I get more useful diagnostic information from MMP Importer reported errors
that would help track down the problem?
Enter the string “-keeptempfiles” into the Platform Selection text box on Page 2 of
the Importer Wizard. This tells the IDE to save the temporary files it creates during an
import operation. For example:
-keeptempfilesARM4,WINSCW

Troubleshooting
The MMP Importer first checks this flag, and deletes it if it exists. The two files that
appear in the MMP project import directory are:
generate_cw.pl -> Perl script that calls makmake
cw_log.txt -> Verbose output of makmake

3 Symbian OS v8.x or v9.x Build
Tools Guide
This chapter describes how to use the CodeWarrior IDE to configure build targets in a
Symbian OS v8.x and v9.x projects, and build them into applications, executable files, and
DLLs. The topics include:
• “Creating a Symbian OS v8 or v9 Project”
• “Target Settings for Symbian OS v8 or v9 Projects”
• “Precompiled Header Support”
• “Examining Link Descriptor XML Files”
• “Creating a Parser DLL”
Refer to Resource Editor and Resources for information on building resources that work
with Symbian OS projects.
3.1 Creating a Symbian OS v8 or v9 Project

You create a Symbian OS v8 or v9 project exactly as you do a Symbian OS v7 project. For
details see:

Symbian OS v8.x or v9.x Build Tools Guide
Target Settings for Symbian OS v8 or v9 Projects
3.1.1 CodeWarrior IDE’s Import Platform Support

The CodeWarrior IDE can import projects created for different platforms from many
different Symbian OS DevKits. Table 3.1 provides a list of import platforms currently
supported by the CodeWarrior IDE as well as those planned for future DevKit releases.
Table 3.1 Supported Symbian OS platforms
Platforms Symbian OS Single Real Time Real Time

v7.0.x & Process kernel kernel
v7.0s kernel (EKA2) v8.xb (EKA2) v9.x
(EKA1) v8.xa
ARM4 Yes Yes Yes
ARMV5 Yes Yes
ARMV6 Yes
ARMI Yes Yes
GCC-E Yes
THUMB Yes Yes
WINSCW Yes Yes Yes Yes
3.2 Target Settings for Symbian OS v8 or v9

Projects
The CodeWarrior IDE implementation of the Symbian Compiler adhered to a strict
sequence of command lines when creating executable Symbian files. With the release of
Symbian Compiler v2, a more robust and customized method of generating command
lines is available.
When you choose Symbian Linker in the Target Settings Panel for a Symbian project, the
IDE follows a strict linking sequence to generate command lines that call various Symbian
tools to create a Symbian executable. See the chapter “Symbian OS v7 Build
Tools Guide” for information on projects that use this linker.
Choosing the Symbian Linker v2 in the Target Settings Panel causes the IDE to use Link
Descriptor files (.cwlink) to generate command lines that call the Symbian tools that in
turn create a Symbian executable. A link descriptor file provides a way to sequence
arbitrary tool and system commands to create Symbian OS executables. The remainder of
this chapter provides information on projects that use Symbian Linker v2.

NOTE The CodeWarrior IDE does not support the direct conversion of a v1 compiler
project to a v2 compiler project. Instead, users should adjust their .mmp files
and re-import into the IDE as a new project.
These panels are common between Symbian Linker v2 and Symbian Linker projects:
• “Build Extras Panel”
• “Source Trees Preference Panel”
• “Target Settings Panel”
The following panels are available to control project options when you choose Symbian
Linker v2 in the Target Settings panel.
• “Symbian Compiler Panel”
• “Symbian Linker Panel”
• “Symbian Common Panel”
• “Symbian Tools Panel”
3.2.1 Build Extras Panel

The Build Extras settings panel contains options that define how the CodeWarrior IDE
builds a project. When building a Symbian project, note the following issues:
• The Generate Browser Data From > Compiler setting is not supported for
Symbian Linker v2, use the Language Parser setting instead.
• The Language Parser can only generate browser information from the macros it finds
in the project source files. If a Symbian tool contains implicit macros, then these
must be passed using the Macros fields in the Symbian Compiler settings panel to
create the most complete browser information and file dependency generation.
See the CodeWarrior IDE User Guide for more information.
3.2.2 Symbian Compiler Panel

The Symbian Compiler settings panel (Figure 3.1) controls the options for the Symbian
Compiler v2.

Figure 3.1 Symbian Compiler Panel
Table 3.2 Symbian Compiler panel—options
Option Explanation
Compiler Choose a compiler from the items listed in the Compiler

drop-down menu. The available Symbian OS compilers
are:
• ARM GCC (gcc.exe)
• ARM RVCT (armcc.exe)
• x86 Compiler (mwccsym2.exe)
• THUMB GCC (thumb-epoc-pe-
gcc.exe)
The contents of the Compiler drop-down menu is
constructed using information in the .cwcomp file.
Prefix File Specify the name of the prefix file for the build target. If
a path is not specified, the compiler searches for the file
in the access paths, then passes it to the language
parser for browser database generation. The Prefix File
name is limited to 256 characters.

Table 3.2 Symbian Compiler panel—options (continued)
Option Explanation
Macros Specify a comma-delimited list of preprocessor macros

that are passed to the compiler for debug and release
build targets, and to the language parser for browser
database generation.
Macro can be entered in two ways:
• Comma-delimited format, as in:
FOO,BAR
Passed to the command-line using the “-d
FOO -d BAR” format
• Non-comma-delimited format:
-d FOO -d BAR
Which is passed exactly as entered. Other
compilers may vary in macro switches.
The Macros list is limited to 1024 characters.
Arguments Specify a list of Symbian generated arguments that are

passed to the compiler for debug and release build
targets. The Arguments list is limited to 1024 characters.
See “Additional Command Line” in the Symbian Linker
panel for a method of passing user generated
arguments.
Turn on CodeTEST Instrumenter Controls whether the CodeTEST performance tool

provides in-circuit software timing measurement for
the program. Turn this option on to compile your code
with performance testing capabilities. This option is
only enabled when a CodeTEST descriptor file (with
extension .ctcomp) is available for the selected
compiler.
Enable SWIC Controls the CodeTEST Software In-Circuit (SWIC)

capability for integrating application software with
target hardware.
NOTE This option is not available for emulator builds
like WINSCW.
3.2.3 Symbian Linker Panel

The Symbian Linker settings panel (Figure 3.2) controls the options for Symbian Linker
v2.
The following hidden arguments appear in the XML Export/Import file:
• canDebug – The makmake utility sets this value to ‘0’ or ‘1’ based upon the linker
output file type. Default setting is ‘0’.

• canRun – The makmake utility sets this value to ‘0’ or ‘1’ based upon the linker
output file type. This argument is disabled for all non-WINSCW targets. Default
setting is ‘0’.
NOTE To modify a hidden argument, you must Export the panel settings to an XML
file, modify the option in the XML file, then Import the updated XML file to
the settings panel.
Figure 3.2 Symbian Linker Panel
Table 3.3 Symbian Linker panel—options
Option Explanation
Output File Specifies the name of the final executable.
Additional Command Line Specifies a list of user generated arguments to pass to

the compiler for debug and release build targets. The
Additional Command Line list is limited to 1024
characters.
See “Arguments” in the Symbian Compiler panel for a
list of Symbian generated arguments.
Importer Library Specifies the path to the import library. If a path is not
specified, the compiler searches for the file in the access
paths, then passes it to the language parser for browser
database generation. The Import Library name is
limited to 256 characters.

Precompiled Header Support
3.2.4 Symbian Common Panel

The Symbian Common settings panel (Figure 3.3) controls where Symbian Linker v2
finds the Symbian build tools.
Figure 3.3 Symbian Common Panel
Table 3.4 Symbian Common panel—options
Option Explanation
Development Kit EPOCROOT Specifies the path to the selected development kit’s
epoc32 directory. The IDE sets the PATH for the tool
executing the current build process using a source tree
relative format. For example, the root directory used for
tools is: \\epoc32\tools.
Display generated commands in Controls whether the IDE displays the command lines
the message window generated by the various tools in the Messages window.
Turn this option on to display the generated command
lines. Turn this option off to prevent display of any
generated command lines.
3.3 Precompiled Header Support

Precompiled header support is available for Symbian OS projects that use the x86
compiler. Precompiled header files use the .pch++ extension. Precompiled headers are
supported when these settings are used:

Precompiled Header Support
• The target’s linker is set to Symbian Linker v2

• The target’s compiler is set to CodeWarrior x86 compiler (WINSCW)
NOTE The x86 compiler supports the precompile command for Symbian OS projects
although others may do so in the future.
You can precompile a header file by opening it and selecting Project > Precompile from
the CodeWarrior menu bar. You can also right-click the file name in the project window
and select Precompile from the contextual menu.
A precompiled header file (.pch++) outputs to a new identically named file with the
.mch++ extension. For example, HelloWorld.pch++ outputs as
HelloWorld.mch++. C++ source files must use the .pch++ extension.
Listing 3.1 shows an example of a precompiled header source file called
pch_test.pch++.
Listing 3.1 .pch Precompiled Header example
#include <e32def.h>
#pragma precompile_target "pch_test.mch++"
#define FOO 1
#define LATIDA 345
typedef struct foo

{
int i, j, k, l, m;
char foobar[256];
} foo;
The resultant output file, pch_test.mch++ can be included in other source or prefix
files as:
#include pch_test.mch++
For more information on precompiled headers, see the C Compiler Manual and IDE
User’s Guide.
3.3.1 Creating Precompiled Header Projects from makmake

Projects
You can create a precompiled header project by creating a TARGETTYPE of “lib” and
adding all the precompiled headers using the SOURCE keyword. The project should be
able to create on .mch++ file for each .pch++ file listed and output to a dummy lib
file. Listing 3.2 shows an example of a makmake precompiled header.

Examining Link Descriptor XML Files
Listing 3.2 makmake Precompiled Header example
TARGET pch_test_ignore.dummy
TARGETTYPE lib
UID 0x100039CE 0X10008ACE
TARGETPATH \system\apps\pch_test
SOURCEPATH .
SOURCE pch_test.pch++
USERINCLUDE .
SYSTEMINCLUDE \epoc32\include
SYSTEMINCLUDE \epoc32\include\techview
3.4 Examining Link Descriptor XML Files

A link descriptor file is an Extensible Markup Language (XML) file that describes how a
particular link operation should occur. It consists of a series of link descriptors that
provide the information the Symbian Linker v2 requires to generate command lines for
various Symbian tools and perform the requested link operation and is identified by the
.cwlink extension.
Symbian OS v8.x projects use . cwlink descriptor files to replace the .pref file used
by Symbian OS v7 projects. See “Symbian OS v7 Build Tools Guide” for information on
projects targeted for Symbian OS v7.
A CodeWarrior project must contain at least one link descriptor file (.cwlink), and can
have more than one. The order in which a link descriptor file is processed is controlled by
its location in the Link Order view of the project window. The IDE reads each link
descriptor file, executes its sequence of link commands, then the next, until all are
processed.
Because a link descriptor file is formatted using XML, it can easily be edited to modify its
behavior, or additional ones created to perform additional linking operations.
WARNING! Because an XML file can be edited in any text processor, care must be
exercised to ensure that the XML is valid; otherwise, errors in linking
will occur, stopping the build process.
The skeleton of a . cwlink descriptor file appears in Listing 3.3. It is not complete, but
illustrates the link descriptor file format.
Listing 3.3 Skeleton .cwlink descriptor file
<template-file xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.forum.nokia.com/schemas/
2005/CWIDE/SymbianLinkDescriptor.xsd">
<template>

<version>1</version>
<setting uuid-alias="." entry="linkCommandSet">
<array inheritance="none">
<struct>
<setting uuid-alias="." entry="linkCommand">

<simple> link command with variables </simple>
</setting>
<setting uuid-alias="." entry="outputParser">

<simple> location of parser DLL</simple>
</setting>
<setting uuid-alias="." entry="parseStdOut">

<simple> true or false</simple>
</setting>
<setting uuid-alias="." entry="parseStdErr">

<simple> true or false</simple>
</setting>
<setting uuid-alias="." entry="toolIDCode">

<simple> long</simple>
</setting>
</struct>

</array>
</setting>




<setting uuid-alias="." entry="textFileDumpDefinitions">

<struct>
<setting uuid-alias="." entry="dumpFileContent">

<simple>info to write to file</simple>
</setting>
<setting uuid-alias="." entry="dumpFileName">
<simple>file name</simple>
</setting>
</struct>

</array>
</setting>




<setting uuid-alias="." entry="environmentVariable">

<struct>
<setting uuid-alias="." entry="envVariableName">

<simple>name of environment variable</simple>
</setting>
<setting uuid-alias="." entry="envVariableValue">

<simple>value of variable, will do symbol subst</simple>
</setting>
<setting uuid-alias="." entry="prependVariable">

<simple>true | false</simple>
</setting>
</struct>

</array>
</setting>



<setting uuid-alias="." entry="symbolDefinitions">

<struct>
<setting uuid-alias="." entry="symbolName">
<simple>name of symbol to create, this file only</simple>
</setting>
<setting uuid-alias="." entry="symbolValue">
<simple>value of symbol name, will do symbol
substitution</simple>
</setting>
</struct>


</array>
</setting>
</template>
</template-file>
The link descriptor file starts with a reference to the XML Schema Definition (.xsd)
which defines how the tags and content are arranged within the document. In this case, the
.xsd file is called SymbianLinkDescriptor.xsd.

The next line opens the file with a template command, followed by the version of the
file. The setting command next defines the start of the first LinkCommandSet,
followed by the array of setting definitions required to implement the
LinkCommandSet elements. Note that multiple linkCommandSets definitions are
possible in a file.
NOTE The value of the <setting> field is not type-checked.
3.4.1 Link Descriptors

A link descriptor file consists of a sequence of XML elements that contain variables the
IDE build system can understand and uses to perform symbol replacement. The basic
elements that define the link descriptor syntax are shown in Table 3.5.
Table 3.5 Link Descriptors
Link Descriptors Description
<template-file> ... Defines the start and end positions of a link

</template-file> descriptor file.
<template> ... Defines the start and end positions of the

</template> body portion of a link descriptor file.
<setting Defines the start and end positions of a

entry="linkCommandSet"> single linkCommandSet entry in a link
... descriptor file. See LinkCommandSet
</setting> Elements for a list of member elements a
linkCommandSet can contain.
3.4.1.1 LinkCommandSet Elements

A linkCommand symbol defines a command process that the IDE must perform as part
of the build system. Table 3.6 provides a list of all valid linkCommand symbols and
their descriptions that the IDE understands.
Table 3.6 LinkCommandSet member elements
Link Commands Description
actionOverrides Override any tool action based on the file

extension. For example, RVCT compilation
requires a different compile sequence for
.cia files, see Listing 3.3 for command
sequences.
addProjectTargetEntry Add files to a project via compiler descriptor

definitions.

Table 3.6 LinkCommandSet member elements
Link Commands Description
firstLibProcessing Use to add a special library separately from

the libraries listed in the link order. The
library defined here should only be listed by
name (no paths). This definition works in
conjunction with the
${var:FIRST_LIB} symbol that goes
in the linkCommand.
linkCommand The command that CodeWarrior will

execute as part of the build system. This
must be one of the valid and defined
“LinkCommand Symbols”.
linkInformation Use to post content to the Errors &

Warnings window as Information.
linkWarning Use to post content to the Errors &

Warnings window as Warnings.
outputParser The name of the DLL used to parse stdout

and stderr and return the information back
to the Link Adapter for display in the IDE’s
Errors & Warnings window. See “Creating a
Parser DLL” for more information.
parserID An ID value passed to an external parser

that it can use to determine which parsing
algorithm to use for a particular tool. Use
this value when the parser must support
more than one parsing algorithm in a single
DLL.
parseStdErr A boolean value that instructs the parser to

parse stderr or not. Default is true.
parseStdOut A boolean value that instructs the parser to

parse stdout or not. Default is true.
postActionIdentifiers Specifies an arbitrary tool action sequence

that occurs during the “default” action. Use
the array to define the sequence of tool
actions.
preActionIdentifiers Specifies an arbitrary tool action sequence

that occurs before the “default” action. Use
the array to define the sequence of tool
actions.

WARNING! Each linkCommandSet member must use the following format in

order to properly validate against the schema:
<setting uuid-alias = "." entry="entry">

<simple> value </simple>
</setting>
Settings that don’t follow this format will fail validation or fail to be
read during parsing.
NOTE You can use Win32 system calls like "Del" if you prepend the call with
cmd.exe like this "cmd.exe /C".
3.4.2 LinkCommand Symbols

A linkCommand symbol defines a command process that the IDE must perform as part
of the build system. Table 3.7 provides a list of valid linkCommand symbols and their
descriptions the IDE understands.
Table 3.7 LinkCommand Symbols
Symbol Description
${Compiler} CodeWarrior product installation

directory.
${output.file.extension} The extension from the Output File

text box in the Symbian Linker panel.
For example: .EXE.
${output.file.name} Contents of the Output File text box in

the Symbian Linker panel with the
extension. For example:
HELLOWORLD.EXE.
${output.file.root} Contents of the Output File text box in

the Symbian Linker panel without the
extension. For example:
HELLOWORLD.
${output} The output directory specified in the

Target Settings panel.
${Plugins} Path to CodeWarrior plug-ins directory

(<cw_install>\bin\plugins).

Symbol Description
${Project} The directory of the .mcp file.
${source.name.double_delimiter} Use to double delimit source files.

Prevents delimiters being stripped
from .c files and preventing
debugging.
${System} System directory (i.e. c:\winnt).
${target.data} The CodeWarrior

<Project>_Data directory for
the current build target.
${var:COMMON_LINK_OBJ} Adds the link flags from the Additional

Command Line text box in the
Symbian Linker panel.
${var:DEF_FILE} The first .def file listed in the Link

Order view of the project window.
${var:FIRST_LIB} The full path for the library defined in

the XML entry for
firstLibProcessing. If
firstLibProcessing is defined
and the
library exists in the link order, it is
replaced with this symbol (quoted
path). If firstLibProcessing
is not defined, the library will be
added to the ${var:LIBS} symbol
instead
${var:IMPORT_LIBRARY} The import library specified in the

Import Library text box in the Symbian
Linker panel.
${var:IMPORT_LIBRARY_NO_EXT} The import library specified in the

Import Library text box without the
file extension in the Symbian Linker
panel.
${var:LIBS} Adds all the libraries of the current

build target to the command line.

Creating a Parser DLL
Symbol Description
${var:LIBS_NO_PATH_VTBLEXPORT} Appends “(VtblExports.o)“ to the

end of the import library defined in
the Symbian Linker settings panel.
Used for EABI builds.
${var:LINK_OBJ} The list of project object files. These

files are stored in the
<project>_Data\ObjectDat
a directory.
${var:LINK_OBJS_NO_PATH} Object file names without the path.
${var:KIT_EPOCROOT} The installation location of the SDK

specified in the Development Kit
EPOCROOT text box in the Symbian
Common panel.
3.5 Creating a Parser DLL

It’s possible to create a custom parser that will do exactly what you need. This section
describes the exported interface necessary to receive data from the IDE and the structure
used to fill in errors, warnings, and information required to report the same in the Errors &
Warnings window.
NOTE When not defining a parser, the Linker Adapter uses the default parser that is
built into the Linker Adapter. This parser assumes a gcc message-style format.
NOTE Exporting parser functionality is only supported for the Linker Adapter. The
compiler uses the same parser as Symbian 2.5 and its predecessors.
An example of a parser DLL is located in the C:\Program Files\Metrowerks\

CodeWarrior for Symbian\Symbian_Support
\SymbianExampleParserPlugin\ directory. Use this as a starting framework to
write your own custom parser.
3.5.1 Exporting
Assuming that the linker adapter has loaded the Parser DLL correctly, the following
exported interface is located and called:
__declspec(dllexport) void * ParseMessages( char *inToolOutput,

unsigned int inToolID, vector<sToolParseInfo> &outParseInfo)

{ … do work here }
The ParseMessages() method is required to fill in the following data structure (one
per message):
typedef struct sToolParseInfo {

std::string message;
std::string file; // optional, must be full path (not relative)
long lineNumber; // 0 if no line number
int errorLevel; // error, warning, or info
}
The following error levels should be used:
/* message types, used for errorlevel parameter to message routines */

enum {
messagetypeInfo, /* informational only */
messagetypeWarning, /* warning message */
messagetypeError /* error message */
};
3.5.2 Allocating and De-Allocating Memory

A parser DLL requires memory to perform its function. However, because the DLL can
use any runtime configuration, it is recommended that memory management be placed on
the side of the DLL and not with the IDE. The __declspec interfaces defined below enable
the DLL to allocate and de-allocate memory as required.
To allocate a memory block, use the method shown in Listing 3.4.
Listing 3.4 Allocating memory for a parser DLL example
__declspec(dllexport) std::vector<sToolParseInfo>
*NewMWCustomParser(long version) {
// allocate and return pointer to vector<sToolParseInfo>
}
To de-allocate the memory block, use the method shown in Listing 3.5.
Listing 3.5 De-allocating memory used by a parser DLL example
__declspec(dllexport) DeleteMWCustomParser(std::
vector<sToolParseInfo>*tpi) { delete tpi; }

3.5.3 Creating a Custom Parser DLL

The example in Listing 3.6 demonstrates how to create a custom parser DLL.
Listing 3.6 Custom parser pseudocode example
NewMWCustomParser()
{
std::vector<sToolParseInfo> *tpi= new std::vector<sToolParserInfo>;
return tpi;
}

4
4 Symbian OS v7 Build
Tools Guide
This chapter describes how to use the CodeWarrior IDE to configure build targets in a
Symbian OS v7 project, and build them into applications, executable files, and DLLs. The
topics include:
• Creating a Symbian OS v7 Project
• Target Settings for Symbian OS v7 Projects
• Building DLLs with Exports
• Assembler Overview
NOTE Although the CodeWarrior IDE User's Guide describes how to import UNIX-
style make files, this IDE feature is not available with CodeWarrior
Development Studio for Symbian OS software.
Refer to Resource Editor and Resources for information on building resources that work
with Symbian OS projects.
4.1 Creating a Symbian OS v7 Project

You create a Symbian OS v7 project exactly as you do a Symbian OS v8 project. For
details see:

Symbian OS v7 Build Tools Guide
Target Settings for Symbian OS v7 Projects
4.2 Target Settings for Symbian OS v7 Projects

The CodeWarrior IDE implementation of the Symbian Compiler adhered to a strict
sequence of command lines when creating executable Symbian files. With the release of
Symbian Compiler v2, a more robust and customizable method of generating command
lines is available.
If the Symbian Linker is chosen as the Linker for a Symbian project in the Target
Settings Panel, the IDE follows a strict linking sequence in order to generate command
lines that call various Symbian tools to create a Symbian executable. The remainder of this
chapter provides information on projects that use Symbian Linker.
When Symbian Linker v2 is chosen as the Linker for a Symbian project in the Target
Settings Panel, the IDE uses Link Descriptor files (.cwlink) to generate command lines
that call the Symbian tools to create a Symbian executable. A link descriptor file provides
a way to sequence arbitrary tool and system commands to create Symbian OS executables.
See the chaper “Symbian OS v8.x or v9.x Build Tools Guide” for information on projects
that use Symbina Linker v2.
The preferences that control how the CodeWarrior IDE builds software for Symbian OS
v7 projects:
• “Preference (.pref) File”
These panels are common between Symbian Linker and Symbian Linker v2 projects:
• “Source Trees Preference Panel”
• “Target Settings Panel”
• “Symbian Resources Panel”
The following panels are available to control project options when you choose Symbian
Linker in the Target Settings panel.
• “Symbian Tools Panel”
• “Symbian Target Panel”
• “Symbian Installation Panel”
4.2.1 Preference (.pref) File

The Symbian Preference File (.pref file) is a source file that contains options and
commands that the CodeWarrior IDE uses for Symbian OS build targets. You must add a
Symbian Preference File in each build target of your project. If you create a project by
following the steps in “Importing a Project from a makmake Project File”, or “Creating a
Project from Stationery”, the IDE creates a Preference File for you.
Topics in this section discuss the differences between Preference Files and IDE target
settings and the format of a Preference File:
• Differences Between Symbian Preference Files and Target Settings
• Format of The Symbian Preference File

NOTE The .pref file is only used for projects that employ the Symbian Linker to
target Symbian OS v7 executables. Projects that target executables for
Symbian Linker v2 use link descriptor files instead. See “Refer to Resource
Editor and Resources for information on building resources that work with
Symbian OS projects.” for more information.
4.2.2 Differences Between Symbian Preference Files and

Target Settings
A CodeWarrior IDE project typically has several build targets. For example, you might
create one build target that is configured to create a debuggable version of your
application. You might create another build target to build a release version of your
application. Both of these build targets can exist in the same project.
The IDE applies the options and commands in a Symbian Preference File to all build
targets in a project. In other words, your Symbian OS project will use one Symbian
Preference File for all build targets. However, the settings that you specify in the target
settings panels can be different for each build target.
4.2.3 Format of The Symbian Preference File

The filename of a Symbian Preference File ends with a .pref filename extension. The
Symbian Preference File contains commands that control the linker and compiler. If the
syntax of these commands is not correct, the IDE will display an error in the Error and
Warnings window when it compiles a build target.
The syntax of a Symbian Preference File is the same as the syntax of a Symbian project
specification (.mmp) file. You can use C++-style comments in the Symbian Preference
File. For example, the linker and the compiler ignore text in the Symbian Preference File
that follows a double forward slash (//) up to the end of line.
The commands in the Symbian Preference File can be upper case or lower case; they are
not case sensitive. Table 4.1 lists the valid commands that you can use in the Symbian
Preference File. The table also indicates whether the command is required by the Symbian
Preference File. If a command is required, but not included in the Symbian Preference
File, the IDE will show an error in the Error and Warnings window when the build target
is compiled.
Table 4.1 Symbian Preference File Commands
Command Required / Optional
TARGET Required
TARGETTYPE Required
UID Required

Table 4.1 Symbian Preference File Commands (continued)
Command Required / Optional
BASEADDRESS Optional
EPOCALLOWDLLDATA Optional
EPOCCALLDLLENTRYPOINTS Optional
EPOCDATALINKADDRESS Optional
EPOCFIXEDPROCESS Optional
EPOCHEAPSIZE Optional
EPOCPROCESSPRIORITY Optional
EPOCSTACKSIZE Optional
EXPORTUNFROZEN Optional
LINKAS Optional
4.2.3.1 Required File Commands
TARGET
Specifies the name of the executable file that the IDE generates.
TARGET filename.ext
This command takes one string parameter, filename.ext. That parameter will be the output
filename generated by the linker. This is a required command and an error will be
generated if it is not found.
TARGETTYPE
Specifies the kind of executable file to generate.
TARGETTYPE target-type
This command takes one string parameter, target-type. That parameter will be the type of
executable the linker generates. The target types are listed in Table 4.2. This is a required
command and an error will be generated if it is not found.

Table 4.2 Target Types for the TARGETTYPE Statement
This target… Specifies this kind of executable file
ANI animation Dynamic Link Library (DLL)
APP GUI program with a

NewApplication() function exported
as ordinal 1
CTL system control
CTPKG a package
DLL static or polymorphic shared library
ECOMIIC ECom implementation collection
EPOCEXE Symbian OS program that can be launched

from the shell.
EXE executable program
EXEDLL executable program for multi-process

platforms, a DLL for single-process
platforms
FSY plug-in file system
KDLL kernel dynamic linked library
KEXT kernel extension
KLIB kernel runtime library
LDD logical device driver
LIB static library
MDA media server plug-in DLL
MDL Multipurpose Internet Mail Extension (MIME)

recognizer
NOTIFIER extended notifier DLL
OPX extension for the Organizer Programming

Language (OPL)
PDD physical device driver
PDL printer driver

Table 4.2 Target Types for the TARGETTYPE Statement (continued)
This target… Specifies this kind of executable file
RDL recognizer
VAR variable file
WLOG
UID
Specifies the unique identifiers, UID2 and, optionally, UID3, for a build target.
UID uid2 [ uid3 ]
This command takes at least one and no more than two numbers as parameters, uid2 and,
optionally, uid3. These values should be valid hex or decimal numbers and will be used to
uniquely identify the program to the operating system. This is a required command and an
error will be generated if it is not found.
4.2.3.2 Optional File Commands
BASEADDRESS
BASEADDRESS hexadecimal-address
Specifies the address to build, and if possible, load, a DLL. This command only applies to
WINSCW/WINS build targets.
When using more than one DLL, use this command to give each DLL a different base
address so that the Windows loader does not have to do any relocation while loading
Symbian OS and its DLLs. Reducing relocation considerably speeds up the initialization
of Symbian OS applications running under WINSCW/WINS.
EPOCALLOWDLLDATA
Specifies that a dynamic link library (DLL) may contain writable data.
Typically, a DLL resides in read-only memory (ROM), which implies that any data it has
must not be writable. To ensure that a DLL can be run reliably from ROM, the petran
tool issues an error if it finds a writable data section in a DLL. Use this option to tell
petran not to issue an error if a DLL has writable data.
This command takes no parameters. Its presence in the preference file tells the linker to
pass this flag to the petran tool in the link phase. This command is optional.

EPOCCALLDLLENTRYPOINTS
pass this flag to the petran tool in the final link phase. This command is optional.
EPOCFIXEDPROCESS
pass this flag to the petran tool in the final link phase. This command is optional.
EPOCDATALINKADDRESS
This command takes one number parameter. This value should be a valid hex or decimal
number and will be passed to the petran tool in the link phase. This command is optional.
EPOCSTACKSIZE
This command takes one number parameter. This value should be a valid hex or decimal
number and will be passed to the petran tool in the link phase. This command is optional.
EPOCHEAPSIZE
This command takes two number parameters. These values should be valid hex or decimal
numbers and will be passed to the petran tool in the link phase. This command is optional.
EPOCPROCESSPRIORITY
This command takes one string parameter. The valid values are low, background,
foreground, high, windsurfer, fileserver, realtimeserver, and
supervisor. The value will be passed to the petran tool in the link phase. This
command is optional.
EXPORTUNFROZEN
Specifies that unfrozen exports are to appear in the project’s import library.

When this command appears in a preference file, the IDE creates an import library as a
side-effect of linking so that all exported functions, even unfrozen ones, appear in the
import library. Import libraries for compatible ABIs are not created.
When this command is not in a preference file, you must supply a .def file with the
frozen exports.
Use of EXPORTUNFROZEN is recommended just for the early stages of development,
when the Application Programming Interface is likely to be subject to change.
LINKAS
This command takes one string parameter. That parameter is the internal name of the
output file. Use this value when calling dlltool in the link phase. This command is
optional.
4.2.4 Source Trees Preference Panel

The CodeWarrior IDE handles multiple installations of Symbian OS SDKs and
development kits with the Source Trees preference panel (Figure 4.1).
Figure 4.1 Source Trees Preference Panel
There are two scopes that source trees in the IDE encompass:
• Global source trees, specified in the IDE’s Preferences window, apply to all
projects.

• Project source trees, specified in the Target Settings window for a particular project,
apply only to files in that project.
Project source trees always take precedence over global source trees. Except for the
difference in scope, global and project source trees operate identically.
The CodeWarrior Development Studio for Symbian OS product uses global source trees,
source trees specified in the IDE’s Source Trees preference panel, to provide a defined
subdirectory into the installed Symbian development kit or SDK. The IDE applies entries
in this preferences panel to all applicable targets that are created within a project
(WINSCW, ARM, ARMI, Thumb).
The IDE uses source trees to determine where to look for the files and programs it needs to
build a project’s build target:
• build tools
• output directories
• access paths for header files and libraries
A global source tree entry will provide the absolute path to the location of the epoc32
directory of the Symbian OS development kit or SDK.
The IDE sets up source trees preferences by reading entries in the devices.xml
file. Each development kit that is installed provides the required information for the IDE
to assign a name to the installation and resolve the location of epoc32.
Use the Symbian Environment Editor to add, remove, and edit device entries in the
devices.xml file. For more information on editing devices, see the appendix
“Symbian Environment Editor”.
Each time the Symbian Environment Editor is launched, it checks for the presence of the
devices.xml file. If the devices.xml file does not exist, it asks if it should
create one. If the devices.xml file already exists, the user can immediately begin
editing device information.
4.2.5 Target Settings Panel

The Target Settings panel (Figure 4.2) is the most critical panel in the IDE. This is the
panel where you set the name of the build target, and specify which linker, pre-linker, and
post-linker plug-ins the IDE should use when building the project.
By selecting a linker, you specify the target operating system or processor. The other
settings panels available in the Target Settings window change to reflect your linker
choice.
Because the linker choice affects the visibility of other related panels, you must specify
the linkers before you can specify other build target options.

Figure 4.2 Target Settings Panel
Table 4.3 Target Settings panel—options
Option Explanation
Target Name Enter into the Target Name edit field the name of the
build target. The IDE uses this name to identify the build
target.
The IDE displays this name in the Edit menu, in the
Targets view of the project window, and in the build
target pop-up menu on the project window. For more
information, see the CodeWarrior IDE User's Guide.
Linker Choose a linker from the items listed in the Linker pop-
up menu.
If you are developing a Symbian OS application there
are different linkers to choose from based upon the
targeted device. The choices are:
Select Symbian Linker if the executable is targeted at
devices that support Symbian OS v6.1 or v7.0
Select Symbian Linker v2 if the executable is targeted at
devices that support Symbian OS v8.0
The available settings panels and options will change
based upon the chosen linker.
Pre-linker Some CodeWarrior products have pre-linkers that

perform additional work (such as data format
conversion) before linking.

Table 4.3 Target Settings panel—options (continued)
Option Explanation
Post-linker Some targets have post linkers that perform additional

work (such as a data format conversion) on the final
executable. The Symbian Installer post-linker enables
the IDE to use the information in the “Symbian
Installation Panel” and a .pkg file to create a .sis file.
Output Directory This text area displays the path to the directory where
the final linked output file is placed.
Save project entries using When enabled, this checkbox lets the IDE distinguish
relative paths between files with the same names but in different
directories. When disabled, the IDE saves project entries
by name instead of path.
If you do not have files with the same name in your
project, you can leave this option unchecked.
4.2.6 Symbian Tools Panel

The Symbian Tools settings panel (Figure 4.3) contains settings that specify the location
of the GNU build tools and the EPOC32 build tools.
Figure 4.3 Symbian Tools Settings Panel

Table 4.4 Symbian Tools Settings panel—options
Option Explanation
Gnu Tools Location Shows the path the IDE uses to locate the GNU tools.
Click the Browse button to navigate to the directory that
contains the GNU build tools for your SDK or
development kit.
Epoc32 Tools Location Shows the path the IDE uses to locate the Epoc32 tools.
Click the Browse button to navigate to the directory that
contains the Symbian build utilities for your SDK or
development kit.
4.2.7 Symbian Target Panel

The Symbian Target settings panel (Figure 4.4) contains settings that control general
settings for the target, and settings that affect the compiler and other build tools.
Figure 4.4 Symbian Target Settings Panel

Table 4.5 Symbian Target panel—options
Option Explanation
Target Architecture Select the Target Architecture on which you intend to

run your application. There are four possible
architectures from which to choose: WINSCW, ARMI,
ARM4, and THUMB. If you select the WINSCW
architecture, your application is debugged using the
Windows-hosted emulator. If you select one of the
other architectures, the IDE uses the TRK debugger to
debug your application.
Display generated commands in Check the Display generated commands in the message
the message window window option if you want to see the command line
equivalent that the IDE uses to start the compiler, linker,
and other build tools. The Errors and Warnings window
displays the command line as a message.
Suppress warning messages Check the Suppress warning messages check box if you
do not want the Errors and Warnings window to display
warning messages.
Generate symbolics Check the Generate symbolics check box if you want
your application to include symbolics information. You
must check the Generate symbolics check box to debug
your application.
Prefix File A prefix file is a source code file, typically a header file,
that is included at the beginning of each source code
file in a project's build target. To use a prefix file, type
the name of the file in the Prefix File option.
The CodeWarrior C compiler automatically includes this
file (and any files that it, in turn, includes) in every
source file in the project’s current build target. This is an
excellent way to include a precompiled header file in a
project.
TIP: This field is also used as an alternative to the -
include option commonly issued for compilers that
operate at the command line.
Additional Command Line If you want to add command line options for the
command that starts the compiler, type the options in
the Additional Command Line text box. The IDE includes
the command line options when it starts the compiler.
Import Library Location Shows the path to the import library used by this
project. Click the Browse control to locate the import
library and show its path in the text box.

4.2.8 Symbian Resources Panel

The Symbian Resources settings panel (Figure 4.5) controls how the CodeWarrior IDE
manages resource files for a C++ application.
For information on building resources, see “Building DLLs with Exports”.
Figure 4.5 Symbian Resources Settings Panel
Table 4.6 Symbian Resources panel—options
Option Explanation
Project Definition File (.mmp) Specifies the directory of the makmake project file
Location (.mmp). This option is usually set to specify the IDE
project’s directory; when importing a .mmp file, the
IDE saves its project file in the same directory as the
imported .mmp file.
Binaries Specifies the directory where you would like the

executable file to reside.
Header Files Specifies the directory of the Symbian OS header files.
Add .resource Dependencies to Adds all dependencies to user resources to the project.
Project at Compile Time This option ignores all resources from
EPOC32\include directory.

4.2.9 Symbian Installation Panel

The Symbian Installation settings panel (Figure 4.6) controls how the CodeWarrior IDE
generates a .sis file. You use the .sis file to upload a Symbian OS application to a
target device. Refer to the appendix “Creating Packages” for instructions that explain how
to create and upload a .sis file.
Figure 4.6 Symbian Installation Settings Panel
Table 4.7 Symbian Installation panel—options
Option Explanation
Output Filename Defines the name of the .sis file to create. If this field is
empty, the default is Application.sis.
Password Specifies the password of an encrypted private key file

used to digitally sign the .sis file.
Create stub format file Generates a residual .sis file for each language
defined in the package file. The extension is .sxx,
where xx is the number of the language. For example,
.s10.

Building DLLs with Exports
Table 4.7 Symbian Installation panel—options (continued)
Option Explanation
Content Search Location Specifies where the IDE looks for files it uses to create
the .sis file.
NOTE: All files required by an application must be in this
directory in order for the Symbian Installer post-linker
to create a valid .sis file. This means that some files,
may have to be manually moved to this directory from
where they are created. For example, .rss files are
normally created in a directory separate from the .app
file.
For post-linker information, see “Post-linker”.
Output Location Specifies the directory where the IDE creates the.sis
file.
4.3 Building DLLs with Exports

DLLs (Dynamic Link Libraries) in the Symbian OS typically require a .def file to list
the items that the DLL exports. When creating a new DLL, the APIs typically change
frequently while under development, and changing the .def file every time you want to
build is cumbersome. The linker adapter in the IDE usually requires a .def file to be
present in the target before building and will report an error message if one is not found.
Although the interface is still being developed, you can specify EXPORTUNFROZEN in
the .pref file to let the linker know to export only whatever functions are exported in
the source code using the EXPORT_C macro. Once the APIs are frozen, the
EXPORTUNFROZEN keyword should be removed from the .pref file and the frozen
.def file should be added to the target.
There is currently no way to generate a frozen .def file from the IDE automatically.
The easiest way to create a frozen .def is from the command line using the abld
freeze command. The generated .def file can then be added to the build target.
Alternatively, you can create the .def file by hand by creating a new text file with
EXPORTS on the first line and then adding the exported symbols and ordinals underneath.
For example:
EXPORTS
MyFunction__Fv @ 1 NONAME
The IDE recognizes the .def file extension as the only valid one for exporting DLL
items, all other file extension variations are ignored. Also, if more than one .def file
appears in the Link Order view of the project window, the IDE only uses the first .def
file listed.

Assembler Overview
4.4 Assembler Overview

This manual does not document the assembly syntax or instruction sets of ARM® or Intel
x86 processors. For information on these topics, consult their respective documentation.
4.4.1 ARM Assembly Language Programming

To program in assembly language for Symbian OS platforms that use ARM® processors,
put the assembly language source code in files that end with “.s”. The assembly source
code must use GCC’s syntax for ARM assembly language.
4.4.2 Intel x86 Assembly Language Programming

To program in assembly language for the Symbian OS emulator, which runs on Microsoft
Windows operating systems, use the CodeWarrior C/C++ compiler’s inline assembler for
Intel x86 processors.

Assembler Overview

5 Emulation Debugging
Symbian SDKs and Development Kits include an emulator that runs Symbian OS on a
Microsoft Windows host computer. The emulator provides the full range of Symbian OS
functionality, letting you do most development tasks on a single desktop computer. The
emulator and the software you build for it with CodeWarrior Development Studio for
Symbian OS software run natively on the Intel x86 family of processors.
In many cases, you can build and debug a complete application using the emulator, then
test the application on the actual device. There are cases however, where you cannot use
the emulator, such as when developing device drivers that access hardware on a device.
For more information about the emulator, please see the documentation that came with
your development kit or SDK under: Developer Library>Tools and Utilities>Emulator.
You will find an emulator to use with the CodeWarrior Development Studio for Symbian
OS product in:
SymbianDir\epoc32\RELEASE\winscw\udeb\epoc.exe
where SymbianDir is the path containing the subdirectories and version number of the
Symbian OS development kit or SDK.
The rest of this chapter describes how to configure projects and debug software that runs
on the Symbian OS emulator:
• “Target Settings”
• “Debugging an Application”
• “Debugging an Executable File”
• “Debugging a DLL”
• “Viewing Processes”
• “Viewing Symbian OS Descriptors”
• “Variable Scoping of Expressions”
5.1 Target Settings

CodeWarrior Development Studio for Symbian OS software uses the CodeWarrior IDE’s
debugger for Intel x86/Windows to debug Symbian OS software that runs on the emulator.

Emulation Debugging
Target Settings
Consequently, configuring the IDE to debug such software is similar to setting it up for
debugging Windows-hosted software.
This chapter describes the settings that are specific to Symbian OS debugging on the
emulator. To see and change the settings in these panels, from the IDE’s Edit menu,
choose Target Settings, where Target is the name of the active build target in the project
window.
• “Runtime Settings Panel”
• “Debugger Settings Panel”
5.1.1 Runtime Settings Panel

The Runtime Settings panel specifies a debugging application for non-executable files.
Dynamic linked libraries (DLLs), shared libraries, and code resources are sample non-
executable files.
Figure 5.1 Runtime Settings Panel Example
Table 5.1 Runtime Settings panel—options
Option Explanation
Host Application for Libraries & To debug a program that is called by another program,
Code Resources type the name of the calling program here. For example,
to debug a DLL called by an application, you must
specify the application that loads the DLL.

Emulation Debugging
Target Settings
Table 5.1 Runtime Settings panel—options (continued)
Option Explanation
Working Directory Specifies the directory to use for debugging the non-
executable files. Leave this field blank to use the same
directory that contains the non-executable files. See the
CodeWarrior IDE User's Guide for more information.
Program Arguments This field lets you specify command line arguments to
the application or executable that you are debugging.
NOTE: If you are debugging from an application or

executable project, the contents of the Program
Arguments option are passed to that program.
If you are debugging a DLL project, these
arguments are passed to the program specified
in the Host Application for Libraries & Code
Resources option.
5.1.2 Debugger Settings Panel

The Debugger Settings panel configures activity logs, data-update intervals, and other
debugger-related options.
Figure 5.2 Debugger Settings Panel Example

Emulation Debugging
Debugging an Application
Table 5.2 Debugger Settings panel—options
Option Explanation
Stop on application launch When this option is on, the debugger will set a
breakpoint at the function specified in the User
Specified option. Note that the Program entry point and
Default language entry point options are not supported
when debugging Symbian OS software running on the
emulator.
Library Targeting Controls how the CodeWarrior Debugger handles the

loading of libraries during a debug session. For
debuggers that support smart-targeting, like the x86
Debugger, the following choices are available:
• None–No libraries are loaded during a debug
session.
• Smart-Targeting–Libraries are loaded as
needed when the debugger thread is halted
during a debug session. Smart-Targeting is
disabled for debuggers that do not support
this feature.
• Auto-Targeting–All libraries required during
the debug session are loaded. This can result
in slower debugger performance for
processes that load lots of modules (ex.
Symbian’s epoc.exe).
NOTE: Breakpoints set in a source file but not mapped
to an open symbolics (executable) file will not work
until the correct symbolics file is opened.
Update data every n seconds Check this box to have the debugger update displayed
debugging information at regular intervals during a
debug session. Enter in the text field the number of
seconds to wait before the debugger updates the data
displayed in debugger windows.
Uncheck this box to have the debugger update
displayed debugging information only when you issue
debug commands such as Run, Stop, Step Over, Step
Into.
Cache symbolics between runs When checked, the debugger will cache symbolic
information between debug sessions as long as the
executable being debugged has not changed. This
option is turned on by default.
5.2 Debugging an Application

Once you have a debug (UDEB) target of an application project built and are ready to
debug it, you first need to ensure that the build target’s settings are correctly configured.

Emulation Debugging
Debugging an Executable File
Files and directories placed in this folder on the host computer appear in the Symbian OS
file system that runs on the emulator:
SymbianDir\epoc32\RELEASE\winscw\udeb\Z\
where SymbianDir is the directory of your Symbian OS development software.
All applications with resources that you build for emulator development should be placed
in
SymbianDir\epoc32\RELEASE\winscw\udeb\Z\System\Apps\Name
where SymbianDir is the directory of your Symbian OS development software and Name
is the name of your application.
To specify the location for the application to be stored, type or browse to the location in
the Output Directory option in the Target Settings panel.
If you imported your project from a makmake project file (“.mmp”), the build target’s
settings will already be configured correctly. Also, resources files and bitmaps built with
the application will be placed in the folders where the emulator expects to find them.
If your application requires additional files, add them to the same directory as your build
target’s output directory.
Specify the path and name of the emulator on your host computer that will use the
application in the Host Application for Libraries & Code Resources option in the
Runtime Settings settings panel. If you imported the project from a .mmp file, the IDE
will set this option for you.
Set a breakpoint or breakpoints in your source code and from the IDE’s Project menu,
choose Debug. After launching the emulator, you will see a debugger thread window with
the name of your emulator. Navigate through the emulator’s file system to the directory
where the application was stored by the IDE and launch the application to start debugging
it.
NOTE How an application is launched varies between emulators. See the Symbian
documentation that came with your SDK or development kit for more
information.
5.3 Debugging an Executable File

Once you have a debug (UDEB) target of an executable file (“.exe” file) built and are
ready to debug it, you first need to ensure that the build target’s settings are properly
configured. If you imported the project from a makmake project file (“.mmp” file), the
IDE configured your build target’s settings to create your executable file in
SymbianDir\epoc32\RELEASE\winscw\udeb\
where SymbianDir is the directory of your Symbian OS development software on the host
computer.

Emulation Debugging
Debugging a DLL
A temporary breakpoint is set at E32Main() by default in the Debugger Settings

settings panel.
If you want to create your executable file in a different directory, specify this directory in
the Target Settings settings panel. Make sure to put your executable file in a subdirectory
of
SymbianDir\epoc32\RELEASE\winscw\udeb\
where SymbianDir is the directory of your Symbian OS development software.
Choose Debug from the IDE's Project menu. A thread window will appear with the name
of your executable file. The debugger will stop at the temporary breakpoint at
E32Main().
5.4 Debugging a DLL

Once you have a debug (UDEB) target for a DLL file built and are ready to debug it, you
first need to ensure that the build target’s settings are properly set up. Specify the location
for the DLL to be created in the Output Directory in the Target Settings panel. If the
directories do not already exist on your host computer, the IDE will create them for you. If
your DLL will be dynamically loaded, it must reside in
SymbianDir\epoc32\RELEASE\winscw\udeb\Z\
on the host computer, where SymbianDir is the Symbian OS software folder.
If an executable or application statically links to it, it must reside in the same directory as
the executable or application.
Specify the path and name of the emulator on your PC that will use the DLL in the Host
Application for Libraries & Code Resources option in the Runtime Settings settings
panel. If you imported the project from a .mmp file, the IDE has already set this option
for you.
Set one or more breakpoints in your DLL’s source code. Create an executable project, that
uses your DLL, as described in “Debugging an Executable File”, then select Debug from
the IDE’s Project menu.
After the emulator launches, you will see a thread window with the name of the emulator,
stopped at the executable file’s E2Main() function. Continue running the executable file
to stop at the DLL breakpoints.
5.5 Viewing Processes

To see a list of all the processes running in the emulator, select Processes from the IDE’s
View menu. Select Local Windows PC in the upper left hand corner. The window will
update with a list of all the processes currently running on the host computer’s operating
system, including their names and process IDs. Select EPOC and you will see a list of the
threads belonging to the emulator process.

Emulation Debugging
Viewing Symbian OS Descriptors
NOTE Because of the way the emulator was written to emulate Symbian OS running
on the Microsoft Windows operating system, the threads belonging to the
EPOC process actually represent processes running inside of Symbian OS.
5.6 Viewing Symbian OS Descriptors

Descriptors are both fundamental to Symbian OS, and an excellent example of the
difference of approach between non-object-oriented and object-oriented designs. They are
a Symbian OS equivalent for character strings. There are several types of descriptors and
they all have TdesC as their superclass. Every descriptor stores and manages data
differently, which makes it difficult for the programmer to know the meaning of a
descriptor’s contents. The CodeWarrior IDE’s debugger has the ability to automatically
identify Descriptors and display their value in a programmer-friendly C-string like format.
Figure 5.3 shows an example of TdesC descriptor display in IDE debugger. In this
example, KTxtOK is a descriptor and has “ok” for its value.
Figure 5.3 Example of Viewing Descriptors
5.7 Variable Scoping of Expressions

The debugger now supports an enhanced method of variable scoping, enabling you to tie
an expression’s value to a specific variables scoping environment. Normally an

Emulation Debugging
Variable Scoping of Expressions
expression’s value is scoped in reference to the PC. This may be impractical, especially
when you want to compare two identically named variables that exist in two different
functional scopes.
The debugger now supports the following enhancements to variable scoping, which
includes:
• Setting a breakpoint condition on a specified variable scope. This enables you to
specify a line within a particular variables scope if you want that particular variable’s
condition met. For example, the breakpoint condition “{@85}myVariable==5”
is scoped to the variable “myVariable” within the range of line 85.
• Tie variables with multiple scopes to a line number within the scope where the
variable resides. For example, you can bind an expression to a scope such as
"{@5}someVar" or "{@5}someVar + {@15}someVar".
5.7.1 Expression Scoping Syntax

The syntax of the “context operator” for expressions is:
{@<linenumber>} <variable>
• The @ symbol refers to a line in the source code file where <variable> is defined.
The scope of that line number is used when looking up “local_variable”.
• You can use this operator wherever expressions are used by the IDE including the
Expressions, Conditions on Breakpoints, Eventpoints, and Watchpoint windows, and
as the origin for the Memory Window.
Some examples include:
• {@147} varA - ties varA evaluation to the block scope containing line 147 of the
current file.
• (char *) {@192} varB + varC - ties varB evaluation to line 192. The
scope used for varC is the current PC. varB is cast to a character pointer before
adding the value of varC.
• (int) ( {@147} varA + {@192} varB ) - ties varA to line 147 and
varB to line 192. The result is cast to an "int" type. In the expression window this
displays the result as an integer type.
• {@147} varA == 0x55 - for use in the condition of a breakpoint, this conditions
the breakpoint so varA (in the block with line 147) must be equal to 0x55 before
the breakpoint is taken.
5.7.2 Limitations of Variable Scoping

The following limitations apply:
• Invalid expression forms include:

Emulation Debugging
– The context operator must appear just before an identifier referring to a variable.
If casting is specified, it can be included before the operator (e.g., (int*)
{@147} varA).
– Lines within a block scope “{}” that do not contain code are considered invalid.
– If a variable cannot be found within the block scope, it is searched for in the
function scope, the file scope, and then in global scope. If not found at all, the
expression is considered invalid.
• There is no file, module, thread, nor target tied to this context. Thus, if another
variable with the same name exists in another file, that expression will be evaluated
also.
• An expression of the form, “{context} varA + varB”, will apply the context
only to varA. The scope of varB will be taken to be the current PC.
• Without this operator, expressions are evaluated as they currently are. That is, the
scope of all identifiers is taken to be the current PC.
• If this operator is used for a non-local variable, it is ignored.
• Line numbers will not automatically adjust when the file is edited.
• The expressions are persistent across debug sessions.
• Only the x86 tools are supported. Other tools may or may not provide the block
scoping debug information necessary for this to work.

Emulation Debugging

6 Resource Editor and
Resources
This chapter describes the graphical Resource Editor used to edit the resource
(.resource) files associated with a project and the types of resources associated with
Symbian OS projecs. Topics include:
• “Using the Resource Editor”
• “Resource Editor Window”
• “Building Resources”
6.1 Using the Resource Editor

The resource files handled by the Resource Editor include:
• RSS files
• Bitmap files and attributes
• AIF files and attributes
NOTE The resource (.resource) files are stored in a well defined XML format that
can be edited with any text editor.
Opening the Resource Editor

To open the Resource Editor:
1. Select Edit > Symbian Resources > Edit Resources for Target <TargetName> from
the CodeWarrior menu bar
2. If more than one .resource file is attached to the target, the Project Resources
window (Figure 6.1) appears:
a. Select a resource file in the Resource File list

Resource Editor and Resources
Resource Editor Window
b. Click OK
The Resource Editor window (Figure 6.2) appears.
Figure 6.1 Project Resources window
6.2 Resource Editor Window

The Resource Editor window provides the ability to manage and edit a project’s resource
(.rss) files. The window contains these pages:
• “Resources Page”
• “Bitmaps Page”
• “AIFs Page”
6.2.1 Resources Page

Use the Resources page to manage the resource files associated with a project. Use it to
add or remove resource files from the project, or change the properties of the selected
resource file. The Resources page provides GUI level validation to ensure that any updates
to the .resources file are valid.

Figure 6.2 Resources page of Resource Editor window
Table 6.1 Resources page in Resource Editor window—options
Option Explanation
Resources The Resources list shows all of the resource (.rss) files
associated with the target. If more than one resource file
appears in the list, select it to specify its Resource File Settings
options. If no resource file is selected or the list is empty, the
Resource File Settings options are disabled.
Click the Add control to locate and add a resource file to the
target. Resource files must be specified as relative to the .mmp
file location. If not, move the resource file to a suitable relative
location before attempting to add it to the project. Once a new
resource file is added to the Resources list, it becomes the
selected file and its Resource File Settings ready for
modification.
Click the Remove control to delete the selected resource file
from the target.
Source Path Shows the name of the currently selected file in the Resources
list.
Target Path Shows the path to the target destination for the resource file.
Languages Click to select the language used by the selected resource file.

Table 6.1 Resources page in Resource Editor window—options (continued)
Option Explanation
UIDs Enter a second or third unique ID (UID) value associated with

the selected resource file into the appropriate text box.
Generate Header Enable to set the Header attribute true in the .resources file. If
unchecked, the Header attribute is set to false.
6.2.2 Bitmaps Page

Use the Bitmaps page to configure the generation of Symbian .mbm files from one or
more .bmp files. The Bitmaps page provides GUI level validation to ensure that any
updates to the .resources file are valid.
Figure 6.3 Bitmap page of Resource Editor window

Table 6.2 Bitmap page in Resource Editor window—options
Option Explanation
MBM Output Files The MBM Output Files list shows all of the MBM files associated
with the target. Select a file name in this list to edit the file
attributes or remove the file.
Click the Add control to add a MBM file to the MBM Output Files
list.
Click the Remove control to delete the currently selected MBM
file from the MBM Output Files list.
Generate Header Enable to set the Header attribute true in the .mbm file. If
unchecked, the Header attribute is set to false.
Output Path Shows the path to the target destination for the MBM file.
Target Path Shows the path to the currently selected file in the AIF Files list.
Bitmap Files Shows the bitmap files associated with the currently selected
MBM Output file. Select a file name in this list to edit the file
attributes or remove the file.
Click the Add control to add a bitmap file to the Bitmap Files
list.
Click the Remove control to delete the currently selected
bitmap file from the Bitmap file list.
BPP Use the BPP (Bits Per Pixel) option list to select the the number
of bits assigned to the selected bitmap image. Range is from 1-
bit (black-and-white) to 24-bit color.
Source Path Shows the name of the currently selected file in the Bitmap
Files list.
6.2.3 AIFs Page

Use the AIF page to configure the generation of Symbian .aif files from one or more .bmp
files.

Figure 6.4 AIFs page of Resource Editor window
Table 6.3 AIF page in Resource Editor window—options
Option Explanation
AIF Files The AIF Files lists shows all the AIF files associated with the
current target. You select a file in the AIF Files list to modify its
attributes. If no file is selected, all of the attribute options are
disabled.
Click the Add control to add a new AIF file to the AIF Files list.
The AIF Output File dialog appears.
Figure 6.5 AIFs Output File dialog
Click the Remove control to delete the selected AIF file from
the AIF Files list.
Source File Shows the name of the currently selected file in the AIF Files
list.
Source Path Shows the path to the currently selected file in the AIF Files list.

Building Resources
Table 6.3 AIF page in Resource Editor window—options (continued)
Option Explanation
Target Path Shows the path to the target destination for the AIF file.
Bitmap Files Shows the bitmap files associated with the currently selected
AIF file. Select a file name in this list to edit the file attributes
or remove the file.
Click the Add control to add a bitmap file to the Bitmap Files
list.
Click the Remove control to delete the currently selected
bitmap file from the Bitmap file list.
BPP Use the BPP (Bits Per Pixel) option list to select the the number
of bits assigned to the selected bitmap image. Range is from 1-
bit (black-and-white) to 24-bit color.
Source Path Shows the name of the currently selected file in the Bitmap
Files list.
Setting Resource Editor Options

To set an option in the Resource Editor:
1. Open the Resource Editor as instructed in “Opening the Resource Editor”
2. Click to select the page (Resources, Bitmap, AIF) to modify
3. Set Resource Editor option(s)
4. Click OK
The Resource Manager begins to update the .resource file in the background using
the settings of the Resource Editor window pages.
NOTE Because the Resource Manager is not part of the IDE, the IDE is left unaware
that a .resource file has been updated by this process. To avoid this issue,
enable the Use Modification Date Caching option to force the IDE to check
the file for modification prior to a build oepration.
6.3 Building Resources

Resource files contain XML data that the CodeWarrior IDE translates into resources for
Symbian OS software:
• “Resource Files”
• “Kinds of Resources”

Building Resources
• “Tags for Resources”

• “Tags for Bitmaps and AIFs”
6.3.1 Resource Files

The IDE uses files that end with “.resources” to generate resources and header
files for your project. The .resources files are XML files that specify the names of
“.rss” files, bitmap files, and AIF files. The IDE uses the information in the .resources
files and options in the Symbian Resources settings panel to generate binary and header
files for the build target.
For information on specifying the location of resource source, binary, and header files see
“Symbian Resources Panel”.
The IDE creates a .resources file when it imports a .mmp file that refers to files
containing resources. The IDE does not create a .resources file when importing a
.mmp file that does not refer to resource files. See “Importing a Project from a makmake
Project File” to learn how to convert a .mmp file into a project for the CodeWarrior IDE.
A .resources file delimits its information with a <resources> tag. Information
enclosed by a <resources> tag specifies the names of files containing resources, their
directory paths, whether or not to generate header files for them, and other information.
Listing 6.1 shows an example of a .resources file.
Listing 6.1 Example of a .resources file
<resources>
<mbm
targetfile = "EXAMPLE.MBM"
targetpath = "Z\SYSTEM\APPS\EXAMPLE"
header = "true">
<bmp
bpp = "c8"
sourcepath = "..\EDATA"
sourcefile = "example1.bmp"/>
<bmp
bpp = "c8"
sourcefile = "example2.bmp"/>
</mbm>
<aif
sourcefile = "EXAMPLE.RSS"
targetfile = "EXAMPLE.AIF"
targetpath = "Z\SYSTEM\APPS\EXAMPLE">
<bmp
bpp = "c8"
sourcepath="..\EDATA"
sourcefile = "EXAMPLE24.BMP"/>

Building Resources
<bmp
bpp = "c8"
sourcepath="..\EDATA"
sourcefile = "EXAMPLE2M.BMP"/>
</aif>
<rsc
sourcefile = "EXAMPLE.RSS"
targetpath = "Z\SYSTEM\APPS\EXAMPLE"
header = "true"
sourcepath = ".">
<language id = "SC"/>
</rsc>
</resources>
6.3.2 Kinds of Resources

Table 6.4 lists the kinds of resources that can be listed in .resources file and their
associated XML tags.
Table 6.4 Resources Listed in a .resources File
Use this tag in a .resources file… to describe information about this

kind of resource
<rsc> resources in a .rss file
<mbm> bitmap images
<aif> AIF images
Table 6.5 lists the attributes that each of the tags listed in Table 6.4 may have.
Table 6.5 Attributes for Resource Tags in a .resources File
Use this attribute in a .resources file… to do this
sourcefile="filename" Replace filename with the name of the file

that contains the source code or binary data
for the resource.

Building Resources
Table 6.5 Attributes for Resource Tags in a .resources File (continued)
Use this attribute in a .resources file… to do this
sourcepath="directory" Replace directory with the name of the

directory of the resource file.
header="trueorfalse" Replace true or false with true if

you want the IDE to generate a matching
header file for the resource data. Replace
trueorfalse with false if you do not want a
matching header file.
The IDE places the header file in the
directory specified by the Header Files
option of the Symbian Resource settings
panel.
6.3.3 Tags for Resources

Table 6.6 lists the tags that may be enclosed by a <rsc> tag to specify options for
resources in .rss files.
Table 6.6 Tags for Resources
This tag… does this
<language id= "idvalue"> Replace idvalue with a language

identification code. The IDE will generate
resources for this language. More than one
of these tags may be enclosed in a <rsc>
tag.
6.3.4 Tags for Bitmaps and AIFs

Use a <bmp> tag within a <mbm> or <aif> tag to specify the names of bitmap files and
their number of bits per pixel. Listing 6.2 shows the format of the <bmp> tag.
Listing 6.2 Format of the <bmp> tag
<bmp sourcefile = "filename" bpp = "depth"/>
Replace filename with the bitmap or AIF file. Replace depth with the bits per pixel and
color depth of the image.

7 Creating Packages
This chapter provides information on using the CodeWarrior™ IDE to create .pkg and .sis
files, and in turn upload the .sis file to a target device.
There is a certain dance one must perform to upload an application to a Symbian OS
device. The major steps in this dance include:
• “Step 1: Creating .pkg Files”
Once you have your project running as desired in the emulator, you need to create a
package file (.pkg) to identify all the project components required.
• “Step 2: Creating .sis Files”
Use the Symbian Installation panel and the .pkg for the application with the
CodeWarrior IDE or the command-line tool makesis to create a .sis file.
• “Step 3: Uploading .sis Files”
Use the Symbian Connect tool to upload the .sis file to the device, installing the
application.
For additonal information, see the Symbian Developer Library, available for downloading
from www.symbian.com.
7.1 Step 1: Creating .pkg Files

The IDE editor can create text files and save them as .pkg files or use .pkg files already
created. This section describes .pkg files, how to use or create them, and how to configure
the IDE to recognize and use them to create .sis files.
See the Symbian Developer Library section “Developer Library » Tools and Utilities »
Installation guide » How to create a simple installation file” for additional information on
creating .pkg files.
7.1.1 .pkg Files Overview

A .pkg file is simply a text file with the information the Installation File Generator
makesis requires to create a .sis file. You can use the CodeWarrior IDE or any text editor
to create a .pkg file. Once a .pkg file is available, you can add it to a project, and the IDE

Creating Packages
Step 1: Creating .pkg Files
will use it and the information entered in the “Symbian Installation Panel” to create a .sis
file.
NOTE Many of the .mmp files you import from a SDK may already have a .pkg file
associated with it. Always check before creating your own .pkg file.
A minimal .pkg file consists of the following lines:

• header–provides the following information on a single line:
– application name–name of the application displayed on the target device
– UID–(0x10004299) unique application ID value
– major and minor version numbers–values that represent the application’s major
and minor version numbers
– current build number–value that represents the current .sis build number
• filenames and install location–the name of the file to include in the .sis file and its
install location within the target device. Each line describes a single file.
• comments–.pkg file comment lines are preceeded by a semi-colon
A sample .pkg file might look like this:
#{"HelloWorld"},(0x10004299),1,0,0
; Only two files to install for the minimal application
"HelloWorld.app"-"!:\system\apps\HelloWorld\HelloWorld.app"
"HelloWorld.rsc"-"!:\system\apps\HelloWorld\HelloWorld.rsc"
7.1.2 .pkg File Mapping

Once you have a .pkg file, you need to validate that the IDE can recognize the .pkg
extension and uses the correct compiler to process it during a build.
Validating the File Mapping

For the CodeWarrior IDE to recognize a specific file extension and know what to do with
that file type, the extension must be present in the File Mappings panel for the build target.
The following steps describe how to ensure that the IDE can recognize and correctly use a
.pkg file.
1. Open the TargetName Setting panel for the build target
The TargetName Setting window appears.
2. Select the File Mappings panel
The File Mappings panel appears (Figure 7.1).

Creating Packages
Step 1: Creating .pkg Files
Figure 7.1 The File Mapping panel in the TargetName Settings window
3. Verify the Mapping Info for the .pkg Extension type

The default settings for the .pkg File Mapping is:
Table 7.1 .pkg default settings
Mapping Info Default Setting
File Type TEXT
Flags Ignored by Make
Edit Language None
Extension .pkg
Compiler None
4. Click OK
The IDE saves the settings and closes the TargetName Settings window.
NOTE If the .pkg extension is not present in the File Mappings settings panel, use the
Add button to create a new entry with the above settings in the File Mappings
list. See the CodeWarrior IDE User’s Guide for additional details.

Creating Packages
Step 2: Creating .sis Files
7.1.3 Project Files and .pkg

With a valid .pkg file and the IDE able to recognize it, it’s time to add the application’s
.pkg file to the project file. This is where the Symbian Installer post-linker expects to find
the file when it comes time to create the .sis file.
Adding .pkg Files to a Project File

You add a .pkg file to a project file using the same methods required to add a source file.
To add a .pkg file from an editor window:
• Select the Project > Add FileName to Project menu item
The filename for the associated editor window is added to the project file.
To add a .pkg file from a directory:
1. Select the Project > Add Files menu item
The Select files to add window appears.
2. Locate and select the .pkg file using the Select files to add window
3. Click Open
The selected .pkg file is added to the project file.
7.2 Step 2: Creating .sis Files

The IDE can create .sis files for applications when provided specific information and the
correct option settings. This section describes the information and settings required by the
IDE.
7.2.1 .sis File Components

A .sis file consists of all the components an application requires and some header
information, merged into a single file for uploading to a Symbian OS target device. The
CodeWarrior IDE can automatically create an application’s .sis file using the proper
information and settings.
Before it can create a .sis file, the IDE needs some information. The information and
settings it needs are:
• .pkg file–provides header and other information to the post-linker that enables it to
create a valid .sis file. See “.pkg Files Overview” for details.
• File Mapping setting–tells the IDE how to handle the .pkg file once it is added to the
project. See “.pkg File Mapping” for details.
• Post-linker setting–when the Symbian Installer post-linker is set, the IDE uses the
information provided by the Symbian Installation settings panel to create a .sis file

Creating Packages
that can be uploaded to a target device. See “Symbian Installer Post-Linker” for
details.
• Symbian Installation settings panel–provides the post-linker with basic .sis file
information like filename, files to include, and more. See “Symbian Installation
Panel” for details.
For more information on .sis files, see the Symbian Developer Library documentation.
7.2.2 Symbian Installer Post-Linker

The key component the IDE uses to create the .sis file is the Symbian Installer post-linker.
Once the CodeWarrior IDE builds the application, it uses the post-linker to create the .sis
file. The post-linker uses the information in the .pkg file and the Symbian Installation
settings panel to construct the .sis file.
Setting a Post-Linker
For the IDE to create a .sis file, the Symbian Installer post-linker must be activated for the
build target represented by TargetName.
2. Select the Target Settings panel
The Target Setting panel appears (Figure 7.2).
Figure 7.2 The Target Settings panel in the TargetName Settings window

Creating Packages
3. Select Post-Linker > Symbian Installer

Symbian Installer appears in the Post-linker setting.
4. Click Apply
The IDE saves the panel changes.
7.2.3 .sis File Settings

The Symbian Installation settings panel provides the information used in conjunction with
the .pkg file by the Symbian Installer post-linker to create a .sis file.
Setting .sis File Information

To create a .sis file for a particular build target:
2. Select the Symbian Installations panel
The Symbian Installations panel appears (Figure 7.3).
Figure 7.3 The Symbian Installation panel in the TargetName Settings window
3. Fill in the following fields (minimum required):

• Output Filename–name of .sis file to create

Creating Packages
Step 3: Uploading .sis Files
• Content Search Location–source directory the post-linker looks at for the files it
adds to the .sis file
NOTE During the development process, some files (like resource files) are placed in a
different directory, which may or may not be the directory pointed to by the
Symbian Installation panel’s Content Search Location field. In those
situations, you must copy those files to the directory indicated in the Content
Search Location field in order for the post-linker to find them and create the
.sis file.
• Output Location–destination directory where .sis is created
NOTE See the “Symbian Installation Panel” for more information on the other options
available in this panel. See the Symbian Developer Library for details on the
various .sis file options.
4. Click Apply
The IDE saves your changes to the build target.
5. Build the application and the .sis file
Select the Project > Make menu item, or press F7, to build the target. When the post-
linker runs, the .sis file is also generated.
You can now use the .sis file to deploy your program to a target device. Refer to the
documentation of your devkit or SDK for instructions that explain how to do this.
7.3 Step 3: Uploading .sis Files

The final step, once you have a valid .sis file, is to upload it to the target device. The
method chosen depends upon the Symbian device you have. Every Symbian SDK ships
with software that provides support for “Symbian Connect” functionality.
The actual name for the software is SDK-dependent, so refer to your SDK’s
documentation for the name. We will refer to it generically as Symbian Connect.
Essentially, the Symbian Connect program provides a method of connecting a PC to the
target device via USB, IrDA, Bluetooth, or other serial connection. Once you make a
connection, you can upload your .sis file to the target device and install the program.
NOTE A simple outline is provided to show the basic steps necessary to upload a .sis
file to a target device. The actual steps required by the specific Symbian
Connect program that ships with the SDK you are using may differ, so always
refer to that SDK’s documentation for details.
To upload a .sis file to a particular device:

Creating Packages
Step 3: Uploading .sis Files
1. Launch the SDK’s Symbian Connect program

2. Select the method of connection
In this step you select the form of the serial connection to use, USB, Irda, Bluetooth,
etc.
3. Select the .sis file to upload
4. Upload the .sis file
5. Install the program on the target device
To make the program available on the target device, you must install the program
stored in the .sis file. This is normally done by selecting Install from the device menu,
selecting the program name, then clicking Install.
Congratulations, you’ve now successfully created a .sis file and uploaded it to your
target device.

8 Symbian Environment Editor
The Symbian Environment Editor enables you to add or remove devices from the
devices.xml file. The CodeWarrior IDE uses the devices.xml file to determine
which development kits are installed, and provides information the IDE uses to resolve the
location of a specific SDK’s root directory.
The Symbian Environment Editor uses the following windows to add and delete devices:
• “Symbian Environments Window”
• “Symbian Environment Editor Window”
For descriptions of how to add, delete, or edit devices, see:
• “Adding Devices to devices.xml”
• “Removing Devices from devices.xml”
• “Editing Environments in devices.xml”
The IDE automatically checks the devices.xml file when the Symbian Environment
Editor is launched from within the IDE. If the devices.xml file or its registry entry is
not listed, the IDE creates a new one with the user’s permission. While possible to edit the
devices.xml file using any text editor, using the Symbian Environment Editor helps
avoid errors in organization and formatting.
By default, the devices.xml file is stored in the C:\Program Files\Common
Files\Symbian\ directory.
NOTE You must have the appropriate Symbian OS development kit or SDK in order
to employ the Symbian Environment Editor. Doing so installs the tools
required in the \Common Files\Symbian\Tools directory.
8.1 Symbian Environments Window

Use the Symbian Environments window (Figure 8.1) to manage devices recognized by
the IDE by adding, editing, and deleting device entries in the devices.xml file.

Symbian Environment Editor
Symbian Environment Editor Window
Figure 8.1 Symbian Environments window shows all currently known Symbian devices
The Symbian Environments window components are described in Table 8.1.
Table 8.1 Symbian Environments window—options
Option Explanation
OK Saves any changes and closes the Symbian

Environments window.
Cancel Closes the Symbian Environments window without

saving.
New Click to add a new device.
Edit Click to edit the device currently selected.
Delete Click to delete the device currently selected.
8.2 Symbian Environment Editor Window

Use the Symbian Environment Editor window (Figure 8.2) to edit a single device entry
in the devices.xml file. Listing 8.1 lists an example entry in the devices.xml
file.

Listing 8.1 Example entry in the devices.xml file
<devices version="1.0">
<device
id="Series60_v21_CW"
name="com.nokia.series60"
default="no" userdeletable="yes">
<epocroot>C:\Symbian\Series60_v21_CW\</epocroot>
</device>
...
</devices>
Figure 8.2 Symbian Environment Editor window
The Symbian Environment Editor window components are described in Table 8.2.
Table 8.2 Symbian Environment Editor window—options
Option Explanation
ID The device’s ID attribute.
Name The device’s name attribute. The name should

always start with “com”, as in
“com.<vendor>.<sdk>”.
EPOC Root Type the path or click Choose to specify the root of
the SDK used for this device.
Make Device Default Marks this device as the default device. All other
devices are set to ‘no’ if OK is clicked. The default
setting is ‘no.’

Table 8.2 Symbian Environment Editor window—options
Option Explanation
OK Saves any changes and closes the Symbian

Environment Editor window.
Cancel Closes the Symbian Environment Editor window

without saving.
Adding Devices to devices.xml

To add a new device environment that the IDE will recognize and use, add the device
information to the devices.xml file as shown in the steps below.
1. Open the Symbian Environments window
Select the Edit > Symbian Environments menu item. The Symbian Environments
window appears.
2. Click New
The Symbian Environment Editor window appears.
3. Enter the new device attributes
Refer to Table 8.2 for more information on device attributes.
4. Click OK
The editor saves the new device information and closes the Symbian Environment
Editor window.
5. Click OK
The editor saves the devices.xml file and closes the Symbian Environments
window.
Removing Devices from devices.xml

To remove a device environment from the devices.xml file, follow these steps:
window appears.
2. Select the device to remove in the device list
The chosen device is highlighted.

3. Click Delete
The chosen device is removed from the device list.
4. Click OK
window.
Editing Environments in devices.xml

To edit a device environment in the devices.xml file, follow these steps:
window appears.
2. Click Edit
The Symbian Environment Editor window appears.
3. Modify the device attributes
Refer to Table 8.2 for more information on device attributes.
4. Click OK
The editor saves the updated device information and closes the Symbian
Environment Editor window.
5. Click OK
window.


9 Device Debugging
The CodeWarrior Development Studio for Symbian OS software lets you debug your
application on a device as well as under the emulator as described in “Emulation
Debugging”. The appearance and functionality of the debugger is similar in both cases.
This chapter contains these sections:
• “Using Target Resident Kernel”
• “Debugging an Application”
• “Debugging an Executable File”
• “Debugging a DLL”
• “Debugging via a USB Connection”
• “Viewing Processes”
• “Troubleshooting”
NOTE TRK must be enabled on the target device to activate device debugging.
9.1 Using Target Resident Kernel

To debug an application on a target running Symbian OS™, you must have the Target
Resident Kernel (TRK) program installed on the device. TRK is a Symbian OS application
that runs inside the operating system and provides debug services via serial
communications to the CodeWarrior debugger running on the host computer. TRK lets
you download an application and support files to the target device and debug it using the
CodeWarrior debugger.
9.1.1 Starting TRK

Before you can connect to a Symbian device with the CodeWarrior debugger, you must
start TRK on the device.

Device Debugging
Target Settings
Start TRK.exe or TRK.app on the target device. Once TRK is running, the target device
displays a message similar to the text in Listing 9.1.
Listing 9.1 TRK Welcome Message
Welcome to TRK for Symbian OS

Version 2.10
Implementing TRK API version 3.0
PDD: EUART1
LDD: ECOMM
CSY: ECUART
Port Number: 0
Baud rate: 115200
NOTE The configuration settings are board specific and may vary.
The target device is now ready to start a CodeWarrior debug session.
9.2 Target Settings

This section describes the CodeWarrior IDE settings panels that let you configure a
CodeWarrior project for device debugging.
NOTE The CodeWarrior IDE User's Guide describes target settings panels and IDE
preference panels that are common to all CodeWarrior projects.
These settings panels are of particular interest to developers debugging applications,

executables, and libraries on Symbian OS devices:
• “Runtime Settings Panel”
• “Debugger Settings Panel”
• “Remote Debugging Panel”
• “Remote Download Panel”
• “Remote Connections Panel”
9.2.1 Runtime Settings Panel

The Runtime Settings panel (shown in Figure 9.1) lets you control how the IDE runs the
target executable.
This settings panel is always visible in the Target Settings window. To view the Target
Settings window, select Edit > TargetName Settings from the CodeWarrior menu bar
(where TargetName is the name of the build target you want to modify).

Device Debugging
Target Settings
Figure 9.1 Runtime Settings Panel
Many types of CodeWarrior projects use the settings in this panel; however only some
settings in this panel are relevant for Symbian OS device debugging. The settings in this
panel that pertain to device debugging are shown in Table 9.1.
Table 9.1 Runtime Settings panel—device debugging options
Option Explanation
Host Application for Libraries & If you want to debug a DLL from the project that creates
Code Resources that DLL, you must specify the host application or
executable that loads the DLL.
Click the Choose button to select the host application, or
type the full path to the host application or executable
into the text field. Click the Clear button to clear the
setting.
Program Arguments Enter in this field any command line arguments you
would like sent to the application or executable you are
debugging.
NOTE If you debug an application or executable target,
the IDE passes these arguments to that program. If you
debug a DLL target, the IDE passes these arguments to
the program specified in the Host Application for
Libraries & Code Resources setting.
9.2.2 Debugger Settings Panel

The Debugger Settings panel (shown in Figure 9.2) lets you control how the IDE debugs
the target executable.

Device Debugging
Target Settings
Figure 9.2 Debugger Settings Panel
Table 9.2 Debugger Settings panel—device debugging options
Option Explanation
Stop on application launch Check this box to have the debugger halt program
execution at the beginning of a debug session. When
this box is checked, the Program entry point, Default
language entry point, and User specified options are
enabled.
NOTE The Program entry point and Default language
entry point options are not supported for Symbian OS
device debugging.

Device Debugging
Target Settings
Table 9.2 Debugger Settings panel—device debugging options (continued)
Option Explanation
debug session. Enter in the text field the number of
Into, or Step Out.
Cache symbolics between runs Check this box to have the debugger cache symbolic
executable you are debugging has not changed.
Checking this box can improve debug session start
times.
NOTE When enabled, this option can prevent the IDE

from building a project with the command line after a
debug session due to symbolics being locked. Disabling
this option will prevent this behavior.
Uncheck this box to have the debugger load symbolic

information each time you start a new debug session,
regardless of whether or not the executable has
changed since the last debug session.
9.2.3 Remote Debugging Panel

The Remote Debugging settings panel (shown in Figure 9.3) controls how the
CodeWarrior debugger connects to target Symbian OS devices, where to place the debug
executable on the target device, and which processes (if any) to launch on the device when
a debug session starts.
This settings panel is visible when the Connection option is set to Symbian TRK in the
Remote Debugging panel. To view the Target Settings window, select
Edit > TargetName Settings from the CodeWarrior menu bar (where TargetName is the
name of the build target you want to modify).
NOTE CodeWarrior Development Studio for Symbian OS software has a default

connection called Symbian TRK. This connection is configured to connect to
the reference platforms in the Symbian OS development kits. If you have
changed any of the settings in the TRK.ini file, you must edit the settings in
the Remote Debugging panel to match these changes.

Device Debugging
Target Settings
Figure 9.3 Remote Debugging Settings Panel
Many types of CodeWarrior projects use the settings in this panel; however only some
settings in this panel are relevant for Symbian OS device debugging.
Table 9.3 Remote Debugging panel—device debugging options
Option Explanation
Connection Select an item from this menu representing the remote

connection with which you want to debug the device.
You configure remote connections using the Remote
Connections preference panel. See “Remote Connections
Panel” for more information.
Edit Connection Click this button to modify the connection associated with the
currently-selected Connection menu item. When you click this
button, the IDE displays a dialog box that lets you edit the
connection properties. For more information about this dialog
box, refer to “Remote Connections Panel”.

Device Debugging
Target Settings
Table 9.3 Remote Debugging panel—device debugging options (continued)
Option Explanation
Remote download path Enter in this text field the path to the location on the target
device where you want the CodeWarrior debugger to
download the output of the current build target. The path
must be the path to a RAM drive (usually C:\).
If you leave this text field blank, the debugger downloads the
build target output to the root of the C drive on the target
device.
NOTE You can run command-line executables from any
location in the Symbian OS for non-platform security devkit
SDKs. For these SDKs, applications must be located in the
C:\System\Apps\AppName\ directory to run properly
(where AppName is the name of the application).
Statically linked libraries may reside in the same directory as
the executable that calls them. Dynamically-linked libraries,
however, must be located in the C:\System\Libs\
directory to function properly.
With Symbian OS v9.1 and later that use platform security, all
executables and DLLs must reside in the c:\sys\bin
directory.
Launch remote host Check this box to have the debugger launch an executable on
application the target device when the debug session starts. Enter the
path to the executable on the target device in the associated
text field.
You can use this feature to debug a DLL project by specifying
the path to the executable that calls the DLL.
9.2.4 Remote Download Panel

The Remote Download settings panel (shown in Figure 9.4) lets you configure the
CodeWarrior debugger to download any files your program requires to the target device at
the start of the debug session (for example, resource files, bitmaps, or libraries).
NOTE To help speed up future debug sessions, the debugger does not download files
if they already exist on the target device and have not been changed on the host
since the last download.
NOTE This panel is not required for debugging in ROM.

Device Debugging
Target Settings
Figure 9.4 Remote Download Settings Panel
Table 9.4 Remote Download panel—options
Option Explanation
File List The file list displays a list of the files you want the IDE to
download to the target device at the start of a debug
session. For each file, the list displays the Host Path, the
path to the file on the machine running the CodeWarrior
debugger, and the Target Path, the path to the file on
the target device where the debugger places the file at
the start of a debug session.
Host File Path Enter in this text field the full path to the file on the
machine running the CodeWarrior debugger. Click
Browse to use the standard file dialog box to navigate
to and select a file.
Target File Path Enter in this text field the full path to the file on the
target device to indicate where you want the debugger
to place the file at the start of a debug session.
NOTE This path must include the destination file name.
The IDE creates the file with this name on the target
device.
Add Click the Add button to add the information in the Host
File Path and Target File Path text fields as a new entry
to the file list.

Device Debugging
Target Settings
Table 9.4 Remote Download panel—options (continued)
Option Explanation
Change Click the Change button to edit the currently-selected

list entry.
Remove Click the Remove button to delete the currently-selected

list entry.
9.2.5 Remote Connections Panel

The Remote Connections preference panel (shown in Figure 9.5) lets you create and
manage remote connections for use with all CodeWarrior projects.
This settings panel is always visible in the IDE Preferences window. To view the IDE
Preferences window, select Edit > Preferences from the CodeWarrior menu bar.
Each remote connection in this panel contains information necessary to establish a
debugger connection between the host computer and remote devices. The IDE displays
these remote connection entries in the Connection menu in the Remote Debugging target
settings panel (see “Remote Debugging Panel”).
Figure 9.5 Remote Connections Preference Panel
NOTE The Symbian TRK remote connection is already defined for use in debugging
Symbian OS devices connected to the COM1 port of the host computer.

Device Debugging
Target Settings
Creating a New Remote Connection for Device Debugging

1. Start the CodeWarrior IDE.
2. Select Edit > IDE Preferences from the CodeWarrior menu bar.
The IDE displays the IDE Preferences window (Figure 9.6).
Figure 9.6 IDE Preferences Window
3. Select Remote Connections from the IDE Preference Panels list.

The IDE displays the Remote Connections preference panel (Figure 9.7).

Device Debugging
Target Settings
4. Click Add.
The IDE displays the New Connection dialog box (Figure 9.8).
Figure 9.8 New Connection Window
5. Define the new remote connection in New Connection window

Device Debugging
Target Settings
a. Enter in the Name text field a name for the new connection, such as TRK
Connection.
b. Select Symbian TRK Protocol from the Debugger menu.
The IDE displays Symbian TRK-related settings in the panel.
c. Select Serial from the Connection Type menu.
d. Select the communications port to which the device is connected from the Port
menu.
e. Select the appropriate Rate, Data Bits, Parity, Stop Bits, and Flow Control for
the device.
f. If you would like the debugger to display a log of all communications through this
connection, check the Log Communications Data to Log Window box.
g. Click OK.
The IDE saves your changes. The new connection appears in the Remote
Connections list (Figure 9.9).
Figure 9.9 Remote Connections Window - Showing New Connection
6. Click OK in the IDE Preferences window

The IDE saves your changes and closes the IDE Preferences window.
You can now use the new remote connection in your projects. For further details about this
preference panel, refer to the CodeWarrior IDE User's Guide.

Device Debugging
9.3 Debugging an Application

This section shows you how to configure a CodeWarrior project to debug an application
on a target Symbian OS device.
Debugging an Application on a Target Symbian OS Device

2. Open the CodeWarrior project for the application you want to debug.
The IDE displays the Project window.
NOTE If you do not have an existing CodeWarrior project configured to build a

Symbian OS application, you can easily import one of the MMP files from the
examples directory of the Symbian OS development kit. See “Importing a
Project from a makmake Project File” for instructions showing how to import
MMP files into the CodeWarrior IDE.
3. Select Project > Set Default Target > TargetName from the CodeWarrior menu bar
to switch to the build target you want to debug (where TargetName is the name of the
build target).
The IDE makes the build target you select the active build target.
TIP If you created this project by importing a MMP file, the debug build target names
in the project end with “UDEB”. Select one of these build targets.
4. Select Project > Make from the IDE menu bar.

The IDE builds the debug target.
5. Select Edit > TargetName Settings from the CodeWarrior menu bar (where
TargetName is the name of the current build target).
The IDE displays the Target Settings window (Figure 9.10).

Device Debugging
Figure 9.10 Target Settings Window
6. Select Remote Debugging from the Target Settings Panels list.

The IDE displays the Remote Debugging settings panel (Figure 9.11).
7. Select Symbian TRK from the Connection menu.

Device Debugging
8. Enter the following path in the Remote download path text field (where AppName is
the name of the application generated by the current build target.
• For v8.x or earlier, use: C:\System\Apps\AppName\
• For v9.1 with platform security, use: C:\sys\bin\AppName\
9. Select Remote Download from the Target Settings Panel list.
The IDE displays the Remote Download settings panel (Figure 9.12).
10. For each file the application requires to be present on the device in order to run
properly (for example, resource files or bitmap files):
a. Click Browse.
The IDE displays the file selection dialog box.
b. Navigate to the directory containing the file you want the debugger to download to
the device when you debug the application.
c. Select the file you want the debugger to download to the device.
d. Click Open.
The IDE closes the file selection dialog and displays the path to the file in the Host
File Path text field.
e. Enter in the Target File Path text field the full path and filename on the target
device where you want the debugger to place the file.

Device Debugging
NOTE The Target File Path must include the destination file name. The IDE creates
the file with this name on the target device.
11. Click OK in the Target Settings window.

The IDE saves your changes and closes the Target Settings window.
12. In the Files page of the Project window, double-click the source file that contains the
function in which you want the debugger to stop program execution when you debug
the application.
The IDE displays the contents of the source file in an editor window.
13. In the editor window, scroll to the function you want to debug.
14. Click the breakpoint column on the left side of the editor window next to the line of
code at which you want the debugger to stop execution.
The IDE displays a breakpoint on the line you click.
15. Start MetroTRK.app or MetroTRK.exe on the target device.
TIP You must include the TRK program in the ROM of the device before you can run
it on the target device.
TIP For instructions showing how to start the TRK program on the target device, see
“Starting TRK”
16. Select Project > Debug from the CodeWarrior menu bar.
The IDE builds the current target, downloads the application and associated files to the
device, starts a debug session, stops at the breakpoint you set, and displays the Thread
window (Figure 9.13).

Device Debugging
Figure 9.13 Thread Window
You can now use the Thread window to start, stop, and step through your code. You can
interact with the application using the device.
NOTE During TRK debug sessions, the Kill button in the Thread window kills the
process you are debugging and ends the debug session.
See the CodeWarrior IDE User's Guide for complete information on using the
9.4 Debugging an Executable File

This section shows you how to configure a CodeWarrior project to debug an executable on
a target Symbian OS device.
Debugging an Executable on a Target Symbian OS Device

2. Open the CodeWarrior project for the executable you want to debug.

Device Debugging

Symbian OS executable, you can easily import one of the MMP files from the
build target).

6. Set remote debugging options in Remote Debugging panel

Device Debugging
a. Select Remote Debugging in the Target Settings Panels list.

NOTE For v9.1 or later with platform security, use the path C:\sys\bin.
b. Select Symbian TRK from the Connection menu.

c. Enter in the Remote download path text field the path to the directory on the
target device where you want the CodeWarrior debugger to download the
executable when you start a debug session.
NOTE If one or more of the directories in the path you supply do not exist on the
target device, the debugger creates them before downloading the executable to
the device.
NOTE If you imported this project from a MMP file, the IDE has already configured
the target settings to download the executable to the root of the C: drive.
7. Set remote download options in Remote Download panel

a. Select Remote Download from the Target Settings Panel list.

Device Debugging
8. For each file the executable requires to be present on the device in order to run
properly (for example, DLL files):
a. Click Browse.
the device when you debug the executable.
d. Click Open.
9. Specify debugger options in the Debugger Settings panel

a. Select Debugger Settings from the Target Settings Panel list.
The IDE displays the Debugger Settings panel (Figure 9.17).

Device Debugging
b. Select the User specified option.

c. Enter in the User specified text field the name of the function at which you want
the debugger to stop program execution.
NOTE The IDE sets the User specified field to E32Main by default. If you want to
stop execution in a different function, replace the contents of this field with the
name of another function.
d. Click OK in the Target Settings window.

10. Set breakpoint to source file
a. In the Files page of the Project window, double-click the source file that contains
the function in which you want the debugger to stop program execution when you
debug the executable.
b. In the editor window, scroll to the function you want to debug.
c. Click the breakpoint column on the left side of the editor window next to the line of
11. Start the TRK program on the target device.

Device Debugging
“Starting TRK”.
The IDE builds the current target, downloads the executable and associated files to the
device, starts a debug session, stops on entry to the function you specified in the
Debugger Settings panel, and displays the Thread window (Figure 9.18).
interact with the executable using the device.

Device Debugging
Debugging a DLL
9.5 Debugging a DLL

This section shows you how to configure a CodeWarrior project to debug a dynamically-
linked library (DLL) on a target Symbian OS device.
The most convenient method of debugging a DLL involves the use of at least two
CodeWarrior project files, one for the host application that calls the DLL whether static or
dynamic, and one for the DLL itself. When using this method some important points to
remember include:
• In the Runtime Settings panel, only the DLL project should complete the Host
Application for Libraries & Code Resources text box by including the host
application or executables name.
• In the Remote Debugging settings panel, only the DLL project should complete the
Launch remote host application text box by including the host application’s name.
• Both projects must fill in the Remote Download settings panel information. The
host application project should list all of the DLL’s it calls, and the DLL project
should list the host application. Fail to do this and the debugger may be unable to
locate and use each project’s breakpoints.
When both the host application project and DLL project are correctly configured you can
smoothly switch from one project file to another to launch the debugger by clicking the
Debug icon in either project window.
Debugging a DLL on a Target Symbian OS Device

2. Open the CodeWarrior project for the DLL you want to debug.

Symbian OS DLL, you can easily import one of the MMP files from the
build target).

Device Debugging
Debugging a DLL

6. Select Runtime Settings from the Target Settings Panels list.

The IDE displays the Runtime Settings panel (Figure 9.20).
7. Set the project’s Runtime Settings options.

Device Debugging
Debugging a DLL
Figure 9.20 Runtime Settings Panel
a. Click Choose.
The IDE displays a file selection dialog box.
b. In the DLL project, navigate to the directory on the host machine of the application
or executable that uses the DLL.
c. Select the application or executable that uses the DLL.
d. Click Open.
The IDE closes the file selection dialog box and displays in the Host application
for Libraries & Code Resources text field the full path of the application or
executable that uses the DLL.
8. Select Remote Debugging in the Target Settings Panels list.

Device Debugging
Debugging a DLL
Figure 9.21 Remote Debugging settings panel
NOTE For v9.1 or later with platform security, use the path C:\sys\bin.
9. Set the project’s Remote Debugging options.

a. Select Symbian TRK from the Connection menu.
b. Enter in the Remote download path text box the path to the directory on the target
device where you want the CodeWarrior debugger to download the DLL or
applciation when you start a debug session.
TIP Enter the appropriate path to download the library or application. These include:
– Dynamically-loaded library–use C:\System\Libs\

– Static-linked library–use the path to the directory that contains the application
or executable that uses the library.
– Applications–use the path C:\System\Apps\AppName\
– Executables–use the full path and filename where you want the debugger to
place the file on the device.
NOTE If one or more of the directories in the path you supply do not exist on the
target device, the debugger creates them before downloading the executable to
the device.
c. If this is a DLL project, check the Launch remote host application checkbox.
NOTE You should not enable this option in the application project.

Device Debugging
Debugging a DLL
d. If this is a DLL project, enter in the Launch remote host application text box the
full path and name of the application or executable that uses the DLL you want to
debug.
The CodeWarrior debugger launches this application or executable when you start
a debug session.
10. Select Remote Download from the Target Settings Panels list.
NOTE The Remote Download settings panel is only used for debugging projects in
RAM. It is not required to debug projects in ROM.
Figure 9.22 Remote Download settings panel
11. Set the project’s Remote Download options.
NOTE When setting the Remote Download options remember that the host
application project should list every DLL it calls or loads while the DLL only
needs to list the host application project.
If the application or executable that uses the DLL is not already on the target device,
add the application or executable using this panel. Debugging a DLL requires that each
file the application or executable requires be present on the device in order to run
properly (for example, resource files or bitmap files). To add files:
a. Click Browse.

Device Debugging
Debugging a DLL
the device when you debug the DLL.
d. Click Open.
TIP Enter the appropriate path to download the library or application. These include:
– Dynamically-loaded library–use the path appropriate for the Symbian OS

release:
• v8.x and earlier: C:\System\Libs
• v9.x and later: C:\sys\bin\
– Static-linked library–use the path to the directory that contains the application
or executable that uses the library.
– Applications–use the path appropriate for the Symbian OS release:
• v8.x and earlier: C:\System\Apps\AppName\
• v9.x and later: C:\sys\bin\AppName\
– Executables–use the full path and filename where you want the debugger to
place the file on the device.
12. Click OK in the Target Settings window.

13. In the Files page of the Project window, double-click the source file that contains the
function in which you want the debugger to stop program execution when you debug
the DLL.
14. In the editor window, scroll to the function you want to debug.
15. Click the breakpoint column on the left side of the editor window next to the line of
16. Start the TRK program on the target device.

Device Debugging
Debugging via a USB Connection
“Starting TRK”.
The IDE builds the current target, downloads the application or executable that uses
the DLL and the DLL itself to the device, starts a debug session, stops at the
breakpoint you set, and displays the Thread window (Figure 9.23).
interact with the executable using the device.
9.6 Debugging via a USB Connection

You can also debug an application on the device via USB. The only complication is that
the connecting software and the debugger cannot use the COM port at the same time. The

Device Debugging
Debugging via a USB Connection
following steps describe the guidelines to set up a Sony Ericsson P800 phone for
debugging via USB.
NOTE The name of the connecting software used for your device is probably different
than the one used below (PC Suite). Always refer to the documentation that
came with the device for any device-specific information.
To set up a device for debugging via USB:

1. Determine which COM port the USB device uses
– Sony Ericsson P800/P900: Open the Phone Connection Link Properties for the
P800 phone. By default this appears in the task bar for the host computer, or you
can double-click the icon to open the Link Properties window. The Link
Properties window lists the connections to the P800 such as Cable, USB, Infrared,
and identifies which COM port each uses. By default, the USB cradle uses COM
port 4. Make a note of the COM port used by the USB cradle.
– Other devices: Open the software that controls the link between the device and
the host computer. Locate and identify which COM port the device and host use
to communicate and make a note of it.
2. Create a Remote Connection setting for USB
You must also set up a Remote Connection in the CodeWarrior IDE to specify the
proper COM port to use.
– Sony Ericsson P800/P900: This is normally the same as the port used by the
Connection Link software for the P800 or P900 phone (COM 4 by default). Call it
Symbian P800 USB to differentiate it from the Symbian TRK connection setup
(Figure 9.24).
– Other devices: Create a remote connection setting that uses the COM port
identified in the previous step. Call it Symbian <device> USB to differentiate it
from other TRK connection setups.

Device Debugging
Viewing Processes
Figure 9.24 Remote Connection setup for USB connection
3. Disconnect the PC Suite before debugging

To debug you must first disconnect the PC Suite, since it uses the USB cradle to allow
you to navigate the phone’s file system. Turn off the check box next to the USB
connection to deactivate the PC Suite’s ability to use the cradle.
Once you finish debugging, you can resume normal operation by going to the Phone
Connection Link Properties and turn on the USB connection for the PC Suite again.
9.7 Viewing Processes

The CodeWarrior IDE lets you view a list of the processes running on a target Symbian
OS device.
To View all Processes Running on a Target Symbian OS Device

2. Select File > Open from the CodeWarrior menu bar.
The IDE displays a file selection dialog box.
3. Open a CodeWarrior project for a Symbian OS application, executable, or library.

Device Debugging
Viewing Processes
4. Select Project > Set Default Target > DebugTargetName (where DebugTargetName
is the name of a debug build target in the project).
The IDE switches to the build target you specified.
The IDE downloads the project output files to the device, starts a debug session, and
displays the Thread window (Figure 9.25).
6. Select View > Processes from the CodeWarrior menu bar.

The IDE displays the Processes window (Figure 9.26).

Device Debugging
Figure 9.26 Processes Window
7. Select Symbian TRK from the Target Machine menu at the top-left of the window.
The IDE displays the processes running on the target device (Figure 9.27).
Figure 9.27 Processes Window - Showing Symbian OS Processes
The Processes window displays process names, ID’s, and priorities. To see all of this
information, expand the Processes window and the Process pane.
You can select any process to display a list of the threads that belong to that process.


Device Debugging
Troubleshooting
example, aString is a descriptor and has “Hello!” for its value.
9.9 Troubleshooting
This section contains answers to common problems specific to device debugging:
• TRK Displays an Error Code
• Cannot Connect to TRK
• Device Displays Not Found Error
TRK Displays an Error Code

When you start TRK, it displays an error message.
The error code TRK displays is a standard Symbian OS error code that may help
determine the problem.
Ensure that the information in the TRK.ini file is correct for the target device.
Make sure that the port defined in the Symbian TRK remote connection is not currently
in use by another application.

Device Debugging
Troubleshooting
TIP To view or edit a remote connection, Select Edit > IDE Preferences from the
CodeWarrior menu bar, and click Remote Connections in the IDE Preferences
window.
Cannot Connect to TRK

When you try to start a CodeWarrior debug session with a device running TRK, you get an
error message that says “Can’t connect to TRK”.
The CodeWarrior debugger running on the host machine is not receiving a response from
the remote TRK program.
Make sure the cable is plugged in to the correct port on both the host machine and the
target device.
Make sure the serial cable is the correct type for the device. Make sure that the
CodeWarrior remote connection settings for the build target you are debugging match the
corresponding settings in the TRK.ini file on the device.
Try hooking up a terminal program to the COM port on the host machine and then
launching TRK on the device. You should see the following message from TRK: “TRK
for Symbian OS started”.
Device Displays Not Found Error

You try to debug an application; but get a message on the screen saying “Not Found”.
This error indicates that the resource file for the application or another application support
file was not found on the device.
Make sure every support file your application requires (for example, resource files and
bitmap files) is downloaded to the target device.
TIP You instruct the IDE to download application support files to the target device
using the Remote Download Panel settings panel. See “Remote Download Panel”
for more information.

Device Debugging
Troubleshooting

10 Device Debugging in ROM
CodeWarrior Development Studio for Symbian OS software lets you debug components
of the OS, including your application, in ROM. This can be done using TRK. This chapter
builds on “Device Debugging” and assumes you have read it.
The IDE uses the information in the log file generated when the ROM image was built to
give you access to almost any component in the ROM image. To be able to debug a ROM
image using the IDE, the ROM image must be built with symbolics information.
The IDE cannot give access to objects running in kernel space. Consequently, when
debugging a ROM image, the IDE does not control TRK, kernel processes and threads,
and device drivers.
The rest of this chapter describes how to debug a ROM image on a target device:
• “Debugging in ROM”
• “Opening Symbolic Files and Setting Breakpoints”
• “Attaching to a Process or Thread”
• “Troubleshooting”
NOTE TRK must be enabled on the target device to debug the ROM.
10.1 Target Settings

In addition to the settings described in “Device Debugging” CodeWarrior Development
Studio for Symbian OS software provides a settings panel that lets you specify the location
of the log file generated from the ROM build and some related options:
• “Symbian Debugging Panel”
10.1.1 Symbian Debugging Panel

The Symbian Debugging settings panel specifies information about the ROM image on
the target device. The IDE’s debugger uses the standard log file generated in the ROM

Device Debugging in ROM
Target Settings
building process to get the addresses of each component on the target device and the
locations of symbolic information files stored on the host computer.
Figure 10.1 Symbian Debugging Settings Panel
Table 10.1 Symbian Debugging Settings panel—options
Option Explanation
Parse ROMBUILD Log File Turn on this option and fill in the other fields to specify
the information that the debugger needs to show
detailed stack information, set breakpoints, and show
source level debugging information for ROM images. In
the first text field, browse to or enter the full path and
name of the log file that corresponds to the ROM image
on the target device. This log file is generated by default
when the ROM image is built.
Symbian OS Kit Epoc32 Specifies the epoc32 directory in which the ROM image
Directory and log files are stored. Since the log file may not
contain full paths to the ROM components on the host
PC, you need to enter this epoc32 directory.
NOTE: Always include the epoc32 folder in this path.
Log unresolved modules Check this box to have the debugger output a list of
modules from the specified ROMBUILD log file that the
debugger cannot resolve. The IDE displays this list in the
debugger console window at the beginning of the
debug session.

Debugging in ROM
Table 10.1 Symbian Debugging Settings panel—options (continued)
Option Explanation
Log unresolved .sym files Check this box to have the debugger output a list of
components from the specified ROMBUILD log file that
do not have debugger symbolic information. The IDE
displays this list in the debugger console window at the
beginning of the debug session.
NOTE: You cannot perform source-level debugging on

components that do not include symbolic
information.
Debug non-XIP executables Check this box to debug a project, or a dynamically

loaded module, that is loaded from NAND-Flash or other
removable media (MMC, memory stick, etc.) at run time
and executed in RAM. Use this option to debug modules
that work fine when executed in place as part of the
ROM image, but sometimes fail when placed in NAND-
Flash or other removable media.
NOTE: Selecting this option will affect debugging

performance. When the debugger needs to
load a module (DLL, EXE, etc.) it will stop the
target, read information from it, then restart it.
10.2 Debugging in ROM

Debugging an application, executable file, or DLL in ROM is the same as debugging these
entities in RAM with these exceptions:
• The Symbian Debugging panel must be configured correctly.
• The module to be debugged must reside in the ROM image and built with symbolic
information.
• To debug a module, set the Remote download path field of the Remote Debugging
panel to the path on the target device (Figure 10.2).
NOTE Typically, Z is the drive letter assigned to the ROM file system of a Symbian
OS image.

Debugging in ROM
Figure 10.2 Remote Debugging path to debug a module
NOTE For Symbian OS v9.1 or later with platform security, use the path
C:\sys\bin.
Whether or not the project you are debugging resides in ROM, you will see symbolic
information for other components if those components were built with symbolic
information. If a function in the stack crawl is in a ROM module and the IDE is able to
find a file containing symbolic information for that module, the IDE will load it
automatically and display function names. The IDE will also allow source level debugging
and let you set breakpoints in this module.

Opening Symbolic Files and Setting Breakpoints
Figure 10.3 Symbolics window
The symbolics window (Figure 10.3) appears when files containing symbolic information
are loaded. From the symbolics window you can easily navigate the sources for each
component and set breakpoints if necessary. If there are no symbolics available for a
component, you will see the name of the module containing the function in the stack crawl
of the debugger window.
10.3 Opening Symbolic Files and Setting

Breakpoints
There is no limit to the number of breakpoints which may be set in ROM. There is
however a restriction on where breakpoints can be placed. No breakpoints can be set from
the beginning of ROM to the end of the user library (Euser.dll). For typical ROM
images, this limitation means that breakpoints are not allowed in Ekern.exe or
Euser.dll. This restriction is applied because setting a breakpoint in a location that
could be hit by a thread running in the kernel space could cause the system to stop.
While you cannot set breakpoints in certain locations, you can still see source information
for those locations which can be helpful when debugging problems with your application.
In addition, if you are using TRK in stop mode, you can set breakpoints while threads are
running or stopped.
Note that if you set a breakpoint at certain locations in ROM, several different threads
from different processes may hit that breakpoint. If that were to happen, the owning

Attaching to a Process or Thread
process gets targeted automatically and the thread window(s) would open and be stopped
at that location.
If you want to set a breakpoint in a module residing in ROM before starting a debug
session, you can open the module or its .sym file by choosing File > Open from the
IDE’s menu or simply drag-and-dropping the .sym file on the IDE. Typically, a
module’s .sym file matches its name and is stored in the output directory of the
module’s build target.
Once the file is opened by the IDE, the Choose Debugger dialog box appears asking you
to select a debugging protocol. Note that selecting the wrong protocol at this point causes
all currently set breakpoints to be ignored.
If more than one remote connection is defined, you must select which debugger to use
when debugging that module. If more than one connection is defined but you only ever
use one of them, you can remove the unused connections and you will no longer be
prompted to select a debugger. Once the file is opened and the debugger selected, the
symbolics window will now contain the module and you can set breakpoints in it.
10.3.1 Resuming a Thread

To close a thread window without killing the owning process, just close the window using
the window’s Close icon ( ) or selecting Window > Close from the CodeWarrior menu
bar. If this window is the only thread window open for a process, an alert message appears
asking if you want to kill the process or resume it. Resuming the process effectively
detaches it from the debug session, leaving it running on the target.
10.3.2 Killing a Process

Click the Kill control ( ) in any thread window to terminate the owning process on the
target. If its the only thread open the debug session is also ended.
CAUTION Killing a thread on the device may place the Symbian OS in an unstable
state, possibly making it crash. Note that it is always better to resume than
to kill a process.
10.4 Attaching to a Process or Thread

You can view the processes and threads currently running on the target in the Processes
window (Figure 10.4). Choose Symbian TRK in the Target Machine menu, then select a
process and click the Attach to Process icon ( ) in the Processes window to attach the
debugger to that process. A thread window for the main thread in that process will appear.
NOTE You can’t attach to a running process in RAM and source level debug it,
although you can if the process is in ROM. The debugger can do this because
the .log file contains the addresses of everything in ROM. For RAM, the

debugger relies on getting the addresses of the executable and library processes
when they are started. Since a running executable started before the debug
session, the host debugger never gets notified when the program is loaded and
can’t determine what its address is.
Figure 10.4 Example of a Processes Window during ROM Debugging
You cannot attach to a system process, a protected process, or the TRK process because
stopping a thread in one of those processes could stop the system. Once attached to a
process, you can open a thread window for any of its threads by double-clicking on it.
10.4.1 Debugging a Connection

Alternately, you can connect to the target device without explicitly debugging a specific
module by choosing Debug > Connect from the IDE’s menu. This command is only
available when a project that is set up correctly for debugging is active on the target
device. This command shows a “dummy” thread window with ID 0x0. This thread does
not represent an actual thread on the device and can be killed to end the session.


Troubleshooting
10.6 Troubleshooting
Stack Crawl and Stepping Do Not Work in the Debugger

I am able to launch my application in ROM, but the stack crawl and stepping do not seem
to be correct.
Make sure that the version in the ROM image is really the debug version. This can be
verified by examining the ROM log file.

11 Kernel Debugging
This chapter describes various Symbian OS kernel debugging issues and provides step-by-
step tutorials showing how to debug Symbian OS start-up code, kernel code and device
drivers.
This chapter includes these topics:
• “Overview”
• “Debugging Kernel and Boot-Loaded Device Drivers Example”
• “Debugging Bare-Board Start-Up Code Example”
• “Attaching to a Process or Thread”
• “Opening Symbolic Files and Setting Breakpoints”
• “Viewing Processes, Threads, Libraries, and Chunks”
• “Supporting Dynamic Targets (OEM only)”
11.1 Overview
The CodeWarrior Development Studio for Symbian OS software lets you debug Symbian
OS v7 through v9 start-up code, kernel code, device drivers, and any other executable in a
Symbian ROM image. CodeWarrior for Symbian OS supports this type of debugging if
the host PC is connected to the JTAG interface of a Symbian target device by an ARM
RDI or Lauterbach Trace32 compliant in-circuit emulator.
NOTE If you are using a TI TargetServer compliant emulator, you must use Texas
Instruments’ Code Composer Studio software to create a configuration for this
emulator.
If connected to a JTAG interface, the CodeWarrior debugger uses stop-mode debugging.

Stop-mode debugging (also called kernel debugging) lets the CodeWarrior debugger halt
the target device such that the debugger controls the execution of the entire CPU. When

Kernel Debugging
Target Settings
the CPU is stopped, the operating system and user programs running on the device are also
stopped and are therefore not able to modify processor registers or memory.
For kernel debugging, the CodeWarrior debugger does not download and launch
individual Symbian executable files on the device. Instead, you must build the executable
files you want to debug into the Symbian ROM image on the device before starting a
debug session. The CodeWarrior debugger can optionally install a ROM image onto the
device for you when you start a debug session. See “Symbian Kernel Debugging” for
more information.
11.2 Target Settings

There are several settings panels that let you configure CodeWarrior projects for
debugging devices using stop-mode debugging. This chapter describes only the settings
panels that are specific to Symbian OS kernel debugging.
NOTE The CodeWarrior IDE User's Guide describes target settings panels and IDE
preference panels common to all CodeWarrior projects.
These settings panels are of particular interest to developers doing kernel debugging:
• “Debugger Settings”
• “Remote Debugging”
• “Symbian ARM Debugger Settings”
• “Symbian Debugging”
• “Symbian Kernel Debugging”
• “Remote Connections”
11.2.1 Debugger Settings

The Debugger Settings panel (shown in Figure 11.1) lets you control how the IDE debugs
the target executable.

Kernel Debugging
Target Settings
Table 11.1 Debugger Settings panel—kernel debugging options
Option Explanation
Library Targeting Controls how the CodeWarrior Debugger handles the

loading of libraries during a debug session. For
debuggers that support smart-targeting, like the x86
Debugger, the following choices are available:
• None–No libraries are loaded during a debug
session.
• Smart-Targeting–Libraries are loaded as
needed when the debugger thread is halted
during a debug session. Smart-Targeting is
disabled for debuggers that do not support
this feature.
• Auto-Targeting–All libraries required during
the debug session are loaded. This can result
in slower debugger performance for
processes that load lots of modules (ex.
Symbian’s epoc.exe).
NOTE: Breakpoints set in a source file but not mapped
to an open symbolics (executable) file will not work
until the correct symbolics file is opened.

Kernel Debugging
Target Settings
Table 11.1 Debugger Settings panel—kernel debugging options (continued)
Option Explanation
debug session. In the text field, enter the number of
Into, or Step Out.
Cache symbolics between runs Check this box to have the debugger cache symbolic
executable you are debugging has not changed.
Checking this box can improve debug session start
times.
Uncheck this box to have the debugger load symbolic
information each time you start a new debug session,
regardless of whether or not the executable has
changed since the last debug session.
11.2.2 Remote Debugging

The Remote Debugging settings panel (shown in Figure 11.2) controls how the
CodeWarrior debugger connects to target Symbian OS devices.
This settings panel is always available in the Target Settings window. To display the
Target Settings window, select Edit > TargetName Settings from the CodeWarrior menu
bar (where TargetName is the name of the build target you want to modify).

Kernel Debugging
Target Settings
Table 11.2 Target Settings panel—options
Option Explanation
Connection Select an item from this menu representing the remote

connection with which you want to debug the device.
NOTE TRK is not available for stop-mode debugging.
You configure remote connections using the Remote
Connections preference panel. See “Remote
Connections” for more information.
Edit Connection Click this button to modify the connection associated

with the currently-selected Connection menu item.
When you click this button, the IDE displays a dialog box
that lets you edit the connection properties. For more
information about this dialog box, refer to “Remote
Connections” on page 163.
Remote download path Unused for kernel debugging.
Launch remote host application Unused for kernel debugging.
11.2.3 Symbian ARM Debugger Settings

The Symbian ARM Debugger Settings panel (shown in Figure 11.3) lets you control
certain aspects of the ARM debugger.
The Symbian ARM Debugger Settings panel does not always appear in the panel list of
the Target Settings window. Instead, this panel is listed only if the remote connection
selected in the Remote Debugging panel uses the Symbian RDI, TI debugger, or
Lauterbach.
To display the Target Settings window, select Edit > TargetName Settings from the
IDE’s menu bar (where TargetName is the name of the build target you want to modify).

Kernel Debugging
Target Settings
Figure 11.3 Symbian ARM Debugger Settings Panel
Table 11.3 Symbian ARM Debugger Settings panel—options
Option Explanation
Hardware Board This menu contains a list of supported hardware boards

and a generic setting. Select the board type you want to
debug. Boards currently supported include:
• Lubbock
• RTC_RB3
• TI H2
• TI H4
• Generic
If the board type is unknown or the Target Processor
value modified as described in “Adding a Hardware
Target”, this field will display “Generic”.

Kernel Debugging
Target Settings
Table 11.3 Symbian ARM Debugger Settings panel—options (continued)
Option Explanation
OS Version Select the desired RTOS support from this menu.

If you select Bareboard from this menu, the CodeWarrior
debugger has no awareness of processes or threads
running on the target device. With this RTOS support,
you can debug the ROM image on the device. However,
you will not be able to view Symbian OS objects, such as
processes and threads, and their attributes on the
target device.
If you select Symbian from this menu, the CodeWarrior
debugger is aware of processes and threads running on
the target device. You can therefore view individual
processes, threads, libraries, and chunks.
NOTE: You can modify the contents of this field to
support new OS versions. See “Modifying an OS Version”
for information.
Target Processor This menu contains a list of supported processor types.

Selecting the Hardware Board option first automatically
updates the Target Processor list to only include
processors the hardware board supports. For example, if
you choose “TI H4” as the hardware board, then the
Target Processor list updates to only show the
“OMAP24xx” processor.
TIP To view the Registers window, select View >
Registers from the IDE’s menu bar during a debug
session.
Use Target Initialization File Check this box to have the debugger run an
initialization script when the debug session starts. For
example, if a target device requires initialization for the
debugger to be able to read and write memory or
registers, you can specify an initialization script here.
Click Browse to select a script file using a standard file
selection dialog box.
NOTE: CodeWarrior™ Development Studio for

Symbian™ OS v3.1 includes target initialization
files for certain target devices, such as the
Texas Instruments Innovator. These files are in
this directory:
InstallDir\Symbian_Support\
Initialization_Files
where InstallDir stands for the directory that
contains CodeWarrior for Symbian OS.

Kernel Debugging
Target Settings
Table 11.3 Symbian ARM Debugger Settings panel—options (continued)
Option Explanation
Use Memory Configuration File Controls whether the debugger uses a memory
configuration file when a debug session starts.
WARNING! This option is not available for stop-mode
debugging and should always be disabled.
Reset Target at the Start of each Forces the IDE to reset the target at the start of each
Debug Session debug session. This ensures that the debugging session
uses the most up-to-date program code.
11.2.3.1 Target Processor

The Target Processor list in the Symbian ARM Debugger Settings preference panel lists
supported ARM processors. These processors include:
• Generic
• ARM920T
• ARM926TEJ
• ARM1136J(F)-S
• OMAP3xx
• OMAP1510
• OMAP16xx
• OMAP1710
• OMAP24xx
• XScale
NOTE The OMAP24xx is an implementation of ARM1136. Both enable you to debug

a TI H4 board.
Selecting the Hardware Board option automatically updates the Target Processor list to
only include processors the hardware board supports. For example, if you choose “TI H4”
as the hardware baord, then the Target Processor list updates to only show the
“OMAP24xx” processor.
To take complete advantage of all debugger features it is strongly recommended that you
choose the correct processor for the target device. Choosing the wrong target processor
can result in the following behaviors:
• If “Generic” is selected, only register groups common to all ARM processors are
visible. Whenever a processor is selected, the processor specific register groups are
visible in addition to the common register groups. Currently, only the CP15 register
group is supported.

Kernel Debugging
Target Settings
• Choosing the wrong processor prevents you from performing kernel-aware

debugging, essentially preventing you from seeing process and thread information,
or other kernel information such as chunks.
• Choosing “Generic” allows you to debug any board, but kernel-aware debugging
will not be available.
NOTE You can modify the contents of the Target Processor field to support new target
processors. See “Supporting Dynamic Targets (OEM only)” for for
information.
11.2.4 Symbian Debugging

The Symbian Debugging settings panel (shown in Figure 10.1) lets you specify the
ROMBUILD log file and control whether the debugger logs unresolved modules and
unresolved SYM files. The CodeWarrior debugger uses the settings in this panel to obtain
the memory address of each component on the target device, as well as the location of
symbolic information files on the host machine.
The Symbian Debugging panel does not always appear in the panel list of the Target
Settings window. Instead, this panel is listed only if the remote connection selected in the
Remote Debugging panel supports an in-circuit emulator.
See “Symbian Debugging Panel” for more details.
11.2.5 Symbian Kernel Debugging

The Symbian Kernel Debugging settings panel (shown in Figure 11.4) lets you configure
the way the CodeWarrior debugger starts debug sessions to Symbian devices.
The Symbian Kernel Debugging panel does not always appear in the panel list of the
Target Settings window. Instead, this panel is listed only if the remote connection
selected in the Remote Debugging panel supports an in-circuit emulator.
To view the Target Settings window, select Edit > TargetName Settings from the
CodeWarrior menu bar (where TargetName is the name of the build target you want to
modify).
TIP Use the Debugger menu in the Edit Connection window to assign a debugger to a
remote connection. View the Edit Connection window by clicking the Change
button in the Remote Connections IDE preference panel.

Kernel Debugging
Target Settings
Figure 11.4 Symbian Kernel Debugging Settings Panel
Table 11.4 Symbian Kernel Debugging Settings panel—options
Option Explanation
Start address Enter in this text field the physical address in memory
from which the execution of Symbian OS start code
begins. This address is target-specific. The address
should be in the form of a hexadecimal number with
the 0x prefix. For example, 0x00100000 is a valid entry.
NOTE: The address entered in this field must match

the start address specified in the source code
used to build the Symbian OS ROM image to be
debugged.
NOTE: The Start address must match the Download

address.
Debug from start address Select this option to have the debugger halt the
program at the address specified in Start Address. You
can then step through start-up code or run the target in
bare-board mode.

Kernel Debugging
Target Settings
Table 11.4 Symbian Kernel Debugging Settings panel—options (continued)
Option Explanation
Run from start address Select this option to have the debugger start the code at
the address specified in Start Address. If you have
breakpoints set, the debugger stops at the first
breakpoint encountered. You can click the Break button
to halt the device.
Download .img File Check this box to have the debugger download a binary
ROM image file to the target device before starting the
debug session. The debugger places the image onto the
device at the memory location specified by the
Download address text field.
Download address Enter in this text field the physical address in memory at
which the debugger should place the ROM image. This
address is target-specific. The address should be in the
form of a hexadecimal number with the 0x prefix. For
example, 0x000FFF00 is a valid entry.
NOTE: The address entered in this field must match

the download address specified in the source
code used to build the Symbian OS ROM image
to be debugged.
NOTE: If you leave this field blank, the debugger does

not download the ROM image to the device at
the beginning of the debug session.
NOTE: The Download address must match the Start

address.

Kernel Debugging
Target Settings
Table 11.4 Symbian Kernel Debugging Settings panel—options (continued)
Option Explanation
Ask at the start of each debug Check this box to have the debugger display a dialog
session box at the beginning of every debug session letting you
choose whether or not you want the debugger to
download the ROM image to the device.
Debug Bootrom .sym file Check this box to have the debugger use the symbolics
file for the start-up bootstrap code at the start of the
ROM image, enabling you to do source-level debugging
of bootstrap code. Click the Browse button to open the
bootrom symbolics file for the ROM image you want to
debug.
If this box is unchecked, you will only be able to do
assembly-level debugging of bootstrap code in the ROM
image.
NOTE: If you want to debug start-up code, you should

select the Debug from start address option so
that the debugger will halt the device once it
establishes a debug session. See“Debug from
start address” for information on that setting.
11.2.6 Remote Connections

The Remote Connections preference panel (shown in Figure 11.5) lets you create and
manage remote connections for use with all CodeWarrior projects.
This Remote Connections panel is always visible in the IDE Preferences window. To
display the IDE Preferences window, select Edit > Preferences from the IDE’s menu
bar.

Kernel Debugging
Target Settings
Each remote connection in this panel contains information necessary to establish a

debugger connection between the host computer and remote devices. The IDE displays
these remote connection entries in the Connection menu in the Remote Debugging target
settings panel (see “Remote Debugging”).
To create a remote connection for kernel debugging:
2. Select Edit > IDE Preferences from the CodeWarrior menu bar.
The IDE displays the IDE Preferences window (Figure 11.6).

Kernel Debugging
Target Settings
Figure 11.6 IDE Preferences Window
3. Select Remote Connections from the IDE Preference Panels list.

The IDE displays the Remote Connections preference panel (Figure 11.7).

Kernel Debugging
Target Settings
4. Click Add.
The IDE displays the New Connection dialog box (Figure 11.8).
Figure 11.8 New Connection Dialog Box
5. In the Name field, type the name for the new connection.
6. If your in-circuit emulator uses the ARM remote debugger interface (RDI):
a. Select ARM RDI from the Debugger dropdown list.
The IDE displays ARM RDI-related settings in the bottom of the New Connection
dialog box (Figure 11.9).

Kernel Debugging
Target Settings
b. Click the Browse button under the Choose an RDI DLL text box.
The IDE displays a standard Windows file selection dialog box.
c. Use this dialog box to select the RDI DLL supplied by the vendor of your in-circuit
emulator.
The IDE displays the path to the selected RDI DLL in the Choose an RDI DLL
field.
NOTE A partially configured ARM RDI remote connection already exists. It is named
Symbian RDI.
If you would like to use this connection instead of creating a new one, finish
setting up the Symbian RDI connection by assigning it the RDI DLL
included with your emulator.
Figure 11.9 New Connection Dialog Box Configured for an ARM RDI ICE
d. Use the RDI Log Level field to define the RDI events you want logged.
See the ARM RDI documentation for more information about this setting.
e. Ensure that all options in the Vector Catch group box are disabled.
f. Click OK.
The IDE saves your configuration. The name of the new ARM RDI connection
appears in the Remote Connections list (Figure 11.10).

Kernel Debugging
Debugging Kernel and Boot-Loaded Device Drivers Example
Figure 11.10 Remote Connections Preference Panel with the New RDI Connection
7. Click OK.
The IDE saves your changes and closes the IDE Preferences window.
You can now use the new remote connection in your projects. For further details about this
preference panel, refer to the CodeWarrior IDE User's Guide.
11.3 Debugging Kernel and Boot-Loaded Device

Drivers Example
This section shows how to create and debug kernel and boot-loaded device drivers on a
Symbian device using the CodeWarrior IDE. In this tutorial, you create a CodeWarrior
project from a devkit example graphicshell project file.
Please complete these sections in order:
1. Importing an MMP Project File
2. Building the Debug Target
3. Build the Driver Into the ROM Image
4. Connect the Target Device to the Host Computer
5. Configure Target Settings
6. Debugging the Project
Importing an MMP Project File

First, import the boot-loaded device driver MMP project file into the IDE:

Kernel Debugging

2. Select File > Import Project From .mmp File from the CodeWarrior menu bar.
The IDE displays the SDK Selection page of the Symbian Importer wizard (Figure
11.11).
Figure 11.11 Symbian Importer - SDK Selection Page
3. Select the vendor whose DevKit you want to use for this project from the Vendor list.
4. Select the DevKit you want to use from the SDK list.
5. Click Next.
The IDE displays the MMP File Selection page of the wizard (Figure 11.12).

Kernel Debugging
Figure 11.12 Symbian Importer - MMP File Selection page
6. Click Browse.
The IDE displays a Select File dialog box (Figure 11.13).
Figure 11.13 Select File dialog box
7. Navigate to SDKRoot\7.0s\Series60_v21_CW\Examples\graphics\
folder (where SDKRoot is the root directory of the SDK you want to use for this
project).
8. Select the graphicshell.mmp file.
9. Click Open.
The wizard displays the path to the file you selected in the MMP File Selection text
field.

Kernel Debugging
10. Enter in the Platform Selection text field the ASSP name corresponding to the target
device (Figure 11.14).
Examples:
• If the target device is the ARM SPP2 Integrator, enter mint
• If the target device is the Texas Instruments Innovator, enter MOMAP15xx
Figure 11.14 Symbian Importer Wizard - SDK Selection Page Completed
11. Click Finish.

The IDE generates a project based on the MMP file and the platform selection settings,
and displays the Project window (Figure 11.15).

Kernel Debugging
Building the Debug Target

Next, build the debug build target in the CodeWarrior project:
1. Select Project > Set Default Target > VIDEODRIVERLDD ASSP Target Name
UDEB from the CodeWarrior menu bar (where ASSP Target Name is a placeholder for
the ASSP name for your target device).
The IDE switches to the debug build target.
2. Select Project > Make from the CodeWarrior menu bar.
The IDE builds the debug version of VIDEODRIVERV1.LDD.
11.3.1 Build the Driver Into the ROM Image

Next, build the debug version of the device driver into the Symbian OS ROM image:
Building the Driver Into the ROM Image

1. Build the Symbian OS ROM image.
2. Ensure that the ROM image contains the debug version of VIDEODRIVERV1.LDD:
a. Open the ROM image log file in a text editor.
b. Locate the VIDEODRIVERV1.LDD entry in the log file.
c. If the log entry shows that VIDEODRIVERV1.LDD is from the release (UREL)
directory, change the appropriate .iby file so that VIDEODRIVERV1.LDD is
taken from the debug directory.
d. Rebuild the ROM image.
11.3.2 Connect the Target Device to the Host Computer

Next, connect the target Symbian device to the host computer:
Connecting the Target Device to the Host Computer

1. Connect your in-circuit emulator to the PC on which you installed CodeWarrior
Development Studio for Symbian OS.
2. Connect your in-circuit emulator to the JTAG port of the target device.
11.3.3 Configure Target Settings

Next, configure the build target settings to debug the Symbian ROM image:

Kernel Debugging
Configuring Target Settings

1. Select Edit > VIDEODRIVERLDD ASSP Target Name UDEB Settings from the
IDE’s menu bar (where ASSP Target Name is a placeholder for the ASSP name for
your target device).
2. Select Remote Debugging in the Target Settings Panels list.


Kernel Debugging
3. Select the appropriate in-circuit emulator

– If your in-circuit emulator uses the ARM remote debugger interface (RDI), select
an RDI remote connection from the Connection dropdown list.
– If you are using an XDS510/XDS560 class in-circuit emulator, select a TI Target
Server remote connection from the Connection dropdown list.
– If you are using the Lauterbach Trace32 Emulator, select ARM Lauterbach
Trace32 remote connection from the Connection dropdown list.
4. Select Symbian ARM Debugger Settings from the Target Settings Panels list.
The IDE displays the Symbian ARM Debugger Settings panel (Figure 11.18).

Kernel Debugging
Figure 11.18 ARM Debugger Settings Panel
5. Set the Target Processor and Target OS options.

a. Select an item representing the type of processor on the target device from the
Target Processor menu.
NOTE If the menu does not contain an item for the target device you want to debug,
select Generic from the Target Processor menu.
b. Select Symbian_EKA1 or Symbian_EKA2 from the Target OS menu.

6. If your target device must be initialized before each debugging session:
a. Check the Use Target Initialization File check box.
The text field and Browse button beneath this check box become enabled.
b. Click Browse
The Choose File dialog box appears.
c. Use the Choose File dialog box to select a file that contains the initialization
commands your target device requires and click Open.
The full path and name of the selected file appears in the text field.
7. Select Symbian Debugging from the Target Settings Panels list.
The IDE displays the Symbian Debugging settings panel (Figure 11.19).

Kernel Debugging
Figure 11.19 Symbian Debugging Settings Panel
8. Set the Symbian Debugging options as follows:

a. Check the Parse ROMBUILD Log File box.
b. Click the top Browse control.
The IDE displays an Open dialog box (Figure 11.20).
Figure 11.20 Open Dialog Box
c. Select the name of the DevKit you want to use for this project from the Path Type
menu (for example, TechView OS7_7.0.15).

Kernel Debugging
d. Select the log file for the ROM image you built earlier in this tutorial.
The log file is located at: SDKRoot\epoc32\rom\LogFileName (where
SDKRoot is the root directory of the DevKit you want to use for this project and
LogFileName is the name of the ROM image log file).
e. Click Open.
The IDE displays the path to the log file you selected.
f. Click the Browse button next to the Symbian OS Kit Epoc32 Directory text field.
The IDE displays the Please Select an Access Path dialog box (Figure 11.21).
Figure 11.21 Please Select an Access Path Dialog Box
g. Select the name of the DevKit you want to use for this project from the Path Type
menu (for example, TechView OS7_7.0.15).
h. Select the epoc32 subdirectory of the SDK you want to use for this project (for
example, SDKRoot\bin\TechView\epoc32).
i. Click OK.
The IDE displays the path to the epoc32 directory you selected in the Symbian
OS Kit Epoc32 Directory text field.
9. Select Symbian Kernel Debugging from the Target Settings Panels list.
The IDE displays the Symbian Kernel Debugging settings panel (Figure 11.19).

Kernel Debugging
10. Set the Symbian Kernel Debugging options as follows:

a. In the Start address text field, enter the address at which the target device starts
executing ROM images.
TIP The Symbian OS documentation lists the correct start address for each supported
device.
b. Select the Run from start address option.

c. Check the Download .img file box.
d. In the Download .img file section, click Browse.
The IDE displays an Open dialog box (Figure 11.23).

Kernel Debugging
Figure 11.23 Open Dialog Box
e. Select the ROM image file you built earlier in this tutorial.
This ROM image file is located here: SDKRoot\epoc32\rom\ (where
SDKRoot is the root directory of the DevKit you want to use for this project).
f. Click Open.
The IDE displays the path to the ROM image file you selected in the Download
.img file text field.
g. In the Download address text field, enter the memory address on the target device
to which the debugger should place the ROM image file.
TIP The Symbian OS documentation lists the correct download address for each
supported device.
h. Check the Ask at start of each debug session box.

11. Click OK.
11.3.4 Debugging Projects
Debugging the Project

Next, start a CodeWarrior debug session:
1. Double-click the VIDEODRIVERLDD.CPP file in the Project window.
The IDE displays the editor window for the file (Figure 11.24).

Kernel Debugging
Figure 11.24 Editor window for VIDEODRIVERLDD.CPP
2. Click in the left column of the editor window adjacent to the first line of code in the
CreateLogicalDevice() function.
The IDE sets a breakpoint for the CreateLogicalDevice() function. A red dot
appears in the left column next to the line with the breakpoint.
3. Select Project > Debug from the IDE’s menu bar.
The Symbian Image Download dialog box appears (Figure 11.25).
Figure 11.25 Symbian Image Download Dialog Box
4. Click OK.
The IDE displays a status dialog box as it downloads the ROM image to target device
(Figure 11.26).

Kernel Debugging
Figure 11.26 Download Status Dialog Box
The device begins execution of the ROM image under control of the CodeWarrior
debugger.
When execution reaches the line of code with the breakpoint, the CodeWarrior
debugger halts the device and displays the Thread window (Figure 11.27).
You can now use the Thread window to start, stop, and step through assembler code on
the device or board.
NOTE During kernel debug sessions, the Kill button in the Thread window does not
kill the process you are debugging. Instead, the debugger continues execution
of the process you were debugging and detaches from the device, and ending
the debug session if it was the only thread open.

Kernel Debugging
Debugging Bare-Board Start-Up Code Example
11.4 Debugging Bare-Board Start-Up Code

Example
This section shows how to use the CodeWarrior debugger to debug startup code on a
device or board before the operating system initialization such as MMU setup and
Symbian debug helpers.
To debug bareboard startup code:
2. Open a CodeWarrior project whose remote debugging connection uses an in-circuit
emulator.
The IDE displays the Project window (Figure 11.28).
(where TargetName is the name of a build target whose remote debugging connection
uses an in-circuit emulator).
The IDE switches to the build target selected.

Kernel Debugging
NOTE If the Symbian Kernel Debugging settings panel is not in the list, ensure that
you have selected a connection that uses an in-circuit emulator from the
Connection menu of the Remote Debugging settings panel.
5. Select Symbian Kernel Debugging from the Target Settings Panels list.
The IDE displays the Symbian Kernel Debugging settings panel (Figure 11.30).

Kernel Debugging
6. Enter in the Start address text field the address at which target device starts executing
ROM images.
7. Select the Debug from start address option to indicate you want the debugger to halt
the device or board before the operating system loads.
8. If the ROM image you want to debug is not already downloaded to the device or
board, configure the debugger to download the ROM image:
a. Check the Download .img file box.
b. Click Browse to display a standard file selection dialog box.
c. Open the ROM image you want to debug.
d. Enter in the Download address text field the download address appropriate for the
target device or board.
9. If you have built a debug version of your start-up code (bootrom.bin),
configure the debugger to let you debug this code:
a. Click Debug Bootrom .sym file.
b. Click Browse to display a standard file selection dialog box.
c. Open your bootrom .sym file.
NOTE Ensure that the selected file was built with symbolics information and included
in the ROM image that was downloaded. For more information on building
bootrom, refer to the DevKit documentation.
10. Click OK.


Kernel Debugging
The IDE builds the target and starts a debug session. If you instructed it to do so, the
debugger downloads the ROM image to the device. Once the ROM image is
downloaded, the debugger halts the device and displays the Thread window (Figure
11.31).
Figure 11.31 Thread Window - Debugging Bareboard Start-up Code
You can now use the Thread window to start, stop, and step through assembler code
on the device or board.
11.5 Attaching to a Process or Thread

The CodeWarrior debugger lets you attach to a running process or thread on the target
device. This section shows you how to use the debugger to connect to running processes
and threads.
Before you continue, make sure that the Symbian OS kernel is booted and running on the
target device.

Kernel Debugging
NOTE The project you use to attach to processes or threads on the device must have
Symbian EKA1 or Symbian EKA2 selected from the Target OS menu in the
Symbian ARM Debugger Settings panel.

2. Open a CodeWarrior project for any Symbian OS executable, application, or library.
The IDE displays the Project window (Figure 11.32).
3. Select Debug > Connect from the CodeWarrior menu bar.

The IDE halts the device and displays a Thread window showing the current stack,
the source code at the current program counter, and the current variables for the
function (Figure 11.33).

Kernel Debugging
4. Select View > Processes from the CodeWarrior menu bar.

Figure 11.34 Processes Window
5. Select Symbian RDI (or whatever protocol you are using) from the menu at the top-
left corner of the Processes window.
The IDE displays all processes running on the target device (Figure 11.35).

Kernel Debugging
Figure 11.35 Processes Window Showing Symbian Processes
6. Select a process from the Process list.

In the Task list, the IDE displays all threads associated with the selected process.
To attach to a process, select a process in the Process list and click the Attach button
( ) in the Processes window. To attach to a thread, select a thread in the Tasks list and
click the Attach button.
When you attach to a process or thread, the CodeWarrior debugger loads symbolic
information (if available) and displays a Thread window (Figure 11.36).

Kernel Debugging
Note that because the target device is halted, the Thread window may display a thread
that is currently inactive. Therefore, you may not be able to use some debugger execution
controls such as Step, Step Over, or Step Into.
If you wish to debug an inactive thread:
1. Add a breakpoint next to the line you want to debug by clicking in the left column of
the Source pane in the Thread window.
2. Click the Run button in the Thread window to continue execution of the device.
When the device executes the line of code containing the breakpoint, the CodeWarrior
debugger halts the device and brings the Thread window to the foreground. At this
point you can use all of the debugger execution controls.
11.6 Opening Symbolic Files and Setting

Breakpoints
The CodeWarrior debugger normally cannot do source-level debugging of executable files
unless you have the associated CodeWarrior project file open in the IDE. This section
shows you how to debug executable files on a target device without having the associated
CodeWarrior project open.
This method of debugging may come in handy in situations where you either do not have
the CodeWarrior project on the host computer or where you do not want to open the
CodeWarrior project on the host computer.

Kernel Debugging
In order to set breakpoints in an executable and debug it with the CodeWarrior debugger,
you must first build a debug version of the executable with symbolics using the
CodeWarrior IDE or command-line. When you do so, the compiler generates a symbolics
file (SYM file) containing all of the symbolic information associated with the executable.
This information enables the CodeWarrior debugger to do source-level debugging with
the executable.
NOTE The rest of this section assumes you already have a SYM file for the executable
you want to debug.
The name of the SYM file is typically the name of the executable plus the .sym file name
extension. The IDE places the file in the same directory as the executable file.
In addition, for breakpoint to work you must have a project open in the IDE that is
configured for stop-mode debugging. It does not have to be the actual CodeWarrior
project used to create the SYM file, any correctly configured project will work.
To insert breakpoints into an executable or debug an executable without having the
associated CodeWarrior project open:
1. Drag the SYM file for the executable and drop it over the IDE icon or the CodeWarrior
IDE’s menu bar.
The IDE displays the Choose Debugger dialog box (Figure 11.37). This dialog box
lists each entry in the Remote Connections settings panel.
Figure 11.37 Choose Debugger dialog box
2. Select the debugger that corresponds to the in-circuit emulator you are using.
NOTE The choices available in the Choose Debugger dialog box will vary based
upon the installed remote connections.
3. Click OK.
The CodeWarrior debugger displays the Symbolics Window (Figure 11.38). Notice
that the Executables pane of the window lists the SYM file for the executable.

Kernel Debugging
Figure 11.38 Symbolics Window
4. Select the SYM file in the Executables pane.

In the Files pane, the IDE displays a list of files associated with the executable.
5. Select one of the files in the Files pane.
In the Functions pane, the IDE displays a list of functions in the file you selected.
6. Select a function from the Functions list.
The IDE displays the source code for the selected function in the Source pane.
7. Add a breakpoint next to the line you want to debug by clicking in the left column of
the Source pane.
NOTE The IDE must have any project open and configured for stop-mode debugging
for breakpoints to work with a SYM file.
8. Click the Run button in the Thread window to continue execution of the device.
When the device executes the line of code containing the breakpoint, the CodeWarrior
debugger halts the device and brings the Thread window to the foreground.
You can now use the Thread window to start, stop, and step through assembler code on
the device or board.

Kernel Debugging
Viewing Processes, Threads, Libraries, and Chunks
11.7 Viewing Processes, Threads, Libraries, and

Chunks
The CodeWarrior debugger lets you view properties of Symbian kernel objects such as
processes, threads, libraries and chunks. This section shows you how to view kernel object
properties during a CodeWarrior debug session.
NOTE You must have met the following condition to view any kernel object
properties:
– Symbian Linker or Symbian Linker v2 is chosen in the Target Settings
panel
– an active debug session
• “Viewing Symbian Processes”

• “Viewing Symbian Threads”
• “Viewing Symbian Libraries”
• “Viewing Symbian Chunks”
11.7.1 Viewing Symbian Processes

To view a list of processes on the Symbian device you are debugging, select
Symbian > Processes from the CodeWarrior menu bar.
Figure 11.39 Symbian Processes Window

Kernel Debugging
For each process on the target device, this window shows you the following information:
• Name
• Process ID
• Priority
• Text size
• Const data size
• Bss size
• Code run address
• Code home address
• Process Threads
• Process Chunks
11.7.2 Viewing Symbian Threads

To view a list of threads on the Symbian device you are debugging, select
Symbian > Threads from the CodeWarrior menu bar.
The IDE displays the Threads window (Figure 11.40).
Figure 11.40 Symbian Threads Window
• Name
• mwThreadID
• Priority
• Status
• Type

Kernel Debugging
• Owning Process
11.7.3 Viewing Symbian Libraries

To view a list of libraries on the Symbian device you are debugging, select
Symbian > Libraries from the CodeWarrior menu bar.
The IDE displays the Libraries window (Figure 11.41).
Figure 11.41 Symbian Libraries Window
For each library on the target device, this window shows you the following information:
• Name
• Code Size
• Data Size
• Constant Data Size
• Bss Size
• Code Address
• Code Load Address
• Data Run Address
• Data Home Address
11.7.4 Viewing Symbian Chunks

To view a list of chunks on the Symbian device you are debugging, select
Symbian > Chunks from the CodeWarrior menu bar.
The IDE displays the Chunks window (Figure 11.42).

Kernel Debugging
Figure 11.42 Symbian Chunks Window
For each chunk on the target device, this window shows you the following information:
• Name
• Size
• Run Address
• Home Address
• Owning Process


Kernel Debugging
Supporting Dynamic Targets (OEM only)
11.9 Supporting Dynamic Targets (OEM only)

The “Symbian ARM Debugger Settings” target settings panel now supports dynamic
targets, enabling you to tell the IDE how to support new releases of both hardware and
operating systems.
Manufacturers have the ability to modify the memory map in Symbian OS to support new
hardware configurations. However, doing so can break the base address values used by the
debugger to locate critical kernel and data structures it needs to interact with both the
Symbian OS and other software during a debugging session. By extracting these critical
values into an XML file, it’s possible to modify the values as required to support the
hardware and software changes and continue development.
Choosing the appropriate Hardware Board, OS Version, and Processor for the target board
in the “Symbian ARM Debugger Settings Panel” target settings panel causes the debugger
to parse the XML file to use the correct values during the debug session.

Kernel Debugging
Figure 11.44 Symbian ARM Debugger Settings Panel
You modify the HardwareConfigurations.xml file to accomodate the changes.

The HardwareConfigurations.xml file is located at:
{CW_Install_Dir}\Bin\Plugins\Support\HardwareDescriptors\
Once you have modified the XML file, you must close and relaunch the IDE or re-open
the project to force the IDE to read the modified XML file.
See Listing 11.1 to see a HardwareConfigurations.xml file example.
Listing 11.1 Symbian_Configuration.xml file example
<hardwaretargets>
<hardwaretarget>
<name>TiH4</name>
<osVersions>
<osVersion>
<osName>v9.1</osName>
<kernelDataAddress>0xC8000000</kernelDataAddress>
<kernelSuperPageBaseAddress>
0xC0000000
</kernelSuperPageBaseAddress>
<ROMLinearBaseAddress>0x80000000</ROMLinearBaseAddress>
<kdebugPointerOffset>0x144</kdebugPointerOffset>
<signatureOffset>0x138</signatureOffset>
<timeOffset>0x80</timeOffset>
</osVersion>

Kernel Debugging
<osVersion>
<osName>v8.1b</osName>
<kernelDataAddress>0xC8000000</kernelDataAddress>
<kernelSuperPageBaseAddress>
0xC0000000
</kernelSuperPageBaseAddress>
<ROMLinearBaseAddress>0x80000000</ROMLinearBaseAddress>
<kdebugPointerOffset>0x144</kdebugPointerOffset>
<signatureOffset>0x7c</signatureOffset>
<timeOffset>0x80</timeOffset>
</osVersion>
</osVersions>
<processors>
<-- Do not modify the processor list for a hardware board -->
<processor>OMAP24xx</processor>
</processors>
</hardwaretarget>
<hardwaretarget>
<-- another hardware target board -->
</hardwaretarget>
<processors>
<processor>Generic</processor>
<processor>ARM920T</processor>
<processor>ARM926TEJ</processor>
<processor>ARM1136J(F)-S</processor>
<processor>OMAP1510</processor>
<processor>OMAP1710</processor>
<processor>XScale</processor>
</processors>
<osVersions>
<osVersion>v7.0-v8.0a</osVersion>
<osVersion>v8.1b</osVersion>
<osVersion>v9.1</osVersion>
</osVersions>
</hardwaretargets>
You can modify or add both the <hardwaretarget> and <osVersion> types
within the XML file to enable kernel-awareness for new or different hardware.

Kernel Debugging
NOTE You should never modify the <processors> or <osVersions> lists to

add a new <processor> or <osVersion>. The debugger cannot display
processor registers it has no knowledge of and attempts to do so can cause
program error. Nor can it interact properly with OS versions when it’s unable
to locate critical data structures vital to communication and interaction.
11.9.1 The “Generic”Target

By default, the debugger includes support for a “Generic” target. Use of the Generic target
enables you to debug software on the device without the benefits of kernel awareness. For
example, you would not be able to view any register data as the debugger would not know
which processor the hardware was using. For that level of kernel awareness you must
choose a specific and supported processor.
NOTE If the Generic target is selected in the “Symbian ARM Debugger Settings
Panel” the debugger sets the Kernel data dependencies in hardware
Descriptors.xml file to the values for Symbian OS 9.1 and the TI H2
board.
11.9.2 Hardware Configuration Fields

The XML fields used by the HWC file are described in Table 11.5.
Table 11.5 Hardware Configuration field descriptions
Field Description
<hardwaretargets>... Describes the start and end sections for defining one or
</hardwaretargets> more <hardwaretarget> entries.
<hardwaretarget>... A hardware target that contains <osVersions> and

</hardwaretarget> <processors> sections.
<osVersions>... Describes the start and end sections for defining one or
</osVersions> more <osVersion> entries.
At the root level of the XML file, it provides the

<osVersion> list that appears in the OS Version drop
down menu.
Within the <hardwaretarget> entry, each

<osVersion> entry it provides mapping information
about the OS used by the debugger.

Kernel Debugging
Table 11.5 Hardware Configuration field descriptions
Field Description
<osVersion>... At the root level, provides the <osVersion> list that

</osVersion> appears in the OS Version drop down menu.
Within the <hardwaretarget> entry, describes a

single OS version containing these entries:
• <osName>
• <kernelDataAddress>
• <kernelSuperPageBaseAddress>
• <ROMLinearBaseAddress>
• <kdebugPointerOffset>
• <signatureOffset>
• <timeOffset>
<osName>... The name of the operating system as it should appear in

</osName> the OS Versions field.
<kernelDataAddress>... Corresponds to the “Kernel data address” entrie in the

</kernelDataAddress> rombuild.log file.
<kernelSuperPageBaseAddress>.. The absolute address of the start of Kernel SuperPage

</kernelSuperPageBaseAddress> (fundamental OS structure) when the OS is loaded and
MMU is initialized.
<ROMLinearBaseAddress>... The absolute address where the Symbian OS image is

</ROMLinearBaseAddress> downloaded onto the target device.
<kdebugPointerOffset>... The offset to the iDebuggerInfo member of Kernel

</kdebugPointerOffset> Superpage.
<signatureOffset>... The offset to the iSignature member of the Kernel

</signatureOffset> Superpage.
<timeOffset>... The offset to the iTime member from

</timeOffset> ROMLinearBaseAddress.
<processors>... Describes the start and end sections for defining one or
</processors> more <processor> entries.
WARNING: Do not modify the <processors> list. The
debugger cannot display processor registers it has no
knowledge of and attempts to do so can cause program
error.
<processor>... A processor name to appear in the Target Processor

</processor> field.

Kernel Debugging
11.9.3 Adding a Hardware Target

You can add a hardware target to the HardwareConfigurations.xml file that is
not currently supported by the CodeWarrior debugger. New hardware targets must use one
of these processor types:
• Generic (ARM processor)
• ARM920T
• ARM926TEJ
• ARM1136J(F)-S
• OMAP3xx
• OMAP1510
• OMAP16xx
• OMAP1710
• OMAP24xx
• XScale
Adding a Hardware Target

To add a hardware target, follow these steps.
WARNING! Always backup the current HardwareConfiguration.xml file

before making any changes.
1. In the IDE, close any open projects.

2. Open the HardwareConfigurations.xml file.
3. Locate the <hardwaretarget> section that most closely matches the new
hardware you want to add.
Choosing a hardware target that closely resembles the target board will minimize the
number of changes you must make to the file.
4. Select and duplicate the <hardwaretarget> section.
5. Rename the duplicate <hardwaretarget> section to identify your board.
NOTE Do not use the name “Generic” as this will cause conflicts with the built-in
default “Generic” configuration.
6. Modify the fields within the duplicate <hardwaretarget> as required to match

the new hardware target settings.

Kernel Debugging
a. Modify the entries within the <osVersions> section to match the OS versions
available to the hardware target.
b. Modify the entries within the <processors> section to list the processors
supported by the hardware target.
NOTE You should never modify the <processors> list to add a new
<processor>. The debugger cannot display processor registers it has no
knowledge of and attempts to do so can cause program error.
7. Save your changes.

8. Repeat steps 1-7 for every hardware board supported by this OS version.
The next time you open the “Symbian ARM Debugger Settings” target settings panel, the
new hardware target appears in the Hardware Board field.
11.9.4 Modifying an OS Version

You can modify the OS version to the HardwareConfigurations.xml file to
support new target hardware. This enables you to develop on new target hardware using
any supported version of the Symbian OS. See “Adding a Hardware Target” for more
information. Only variations of these Symbian OS versions are supported:
• v7.0-v8.1a
• v8.1b
• v9.1
NOTE Attempting to use any unsupported OS version will cause unpredictable

behavior.
Modifying an OS Version
To modify an OS version, follow these steps.
WARNING! Always backup the current HardwareConfiguration.xml file

before making any changes.
1. In the IDE, close any open projects.

2. Open the HardwareConfigurations.xml file.
3. Locate the <hardwaretarget> section for your board.
4. Modify the fields within the appropriate <osVersion> as required so the debugger
can use the OS.
5. Save your changes

Kernel Debugging
The next time you open the “Symbian ARM Debugger Settings” target settings panel, and
choose the new target hardware, only the OS versions you defined for that
<hardwaretarget> appear in the OS Versions field.

12 Kernel Debugging Protocols
The CodeWarrior Development Studio for Symbian OS software lets you debug the kernel
using different debugging protocols. This chapter describes how to set up and use various
debugging protocols.
This chapter contains these sections:
• “Lauterbach”
• “Midas RTE for Win32”
• “Sophia Target Interface”
See the section “Remote Connections Panel” for information on creating remote
connections.
12.1 Lauterbach
The IDE supports the ARM Lauterbach Trace32 debugging protocol.
You must configure the Connection Type setting of the remote connection to use the
Lauterbach Trace32 protocol. Figure 12.1 shows the default configuration when choosing
ARM Lauterbach TRACE32 as the Debugger in the New Connection window. Your
settings may vary depending upon the remote device. Always refer to the device
documentation for connection setting details.
Refer to the section “Remote Connections Panel” for information on creating remote
connections.
For more information, visit www.lauterbach.com.

Kernel Debugging Protocols
Lauterbach
Figure 12.1 Configuring a Lauterbach connection (default settings shown)
Table 12.1 Lauterbach connection window—options
Option Explanation
Trace32 Driver location Specify the path to the Trace32 executable. The default
path assumes that the Trace32 executable is installed in
the default location: C:\T32\T32marm.exe.
Trace32 Configuration File Specify the path to the config.t32 file or other custom
config file. The default path assumes that the Trace32
configuration file is installed in the default location:
C:\T32\config.t32.
You can modify the config.t32 file to support UDP
(User Datagram Protocol) connections by adding the
following lines:
PBI=USB
RCL=NETASSIST
PACKLEN=1024
PORT=20000

Midas RTE for Win32
Table 12.1 Lauterbach connection window—options (continued)
Option Explanation
Boot Configuration File Specify the path to the boot.cmm or t32.cmm

configuration files. Examples of boot configuration files
are located at: <CW_FOLDER>\
Symbian_Support\Lauterbach\
Boot_Configuration\ and include:
• BootIntegrator.cmm – ARM Integrator
board
• BootOMAP1510.cmm – Innovator board
using OMAP1510 CPU
• BootPXA250.cmm – Intel PXA250
(Lubbock)
NOTE: Always make sure the boot configuration file is
appropriate for the chosen target.
UDP Port Sets the port the IDE uses to communicate with Trace32.
It should always match the UDP port setting in the
config.t32 file.
Log Trace32 Communication Controls the logging of communication with Trace32.

Enable to log communications with Trace32 to the
console window.
12.2 Midas RTE for Win32

The IDE supports the Midas Real Time Emulator (RTE) for Win32 debugging protocol.
This enables the IDE to use the Midas JTAG emulator as the hardware debug target. This
section provides information on:
• “Installation Requirements”
• “RTE for Win32 Configuration”
• “Remote Connection Setup”
• “Debugging Preference Settings”
12.2.1 Installation Requirements

You need these components in order to debug software on a target board using the RTE
for Windows debugging protocol:
• Midas RTE for Windows v5.13 or later
• Symbian OS v8.0b (03190_Symbian_OS_v8.1b) or later
• CodeWarrior for Symbian OS 3.0.1 or later
Follow the directions included with the Midas Lab RTE for Windows software to install it
properly.

Midas RTE for Win32
NOTE You must have the RTE for Windows program installed on your PC in order to
debug using the RTE for Windows protocol.
12.2.2 RTE for Win32 Configuration

Once RTE for Windows is installed, configure it for your target board by launching the
Check RTE2 setup program.
Configuring RTE for Win32

1. Connect the target board to the host PC using the RTE-2000-TP box
2. Launch the Start > Program Files > RTE for Windows > Check RTE2 program
3. Select your supported board from the Products list
For example, select the target board OMAP24xx_ARM11-TP from the Products list.
4. Select the connection type from the I/F-1 list
For example, select USB I/F if your RTE-2000-TP box is connected using a USB port.
5. Click License
6. Enter the serial number and RTE for Win32 license key for the target board
7. Click OK
The RTE for Windows dialog appears.
8. Click OK
9. Exit RTE for Windows Check RTE2 application
RTE for Win32 is now ready to communicate with the target board.
12.2.3 Remote Connection Setup

You must create a remote connection configuration that describes how the IDE connects
using the RTE for Win32 protocol. Refer to the section “Remote Connections Panel” for
information on creating remote connections. The default remote connection configuration
for RTE for Win32 is shown in Figure 12.2.
NOTE You will not be able to create a remote connection setting unless the Midas
JTAG emulator is connected to the PC.

Midas RTE for Win32
Figure 12.2 Configuring a Midas RTE for Win32 connection (default settings shown)
Table 12.2 Symbian RDI connection window—options
Option Explanation
Midas RTE for Win32 Specify the path to the RTE for Win32 configuration file
configuration file supplied with the product. Ensure that RTE for Win32 is
installed before selecting a configuration file located at:
<CW_FOLDER>\Symbian_Support\Midas\
Midas_Config_H4.txt\
NOTE: Always make sure the boot configuration file is
appropriate for the chosen target.
Browse Click Browse to choose the configuration file supplied

with RTE for Win32 for the target board. See “Sample
Configuration File” for more details.
RTE message language Specify the language used for RTE messages.
NOTE: Only English messages supported.
Log RTE-2000-TP Enable to log CodeWarrior communicatons with RTE

Communication messages to a console window.
Once you have the RTE for Windows remote connection configured, import a MMP file
in the CodeWarrior IDE and create projects that use this setting.

Midas RTE for Win32
12.2.4 Debugging Preference Settings

To debug using the RTE for Windows debugger protocol, Table 12.3 shows the
configuration settings for several preference panels.
Table 12.3 RTE for Windows debugger preference settings
Preference Panel Configuration
Symbian ARM Debugger Setting • Target Processor: H4 or non-H4 board

NOTE: Selecting Generic for the Target Processor
disables kernel aware debugging as the kernel data
address is unknown.
• Target OS: Symbian EKA2 (Symbian OS
8.1b)
• Use Target Initialization File:
{install_dir}\Symbian_Support
\Initialization_Files\target_
board.cfg
• Reset target at the start of each debug
session: checked
Symbian Debugging • Parse ROMBUILD Log File: checked

• Symbian OS Kit Epoc32 Directory:
{Techview
03190_Symbian_OS_v8.1b}
epoc32
Symbian Kernel Debugging • Start address: 0x80000000

(e.g. OMAP24xx or ARM1136) • Download .img file: checked
({Techview
03190_Symbian_OS_v8.1b}epoc32
\rom\ads_001.techview.img)
• Download address: 0x80000000
• Ask at the start of each debug session:
checked
12.2.5 Sample Configuration File

Listing 12.1 shows an example of a RTE for Windows configuration file for the Freescale
i.MX21ADS.
Listing 12.1 RTE for Windows configuration file example
# Midas RTE for Win32 through command file - i.MX21ADS

#
env jtag12 # set env command

ememstat #
work_addr unused
nc 10000000 4400 # NO CACHE area : i.MX21 internal registers

Sophia Target Interface
accenv jall
accenv jsbp
armopt resetrecovery
armopt !resetautorun
12.3 Sophia Target Interface

The IDE supports the Sophia Target Interface debugging protocol for ARM processors.
This enables the IDE to use the Sophia JTAG emulator as the hardware debug target.
12.3.1 Installation Requirements

You need these components in order to debug software on a target board using the Sophia
Target Interface debugging protocol:
• Install the Watchpoint program appropriate for the hardware board (ARM9 or
ARM11) in order to debug using the Sophia protocol
• Install the Watchpoint Connection tool to enable communication between
Watchpoint and the CodeWarrior debugger
• Install the USB driver for the STI ARM dongle (see STI ARM dongle documentation
for details)
• CodeWarrior for Symbian OS 3.1 or later
12.3.2 Sophia Configuration

Once Watchpoint, the Watchpoint Connection tool, and the USB dongle software are
installed, configure the Sophia connection as follows:.
Configuring a Sophia Connection

1. Create or open a Watchpoint project file
Use Watchpoint to create a new project file or select one of the pre-build Sophia
projects found in the \CW_INSTALL\Symbian_Support\Sophia\ folder.
2. Establish a target connection by using Watchpoint to connect to the target hardware
via the Sophia JTAG emulator
3. In Watchpoint, under the Resources menu, enable the Connection I/F for External
Tools and checkmark the CodeWarrior option setting
4. Click Reset in the Watchpoint window

Sophia Target Interface
5. Create a remote connection for the Sophia Debug protocol

Refer to the section “Remote Connections Panel” for information on creating remote
connections. The default remote connection configuration for Sophia Systems
Debugger is shown in Figure 12.3.
Figure 12.3 Configuring a Sophia connection (default settings shown)
Table 12.4 Sophia connection window—options
Option Explanation
Sophia Target Interface Specify the path to the Sophia Target Interface file
(WTL.dll) location (WTL.dll) supplied with the product.
Log STI Communication Enable to log CodeWarrior communicatons with STI

messages to a console window.

13 RomBuild Support
This chapter describes how to use the CodeWarrior IDE to build Symbian OS images, or
RomBuilds.
There are two methods of creating a Symbian OS image, they are:
• Using the Symbian RomBuild post-linker as part of a CodeWarrior project and
applying the options specified in the “Symbian RomBuild Panel”, or
• Launching the command-line tools directly from a menu item and applying the
options set in the “SymbianRomBuild Window”
Both will result in a valid Symbian OS image.
13.1 Symbian RomBuild Panel

The Symbian RomBuild settings panel contains options that define how the IDE creates
the Symbian OS image as part of the normal build process. This settings panel appears
when Post-Linker > Symbian RomBuild is selected in the Target Settings panel.

RomBuild Support
Symbian RomBuild Panel
Figure 13.1 Symbian RomBuild Panel
Table 13.1 SymbianRomBuild settings panel—options
Option Explanation
RomBuild Command Line Enter the command line that the post-linker uses to
build the ROM image.
Output Location Displays the path where the ROM image is generated
and stored. Click the Browse control to specify a new
location.
Display RomBuild Messages Controls the ability to view all messages generated
during the ROM build process. Enable this option to view
all messages generated by the Rom build command in
the Errors & Warnings window. Note that warning and
error messages are always shown no matter what the
Display RomBuild Messages option state.
Creating RomBuilds within the Build Process

Rom build support is provided as part of the normal build process within the CodeWarrior
IDE as a post-link operation. Each version of the Symbian linker uses a version of the
ROM build post-linker compatible with the chosen linker.
To setup a ROM build within the build process:

RomBuild Support
SymbianRomBuild Window
1. Select Edit > TargetName Settings from the CodeWarrior menu bar
The TargetName Settings window appears.
2. Select the Target Settings panel from the Target Settings Panels list.
The Target Settings panel appears in the TargetName Settings window.
3. Select the Post-Linker > Symbian RomBuild option (Figure 13.2)
Figure 13.2 Selecting the Symbian RomBuild Post-Linker option
4. Click OK
The Symbian RomBuild post-linker is added to the build process and the TargetName
Settings window closes.
5. Select the Symbian RomBuild panel from the Target Settings Panels list.
The Symbian RomBuild panel appears in the TargetName Settings window.
6. Set the Symbian RomBuild post-linker options (Figure 13.1).
7. Click OK.
The Symbian RomBuild options are saved and the Target Settings window closed. The
next time a build is executed, the RomBuild options will be applied as part of the build
process.
13.2 SymbianRomBuild Window

It is also possible to create ROM builds independent of the entire build process normally
envoked by the IDE. You may need to do this if dependent IBY or OBY files are
modified.

RomBuild Support
The SymbianRomBuild window contains options that define how the IDE creates the
Symbian OS image when Project > Symbian Rom Build is selected from the
CodeWarrior menu bar.
Figure 13.3 SymbianRomBuild window
Table 13.2 SymbianRomBuild window—options
Option Explanation
Epoc Root Specifies the path to the selected development kit’s

epoc32 directory.
Rom Build Cmd Line Enter the command line that the tools use to build the
ROM image.
Working Directory Displays the path where the ROM image is generated
and stored. Click the Browse control to specify a new
location.

RomBuild Support
Creating RomBuilds Independent of Build Process

To create an independent ROM build:
1. Select Project > Symbian RomBuild from the CodeWarrior menu bar.
The SymbianRomBuild window appears.
2. Set independent ROM build options in the SymbianRomBuild window.
3. Click OK
The SymbianRomBuild window closes and the ROM build begins.

RomBuild Support

14 Debug Initialization Files
A debug initialization file is used to initialize the target board before the debugger
downloads the code. The main purpose is to ensure that the target memory is initialized
properly before being accessed.
This appendix contains these topics:
• “Using Debug Initialization Files”
• “Debug Initialization File Commands”
14.1 Using Debug Initialization Files

A debug initialization file is a command file processed and executed each time the
debugger is invoked. It is usually necessary to include an initialization file when
debugging via BDM or JTAG to ensure that the target memory is initialized correctly and
that any register values that need to be set for debugging purposes are set correctly. You
specify whether or not to use an initialization file and which file to use in the Symbian
target settings panel.
NOTE You do not need to use an initialization file when debugging with TRK.
Several examples of initialization files are provided in the CodeWarrior installation

directory at:
Symbian_Support\Initialization_Files\
14.2 Debug Initialization File Commands

This section explains debug initialization file commands, including:
• Debug initialization file command syntax
• Descriptions and examples of individual commands
Each section explains these individual command lists:
• The command name
• A brief description of the command

Debug Initialization Files
Debug Initialization File Commands
• Command usage (prototype)

• Command parameters descriptions
• Command examples
• Any important notes about the command
14.2.1 Debug Initialization File Command Syntax

The following list shows the rules for the syntax of debug initialization file commands.
• Any white spaces and tabs characters are ignored.
• Character case is ignored in all commands.
• You can enter a number in hex, octal, or decimal:
– Hex - preceded by 0x (0x00002222 0xA 0xCAfeBeaD)
– Oct - preceded by 0 (0123 0456)
– Dec - starts with 1-9 (12 126 823643)
• Comments start with a “;” or “#”, and continue to the end of the line.
writemem.b
Writes data to a memory location using a byte as the size of the write.
Usage
writemem.b <address> <value>
Parameters
<address>
The hex, octal, or decimal address in memory to modify.
<value>
The hex, octal, or decimal value to write at the address.
Example
writemem.b 0x0001FF00 0xFF # Write 1 byte to memory
writemem.w
Writes data to a memory location using a word as the size of the write.

Usage
writemem.w <address> <value>
Parameters
<address>
<value>
Example
writemem.w 0x0001FF00 0x1234 # Write 2 bytes to memory
writemem.l
Writes data to a memory location using a long as the size of the write.
Usage
writemem.l <address> <value>
Parameters
<address>
<value>
Example
writemem.l 0x00010000 0x00000000 # Write 4 bytes to
memory
writereg
Writes data to the specified register on the target. All register names that are part of
the core processor are supported including GPRs and SPRs.
Usage
writereg <registerName> <value>

Parameters
<registerName>
The name of the register to modify.
<value>
The hex, octal, or decimal value to write at the register.
Example
writereg MSR 0x00001002

Index
Symbols debugging 78, 121
.cwlink descriptor file 47 emulator, running on 78
.def 64, 72 Application Title 31
.exe. See executable file. Application Title option 31
.mcp 17 Application.sis 71
.mmp 17, 59 Arguments option 43
.pch++ extension 46 ARM
.pkg files assembler 73
adding to project 98 compiler 13
creating 95 debugger 13
file mapping 96 linker 13
specification 96 selecting platforms 20, 31
.pref 59, 72 ARM Debugger Settings panel 157
.pref file 24 ARM Lauterbach Trace32
.resources 92 remote connections panel 205
.rss 92, 93 ARM4 platform 40
.s 73 ARMI platform 40
.sis files 71 ARMV5 13, 14
components 98 ARMV5 platform 40
creating 98 Ask at the start of each debug session option 164
setting information 100 assemblers 73
uploading 101 ARM 73
.xml file 24 Intel x86 73
<aif> tag 93 Author option 32
<bmp> 94
<mbm> tag 93, 94 B
<resources> 92 BASEADDRESS 62
<rsc> tag 93, 94 BASEADDRESS file command 62
Binaries option 70
A bitmap 92, 93
actionOverrides link command 50 Bitmap Files list 89, 91
adding bits per pixel 94
hardware target 202 Boot Configuration File option 207
adding .pkg files 98 bootrom.bin 185
Adding .pkg Files to a Project File 98 BPP (Bits Per Pixel) option 89, 91, 94
adding devices 106 breakpoints
Additional Command Line option 44, 69 kernel, setting in 190
addProjectTargetEntry link command 50 setting 129
AIF 92, 93 setting in ROM image 149
AIF Files list 90 temporary 80
application build targets
default 21

C writemem.b 220
Cache symbolics between runs 156 writemem.w 220
Cache symbolics between runs option 78, 113 writereg 221
Choose an RDI DLL option 209 using 219
chunks Debug non-XIP executables option 147
viewing 193 Debugger Settings panel 80, 111, 154
color 94 debuggers
comments 59 ARM 13
COMMON_LINK_OBJ symbol 53 device 109, 205
compile error 59 Intel x86 13
Compiler option 42, 97 debugging
Compiler symbol 52 application 121
compilers device 109, 205
ARM 13 device drivers 169
errors 59 device troubleshooting 142
Intel x86 13 DLL 80, 131
components .sis file 98 emulator 75
Connection option 114, 157 executable file 79
Content Search Location option 72 ROM images 147
Copyright option 32 start-up code 183
Create Files in Default ROOT Directory stop-mode 153
option 22 USB connections 137
Create stub format file option 71 Debugging a Connection 151
creating Debugging a DLL on a Target Device 131
precompiled headers 45 Debugging an Application on a Target
creating .pkg files 95 Device 121
creating .sis Files 98 Debugging an Executable on a Target Device 125
Creating a New Remote Connection for Device DEF_FILE symbol 53
Debugging 118 Default attribute 105
Creating Precompiled Header Projects from deleting devices 106
makmake Projects 46 descriptors, viewing 81, 141, 151, 196
Creating RomBuilds Independent of Build Development Kit EPOCROOT option 45
Process option 217 device
Creating RomBuilds within the Build Process debugging 109, 205
option 214 troubleshooting 142
cw_project_template_v2.xml template 36 device attributes
cw_project_template_v3.xml template 36 Default 105
cw_project_template_v4.xml template 36 Device ID 105
EPOC Root 105
D Name 105
device drivers
Debug Bootrom .sym file option 164
debugging 169
Debug from start address option 162
Device ID attribute 105
debug initialization files
devices
command syntax 220
adding 106
commands
editing 107

remote connection 138 link descriptor XML files 47–54
removing 106 target settings 40–45
USB connection 138 Ekern.exe 149
devices.xml file 65, 103, 104, 106, 107 Embedded-Application Binary Interface 11
DevKit emulator
choosing automatically 65 application, running on 78
documentation 11 debugging 75
overview 12 DLL, running on 80
version 13 executable file, running on 79
Display generated commands in the message Enable SWIC option 43
window option 45, 69 Epoc Kernel Architecture 11
Display RomBuild Messages option 214 EPOC Root attribute 105
DLL Epoc Root option 216
debugging 80, 131 EPOC32
emulator, running on 80 location of build tools 67
exported symbols 72 Epoc32 Tools Location option 68
exporting 72 EPOCALLOWDLLDATA file command 62
parsers 54–56 EPOCCALLDLLENTRYPOINTS file
dlltool 64 command 63
documentation EPOCDATALINKADDRESS file command 63
on CD 10 EPOCFIXEDPROCESS file command 63
Download .img File option 163 EPOCHEAPSIZE file command 63
Download address option 163 EPOCPROCESSPRIORITY file command 63
downloading EPOCSTACKSIZE file command 63
configuring 115 error 59
Dynamic Link Library. See DLL. Euser.dll 149
dynamic targets, supporting 10, 197 executable file
debugging 79
E emulator, running on 79
E2Main() 80 EXPORTS 72
E32Main() 80 EXPORTUNFROZEN file command 63, 72
EABI 11 Extension option 97
Edit Connection option 114, 157
Edit Language option 97 F
editing devices 107 features
EKA1 11 new 9
EKA1 tools 57–73 fields, hardware configuration 200
assembler 73 file commands
building resources 91–94 BASEADDRESS 62
creating projects 57 EPOCCALLDLLENTRYPOINTS 63
exporting DLLs 72 EPOCCALLOWDLLDATA 62
target settings 58–72 EPOCDATALINKADDRESS 63
EKA2 11 EPOCFIXEDPROCESS 63
EKA2 tools 39–56 EPOCHEAPSIZE 63
creating projects 39–40, ??–40 EPOCPROCESSPRIORITY 63
DLL parsers 54–56 EPOCSTACKSIZE 63

EXPORTUNFROZEN 63 Importing
LINKAS 64 .mmp files 18
TARGET 60 Intel x86
TARGETTYPE 60 assembler 73
UID 62 compiler 13
File List option 116 debugger 13
file mapping .pkg files 96 linker 13
File Type option 97
FIRST_LIB symbol 53 J
firstLibProcessing link command 51 JTAG 173
Flags option 97
folder. See directory. K
kernel
G breakpoints 190
GCC 13 Killing a Process 150
Generate Header option 88, 89 KIT_EPOCROOT symbol 54
Generate Platform Security Application (Convert
APP to EXE) option 30 L
Generate symbolics option 69 language id 94
GNU language id tag 94
build tools 13 Languages option 87
location of build tools 67 Launch remote host application option 115, 157
Gnu Tools Location option 68 libraries
viewing 193
H Library 78
hardware configuration fields 200 Library Targeting option 78, 155
Hardware Target, adding 202 LIBS symbol 53
HardwareConfigurations.xml LIBS_NO_PATH_VTBLEXPORT symbol 54
file 198, 202, 203 link command symbols
header files COMMON_LINK_OBJ 53
extension 46 Compiler 52
precompiling 46 DEF_FILE 53
Header Files option 70 FIRST_LIB 53
header tag 94 IMPORT_LIBRARY 53
Host Application for Libraries & Code Resources IMPORT_LIBRARY_NO_EXT 53
option 76, 111 KIT_EPOCROOT 54
Host File Path option 116 LIBS 53
LIBS_NO_PATH_VTBLEXPORT 54
I LINK_OBJ 54
images, ROM 147 LINK_OBJS_NO_PATH 54
Import Library Location option 69 output 52
Import Project From .mmp File 17 output.file.extension 52
IMPORT_LIBRARY symbol 53 output.file.name 52
IMPORT_LIBRARY_NO_EXT symbol 53 output.file.root 52
Importer Library option 44 Plugins 52

project 53 starting 109
source.name.double_delimiter 53 MMP 11
System 53 modifying
target.data 53 OS version 203
link commands Motorola 12
actionOverrides 50
addProjectTargetEntry 50 N
firstLibProcessing 51 Name attribute 105
linkCommand 51 new features 9
linkInformation 51 NewApplication() 61
linkWarning 51 Nokia 12
outputParser 51
parseID 51 O
parseStdErr 51 OS Version
parseStdOut 51 modifying 203
postActionIdentifiers 51 Output Directory option 67
preActionIdentifiers 51 Output File option 44
link descriptor XML files 47–54 Output Filename option 71
LINK_OBJ symbol 54 Output Location option 72, 214
LINK_OBJS_NO_PATH symbol 54 Output Path option 89
LINKAS file command 64 output symbol 52
linkCommand link command 51 output.file.extension symbol 52
Linker option 66 output.file.name symbol 52
Linker setting 87 output.file.root symbol 52
linkers outputParser link command 51
ARM 13
Intel x86 13
P
Symbian OS v6.1 58
Parse ROMBUILD Log File option 146
Symbian OS v7.0 58
parserID link command 51
Symbian OS v8.0 58
parseStdErr link command 51
linkInformation link command 51
parseStdOut link command 51
linkWarning link command 51
Password option 71
Log Trace32 Communication option 207
petran 63
Log unresolved .sym files option 147
platform security 30
Log unresolved modules option 146
Platform Selection option 31
M platforms
ARM4 40
Macros option 43 ARMI 40
make files 17, 57 ARMV5 40
Makefile 17, 57 selecting 20, 31
makesis (Installation File Generator) 95 THUMB 40
makmake 17, 20, 24, 31 WINSCW 40
makmake project file 11 Plugins symbol 52
MBM Output Files option 89 postActionIdentifiers link command 51
MetroTRK Post-linker option 67
device, using with 109

post-linker, Symbian Installer 99 requirements, system 10
preActionIdentifiers link command 51 Reset Target at the Start of each Debug Session
precompile, header files 46 option 160
Precompiled headers, creating 45 resource file 92, 93
preference file 59 resources
preferences Symbian OS v7.0 91–94
Remote Connections 117, 164 Resources list 87
See also settings. Resuming a Thread 150
Source Trees 64 ROM
Prefix File option 42, 69 breakpoints 149
Pre-linker option 66 debugging 147
processes troubleshooting 152
attaching to 150, 186 RomBuild Command Line option 214, 216
viewing 139, 193 Run from start address option 163
Processes command 80 Runtime Settings panel 76, 110
processes, viewing 139 RVCT definition 11
Program Arguments option 77, 111 RVCT support 13, 14, 40
project 24
create 26 S
Project Definition File (.mmp) Location Save project entries using relative paths option 67
option 70 SDK
project file 17, 59 choosing automatically 65
Project Re-import Settings window 35 documentation 11
project support package 26 overview 12
project symbol 53 version 13
projectuid.cpp file 24 selecting platforms 20, 31
serial connection
Q USB 137
Quick Start 11 Setting .sis File Information 100
Setting a Post-Linker 99
R settings
RDI 11 ARM Debugger Settings 157
RealView Compiler Tools (RVCT) 11 Debugger Settings 80, 111, 154
remote connection Remote Debugging 156
devices 138 Remote Download 115
Sony Ericsson P800 138 Runtime Settings 76, 110
Remote Connections panel 117, 164 See also preferences.
remote connections panel Symbian Common 45
ARM Lauterbach Trace32 205 Symbian Compiler 41
Remote Debug Interface 11 Symbian Debugging 145, 161
Remote Debugging panel 156 Symbian Installation 71
Remote Download panel 115 Symbian Kernel Debugging 161
Remote download path option 115, 157 Symbian Linker 43
requirements Symbian Resources 70, 94
version 13 Symbian Target 68
Symbian Tools 67

Target Settings 65 building resources 91–94
Sony Ericsson P800 creating projects 57
remote connection 138 exporting DLLs 72
USB connection 138 target settings 58–72
Sony-Ericsson 12 Symbian OS v8.0 linker 58
Source File option 90 Symbian OS v8.0 tools 39–56
Source Path option 87, 89, 90, 91 creating projects 39–40, ??–40
Source Trees DLL parsers 54–56
panel 64 link descriptor XML files 47–54
source.name.double_delimiter symbol 53 target settings 40–45
sourcefile tag 93 Symbian Preference File
sourcepath tag 94 format 59
Specify alternate ‘makmake’ name option 22 syntax 59
stack 152 usage 59
Start address option 162 Symbian Resources panel 70, 94
start-up code Symbian Target 68
debugging 183 Symbian Target panel 68
stationery 24 Symbian Tools panel 67
stepping 152 symbols
Stop on application launch option 78, 112 DLL, exporting from 72
stop-mode debugging 153 system requirements 10
support package, projects 26 System symbol 53
Suppress warning messages option 69
Symbian Common panel 45 T
Symbian Compiler panel 41 TARGET 60
Symbian Compiler v2 41, 45 Target Architecture option 69
Symbian Debugging panel 145, 161 TARGET file command 60
Symbian Developer Library, Symbian Target File Path option 116
documentation 95 target name 24
Symbian Environments Editor 103 Target Name option 66
Symbian Environments Editor window 104 Target Path option 87, 89, 91
Symbian Environments window 103 Target Processor option 159
Symbian Installation panel 71, 100 target settings 59
Symbian Installer post-linker 99 Target Settings panel 65
Symbian Kernel Debugging panel 161 target settings Symbian OS v7.0 58–72
Symbian Linker 11, 58 target type 24
Symbian Linker panel 43 target.data symbol 53
Symbian Linker v2 11, 43, 58 targets, dynamic 10, 197
Symbian OS TARGETTYPE 60
descriptors 81, 141, 151, 196 TARGETTYPE file command 60
kernel 153 TdesC 81, 142, 151, 196
what is 12 templates
Symbian OS Kit Epoc32 Directory option 146 cw_project_template_v2.xml 36
Symbian OS v7.0 linker 58 cw_project_template_v3.xml 36
Symbian OS v7.0 tools 57–73 cw_project_template_v4.xml 36
assembler 73 threads

attaching to 186 Windows CodeWarrior 12
viewing 193 WINSCW 12, 46
THUMB platform 40 WINSCW platform 40
Trace32 Configuration File option 206 Working Directory option 77
Trace32 Driver location option 206 writemem.b 220
TRK 11 writemem.w 220
troubleshooting writereg 221
device debugging 142
ROM images 152 X
Turn on CodeTEST Instrumenter option 43 xml 92
XML Schema Definition 12
U XSD 12
UDEB 12, 21
UDP 12
UDP Port option 207
UID 24, 62
UID file command 62
UIDs list option 88
Unicode debug 12
Unicode release 12
Unicode UID option 31
Update data every n seconds 156
Update data every n seconds option 78, 113
uploading .sis files 101
Upoading .sis files 101
UREL 12, 21
USB connection
devices 138
Sony Ericsson P800 138
USB, debugging with 137
Use Memory Configuration File option 160
Use Target Initialization File option 159
User Datagram Protocol 12
V
Validating the File Mapping 96
View menu 80
Viewing Processes 139
W
window
Project Re-import Settings 35
windows
Symbian Environments 103
Symbian Environments Editor 104

CodeWarrior For Symbian OS

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CodeWarrior For Symbian OS

Uploaded by

Copyright:

Available Formats

CodeWarrior ™ Development Studio

2 Creating Symbian OS Projects 17

3 Symbian OS v8.x or v9.x Build Tools Guide 39

CodeWarrior for Symbian OS 3

3.2 Target Settings for Symbian OS v8 or v9 Projects. . . . . . . . . . . . . . . . . . . .40

4 Symbian OS v7 Build Tools Guide 57

4 CodeWarrior for Symbian OS

5.2 Debugging an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

6 Resource Editor and Resources 85

8 Symbian Environment Editor 103

CodeWarrior for Symbian OS 5

9 Device Debugging 109

10 Device Debugging in ROM 145

11 Kernel Debugging 153

6 CodeWarrior for Symbian OS

11.2.5 Symbian Kernel Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

12 Kernel Debugging Protocols 205

13 RomBuild Support 213

CodeWarrior for Symbian OS 7

13.2 SymbianRomBuild Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215

14 Debug Initialization Files 219

8 CodeWarrior for Symbian OS

1.1 What is New

CodeWarrior for Symbian OS 9

1.2 System Requirements

Edition of Support Package

Personal An SDK only (not included) Targets: Series 60, UIQ

Professional An SDK or OS devkit, v7.0s or Targets: Series 60, TechView, UIQ

OEM An OS devkit v7.0s or higher Targets: TechView, UIQ SDK

1.3.1 For everyone

10 CodeWarrior for Symbian OS

1.3.2 If you are new to CodeWarrior IDE

1.3.3 For information on the Symbian operating system

Glossary Term Description

ABIv1 ABI for ARM Architecture v1.0

ABIv2 ABI for ARM Architecture v2.0

EABI Embedded-Application Binary Interface

EKA1 EPOC Kernel Architecture supporting Symbian OS v6.1, v7.0,

EKA2 Epoc Kernel Architecture supporting Symbian OS v8.xb and

GCC-E GNU Compiler Collection for EABI (ABIv2)

MMP makmake project file

RDI Remote Debug Interface

RVCT RealView Compiler Tools

Symbian Linker CodeWarrior linker used when creating EKA1 projects

Symbian Linker v2 CodeWarrior linker used when creating EKA2 projects

TRK Target Resident Kernel (formerly MetroTRK)

CodeWarrior for Symbian OS 11

Table 1.2 Symbian OS glossary

Glossary Term Description

UDEB Unicode Debug

UDP User Datagram Protocol

UREL Unicode Release

WINSCW Windows CodeWarrior

XSD XML Schema Definition

1.5 Features Overview

NOTE Access to a specific feature is controlled by the version of the CodeWarrior

1.5.1 SDKs and Development Kits

12 CodeWarrior for Symbian OS

1.5.2 Builds Tools

NOTE You can download GCC-E from www.codesourcery.com/

1.5.3 Emulation Debugging

1.5.4 Device Debugging

CodeWarrior for Symbian OS 13