dsPIC IAR Embedded Workbench™ IDE User Guide
for Microchip’s dsPIC Microcontroller Family
UDSPIC-1
COPYRIGHT NOTICE © Copyright 2002 IAR Systems. All rights reserved. No part of this document may be reproduced without the prior written consent of IAR Systems. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license.
DISCLAIMER The information in this document is subject to change without notice and does not represent a commitment on any part of IAR Systems. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions. In no event shall IAR Systems, its employees, its contractors, or the authors of this document be liable for special, direct, indirect, or consequential damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind.
TRADEMARKS IAR, IAR Embedded Workbench, IAR XLINK Linker, IAR XAR Library Builder, IAR XLIB Librarian, IAR MakeApp, and IAR PreQual are trademarks owned by IAR Systems. C-SPY is a trademark registered in Sweden by IAR Systems. IAR visualSTATE is a registered trademark owned by IAR Systems. dsPIC and Microchip are registered trademarks of Microchip Technology Inc. Microsoft and Windows are registered trademarks of Microsoft Corporation. Adobe and Acrobat Reader are registered trademarks of Adobe Systems Incorporated. CodeWright is a registered trademark of Starbase Corporation. All other product names are trademarks or registered trademarks of their respective owners.
EDITION NOTICE First edition: March 2002 Part number: UDSPIC-1
UDSPIC-1
Contents Tables .................................................................................................................................... xv Figures ................................................................................................................................ xvii Preface .............................................................................................................................. xxiii Who should read this guide ..................................................................... xxiii How to use this guide ................................................................................... xxiii What this guide contains ........................................................................... xxiv Document conventions ................................................................................ xxv
Part 1. The IAR development tools Product overview
....................................1
..................................................................................................... 3
The IAR Embedded Workbench IDE .....................................................3 An extensible and modular environment ....................................................3 Features ..............................................................................................................4 Documentation ..................................................................................................4
IAR C-SPY Debugger .........................................................................................5 Single stepping on function call level ..........................................................5 Backtracing ........................................................................................................5 Debugging in the source window .................................................................5 Disassembly debugging ..................................................................................5 Features ..............................................................................................................6 Versions ..............................................................................................................7 Documentation ..................................................................................................7
IAR C/EC++ Compiler .......................................................................................8 Compiler extensions ........................................................................................8 Embedded C++ .................................................................................................8 Code generation ................................................................................................9 Runtime libraries ..............................................................................................9
iii
UDSPIC-1
Documentation ..................................................................................................9
IAR Assembler ..................................................................................................... 10 Features ........................................................................................................... 10 Documentation ............................................................................................... 10
IAR XLINK Linker ............................................................................................. 10 Features ........................................................................................................... 11 Documentation ............................................................................................... 11
IAR XLIB Librarian ........................................................................................... 11 Features ........................................................................................................... 12 Documentation ............................................................................................... 12
Product configuration
....................................................................................... 13
Included in this package ................................................................................. 13 Running the IAR Embedded Workbench ......................................... 13 Directory structure ........................................................................................... 13 Root directory ................................................................................................ 14 The common\bin directory ......................................................................... 14 The common\doc directory ........................................................................ 14 The common\src directory ......................................................................... 14 The dspic\bin directory ................................................................................ 15 The dspic\config directory .......................................................................... 15 The dspic\doc directory ............................................................................... 15 The dspic\inc directory ................................................................................ 15 The dspic\layouts directory ......................................................................... 15 The dspic\lib directory ................................................................................. 15 The dspic\settings directory ....................................................................... 15 The dspic\src directory ................................................................................ 16 The dspic\tutor directory ............................................................................ 16
File types ................................................................................................................... 16 Documentation .................................................................................................... 17 The user and reference guides .................................................................... 17 Online help and documentation ................................................................. 19 IAR on the web .............................................................................................. 19
dsPIC IAR Embedded Workbench™ IDE
iv User Guide
UDSPIC-1
The project model
................................................................................................ 21
Developing projects .......................................................................................... 21 How projects are organized ........................................................................ 21 Setting options ............................................................................................... 22 Building a project .......................................................................................... 23 Testing the code ............................................................................................. 23 Sample applications ...................................................................................... 24
Part 2. Tutorials
................................................................................................ 27
IAR Embedded Workbench IDE tutorial
................................. 29
Using the IAR Embedded Workbench IDE ..................................... 29 Creating a new project ................................................................................. 29 Adding files to the project ........................................................................... 30 Setting project options ................................................................................. 32 Compiling the source files .......................................................................... 33 Viewing the list file ...................................................................................... 34 Linking the program ..................................................................................... 39 Running the program ................................................................................... 41 Inspecting variables ...................................................................................... 43 Setting breakpoints ....................................................................................... 45 Continuing execution ................................................................................... 47
Compiler tutorials ................................................................................................. 49 Using interrupts, breakpoints, and macros ..................................... 49 The tutor2.mac macro file ........................................................................... 49 Compiling and linking the tutor2.c program ........................................... 53 Running the tutor2.c program .................................................................... 54 Displaying function calls ............................................................................. 57
Using Embedded C++ ...................................................................................... 58 Compiling and linking the tutor3.cpp program ...................................... 58 Setting a breakpoint and executing to it ................................................... 59 Looking at the function calls ...................................................................... 61 Printing the Fibonacci numbers ................................................................. 62
v
UDSPIC-1
Assembler tutorials .............................................................................................. 63 Creating and running an assembler project .................................... 63 Creating a new project ................................................................................. 63 Assembling the program .............................................................................. 63 Viewing the first.lst list file ........................................................................ 65 Linking the program ..................................................................................... 67 Running the program .................................................................................... 69
Working with library modules .................................................................. 70 Using libraries ................................................................................................ 70 Creating a new project ................................................................................. 71 Using the IAR XLIB Librarian .................................................................. 71 Using the library in the project ................................................................... 73
Advanced tutorials
................................................................................................ 75
Using complex breakpoints ........................................................................ 75 Setting up the project .................................................................................... 75 Defining a complex breakpoint .................................................................. 76 Executing the program ................................................................................. 77 Displaying function calls ............................................................................. 79
Debugging in disassembly mode ............................................................ 80 Monitoring memory ...................................................................................... 80 Monitoring registers ..................................................................................... 81
Creating a combined C and assembler project ............................ 82
Part 3. The IAR Embedded Workbench IDE General options
..... 85
....................................................................................................... 87
Setting general options .................................................................................. 87 Target ......................................................................................................................... 88 Processor variant ........................................................................................... 88 Runtime library .............................................................................................. 88 Float size ......................................................................................................... 88 Data model ...................................................................................................... 88
dsPIC IAR Embedded Workbench™ IDE
vi User Guide
UDSPIC-1
Output directories ............................................................................................. 89
Compiler options
................................................................................................... 91
Setting compiler options .............................................................................. 91 Language .................................................................................................................. 92 Enable Embedded C++ syntax ................................................................... 92 Enable language extensions ........................................................................ 92 Treat ‘char’ as ‘signed char’ ....................................................................... 93
Code ............................................................................................................................ 93 Optimizations ................................................................................................. 93 Enabled transformations .............................................................................. 94
Output ........................................................................................................................ 96 Make library module .................................................................................... 96 Object module name ..................................................................................... 96 Generate debug information ....................................................................... 97
List ................................................................................................................................ 97 Preprocessor ........................................................................................................ 98 Include paths .................................................................................................. 98 Defined symbols ............................................................................................ 98 Preprocessor output to file .......................................................................... 99
Diagnostics .............................................................................................................. 99 Enable remarks ............................................................................................ 100 Suppress these diagnostics ........................................................................ 100 Treat these as remarks ................................................................................ 100 Treat these as warnings .............................................................................. 100 Treat these as errors ................................................................................... 100 Treat all warnings as errors ....................................................................... 100
Assembler options
.............................................................................................. 101
Setting assembler options .......................................................................... 101 Language ................................................................................................................ 102 User symbols are case sensitive ............................................................... 102 Allow mnemonics in first column ........................................................... 102 Allow directives in first column .............................................................. 102 Macro quote characters .............................................................................. 102
vii
UDSPIC-1
Output ...................................................................................................................... 103 Make library module .................................................................................. 103 Object module name ................................................................................... 104 Generate debug information ..................................................................... 104
List .............................................................................................................................. 104 Output list file .............................................................................................. 105
Preprocessor ........................................................................................................ 105 Include paths ............................................................................................... 105 Defined symbols .......................................................................................... 106 Preprocessor output to file ........................................................................ 106
Diagnostics ............................................................................................................ 107 Enable remarks ............................................................................................ 107 Treat all warnings as errors ....................................................................... 107 Suppress these diagnostics ........................................................................ 107 Treat these as remarks ................................................................................ 108 Treat these as warnings .............................................................................. 108 Treat these as errors ................................................................................... 108
XLINK options
........................................................................................................ 109
Setting XLINK options ................................................................................. 109 Output ...................................................................................................................... 110 Output file .................................................................................................... 110 Format ............................................................................................................ 110
#define ...................................................................................................................... 112 Define symbol ............................................................................................. 112
Diagnostics ............................................................................................................ 113 Always generate output ............................................................................. 113 Segment overlap warnings ........................................................................ 113 No global type checking ............................................................................ 113 Range checks ................................................................................................ 114 Warnings/Errors .......................................................................................... 114
List .............................................................................................................................. 115 Generate linker listing ................................................................................ 115
dsPIC IAR Embedded Workbench™ IDE
viii User Guide
UDSPIC-1
Include ...................................................................................................................... 116 Include paths ................................................................................................ 116 Library ........................................................................................................... 116 XCL filename ............................................................................................. 117
Input ...........................................................................................................................117 Module status ............................................................................................... 117
Processing .............................................................................................................. 119 Fill unused code memory .......................................................................... 119
C-SPY options
.......................................................................................................... 121
Setting C-SPY options .................................................................................. 121 C-SPY Settings ................................................................................................... 122 Driver ............................................................................................................. 122 Run to ........................................................................................................... 122 Setup file ....................................................................................................... 123 Device description file ............................................................................... 123
IAR Embedded Workbench IDE reference
........................... 125
The IAR Embedded Workbench IDE window ............................. 125 Menu bar ....................................................................................................... 126 Toolbar .......................................................................................................... 126 Project window ............................................................................................ 127 Editor window ............................................................................................. 129 Status bar ....................................................................................................... 133 Messages window ....................................................................................... 133
File menu ................................................................................................................ 134 New ................................................................................................................ 135 Open ............................................................................................................... 136 Close .............................................................................................................. 136 Open Project ................................................................................................. 136 Save Project .................................................................................................. 137 Close Project ............................................................................................... 137 Save ................................................................................................................ 137 Save As .......................................................................................................... 137 Save All ......................................................................................................... 137
ix
UDSPIC-1
Page Setup .................................................................................................... 137 Print ................................................................................................................ 137 Recent Files ................................................................................................. 137 Recent Projects ........................................................................................... 137 Exit ................................................................................................................. 138
Edit menu ............................................................................................................... 138 Undo ............................................................................................................... 138 Redo ............................................................................................................... 138 Cut, Copy, Paste ......................................................................................... 139 Paste Special ............................................................................................... 139 Select All ..................................................................................................... 139 Find ................................................................................................................ 139 Replace .......................................................................................................... 139 Find in Files .................................................................................................. 140 Go to .............................................................................................................. 142 Toggle Bookmark ...................................................................................... 142 Go to Bookmark ......................................................................................... 142 Complete ...................................................................................................... 143 Match Brackets ............................................................................................ 143 Next Error/Tag ............................................................................................. 143 Toggle Breakpoint ..................................................................................... 143 Enable/Disable Breakpoint ...................................................................... 143 Breakpoints ................................................................................................... 143
View menu ............................................................................................................ 144 Messages ....................................................................................................... 144 Toolbars ......................................................................................................... 144 Status bar ....................................................................................................... 144 Debugger Windows ................................................................................... 144
Project menu ....................................................................................................... 145 Files ................................................................................................................ 145 New Group ................................................................................................... 146 Targets ........................................................................................................... 147 Options .......................................................................................................... 148 Compile ......................................................................................................... 149
dsPIC IAR Embedded Workbench™ IDE
x User Guide
UDSPIC-1
Make .............................................................................................................. 149 Link ................................................................................................................ 149 Build All ........................................................................................................ 149 Stop Build ..................................................................................................... 149 Debugger ....................................................................................................... 149
Tools menu ........................................................................................................... 150 Options .......................................................................................................... 150 Configure Tools ........................................................................................... 160
Window menu .................................................................................................... 163 New Window ............................................................................................... 163 Split ................................................................................................................ 163 Close ............................................................................................................. 163 Close All ...................................................................................................... 163 Cascade, Tile Horizontally, Tile Vertically ......................................... 163 Next ............................................................................................................... 164 Previous ........................................................................................................ 164
Help menu ............................................................................................................. 164 Help ................................................................................................................ 164 Embedded Workbench Guide ................................................................. 164 Assembler Reference Guide .................................................................... 164 C/EC++ Compiler Reference Guide ...................................................... 164 XLINK and XLIB Reference Guide ...................................................... 165 ANSI C/EC++ Library Reference .......................................................... 165 IAR on the web ............................................................................................ 165 About ............................................................................................................. 165
Introduction to the IAR C-SPY Debugger
............................. 167
Disassembly and source debugging .................................................... 167 Projects built outside of the Embedded Workbench ........................... 167
Program execution ......................................................................................... 168 Go ................................................................................................................... 168 Stepping ......................................................................................................... 168 Breakpoints ................................................................................................... 169 Interrupt simulation .................................................................................... 169
xi
UDSPIC-1
C function information ............................................................................... 170 Viewing and editing memory and registers ........................................... 170 Terminal I/O ................................................................................................. 170 Macro language ........................................................................................... 170
C-SPY expressions .............................................................................................. 171 Expression syntax ............................................................................................. 171 C symbols ..................................................................................................... 171 Assembler symbols ..................................................................................... 171
C-SPY macros
.......................................................................................................... 173
Using C-SPY macros ...................................................................................... 173 Macro variables ........................................................................................... 174 Macro functions ........................................................................................... 174 Macro statements ........................................................................................ 175
C-SPY setup macros ...................................................................................... 177 Descriptions of C-SPY system macros ............................................. 177
C-SPY Debugger reference
...................................................................... 193
The C-SPY windows ....................................................................................... 193 Types of C-SPY windows ......................................................................... 194 Using layouts ................................................................................................ 194 Editing in C-SPY windows ....................................................................... 194 Menus ............................................................................................................ 195 Debug toolbar .............................................................................................. 195 Disassembly window .................................................................................. 195 Memory window ......................................................................................... 198 Register window .......................................................................................... 200 Watch window ............................................................................................. 201 Locals window ............................................................................................. 202 Call Stack window ...................................................................................... 203 Log window .................................................................................................. 203 Terminal I/O window ................................................................................. 204 Code Coverage window ............................................................................. 205 Profiling window ......................................................................................... 207
dsPIC IAR Embedded Workbench™ IDE
xii User Guide
UDSPIC-1
Debug menu ......................................................................................................... 210 Go ................................................................................................................... 210 Break .............................................................................................................. 210 Reset ............................................................................................................... 210 Stop Debugging .......................................................................................... 210 Step Over ..................................................................................................... 211 Step Into ........................................................................................................ 211 Step Out ......................................................................................................... 211 Next Statement ........................................................................................... 211 Run To Cursor ............................................................................................. 211 Quick Watch ............................................................................................... 211 Refresh ........................................................................................................... 212 Set Next Statement ..................................................................................... 212 Macros ........................................................................................................... 213 Logging > Set Log File .............................................................................. 214 Logging > Set Terminal IO Log File ...................................................... 214 Load Layout ................................................................................................. 215 Save Layout As ............................................................................................ 215 Load Default Layout .................................................................................. 215 Save Current Layout As Default .............................................................. 215
Simulator menu ................................................................................................ 215 Interrupts ....................................................................................................... 215 Memory map ................................................................................................ 218
Editing Breakpoints ........................................................................................ 220
Glossary .......................................................................................................................... 225 Index .................................................................................................................................... 237
xiii
UDSPIC-1
dsPIC IAR Embedded Workbench™ IDE
xiv User Guide
UDSPIC-1
Tables 1: Typographic conventions used in this guide ..................................................... xxv 2: File types ............................................................................................................. 16 3: Target settings for project1 ................................................................................. 32 4: Compiler options for project1 ............................................................................. 33 5: Tutorial 1 XLINK options ................................................................................... 39 6: Project options for Embedded C++ tutorial ........................................................ 58 7: Tutorial 4 assembler options ............................................................................... 64 8: Symbol and cross-reference table ....................................................................... 67 9: Tutorial 4 XLINK options ................................................................................... 68 10: Tutorial 5 XLINK options ................................................................................. 71 11: XLIB FETCH-MODULES parameters ............................................................ 72 12: XLIB LIST-MODULES parameters ................................................................. 73 13: Changing XLINK options ................................................................................. 73 14: Project options for project6 ............................................................................... 75 15: Compiler options for modified project6 ............................................................ 82 16: Compiler optimization levels ............................................................................ 94 17: Compiler list file options ................................................................................... 97 18: Assembler list file options ............................................................................... 105 19: XLINK range check options ........................................................................... 114 20: XLINK list file options ................................................................................... 115 21: XLINK checksum algorithms ......................................................................... 120 22: C-SPY driver options ...................................................................................... 122 23: IAR Embedded Workbench IDE menu bar .................................................... 126 24: Editor keyboard commands for insertion point navigation ............................. 131 25: Editor keyboard commands for scrolling ........................................................ 131 26: Editor keyboard commands for selecting text ................................................. 132 27: Option categories in IAR Embedded Workbench IDE ................................... 148 28: Editor settings ................................................................................................. 155 29: Project settings ................................................................................................ 157 30: Argument variables ......................................................................................... 161 31: Command shells .............................................................................................. 162
xv
UDSPIC-1
32: C-SPY assembler symbols expressions .......................................................... 171 33: Handling name conflicts between h/w registers and assembler labels ........... 171 34: Examples of C-SPY macro variables .............................................................. 174 35: C-SPY setup macros ....................................................................................... 177 36: Summary of system macros ............................................................................ 177 37: __cancelInterrupt return values ...................................................................... 179 38: __disableInterrupts return values .................................................................... 180 39: __driverType return values ............................................................................. 180 40: __enableInterrupts return values ..................................................................... 181 41: __openFile return values ................................................................................. 181 42: __readFile return values ................................................................................. 183 43: __setCodeBreak return values ........................................................................ 186 44: __setDataBreak return values ......................................................................... 187 45: __setSimBreak return values .......................................................................... 188 46: Editing in C-SPY windows ............................................................................. 194 47: C-SPY menus .................................................................................................. 195 48: Memory fill operations .................................................................................... 200 49: Breakpoint categories ...................................................................................... 220 50: Breakpoint conditions ..................................................................................... 222 51: Breakpoint types ............................................................................................. 223
dsPIC IAR Embedded Workbench™ IDE
xvi User Guide
UDSPIC-1
Figures 1: Directory structure ............................................................................................... 14 2: Project window .................................................................................................... 22 3: Project menu ........................................................................................................ 23 4: Basic application .................................................................................................. 24 5: Complex application ............................................................................................ 25 6: Creating a new project ......................................................................................... 29 7: New Project dialog box........................................................................................ 30 8: Project window .................................................................................................... 30 9: Adding files to project.......................................................................................... 31 10: Displaying files in the Project window .............................................................. 31 11: Target settings .................................................................................................... 32 12: Setting compiler options .................................................................................... 33 13: Compilation message ......................................................................................... 34 14: XLINK options for project1............................................................................... 39 15: Linker message .................................................................................................. 40 16: Starting C-SPY................................................................................................... 41 17: Stepping in C-SPY ............................................................................................. 42 18: Using Step Into in C-SPY .................................................................................. 43 19: Inspecting variables in Locals window .............................................................. 44 20: Watching variables in Watch window ............................................................... 44 21: Setting breakpoints............................................................................................. 46 22: Executing up to a breakpoint ............................................................................. 47 23: Reaching program exit in C-SPY....................................................................... 48 24: Specifying setup macro file................................................................................ 53 25: C-SPY windows................................................................................................. 54 26: Log window contents ......................................................................................... 55 27: Inspecting the interrupt settings ........................................................................ 56 28: Printing the Fibonacci values in the Terminal I/O window .............................. 57 29: Call Stack window ............................................................................................. 57 30: Tutor3.cpp Disassembly window....................................................................... 59 31: Setting a breakpoint in tutor3.cpp ...................................................................... 60
xvii
UDSPIC-1
32: Setting the breakpoint condition ........................................................................ 61 33: Inspecting the function calls .............................................................................. 61 34: Printing Fibonacci sequences............................................................................. 62 35: Assembler code generation options ................................................................... 64 36: Messages window .............................................................................................. 65 37: Symbol and cross-reference table in assembler list file ..................................... 66 38: XLINK output options ....................................................................................... 68 39: Messages window .............................................................................................. 69 40: Registers counting during program execution ................................................... 69 41: XLIB window .................................................................................................... 72 42: Displaying breakpoint information .................................................................... 76 43: Modifying breakpoints....................................................................................... 77 44: Executing in C-SPY until a breakpoint condition is true................................... 78 45: Examining the root array in the Watch window ................................................ 79 46: Inspecting the call stack ..................................................................................... 79 47: Debugging in disassembly mode ....................................................................... 80 48: Monitoring memory ........................................................................................... 81 49: Displaying memory contents as 32-bit units...................................................... 81 50: Register window ................................................................................................ 82 51: Compiler list file options.................................................................................... 83 52: Setting general options....................................................................................... 87 53: Target options .................................................................................................... 88 54: Output directories............................................................................................... 89 55: Compiler options................................................................................................ 91 56: Compiler language options ................................................................................ 92 57: Compiler code options ....................................................................................... 93 58: Compiler output options..................................................................................... 96 59: Compiler list file options.................................................................................... 97 60: Compiler preprocessor options .......................................................................... 98 61: Compiler diagnostics options............................................................................. 99 62: Assembler options............................................................................................ 101 63: Assembler language options ............................................................................ 102 64: Selecting macro quote characters..................................................................... 103 65: Assembler output options................................................................................. 103
dsPIC IAR Embedded Workbench™ IDE
xviii User Guide
UDSPIC-1
Figures
66: Assembler list file options................................................................................ 104 67: Assembler preprocessor options ...................................................................... 105 68: Assembler diagnostics options......................................................................... 107 69: XLINK options ................................................................................................ 109 70: XLINK output file options............................................................................... 110 71: XLINK defined symbols options ..................................................................... 112 72: XLINK diagnostics options ............................................................................. 113 73: XLINK list file options .................................................................................... 115 74: XLINK include files options............................................................................ 116 75: XLINK input files options ............................................................................... 117 76: XLINK processing options .............................................................................. 119 77: C-SPY options.................................................................................................. 121 78: C-SPY Settings options.................................................................................... 122 79: IAR Embedded Workbench IDE window ....................................................... 125 80: IAR Embedded Workbench IDE toolbar ......................................................... 126 81: Quick search..................................................................................................... 127 82: Project window ................................................................................................ 127 83: Project window pop-up menu .......................................................................... 128 84: Editor window.................................................................................................. 130 85: Go to function button ....................................................................................... 130 86: Splitting the Editor window ............................................................................. 132 87: Editor window status bar.................................................................................. 133 88: Messages window ............................................................................................ 133 89: Messages window pop-up menu ...................................................................... 134 90: File menu.......................................................................................................... 135 91: New dialog box ................................................................................................ 135 92: New Project dialog box.................................................................................... 136 93: Edit menu ......................................................................................................... 138 94: Find dialog box ................................................................................................ 139 95: Replace dialog box........................................................................................... 140 96: Find in File dialog box ..................................................................................... 140 97: Messages window displaying found strings..................................................... 141 98: Editor window displaying found string............................................................ 142 99: Goto Line dialog box ....................................................................................... 142
xix
UDSPIC-1
100: View menu ..................................................................................................... 144 101: Project menu .................................................................................................. 145 102: Project Files dialog box.................................................................................. 145 103: New Group dialog box ................................................................................... 146 104: Targets dialog box.......................................................................................... 147 105: Options dialog box ......................................................................................... 148 106: Tools menu..................................................................................................... 150 107: Specifying external command-line editor ...................................................... 151 108: External editor DDE settings ......................................................................... 152 109: Specifying common fonts .............................................................................. 153 110: Specifying key bindings................................................................................. 154 111: Editor settings ................................................................................................ 155 112: Specifying Editor window colors and fonts................................................... 156 113: Project settings ............................................................................................... 157 114: Debugger settings........................................................................................... 158 115: Register Filter page ........................................................................................ 159 116: Configure Tools dialog box ........................................................................... 160 117: Customized Tools menu................................................................................. 162 118: Window menu ................................................................................................ 163 119: Help menu ...................................................................................................... 164 120: Embedded Workbench with C-SPY started................................................... 193 121: C-SPY debug toolbar ..................................................................................... 195 122: C-SPY Disassembly window ......................................................................... 196 123: Disassembly window pop-up menu ............................................................... 197 124: Memory window ............................................................................................ 198 125: Memory window pop-up menu...................................................................... 199 126: Memory Fill dialog box ................................................................................. 199 127: Register window ............................................................................................ 200 128: C-SPY Watch window ................................................................................... 201 129: Add command on C-SPY Watch window pop-up menu ............................... 202 130: Locals window ............................................................................................... 202 131: Call Stack window ......................................................................................... 203 132: Log window ................................................................................................... 203 133: Terminal I/O window..................................................................................... 204
dsPIC IAR Embedded Workbench™ IDE
xx User Guide
UDSPIC-1
Figures
134: Change Input Type dialog box....................................................................... 204 135: Code Coverage window ................................................................................. 205 136: Code Coverage window pop-up menu........................................................... 206 137: Profiling window............................................................................................ 207 138: Profiling window pop-up menu ..................................................................... 208 139: Graphs in Profiling window ........................................................................... 208 140: Function details window ................................................................................ 209 141: Debug menu ................................................................................................... 210 142: QuickWatch window...................................................................................... 211 143: Macro Files dialog box .................................................................................. 213 144: Log File dialog box ........................................................................................ 214 145: Terminal I/O Log File dialog box .................................................................. 214 146: Simulator menu .............................................................................................. 215 147: Interrupts dialog box ...................................................................................... 216 148: Memory Map dialog box................................................................................ 218 149: Illegal memory access.................................................................................... 219 150: Breakpoints dialog box .................................................................................. 220 151: Setting a breakpoint on a source location ...................................................... 221 152: Setting a breakpoint on an expression............................................................ 222
xxi
UDSPIC-1
dsPIC IAR Embedded Workbench™ IDE
xxii User Guide
UDSPIC-1
Preface Welcome to the dsPIC IAR Embedded Workbench™ IDE User Guide. The purpose of this guide is to help you fully utilize the features in the dsPIC IAR Embedded Workbench with its integrated Windows development tools for the dsPIC microcontroller. The IAR Embedded Workbench is a very powerful Integrated Development Environment that allows you to develop and manage a complete embedded application project. The user guide includes comprehensive information about installation and product overviews, as well as tutorials that can help you get started.
Who should read this guide You should read this guide if you want to get the most out of the features and tools used in the IAR Embedded Workbench. In addition, you should have a working knowledge of the following:
The C or Embedded C++ programming language The IAR dsPIC assembler language Application development for embedded systems The architecture and instruction set of the dsPIC microcontroller (refer to the chip manufacturer's documentation) The operating system of your host machine. Refer to the dsPIC IAR C/EC++ Compiler Reference Guide, dsPIC IAR Assembler Reference Guide, and IAR Linker and Library Tools Reference Guide for more information about the other development tools incorporated in the IAR Embedded Workbench IDE.
How to use this guide If you are new to using this product, we suggest that you start by reading Part 1. The IAR development tools to give you a complete overview of the tools and the functions that the IAR Embedded Workbench can offer. If you already have had some experience using the IAR Embedded Workbench, but need refreshing on how to work with the IAR development tools, Part 2. Tutorials is a good place to begin. If you are an experienced user and need this guide as more of a reference, see the reference sections in Part 3. The IAR Embedded Workbench IDE.
xxiii
UDSPIC-1
What this guide contains
Finally, we recommend you to refer to the Glossary if you should encounter any unfamiliar terms in the IAR Systems user and reference guides.
What this guide contains Below is a brief outline and summary of the chapters in this guide. Part 1. The IAR development tools This section provides a general overview of all the IAR development tools so that you can become familiar with all their functions and features:
Product overview provides a brief summary and lists the features offered in each of the IAR Systems development tools—IAR Embedded Workbench IDE, IAR C/EC++ Compiler, IAR Assembler, IAR XLINK Linker, IAR XLIB Librarian™ and IAR C-SPY™ Debugger—for the dsPIC microcontroller Product configuration describes the directory structure and the type of files it contains, and includes an overview of the documentation supplied with the IAR development tools The project model describes how you can organize a project using the IAR Embedded Workbench by specifying the different target versions of the application that you want to build, creating groups for a particular target, and keeping track of source files. The chapter also explains how configuration options are managed and related to the project. Part 2. Tutorials The tutorials give you hands-on training in order to help you get started with using the tools:
IAR Embedded Workbench IDE tutorial guides you through setting up a new project, compiling the program, examining the list file, linking the program and debugging it. The tutorial demonstrates a typical development cycle using the IAR Embedded Workbench IDE; the dsPIC IAR C/EC++ Compiler, the IAR XLINK Linker, and the IAR C-SPY Debugger. Compiler tutorials demonstrates how to utilize the features in the IAR Embedded Workbench to develop a series of typical programs for the dsPIC IAR C/EC++ Compiler. Assembler tutorials illustrates how you use the IAR Embedded Workbench IDE to develop machine-code programs by using some of the most important features of the dsPIC IAR Assembler. This chapter also introduces you to the IAR XLIB Librarian, which helps to maintain files of library modules.
dsPIC IAR Embedded Workbench™ IDE
xxiv User Guide
UDSPIC-1
Preface
Advanced tutorials is divided into several tutorials that explore some of the more advanced features of the IAR C-SPY Debugger, such as how to define complex breakpoints, and debug in disassembly mode. Part 3. The IAR Embedded Workbench IDE This section describes the IAR Embedded Workbench IDE graphical user interface, and how to set project options:
General options specifies the runtime options and output directories Compiler options specifies compiler options for language, code, optimizations, output, list file, preprocessor, and diagnostics
Assembler options shows how to set assembler options for code generation, debugging, preprocessor, and list file generation
XLINK options shows how to set XLINK options for output, defining symbols,
diagnostics, list generation, setting up the include path for the linker command file, input, and processing C-SPY options shows how to set options for the debugger IAR Embedded Workbench IDE reference contains a detailed reference for the development environment, such as details about the graphical user interface Introduction to the IAR C-SPY Debugger gives an overview of the IAR debugger C-SPY expressions defines the syntax of the expressions and variables used in C-SPY macros C-SPY macros lists the built-in system macros supplied with the IAR C-SPY Debugger C-SPY Debugger reference provides detailed reference information about the graphical user interface of the IAR C-SPY Debugger.
Document conventions This book uses the following typographic conventions: Style
Used for
computer
Text that you enter or that appears on the screen.
parameter
A label representing the actual value you should type as part of a command.
[option]
An optional part of a command.
{a | b | c}
Alternatives in a command.
bold
Names of menus, menu commands, buttons, and dialog boxes that appear on the screen.
reference
A cross-reference within or to another guide.
Table 1: Typographic conventions used in this guide
xxv
UDSPIC-1
Document conventions
Style
Used for
Identifies instructions specific to the IAR Embedded Workbench versions of the IAR development tools. Identifies instructions specific to the command line versions of the IAR development tools. Table 1: Typographic conventions used in this guide (Continued)
dsPIC IAR Embedded Workbench™ IDE
xxvi User Guide
UDSPIC-1
Part 1. The IAR development tools This part of the dsPIC IAR Embedded Workbench™ IDE User Guide includes the following chapters: Product overview Product configuration The project model.
1
UDSPIC-1
2
UDSPIC-1
Product overview The IAR Embedded Workbench™ is a very powerful Integrated Development Environment (IDE), that allows you to develop and manage complete embedded application projects. It is a true 32-bit Windows environment, with all the features you would expect to find in your everyday working place. This chapter describes the IAR Embedded Workbench IDE and provides a general overview of all the tools that are integrated in this product.
The IAR Embedded Workbench IDE The IAR Embedded Workbench IDE is the framework where all necessary tools are seamlessly integrated: a highly optimizing C/EC++ compiler, an assembler, the versatile IAR XLINK Linker™, the IAR XLIB Librarian™, a powerful editor, a project manager with Make utility, and C-SPY™, a state-of-the-art high-level language debugger. The IAR Embedded Workbench is available for a large number of microprocessors and microcontrollers in the 8-, 16-, and 32-bit segments, allowing you to stay within a well-known development environment also for your next project. It provides an easy-to-learn and highly efficient development environment with maximum code inheritance capabilities, comprehensive and specific target support. The IAR Embedded Workbench promotes a useful working methodology, and thus a significant reduction of the development time can be achieved by using the IAR tools. We call this concept: “Different Architectures. One Solution.” If you want detailed information about supported target processors, contact your software distributor or your IAR representative, or visit the IAR website www.iar.com for information about recent product releases.
AN EXTENSIBLE AND MODULAR ENVIRONMENT Although the IAR Embedded Workbench IDE provides all the features required for a successful project, we also recognize the need to integrate other tools. Therefore the IAR Embedded Workbench can be easily adapted to work with your editor of choice. Project files can be saved as text files, to support your own Make facility. The IAR XLINK Linker can produce a large number of output formats, allowing for debugging on most third-party emulators. RTOS support can also be added to the product. The compiler, assembler, and linker can also be run from a command line environment, if you want to use them as external tools in an already established project environment.
Part 1. The IAR development tools 3
UDSPIC-1
The IAR Embedded Workbench IDE
FEATURES The IAR Embedded Workbench is a flexible integrated development environment, allowing you to develop applications for a variety of different target processors. It provides a convenient Windows interface for rapid development and debugging.
Project management The IAR Embedded Workbench IDE comes with functions that will help the developer to stay in control of all project modules like C or Embedded C++ source code files, assembler files, include files and other related modules. Modules can be grouped, and options can be set on all levels—project, group, or file. Changes are tracked so that a request for rebuild will retranslates all required modules, making sure that no executables contain out-of-date modules.
Hierarchical project representation Projects build in the background, allowing simultaneous editing Options can be set globally, on groups of source files, or on individual source files The Make utility recompiles, reassembles, and links files only when necessary Generic and dsPIC-specific optimization techniques produce very efficient machine code.
The text editor The integrated text editor allows editing of multiple files in parallel, and provides all basic editing features expected from a modern editor, including unlimited undo/redo and automatic completion. In addition, it provides functions specific to software development, like coloring of keywords (C/EC++, assembler, and user-defined), block indent, and function navigation within source files. It also recognizes C language elements like matching brackets.
Syntax of C or Embedded C++ programs shown using text styles and colors Powerful search and replace commands, including multi-file search Direct jump to context from error listing Parenthesis matching Automatic indentation Unlimited undo and redo for each window.
DOCUMENTATION The dsPIC IAR Embedded Workbench IDE is documented in the dsPIC IAR Embedded Workbench™ IDE User Guide (this guide). There is also help and hypertext versions of the user documentation available online.
dsPIC IAR Embedded Workbench™ IDE
4 User Guide
UDSPIC-1
Product overview
IAR C-SPY Debugger The IAR C-SPY Debugger is a high-level-language debugger for embedded applications. It is designed for use with the IAR compilers and assemblers, and is completely integrated in the IAR Embedded Workbench IDE, providing seamless switching between development and debugging.
SINGLE STEPPING ON FUNCTION CALL LEVEL Since IAR Systems provides an entire tool chain, the output provided by the compiler and linker can include extensive debug information for the debugger, resulting in good debugging properties for the user. Compared to traditional debuggers, where the lowest source level step is line by line, C-SPY source code stepping provides a finer level of control by identifying every function call as a step point. This means that function calls inside expressions can be single stepped, as well as function calls being part of parameter lists to other function calls. The latter is especially useful when debugging EC++ code, where numerous extra function calls are made, for example to object constructors. The debug information also presents inlined functions as if a call was made, making the source code of the inlined function available.
BACKTRACING The dsPIC IAR C/EC++ Compiler generates extensive backtrace information. This allows C-SPY to show, without any runtime penalty, the complete stack of function calls wherever the program counter is.
DEBUGGING IN THE SOURCE WINDOW The source code windows used during debugging are those used to edit or view source code in the IDE. The integration allows things like:
Editing while debugging. During a debug session, corrections can be made directly into the same source code window that is used to control the debugging. Changes will be included in the next project rebuild. Setting source code breakpoints before starting the debugger. Breakpoints in source code will be associated with the same piece of source code even if additional code is inserted.
DISASSEMBLY DEBUGGING The IAR C-SPY Debugger allows you to seamlessly switch between C source and disassembly debugging as required, for both C or Embedded C++ and assembler source code.
Part 1. The IAR development tools 5
UDSPIC-1
IAR C-SPY Debugger
Debugging the C or Embedded C++ source code provides the quickest and easiest way of verifying your application, without needing to worry about how the compiler has implemented your C or Embedded C++ code in assembler language. When debugging you can execute the program one function call at a time, and monitor the values of variables and data structures. Disassembly debugging lets you focus on the critical sections of your application, and provides you with precise control over the hardware. You can execute the program an assembler instruction at a time, and display the registers and memory or change their contents. In Mixed-Mode display, the debugger also displays the corresponding C/EC++ source code interleaved with the disassembly listing.
FEATURES The IAR C-SPY Debugger offers a unique combination of features.
General The IAR C-SPY Debugger offers the following general features:
A modular and extensible architecture Threaded execution keeps the IDE responsive while running the target program Source and disassembly mode debugging Fast simulator Log file option Powerful macro language Complex code and data breakpoints Memory validation Interrupt simulation UBROF, INTEL-EXTENDED, and Motorola input formats supported.
High-level-language debugging
Expression analyzer Extensive type recognition of variables Configurable register and memory windows Support for real stack backtrace Call stack with parameters Watch and Locals windows allow you to expand complex data structures Optional terminal I/O emulation.
Assembler-level debugging Built-in disassembler.
dsPIC IAR Embedded Workbench™ IDE
6 User Guide
UDSPIC-1
Product overview
VERSIONS The IAR C-SPY Debugger for the dsPIC microcontroller is currently available in a simulator version. Contact your software distributor or IAR representative for information about other versions of C-SPY. Below are general descriptions of the different C-SPY versions.
Simulator version The simulator version simulates the functions of the target processor entirely in software. With this C-SPY version, the program logic can be debugged long before any hardware is available. Since no hardware is required, it is also the most cost-effective solution for many applications. For additional information about the simulator version of the IAR C-SPY Debugger, refer to Part 3. The IAR Embedded Workbench IDE in this guide.
Emulator version The emulator version of the IAR C-SPY Debugger provides control over an in-circuit emulator, which is connected to the host computer. The IAR C-SPY Debugger uses the hardware features of the emulator, such as breakpoint logic and memory inspection, to allow an application to be executed in real time and in the proper target environment.
ROM-monitor version The ROM-monitor version of the IAR C-SPY Debugger provides a low-cost solution to real-time debugging.
DOCUMENTATION The IAR C-SPY Debugger is documented in the dsPIC IAR Embedded Workbench™ IDE User Guide (this guide). There is also help and hypertext versions of the documentation available online.
Part 1. The IAR development tools 7
UDSPIC-1
IAR C/EC++ Compiler
IAR C/EC++ Compiler The dsPIC IAR C/EC++ Compiler is a state-of-the-art compiler that offers the standard features of the C or Embedded C++ language, plus many extensions designed to take advantage of the dsPIC-specific facilities. The compiler is integrated with other IAR Systems software for the dsPIC microcontroller. It is supplied with the dsPIC IAR Assembler, with which it shares linker and librarian tools.
COMPILER EXTENSIONS The dsPIC IAR C/EC++ Compiler provides #pragma directives consistent with ISO/ANSI C, which is very useful when you want to make sure that the source code is portable, while still being able to use processor-specific extensions. There are also predefined preprocessor symbols that you can use to inspect your compile-time environment, for example the code model and processor variant. In addition, the compiler has a set of intrinsic functions that provide direct access to low-level processor operations and can be very useful in, for example, time-critical routines. The intrinsic functions compile into in-line code, either as a single instruction or as a short sequence of instructions. Another feature is a set of extended keywords that can be used for controlling the behavior of the program. There are, for example, keywords for controlling the memory type for individual variables as well as for declaring special function types. In addition, the compiler supports inline assembler statements.
EMBEDDED C++ The compiler provides support for Embedded C++, which can be seen as a subset of C++ designed to suit the development of embedded applications. The C++ features not found in EC++ are those that were considered to be costly for some reason, for example due to risk of increasing code size or decreased execution speed. EC++ is well suited for modern modeling and development techniques. The most important reason for using EC++ is support for object-oriented programming, a technique used to modularize an application. The benefits of EC++ become visible when larger applications are written. An application that contains several modules could be modeled using object-oriented principles. This is especially valuable if the modules are written by different groups or if the modules are intended to be used by a larger audience, such as a third-party library.
dsPIC IAR Embedded Workbench™ IDE
8 User Guide
UDSPIC-1
Product overview
CODE GENERATION The dsPIC IAR C/EC++ Compiler offers comprehensive output options, including relocatable object code, assembler source code, and list files with optional assembler mnemonics. The object code can be linked with assembler routines. The compiler includes a global optimizer that performs, among other things, dead-code elimination, constant propagation, inlining, common sub-expression elimination, and precision reduction. It also performs loop optimizations such as unrolling. The user can control the level of optimization and decide if the basic approach is to optimize for speed or for size. It is also possible to disallow individual optimizations.
Language facilities
Conformance to the ISO/ANSI C standard for a free-standing environment Standard library of functions applicable to embedded systems IEEE-compatible floating-point arithmetic Interrupt functions can be written in C or Embedded C++.
Type checking
External references are type-checked at link time Extensive type checking at compile time Link-time inter-module consistency checking of the application Compatibility with the C-SPY high-level language debugger.
RUNTIME LIBRARIES The dsPIC IAR C/EC++ Compiler supports two sets of runtime libraries:
The IAR CLIB Library, which is a small, efficient library well-suited for 8- and 16-bit processors. This library is not fully compliant with ISO/ANSI C, and does not fully support IEEE 754 floating-point numbers. Embedded C++ is not supported. The IAR DLIB Library, which supports ISO/ANSI C and Embedded C++. Note: CLIB is the default library, unless you run the compiler in EC++ mode.
DOCUMENTATION The dsPIC IAR C/EC++ Compiler is documented in the dsPIC IAR C/EC++ Compiler Reference Guide.
Part 1. The IAR development tools 9
UDSPIC-1
IAR Assembler
IAR Assembler The dsPIC IAR Assembler is integrated with other IAR Systems software for the dsPIC microcontroller. It is a powerful relocating macro assembler (supporting the Intel/Motorola style) with a versatile set of directives and expression operators. The assembler features a built-in C language preprocessor and supports conditional assembly. The dsPIC IAR Assembler uses the same mnemonics and operand syntax as the Microchip dsPIC Assembler, which makes the migration of existing code quite easy. For detailed information, see the dsPIC IAR Assembler Reference Guide.
FEATURES The dsPIC IAR Assembler provides the following features:
C preprocessor List file with augmented cross-reference output Number of symbols and program size limited only by available memory Support for complex expressions with external references Up to 65536 relocatable segments per module 255 significant characters in symbol names 32-bit arithmetic used internally for assembler instructions.
DOCUMENTATION The dsPIC IAR Assembler is documented in the dsPIC IAR Assembler Reference Guide.
IAR XLINK Linker The IAR XLINK Linker links one or more relocatable object files produced by the dsPIC IAR Assembler or dsPIC IAR C/EC++ Compiler to produce machine code for the dsPIC microcontroller. It is equally well suited for linking small, single-file, absolute assembler programs as for linking large, relocatable, multi-module, C/EC++, or mixed C/EC++ and assembler programs. It can output any one of more than 30 industry-standard loader formats, in addition to the IAR Systems proprietary debug format used by the IAR C-SPY Debugger—UBROF (Universal Binary Relocatable Object Format). An application can be made up of any number of UBROF relocatable files, in any combination of assembler and C or Embedded C++ programs.
dsPIC IAR Embedded Workbench™ IDE
10 User Guide
UDSPIC-1
Product overview
The final output produced by the IAR XLINK Linker is an absolute, target-executable object file that can be downloaded to the dsPIC microcontroller or to a hardware emulator. The IAR XLINK Linker supports user libraries, and will load only those modules that are actually needed by the program you are linking. Before linking, the IAR XLINK Linker performs a full C-level type checking across all modules as well as a full dependency resolution of all symbols in all input files, independent of input order. It also checks for consistent compiler settings for all modules and makes sure that the correct version and variant of the C or Embedded C++ runtime library is used.
FEATURES
Full inter-module type checking Simple override of library modules Flexible segment commands allow detailed control of code and data placement Link-time symbol definition enables flexible configuration control Optional code checksum generation for runtime checking.
DOCUMENTATION The IAR XLINK Linker is documented in the IAR Linker and Library Tools Reference Guide which is available in PDF format.
IAR XLIB Librarian The IAR XLIB Librarian enables you to manipulate the relocatable library object files produced by the IAR Systems assembler and compiler. A library is a single file that contains a number of relocatable object modules, each of which can be loaded independently from other modules in the file as it is needed. A library file is no different from any other relocatable object file produced by the assembler or compiler, except that it includes a number of modules of the LIBRARY type. All C or Embedded C++ programs make use of libraries, and the dsPIC IAR C/EC++ Compiler is supplied with a number of standard library files. If you are only writing in assembler language there is no need to use libraries. However, libraries provide the following advantages, especially when writing medium- and large-sized assembler applications:
They allow you to combine utility modules used in more than one project into a simple library file. This simplifies the linking process by eliminating the need to include a list of input files for all the modules you need. Only the library module(s) needed for the program will be included in the output file.
Part 1. The IAR development tools 11
UDSPIC-1
IAR XLIB Librarian
They simplify program maintenance by allowing multiple modules to be placed in a single assembler source file. Each of the modules can be loaded independently as a library module. They reduce the number of object files that make up an application, maintenance, and documentation.
FEATURES The IAR XLIB Librarian provides the following features:
Modules can be listed, added, inserted, replaced, or deleted Modules can be changed between program and library type Segments can be listed Symbols can be listed Interactive or batch mode operation.
DOCUMENTATION The IAR XLIB Librarian is documented in the IAR Linker and Library Tools Reference Guide.
dsPIC IAR Embedded Workbench™ IDE
12 User Guide
UDSPIC-1
Product configuration To help you get started, this chapter shows you how to run the IAR Embedded Workbench. It also describes which directories are created and what file types are used. At the end of the chapter, there is a section that describes what information you can find in the various guides and online documentation. Refer to the QuickStart Card and the Installation and Licensing Guide, which are delivered with the product, for system requirements and information about how to install and register the IAR products.
Included in this package The IAR Systems development tools package for the dsPIC microcontroller contains the following items:
Installation media QuickStart Card User documentation: dsPIC IAR Embedded Workbench™ IDE User Guide (this guide) dsPIC IAR C/EC++ Compiler Reference Guide dsPIC IAR Assembler Reference Guide.
Running the IAR Embedded Workbench Press the Start button in the taskbar and select Programs. Select IAR Systems in the menu. Then select IAR Embedded Workbench for dsPIC and IAR Embedded Workbench. The iaride.exe file is located in the common\bin directory, in case you want to run the program from the command line or from within the Windows Explorer; see Figure 1, Directory structure, page 14.
Directory structure The installation procedure creates several directories to contain the different types of files used with the IAR Systems development tools. The following sections give a description of the files contained by default in each directory.
Part 1. The IAR development tools 13
UDSPIC-1
Directory structure
ROOT DIRECTORY The root directory created by the default installation procedure is the x:\Program Files\IAR Systems\Embedded Workbench 3.n\ directory where x is the drive where Microsoft Windows is installed and 3.n is the version number of the IAR Embedded Workbench IDE. The dspic directory, containing all product-specific subdirectories, and the common directory with components shared by
all IAR Embedded Workbench products, are located here.
Figure 1: Directory structure
Note: The default installation path can be different from the one shown above depending on previously installed IAR products.
THE COMMON\BIN DIRECTORY The common\bin subdirectory contains executable files for components common to all IAR Embedded Workbench products, such as the IAR XLINK Linker™, the IAR XLIB Librarian™, the editor and the graphic user interface components. The executable file for the IAR Embedded Workbench is also located here.
THE COMMON\DOC DIRECTORY The common\doc subdirectory contains read-me files with recent additional information about the components common to all IAR Embedded Workbench products, such as the IAR XLINK Linker and the IAR XLIB Librarian. We recommend that you read these files before proceeding. The directory also contains an online version in PDF format of the IAR Linker and Library Tools Reference Guide.
THE COMMON\SRC DIRECTORY The common\src subdirectory contains source files for components common to all IAR Embedded Workbench products, such as a sample reader of the IAR XLINK Linker output format SIMPLE.
dsPIC IAR Embedded Workbench™ IDE
14 User Guide
UDSPIC-1
Product configuration
THE DSPIC\BIN DIRECTORY The dspic\bin subdirectory contains executable files for dsPIC-specific components, such as the dsPIC IAR C/EC++ Compiler, the dsPIC IAR Assembler, and the dsPIC IAR C-SPY driver.
THE DSPIC\CONFIG DIRECTORY The dspic\config subdirectory contains files used for configuring the system, for example:
Linker command file templates (*.xcl) Special function register description files (*.sfr) The C-SPY device description files (*.ddf) Syntax coloring configuration files (*.cfg).
THE DSPIC\DOC DIRECTORY The dspic\doc subdirectory contains readme files with recent additional information about the dsPIC tools. We recommend that you read all of these files before proceeding. The directory also contains online versions (PDF format) of this user guide, the dsPIC reference guides, and a DLIB reference in HTML format.
THE DSPIC\INC DIRECTORY The dspic\inc subdirectory holds include files, such as the header files for the standard C or Embedded C++ library. There are also specific header files defining special function registers (SFRs); these files are used by both the compiler and the assembler.
THE DSPIC\LAYOUTS DIRECTORY The dspic\layouts subdirectory holds one or more layout files (*.lew) that describe how the C-SPY windows are arranged on the screen during a debug session. For additional information, see Using layouts, page 194.
THE DSPIC\LIB DIRECTORY The dspic\lib subdirectory holds library modules used by the compiler.
THE DSPIC\SETTINGS DIRECTORY The dspic\settings subdirectory holds files which contain information about your project configuration and other settings.
Part 1. The IAR development tools 15
UDSPIC-1
File types
THE DSPIC\SRC DIRECTORY The dspic\src subdirectory holds source files for some configurable library functions.
THE DSPIC\TUTOR DIRECTORY The dspic\tutor subdirectory contains the files used for the tutorials in this guide.
File types The dsPIC versions of the IAR Systems development tools use the following default filename extensions to identify the IAR-specific file types: Ext.
Type of file
Output from
Input to
a59
Target program
XLINK
EPROM, C-SPY, etc
asm
Assembler source code
Text editor
Assembler
c
C source code
Text editor
Compiler
cfg
Syntax coloring configuration
Text editor
IAR Embedded Workbench
cpp
Embedded C++ source code
Text editor
Compiler
d59
Target program with debug information
XLINK
C-SPY and other symbolic debuggers
ddf
Device description file
Text editor
C-SPY
dni
Debugger initialization file
C-SPY
C-SPY
h
C or Embedded C++ header source
Text editor
Compiler #include
i
Preprocessed source
Compiler
Compiler
inc
Assembler header source
Text editor
Assembler #include
lew
Window layout information
C-SPY
C-SPY
lst
List output
Compiler and assembler
–
mac
C-SPY macro definition
Text editor
C-SPY
map
List output
XLINK
–
pew
IAR Embedded Workbench project
IAR Embedded IAR Embedded Workbench Workbench
r59
Object module
Compiler and assembler
Table 2: File types
dsPIC IAR Embedded Workbench™ IDE
16 User Guide
UDSPIC-1
XLINK and XLIB
Product configuration
Ext.
Type of file
Output from
Input to
s59
dsPIC assembler source code
Text editor
dsPIC IAR Assembler
sfr
Special function register definitions
Text editor
C-SPY
xcl
Extended command line
Text editor
Assembler, compiler, XLINK
xlb
Extended librarian batch command
Text editor
XLIB
Table 2: File types (Continued)
You can override the default filename extension by including an explicit extension when specifying a filename. Files with the extensions ini and dni are created dynamically when you run the IAR Embedded Workbench tools. These files, which contain information about your project configuration and other settings, are located in a settings directory under your project directory. Project files created by the current version of the IAR Embedded Workbench have the file extension pew. If you have several different versions of the Embedded Workbench installed, files you double-click will be opened with the current version if they have this extension. If the project file was in fact last saved by an older version of the Embedded Workbench, it will be converted on opening. See Open, page 136. Note: If you run the tools from the command line, the XLINK listings (maps) will by default have the extension lst, which may overwrite the list file generated by the compiler. Therefore, we recommend that you name XLINK map files explicitly, for example project1.map.
Documentation This section briefly describes the information that is available in the dsPIC user and reference guides, in the online help, and on the Internet.
THE USER AND REFERENCE GUIDES The user and reference guides provided with the IAR Embedded Workbench are as follows:
dsPIC IAR Embedded Workbench™ IDE User Guide This guide.
Part 1. The IAR development tools 17
UDSPIC-1
Documentation
dsPIC IAR C/EC++ Compiler Reference Guide This guide provides reference information about the dsPIC IAR C/EC++ Compiler. You should refer to this guide for information about:
How to configure the compiler to suit your target processor and application
requirements How to write efficient code for your target processor The available data types The runtime libraries The IAR language extensions.
dsPIC IAR Assembler Reference Guide This guide provides reference information about the dsPIC IAR Assembler, including details of the assembler source format, and reference information about the assembler operators, directives, mnemonics, and diagnostics.
IAR Linker and Library Tools Reference Guide This online PDF guide provides reference information about the IAR XLINK Linker, and IAR XLIB Librarian:
The IAR XLINK Linker reference sections provide information about XLINK options, output formats, environment variables, and diagnostics.
The IAR XLIB Librarian reference sections provide information about XLIB commands, environment variables, and diagnostics.
CLIB Library Reference Guide This online guide in PDF format contains reference information about the IAR CLIB Library. It is available from the Help menu in the IAR Embedded Workbench IDE.
DLIB Library Reference Guide, C part This online guide in PDF format provides reference information about the ISO/ANSI C part of the IAR DLIB Library. It is available from the Help menu in the IAR Embedded Workbench IDE.
DLIB Library Reference Guide, EC++ part This online guide in HTML format provides reference information about the Embedded C++ part of the IAR DLIB Library. It is available from the Help menu in the IAR Embedded Workbench IDE.
dsPIC IAR Embedded Workbench™ IDE
18 User Guide
UDSPIC-1
Product configuration
ONLINE HELP AND DOCUMENTATION You can access the dsPIC online documentation from the Help menu in the IAR Embedded Workbench. Help is also available via the F1 button in the IAR Embedded Workbench IDE. We recommend that you read the readme.htm file for recent information that may not be included in the user guides. It is located in the dspic\doc directory.
IAR ON THE WEB The latest news from IAR Systems can be found at the website www.iar.com, available from the Help menu in the Embedded Workbench IDE. Visit it for information about:
Product announcements Updates and news about current versions Special offerings Evaluation copies of the IAR products Technical Support, including technical notes Application notes Links to chip manufacturers and other interesting sites Distributors; the names and addresses of distributors in each country.
Part 1. The IAR development tools 19
UDSPIC-1
Documentation
dsPIC IAR Embedded Workbench™ IDE
20 User Guide
UDSPIC-1
The project model This chapter briefly discusses the project model used by the IAR Embedded Workbench. It covers how projects are organized and how you specify targets, groups, source files, and options so that you can better handle different versions of your applications. The concepts discussed in this chapter are illustrated in Part 2. Tutorials in this guide. You may find it helpful to return to this chapter while running the tutorials.
Developing projects The IAR Embedded Workbench provides a powerful environment for developing projects with a range of different target processors, and a selection of tools for each target processor.
HOW PROJECTS ARE ORGANIZED The IAR Embedded Workbench has been specially designed to fit in with the way that software development projects are typically organized. For example, you may need to develop related versions of an application for different versions of the target hardware, and you may also want to include debugging routines into the early versions, but not in the final code. Versions of your applications for different target hardware will often have source files in common, and you want to be able to maintain a unique copy of these files, so that improvements are automatically carried through to each version of the application. There can also be source files that differ between different versions of the application, such as those dealing with hardware-dependent aspects of the application. These files can be maintained separately for each target version. The IAR Embedded Workbench addresses these requirements, and provides a powerful environment for maintaining the source files used for building all versions of an application. It allows you to organize projects in a hierarchical tree structure showing the dependency between files at a glance.
Targets At the highest level of the structure you specify the different target versions of your application that you want to build. For a simple application you might need just two targets, called Debug and Release. A more complex project might include additional targets for each of the different processor variants that the application is to run on.
Part 1. The IAR development tools 21
UDSPIC-1
Developing projects
Groups Each target in turn contains one or more groups, which collect together related sets of source files. A group can be unique to a particular target, or it can be present in two or more targets. For example, you might create a group called Debugging routines which would be present only in the Debug target, and another group called Common sources which would be present in all targets.
Source files Each group is used for grouping together one or more related source files. For maximum flexibility each group can be included in one or more targets. When you are working with a project you always have a current target selected, and only the groups that are members of that target, along with their enclosed files, are visible in the Project window. Only these files will actually be built and linked into the output code.
Figure 2: Project window
SETTING OPTIONS For each target you set global assembler and compiler options at the target level, to specify how that target should be built. At this level you typically define the runtime options, for example which processor variant to use. You can also set local compiler and assembler options on individual groups and source files. These local options are specific to the context of a target and override any corresponding global options set at the target level, and are specific to that target. A group can be included in two different targets and have different options set for it in each target. For example, you might set optimization high for a group containing source files that you have already debugged, but set it low for another group containing source files that you are still developing.
dsPIC IAR Embedded Workbench™ IDE
22 User Guide
UDSPIC-1
The project model
For an example where different options are set on file level, see Creating a combined C and assembler project. For information about how to set options, see the chapters Compiler options and Assembler options in Part 3. The IAR Embedded Workbench IDE in this guide.
BUILDING A PROJECT The Compile command on the IAR Embedded Workbench Project menu allows you to compile or assemble the files of a project individually. The IAR Embedded Workbench automatically determines whether a source file should be compiled or assembled depending on the filename extension.
Figure 3: Project menu
Alternatively, you can build the entire project using the Make command. This command identifies the modified files, and only recompiles or reassembles those files that have changed before it relinks the project. A Build All option is also provided, which unconditionally regenerates all files. The Compile, Make, Link, and Build commands all run in the background so that you can continue editing or working with the IAR Embedded Workbench while your project is being built.
TESTING THE CODE The compiler, assembler, and debugger are fully integrated with the development environment, so that if there are errors in your source code you can jump directly from the error listing to the correct position in the appropriate source file, to allow you to locate and correct the error. After you have resolved any problems reported during the build process, you can continue directly to debug the resulting code at source level.
Part 1. The IAR development tools 23
UDSPIC-1
Developing projects
Applications built outside of the IDE It is also possible to use the IAR C-SPY Debugger to debug applications that you have built outside of the IAR Embedded Workbench IDE. See Open Project, page 136, for instructions on how to do this.
SAMPLE APPLICATIONS The following examples describe two sample applications to illustrate how you would use the IAR Embedded Workbench in typical development projects.
A basic application The following diagram shows a simple application, developed for one target processor only. Here you would manage with the two default targets, Release and Debug:
Targets Debug
Release
Groups I/O stubs
Common
I/O routines
Source files Iodebug.c
Main.c
Process.c
Compute.c
Io.c
Figure 4: Basic application
Both targets share a common group containing the project’s core source files. Each target also contains a group containing the source files specific to that target: I/O routines, contains the source files for the input/output routines to be used in the final release code, and I/O stubs which contains input/output stubs to allow the I/O to be debugged with C-SPY. The release and debug targets would typically have different compiler options set for them; for example, you could compile the Debug version with trace, assertions, etc, and the Release version without it.
dsPIC IAR Embedded Workbench™ IDE
24 User Guide
UDSPIC-1
The project model
A more complex project In the following more complex project an application is being developed for several different pieces of target hardware, containing different variants of a processor, different I/O ports and memory configurations. The project therefore includes a debug target, and a release target for each of the different sets of target hardware. The source files that are common to all the targets are collected together, for convenience, into groups which are included in each of the targets. The names of these groups reflect the areas in the application that the source code deals with; for example math routines. Areas of the application that depend on the target hardware, such as the memory management, are included in a number of separate groups, one per target. Finally, as before, debugging routines are provided for the Debug target.
Targets Debug
Release
Groups I/O stubs
Memory management
General routines
Iodebug.c
Kbmem.c
Main.c
Math routines
I/O routines
Source files Calc.c
Fp.c
Io.c
Figure 5: Complex application
When you are working on larger projects, the IAR Embedded Workbench minimizes your development time by helping you to keep track of the structure of your project, and by optimizing the development cycle by assembling and compiling the minimum set of source files necessary to keep the object code completely up to date after changes.
Part 1. The IAR development tools 25
UDSPIC-1
Developing projects
dsPIC IAR Embedded Workbench™ IDE
26 User Guide
UDSPIC-1
Part 2. Tutorials This part of the dsPIC IAR Embedded Workbench™ IDE User Guide contains the following chapters: IAR Embedded Workbench IDE tutorial Compiler tutorials Assembler tutorials Advanced tutorials.
27
UDSPIC-1
28
UDSPIC-1
IAR Embedded Workbench IDE tutorial This chapter introduces you to the IAR Embedded Workbench™ IDE and the IAR C-SPY™ Debugger. It shows you how to create and debug a small program for the dsPIC microcontroller. The following steps demonstrate a typical development cycle: Creating a project with C source files and specifying target options Compiling the program, examining the list file, and linking the program Running the program in the IAR C-SPY Debugger.
Using the IAR Embedded Workbench IDE We recommend that you create a specific directory where you can store all your project files, for example, a \dspic\projects directory.
CREATING A NEW PROJECT The first step is to create a new project for the tutorial programs.
1 Start the IAR Embedded Workbench IDE. 2 Choose File>New to display the following dialog box:
Figure 6: Creating a new project
The Help button provides access to information about the IAR Embedded Workbench IDE. You can at any time press the F1 key to access the online help.
3 Select Project and click OK to display the New Project dialog box.
Part 2. Tutorials 29
UDSPIC-1
Using the IAR Embedded Workbench IDE
4 Enter Project1 in the File name box, and set the Target CPU Family to dspic. Specify where you want to place your project files, for example in a projects directory. Then click Create to create the new project.
Figure 7: New Project dialog box
The Project window will be displayed.
5 If necessary, select Debug from the Targets drop-down list to display the Debug target:
Figure 8: Project window
ADDING FILES TO THE PROJECT This tutorial uses the source files tutor1.c and common.c, and the include files tutor1.h and common.h, which are all available in the tutor directory.
The tutor1.c program is a simple program using only standard features of the C language. It initializes an array with the ten first Fibonacci numbers and prints the result in the Terminal I/O window. The common.c program contains utility routines for the Fibonacci calculations.
dsPIC IAR Embedded Workbench™ IDE
30 User Guide
UDSPIC-1
IAR Embedded Workbench IDE tutorial
1 Choose Project>Files to display the Project Files dialog box. Locate the file tutor1.c in the file selection list in the upper half of the dialog box, and click Add
to add it to the Common Sources group.
Figure 9: Adding files to project
2 Locate the file common.c and add it to the group. Finally click Done to close the Project Files dialog box.
3 Click on the plus sign icon to display the file in the Project window tree display:
Figure 10: Displaying files in the Project window
The Common Sources group was created by the IAR Embedded Workbench when you created the project. More information about groups is available in the chapter The project model in Part 1. The IAR development tools in this guide.
Part 2. Tutorials 31
UDSPIC-1
Using the IAR Embedded Workbench IDE
SETTING PROJECT OPTIONS Now set up the target options to suit the processor configuration in this tutorial.
1 Select the Debug folder icon in the Project window and choose Project>Options. The Target options page in the General category is displayed.
Figure 11: Target settings
This tutorial uses the default settings: Target option
Default setting
Processor variant
With DSP Support
Runtime library
IAR CLIB
Float size
32bit doubles
Data model
Large
Table 3: Target settings for project1
Then set up the compiler options for the project.
dsPIC IAR Embedded Workbench™ IDE
32 User Guide
UDSPIC-1
IAR Embedded Workbench IDE tutorial
2 Select ICCDSPIC in the Category list to display the compiler option pages:
Figure 12: Setting compiler options
3 Make sure that the following options are selected on the appropriate pages of the compiler Options dialog box: Page
Setting
Code
Optimizations, Size: Low
Output
Generate debug info
List
Output list file Assembler mnemonics
Table 4: Compiler options for project1
4 When you have made these selections, click OK to set the options you have specified.
COMPILING THE SOURCE FILES
1 To compile the common.c file, select it in the Project window and choose Project>Compile. Alternatively, click the Compile button in the toolbar or select the Compile command from the pop-up menu that is available in the Project window. It appears when you click the right mouse button.
Part 2. Tutorials 33
UDSPIC-1
Using the IAR Embedded Workbench IDE
The progress will be displayed in the Messages window.
Figure 13: Compilation message
You can specify the amount of information to be displayed in the Messages window. Select Tools>Options and then select the Project page. Note that in these tutorials we will not be using the default option, which is to display all build messages.
2 Compile the file tutor1.c in the same manner. The IAR Embedded Workbench has now created new directories in your project directory. Since you have chosen the Debug target, a Debug directory has been created containing the new directories List, Obj, and Exe:
In the list directory, your list files from the Debug target will be placed. The list files have the extension lst and will be located here.
In the obj directory, the object files from the compiler and the assembler will be placed. These files have the extension r59 and will be used as input to the IAR XLINK Linker. In the exe directory, you will find the executable file. It has the extension d59 and will be used as input to the IAR C-SPY Debugger. Notice that this directory will be empty until you have linked the object files.
VIEWING THE LIST FILE
1 Open the list file tutor1.lst by choosing File>Open, and selecting tutor1.lst from the debug\list directory. Examine the list file, which contains the following information: The header shows the product version, information about when the file was created, and the command line version of the compiler options that were used: ########################################################################## # # # IAR DSPIC C/EC++ Compiler Vx.xxx dd/Mmm/yyyy hh:mm:ss # # Copyright 2002 IAR Systems. All rights reserved. # # # # Data model = Large # # Double size = 32 bits #
dsPIC IAR Embedded Workbench™ IDE
34 User Guide
UDSPIC-1
IAR Embedded Workbench IDE tutorial
# = # # Source file = D:\Program Files\IAR Systems\Embedded Workbench # # 3.1\dspic\tutor\tutor1.c # # Command line = -I "D:\Program Files\IAR Systems\Embedded Workbench # # 3.1\dspic\INC\" -I "D:\Program Files\IAR # # Systems\Embedded Workbench 3.1\dspic\INC\CLIB\" -lCN# # "D:\Program Files\IAR Systems\Embedded Workbench # # 3.1\dspic\projects\Debug\List\" --data_model=l -o # # "D:\Program Files\IAR Systems\Embedded Workbench # # 3.1\dspic\projects\Debug\Obj\" -e -z3 --no_cse # # --no_unroll --no_inline --no_code_motion --debug # # "D:\Program Files\IAR Systems\Embedded Workbench # # 3.1\dspic\tutor\tutor1.c" # # List file = D:\Program Files\IAR Systems\Embedded Workbench # # 3.1\dspic\projects\Debug\List\tutor1.lst # # Object file = D:\Program Files\IAR Systems\Embedded Workbench # # 3.1\dspic\projects\Debug\Obj\tutor1.r59 # # # ##########################################################################
The body of the list file shows the assembler code and binary code generated for each statement. It also shows how the variables are assigned to different segments: 1 2 3 4 5 6 7 8 9 10 11 12 13
/************************************************** * * ICC COMPILER TUTORIAL * Print the Fibonacci numbers * * Copyright 2002 IAR Systems. All rights reserved. * * $Revision: 1.3 $ * **************************************************/ #include "tutor1.h"
\ 14 \ \ \
000000 000002 15 16 17 18 19
\
In segment MEM_Z, align 2, keep-with-next int call_count; `call_count`: DS 2 REQUIRE `__INIT_MEM_Z`
/* Increase the 'call_count' variable by one. */ In segment CODE, align 4, keep-with-next
Part 2. Tutorials 35
UDSPIC-1
Using the IAR Embedded Workbench IDE
20 \ \
000000 21
\ \ \ \ \
000000 000000 000000 000000 000000 22
\ \
000000 000004 23
\
000008 24 25 26 27 28 29
/* Increase the 'call_count' variable. Get and print the assiciated Fibonacchi number. */
\ 30 \ \
000000 31
\ \ \ \ \
000000 000000 000000 000000 000000 32 33
\ \
000000 000000 34
\ \ \ \ \ \
000008 000008 00000C 00000C 000014 000014 35
\ \ \ \
dsPIC IAR Embedded Workbench™ IDE
36 User Guide
UDSPIC-1
void next_counter(void) `next_counter`: REQUIRE `?CLDSPIC_1_00_L00` { ; * Stack frame (at entry) * ; Param size: 0 ; Return address size: 4 ; Saved register size: 0 ; Auto size: 0 call_count += 1; /* from d_f_p */ ........ MOV #`call_count`,W0 1008E800 INC [W0],[W0] } 00000600 RETURN
000014 000014 000014 000014
In segment CODE, align 4, keep-with-next void do_foreground_process(void) `do_foreground_process`: REQUIRE `?CLDSPIC_1_00_L00` { ; * Stack frame (at entry) * ; Param size: 0 ; Return address size: 4 ; Saved register size: 0 ; Auto size: 0 unsigned int fib; next_counter(); ; Setup parameters for call to function next_counter ............ CALL `next_counter` fib = get_fib( call_count ); ; Setup parameters for call to function get_fib ........ MOV `call_count`,W0 ; REMOVED MOV#8: MOV W0,W0 ............ CALL `get_fib` ; DSP MODE; unknown ; REMOVED MOV#8: MOV W0,W0 put_fib( fib ); ; Setup parameters for call to function put_fib ; REMOVED MOV#8: MOV W0,W0 ; REMOVED MOV#8: MOV W0,W0 ............ GOTO `put_fib`
IAR Embedded Workbench IDE tutorial
36 37 38 39 40 41 42
}
/* Main program for tutor1. Prints the Fibonacchi numbers. */
\ 43 \ \
000000 44
\ \ \ \
000000 000000 000000 000000 45
\ \
000000 000004 46 47
\ \ \
init_fib(); 000008 ; Setup parameters for call to function init_fib 000008 ............ CALL `init_fib` 000010 02003700 BRA `??main_0`
48 49 50 51 \ \
000014
\
000014 52
\ \ \ \
00001C 000020 000024 53
\
In segment CODE, align 4, keep-with-next void main(void) main: REQUIRE `?CLDSPIC_1_00_L00` { ; * Stack frame (at entry) * ; Param size: 0 ; Return address size: 4 ; Auto size: 0 call_count=0; 00002000 MOV #0,W0 ........ MOV W0,`call_count`
000028
while( call_count < MAX_FIB ) { do_foreground_process(); `??main_1`: ; Setup parameters for call to function do_foreground_process ............ CALL `do_foreground_process` } `??main_0`: ........ MOV `call_count`,W0 6A00E100 CP W0,#10 FBFF3500 BRA LT, `??main_1` } 00000600 RETURN
The end of the list file shows the amount of stack, code, and data memory required, and contains information about error and warning messages that may have been generated: Maximum stack usage in bytes: Function
CSTACK
Part 2. Tutorials 37
UDSPIC-1
Using the IAR Embedded Workbench IDE
-------do_foreground_process -> next_counter -> get_fib -> put_fib main -> init_fib -> do_foreground_process next_counter
42 words in segment CODE 2 bytes in segment MEM_Z 42 words of CODE memory 2 bytes of DATA memory Errors: none Warnings: none
dsPIC IAR Embedded Workbench™ IDE
38 User Guide
UDSPIC-1
-----2 0 0 0 2 0 0 2
IAR Embedded Workbench IDE tutorial
LINKING THE PROGRAM Now you should set up the options for the IAR XLINK Linker™:
1 Select the Debug folder icon in the Project window and choose Projects>Options. Then select XLINK in the Category list to display the XLINK options pages:
Figure 14: XLINK options for project1
2 Make sure that the following options are selected on the appropriate pages of the Options dialog box: Page
Options
Output
Debug info with terminal I/O
List
Generate linker listing Segment map Module map
Include
XCL file name Override default
Input
Module status: Inherent
lnkdspic.xcl (linker command file in config directory) Table 5: Tutorial 1 XLINK options
If you want to examine the linker command file, use a suitable text editor, such as the IAR Embedded Workbench editor, or print a copy of the file, and verify that the entries match your requirements.
Part 2. Tutorials 39
UDSPIC-1
Using the IAR Embedded Workbench IDE
The definitions in the linker command file are not related to any particular hardware. The linker command file template supplied with the product can be used in the simulator, but you must adapt the linker command file to your actual hardware memory layout. For more information about linker command files, see the dsPIC IAR C/EC++ Compiler Reference Guide.
3 Click OK to save the XLINK options. Note: The chapter XLINK options in Part 3. The IAR Embedded Workbench IDE in this guide contains information about the XLINK options available in the IAR Embedded Workbench IDE. In the linker command file, the XLINK command line option -Z is used for segment control. This option is described in the IAR Linker and Library Tools Reference Guide. Now you should link the object file to generate code that can be debugged.
4 Choose Project>Link. The progress will be displayed in the Messages window:
Figure 15: Linker message
The result of the linking is a code file project1.d59 with debug information and a map file project1.map.
Viewing the map file
5 Examine the project1.map file to see how the segment definitions and code were placed into their physical addresses. Following are the main points of interest in a map file:
dsPIC IAR Embedded Workbench™ IDE
40 User Guide
UDSPIC-1
The header includes the options used for linking. The CROSS REFERENCE section shows the address of the program entry. The RUNTIME MODEL section shows the runtime model attributes that are used. The MODULE MAP shows the files that are linked. For each file, information about the modules that were loaded as part of the program, including segments and global symbols declared within each segment, is displayed.
IAR Embedded Workbench IDE tutorial
The SEGMENTS IN ADDRESS ORDER section lists all the segments that constitute the program.
Viewing the build tree
6 In the Project window, press the right mouse button and select Save as Text from the pop-up menu that appears. This creates a text file that allows you to conveniently examine the options for each level of the project. Notice that the text file will contain the command line equivalents to the options that you have specified in the IAR Embedded Workbench. The command line options are described in the dsPIC IAR C/EC++ Compiler Reference Guide and dsPIC IAR Assembler Reference Guide, respectively.
RUNNING THE PROGRAM The project1.d59 program is now ready to be run in the IAR C-SPY Debugger where you can watch variables, set a breakpoint, and print the program output in the Terminal I/O window.
1 Choose Project>Debugger. Alternatively, click the Debugger button in the toolbar. The following C-SPY Disassembly window will be opened:
Figure 16: Starting C-SPY
Part 2. Tutorials 41
UDSPIC-1
Using the IAR Embedded Workbench IDE
The current position in the program, which is the next assembler instruction to be executed, is shown highlighted in the Disassembly window. In disassembly mode, stepping is executed one assembler instruction at a time; the corresponding source statement is always available.
2 To inspect the source statement, double click the tutor1.c file in the Project window, if the source file is not open already.
3 With the tutor1.c window active, first step into the application with the Debug>Step Into command and then execute one step by choosing Debug>Step Over. Alternatively, click the Step Into and Step Over buttons in the toolbar. At source level, the Step Over and Step Into commands allow you to execute the program a statement or instruction at a time. Step Into continues stepping inside function or subroutine calls whereas Step Over executes each function call in a single step. See Stepping, page 168. The current position should be the call to the init_fib function:
Figure 17: Stepping in C-SPY
4 Select Debug>Step Into to execute init_fib one step at a time. Alternatively, click the Step Into button in the toolbar. When Step Into is executed you will notice that the active window changes to common.c since the function init_fib is located in this file.
dsPIC IAR Embedded Workbench™ IDE
42 User Guide
UDSPIC-1
IAR Embedded Workbench IDE tutorial
5 Execute Step Into twice until you reach the for loop:
Figure 18: Using Step Into in C-SPY
6 Then step until you are back in the header of the for loop. You will notice that the step points are on function call level, not on statement level. You can also step on statement level. Select Debug>Next statement to execute one statement at a time. Notice how this command differs from the Step command. Alternativley, click the Next statement button in the toolbar.
INSPECTING VARIABLES C-SPY allows you to watch variables or expressions in the source code, so that you can keep track of their values as you execute the program. You can look at a variable in a number of ways; for example by pointing at it in the source window with the mouse pointer, or by opening the Locals window.
1 Choose View>Locals to open the Locals window. If necessary, resize and rearrange the windows so that the Locals window is visible. The Locals window will show the current value of i.
Part 2. Tutorials 43
UDSPIC-1
Using the IAR Embedded Workbench IDE
2 Execute one more step to see how the value of i changes:
Figure 19: Inspecting variables in Locals window
You can also use the Watch window.
3 Choose View>Watch to open the Watch window. Setting a watchpoint
4 Set a watchpoint on the variable i using the following procedure: Click the dotted rectangle. In the entry field that appears, type i and press the Enter key. You can also drag and drop a variable into the Watch window.
5 Select the root array in the init_fib function, then drag and drop it into the Watch window. The Watch window will show the current value of i and root.
Figure 20: Watching variables in Watch window
dsPIC IAR Embedded Workbench™ IDE
44 User Guide
UDSPIC-1
IAR Embedded Workbench IDE tutorial
root is an array and can be watched in more detail. This is indicated in the Watch window by the plus sign icon to the left of the variable.
6 Execute some more steps to see how the values of i and root change. 7 Then select i and press Delete to remove the variable from the Watch window. SETTING BREAKPOINTS You can set breakpoints at functions or line numbers, or at assembler symbols or addresses. The most convenient way is usually to set breakpoints interactively, simply by positioning the cursor in or near a statement and then choosing the Toggle Breakpoint command. For additional information, see Toggle Breakpoint, page 143.
1 To display information about breakpoint execution, make sure that the Log window is open by choosing View>Log. You should now have the tutor1.c, common.c, Log, Project, and Watch windows on the screen; position them neatly before proceeding.
2 Set a breakpoint at the statement i++ using the following procedure: First click in this statement in the common.c window, to position the cursor. Then choose Edit>Toggle Breakpoint, Alternatively, click the Toggle Breakpoint button in the toolbar.
Part 2. Tutorials 45
UDSPIC-1
Using the IAR Embedded Workbench IDE
A breakpoint will be set at this statement. The statement will be highlighted and there will be an X in the margin to show that there is a breakpoint there:
Figure 21: Setting breakpoints
Executing up to a breakpoint
3 To execute the program until it reaches a breakpoint, choose Debug>Go. Alternatively, click the Go button in the toolbar. The program will execute up to the breakpoint you set. The Watch window will display the value of the root expression and the Log window will contain information about the breakpoint:
dsPIC IAR Embedded Workbench™ IDE
46 User Guide
UDSPIC-1
IAR Embedded Workbench IDE tutorial
Figure 22: Executing up to a breakpoint
4 Remove the breakpoint by choosing Edit>Breakpoints. In the Breakpoints dialog box, select the breakpoint and click Remove.
5 Then close the Breakpoints dialog box. CONTINUING EXECUTION
1 Open the Terminal I/O window, by choosing View>Terminal I/O, to display the output from the I/O operations.
2 To complete execution of the program, select Debug>Go. Alternatively, click the Go button in the toolbar.
Part 2. Tutorials 47
UDSPIC-1
Using the IAR Embedded Workbench IDE
Since no more breakpoints are encountered, C-SPY reaches the end of the program and a program exit reached message is printed in the Log window:
Figure 23: Reaching program exit in C-SPY
If you want to start again with the existing program, choose Debug>Reset, or click the Reset button in the toolbar.
3 To exit from C-SPY, choose Debug>Stop debugging. C-SPY also provides many other debugging facilities. Some of these—for example using C-SPY macros and disassembly debugging—are described in the following tutorial chapters. For complete information about the features of C-SPY, see the chapter C-SPY Debugger reference in Part 3. The IAR Embedded Workbench IDE in this guide.
dsPIC IAR Embedded Workbench™ IDE
48 User Guide
UDSPIC-1
Compiler tutorials This chapter introduces you to some of the compiler’s dsPIC-specific features: In the first tutorial, the Fibonacci numbers will be read from an on-chip peripheral communication module (UART). This will show the usage of the dsPIC IAR C/EC++ Compiler intrinsic functions and the interrupt keyword. Finally, the program is run using the C-SPY interrupt system in conjunction with complex breakpoints and macros. In the second tutorial, Embedded C++ is used to create an EC++ class. This class is then used to create two independent objects.
Before running these tutorials, you should be familiar with the IAR Embedded Workbench and the IAR C-SPY Debugger as described in the previous chapter, IAR Embedded Workbench IDE tutorial.
Using interrupts, breakpoints, and macros In this tutorial the UART functionality is used for getting the Fibonacci values. UART setup code and an interrupt handler are added to the source program. Then the C-SPY interrupt simulation is activated and the macro system is used for reading values from a text file and inserting them into the UART receive buffer. The following lines define the interrupt function: // define the interrupt handler #pragma vector=0x26 __interrupt void uartReceiveHandler( void )
The interrupt handler will read the received Fibonacci value from the UART receive register, U1RXREG, and place it in the fib variable. It will then print the value by using the put_fib function. The main program enables interrupts and starts printing periods (.) in the foreground process while waiting for interrupts. For detailed information about the extended keywords and #pragma directives used in this tutorial, see the dsPIC IAR C/EC++ Compiler Reference Guide.
THE TUTOR2.MAC MACRO FILE The C-SPY macro file, tutor2.mac, contains both system and user-defined macros. Notice that this example is not intended as an exact simulation; the purpose is to illustrate a situation where C-SPY macros can be useful. For detailed information about macros, see the chapter C-SPY macros in Part 3. The IAR Embedded Workbench IDE in this guide.
Part 2. Tutorials 49
UDSPIC-1
Using interrupts, breakpoints, and macros
Initializing the system The macro execUserSetup() is automatically executed during C-SPY setup. First a message is printed in the Log window to confirm that this macro has been executed. __var _fileHandle; __var _interruptID; __var _breakID; execUserSetup() { __message "execUserSetup() called\n"; // Call the tutor2 setup Tutor2Setup (); }
Using interrupts and breakpoints to simulate incoming values The execUserSetup() macro calls the Tutor2Setup() user-defined macro. The tutor2.txt file contains the Fibonacci series to be fed into the UART. The file is opened for reading in ASCII mode, which means that the data in the file is in hexadecimal notation, but without the 0x prefix. The _ _orderInterrupt system macro initializes the interrupt system. The __setBreak system macro is used for setting a breakpoint that enables the simulation of the UART functionality. Tutor2Setup() { // Open the text file for ASCII reading // Put in the appropriate path to the tutor2.txt file _fileHandle = __openFile( "$TOOLKIT_DIR$\\tutor\\tutor2.txt", "r" ); if( !_fileHandle ) { __message "could not open file" ; } _interruptID = __orderInterrupt( "U1RX", 4000, 2000, 0, 0, 100 ); if( -1 == _interruptID ) { __message "ERROR: syntax error in interrupt description"; } // Set up the immediate breakpoint _breakID = __setSimBreak( "U1RXREG", "R", "Access()" ); }
dsPIC IAR Embedded Workbench™ IDE
50 User Guide
UDSPIC-1
Compiler tutorials
The _ _orderInterrupt system macro makes C-SPY generate interrupts. The following parameters are used: U1RX
Specifies which interrupt to use; the name is defined in the *.ddf file.
4000
Specifies the activation moment for the interrupt. The interrupt is activated when the cycle counter has passed this value.
2000
Specifies the repeat interval for the interrupt, measured in clock cycles.
0
Time variance, not used here.
0
Latency, not used here.
100
Specifies probability. 100% specifies that the interrupt will occur at the given frequency. Another percentage could be used for simulating a more randomized interrupt behavior.
During execution, C-SPY will wait until the cycle counter has passed the activation time. Then it will, with 100% certainty, generate an interrupt approximately every 2000 cycles. The input to the UART is simulated by setting an immediate read breakpoint on the U1RXREG address and connecting the user-defined Access macro to it. Breakpoints are used to simulate the incoming values to the UART. The following parameters are used for the __setSimBreak system macro: "U1RXREG"
Receive buffer address. In this case, an SFR register defined in the *.ddf file.
"R"
The breakpoint type (read)
"Access()"
The macro connected to the breakpoint.
During execution, when C-SPY detects a read from the U1RXREG address, it will temporarily halt the simulation and run the Access macro. C-SPY will then resume the simulation and start by reading the receive buffer value, now properly inserted.
Part 2. Tutorials 51
UDSPIC-1
Using interrupts, breakpoints, and macros
The Access macro is executed whenever C-SPY tries to read the value in the U1RXREG address, as defined in the __setBreak macro: Access() { __message "Access() called\n"; // In this tutorial we read the fib values from a file __var _fibValue; if( 0 == __readFile( _fileHandle, &_fibValue ) ) { U1RXREG = _fibValue; } else { __message "error reading value from file"; } __message "U1RXREG = ", _fibValue:%X,"\n"; }
First a message is printed to confirm that this user-defined macro has been executed. Next a value is read from the file.
Exiting the system The macro execUserExit() is executed automatically during C-SPY exit. It prints a message and calls the user-defined macro Tutor2Shutdown: execUserExit() { __message "execUserExit() called\n"; // Call the Tutor2 shutdown Tutor2Shutdown(); } Tutor2Shutdown() { __cancelInterrupt( _interruptID ); __clearBreak( _breakID ); __closeFile( _fileHandle ); }
The interrupt is cancelled and the U1RXREG breakpoint is cleared. Finally the input file is closed.
dsPIC IAR Embedded Workbench™ IDE
52 User Guide
UDSPIC-1
Compiler tutorials
COMPILING AND LINKING THE TUTOR2.C PROGRAM
1 Create a new project in the IAR Embedded Workbench, for example project2. 2 Add the files common.c and tutor2.c to it. 3 Select Project>Options. Use the default settings in the General, ICCDSPIC, and XLINK categories.
4 In the C-SPY category, specify the macro file to be used by setting the Use setup file option to: ....\Embedded Workbench 3.n\dspic\tutor\tutor2.mac
substituting .... with whatever is the appropriate path for your installation. Alternatively, use argument variables to specify the path, see Table 30, Argument variables, page 161, for details. Note: Macro files can also be loaded via the Options menu in the IAR C-SPY Debugger, see Macros, page 213. Due to its contents, the tutor2.mac file cannot, however, be used in this manner because the execUserSetup macro will not be activated until you load the project2.d59 file.
Figure 24: Specifying setup macro file
The interrupt system requires a device description file to be specified.
5 Set the Use device description file option to iotutor.ddf. 6 Select Run to main and click OK.
Part 2. Tutorials 53
UDSPIC-1
Using interrupts, breakpoints, and macros
7 Compile and link the project by choosing Project>Make. Alternatively, select the Make button from the toolbar. The Make command compiles and links those files that have been modified.
RUNNING THE TUTOR2.C PROGRAM
1 Start the IAR C-SPY Debugger to run the project2 project. The tutor2.c window will be displayed:
Figure 25: C-SPY windows
If warning or error messages should appear in the Messages window, make sure that the breakpoint has been set, that the interrupt has been registered, and that the tutor2.mac macro file contains the correct path to tutor2.txt.
dsPIC IAR Embedded Workbench™ IDE
54 User Guide
UDSPIC-1
Compiler tutorials
2 Examine the Log window. It should have the following contents: Line 1 Line 2 Line 3
Figure 26: Log window contents
If line 1 and 3 are missing, you have forgotten to specify the setup file tutor2.mac. Select Project>Options and add the macro file in the C-SPY category; see Figure 24, Specifying setup macro file, page 53. If the message "could not open file "$TOOLKIT\\tutor\tutor2.txt"" should appear, your project file is in another directory than the recommended one. Open the tutor2.mac file in the tutor directory and change the path accordingly. If you need to edit the macro file, select Debug>Macros to display the Macro Configuration dialog box. Open the tutor2.mac file by double-clicking on a user macro name, and edit it as required. It is normally sufficient to register the macro again after saving the mac file.
3 Step through the program and stop when it reaches the while loop, which waits for input.
4 Make the tutor2.c source window active and locate the uartReceiveHandler function.
5 Place the cursor on the ++callcount; statement in this function and set a breakpoint by selecting Edit>Toggle Breakpoint, or click the Toggle Breakpoint button in the toolbar. Alternatively, use the pop-up menu. If you want to inspect the details of the breakpoint, select Edit>Breakpoints. The setup file tutor2.mac adds a simulated interrupt to C-SPY. If you want to view the interrupt settings, select Simulator>Interrupts to display the Interrupts dialog box.
Part 2. Tutorials 55
UDSPIC-1
Using interrupts, breakpoints, and macros
To display its settings, select the interrupt in the list of installed interrupts:
Figure 27: Inspecting the interrupt settings
Interrupt is the vector name and Description is the definition that the simulator uses to be able to simulate the interrupt correct. If empty, the description from the chosen ddf file is used. Activation Time shows when the first activation is to occur and Repeat Interval is the time in cycles from the first interrupt until the next one. Now you have a breakpoint in the interrupt function and an interrupt that will be simulated every 2000 cycles. When you have examined the settings, just close the Interrupt dialog box.
6 Open the Terminal I/O window and run the program by choosing Debug>Go or click the Go button in the toolbar. The program should stop in the interrupt function.
7 Click Go again in order to see the next number being printed in the Terminal I/O window. Since the main program has an upper limit on the Fibonacci value counter, the tutorial program will soon reach the exit label and stop.
dsPIC IAR Embedded Workbench™ IDE
56 User Guide
UDSPIC-1
Compiler tutorials
The Terminal I/O window will display the Fibonacci series:
Figure 28: Printing the Fibonacci values in the Terminal I/O window
DISPLAYING FUNCTION CALLS When the interrupt has occurred, you can study the sequence of calls to the current position in the Call Stack window.
1 Choose View>Call Stack to open the Call Stack window.
Figure 29: Call Stack window
2 Reset the program and Go to the breakpoint in the uartReceiveHandler function. The Call Stack window will show a list of function calls, with the current function at the top.
3 Double click the function calls and trace back to determine when the interrupt occurred and the different values of variables in the different function instances.
Part 2. Tutorials 57
UDSPIC-1
Using Embedded C++
Using Embedded C++ This tutorial will demonstrate how to use the dsPIC Embedded C++ features. The tutorial consists of two files: fibonacci.cpp that creates a class fibonacci that can be used to extract series of Fibonacci numbers, and tutor3.cpp that creates two objects and extracts two sequences of Fibonacci numbers using the fibonacci class. To demonstrate that the two objects are independent of each other, the numbers are extracted at different speed. A number is extracted from fib1 each turn in the loop while a number is extracted from fib2 only every second turn. fib1 is created using the default constructor while the definition of fib2 uses the
constructor that takes an integer as its argument. A copy of the tutor3.cpp program is provided with the product.
COMPILING AND LINKING THE TUTOR3.CPP PROGRAM
1 Create a new project, project3, in the IAR Embedded Workbench. 2 Add the files fibonacci.cpp and tutor3.cpp to project3. 3 Choose Project>Options and enable the following options: Category
Page
Enabled option
General
Target
IAR DLIB
ICCDSPIC
Language
Enable Embedded C++ syntax Language extensions
Table 6: Project options for Embedded C++ tutorial
4 Compile and link the program by choosing Project>Make. Alternatively, select the Make button from the toolbar. The Make command compiles and links those files that have been modified.
5 Start the IAR C-SPY Debugger by selecting Project>Debugger.
dsPIC IAR Embedded Workbench™ IDE
58 User Guide
UDSPIC-1
Compiler tutorials
The C-SPY Disassembly window will be displayed:
Figure 30: Tutor3.cpp Disassembly window
SETTING A BREAKPOINT AND EXECUTING TO IT
1 Open the tutor3.cpp editor window if it is not already open. 2 Set a breakpoint on the C++ object fib1 on the line fibonacci fib1;
to see how the object is constructed.
Part 2. Tutorials 59
UDSPIC-1
Using Embedded C++
Figure 31: Setting a breakpoint in tutor3.cpp
3 Then choose Debug>Go, or click the Go button in the toolbar. The cursor should now be placed at the breakpoint.
4 Now choose Debug>Step Into or click the Step Into button in the toolbar to step into the constructor, and Step Out again.
5 Then Step Over three more times and Step Into once until you are in the next function in the fibonacci.cpp editor window.
6 Use the Go to function button in the lower left corner of the editor window to find and go to the nth function. Set a breakpoint on the function call nth(n-1)at the line value = nth(n-1) + nth(n-2);
7 Choose Edit>Breakpoints to edit this breakpoint. In the Breakpoints dialog box, select the breakpoint and set the value in the Skip count text box to 4 and click Apply.
dsPIC IAR Embedded Workbench™ IDE
60 User Guide
UDSPIC-1
Compiler tutorials
Figure 32: Setting the breakpoint condition
8 Then close the dialog box. LOOKING AT THE FUNCTION CALLS
1 Choose Debug>Go to execute the application until the breakpoint condition is reached.
2 When C-SPY stops at the breakpoint, choose View>Call Stack to open the Call Stack window.
Figure 33: Inspecting the function calls
There are five instances of function nth() displayed on the call stack. Since the Call Stack window displays the values of the function parameters, you can see the different values of n in the different function instances.
Part 2. Tutorials 61
UDSPIC-1
Using Embedded C++
You can also open the Register window to see how it is updated as you trace the function calls by double clicking on the function instances.
PRINTING THE FIBONACCI NUMBERS
1 Open the Terminal I/O window from the View menu. 2 Run the program to the end and verify the Fibonacci sequences being printed:
Figure 34: Printing Fibonacci sequences
dsPIC IAR Embedded Workbench™ IDE
62 User Guide
UDSPIC-1
Assembler tutorials These tutorials illustrate how you might use the IAR Embedded Workbench™ to develop a series of simple machine-code programs for the dsPIC microcontroller. The first tutorial shows how to assemble and link a small assembler program and then run it using the IAR C-SPY™ Debugger. The second tutorial demonstrates how to create library modules and use the IAR XLIB Librarian™ to maintain files of modules.
Before running these tutorials, you should be familiar with the IAR Embedded Workbench and the IAR C-SPY Debugger as described in the chapter IAR Embedded Workbench IDE tutorial.
Creating and running an assembler project This assembler tutorial illustrates how to assemble and link a basic assembler program, and then run it.
CREATING A NEW PROJECT
1 Start the IAR Embedded Workbench and create a new project called project4 in the projects directory.
2 Add the file first.s59 to the project. The procedure is described in Adding files to the project, page 30. Note that you may have to change the viewing filter in the Files of type drop-down list to be able to see the file. The first assembler tutorial program is a simple count loop which counts up the registers W6 and W7 in binary-coded decimal. A copy of the program first.s59 is provided with the product in the tutor directory.
ASSEMBLING THE PROGRAM Now you should set up the assembler options for the project.
Part 2. Tutorials 63
UDSPIC-1
Creating and running an assembler project
1 Select the Debug folder icon in the Project window, choose Projects>Options, and select ADSPIC in the Category list to display the assembler options pages:
Figure 35: Assembler code generation options
2 Make sure that the following options are selected on the appropriate pages of the Options dialog box: Page
Option
Output
Generate debug information
List
Output list file
Table 7: Tutorial 4 assembler options
This tutorial uses the default options in the General category.
3 Click OK to set the options you have specified. 4 To assemble the file, select it in the Project window and choose Project>Compile.
dsPIC IAR Embedded Workbench™ IDE
64 User Guide
UDSPIC-1
Assembler tutorials
The progress will be displayed in the Messages window:
Figure 36: Messages window
VIEWING THE FIRST.LST LIST FILE The listing is created in a file first.lst in the directory specified in the General options page; by default this is debug\list.
1 Open the list file by choosing File>Open and selecting first.lst from the appropriate folder.
Header The header section contains product version information, the date and time when the file was created, and also specifies the options that were used: ########################################################################## IAR DSPIC Assembler Vx.xxx dd/Mmm/yyyy Copyright 2002 IAR Systems. All rights reserved. Source file
=
Command line =
List file
=
Object file
=
hh:mm:ss
D:\Program Files\IAR Systems\Embedded Workbench 3.1\dspic\tutor\first.s59 "-oD:\Program Files\IAR Systems\Embedded Workbench 3.1\dspic\projects\Debug\Obj\" -I "D:\Program Files\IAR Systems\Embedded Workbench 3.1\dspic\INC\" -l "D:\Program Files\IAR Systems\Embedded Workbench 3.1\dspic\projects\Debug\List\" --debug -M{} "D:\Program Files\IAR Systems\Embedded Workbench 3.1\dspic\tutor\first.s59" D:\Program Files\IAR Systems\Embedded Workbench 3.1\dspic\projects\Debug\List\first.lst D:\Program Files\IAR Systems\Embedded Workbench 3.1\dspic\projects\Debug\Obj\first.r59
##########################################################################
Part 2. Tutorials 65
UDSPIC-1
Creating and running an assembler project
Body The body of the listing contains the following fields of information:
The line number in the source file. Lines generated by macros will, if listed, have a . (period) in the source line number field; for information about assembler macros, see the dsPIC IAR Assembler Reference Guide. The address field shows the location in memory, which can be absolute or relative depending on the type of segment. The notation is hexadecimal. The data field shows the data generated by the source line. The notation is hexadecimal. Unsolved values are represented by ..... (periods); two periods signify one byte. These unsolved values will be solved during the linking process. The assembler source line.
CRC The end of the file contains the CRC which can be used for verifying the integrity of the assembled code, and a summary of errors and warnings that were generated. 4b3a CRC checksum in module first Errors: none Warnings: none
Note: The CRC number depends on the date of assembly, and may vary.
Symbol and cross-reference table When you specify the option Include cross-reference, or if the LSTXRF+ directive has been included in the source file, a symbol and cross-reference table is produced:
Segments
Symbols
Segment Type Mode ---------------------------------------__aseg untyped abs Org:0x0 CODE untyped rel Label Mode Type Segment Value/Offset ----------------------------------------------------------------------done_it rel label CODE 0x16 loop rel label CODE 0x4 main rel label, unref CODE 0x0
Figure 37: Symbol and cross-reference table in assembler list file
dsPIC IAR Embedded Workbench™ IDE
66 User Guide
UDSPIC-1
Assembler tutorials
The following information is provided for each symbol in the table: Information
Description
Label
The label’s user-defined name.
Mode
ABS (Absolute), or REL (Relative).
Type
The label’s type.
Segment
The name of the segment to which this label is defined relative.
Value/Offset
The value (address) of the label within the current module, relative to the beginning of the current segment part.
Table 8: Symbol and cross-reference table
If you make any errors when writing a program, these will be displayed on the screen during the assembly and will be listed in the list file. If this happens, return to the editor by double-clicking on the error message. Correct all the mistakes, save the source file, and try assembling it again. Assuming that the source assembled successfully, the file first.r59 will also be created, containing the linkable object code.
LINKING THE PROGRAM Before linking the program you need to set up the linker options for the project.
1 Select the Debug folder in the Project window. 2 Then choose Project>Options and select XLINK in the Category list to display the linker option pages.
Part 2. Tutorials 67
UDSPIC-1
Creating and running an assembler project
Figure 38: XLINK output options
3 Specify the following XLINK options: Page
Option
Include
Library Ignore CSTARTUP in library XCL file name Override default Select the file lnkasm.xcl in the config directory
Table 9: Tutorial 4 XLINK options
4 Select C-SPY in the Category list and deselect Run to main. 5 Click OK to set the options you have specified. 6 To link the file, choose Project>Link.
dsPIC IAR Embedded Workbench™ IDE
68 User Guide
UDSPIC-1
Assembler tutorials
As before, the progress during linking is shown in the Messages window:
Figure 39: Messages window
The output file will be called project4.d59.
RUNNING THE PROGRAM
1 Start C-SPY to run the example program. 2 Open the Register window by selecting View>Register. Position the windows conveniently.
3 Choose Debug>Step Over, or click the Step Over button in the toolbar. When you repeatedly click Step Over, you can watch the W6 and W7 registers count in binary-coded decimal.
Figure 40: Registers counting during program execution
Part 2. Tutorials 69
UDSPIC-1
Working with library modules
Working with library modules This tutorial demonstrates how to create library modules and use the IAR XLIB Librarian™ to maintain files of modules.
USING LIBRARIES If you are working on a large project you will soon accumulate a collection of useful routines that are used by several of your programs. To avoid having to assemble a routine each time the routine is needed, you can store such routines as object files, that is, assembled but not linked. A collection of routines in a single object file is referred to as a library. It is recommended that you use library files to create collections of related routines, such as a device driver. Use the IAR XLIB Librarian to manipulate libraries. It allows you to:
Change modules from PROGRAM to LIBRARY type, and vice versa Add or remove modules from a library file Change the names of entries List module names, entry names, etc.
The main.s59 program The main.s59 program simply uses a routine called max to shift the contents of register W0 to the maximum value of the word registers W1 and W2. The EXTERN directive declares max as an external symbol, to be resolved at link time. A copy of the program is provided with the product in the tutor directory.
The library routines The two library routines will form a separately assembled library. It consists of the max routine called by main, and a corresponding min routine, both of which operate on the contents of the word registers W1 and W2 and return the result in W0. The file containing these library routines is called maxmin.s59, and a copy is provided with the product in the tutor directory. The routines are defined as library modules by the MODULE directive, which instructs the IAR XLINK Linker™ to include the modules only if they are called by another module. The PUBLIC directive makes the max and min entry addresses public to other modules. For detailed information about the MODULE and PUBLIC directives, see the dsPIC IAR Assembler Reference Guide.
dsPIC IAR Embedded Workbench™ IDE
70 User Guide
UDSPIC-1
Assembler tutorials
CREATING A NEW PROJECT
1 Create a new project called project5. 2 Add the files main.s59 and maxmin.s59 to the new project. To assemble and link the main.s59 and maxmin.s59 source files, you must select the correct linker command file.
3 Select Project>Options. Then select XLINK in the Category list and set the following options: Page
Option
Include
Library Ignore CSTARTUP in library XCL file name Override default Select the file lnkasm.xcl in the config directory
Table 10: Tutorial 5 XLINK options
This tutorial uses the default options in the General and ADSPIC categories.
4 To assemble and link the main.s59 and the maxmin.s59 files, select Project>Make. Alternatively, select the Make button in the toolbar. If a warning should appear, you can just ignore it. For more information about the XLINK options, see the IAR Linker and Library Tools Reference Guide.
USING THE IAR XLIB LIBRARIAN Once you have assembled and debugged modules intended for general use, like the max and min modules, you can add them to a library using the IAR XLIB Librarian. The IAR Embedded Workbench IDE is preconfigured to include XLIB as a menu command in the Tools menu.
1 Select Tools>XLIB to display the XLIB window:
Part 2. Tutorials 71
UDSPIC-1
Working with library modules
Figure 41: XLIB window
You can now enter XLIB commands at the * prompt.
2 First you define the processor: DEFINE-CPU dspic
Giving XLIB options To make sure the library file is created in a suitable directory, you should change to the lib directory in your dsPIC installation.
3 Enter the following command on a single line, using the correct path to your IAR Embedded Workbench installation: cd "c:\program files\iar systems\embedded workbench 3.2\dspic\lib"
You should now extract the modules you want from maxmin.r59 into a library called math.r59.
4 Enter the command: FETCH-MODULES
5 Enter the following information when prompted by the IAR XLIB Librarian: Prompt
Response
Source file
Type ..\projects\debug\obj\maxmin and press Enter.
Destination file
Type math and press Enter.
Start module
Press Enter to use the default start module, which is the first in the file.
End module
Press Enter to use the default end module, which is the last in the file.
Table 11: XLIB FETCH-MODULES parameters
This creates the file math.r59 which contains the code for the max and min routines.
dsPIC IAR Embedded Workbench™ IDE
72 User Guide
UDSPIC-1
Assembler tutorials
6 Confirm this by typing: LIST-MODULES
7 Enter the following information when prompted by the IAR XLIB Librarian: Prompt
Response
Object file
Type math and press Enter.
List file
Press Enter to display the list file on the screen.
Start module
Press Enter to start from the first module.
End module
Press Enter to end at the last module.
Table 12: XLIB LIST-MODULES parameters
You could use the same procedure to add further modules to the math library at any time.
8 Finally, leave the librarian by typing: EXIT
or QUIT
For more information about the XLIB commands, see the IAR Linker and Library Tools Reference Guide.
USING THE LIBRARY IN THE PROJECT You can now use the math library file in your project instead of the maxmin source file.
1 Select Project>Files and delete the source file maxmin.s59 from the project. 2 Open the Options dialog box by selecting Project>Options. 3 Select XLINK in the Category list and change the following option: Page
Option
Include
Library Override default library name Enter the library name math
Table 13: Changing XLINK options
4 Assemble and link the project again and check that no errors are reported. You have now successfully used the library that you created with the IAR XLIB Librarian.
Part 2. Tutorials 73
UDSPIC-1
Working with library modules
dsPIC IAR Embedded Workbench™ IDE
74 User Guide
UDSPIC-1
Advanced tutorials These tutorials explore some of the more advanced features of the IAR C-SPY™ Debugger: The first tutorial shows how to define complex breakpoints and inspect the function call stack. The second tutorial shows how to debug in disassembly mode. The third tutorial demonstrates how to create a project containing both C or Embedded C++ and assembler language source files.
Before running these tutorials, you should be familiar with the IAR Embedded Workbench and the IAR C-SPY Debugger as described in the chapter IAR Embedded Workbench IDE tutorial.
Using complex breakpoints C-SPY allows you to define complex breakpoint conditions, to detect when your program has reached a particular state of interest.
SETTING UP THE PROJECT
1 In the IAR Embedded Workbench IDE, create a new project called project6 and add the files tutor1.c and common.c to it.
2 Make sure that the following project options are set: Category
Page
Option
General
Target
Data model: Large (default) Runtime library: IAR CLIB Float size: 32bit doubles
ICCDSPIC
Code
Size optimization: Low (default)
Output
Generate debug info (default)
List
Output list file
XLINK
Output
Debug info with terminal I/O (default)
C-SPY
C-SPY Settings
Run to main
Table 14: Project options for project6
3 Click OK to set the options. 4 Select Project>Make, or click the Make button in the toolbar to compile and link the files. This creates the project6.d59 file.
Part 2. Tutorials 75
UDSPIC-1
Using complex breakpoints
5 Start C-SPY to run the project6.d59 program. DEFINING A COMPLEX BREAKPOINT
1 In the file tutor1.c, click Step Over once. The current position should be the call to the init_fib function.
2 Click Step Into to move to the init_fib function in the file common.c. 3 Set a breakpoint at the statement i++. Now you should modify this breakpoint so that C-SPY detects when the value of i exceeds 5.
4 Choose Edit>Breakpoints to display the Breakpoints dialog box. 5 Select the breakpoint in the Breakpoints list to display information about the breakpoint you have defined:
Figure 42: Displaying breakpoint information
Currently the breakpoint is triggered when a fetch occurs from the location corresponding to the source statement. Now you should add a condition to the breakpoint.
6 Enter i>5 in the Expression box and, if necessary, select Condition True.
dsPIC IAR Embedded Workbench™ IDE
76 User Guide
UDSPIC-1
Advanced tutorials
7 Click Apply to modify the breakpoint with the settings you have defined:
Figure 43: Modifying breakpoints
8 Click OK to close the Breakpoints dialog box. 9 Open the Watch window and add the variable i. The procedure is described in Inspecting variables, page 43.
EXECUTING THE PROGRAM
1 Position the common.c, tutor1.c, Project, and Watch windows conveniently. 2 Execute the program until the breakpoint condition is true by choosing Debug>Go, or clicking the Go button in the toolbar.
Part 2. Tutorials 77
UDSPIC-1
Using complex breakpoints
The program will stop when it reaches a breakpoint and the value of i exceeds 5:
Figure 44: Executing in C-SPY until a breakpoint condition is true
Executing up to the cursor A convenient way of executing up to a particular statement in the program is to use the Run to Cursor option.
3 First remove the existing breakpoint. Use the Edit>Breakpoints menu command and remove the breakpoint, or toggle the breakpoint off from the pop-up menu.
4 Remove the variable i from the Watch window. Select the variable in the Watch window and press the Delete key.
5 Add root instead to watch the array during execution. 6 Position the cursor in the source window in the statement: return root[nr-1];
in the get_fib function.
7 Choose Debug>Run to Cursor, or click the Run to Cursor button in the toolbar. The program will then execute up to the statement at the cursor position.
8 Expand the contents of the root array to view the result:
dsPIC IAR Embedded Workbench™ IDE
78 User Guide
UDSPIC-1
Advanced tutorials
Figure 45: Examining the root array in the Watch window
DISPLAYING FUNCTION CALLS The program is now executing statements inside a function called from main. You can display the sequence of calls to the current position in the Call Stack window.
1 Choose View>Call Stack to open the Call Stack window. You will see a list of function calls, with the current function at the top.
2 Double click the init_fib function.
Figure 46: Inspecting the call stack
C-SPY now focuses on that call frame instead. Notice also how the editor and Watch windows are updated to reflect the information in that call frame. If you had had the Locals, Registers, and Disassembly windows open as well, they would also have been updated “live”.
3 You can now close both the Call Stack window and the Watch window.
Part 2. Tutorials 79
UDSPIC-1
Debugging in disassembly mode
Debugging in disassembly mode Although debugging with C-SPY is usually quicker and more straightforward in C/EC++ source mode, some demanding applications can only be debugged in disassembly mode where each step corresponds to one assembler instruction. C-SPY lets you switch freely between the two modes. Open the Disassembly window by selecting View>Disassembly, if it was not open already. You will see the assembler code corresponding to the current C statement.
Figure 47: Debugging in disassembly mode
MONITORING MEMORY The Memory window allows you to monitor selected areas of memory. In the following example the memory corresponding to the variable root will be monitored.
1 Select View>Memory to open the Memory window. 2 Position the Disassembly and Memory windows conveniently on the screen. 3 Make the common.c window active and select root. Then drag it from the C source window and drop it into the Memory window.
dsPIC IAR Embedded Workbench™ IDE
80 User Guide
UDSPIC-1
Advanced tutorials
The memory contents in the Memory window corresponding to root will be selected:
Figure 48: Monitoring memory
4 Click the x2 button in the Memory window toolbar, since 16-bit data units are displayed:
Figure 49: Displaying memory contents as 32-bit units
Notice that the 10 units have been initialized by the init_fib function of the C program. You can change the memory contents by editing the values in the Memory window. Just select the memory contents that you want to edit and type the desired value.
5 Close the Memory window. MONITORING REGISTERS The Register window allows you to monitor the contents of the processor registers and modify their contents.
1 Make the Disassembly window active. 2 Select View>Register to open the Register window.
Part 2. Tutorials 81
UDSPIC-1
Creating a combined C and assembler project
Figure 50: Register window
3 Use Step Over to execute the next instructions, and watch how the values change in the Register window.
4 Then close the Register window.
Creating a combined C and assembler project In large projects it may be convenient to use source files written in both C or Embedded C++ and assembler language. This tutorial demonstrates how they can be combined by substituting the file common.c with the assembler file common.s59 and compiling the project.
1 Return to or open project6 in the IAR Embedded Workbench. The project should contain the files tutor1.c and common.c, which you will now turn into the assembler file common.s59.
2 In the Project window, select the file common.c. 3 Then select Project>Options. You will notice that only the ICCDSPIC and XLINK categories are available.
4 In the ICCDSPIC category, select Override inherited settings and set the following options: Page
Option
List
Deselect Output list file. Select Output assembler file. Select the suboption Include source.
Table 15: Compiler options for modified project6
dsPIC IAR Embedded Workbench™ IDE
82 User Guide
UDSPIC-1
Advanced tutorials
Figure 51: Compiler list file options
5 Then click OK and return to the Project window. 6 Compile each of the files. 7 To see how the C or Embedded C++ code is represented in assembler language, open the file common.s59 that was created from the file common.c (you will find the file in the debug\list subdirectory).
8 Modify project6 by removing the file common.c and adding the file common.s59 instead.
9 Select common.s59 in the Project window and compile it; this will ensure that the linker will use the object file created from the assembler file.
10 Select Project>Make to relink project6. 11 Start C-SPY to run the project6.d59 program and see that it behaves like in the previous tutorials.
Part 2. Tutorials 83
UDSPIC-1
Creating a combined C and assembler project
dsPIC IAR Embedded Workbench™ IDE
84 User Guide
UDSPIC-1
Part 3. The IAR Embedded Workbench IDE This part of the dsPIC IAR Embedded Workbench™ IDE User Guide contains the following chapters: General options Compiler options Assembler options XLINK options C-SPY options IAR Embedded Workbench IDE reference Introduction to the IAR C-SPY Debugger C-SPY expressions C-SPY macros C-SPY Debugger reference.
85
UDSPIC-1
86
UDSPIC-1
General options This chapter describes how to set general options in the IAR Embedded Workbench™. These include how to specify the runtime options, as well as how to set up output directories.
Setting general options To set general options in the IAR Embedded Workbench, select Project>Options to display the Options dialog box. The Target page in the General category is displayed:
Figure 52: Setting general options
Click the tab corresponding to the type of options that you want to view or change. The following sections give full descriptions of each general option.
Part 3. The IAR Embedded Workbench IDE 87
UDSPIC-1
Target
Target The Target options specify processor variant, runtime library, float size, and data model for the toolkit.
Figure 53: Target options
PROCESSOR VARIANT Use this option to select the processor variant for your project.
RUNTIME LIBRARY Use this option to select a runtime library. The default is IAR CLIB library. For Embedded C++ projects you must use the IAR DLIB library. Your choice of library will affect a few other options such as include paths for the dsPIC IAR C/EC++ Compiler and IAR XLINK Linker™. See Runtime libraries, page 9, for information about the two libraries.
FLOAT SIZE Use this option to select the floating point size for your project.
DATA MODEL Use this option to select the data model for your project. For a description of the available options, see the dsPIC IAR C/EC++ Compiler Reference Guide.
dsPIC IAR Embedded Workbench™ IDE
88 User Guide
UDSPIC-1
General options
Output directories The Output directories options allow you to specify directories for executable files, object files, and list files. Notice that incomplete paths are relative to your project directory.
Figure 54: Output directories
Executables Use this option to override the default directory for executable files. Enter the name of the directory where you want to save executable files for the project. Object files Use this option to override the default directory for object files. Enter the name of the directory where you want to save object files for the project. List files Use this option to override the default directory for list files. Enter the name of the directory where you want to save list files for the project.
Part 3. The IAR Embedded Workbench IDE 89
UDSPIC-1
Output directories
dsPIC IAR Embedded Workbench™ IDE
90 User Guide
UDSPIC-1
Compiler options This chapter explains how to set compiler options from the IAR Embedded Workbench™, and describes each option.
Setting compiler options To set compiler options in the IAR Embedded Workbench, select Project>Options to display the Options dialog box. Then select ICCDSPIC in the Category list to display the Project compiler options pages:
Figure 55: Compiler options
Click the tab corresponding to the type of options that you want to view or change. Notice that compiler options can be specified on a target level, group level, or file level. When options are set on the group or file level, you can choose to override settings inherited from a higher level. To restore all settings to the default factory settings, click on the Factory Settings button. The following sections give full descriptions of each compiler option.
Part 3. The IAR Embedded Workbench IDE 91
UDSPIC-1
Language
Language The Language options enable the use of target-dependent extensions to the C or Embedded C++ language.
Figure 56: Compiler language options
ENABLE EMBEDDED C++ SYNTAX In Embedded C++ mode, the compiler treats the source code as Embedded C++. If Embedded C++ is disabled, the compiler runs in ISO/ANSI C mode, in which features specific to Embedded C++, such as classes and overloading, cannot be utilized. In the dsPIC IAR Embedded Workbench, Embedded C++ syntax is disabled by default. Select the Enable Embedded C++ syntax option to enable Embedded C++.
ENABLE LANGUAGE EXTENSIONS Language extensions must be enabled for the dsPIC IAR C/EC++ Compiler to be able to accept dsPIC-specific keywords as extensions to the standard C or Embedded C++ language. In the IAR Embedded Workbench, language extensions are enabled by default. Deselect the Enable language extensions check box to disable language extensions. For details about language extensions, see the dsPIC IAR C/EC++ Compiler Reference Guide.
dsPIC IAR Embedded Workbench™ IDE
92 User Guide
UDSPIC-1
Compiler options
Strict ISO/ANSI By default the compiler accepts a superset of ISO/ANSI C (for additional information, see the dsPIC IAR C/EC++ Compiler Reference Guide). Use this option to adhere to strict ISO/ANSI. First select Disable extensions, and then select Strict ISO/ANSI to adhere to the strict ISO/ANSI C standard.
TREAT ‘CHAR’ AS ‘SIGNED CHAR’ Normally, the compiler interprets the char type as unsigned char. Use this option to make the compiler interpret the char type as signed char instead, for example for compatibility with another compiler. Note: The runtime library is compiled without the Treat ‘char’ as ‘signed char’ option. If you use this option, you may get type mismatch warnings from the linker since the library uses unsigned char.
Code The Code options determine the type and level of optimization for generation of object code.
Figure 57: Compiler code options
OPTIMIZATIONS Size and speed The dsPIC IAR C/EC++ Compiler supports two optimization models—size and speed—at different optimization levels.
Part 3. The IAR Embedded Workbench IDE 93
UDSPIC-1
Code
Select the optimization model using either the Size or Speed radio button. Then select the optimization level—low, medium, or high—from the drop-down list next to the radio buttons. By default, a debug project will have a size optimization that is fully debuggable, while a release project will have a size optimization that generates an absolute minimum of code. The following table describes the optimization levels: Optimization level
Description
Low
Dead code elimination. Redundant label elimination. Redundant branches elimination.
Medium
Live-dead analysis and optimization. Peephole optimization. Code hoisting. Register content analysis and optimization.
High
Cross jumping.
Table 16: Compiler optimization levels
ENABLED TRANSFORMATIONS The dsPIC IAR C/EC++ Compiler supports the following types of transformations:
Common sub-expression elimination Loop unrolling Function inlining Code motion
In a debug project, the transformations are by default disabled. You can enable a transformation by selecting its check box. The compiler will then determine if this transformation is feasible. In a release project, the transformations are by default enabled. You can disable a transformation by deselecting its check box.
Common sub-expression elimination Redundant re-evaluation of common sub-expressions is by default eliminated at optimization levels Medium and High. This optimization normally reduces both code size and execution time. The resulting code may however be difficult to debug. Note: This option has no effect at optimization level Low.
dsPIC IAR Embedded Workbench™ IDE
94 User Guide
UDSPIC-1
Compiler options
Loop unrolling It is possible to duplicate the loop body of a small loop, whose number of iterations can be determined at compile time, to reduce the loop overhead. This optimization, which can be performed at optimization level High, normally reduces execution time, but increases code size. The resulting code may also be difficult to debug. The compiler heuristically decides which loops to unroll. Different heuristics are used when optimizing for speed and size. Select the Loop unrolling checkbox to enable loop unrolling. Note: This option has no effect at optimization levels Low and Medium.
Function inlining Function inlining means that a simple function, whose definition is known at compile time, is integrated into the body of its caller to eliminate the overhead of the call. This optimization, which is performed at optimization level High, normally reduces execution time, but increases code size. The resulting code may also be difficult to debug. The compiler decides which functions to inline. Different heuristics are used when optimizing for speed and size. Note: This option has no effect at optimization levels Low and Medium.
Code motion Evaluation of loop-invariant expressions and common sub-expressions are moved to avoid redundant reevaluation. This optimization, which is performed at optimization level High, normally reduces code size and execution time. The resulting code may however be difficult to debug. Note: This option has no effect at optimization levels Low and Medium.
Part 3. The IAR Embedded Workbench IDE 95
UDSPIC-1
Output
Output The Output options determine the output format of the compiled file, including the level of debugging information in the object code.
Figure 58: Compiler output options
MAKE LIBRARY MODULE By default the compiler generates program modules, which are always included during linking. Use this option to make a library module that will only be included if it is referenced in your program. Select the Make library module option to make the object file be treated as a library module rather than as a program module. For information about working with libraries, see the IAR XLIB Librarian chapters in the IAR Linker and Library Tools Reference Guide, available from the Help menu.
OBJECT MODULE NAME Normally, the internal name of the object module is the name of the source file, without a directory name or extension. Use this option to set the object module name explicitly. First select the Object module name check box, then enter a name in the entry field. This option is particularly useful when several modules have the same filename, since the resulting duplicate module name would normally cause a linker error; for example, when the source file is a temporary file generated by a preprocessor.
dsPIC IAR Embedded Workbench™ IDE
96 User Guide
UDSPIC-1
Compiler options
GENERATE DEBUG INFORMATION This option causes the compiler to include additional information in the object modules that is required by C-SPY™ and other symbolic debuggers. The Generate debug information option is specified by default. Deselect this option if you do not want the compiler to generate debug information. Note: The included debug information increases the size of the object files.
List The List options determine whether a list file is produced, and the information included in the list file.
Figure 59: Compiler list file options
Normally, the compiler does not generate a list file. Select one of the following options to generate a list file: Option
Description
Output list file
Generates a list file
Assembler mnemonics
Includes assembler mnemonics in the list file
Diagnostics
Includes diagnostic information in the list file
Output assembler file
Generates an assembler list file
Include source
Includes source code in the assembler list file
Table 17: Compiler list file options
The list file will be saved in the List directory, and its filename will consist of the source filename, plus the filename extension lst.
Part 3. The IAR Embedded Workbench IDE 97
UDSPIC-1
Preprocessor
Preprocessor The Preprocessor options allow you to define symbols and include paths for use by the compiler.
Figure 60: Compiler preprocessor options
INCLUDE PATHS The Include paths option adds a path to the list of #include file paths. The paths required by the product are specified by default depending on your choice of runtime library. Enter the full file path of your #include files. To make your project more portable, use the argument variable $TOOLKIT_DIR$ for the subdirectories of the active product and $PROJ_DIR$ for the directory of the current project. For an overview of the argument variables, see Table 30, page 161.
DEFINED SYMBOLS The Defined symbols option is useful for conveniently specifying a value or choice that would otherwise be specified in the source file. Enter the symbols that you want to define for the project. This option has the same effect as a #define statement at the top of the source file.
dsPIC IAR Embedded Workbench™ IDE
98 User Guide
UDSPIC-1
Compiler options
For example, you could arrange your source to produce either the test or production version of your program depending on whether the symbol TESTVER was defined. To do this you would use include sections such as: #ifdef TESTVER ... ; additional code lines for test version only #endif
You would then define the symbol TESTVER in the Debug target but not in the Release target.
PREPROCESSOR OUTPUT TO FILE By default the compiler does not generate preprocessor output. Select the Preprocessor output to file option if you want to generate preprocessor output. You can also choose to preserve comments and/or to generate #line directives.
Diagnostics The Diagnostics options determine how diagnostics are classified and displayed. Use the diagnostics options to override the default classification of the specified diagnostics. Note: The diagnostics cannot be suppressed for fatal errors, and fatal errors cannot be reclassified.
Figure 61: Compiler diagnostics options
Part 3. The IAR Embedded Workbench IDE 99
UDSPIC-1
Diagnostics
ENABLE REMARKS The least severe diagnostic messages are called remarks. A remark indicates a source code construct that may cause strange behavior in the generated code. By default remarks are not issued. Select the Enable remarks option if you want the compiler to generate remarks.
SUPPRESS THESE DIAGNOSTICS This option suppresses the output of diagnostics for the tags that you specify. For example, to suppress the warnings Pe117 and Pe177, type: Pe117,Pe177
TREAT THESE AS REMARKS A remark is the least severe type of diagnostic message. It indicates a source code construct that may cause strange behavior in the generated code. Use this option to classify diagnostics as remarks. For example, to classify the warning Pe177 as a remark, type: Pe177
TREAT THESE AS WARNINGS A warning indicates an error or omission that is of concern, but which will not cause the compiler to stop before compilation is completed. Use this option to classify diagnostic messages as warnings. For example, to classify the remark Pe826 as a warning, type: Pe826
TREAT THESE AS ERRORS An error indicates a violation of the C or Embedded C++ language rules, of such severity that object code will not be generated, and the exit code will not be 0. Use this option to classify diagnostic messages as errors. For example, to classify the warning Pe117 as an error, type: Pe117
TREAT ALL WARNINGS AS ERRORS Use this option to make the compiler treat all warnings as errors. If the compiler encounters an error, object code is not generated.
dsPIC IAR Embedded Workbench™ IDE
100 User Guide
UDSPIC-1
Assembler options This chapter first explains how to set the options from the IAR Embedded Workbench™ and then provides detailed reference information for each assembler option.
Setting assembler options To set assembler options in the IAR Embedded Workbench, select Project>Options to display the Options dialog box. Then select ADSPIC in the Category list to display the assembler options pages:
Figure 62: Assembler options
Click the tab corresponding to the type of options you want to view or change. Notice that assembler options can be specified on target level, group level, or file level. When options are set on group or file level, you can choose to override settings inherited from a higher level. To restore all settings to the default factory settings, click on the Factory Settings button. The following sections give detailed descriptions of each assembler option.
Part 3. The IAR Embedded Workbench 101
UDSPIC-1
Language
Language The Language options control the code generation of the assembler.
Figure 63: Assembler language options
USER SYMBOLS ARE CASE SENSITIVE By default, case sensitivity is on. This means that, for example, LABEL and label refer to different symbols. You can deselect User symbols are case sensitive to turn case sensitivity off, in which case LABEL and label will refer to the same symbol.
ALLOW MNEMONICS IN FIRST COLUMN The default behavior by the assembler is to treat all identifiers starting in the first column as labels. Use this option to make mnemonics names (without a trailing colon) starting in the first column to be recognized as mnemonics.
ALLOW DIRECTIVES IN FIRST COLUMN The default behavior by the assembler is to treat all identifiers starting in the first column as labels. Use this option to make directive names (without a trailing colon) that start in the first column to be recognized as directives.
MACRO QUOTE CHARACTERS The Macro quote chars option sets the characters used for the left and right quotes of each macro argument.
dsPIC IAR Embedded Workbench™ IDE
102 User Guide
UDSPIC-1
Assembler options
By default, the characters are < and >. This option allows you to change the quote characters to suit an alternative convention or simply to allow a macro argument to contain < or >. From the drop-down list, select one of four types of brackets to be used as macro quote characters:
Figure 64: Selecting macro quote characters
Output The Output options allow you to generate information to be used by a debugger such as the IAR C-SPY™ Debugger.
Figure 65: Assembler output options
MAKE LIBRARY MODULE By default, the assembler produces a program module ready to be linked with the IAR XLINK Linker™. Select the Make library module option if you instead want the assembler to make a library module for use with the IAR XLIB Librarian™.
Part 3. The IAR Embedded Workbench 103
UDSPIC-1
List
Note: If the NAME directive is used in the source code (to specify the name of the program module), the Make library module option is ignored. This means that the assembler produces a program module regardless of the Make library module option.
OBJECT MODULE NAME Use this option to specify a name for the assembler object file. If no name is specified, the name of the source file is used. If no extension is specified, r59 is used.
GENERATE DEBUG INFORMATION In order to reduce the size and link time of the object file, the assembler does not generate debug information in a Release project. You must use the Generate debug information option if you want to use a debugger with the program.
List The List options are used for making the assembler generate a list file and for selecting the list file contents.
Figure 66: Assembler list file options
By default, the assembler does not generate a list file. Selecting Output list file causes the assembler to generate a listing and send it to the file sourcename.lst. Note: If you want to save the list file in another directory than the default directory for list files, use the Output Directories option in the General category; see Output directories, page 89, for additional information.
dsPIC IAR Embedded Workbench™ IDE
104 User Guide
UDSPIC-1
Assembler options
OUTPUT LIST FILE Use the Output list file option to specify the information to include in the list file: Option
Description
Do not include diagnostics
Excludes diagnostic information from the list file
Include assembler macro execution information
Prints macro execution information on every call of a macro
Include cross-reference
Generates a cross-reference table at the end of the list file
List macro definitions
Includes macro definitions in the list file
Disable macro expansion
Excludes macro expansions from the list file
List only assembled parts
Excludes lines in false conditional assembly sections from the list file
List several lines of code
Lists the code generated by directives on several lines if necessary
Table 18: Assembler list file options
Preprocessor The Preprocessor options allow you to define include paths and symbols in the assembler.
Figure 67: Assembler preprocessor options
INCLUDE PATHS The Include paths option adds paths to the list of #include file paths. The path required by the product is specified by default.
Part 3. The IAR Embedded Workbench 105
UDSPIC-1
Preprocessor
Enter the full path of the directories that you want the assembler to search for #include files. To make your project more portable, use the argument variable $TOOLKIT_DIR$ for the subdirectories of the active product and $PROJ_DIR$ for the directory of the current project. For an overview of the argument variables, see Table 30, Argument variables, page 161. See the dsPIC IAR Assembler Reference Guide for information about the #include directive. Note: By default the assembler also searches for #include files in the paths specified in the ADSPIC_INC environment variable. We do not, however, recommend the use of environment variables in the IAR Embedded Workbench.
DEFINED SYMBOLS This option provides a convenient way of specifying a value or choice that you would otherwise have to specify in the source file. Enter the symbols you want to define, one per line.
For example, you could arrange your source to produce either the test or production version of your program depending on whether the symbol TESTVER was defined. To do this you would use include sections such as: #ifdef TESTVER ... ; additional code lines for test version only #endif
You would then define the symbol TESTVER in the Debug target but not in the Release target.
Alternatively, your source might use a variable that you need to change often, for example FRAMERATE. You would leave the variable undefined in the source and use this option to specify a value for the project, for example FRAMERATE=3. To remove a user-defined symbol, select in the Defined symbols list and press the Delete key.
PREPROCESSOR OUTPUT TO FILE By default the assembler does not generate preprocessor output. Select the Preprocessor output to file option if you want to generate preprocessor output. You can also choose to preserve comments and/or to generate #line directives.
dsPIC IAR Embedded Workbench™ IDE
106 User Guide
UDSPIC-1
Assembler options
Diagnostics The Diagnostics options determine how diagnostics are classified and displayed. Use the diagnostics options to override the default classification of the specified diagnostics. Note: The diagnostics cannot be suppressed for fatal errors, and fatal errors cannot be reclassified.
Figure 68: Assembler diagnostics options
ENABLE REMARKS The least severe diagnostic messages are called remarks. A remark indicates a source code construct that may cause strange behavior in the generated code. By default remarks are not issued. Select the Enable remarks option if you want the assembler to generate remarks.
TREAT ALL WARNINGS AS ERRORS Use this option to make the compiler treat all warnings as errors. If the assembler encounters an error, object code is not generated.
SUPPRESS THESE DIAGNOSTICS This option suppresses the output of diagnostics for the tags that you specify. For example, to suppress the warnings As053 and As054, type: As053,As054
Part 3. The IAR Embedded Workbench 107
UDSPIC-1
Diagnostics
TREAT THESE AS REMARKS A remark is the least severe type of diagnostic message. It indicates a source code construct that may cause strange behavior in the generated code. Use this option to classify diagnostics as remarks. For example, to classify the warning As054 as a remark, type: As054
TREAT THESE AS WARNINGS A warning indicates an error or omission that is of concern, but which will not cause the compiler to stop before assembly is completed. Use this option to classify diagnostic messages as warnings. For example, to classify the remark As098 as a warning, type: As098
TREAT THESE AS ERRORS An error indicates a violation of the assembler language rules, of such severity that object code will not be generated, and the exit code will not be 0. Use this option to classify diagnostic messages as errors. For example, to classify the warning As054 as an error, type: As054
dsPIC IAR Embedded Workbench™ IDE
108 User Guide
UDSPIC-1
XLINK options This chapter describes how to set XLINK options and gives reference information about the options available in the IAR Embedded Workbench. XLINK options allow you to control the operation of the IAR XLINK Linker™. Note: The XLINK command line options that are used for defining segments in a linker command file are described in the IAR Linker and Library Tools Reference Guide.
Setting XLINK options To set XLINK options in the IAR Embedded Workbench, select Project>Options to display the Options dialog box. Then select XLINK in the Category list to display the XLINK options pages:
Figure 69: XLINK options
Click the tab corresponding to the type of options you want to view or change. Notice that XLINK options can be specified on target level, group level, or file level. When options are set on the group or file level, you can choose to override settings inherited from a higher level.
Part 3. The IAR Embedded Workbench IDE 109
UDSPIC-1
Output
To restore all settings to the default factory settings, click on the Factory Settings button. The following sections give full descriptions of each XLINK option.
Output The Output options are used for specifying the output format and the level of debugging information included in the output file.
Figure 70: XLINK output file options
OUTPUT FILE Use Output file to specify the name of the XLINK output file. If a name is not specified the linker will use the name project.d59. If a name is supplied without a file type, the default file type for the selected output format (see Other, page 111) will be used. Note: If you select a format that generates two output files, the file type that you specify will only affect the primary output file (first format).
Override default Use this option to specify a filename or file type other than default.
FORMAT The format options determine the format of the output file generated by the IAR XLINK Linker. The IAR Systems proprietary output format is called UBROF, Universal Binary Relocatable Object Format.
dsPIC IAR Embedded Workbench™ IDE
110 User Guide
UDSPIC-1
XLINK options
Debug info This option creates an output file in debug (ubrof) format, with a d59 extension, to be used with the IAR C-SPY™ Debugger. Note: For debuggers that support the IAR Systems debug format, select Other and then ubrof from the Output format drop-down list.
Debug info with terminal I/O This option is equivalent to Debug info but allows you to simulate terminal I/O when running C-SPY.
Other Use this option to generate output for other debuggers than C-SPY. Then select the appropriate output format and, if applicable, a format variant: Use Output format to select an output format other than the default format:
In a debug project, the default output format is debug (ubrof). In a release project, the default output format is Motorola (S-records). Note: When you specify the Output format option as debug (ubrof), the special runtime modules used by C-SPY will not be included in the object code. Use the Debug info option instead if you want to run the program in C-SPY. Use Format variant to select enhancements available for some output formats. The alternatives depend on the output format chosen. For more information, see the IAR Linker and Library Tools Reference Guide.
Module-local symbols Use this option to specify whether local (non-public) symbols in the input modules should be included or not by the IAR XLINK Linker. If suppressed, the local symbols will not appear in the listing cross-reference and they will not be passed on to the output file. You can choose to ignore just the compiler-generated local symbols, such as jump or constant labels. Usually these are only of interest when debugging at assembler level. Note: Local symbols are only included in files if they were compiled or assembled with the appropriate option to specify this.
Part 3. The IAR Embedded Workbench IDE 111
UDSPIC-1
#define
#define The #define option allows you to define symbols.
Figure 71: XLINK defined symbols options
DEFINE SYMBOL Use Define symbol to define absolute symbols at link time. This is especially useful for configuration purposes. Any number of symbols can be defined in a linker command file. The symbol(s) defined in this manner will be located in a special module called ?ABS_ENTRY_MOD, which is generated by the linker. XLINK will display an error message if you attempt to redefine an existing symbol.
dsPIC IAR Embedded Workbench™ IDE
112 User Guide
UDSPIC-1
XLINK options
Diagnostics The Diagnostics options determine the error and warning messages generated by the IAR XLINK Linker.
Figure 72: XLINK diagnostics options
ALWAYS GENERATE OUTPUT Use Always generate output to generate an output file even if a non-fatal error was encountered during the linking process, such as a missing global entry or a duplicate declaration. Normally, XLINK will not generate an output file if an error is encountered.
Note: XLINK always aborts on fatal errors, even when this option is used. The Always generate output option allows missing entries to be patched in later in the absolute output image.
SEGMENT OVERLAP WARNINGS Use Segment overlap warnings to reduce segment overlap errors to warnings, making it possible to produce cross-reference maps, etc.
NO GLOBAL TYPE CHECKING Use No global type checking to disable type checking at link time. While a well-written program should not need this option, there may be occasions where it is helpful. By default, XLINK performs link-time type checking between modules by comparing the external references to an entry with the PUBLIC entry (if the information exists in the object modules involved). A warning is generated if there are mismatches.
Part 3. The IAR Embedded Workbench IDE 113
UDSPIC-1
Diagnostics
RANGE CHECKS Use Range checks to specify the address range check. The following table shows the range check options in the IAR Embedded Workbench: IAR Embedded Workbench
Description
Generate errors
An error message is generated
Generate warnings
Range errors are treated as warnings
Disabled
Disables the address range checking
Table 19: XLINK range check options
If an address is relocated outside of the target CPU’s address range—code, external data, or internal data address—an error message is generated. This usually indicates an error in an assembly language module or in the segment placement.
WARNINGS/ERRORS By default, the IAR XLINK Linker generates a warning when it detects that something may be wrong, although the generated code may still be correct. The Warnings/Errors options allow you to suppress or enable all warnings, and to change the severity classification of errors and warnings. Refer to the IAR Linker and Library Tools Reference Guide for information about the different warning and error messages. Use the following options to control the generation of warning and error messages:
Suppress all warnings Use this option to suppress all warnings.
Suppress these diagnostics This option suppresses the output of diagnostics for the tags that you specify. For example, to suppress the warnings w117 and w177, type w117,w177.
Treat these as warnings Use this option to specify errors that should be treated as warnings instead. For example, to make error 106 become treated as a warning, enter e106.
Treat these as errors Use this option to specify warnings that should be treated as errors instead. For example, to make warning 26 become treated as an error, enter w26.
dsPIC IAR Embedded Workbench™ IDE
114 User Guide
UDSPIC-1
XLINK options
List The List options determine the generation of an XLINK cross-reference listing.
Figure 73: XLINK list file options
GENERATE LINKER LISTING Causes the linker to generate a listing and send it to the file project.map.
Segment map Use Segment map to include a segment map in the XLINK listing file. The segment map will contain a list of all the segments in dump order.
Symbols The following options are available: Option
Description
None
Symbols will be excluded from the linker listing.
Symbol listing
An abbreviated list of every entry (global symbol) in every module. This entry map is useful for quickly finding the address of a routine or data element.
Module map
A list of all segments, local symbols, and entries (public symbols) for every module in the program.
Table 20: XLINK list file options
Lines/page Sets the number of lines per page for the XLINK listings to lines, which must be in the range 10 to 150.
Part 3. The IAR Embedded Workbench IDE 115
UDSPIC-1
Include
Include The Include options allow you to set the include path for linker command files, and specify the linker command file.
Figure 74: XLINK include files options
INCLUDE PATHS By default, XLINK searches for object files only in the current working directory. The Include paths option allows you to specify the names of the directories which it will also search if it fails to find the file in the current working directory. The paths required by the product are specified by default depending on your choice of runtime library. Enter the full file path of your #include files. To make your project more portable, use the argument variable $TOOLKIT_DIR$ for the subdirectories of the active product and $PROJ_DIR$ for the directory of the current project. For an overview of the argument variables, see Table 30, page 161.
LIBRARY A default library file is selected automatically. You can override this by selecting Override default library name, and then specifying an alternative library file.
Ignore CSTARTUP in library When you select the option Ignore CSTARTUP in library, all modules in the library will be treated as library modules, even if they have not been assembled or compiled as library modules.
dsPIC IAR Embedded Workbench™ IDE
116 User Guide
UDSPIC-1
XLINK options
If you want to include your own version of cstartup.s59 in a project, use this option to prevent the CSTARTUP module in the library from being linked. You should use this option also when linking assembler source files, since the functionality of CSTARTUP does not apply to projects containing only assembler source files.
XCL FILENAME A default linker command file is selected automatically for the chosen Target settings in the General category. You can override this by selecting Override default, and then specifying an alternative file. The argument variables $TOOLKIT_DIR$ or $PROJ_DIR$ can be used here too, to specify a project-specific or predefined linker command file.
Input The Input options define the status of input modules.
Figure 75: XLINK input files options
MODULE STATUS The status of the input files, either PROGRAM or LIBRARY, are defined in the files themselves.
Inherent When you select this option, the file will use the status defined in the file itself. Use Inherent to link files normally, and generate output code.
Part 3. The IAR Embedded Workbench IDE 117
UDSPIC-1
Input
Inherent, no object code Use Inherent, no object code to empty-load specified input files; they will be processed normally in all regards by the linker but output code will not be generated for these files. One potential use for this feature is in creating separate output files for programming multiple EPROMs. This is done by empty-loading all input files except the ones that you want to appear in the output file.
Load as PROGRAM Use Load as PROGRAM to temporarily force all of the modules within the specified input files to be loaded as if they were all program modules, even if some of the modules have the LIBRARY attribute. This option is particularly suited for testing library modules before they are installed in a library file, since this option will override an existing library module with the same entries. In other words, XLINK will load the module from the specified input file rather than from the original library.
Load as LIBRARY Use Load as LIBRARY to temporarily cause all of the modules within the specified input files to be treated as if they were all library modules, even if some of the modules have the PROGRAM attribute. This means that the modules in the input files will be loaded only if they contain an entry that is referenced by another loaded module. If you have made modifications to CSTARTUP, this option is particularly useful when testing CSTARTUP before you install it in the library file, since this option will override the existing program module CSTARTUP.
dsPIC IAR Embedded Workbench™ IDE
118 User Guide
UDSPIC-1
XLINK options
Processing The Processing options allow you to specify details about how the code is generated.
Figure 76: XLINK processing options
FILL UNUSED CODE MEMORY Use Fill unused code memory to fill all gaps between segment parts introduced by the linker with the value you enter. The linker can introduce gaps either because of alignment restriction, or at the end of ranges given in segment placement options. The default behavior, when this option is not used, is that these gaps are not given a value in the output file.
Fill pattern Use this option to specify size, in hexadecimal notation, of the filler to be used in gaps between segment parts.
Generate checksum Use Generate checksum to checksum all generated raw data bytes. This option can only be used if the Fill unused code memory option has been specified. Size specifies the number of bytes in the checksum, which can be 1, 2, or 4.
Part 3. The IAR Embedded Workbench IDE 119
UDSPIC-1
Processing
One of the following algorithms can be used: Algorithms
Description
Arithmetic sum
Simple arithmetic sum.
CRC16
CRC16, generating polynomial 0x11021 (default)
CRC32
CRC32, generating polynomial 0x104C11DB7.
Crc polynomial
CRC with a generating polynomial of the value you enter..
Table 21: XLINK checksum algorithms
You may also specify that the one’s complement or two’s complement should be used. By default it is the most significant 1, 2, or 4 bytes (MSB) of the result that will be output, in the natural byte order for the processor. Select LSB from the Bit order drop-down list if you want the least significant bytes to be output. The CRC checksum is calculated as if the following code was called for each bit in the input, starting with a CRC of 0: unsigned long crc(int bit, unsigned long oldcrc) { unsigned long newcrc = (oldcrc Options to display the Options dialog box. Then select C-SPY in the Category list to display the C-SPY options pages:
Figure 77: C-SPY options
To restore all settings to the default factory settings, click on the Factory Settings button. The following sections give full descriptions of each C-SPY option.
Part 3. The IAR Embedded Workbench IDE 121
UDSPIC-1
C-SPY Settings
C-SPY Settings The C-SPY Settings options specify the C-SPY driver, the setup file, and device description file to be used, and which default source code location to run to.
Figure 78: C-SPY Settings options
DRIVER Selects the appropriate driver for use with C-SPY, for example a simulator or an emulator. The following drivers are currently available: C-SPY version
Driver
Simulator
dspicsim.dll
Table 22: C-SPY driver options
Contact your distributor or IAR representative, or visit the IAR website at www.iar.com for the most recent information about the available C-SPY versions.
RUN TO Normally when C-SPY is launched, the Disassembly window is the active debugger window, with the first assembler instruction to be executed highlighted. If you instead want C-SPY to begin by running to a location in one of the source files and displaying that source file as the active debugger window, select the Run to option and enter the name of the location. The default location to run to is the main function. Execution will start as you start the debugger. The Reset command will then first reset the system and then immediately start the execution.
dsPIC IAR Embedded Workbench™ IDE
122 User Guide
UDSPIC-1
C-SPY options
SETUP FILE To register the contents of a macro file in the C-SPY startup sequence, select Use setup file and enter the path and name of your setup file, for example, watchdog.mac. If no extension is specified, the extension mac is assumed. A browse button is available for your convenience.
DEVICE DESCRIPTION FILE Use this option to load a device description file that contains various device-specific information such as I/O register (SFR) definitions and their reset values, memory layout, and interrupt descriptions. This will add the following functionality to the debugger:
The contents of the SFRs can be displayed and edited SFR registers can be set to their default value, if any, at reset Interrupt simulation will be available in the simulator The memory map system can be loaded with a default setting.
Some device description files are provided with the product and have the extension ddf. The syntax of the device descriptions is described in the files, which are configurable. Note however that the syntax of these descriptions may change in a future version of the product.
Part 3. The IAR Embedded Workbench IDE 123
UDSPIC-1
C-SPY Settings
dsPIC IAR Embedded Workbench™ IDE
124 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference This chapter contains detailed descriptions about the windows, menus, menu options, and their components which are found in the IAR Embedded Workbench IDE. The IAR Embedded Workbench IDE is a modular application. What menus are available depends on which plug-in modules you have installed.
The IAR Embedded Workbench IDE window The following illustration shows the different components of the IAR Embedded Workbench IDE window. The window might look different depending on which plug-in modules you are using.
Menu bar Toolbar
Messages window
Project window
Editor window
Status bar Figure 79: IAR Embedded Workbench IDE window
These components are explained in greater detail in the following sections.
Part 3. The IAR Embedded Workbench IDE 125
UDSPIC-1
The IAR Embedded Workbench IDE window
MENU BAR Gives access to the IAR Embedded Workbench IDE menus. Menu
Description
File
The File menu provides commands for opening source and project files, saving and printing, and exiting from the IAR Embedded Workbench IDE.
Edit
The Edit menu provides commands for editing and searching in Editor windows and for editing breakpoints in C-SPY.
View
The commands on the View menu allow you to change the information displayed in the IAR Embedded Workbench IDE window.
Project
The Project menu provides commands for adding files to a project, creating groups, and running the IAR tools on the current project.
Tools
The Tools menu is a user-configurable menu to which you can add tools for use with the IAR Embedded Workbench IDE.
Window
The commands on the Window menu allow you to manipulate the IAR Embedded Workbench IDE windows and change their arrangements on the screen.
Help
The commands on the Help menu provide help about the IAR Embedded Workbench IDE.
Table 23: IAR Embedded Workbench IDE menu bar
The menus are described in greater detail on the following pages.
TOOLBAR The IAR Embedded Workbench IDE toolbar provides buttons for the most useful options on the IAR Embedded Workbench IDE menus, and a text box for entering a string to do a quick search. The toolbar also provides buttons for the commands on the Project menu. You can display a description of any button by pointing to it with the mouse button. When a command is not available the corresponding toolbar button will be grayed out, and you will not be able to select it. This figure shows the menu commands corresponding to each of the toolbar buttons:
Open New
Copy
Print Save
Cut
Quick search text box
Undo Paste
Redo Figure 80: IAR Embedded Workbench IDE toolbar
dsPIC IAR Embedded Workbench™ IDE
126 User Guide
UDSPIC-1
Find
Goto
Replace
Make Compile
Debug
Stop building
IAR Embedded Workbench IDE reference
Quick search To search for text in the frontmost Editor window, enter the text in the Quick search text box, and press Enter. Press Escape to cancel the search.
Figure 81: Quick search
Alternatively, you can select a string you have previously searched for from the drop-down list box.
PROJECT WINDOW The Project window shows the name of the current project and a tree representation of the groups and files included in the project.
Figure 82: Project window
Clicking the right mouse button in the Project window displays a pop-up menu which gives you convenient access to several useful commands.
Part 3. The IAR Embedded Workbench IDE 127
UDSPIC-1
The IAR Embedded Workbench IDE window
Figure 83: Project window pop-up menu
Choose Export File List to save information about which files and groups the project consists of, in a product-neutral format (which means that no settings are saved). If you want to import the corresponding information from another project, choose Import File List. All information about files or groups that are missing from your current project will be added from the imported project file list. These menu options can be useful if you want to migrate a project from a similar processor family, or if you want to synchronize different stages of a project. The Generate Makefile command opens a standard file save dialog box. After you choose a location, clicking Save will create a simple makefile. This brings the project up to date for all defined configurations. The makefile contains quoted paths; make sure that the make utility you are using can handle this correctly. Save As Text allows you to save a description of the project, including all options that you have specified.
Targets The top node in the tree shows the current target. You can change the target by choosing a different target from the Targets drop-down list box at the top of the Project window. Each target corresponds to a different version of your project that you want to compile or assemble. For example, you might have a target called Debug, which includes debugging code, and one called Release, with the debugging code omitted. You can expand the tree by double-clicking on the target icon, or by clicking on the plus sign icon, to display the groups included in this target.
dsPIC IAR Embedded Workbench™ IDE
128 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Groups Groups are used for collecting together related source files. Each group may be included in one or more targets, and a source file can be present in one or more groups.
Source files You can expand each group by double-clicking on its icon, or by clicking on the plus sign icon, to show the list of source files it contains. Once a project has been successfully built any include files are displayed in the structure below the source file that included them. Note: The include files associated with a particular source file may depend on which target the source file appears in, since preprocessor or directory options may affect which include files are associated with a particular source file.
Editing a file To open a source or include file for editing, double-click its icon in the Project window tree display.
Moving a source file between groups You can move a source file between two groups by dragging its icon between the group icons in the project tree displayed in the Project window.
Removing items from a project To remove an item from a project, click on it to select it, and then press Delete. To remove a file from a project you can also use the Project Files dialog box, displayed by choosing Project>Files.
EDITOR WINDOW Source files are displayed in the Editor window. The IAR Embedded Workbench IDE editor automatically recognizes the syntax of assembler and C or Embedded C++ programs, and displays the different components of the program in different text styles.
Part 3. The IAR Embedded Workbench IDE 129
UDSPIC-1
The IAR Embedded Workbench IDE window
Figure 84: Editor window
To change these styles, choose Tools>Options, and then select the Editor Colors and Fonts page in the IDE Options dialog box; for additional information, see Editor Colors and Fonts, page 156.
Indentation The editor automatically indents a line to the same indent as the previous line, making it easy to lay out programs in a structured way. If you want to indent a number of lines, select the lines and press the Tab key. Press Shift-Tab to move a whole block of lines to the left.
Matching brackets Use the Match Brackets option on the Edit menu to select all text between the brackets immediately surrounding the insertion point. Every time you select Match Brackets after that, the selection will increase to the next hierachic pair of brackets.
Go to function Click the Go to function shortcut button in the bottom left corner in an editor window to display all functions in the C or Embedded C++ source code window. You can then choose to go directly to one of them.
Figure 85: Go to function button
dsPIC IAR Embedded Workbench™ IDE
130 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Read-only and modification indicators The name of the open source file is displayed in the Editor window title bar. If a file is a read-only file, the text (Read Only) appears after the file name, for example common.c (Read Only). When a file has been modified after it was last saved, an asterisk appears after the window title, for example common.c *.
Editor options The IAR Embedded Workbench IDE editor provides a number of special features, each of which can be enabled or disabled independently in the Editor page of the Settings dialog box. For more information see Options, page 150.
Editor key summary The following tables summarize the editor’s keyboard commands. Use the following keys and key combinations for moving the insertion point: To move the insertion point
Press
One character left
Arrow left
One character right
Arrow right
One word left
Ctrl+Arrow left
One word right
Ctrl+Arrow right
One line up
Arrow up
One line down
Arrow down
To the start of the line
Home
To the end of the line
End
To the first line in the file
Ctrl+Home
To the last line in the file
Ctrl+End
Table 24: Editor keyboard commands for insertion point navigation
Use the following keys and key combinations for scrolling text: To scroll
Press
Up one line
Ctrl+Arrow up
Down one line
Ctrl+Arrow down
Up one page
Page Up
Down one page
Page Down
Table 25: Editor keyboard commands for scrolling
Part 3. The IAR Embedded Workbench IDE 131
UDSPIC-1
The IAR Embedded Workbench IDE window
Use the following key combinations for selecting text: To select
Press
The character to the left
Shift+Arrow left
The character to the right
Shift+Arrow right
One word to the left
Shift+Ctrl+Arrow left
One word to the right
Shift+Ctrl+Arrow right
To the same position on the previous line
Shift+Arrow up
To the same position on the next line
Shift+Arrow down
To the start of the line
Shift+Home
To the end of the line
Shift+End
One screen up
Shift+Page Up
One screen down
Shift+Page Down
To the beginning of the file
Shift+Ctrl+Home
To the end of the file
Shift+Ctrl+End
Table 26: Editor keyboard commands for selecting text
Splitting the Editor window into panes You can split the Editor window horizontally or vertically into multiple panes, to allow you to look at two or more different parts of the same source file at once, or cut and paste text between two different parts. To split the window drag the appropriate splitter control to the middle of the window:
Splitter control
Splitter control Figure 86: Splitting the Editor window
dsPIC IAR Embedded Workbench™ IDE
132 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
To revert to a single pane, double-click the appropriate splitter control or drag it back to the end of the scroll bar. You can also split a window into panes using the Window>Split command.
STATUS BAR Displays the status of the IAR Embedded Workbench IDE, and the state of the modifier keys. As you are editing, the status bar shows the current line and column number containing the insertion point, and the Caps Lock, Num Lock, and Overwrite status:
Figure 87: Editor window status bar
MESSAGES WINDOW The Messages window shows the output from different IAR Embedded Workbench IDE commands. The window is divided into multiple pages and you select the appropriate page by clicking on the corresponding tab.
Figure 88: Messages window
To specify the level of output to the Messages window, select the Project page in the IDE Options dialog box. See Project, page 157.
Part 3. The IAR Embedded Workbench IDE 133
UDSPIC-1
File menu
Pressing the right mouse button in the Messages window displays a pop-up menu which allows you to copy the contents of the window.
Figure 89: Messages window pop-up menu
Build Build shows the messages generated when building a project. Double-clicking a message in the Build panel opens the appropriate file for editing, with the insertion point at the correct position.
Find in Files Find in Files displays the output from the Edit>Find in Files. Double-clicking an entry in the panel opens the appropriate file with the insertion point positioned at the correct location.
Tool Output Tool Output displays any messages output by user-defined tools in the Tools menu, provided that you have specified the option Redirect to Output Window in the Configure Tools dialog box; see Configure Tools, page 160.
File menu The File menu provides commands for opening projects and source files, saving and printing, and exiting from the IAR Embedded Workbench IDE. The menu also includes a numbered list of the most recently opened files to allow you to open one by selecting its name from the menu.
dsPIC IAR Embedded Workbench™ IDE
134 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Figure 90: File menu
NEW Displays the following dialog box to allow you to specify whether you want to create a new project, or a new text file:
Figure 91: New dialog box
Choosing Source/Text opens a new Editor window to allow you to enter a text file.
Part 3. The IAR Embedded Workbench IDE 135
UDSPIC-1
File menu
Choosing Project displays the following dialog box to allow you to specify a name for the project and the target CPU family:
Figure 92: New Project dialog box
The project will then be displayed in a new Project window. By default new projects are created with two targets, Release and Debug.
OPEN Displays a standard Open dialog box to allow you to select a text or project file to open. Opening a new project file automatically saves and closes any currently open project. The converted project file retains its old file extension unless you save it choosing File>Save As. If you save it with the old file extension, it can no longer be opened by double-clicking it.
CLOSE Closes the active window. You will be warned if a text document has changed since it was last saved, and given the opportunity to save it before closing. Projects are saved automatically.
OPEN PROJECT Displays a standard Open dialog box to allow you to select a project file to open. Opening a new project file automatically saves and closes any currently open project.
dsPIC IAR Embedded Workbench™ IDE
136 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
If you change the viewing filter in the Files of type drop-down list to Debug Files, you can open an executable file that has been built outside of the IAR Embedded Workbench IDE. This creates a special debugging project. See Projects built outside of the Embedded Workbench, page 167, for more information.
SAVE PROJECT Saves the current project document.
CLOSE PROJECT Closes the current project document. You will be warned if a text document has changed since it was last saved, and given the opportunity to save it before closing. Projects are saved automatically.
SAVE Saves the current text or project document.
SAVE AS Displays the standard Save As dialog box to allow you to save the active document with a different name.
SAVE ALL Saves all open text documents and project files.
PAGE SETUP Displays a dialog box to allow you to format the current document.
PRINT Displays the standard Print dialog box to allow you to print a text document.
RECENT FILES Displays a submenu to allow you to quickly open the most recently opened text documents.
RECENT PROJECTS Displays a submenu to allow you to quickly open the most recently opened project files.
Part 3. The IAR Embedded Workbench IDE 137
UDSPIC-1
Edit menu
EXIT Exits from the IAR Embedded Workbench IDE. You will be asked whether to save any changes to text windows before closing them. Changes to the project are saved automatically.
Edit menu The Edit menu provides commands for editing and searching in Editor windows.
Figure 93: Edit menu
UNDO Undoes the last edit made to the current Editor window.
REDO Redoes the last Undo in the current Editor window. You can undo and redo an unlimited number of edits independently in each Editor window.
dsPIC IAR Embedded Workbench™ IDE
138 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
CUT, COPY, PASTE Provide the standard Windows functions for editing text within Editor windows and dialog boxes.
PASTE SPECIAL Provides you with a choice of the most recent contents of the clipboard to choose from when pasting in Editor documents.
SELECT ALL Selects all text in the active Editor window.
FIND Displays the following dialog box to allow you to search for text within the current Editor window:
Figure 94: Find dialog box
Enter the text to search for in the Find What text box. Select Match Whole Word Only to find the specified text only if it occurs as a separate word. Otherwise int will also find print, sprintf etc. Select Match Case to find only occurrences that exactly match the case of the specified text. Otherwise specifying int will also find INT and Int. Select Incremental Search to gradually fine-tune or expand the search by changing the search string continuously. Select Up or Down to specify the direction of the search. Choose Find Next to find the next occurrence of the text you have specified.
REPLACE Allows you to search for a specified string and replace each occurrence with another string.
Part 3. The IAR Embedded Workbench IDE 139
UDSPIC-1
Edit menu
Figure 95: Replace dialog box
Enter the text to replace each found occurrence in the Replace With box. The other options are identical to those for Find. Choose Find Next to find the next occurrence, and Replace to replace it with the specified text. Alternatively choose Replace All to replace all occurrences in the current Editor window.
FIND IN FILES Allows you to search for a specified string in multiple text files. The following dialog box allows you to specify the criteria for the search:
Figure 96: Find in File dialog box
Specify the string you want to search for in the Search String text box, or select a string you have previously searched for from the drop-down list box.
dsPIC IAR Embedded Workbench™ IDE
140 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Select Match Whole Word or Match Case to restrict the search to the occurrences that match as a whole word or match exactly in case, respectively. If the File Groups drop-down box is set to Selected Files, you select each file you want to search in the File Name list, and click Add to add it to the Selected Files list. You can also add all the files in the File Name list by clicking Add All, or you can select multiple files using the Shift and Ctrl keys and click Add to add the files you have selected. Likewise you can remove files from the Selected Files list using the Remove and Remove All buttons. Another way to select which files to search is to select one of the options All Files in Current Target, Source Files in Current Target, or Include Files in Current Target in the File Groups box. These options will automatically select all files of the given type that are part of your dsPIC project. When you have selected the files you want to search choose Find to proceed with the search. All the matching occurrences are listed in the Messages window. You can then very simply edit each occurrence by double-clicking it:
Figure 97: Messages window displaying found strings
Part 3. The IAR Embedded Workbench IDE 141
UDSPIC-1
Edit menu
This opens the corresponding file in an Editor window with the insertion point positioned at the start of the specified text. Notice the blue flag indicating the line:
Figure 98: Editor window displaying found string
GO TO Displays the following dialog box to allow you to move the insertion point to a specified line and column in the current Editor window:
Figure 99: Goto Line dialog box
TOGGLE BOOKMARK Places or removes a bookmark at the line where the insertion point is in the active Editor window.
GO TO BOOKMARK Moves the insertion point to the next bookmark that has been defined with the Toggle Bookmark command.
dsPIC IAR Embedded Workbench™ IDE
142 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
COMPLETE This command will attempt to complete the word you have begun to type, basing the guess on the contents of the rest of the Editor document.
MATCH BRACKETS Selects all text between the brackets immediately surrounding the insertion point, increases the selection to the next hierachic pair of brackets, or beeps if there is no higher bracket hierarchy.
NEXT ERROR/TAG If there is a list of error messages or the results from a Find in Files search in the Messages window, this command will display the next item from that list in the Editor window.
TOGGLE BREAKPOINT Toggles on or off a breakpoint at the statement or instruction containing or near the cursor in the source window. This command is also available as an icon button in the debug bar.
ENABLE/DISABLE BREAKPOINT This command toggles a breakpoint between being disabled, but not actually removed—making it available for future use—and being enabled again.
BREAKPOINTS This command opens the Breakpoints dialog box, where you can create, remove and edit breakpoints. See Editing Breakpoints, page 220.
Part 3. The IAR Embedded Workbench IDE 143
UDSPIC-1
View menu
View menu The commands on the View menu allow you to change the information displayed in the IAR Embedded Workbench IDE window.
Figure 100: View menu
MESSAGES Opens the Messages window that displays messages and text output from the IAR Embedded Workbench IDE commands, or makes it the current window if it is already open. For more information, see Messages window, page 133.
TOOLBARS The submenus Main and Debug toggle the two toolbars on and off.
STATUS BAR Toggles the status bar on and off.
DEBUGGER WINDOWS During a debugging session, the different debugging windows are available from the View menu:
Disassembly window Memory window Register window Watch window Locals window Call Stack window Log window Terminal I/O window Code Coverage window Profiling window.
For descriptions of these windows, see page 195 and onwards.
dsPIC IAR Embedded Workbench™ IDE
144 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Project menu The Project menu provides commands for adding files to a project, creating groups, specifying project options, and running the IAR Systems development tools on the current project.
Figure 101: Project menu
FILES Displays the following dialog box to allow you to edit the contents of the current project:
Figure 102: Project Files dialog box
Part 3. The IAR Embedded Workbench IDE 145
UDSPIC-1
Project menu
The Add to Group drop-down list box shows all the groups included in the current target. Select the one you want to edit, and the files currently in that group are displayed in the Files in Group list at the bottom of the dialog box. The upper part of the Project Files dialog box is a standard file dialog box, to allow you to locate and select the files you want to add to each particular group.
Adding files to a group To add files to the currently displayed group select them using the standard file controls in the upper half of the dialog box and choose the Add button, or choose Add All to add all the files in the File Name list box.
Removing files from a group To remove files from the currently displayed group select them in the Files in Group list and choose Remove, or choose Remove All to remove all the files from the group. You can use the Project Files dialog box to make changes to several groups. Choosing Done will then apply all the changes to the project. Alternatively, choosing Cancel will discard all the changes and leave the project unaffected.
Source file paths The IAR Embedded Workbench IDE supports relative source file paths to a certain degree. If a source file is located in the project file directory or in any subdirectory of the project file directory, the IAR Embedded Workbench IDE will use a path relative to the project file when accessing the source file.
NEW GROUP Displays the following dialog box to allow you to create a new group:
Figure 103: New Group dialog box
dsPIC IAR Embedded Workbench™ IDE
146 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Specify the name of the group you want to create in the Group Name text box. Select the targets to which you want to add the new group in the Add to Targets list. By default the group is added to all targets.
TARGETS Displays the following dialog box to allow you to create new targets, and display or change the groups included in each target:
Figure 104: Targets dialog box
To create a new target, select New and enter a name for the new target. To delete a target, select it and click Delete. To view the groups included in a target select it in the Targets list; the groups are shown in the Included Groups list. Use the arrow buttons to add or remove groups.
Part 3. The IAR Embedded Workbench IDE 147
UDSPIC-1
Project menu
OPTIONS Displays the Options dialog box to allow you to set directory and compiler options on the selected item in the Project window. You can set options on the entire target, on a group of files, or on an individual file.
Figure 105: Options dialog box
The Category list allows you to select which set of options you want to modify. The options available in the Category list will depend on the tools installed in your IAR Embedded Workbench IDE, and will typically include the following options: Category
Description
Refer to the chapter
General
General options
General options
ICCDSPIC
dsPIC IAR C/EC++ Compiler options
Compiler options
ADSPIC
dsPIC IAR Assembler options
Assembler options
XLINK
IAR XLINK Linker™ options
XLINK options
C-SPY
IAR C-SPY™ Debugger options
C-SPY options
Table 27: Option categories in IAR Embedded Workbench IDE
Selecting a category displays one or more pages of options for that component of the IAR Embedded Workbench IDE.
dsPIC IAR Embedded Workbench™ IDE
148 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
For more detailed information about the tools installed, see the dsPIC IAR C/EC++ Compiler Reference Guide, the dsPIC IAR Assembler Reference Guide, and—on the Help menu—the IAR Linker and Library Tools Reference Guide.
COMPILE Compiles or assembles the currently active file as appropriate. You can compile a file by selecting its icon in the Project window and choosing Compile. Alternatively, you can compile a file in the Editor window provided it is a member of the current target.
MAKE Brings the current target up to date by compiling, assembling, and linking only the files that have changed since the last build.
LINK Explicitly relinks the current target.
BUILD ALL Rebuilds and relinks all files in the current target.
STOP BUILD Stops the current build operation.
DEBUGGER Starts the IAR C-SPY Debugger so that you can debug the project object file. You can specify the version of C-SPY to run in the Debug options for the target. If necessary a Make will be performed before running C-SPY to ensure that the project is up to date.
Part 3. The IAR Embedded Workbench IDE 149
UDSPIC-1
Tools menu
Tools menu The Tools menu is a user-configurable menu to which you can add tools for use with the IAR Embedded Workbench. It may look different, depending on which tools have been pre-configured to appear as menu items. See Configure Tools, page 160.
Figure 106: Tools menu
OPTIONS Displays the IDE Options dialog box to allow you to customize the IAR Embedded Workbench IDE. Select the feature you want to customize by clicking the appropriate tab. Which pages that are available in this dialog box depends on your IAR Embedded Workbench IDE configuration, and whether the IDE is in a debugging session or not.
External Editor The External Editor page allows you to specify an external editor. An external editor can be called either by passing command line parameters or by using DDE (Windows Dynamic Data Exchange).
dsPIC IAR Embedded Workbench™ IDE
150 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Figure 107: Specifying external command-line editor
Selecting Type: Command Line will call the external editor by passing command line parameters. Provide the file name and path of your external editor in the Editor field. Then specify the command line to pass to the editor in the Arguments field. Note: Variables can be used in arguments. See Table 30, Argument variables, page 161, for information about the argument variables that are available. Selecting Type: DDE will call the external editor by using DDE. Provide the file name and path of your external editor in the Editor field. Specify the DDE service name used by the editor in the Service field. Then specify a sequence of command strings to send to the editor in the Command field.
Part 3. The IAR Embedded Workbench IDE 151
UDSPIC-1
Tools menu
The command strings should be entered as: DDE-Topic CommandString DDE-Topic CommandString
as in the following example, which applies to Codewright®:
Figure 108: External editor DDE settings
The service name and command strings depend on the external editor that you are using. Refer to the user documentation of your external editor to find the appropriate settings. Note: Variables can be used in the arguments. See Table 30, Argument variables, page 161, for more information about the argument variables that are available.
dsPIC IAR Embedded Workbench™ IDE
152 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Common fonts The Common Fonts page displays the fonts used for all project windows except for the editor windows.
Figure 109: Specifying common fonts
Click the Font buttons to change the fixed and proportional width fonts, respectively.
Part 3. The IAR Embedded Workbench IDE 153
UDSPIC-1
Tools menu
Key Bindings The Key Bindings page displays the shortcut keys used for each of the menu options, and allows you to change them:
Figure 110: Specifying key bindings
Select the menu you want to edit from the Category drop-down list. Any currently defined shortcut keys are shown in the scroll list below. There are two kinds of possible shortcut keys: Primary keys, which will be displayed next to the command on the menu, and aliases which will work but not be displayed. To add or change a shortcut to the command, place the insertion point in the Press shortcut key box and type the key combination you want to use. Click Set under Primary or Add under Alias, to add it to the list. You will not be allowed to set or add it if it is already used by another command. To remove a shortcut key, select the corresponding menu command in the scroll list and click Clear under Primary or Alias. To revert all command shortcut keys to the factory settings, click Reset All. Then click OK to use the new key bindings you have defined and the menus will be updated to show the shortcuts you have defined.
dsPIC IAR Embedded Workbench™ IDE
154 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Editor The Editor page allows you to change the editor options:
Figure 111: Editor settings
It provides the following options: Option
Description
Tab Size
Specifies the number of character spaces corresponding to each tab.
Indent Size
Specifies the number of character spaces to be used for indentation.
Tab Key Function
Specifies how the tab key is used.
Syntax Highlighting
Displays the syntax of C or Embedded C++ programs in different text styles.
Auto Indent
When you insert a line, the new line will automatically have the same indentation as the previous line.
Show Line Numbers
Displays line numbers in the Editor window.
Scan for Changed Files
The editor will check if files have been modified by some other tool and automatically reload them. If a file has been modified in the IAR Embedded Workbench IDE, you will be prompted first.
Show Bookmarks
Displays compiler errors, lines found with the Find in Files command, and user bookmarks.
Enable Virtual Space
Allows the insertion point to move outside the text area.
Custom Keyword File
Allows you to select a text file containing keywords that you want the editor to use a special syntax highlighting for.
Table 28: Editor settings
Part 3. The IAR Embedded Workbench IDE 155
UDSPIC-1
Tools menu
Option
Description
Use Default SIze
Allows you to set the default size of editor windows.
Table 28: Editor settings (Continued)
For more information about the IAR Embedded Workbench IDE Editor, see Editor window, page 129.
Editor Colors and Fonts The Editor Colors and Fonts page allows you to specify the colors and fonts used for text in the Editor windows. To change the font used in Editor windows, click the Font button in the Editor Font section. The scroll list in the Syntax Coloring section shows a list of the C or Embedded C++ syntax elements you can customize in the Editor window:
Figure 112: Specifying Editor window colors and fonts
To specify the style used for each element of C or Embedded C++ syntax in the Editor window, select the item you want to define from the list. The current setting is shown in the Sample box below the list box. You choose a text color by clicking Color. You can also choose the type style from the Type Style drop-down list. Then click OK to use the new styles you have defined, or Cancel to revert to the previous styles.
dsPIC IAR Embedded Workbench™ IDE
156 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
The color and font settings for assembler and C or Embedded C++ source code are specified in the files syntax_icc.cfg and syntax_asm.cfg, respectively. These files are located in the config directory.
Project The Project page allows you to set options for Make and Build:
Figure 113: Project settings
The following table gives the options, and the alternative settings for each option: Option
Setting
Show build messages
All: Show all messages. Include compiler and linker information. Messages: Show messages, warnings, and errors. Warnings: Show warnings and errors. Errors: Show errors only.
Stop build operation on
Never: Do not Stop. Warnings: Stop on warnings and errors. Errors: Stop on errors.
Save editor windows on build
Always: Always save before Make or Build. Ask: Prompt before saving. Never: Do not save.
Make before debugging
Always: Always Make before debugging. Ask: Always prompt before Making. Never: Do not Make.
Table 29: Project settings
Part 3. The IAR Embedded Workbench IDE 157
UDSPIC-1
Tools menu
Select the Reload last project at startup check box if you want the last active project to load automatically the next time you launch the IAR Embedded Workbench IDE.
Debugger The Debugger page allows you to use a dedicated editor window for debugging purposes. This can be very convenient if your project contains many source files.
Figure 114: Debugger settings
You can choose whether the dedicated debugger window should close at the end of the debug session, or if the code that has been executed should be displayed in the regular Editor window.
dsPIC IAR Embedded Workbench™ IDE
158 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Register filter You can choose to display registers in the Register window in groups you have created yourself, using the Register Filter page. This page is only available when the IAR C-SPY Debugger is running. See Register window, page 200 for more information on the Register window.
Figure 115: Register Filter page
Enable the customized filter function by selecting the Use register filter check box and choose or create a filter file with the Filter Files button. Choose a display group from the drop-down menu under Groups or create a new one by clicking the New Group button. Then select registers in the left scroll list and move them into the Group members list on the right with the arrow button. The registers will be shown using the default base. If you want to change the base, select the Override check box.
Part 3. The IAR Embedded Workbench IDE 159
UDSPIC-1
Tools menu
CONFIGURE TOOLS Configure Tools displays the following dialog box to allow you to specify a user-defined tool to add to the menu:
Figure 116: Configure Tools dialog box
Click New and specify the text for the menu item in the Menu Text box, and the command to be run when you select the item in the Command text box. Alternatively, click Browse to display a standard file dialog box to allow you to locate an executable file on disk and add its path to the Command text box. Specify the argument for the command in the Argument text box, or select Prompt for Command Line to display a prompt for the command line argument when the command is selected from the Tools menu. Variables can be used in the arguments, allowing you to set up useful tools such as interfacing to a command line revision control system, or running an external tool on the selected file.
dsPIC IAR Embedded Workbench™ IDE
160 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
The following argument variables can be used: Variable
Description
$CUR_DIR$
Current directory
$CUR_LINE$
Current line
$EW_DIR$
Top directory of the IAR Embedded Workbench, for example
c:\program files\iar systems\embedded workbench 3.n $EXE_DIR$
Directory for executable output
$FILE_DIR$
Directory of active file, no file name
$FILE_FNAME$
File name of active file without path
$FILE_PATH$
Full path of active file (in Editor, Project, or Message window)
$LIST_DIR$
Directory for list output
$OBJ_DIR$
Directory for object output
$PROJ_DIR$
Project directory
$PROJ_FNAME$
Project file name without path
$PROJ_PATH$
Full path of project file
$TARGET_DIR$
Directory of primary output file
$TARGET_FNAME$
Filename without path of primary output file
$TARGET_PATH$
Full path of primary output file
$TOOLKIT_DIR$
Directory of the active product, for example c:\program
files\iar systems\embedded workbench 3.n\dspic Table 30: Argument variables
The Initial Directory text box allows you to specify an initial working directory for the tool. Select Redirect to Output Window to display any console output from the tool to the Tool Output page in the Messages window. Tools that are launched with this option cannot receive any user input, for instance input from the keyboard. If the tool stops and waits for user input, the process will hang there. Note: Tools that require user input or make special assumptions regarding the console that they execute in, will not work at all if launched with this option. If the tool you are adding is useful only in a certain context, select an option from the Tool Available drop-down box to have the tool available only when debugging or only when not debugging.
Part 3. The IAR Embedded Workbench IDE 161
UDSPIC-1
Tools menu
You can remove a command from the Tools menu by selecting it in this list and clicking Remove. Click OK to confirm the changes you have made to the Tools menu and close the dialog box. The menu items you have specified will then be displayed in the Tools menu:
Figure 117: Customized Tools menu
Specifying command line commands or batch files Command line commands or batch files need to be run from a command shell, so to add these to the Tools menu you need to specify an appropriate command shell in the Command text box, and the command line command or batch file name in the Argument text box. The command shells are specified as follows: System
Command shell
Windows 98/Me
command.com
Windows XP/NT/2000
cmd.exe (recommended) or command.com
Table 31: Command shells
The Argument text should be specified as: /C name
where name is the name of the command or batch file you want to run. The /C option terminates the shell after execution, to allow the IAR Embedded Workbench IDE to detect when the tool has completed. For example, to add the command Backup to the Tools menu to make a copy of the entire project directory to a network drive, you would specify Command as command and Argument as: /C copy c:\project\*.* F:
or /C copy $PROJ_DIR$\*.* F:
dsPIC IAR Embedded Workbench™ IDE
162 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
Window menu The commands on the Window menu allow you to manipulate the IAR Embedded Workbench windows and change their arrangement on the screen. The last section of the Window menu lists the windows currently open on the screen, and allows you to activate one by selecting it.
Figure 118: Window menu
NEW WINDOW Opens a new window for the current file.
SPLIT Allows you to split an Editor window horizontally and vertically into two or four panes to allow you to see more parts of a file simultaneously.
CLOSE Closes the current window.
CLOSE ALL Closes all open editor windows.
CASCADE, TILE HORIZONTALLY, TILE VERTICALLY Provide the standard Windows functions for arranging the IAR Embedded Workbench IDE windows on the screen.
Part 3. The IAR Embedded Workbench IDE 163
UDSPIC-1
Help menu
NEXT Brings the next IAR Embedded Workbench IDE window to the foreground again, in the order they are listed in last section of the Window menu.
PREVIOUS Brings the previous IAR Embedded Workbench IDE window to the foreground again, in the order they are listed in last section of the Window menu.
Help menu Provides help about the IAR Embedded Workbench IDE and displays the version numbers of the user interface and of the dsPIC IAR Embedded Workbench IDE.
Figure 119: Help menu
HELP Provides access to the IAR Embedded Workbench IDE online help.
EMBEDDED WORKBENCH GUIDE Provides access to an online version of this user guide, available in PDF format.
ASSEMBLER REFERENCE GUIDE Provides access to an online version of the dsPIC IAR Assembler Reference Guide, available in PDF format.
C/EC++ COMPILER REFERENCE GUIDE Provides access to an online version of the dsPIC IAR C/EC++ Compiler Reference Guide, available in PDF format.
dsPIC IAR Embedded Workbench™ IDE
164 User Guide
UDSPIC-1
IAR Embedded Workbench IDE reference
XLINK AND XLIB REFERENCE GUIDE Provides access to the online version of the IAR Linker and Library Tools Reference Guide, available in PDF format.
ANSI C/EC++ LIBRARY REFERENCE Provides access to the IAR CLIB library documentation, available in PDF format.
IAR ON THE WEB Allows you to browse the home page, the news page, and the technical notes search page of the IAR website, and to contact IAR Technical Support.
ABOUT Clicking the Product info button in the dialog box that opens displays detailed information about the installed IAR products. Copy this information (using the Ctrl+C keyboard shortcut) and include it in your message if you contact IAR Technical Support via electronic mail.
Part 3. The IAR Embedded Workbench IDE 165
UDSPIC-1
Help menu
dsPIC IAR Embedded Workbench™ IDE
166 User Guide
UDSPIC-1
Introduction to the IAR C-SPY Debugger The IAR C-SPY™ Debugger is a powerful interactive debugger for embedded applications. This chapter gives an overview of the functions for debugging projects provided by this tool. Note: For information about the IAR C-SPY Debugger options available in the IAR Embedded Workbench IDE, see the chapter C-SPY options.
Disassembly and source debugging The IAR C-SPY Debugger allows you to switch seamlessly between C/EC++ or assembler source and disassembly debugging as required. All source code editor windows that were open before you started debugging stay open, and you can execute the program one step at a time while monitoring the values of variables and data structures. Source debugging provides the quickest and easiest way of developing your application, without having to worry about how the compiler or assembler has implemented the code. The Disassembly window displays a mnemonic assembler listing of your program based on actual memory contents rather than source code, and lets you execute the program exactly one assembler instruction at a time. Disassembly debugging lets you focus on the critical sections of your application, and provides you with precise control over the hardware. Regardless of which type of window you are debugging in, you can display registers and memory, and change their contents.
PROJECTS BUILT OUTSIDE OF THE EMBEDDED WORKBENCH By opening an executable file in the IAR Embedded Workbench (as described in Open Project, page 136), you create a special debugging project that does not include any source files or other information needed to build applications. This is convenient if you want to debug applications that you have built outside of the IAR Embedded Workbench IDE, for example by compiling your source files from the command line. The only project options that are meaningful to set for this kind of project are general and C-SPY options.
Part 3. The IAR Embedded Workbench IDE 167
UDSPIC-1
Program execution
Program execution The IAR C-SPY Debugger provides a flexible range of options for executing the target program.
GO The Go command continues execution from the current position until a breakpoint or program exit is reached. You can also execute up to a selected point in the program, without having to set a breakpoint, with the Go to Cursor command. Alternatively, you can execute out of a C function with the Step Out command. Program execution is indicated by a red Break command button in the debug toolbar. While the program is executing you may stop it by clicking on the Break button. You may also use any command accelerator associated with the Debug>Break command.
STEPPING The Step Over and Step Into commands allow you to execute the program step by step. Step Into lets you continue stepping inside function or subroutine calls whereas Step Over executes each function call in a single step. The compiler generates detailed stepping information for each source statement in the form of one or more step points associated with the generated machine code. These are placed at the beginning of each statement and at each function call.
Step points at function calls Whenever the program counter is at a step point, C-SPY can highlight a corresponding C or Embedded C++ source range and display information for local variables. If the step point is a function call, you have the choice of stepping into the function or stepping over it to the next step point in the current function. This is particularly useful with C code containing many nested function calls and especially so with Embedded C++ which tends to have many implicit function calls, such as constructors, destructors, assignment operators and other user-defined operators. You can independently choose whether to step into or over each function call.
Step points at statements Depending on your code, the more detailed stepping can be either invaluable or unnecessarily slow. For faster stepping, use the Next Statement command, which steps directly to the first step point in the next statement.
dsPIC IAR Embedded Workbench™ IDE
168 User Guide
UDSPIC-1
Introduction to the IAR C-SPY Debugger
Highlighting For simple statements without function calls, the whole statement is typically highlighted when stepping. When reaching a statement with function calls, C-SPY highlights the first call point since this illustrates much more clearly what Step Into and Step Over would mean at that time. Occasionally, the program counter will be at a machine instruction which is part of a source statement, but not exactly at a step point. This is often the case when stepping in the Disassembly window. In such cases, C-SPY highlights the entire statement in the source window using a pale variation of the normal highlight color, which is green.
BREAKPOINTS You can set breakpoints in the program being debugged using the Toggle Breakpoint command. Statements or instructions at which breakpoints are set are shown highlighted in the source window listing. Alternatively the Edit>Breakpoints command allows you to define and alter complex breakpoints, including break conditions. Since function calls are treated in a special way, you can exert more control when you set breakpoints in source code. However, you must take care. Consider the following example: func1(i, func2(k));
If the insertion point is anywhere in the range for the call to func2 when you set a breakpoint, the break will be put on that function call. When execution stops, you will have a choice of stepping into or over func2. On the other hand, if the insertion point is anywhere else the break will be set on the call to func1. When execution stops, you will have a choice of stepping into or over func1, but not func2, because it has already been called. For detailed reference information about setting breakpoints, see Editing Breakpoints, page 220.
INTERRUPT SIMULATION When you are using the simulator driver, the IAR C-SPY Debugger includes an interrupt system allowing you to simulate the execution of interrupts when debugging. The interrupt system can be turned on or off as required either with a system macro, or using the Interrupts dialog box. The interrupt system is activated by default, but if it is not required it can be turned off to speed up instruction set simulation.
Part 3. The IAR Embedded Workbench IDE 169
UDSPIC-1
Program execution
The interrupt system has the following features:
Interrupts, single or periodical, can be set up so that they are generated based on the cycle counter value.
C-SPY provides interrupt support suitable for the dsPIC microcontroller. By combining an interrupt with a simulator or immediate breakpoint you can simulate peripheral devices, such as a serial port. Note: Since the interrupt system depends on the definitions in the device description file (*.ddf), it is important that you select the appropriate ddf file.
C FUNCTION INFORMATION The dsPIC IAR C/EC++ Compiler generates extensive backtrace information. This allows C-SPY to show, without any runtime penalty, the complete stack of function calls wherever the program counter is. The Call Stack window shows a list of function invocations, with the current function at the top. Double clicking on any function focuses the debugger on that particular call frame. The Editor, Locals, Register, Watch and Disassembly windows are updated to reflect the values of variables and other information in that call frame. In the editor and disassembly windows, a green highlight indicates the topmost, or current, call frame, while a yellow highlight is used when inspecting subordinate frames.
VIEWING AND EDITING MEMORY AND REGISTERS You can display the contents of the processor registers and special function registers in the Register window, and specified areas of memory in the Memory window. The Register window allows you to edit the content of any register, and the register is automatically updated to reflect the change. The Memory window can display the contents of memory in groups of 8, 16, or 32 bits. The contents is editable in place.
TERMINAL I/O The IAR C-SPY Debugger can simulate terminal input and output using the Terminal I/O window.
MACRO LANGUAGE The IAR C-SPY Debugger includes a powerful internal macro language, to allow you to define complex sets of actions to be performed. The macro language includes conditional and loop constructs, and you can use variables and expressions.
dsPIC IAR Embedded Workbench™ IDE
170 User Guide
UDSPIC-1
C-SPY expressions In addition to the C symbols defined in your program, C-SPY™ allows you to define C-SPY variables and macros and use them when evaluating expressions. Expressions that are built with these components are called C-SPY expressions and can be used in the Watch window and in C-SPY macros. This chapter defines the syntax of the expressions and variables used in C-SPY macros.
Expression syntax C-SPY expressions can include any type of C expression, except function calls. The following types of symbols can be used in expressions:
C symbols Assembler symbols; i.e. CPU register names and assembler labels C-SPY variables and C-SPY macros; see the chapter C-SPY macros.
C SYMBOLS C symbols can be referenced by their names. In case of a name conflict, C-SPY variables have a higher precedence than C variables. Examples of valid C-SPY expressions are: i = my_var * my_mac() + #asm_label another_mac(2, my_var)
ASSEMBLER SYMBOLS Assembler symbols can be used in C expressions if they are preceded by #. These symbols can be assembler labels or CPU register names. Example
What it does
#pc++
Increments the value of the program counter.
myptr = #main
Sets myptr to point to label main.
Table 32: C-SPY assembler symbols expressions
In case of a name conflict between a hardware register and an assembler label, hardware registers have a higher precedence. To refer to an assembler label in such a case, you must encapsulate the label in backquotes ` (ASCII character 0x60). For example: Example
What it does
#pc
Refers to the program counter.
#`pc`
Refers to the assembler label pc.
Table 33: Handling name conflicts between h/w registers and assembler labels
Part 3. The IAR Embedded Workbench IDE 171
UDSPIC-1
Expression syntax
Which processor-specific symbols are available can be seen in the Register window, using the CPU Registers filter. See Register window, page 200. If a device description file is used, all special function registers (SFR) may also be used as assembler symbols in the same way as the CPU registers.
dsPIC IAR Embedded Workbench™ IDE
172 User Guide
UDSPIC-1
C-SPY macros The IAR C-SPY™ Debugger provides comprehensive macro capabilities allowing you to automate the debugging process and to simulate peripheral devices. Macros can be used in conjunction with complex breakpoints and interrupt simulation to perform a wide variety of tasks. This chapter deals with how to use and set up C-SPY macros. At the end of the chapter, there is reference information for each built-in system macro provided with C-SPY. Using interrupts, breakpoints, and macros in the Compiler tutorials chapter gives an example of how C-SPY macros can be used.
Using C-SPY macros C-SPY allows you to define both macro variables (global or local) and macro functions. In addition, several predefined system macro functions are provided; they return information about the system status, and perform complex tasks such as opening and closing files, and file I/O operations. System macro names start with double underscore and are reserved names. Note: To view the available macros, select Debug>Macros. The available macros will be displayed in the Macro Configuration dialog box, under Registered Macros. You can select whether to view all macros, the predefined system macros, or the user-defined macros. For more information, see Macros, page 213.
Defining macros To define a macro variable or macro function, you should first create a text file containing its definition. You can use any suitable text editor, such as the IAR Embedded Workbench™ Editor. Then you should register the macro file. There are several ways to do this:
You can register a macro by choosing Macros from the Debug menu. For more information, see Macros, page 213.
In the IAR Embedded Workbench, you can specify which setup file to use with a project. See Setting C-SPY options, page 121, for more information.
Macros can also be registered using the system macro __ registerMacroFile. This macro allows you to register macro files from other macros. This means that you can dynamically select which macro files to register, depending on the runtime conditions. For more information, see __registerMacroFile, page 184.
Part 3. The IAR Embedded Workbench IDE 173
UDSPIC-1
Using C-SPY macros
Executing C-SPY macros You can assign values to a macro variable, or execute a macro function from within another C-SPY macro including setup macros. You can also execute C-SPY macros in the Quick Watch dialog box, see Quick Watch, page 211. For details of the setup macros, see C-SPY setup macros, page 177. A macro can also be executed if it is associated with a breakpoint that is activated.
MACRO VARIABLES A macro variable is a variable defined and allocated outside the user program space. It can then be used in a C-SPY expression. The command to define one or more macro variables has the following form: __var nameList;
where nameList is a list of C-SPY variable names separated by commas. A macro variable defined outside a macro body has global scope, and retains its value and type through the whole debugging session. A macro variable defined within a macro body is created when its definition is executed and destroyed on return from the macro. By default a macro variable is initialized to signed integer 0. When a C-SPY variable is assigned a value in an expression, it also acquires the type of that expression. For example: Expression
What it means
myvar = 3.5
myvar is now type float, value 3.5.
myvar = (int*)i myvar is now type pointer to int, and the value is the same as i. Table 34: Examples of C-SPY macro variables
MACRO FUNCTIONS C-SPY macro functions consist of a series of C-SPY variable definitions and macro statements which are executed when the macro is called. An unlimited number of parameters can be passed to a macro, and macros can return a value on exit. A C-SPY macro has the following form: macroName (parameterList) { macroBody }
where parameterList is a list of macro formal names separated by commas, and macroBody is any series of C-SPY variable definitions and C-SPY statements.
dsPIC IAR Embedded Workbench™ IDE
174 User Guide
UDSPIC-1
C-SPY macros
Type checking is not performed on the values passed to the macro parameters.
MACRO STATEMENTS The following C-SPY macro statements are accepted:
Expressions expression;
Conditional statements if (expression) statement if (expression) statement else statement
Loop statements for (init_expression; cond_expression; after_expression) statement while (expression) statement do statement while (expression);
Return statements return; return expression;
If the return value is not explicitly set by default, signed int 0 is returned.
Blocks { statement1 statement2 . . . statementN }
Part 3. The IAR Embedded Workbench IDE 175
UDSPIC-1
Using C-SPY macros
In the above example, expression means a C-SPY expression; statements are expected to behave in the same way as corresponding C statements would do.
Printing messages The __message statement allows you to print messages while executing a macro. Its definition is as follows: __message argList;
where argList is a list of C-SPY expressions or strings separated by commas, as in the following example: __message "The result is ", res, " units. The most common mask is 0x", mask:%x, ".";
This could produce The result is 42 units. The most common mask is 0x37c0.
The value of expression arguments or strings are printed to the Log window. It is possible to override the default display format of a scalar argument (number or pointer) in argList by suffixing it with a : followed by a format specifier. Available specifiers are b for binary, o for octal, d for decimal, x for hexadecimal and c for character. These match the formats available in the Watch and Locals windows, but number prefixes and quotes around strings and characters are not printed. Another example: __message "The character '", cvar:%c, "' has the decimal value ", cvar;
This could produce The character 'A' has the decimal value 65
Note: A character enclosed in single quotes (a character literal) is an integer constant and is not automatically formatted as a character. For example: __message 'A', " is the numeric value of the character ", 'A':%c;
would produce 65 is the numeric value of the character A
There is also a statement __fmessage which is similar to __message, except that the first argument must be a file handle. The output is then written to the designated file. For example: __fmessage myfile, "Result is ", res, "!\n";
dsPIC IAR Embedded Workbench™ IDE
176 User Guide
UDSPIC-1
C-SPY macros
C-SPY setup macros The setup macros are reserved macro names that will be called by C-SPY at specific stages during execution. To use them you should create and register a macro with the name specified in the following table: Macro
Description
execUserPreload()
Called after communication with the target system is established but before downloading the target program. Implement this macro to initialize memory locations and/or registers which are vital for loading data properly.
execUserSetup()
Called once after the target program is downloaded. Implement this macro to set up the memory map, breakpoints, interrupts, register macro files, etc.
execUserReset()
Called each time the reset command is issued. Implement this macro to set up and restore data.
execUserExit()
Called once when the debug session ends. Implement this macro to save status data etc.
Table 35: C-SPY setup macros
Note: If you define interrupts or breakpoints in a macro file that is executed at system start (using execUserSetup) we strongly recommend that you also make sure that they are removed at system shutdown (using execUserExit); an example is available in tutor2.mac. The reason for this is that the simulator saves breakpoint and interrupt settings between sessions and if they are not removed they will get duplicated every time execUserSetup is executed again. This seriously affects the execution speed.
Descriptions of C-SPY system macros C-SPY includes the following system macros: Macro
Description
__cancelAllInterrupts
Cancels all ordered interrupts.
__cancelInterrupt
Cancels an interrupt.
__clearBreak
Clears a brekpoint.
__closeFile
Closes a file that was open by __openFile.
__disableInterrupts
Disables generation of interrupts.
__driverType
Verifies the driver type.
Table 36: Summary of system macros
Part 3. The IAR Embedded Workbench IDE 177
UDSPIC-1
Descriptions of C-SPY system macros
Macro
Description
__enableInterrupts
Enables generation of interrupts.
__openFile
Opens a file for I/O operations.
__orderInterrupt
Generates an interrupt.
__readFile
Reads from the specified file.
__readFileByte
Reads one byte from the specified file.
__readMemoryByte
Reads one byte from the specified memory location.
__registerMacroFile
Registers macros from the specified file.
__resetFile
Rewinds a file opened by __openFile .
__setCodeBreak
Sets a code breakpoint.
__setDataBreak
Sets a data breakpoint.
__setSimBreak
Sets a simulation breakpoint.
__strFind
Searches a given string for the occurrence of another string.
__subString
Extracts a substring from another string.
__toLower
Returns a copy of the parameter string where all the characters have been converted to lower case.
__toUpper
Returns a copy of the parameter string where all the characters have been converted to upper case.
__writeFile
Writes to the specified file.
__writeFileByte
Writes one byte to the specified file.
__writeMemoryByte
Writes one byte to the specified memory location.
Table 36: Summary of system macros (Continued)
The following sections gives reference information about each of the C-SPY system macros.
__cancelAllInterrupts __cancelAllInterrupts()
Return value int 0
Description Cancels all ordered interrupts. This macro is only applicable to the simulator version of C-SPY. For additional information, see Interrupts, page 215.
dsPIC IAR Embedded Workbench™ IDE
178 User Guide
UDSPIC-1
C-SPY macros
__cancelInterrupt __cancelInterrupt(interrupt_id)
Parameter interrupt_id
The value returned by the corresponding __orderInterrupt macro call (unsigned long)
Return value Result
Value
Successful
int 0
Unsuccessful
Non-zero error number
Table 37: __cancelInterrupt return values
Description Cancels an interrupt. This macro is only applicable to the simulator version of C-SPY. For additional information, see Interrupts, page 215.
_ _clearBreak __clearBreak(break_id)
Parameter break_id
The value returned by any of the set breakpoint macros
Return value int 0
Description Clears a user-defined breakpoint. For additional information, see Editing Breakpoints, page 220.
__closeFile
__closeFile(filehandle)
Parameter filehandle
The macro variable used as filehandle by the __openFile macro
Part 3. The IAR Embedded Workbench IDE 179
UDSPIC-1
Descriptions of C-SPY system macros
Return value int 0.
Description Closes a file previously opened by __openFile.
__disableInterrupts __disableInterrupts()
Return value Result
Value
Successful
int 0
Unsuccessful
Non-zero error number
Table 38: __disableInterrupts return values
Description Disables the generation of interrupts. This macro is only applicable to the simulator version of C-SPY. For additional information, see Interrupts, page 215.
_ _driverType __driverType(driver_id)
Parameter driver_id
A string corresponding to the driver you want to check for; one of the following: "sim" corresponds to the simulator driver
Return value Result
Value
Successful
1
Unsuccessful
0
Table 39: __driverType return values
Description Checks to see if the current IAR C-SPY Debugger driver is identical to the driver type of the driver_id parameter.
dsPIC IAR Embedded Workbench™ IDE
180 User Guide
UDSPIC-1
C-SPY macros
Example __driverType("sim")
If a simulator is the current driver, the value 1 is returned. Otherwise 0 is returned.
_ _enableInterrupts __enableInterrupts()
Return value Result
Value
Successful
int 0
Unsuccessful
Non-zero error number
Table 40: __enableInterrupts return values
Description Enables the generation of interrupts. This macro is only applicable to the simulator version of C-SPY. For additional information, see Interrupts, page 215.
_ _openFile __openFile(file, access)
Parameters file
The filename as a string
access
The access type (string); one of the following: “r” ASCII read “w” ASCII write
Return value Result
Value
Successful
The file handle
Unsuccessful
An invalid file handle, which tests as False
Table 41: __openFile return values
Description Opens a file for I/O operations. The default base directory of this macro is where the currently open project file (*.pew or *.prj) is located. The argument to __openFile can specify a location relative to this directory. In addition, you can use argument variables such as $PROJ_DIR$ and $TOOLKIT_DIR$ in the path argument; see Table 30, Argument variables, page 161.
Part 3. The IAR Embedded Workbench IDE 181
UDSPIC-1
Descriptions of C-SPY system macros
Example __var filehandle;
/* The macro variable to contain */ /* the file handle */ filehandle = __openFile("Debug\\Exe\\test.tst", "r"); if (filehandle) { /* successful opening */ }
_ _orderInterrupt __orderInterrupt(specification, activation_time, repeat_interval, jitter, latency, probability)
Parameters specification
The interrupt (string). The specification could either be the full specification used in the device description file (ddf) or only the name. In the latter case the interrupt system will automatically get the description from the device description file.
activation_time
The activation time in cycles (integer)
repeat_interval
The periodicity in cycles (integer)
jitter
The timing variation range (integer between 0 and 100)
latency
The latency (integer)
probability
The probability in percent (integer between 0 and 100)
Return value The macro returns an interrupt identifier (unsigned long). If the syntax of specification is incorrect, it returns -1.
Description Generates an interrupt. This macro is only applicable to the simulator version of C-SPY. For additional information, see Interrupts, page 215. Example The following example generates a repeating interrupt first activated after 4000 cycles: __orderInterrupt( "U1RX", 4000, 2000, 0, 0, 100 );
dsPIC IAR Embedded Workbench™ IDE
182 User Guide
UDSPIC-1
C-SPY macros
_ _readFile __readFile(file, value)
Parameters file
A file handle
value
A pointer to a macro variable
Return value Result
Value
Successful
0
Unsuccessful
Non-zero error number
Table 42: __readFile return values
Description Reads a sequence of hexadecimal digits from the given file and converts them to an unsigned long which is assigned to the value parameter, which should be a pointer to a macro variable. Example __var number; if (__readFile(myFile, &number) == 0) { // Do something with number }
_ _readFileByte __readFileByte(file)
Parameter file
A file handle
Return value -1 upon error or end-of-file, otherwise a value between 0 and 255.
Description Reads one byte from the file file.
Part 3. The IAR Embedded Workbench IDE 183
UDSPIC-1
Descriptions of C-SPY system macros
Example __var byte; while ( (byte = __readFileByte(myFile)) != -1 ) { // Do something with byte }
_ _readMemoryByte __readMemoryByte(address, zone)
Parameters address
The memory address (integer)
zone
The memory zone name (string); select it from the Memory window drop-down menu
Return value The macro returns the value from memory.
Description Reads one byte from a given memory location. Example __readMemoryByte(0x0108, "Code");
__registerMacroFile __registerMacroFile(filename)
Parameter filename
A file containing the macros to be registered (string)
Return value int 0
Description Registers macros from a specified macro file. For additional information, see Macros, page 213.
dsPIC IAR Embedded Workbench™ IDE
184 User Guide
UDSPIC-1
C-SPY macros
Example __registerMacroFile("c:\\testdir\\macro.mac");
__resetFile __resetFile(filehandle)
Parameter filehandle
The macro variable used as filehandle by the __openFile macro
Return value int 0
Description Rewinds the file previously opened by __openFile.
_ _setCodeBreak __setCodeBreak(location, count, condition, cond_type, action)
Parameters location
A string with a location description. This can be either: A source location on the form {filename}.line.col (for example {D:\\src\\prog.c}.12.9) An absolute location on the form zone:hexaddress or simply hexaddress (for example Code:0x42) An expression whose value designates a location (for example main)
count
The number of times that a breakpoint condition must be fulfilled before a break occurs (integer)
condition
The breakpoint condition (string)
cond_type
The condition type; either “CHANGED” or “TRUE” (string)
action
An expression, typically a call to a macro, which is evaluated when the breakpoint is detected
Part 3. The IAR Embedded Workbench IDE 185
UDSPIC-1
Descriptions of C-SPY system macros
Return value Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. This value must be used to clear the breakpoint.
Unsuccessful
0
Table 43: __setCodeBreak return values
Description Sets a code breakpoint, that is, a breakpoint which is triggered when the processor fetches an instruction at the specified location. Example __setCodeBreak("{D:\\src\\prog.c}.12.9", 3, "d>16", "TRUE", "ActionCode()");
For additional information, see Editing Breakpoints, page 220.
_ _setDataBreak __setDataBreak(location, count, condition, cond_type, access, action)
Parameters location
A string with a location description. This can be either: A source location on the form {filename}.line.col (for example {D:\\src\\prog.c}.12.9), although this is not very useful for data breakpoints An absolute location on the form zone:hexaddress or simply hexaddress (for example Data:0x42) An expression whose value designates a location (for example main).
count
The number of times that a breakpoint condition must be fulfilled before a break occurs (integer)
condition
The breakpoint condition (string)
cond_type
The condition type; either “CHANGED” or “TRUE” (string)
access
The memory access type: "R" for read, "W" for write, or "RW" for read/write
action
An expression, typically a call to a macro, which is evaluated when the breakpoint is detected
dsPIC IAR Embedded Workbench™ IDE
186 User Guide
UDSPIC-1
C-SPY macros
Return value Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. This value must be used to clear the breakpoint.
Unsuccessful
0
Table 44: __setDataBreak return values
Description Sets a data breakpoint, that is, a breakpoint which is triggered when the processor reads or writes data at the specified location. This macro is only applicable to the simulator version of C-SPY. Example __var brk; brk = __setDataBreak("Data:0x4711", 3, "d>6", "TRUE", "W", "ActionData()"); ... __clearBreak(brk);
For additional information, see Editing Breakpoints, page 220.
__setSimBreak __setSimBreak(location, access, action)
Parameters location
A string with a location description. This can be either: A source location on the form {filename}.line.col (for example {D:\\src\\prog.c}.12.9), although this is not very useful for simulation breakpoints An absolute location on the form zone:hexaddress or simply hexaddress (for example Memory:0x42) An expression whose value designates a location (for example main).
access
The memory access type: "R" for read or "W" for write
action
An expression, typically a call to a macro, which is evaluated when the breakpoint is detected
Part 3. The IAR Embedded Workbench IDE 187
UDSPIC-1
Descriptions of C-SPY system macros
Return value Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. This value must be used to clear the breakpoint.
Unsuccessful
0
Table 45: __setSimBreak return values
Description Sets an immediate breakpoint. An immediate breakpoint does not stop execution, but it allows a macro to be called when the processor is about to read data from a location or immediately after it has written data. The call happens immediately, i.e. during execution of the instruction. These breakpoints are useful for simulating memory-mapped devices of various kinds (e.g. serial ports, timers, etc.). When the processor reads an SFR location, a macro can intervene and supply appropriate data and conversely, when the processor writes to an SFR location, a macro can act upon the value written. This macro is only applicable to the simulator version of C-SPY. For additional information, see Editing Breakpoints, page 220. See Using interrupts, breakpoints, and macros, page 49, for an example where an immediate breakpoint is used.
__strFind __strFind(str, pat, pos)
Parameters str
The string to search in
pat
The string pattern to search for
pos
The position where to start the search. The first position is 0
Return value The position where the pattern was found or -1 if the string is not found.
Description This macro searches a given string for the occurrence of another string.
dsPIC IAR Embedded Workbench™ IDE
188 User Guide
UDSPIC-1
C-SPY macros
Example __strFind("Compiler", "pile", 0) __strFind("Compiler", "foo", 0)
= 3 = -1
__subString __subString(str, pos, len)
Parameters str
The string from which to extract a substring
pos
The start position of the substring
len
The length of the substring
Return value A substring extracted from the given string.
Description This macro extracts a substring from another string. Example __subString("Compiler", 0, 2) __subString("Compiler", 3, 4)
= "Co" = "pile"
__toLower __toLower(str)
Parameter str is any string.
Return value The converted string.
Description This macro returns a copy of the parameter string where all the characters have been converted to lower case. Example __toLower("IAR") __toLower("Mix42")
= "iar" = "mix42"
Part 3. The IAR Embedded Workbench IDE 189
UDSPIC-1
Descriptions of C-SPY system macros
__toUpper __toUpper(str)
Parameter str is any string.
Return value The converted string.
Description This macro returns a copy of the parameter string where all the characters have been converted to upper case. Example __toUpper("string")
= "STRING"
__writeFile __writeFile(file, value)
Parameters file
A file handle
value
An integer
Return value int 0
Description Prints the integer value in hexadecimal format (with a trailing space) to the file file. Note: The __fmessage statement can do the same thing. The __writeFile macro is provided for symmetry with __readFile.
__writeFileByte __writeFileByte(file, value)
Parameters file
A file handle
value
An integer in the range 0-255
dsPIC IAR Embedded Workbench™ IDE
190 User Guide
UDSPIC-1
C-SPY macros
Return value int 0
Description Writes one byte to the file file.
__writeMemoryByte __writeMemoryByte(value, address, zone)
Parameters value
The value to be written (integer)
address
The memory address (integer)
zone
The memory zone name (string); select it from the Memory window drop-down menu
Return value int 0
Description Writes one byte to a given memory location. Example __writeMemoryByte(0x2F, 0x1F, "Code");
Part 3. The IAR Embedded Workbench IDE 191
UDSPIC-1
Descriptions of C-SPY system macros
dsPIC IAR Embedded Workbench™ IDE
192 User Guide
UDSPIC-1
C-SPY Debugger reference This chapter contains detailed descriptions about the windows, menus, menu commands, and their components found in the IAR C-SPY™ Debugger.
The C-SPY windows The following illustration shows the main IAR Embedded Workbench IDE window when you are debugging, using the IAR C-SPY Debugger:
Menu bar Toolbar
Project window
Editor window
Status bar
Figure 120: Embedded Workbench with C-SPY started
Part 3. The IAR Embedded Workbench IDE 193
UDSPIC-1
The C-SPY windows
TYPES OF C-SPY WINDOWS The following windows are available in the IAR Embedded Workbench IDE when the IAR C-SPY Debugger is running:
Disassembly window Memory window Register window Watch window Locals window Call Stack window Log window Terminal I/O window Code Coverage window Profiling window.
These windows are described in greater detail on the following pages.
USING LAYOUTS While debugging different types of projects and depending on the current focus when debugging, you may want to arrange the debugger windows in a particular way, for instance their size and position on the screen. This can be done by using layouts that specify the window arrangement. At any time during a debug session, you can save and load any number of layouts reflecting your preferences, specify which one to use as the default layout, or use the default layout supplied with the product. The layout information is saved with the project when you stop the debugger. For details about the commands, see Debug menu, page 210.
EDITING IN C-SPY WINDOWS The contents of the Memory, Register, Watch, and Locals windows is editable. Use the following keys to edit the contents of the Register window: Key
Description
Tab
Selects an item.
Return
Makes an item editable and saves the new value.
Esc
Cancels a new value.
Table 46: Editing in C-SPY windows
dsPIC IAR Embedded Workbench™ IDE
194 User Guide
UDSPIC-1
C-SPY Debugger reference
MENUS Gives access to the C-SPY-specific menu items: Menu
Description
Debug
The Debug menu provides commands for executing and debugging the source program. Most of the commands are also available as icon buttons in the debug toolbar.
Simulator
The Simulator menu provides access to the dialog boxes for setting up interrupt simulation and memory maps.
Table 47: C-SPY menus
The menus are described in greater detail on the following pages. There may also be other debugging menus available, depending on your IAR Embedded Workbench configuration.
DEBUG TOOLBAR The debug toolbar provides buttons for the most frequently-used commands on the Debug menu. You can display a description of any button by pointing to it with the mouse pointer. When a command is not available the corresponding button will be grayed out and you will not be able to select it. The following diagram shows the command corresponding to each button:
Step Into
Break
Reset
Step over
Next Statement
Step Out
Run to Cursor
Go
Stop Debugging
Toggle Breakpoint
Figure 121: C-SPY debug toolbar
DISASSEMBLY WINDOW The C-SPY Disassembly window shows the program being debugged as disassembled program code. If you have closed the editor windows displaying the C source files, you can open them again in the normal manner to see the C source code being debugged.
Part 3. The IAR Embedded Workbench IDE 195
UDSPIC-1
The C-SPY windows
Go to memory address
Toggle disassembly mode
Current position Zone display
Breakpoint
Figure 122: C-SPY Disassembly window
Zone display The Zone box allows you to choose which memory or register zone to display. By default there is one program address zone only in the debugger, namely Code, which covers the whole dsPIC program memory range. It is possible to define additional zones by adding them to the appropriate device description file.The syntax is described in the file. You may also delete unwanted zones or edit their characteristics just by editing the file. Remember to make a copy of the original file. Note: IAR Systems reserves the right to without further notice change the syntax used in device description files.
Go to memory address Type the memory location you want to view in the Go to box, and press Enter. You can also choose from a list of the latest memory locations you have accessed using the drop-down list.
dsPIC IAR Embedded Workbench™ IDE
196 User Guide
UDSPIC-1
C-SPY Debugger reference
Toggle disassembly mode By clicking this button, the source code corresponding to the disassembled lines will be displayed as well. A source code statement will precede the machine instructions generated by the compiler or assembler for this statement. Note that one source code line may include several statements. The entire source code line is displayed, but the statement for which code is generated is underlined. Source code information requires that the corresponding source file has been compiled with debug information.
Highlighting The current position indicates the next assembler instruction to be executed, and is highlighted in green. Assembler instructions at which code breakpoints have been set are highlighted in red. To set a code breakpoint, choose Edit>Toggle Breakpoint or click the Toggle Breakpoint button in the toolbar.
Cursor You can move the cursor to any line in the Disassembly window by clicking on the line with the mouse pointer. Alternatively, you can move the cursor using the navigation keys. The Debug>Run to Cursor command will execute the program from the current position up to the line containing the cursor.
Pop-up menu Clicking the right mouse button in the Disassembly window displays a pop-up menu which gives you access to several useful commands.
Figure 123: Disassembly window pop-up menu
Part 3. The IAR Embedded Workbench IDE 197
UDSPIC-1
The C-SPY windows
MEMORY WINDOW The Memory window gives an up-to-date display of a specified area of memory and allows you to edit it. You can open several instances of this window, which is very convenient if you want to keep track of different memory or register zones, or monitor different parts of the memory.
Go to memory address Zone display
Figure 124: Memory window
Zone display The Zone box allows you to choose which memory or register zone to display. By default there are two zones in the debugger, namely Code, which covers the whole dsPIC program memory range, and Data, which covers the whole dsPIC data memory range. It is possible to define additional zones by adding them to the appropriate device description file.The syntax is described in the file. You may also delete unwanted zones or edit their characteristics just by editing the file. Remember to make a copy of the original file. Note: IAR Systems reserves the right to without further notice change the syntax used in device description files.
Go to memory address Type the memory location you want to view in the Go to box, and press Enter. You can also choose from a list of the latest memory locations you have accessed using the drop-down list.
dsPIC IAR Embedded Workbench™ IDE
198 User Guide
UDSPIC-1
C-SPY Debugger reference
Display options Choose x1, x2, or x4 to display the memory contents in units of 8, 16, or 32 bits. You can also choose between displaying the contents in big-endian or little-endian order. An asterisk (*) indicates the default endianess. Clicking the right mouse button in the Memory window displays a pop-up menu which gives you access to several useful commands.
Figure 125: Memory window pop-up menu
Memory Fill This menu option allows you to fill a specified area of memory with a value. The following dialog box is displayed to allow you to specify the area to fill:
Figure 126: Memory Fill dialog box
Enter the Start Address and Length—in binary, octal, decimal or hexadecimal notation—and select the memory zone type from the Zone drop-down list.
Part 3. The IAR Embedded Workbench IDE 199
UDSPIC-1
The C-SPY windows
Enter the Value to be used for filling each memory location and select the logical operation. The default is Copy, but you may choose one of the following operations: Operation
Description
Copy
The Value will be copied to the specified memory area.
AND
An AND operation will be performed between the Value and the existing contents of memory before writing the result to memory.
XOR
An XOR operation will be performed between the Value and the existing contents of memory before writing the result to memory.
OR
An OR operation will be performed between the Value and the existing contents of memory before writing the result to memory.
Table 48: Memory fill operations
Finally choose OK to proceed with the memory fill.
REGISTER WINDOW The Register window gives an up-to-date display of the contents of the processor registers, and allows you to edit them. When a value changes it becomes highlighted. You can open several instances of this window, which is very convenient if you want to keep track of different register groups.
Figure 127: Register window
You can select which register group to display in the Register window using the drop-down list. To change the contents of a register, click it. Some registers are expandable, which means that the register contains interesting sub-groups of bits. Note: If the contents of a register changes during execution, the change will be highlighted in this window.
dsPIC IAR Embedded Workbench™ IDE
200 User Guide
UDSPIC-1
C-SPY Debugger reference
Register groups By default there is one register group in the dsPIC debugger, namely CPU Registers. If target-specific device description files are used, additional groups are defined, thus making all SFR registers available in the register window. The device description file contains an entry specifying which SFR specification file (*.sfr) to use for defining the special function registers and their groups. Use the register filter functionality described in Register filter, page 159 when designing application-specific groups.
WATCH WINDOW Allows you to monitor the values of C expressions or variables:
Figure 128: C-SPY Watch window
When a value changes it becomes highlighted.
Viewing the contents of an expression To view the contents of an expression such as an array, a struct or a union, click the plus sign icon to expand the tree structure.
Modifying an expression To modify an existing expression, edit the left-most column in the Watch window.
Part 3. The IAR Embedded Workbench IDE 201
UDSPIC-1
The C-SPY windows
Adding an expression to the Watch window To add an expression to the Watch window, click in the dotted rectangle and type the expression you want to add, or select an expression in another window and drag it to the Watch window. Alternatively, click the right mouse button in the Watch window and choose Add from the pop-up menu.
Figure 129: Add command on C-SPY Watch window pop-up menu
Then type the expression and press Enter. When a value changes it becomes highlighted.
Removing an expression Select the expression and press the Delete key, or choose Remove from the pop-up menu.
LOCALS WINDOW Automatically displays the local variables and function parameters:
Figure 130: Locals window
Select a value in the Locals window and click it to edit it.
dsPIC IAR Embedded Workbench™ IDE
202 User Guide
UDSPIC-1
C-SPY Debugger reference
CALL STACK WINDOW Displays the C call stack. Each entry has the format: function(values)
where values is a list of the current value of the parameters, or empty if the function does not take any parameters.
Figure 131: Call Stack window
The current function is listed at the top. To inspect a function call, double click it. C-SPY now focuses on that call frame instead. The editor, Locals, Register, Watch and Disassembly windows are updated to reflect the values of variables and other information in that call frame. In the editor and Disassembly windows, a green highlight indicates the topmost, or current, call frame, while a yellow highlight is used when inspecting subordinate frames.
LOG WINDOW Displays debugger output, such as diagnostic messages and trace information.
Figure 132: Log window
Part 3. The IAR Embedded Workbench IDE 203
UDSPIC-1
The C-SPY windows
TERMINAL I/O WINDOW Allows you to enter input to your program, and display output from it.
Figure 133: Terminal I/O window
To use this window, you need to link the program with the option Debug info with terminal I/O. C-SPY will then direct stdin, stdout and stderr to this window. The window will only be available if your program uses the terminal I/O functions in the C library. If the Terminal I/O window is open, C-SPY will write output to it, and read input from it. If the Terminal I/O window is closed, C-SPY will open it automatically when input is required, but not for output.
Input Mode Use this button to choose whether to input data from the keyboard or from a text file. The following dialog box opens:
Figure 134: Change Input Type dialog box
When a file is used for input, the Terminal I/O window will read one line from the file every time that input is requested. If the program requests more input than the file can provide, the mode will automatically switch to keyboard input when the end of file is reached.
dsPIC IAR Embedded Workbench™ IDE
204 User Guide
UDSPIC-1
C-SPY Debugger reference
CODE COVERAGE WINDOW This window reports the current code coverage status, that is, what parts of the code that have been reached so far during execution. The report includes all modules and functions, and the step points that have not yet been executed. The coverage will continue until turned off. Note: The code coverage functionality is available only in the simulator version of C-SPY.
Figure 135: Code Coverage window
The code coverage information is displayed in a tree structure, showing the program, module, function and step point levels. The plus sign and minus sign icons allow you to expand and collapse the structure. The percentage displayed at the end of every program, module and function line shows the amount of code that has been covered so far. For step point lines, the information displayed is the column range and row of the step point in the source window, and the address of the step point. The window displays only statements with debug info. Thus, start-up code, exit code and library code will not be displayed in the window. Furthermore, coverage information for statements in inlined functions will not be displayed. Only the statement containing the inlined function call will be marked as executed. The following icons are used to give you an overview of the current status on all levels:
A red diamond signifies that 0% of the code has been covered. A green diamond signifies that 100% of the code has been covered. A red and green diamond signifies that some of the code has been covered. A yellow diamond signifies a step point that has not been executed.
Part 3. The IAR Embedded Workbench IDE 205
UDSPIC-1
The C-SPY windows
When a step point has been executed, it is removed from the window. Double-clicking a step point or a function in the Code Coverage window displays that step point or function as the current position in the source window, which becomes the active window. Double-clicking a module or the program level expands or collapses the tree structure. An asterisk (*) in the title bar indicates that C-SPY has continued to execute, and that the Code Coverage window needs to be refreshed because the displayed information is no longer up to date. This is accomplished by using the Reload command described below. Clicking the right mouse button in the Code Coverage window displays a pop-up menu that gives you access to several useful commands. Most of the commands are also available as icon buttons in the toolbar of the Code Coverage window.
Figure 136: Code Coverage window pop-up menu
Activate Switches code coverage on and off during execution.
Clear Clears the code coverage information. All step points are marked as not executed.
Refresh Reloads the code coverage information and updates the window. All executed step points are removed from the tree.
Auto-refresh Toggles the automatic reload of code coverage information on and off. When turned on, the code coverage information is reloaded automatically when C-SPY stops at a breakpoint, at a step point, and at program exit.
Save As Saves the current code coverage information in a text file.
dsPIC IAR Embedded Workbench™ IDE
206 User Guide
UDSPIC-1
C-SPY Debugger reference
PROFILING WINDOW This window displays profiling information, that is, timing information for the functions in a program. Profiling must be turned on explicitly by using an icon button in the window’s toolbar, but will stay active as long as it is not turned off. Note: The profiling functionality is available only in the simulator version of C-SPY.
Figure 137: Profiling window
The Profiling window contains the following columns:
Function is the name of each function. Calls is the number of times each function has been called. Flat Time is the total time spent in each function in cycles or as a percentage of the total number of cycles, excluding all function calls made from that function.
Accumulated Time is time spent in each function in cycles or as a percentage of the total number of cycles, including all function calls made from that function. The information in the percentage colums for Flat time and Accumulated time can be displayed either as numbers or as bar charts. Clicking on a column header sorts the complete list according to the column. There is always an item in the list called Outside main. This is time that cannot be placed in any of the functions in the list, for instance the time it takes to get to the main function, outside of any known functions. Time is only measured at the entry and return of a function. This means that local time consumed in a function is not added until the function returns or another function is called. You will only notice this if you are stepping into a function.
Part 3. The IAR Embedded Workbench IDE 207
UDSPIC-1
The C-SPY windows
An item in the list may be displayed using gray text. This indicates a function for which at least one of the calls was not measured in time. When a function is called by functions that do not have their source code available, such as library functions, no measurement in time is made. Thus, a function displayed in gray has been called by functions without source code. Clicking the right mouse button in the Profiling window displays a pop-up menu which gives you access to several useful commands. Most of the commands are also available as icon buttons in the toolbar of the Profiling window.
Figure 138: Profiling window pop-up menu
Activate Switches profiling on and off during execution.
New measurement Starts a new measurement. By clicking on the icon the values displayed are reset to zero.
Graph Displays the percentage information for Flat Time and Accumulated Time as graphs (bar charts) or numbers. The figure below shows the display using graphs.
Figure 139: Graphs in Profiling window
dsPIC IAR Embedded Workbench™ IDE
208 User Guide
UDSPIC-1
C-SPY Debugger reference
Show details Shows more detailed information about the function selected in the list. A window is opened showing information about callers and callees for the selected function:
Figure 140: Function details window
Refresh Updates the profiling information and refreshes the window.
Auto refresh Toggles the automatic update of profiling information on and off. When turned on, the profiling information is updated automatically when C-SPY stops at a breakpoint, at a step point, and at program exit.
Save As Saves the current profiling information in a text file.
Part 3. The IAR Embedded Workbench IDE 209
UDSPIC-1
Debug menu
Debug menu The Debug menu provides commands for executing and debugging your application. Most of the commands are also available as icon buttons in the toolbar.
Figure 141: Debug menu
GO Executes from the current statement or instruction until a breakpoint or program exit is reached.
BREAK Stops program execution.
RESET Resets the target processor.
STOP DEBUGGING Stops the debugging session and returns you to the project manager.
dsPIC IAR Embedded Workbench™ IDE
210 User Guide
UDSPIC-1
C-SPY Debugger reference
STEP OVER Executes the next statement or instruction, without entering C or Embedded C++ functions or assembler subroutines.
STEP INTO Executes the next statement or instruction, entering C or Embedded C++ functions or assembler subroutines. Note: To step into functions or subroutines compiled without debug information, you must Step Into from the Disassembly window.
STEP OUT Executes from the current statement up to the statement after the call to the current function.
NEXT STATEMENT If stepping into and out of functions is unnecessarily slow, use the Next Statement command to step directly to the first step point in the next statement.
RUN TO CURSOR Executes from the current statement or instruction up to a selected statement or instruction.
QUICK WATCH Allows you to watch the value of a variable or expression and to execute macros. Displays the following dialog box to allow you to specify the expression to watch:
Figure 142: QuickWatch window
Part 3. The IAR Embedded Workbench IDE 211
UDSPIC-1
Debug menu
Enter the C-SPY variable or expression you want to evaluate in the Expression box. Alternatively, you can select an expression you have previously watched from the drop-down list. For detailed information about C-SPY expressions, see Expression syntax, page 171. Then choose Recalculate to evaluate the expression, or Add Watch to evaluate the expression and add it to the Watch window. Choose Close to close the Quick Watch dialog box.
REFRESH Refreshes the contents of the Memory, Register, Watch, and Locals windows.
SET NEXT STATEMENT Moves the program counter directly to where the cursor is, without executing any source code. Note, however, that this creates an anomaly in the program flow and may have unexpected effects.
dsPIC IAR Embedded Workbench™ IDE
212 User Guide
UDSPIC-1
C-SPY Debugger reference
MACROS Displays the following dialog box, to allow you to specify a list of files from which to read macro definitions into C-SPY:
Figure 143: Macro Files dialog box
Select the macro definition files you want to use in the file selection list, and click Add to add them to the Selected Macro Files list or Add All to add all the listed files. You can remove files from the Selected Macro Files list using Remove or Remove All. Once you have selected the macro definition files you want to use click Register to register them, replacing any previously defined macros or variables. Registered macros are also displayed in the scroll window under Registered Macros. Clicking on either Name or File under Registered Macros displays the column contents sorted by macro names or by file. Clicking once again sorts the contents in the reverse order. Selecting All displays all macros, selecting User displays all user macros, and selecting System displays all system macros.
Part 3. The IAR Embedded Workbench IDE 213
UDSPIC-1
Debug menu
Double-clicking a user-defined macro in the Name column automatically opens the file. Click Close to exit the Macro Files window.
LOGGING > SET LOG FILE Allows you to log input and output from C-SPY to a file. This command displays a dialog box where you select the type and the location of the log file. You can choose what you want to log: errors, warnings, system information, user messages, or all of the above.
Figure 144: Log File dialog box
If you click the browse button, a standard Save As dialog box is displayed. Browse to a suitable folder and type in a filename; the default extension is log. Then click Save to select the specified file. Enable and disable logging to the file with the Enable Log file check box.
LOGGING > SET TERMINAL IO LOG FILE Allows you to log terminal I/O input and output from C-SPY to a file. This command displays a dialog box where you select the location of the log file.
Figure 145: Terminal I/O Log File dialog box
dsPIC IAR Embedded Workbench™ IDE
214 User Guide
UDSPIC-1
C-SPY Debugger reference
If you click the browse button, a standard Save As dialog box is displayed. Browse to a suitable folder and type in a filename; the default extension is log. Then click Save to select the specified file.
LOAD LAYOUT Loads the specified arrangement of debugger windows from a layout file (*.lew) in the dspic\layouts directory.
SAVE LAYOUT AS Saves the current arrangement of debugger windows in a layout file (*.lew) in the dspic\layouts directory.
LOAD DEFAULT LAYOUT Loads the default arrangement of debugger windows.
SAVE CURRENT LAYOUT AS DEFAULT Saves the current arrangement of debugger windows as the default layout.
Simulator menu Using the simulator driver creates a new menu in the menu bar, the Simulator menu.
Figure 146: Simulator menu
INTERRUPTS The dsPIC interrupt simulation has the same behavior as the hardware. This means that the execution of an interrupt is dependant on the status of the global enable interrupt bit. The execution of maskable interrupts are also dependant on the status of the local enable bit. If latency is used the corresponding pending bit will be set until the interrupt is acknowledged or removed. To be able to perform these actions for various derivatives the interrupt system must have detailed information about available interrupts. This information is provided in the device description files. Thus the interrupt simulation is not available without the usage of any such file.
Part 3. The IAR Embedded Workbench IDE 215
UDSPIC-1
Simulator menu
The C-SPY interrupt system uses the cycle counter as a clock to determine when an interrupt should be raised in the simulator. Changing the cycle counter manually will affect any interrupt you have set up in the Interrupt dialog box. C-SPY only polls for interrupts between instructions, regardless of how many cycles an instruction takes. Defined interrupts will be preserved until they are removed by the user. The interrupt simulation can be used in conjunction with macros and complex breakpoints to simulate interrupt-driven on-chip peripherals, see Using interrupts, breakpoints, and macros, page 49. The Interrupts command displays the following dialog box to allow you to configure C-SPY’s interrupt simulation:
Figure 147: Interrupts dialog box
The option Enable simulation enables or disables interrupt simulation. If the interrupt simulation is disabled the definitions remain but no interrupts will be generated. To define a new interrupt enter the characteristics of the interrupt you want to simulate and click Install. The interrupt is then added to the list of installed interrupts. You can also enable and disable installed interrupts individually by using the check box to the left of the interrupt name in the list of installed interrupts.
dsPIC IAR Embedded Workbench™ IDE
216 User Guide
UDSPIC-1
C-SPY Debugger reference
The interrupt specification text in the list of installed interrupts is prefixed with either [S] for a single-shot interrupt or [R] for a repeated interrupt. If the interrupt is activated but pending an additional [P] will be inserted. To edit an existing interrupt select it in the list of installed interrupts, edit its characteristics and click Modify. You can also click Remove to delete it, or Remove All to delete all defined interrupts. Notice that deleting an interrupt does not remove any pending interrupt from the system. For each interrupt you can define the following characteristics:
Interrupt Select the interrupt from the drop-down list. Your selection will automatically update the Description box. The drop-down list of available interrupts is populated with entries from the device description file that you have selected using the C-SPY option Device description in the IAR Embedded Workbench IDE. See page 123 for additional information.
Description Contains the description of the chosen interrupt, if available. The description is retrieved from the selected device description file. When defining an interrupt via the system macro __orderInterrupt it is possible to use only the name; the description will then be retrieved from the device description file when activated. In those cases the description field will be empty.
Activation Time The time, in cycles, after which the specified type of interrupt can be generated.
Repeat Interval The periodicity of the interrupt in cycles.
Latency Describes how long, in cycles, the interrupt remains pending until removed if it has not been processed.
Probability The probability, in percent, that the interrupt will actually appear in a period.
Part 3. The IAR Embedded Workbench IDE 217
UDSPIC-1
Simulator menu
Variance A timing variation range, as a percentage of the repeat interval, in which the interrupt may occur for a period. For example, if the repeat interval is 100 and the variance 5%, the interrupt may occur anywhere between T=95 and T=105, to simulate a variation in the timing.
MEMORY MAP C-SPY allows the simulation of different memory types by the use of memory maps. A memory map is a specified memory area with an access type attatched to it, either Read Only or Read & Write. If the simulator tries to access memory outside of the mapped areas or to write to a read-only memory, this will cause the simulation to stop. Use the Memory Map dialog box to define memory maps:
Figure 148: Memory Map dialog box
To define a new range, you can either:
Load settings from the device description file in use (if any) Enter the characteristics of the memory you want to monitor and click Set. Loading the settings from the device description file will automatically first clear the existing ranges in the map. It will use the entries in the [Memory] section to create a memory map. The mapping system will strive to limit the number of ranges for efficiency reasons. This means that it will concatenate ranges whenever possible. If you define two ranges 0–1FFF and 2000–2FFF of the same access type and in the same address space, the system will treat them as one range 0–2FFF. It is not possible to map two different access types to the same memory location.
dsPIC IAR Embedded Workbench™ IDE
218 User Guide
UDSPIC-1
C-SPY Debugger reference
To edit an existing memory range, select it in the list and click Modify to display or edit its properties, or Remove to delete it. Note that the settings you specify in the Memory Map dialog box are saved between debug sessions. For each entry you can define the following properties:
Address space Select the appropriate address space from the drop-down list. Normally there is one address space available for microprocessors with a von Neumann architecture, and two address spaces available for microprocessors with a Harvard architecture.
Start address The start address, in hexadecimal notation, for the address range.
End address The end address, in hexadecimal notation, for the address range.
Access type Select the access type from the drop-down list. Available types are Read Only and Read & Write.
Enable memory mapping Enables or disables memory mapping. When memory mapping is disabled, the definition remains but no memory map checks will be performed. If a memory access occurs that violates the access type of that memory map, C-SPY will regard this as an illegal access. Execution will be halted and an error message will be displayed:
Figure 149: Illegal memory access
Part 3. The IAR Embedded Workbench IDE 219
UDSPIC-1
Editing Breakpoints
Editing Breakpoints The following breakpoint categories are available for the dsPIC debugger: Category
Break when
Code
Opcode is fetched from the specified location.
Data
Data is accessed at the specified location. This is reported after the instruction is completed.
Immediate
This will temporarily halt the instruction execution (before reading or after writing the specified location) to perform the specified action. Execution will then resume. Immediate breakpoints are sometimes called simulation breakpoints.
Table 49: Breakpoint categories
Breakpoints will be preserved between debug sessions. The Edit>Breakpoints command displays the following dialog box which shows the currently defined breakpoints, and allows you to edit them or define new breakpoints:
Figure 150: Breakpoints dialog box
To define a new breakpoint, enter the location of the breakpoint you want to define in the Break At text box.
dsPIC IAR Embedded Workbench™ IDE
220 User Guide
UDSPIC-1
C-SPY Debugger reference
To modify an existing breakpoint, select it in the list. Click Remove or Remove All to remove one or more breakpoints. Note: You can set breakpoints even if no debugging session is active. The breakpoints will then be validated when the debugging session starts. For each breakpoint you can define the following characteristics:
Break At In this box you enter the address in memory or any expression that evaluates to a valid address, for example a function or variable name. When setting a code breakpoint, you can specify a location in the C source program using the syntax {file path}.row.column. You can also use the browse button to the right of the text box, and browse your way to the file with the Enter Location dialog box.
Figure 151: Setting a breakpoint on a source location
For example, {C:\IAR Systems\dspic\common.c}.22.3 sets a breakpoint on the third character position on line 22 in the source file common.c.
Part 3. The IAR Embedded Workbench IDE 221
UDSPIC-1
Editing Breakpoints
When setting a data or an immediate breakpoint, click the browse button to the right of the Break At text box and click the appropriate Type radio button. Then enter the absolute address of the data breakpoint in the Address box or the name of a variable or any expression that evaluates to a valid memory location in the Expression box. For example, my_var refers to the location of the variable my_var, and arr[3] refers to the third element of the array arr:
Figure 152: Setting a breakpoint on an expression
The Source location option is not meaningful for immediate or data breakpoints. For absolute addresses, you must also specify the memory Zone in which the address belongs. Data breakpoints are primarily useful for variables that have a constant address in memory. If you set a breakpoint on an accessible local variable, the breakpoint will be set on the corresponding register or stack location. The validity of this location is not guaranteed except for in small parts of the code. Note: You cannot set a breakpoint on a variable that does not have a constant address in memory.
Condition A valid expression conforming to C-SPY expression syntax. Condition type
Description
Condition True
The breakpoint is triggered if the value of the expression is true.
Condition Changed
The breakpoint is triggered if the value of the condition expression has changed.
Table 50: Breakpoint conditions
Note: The condition is evaluated only when the breakpoint is encountered. Skip count The number of times remaining that the breakpoint condition must be fulfilled before a break takes place.
dsPIC IAR Embedded Workbench™ IDE
222 User Guide
UDSPIC-1
C-SPY Debugger reference
Memory access type Specifies the type of memory access guarded by a data or immediate (simulator) breakpoint: Type
Description
Read/Write
Read and write from location.
Read
Read from location.
Write
Write to location.
Table 51: Breakpoint types
The breakpoints never break execution within a single assembler instruction. They are recorded and reported after the instruction is completed.
Action An optional expression to be executed once the breakpoint is reached. This option is only applicable to immediate (simulator) breakpoints.
Part 3. The IAR Embedded Workbench IDE 223
UDSPIC-1
Editing Breakpoints
dsPIC IAR Embedded Workbench™ IDE
224 User Guide
UDSPIC-1
Glossary
Glossary A
B
Absolute location. A specific memory address for an object specified in the source code, as opposed to the object being assigned a location by the IAR XLINK Linker.
Backtrace. Information that allows the IAR C-SPY™ Debugger to show, without any runtime penalty, the complete stack of function calls wherever the program counter is, provided that the code comes from compiled C functions.
Absolute segments. Segments that have fixed locations in memory before linking. Address expression. An expression which has an address as its value. Application. The application program developed by the user of the IAR toolkit and which will be run as an embedded application on a target chip. Architecture. A term used by computer designers to designate the structure of complex information-processing systems. It includes the kinds of instructions and data used, the memory organisation and addressing, and the methods by which the system is implemented. The two main architecture types used in processor design are Harvard and von Neumann. Assembler directives. The set of commands that control how the assembler operates. Assembler options. Parameters you can specify to change the default behavior of the assembler. Assembler language. A machine-specific set of mnemonics used to specify operations to the target processor and input or output registers or data areas. Assembler language may sometimes be preferred over C/Embedded C++ to save memory or to enhance the execution speed of the application. Auto variables. The term refers to the fact that each time the function in which the variable is declared is called, a new instance of the variable is created automatically. This can be compared with the behavior of local variables in systems using static overlay, where a local variable only exists in one instance, even if the function is called recursively. Also called local variables. Compare Register variables.
Bank. See Memory bank. Bank switching. Switching between different sets of memory banks. This software technique is used to increase a computer's usable memory by allowing different pieces of memory to occupy the same address space. Banked code. Code that is distributed over several banks of memory. Each function must reside in only one bank. Banked data. Data that is distributed over several banks of memory. Each data object must fit inside one memory bank. Banked memory. Has multiple storage locations for the same address. See also Memory bank. Bank-switching routines. Code that selects a memory bank. Batch files. A text file containing operating system commands which are executed by the command line interpreter. In Unix, this is called a “shell script” since it is the Unix shell which includes the command line interpreter. Batch files can be used as a simple way to combine existing commands into new commands. Bitfield. A group of bits considered as a unit. Breakpoint. 1. Code breakpoint. A point in a program that, when reached, triggers some special behavior useful to the process of debugging. Generally, breakpoints are used for stopping program execution or dumping the values of some or all of the program variables. Breakpoints may be part of the program itself, or they may be set by the programmer as part of an interactive session with a debugging tool for scrutinizing the program's execution.
225
UDSPIC-1
2. Data breakpoint. A point in memory that, when accessed, triggers some special behavior useful to the process of debugging. Generally, data breakpoints are used to stop program execution when an address location is accessed either by a read operation or a write operation. 3. Immediate breakpoint. A point in memory that, when accessed, trigger some special behavior useful in the process of debugging. Immediate breakpoints are generally used for halting the program execution in the middle of a memory access instruction (before or after the actual memory access depending on the access type) while performing some user-specified action. The execution is then resumed. This feature is only available in the simulator version of C-SPY.
C Calling convention. A calling convention describes the way one function in a program calls another function. This includes how register parameters are handled, how the return value is returned, and which registers that will be preserved by the called function. The compiler handles this automatically for all C and C++ functions. All code written in assembler language must conform to the rules in the calling convention in order to be callable from C or C++, or to be able to call C and C++ functions. The C calling convention and the C++ calling conventions are not necessarily the same. Cheap. As in cheap memory access. A cheap memory access either requires few cycles to perform, or few bytes of code to implement. A cheap memory access is said to have a low cost. See Memory access cost. Checksum. A computed value which depends on the contents of a block of data and which is stored along with the data in order to detect corruption of the data. Compare CRC. Code banking. See Banked code. Code model. The code model controls how code is generated for an application. All object files of a system must be compiled using the same code model.
Code pointers. A code pointer is a function pointer. As many microcontrollers allow several different methods of calling a function, compilers for embedded systems usually provide the users with the ability to use all these methods. Do not confuse code pointers with data pointers. Compilation unit. See Translation unit. Compiler function directives. The compiler function directives are generated by the compiler to pass information about functions and function calls to the IAR XLINK Linker. To view these directives, you must create an assembler list file. These directives are primarily intended for compilers that support static overlay, a feature which is useful in smaller microcontrollers. Compiler options. Parameters you can specify to change the default behavior of the compiler. Cost. See Memory access cost. CRC (cyclic redundancy checking). A number derived from, and stored with, a block of data in order to detect corruption. A CRC is based on polynomials and is a more advanced way of detecting errors than a simple arithmetic checksum. Compare Checksum. C-SPY options. Parameters you can specify to change the default behavior of the IAR C-SPY Debugger. Cstartup. Code that sets up the system before the application starts executing. C-style preprocessor. A preprocessor is either a stand-alone application or an integrated part of a compiler, that performs preprocessing of the input stream before actual compilation takes place. A C-style preprocessor follows the rules set up in the ANSI specification of the C language and implements commands like #define, #if, and #include, which are used to handle textual macro substitution, conditional compilation, and inclusion of other files.
D Data banking. See Banked data.
dsPIC IAR Embedded Workbench™ IDE
226 User Guide
UDSPIC-1
Glossary
Data model. See Memory model. Data pointers. Many microcontrollers have different addressing modes in order to access different memory types or address spaces. Compilers for embedded systems usually have a set of different data pointer types so they can access the available memory efficiently. Data representation. How different data types are laid out in memory and what value ranges they represent. Declaration. A specification to the compiler that an object, a variable or function, exists. The object itself must be defined in exactly one translation unit (source file). An object must either be declared or defined before it is used. Normally an object that is used in many files is defined in one source file. A declaration is normally placed in a header file that is included by the files that use the object. For example: /* Variable "a" exists somewhere. Function "b" takes two int parameters and returns an int. */ extern int a; int b(int, int);
Definition. The variable or function itself. Only one definition may exist for each variable or function in an application. See also Tentative definition. For example: int a; int b(int x, int y) { return x + y; }
Derivative. One of two or more processor variants in a series or family of microprocessors or microcontrollers. Device description file. A file used by the IAR C-SPY Debugger that contains various device-specific information such as I/O registers (SFR) definitions, interrupt vectors, and control register definitions.
Device driver. Software that provides a high-level programming interface to a particular peripheral device. Digital signal processor (DSP). A device that is similar to a microprocessor, except that the internal CPU has been optimized for use in applications involving discrete-time signal processing. In addition to standard microprocessor instructions, DSPs usually support a set of complex instructions to perform common signal-processing computations quickly. Disassembly window. A C-SPY window that shows the memory contents disassembled as machine instructions, interspersed with the corresponding C source code (if available). Dynamic initialization. Variables in a program written in C are initialized during the initial phase of execution, before the main function is called. These variables are always initialized with a static value, which is determined either at compile-time or at link-time. This is called static initialization. In Embedded C++, variables may require initialization to be performed by executing code, e.g. running the constructor of global objects, or performing dynamic memory allocation. Dynamic memory allocation. There are two main strategies for storing variables: statically at link-time, or dynamically at runtime. Dynamic memory allocation is often performed from the heap and it is the size of the heap that determines how much memory that can be used for dynamic objects and variables. The advantage of dynamic memory allocation is that several variables or objects that are not active at the same time may be stored in the same memory, thus reducing the memory need of an application. See also Heap memory. Dynamic object. An object that is allocated, created, destroyed, and released at runtime. Dynamic objects are almost always stored in memory that is dynamically allocated. Compare Static objects.
227
UDSPIC-1
E EEPROM. Electronically Erasable, Programmable Read-Only Memory. A type of ROM that can be erased electronically, and then be re-programmed. EPROM. Erasable, Programmable Read-Only Memory. A type of ROM that can be erased by exposing it to ultraviolet light, and then be re-programmed.
Exceptions. An exception is an interrupt initiated by the processor hardware, or hardware that is tightly coupled with the processor, e.g. a memory management unit (MMU). The exception signals a violation of the rules of the architecture (access to protected memory), or an extreme error condition (division by zero). Do not confuse this use of the word exception with the term exception used in the C++ language (but not in Embedded C++!).
Embedded C++. A subset of the C++ programming language, which is intended for embedded systems programming. The fact that performance and portability are particularly important in embedded systems development was considered when defining the language.
Expensive. As in expensive memory access. An expensive memory access either requires many cycles to perform, or many bytes of code to implement. An expensive memory access is said to have a high cost. See Memory access cost.
Embedded system. A combination of hardware and software, designed for a specific purpose. Embedded systems are often part of a larger system or product.
Extended keywords. Non-standard keywords in C and C++. These usually control the definition and declaration of objects (i.e. data and functions). See also Keywords.
Emulator. An emulator is a hardware device that performs emulation of one or more derivatives of a microcontroller family. An emulator can often be used instead of the actual microcontroller chip and connects directly to the printed circuit board—where the chip would have been connected—via a connecting device. An emulator always behaves exactly as the microcontroller it emulates, and is used when debugging requires all systems actuators, or when debugging device drivers.
F
Enumeration. A type which includes in its definition an exhaustive list of possible values for variables of that type. Common examples include Boolean, which takes values from the list [true, false], and day-of-week which takes values [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]. Enumerated types are a feature of typed languages, including C and Ada. Characters, (fixed-size) integers, and even floating-point types could be (but are not usually) considered to be (large) enumerated types.
dsPIC IAR Embedded Workbench™ IDE
228 User Guide
UDSPIC-1
Format specifiers. Used to specify the format of strings sent by library functions such as printf. In the following example, the function call contains one format string with one format specifier, %c, that prints the value of a as a single ASCII character: printf("a = %c", a);
G General options. Parameters you can specify to change the default behavior of all tools that are included in the IAR Embedded Workbench IDE. Generic pointers. Pointers that have the ability to point to all different memory types in for instance a microcontroller based on the Harvard architecture
Glossary
H Harvard architecture. A microcontroller based on the Harvard architecture has separate data and instruction buses. This allows execution to occur in parallel. As an instruction is being fetched, the current instruction is executing on the data bus. Once the current instruction is complete, the next instruction is ready to go. This theoretically allows for much faster execution than a von Neumann architecture, but there is some added silicon complexity. Compare von Neumann architecture. Heap memory. The heap is a pool of memory in a system that is reserved for dynamic memory allocation. An application may request parts of the heap for its own use; once memory has been allocated from the heap it remains valid until it is explicitly released back to the heap by the application. This type of memory is useful when the number of objects is not known until the application executes. Note that this type of memory is risky to use in systems with a limited amount of memory or systems that are expected to run for a very long time. Heap size. Total size of memory that can be dynamically allocated. Host. The computer that communicates with the target chip. The term is used to distinguish the computer on which the debugger is running from the microcontroller the embedded application you develop runs on.
I IDE (integrated development environment). A programming environment with all necessary tools integrated into one single application. Include file. A text file which is included into a source file. This is often performed by the preprocessor. Inline assembler. Assembler language code that is inserted directly between C statements.
Inlining. An optimization that replaces function calls with the body of the called function. This optimization increases the execution speed and may even reduce the size of the generated code. Instruction mnemonics. A word or acronym used in assembler language to represent a machine instruction. Different processors have different instruction sets and therefore use a different set of mnemonics to represent them, such as, ADD, BR (branch), BLT (branch if less than), MOVE, LDR (load register). Interrupt vector. A small piece of code that will be executed, or a pointer that points to code that will be executed when an interrupt occurs. Interrupt vector table. A table containing interrupt vectors, indexed by interrupt type. This table contains the processor's mapping between interrupts and interrupt service routines and must be initialized by the programmer. Interrupts. In embedded systems, the use of interrupts is a method of detecting external events immediately, for example a timer overflow or the pressing of a button. Interrupts are asynchronous events that suspend normal processing and temporarily divert the flow of control through an “interrupt handler” routine. Interrupts may be caused by both hardware (I/O, timer, machine check) and software (supervisor, system call or trap instruction). Compare Trap.
Intrinsic. An adjective describing native compiler objects, properties, events, and methods. Intrinsic functions. 1. Function calls that are directly expanded into specific sequences of machine code. 2. Functions called by the compiler for internal purposes (i.e. floating point arithmetic etc.).
K Key bindings. Key shortcuts for menu commands used in the IAR Embedded Workbench IDE.
229
UDSPIC-1
Keywords. A fixed set of symbols built into the syntax of a programming language. All keywords used in a language are reserved—they may not be used as identifiers (i.e. user-defined objects such as variables or procedures). See also Extended keywords.
M MAC (Multiply and accumulate). A special instruction, or on-chip device, that performs a multiplication together with an addition. This is very useful when performing signal processing where many filters and transforms have the form:
L L-value. A value that can be found on the left side of an assignment and thus be changed. This includes plain variables and de-referenced pointers. Expressions like (x + 10) can not be assigned a new value and are therefore not L-values. Language extensions. Target-specific extensions to the C language. Library. See Runtime library. Linker command file. A file used by the IAR XLINK Linker. It contains command line options which specify the locations where the memory segments can be placed, thereby assuring that your application fits on the target chip. Since many of the chip-specific details are specified in the linker command file and not in the source code, the linker command file also helps to make the code portable. In particular, the linker specifies the placement of segments, the stack size, and the heap size. Local variable. See Auto variables. Location counter. See Program location counter. Logical address. See Virtual address.
The accumulator of the MAC usually has a higher precision (more bits) than normal registers. See also Digital signal processor. Macro. 1. Assembler macros are user-defined sets of assembler lines that can be expanded later in the source file by referring to the given macro name. Parameters will be substituted if referred to. 2. C macro. A text substitution mechanism used during preprocessing of source files. Macros are defined using the #define preprocessing directive. The replacement text of each macro is then substitued for any occurrences of the macro name in the rest of the translation unit. 3. C-SPY macros are programs that you can write to enhance the functionality of the IAR C-SPY Debugger. A typical application of C-SPY macros is to associate them with breakpoints; when such a breakpoint is hit, the macro is run and can for example be used to simulate peripheral devices, to evaluate complex conditions, or to output a trace. The C-SPY macro language is like a simple dialect of C, but is less strict with types. Mailbox. A mailbox in an RTOS is a point of communication between two or more tasks. One task can send messages to another task by placing the message in the mailbox of the other task. Mailboxes are also known as message queues or message ports.
dsPIC IAR Embedded Workbench™ IDE
230 User Guide
UDSPIC-1
Glossary
Memory access cost. The cost of a memory access may be in clock cycles, or in the number of bytes of code needed to perform the access. A memory which requires large instructions or many instructions is said to have a higher access cost than a memory which can be accessed with few, or small instructions. Memory area. A region of the memory. Memory bank. The smallest unit of continuous memory in banked memory. One memory bank at a time is visible in a microcontroller’s physical address space. Memory map. A map of the different memory areas available to the microcontroller. Memory model. Specifies the memory hierarchy and how much memory the system can handle. Your program must use only one memory model at a time, and the same model must be used by all user modules and all library modules. Most default behaviors originating from the selected memory model can be altered by the use of extended keywords and #pragma directives. Microcontroller. A microprocessor on a single integrated circuit intended to operate as an embedded system. As well as a CPU, a microcontroller typically includes small amounts of RAM, PROM, timers, and I/O ports. Microprocessor. A CPU contained on one (or a small number of) integrated circuits. A single-chip microprocessor may include other components such as memory, memory management, caches, floating-point unit, I/O ports and timers. Such devices are also known as microcontrollers. Module. The basic unit of linking. A module contains definitions for symbols (exports) and references to external symbols (imports). When compiling C/C++, each translation unit produces one module. In assembler, each source file can produce more than one module.
N Nested interrupts. A system where an interrupt may be interrupted by another interrupt is said to have nested interrupts. Non-banked memory. Has a single storage location for each memory address in a microcontroller’s physical address space. Non-initialized memory. Memory that can contain any value at reset, or in the case of a soft reset, can remember the value it had before the reset. Non-volatile storage. Memory devices such as battery-backed RAM, ROM, magnetic tape and magnetic disks that can retain data when electric power is shut off. Compare Volatile storage. NOP. No operation. This is an instruction that does not perform anything, but is used to create a delay. In pipelined architectures, the NOP instruction can be used for synchronizing the pipeline. See also Pipeline.
O Operator. A symbol used as a function, with infix syntax if it has two arguments (e.g. +) or prefix syntax if it has only one (e.g. bitwise negation, ~). Many languages use operators for built-in functions such as arithmetic and logic. Operator precedence. Each operator has a precedence number assigned to it that determines the order in which the operator and its operands are evaluated. The highest precedence operators are evaluated first. Use parentheses to group operators and operands to control the order in which the expressions are evaluated.
P Parameter passing. See Calling convention. Peripheral. A hardware component other than the processor, for example memory or an I/O device.
231
UDSPIC-1
Pipeline. A structure that consists of a sequence of stages through which a computation flows. New operations can be initiated at the start of the pipeline even though other operations are already in progress through the pipeline.
PROM. Programmable Read-Only Memory. A type of ROM that can be programmed only once.
Pointer. An object that contains an address to another object of a specified type.
Project options. General options that apply to an entire project, for example the target processor that the application will run on.
#pragma directive. During compilation of a C/C++ program, #pragma directives cause the compiler to behave in an implementation-defined manner. This can include, for example, producing output on the console, changing the declaration of a subsequent object, changing the optimization level, or enabling/disabling language extensions. Preemptive multitasking. An RTOS task is allowed to run until a higher priority process is activated. The higher priority task may become active as the result of an interrupt. The term preemptive indicates that although a task is allotted to run a given length of time (a timeslice), it may lose the processor at any time. Each time an interrupt occurs, the task scheduler looks for the highest priority task that is active and switches to that task. If the located task is different from the task that was executing before the interrupt, the previous task is suspended at the point of interruption. Compare Round Robin. Preprocessing directives. A set of directives that are executed before the parsing of the actual code is started. Preprocessor. See C-style preprocessor. Processor variant. The different chip setups that the compiler supports. See Derivative. Program counter (PC). A special processor register that is used to address instructions. Compare Program location counter. Program location counter (PLC). Used in the IAR Assembler to denote the code address of the current instruction. The PLC is represented by a special symbol (typically $) that can be used in arithmetic expressions. Also called simply location counter (LC).
dsPIC IAR Embedded Workbench™ IDE
232 User Guide
UDSPIC-1
Project. The user application development project.
Q Qualifiers. See Type qualifiers.
R R-value. A value that can be found on the right side of an assignment. This is just a plain value. See also L-Value. Real-time operating system (RTOS). An operating system which guarantees the latency between an interrupt being triggered and the interrupt handler starting, as well as how tasks are scheduled. An RTOS is typically much smaller than a normal desktop operating system. Compare Real-time system. Real-time system. A computer system whose processes are time-sensitive. Compare Real-time operating system. Register constant. A register constant is a value that is loaded into a dedicated processor register when the system is initialized. The compiler can then generate code that assumes that the constants are present in the dedicated registers. Register. A small on-chip memory unit, usually just one or a few bytes in size, which is particularly efficient to access and therefore often reserved to function as a temporary storage area during program execution. Register locking. Register locking means that the compiler can be instructed that some processor registers shall not be used during normal code generation. This is useful in a number of situations. For example, some parts of a system
Glossary
could be written in assembler language to gain speed. These parts could be given dedicated processor registers. Or the register could be used by an operating system, or by other third-party software. Register variables. Typically, register variables are local variables that have been placed in registers instead of on the (stack) frame of the function. Register variables are much more efficient than other variables because they do not require memory accesses, so the compiler can use shorter/faster instructions when working with them. See also Auto variables. Relocatable segments. Segments that have no fixed location in memory before linking. Reset. A reset is a restart from the initial state of a system. A reset can originate from hardware (hard reset), or from software (soft reset). A hard reset can usually not be distinguished from the power-on condition, which a soft reset can be. ROM-monitor. A piece of embedded software that has been designed specifically for use as a debugging tool. It resides in the ROM of the evaluation board chip and communicates with a debugger via a serial port or network connection. The ROM-monitor provides a set of primitive commands to view and modify memory locations and registers, create and remove breakpoints, and execute your program. The debugger combines these primitives to fulfill higher-level requests like program download and single-step. Round Robin. Task scheduling in an operating system, where all tasks have the same priority level and are executed in turn, one after the other. Compare Preemptive multitasking.
Two modules can only be linked together if they have the same value for each key that they both define.
S Saturated mathematics. Most, if not all, C and C++ implementations use mod–2N 2-complement-based mathematics where an overflow wraps the value in the value domain, i.e. (127 + 1) = -128. Saturated mathematics, on the other hand, does not allow wrapping in the value domain, e.g. (127 + 1) = 127, if 127 is the upper limit. Saturated mathematics is often used in signal processing, where an overflow condition would have been fatal if value wrapping had been allowed. Scheduler. The part of an RTOS that performs task-switching. It is also responsible for selecting which task that should be allowed to run. There are many different scheduling algorithms, but most of them are either based on static scheduling (performed at compile-time), or on dynamic scheduling (where the actual choice of which task to run next is taken at runtime, depending on the state of the system at the time of the task-switch). Most real-time systems use static scheduling, because it makes it possible to prove that the system will not violate the real-time requirements. Scope. The section of an application where a function or a variable can be referenced by name. The scope of an item may be limited to file, function, or block. Segment. A chunk of data or code that should be mapped to a physical location in memory. The segment could either be placed in RAM (read-and-writeable memory) or in ROM (read-only memory). Segment map. A set of segments and their locations.
RTOS. See Real-time operating system. Runtime library. A collection of useful routines, stored as an object file, that can be linked into any program. Runtime model attributes. A mechanism that is designed to prevent modules that are not compatible to be linked into an application. A runtime attribute is a pair constituted of a named key and its corresponding value.
Semaphore. A semaphore is a type of flag that is used for guaranteeing exclusive access to resources. The resource can be a hardware port, a configuration memory, or a set of variables. If several different tasks have to access the same resource, the parts of the code (the critical sections) that access the resource have to be made exclusive for every task. This is done by obtaining the semaphore that protects that
233
UDSPIC-1
resource, thus blocking all other tasks from it. If another task wishes to use the resource, it also has to obtain the semaphore. If the semaphore is already in use, the second task has to wait until the semaphore is released. After the semaphore is released, the second task is allowed to execute and can obtain the semaphore for its own exclusive access. Severity level. The level of seriousness of the diagnostic response from the assembler, compiler, or debugger, when it notices that something is wrong. Typical severity levels are remarks, warnings, errors, and fatal errors. A remark just points to a possible problem, while a fatal error means that the programming tool exits without finishing. Short addressing. Many microcontrollers have special addressing modes for efficient access to internal RAM and memory mapped I/O. Short addressing is therefore provided as an extended feature by many compilers for embedded systems. See also Data pointers. Side-effect. An expression in C or C++ is said to have a side-effect if it changes the state of the system. Examples are assignments to a variable, or using a variable with the post-increment operator. The C and C++ standards state that a variable that is subject to a side-effect should not be used more that once in an expression. As an example, this statement violates that rule: *d++ = *d;
Signal. Signals provide event-based communication between tasks. A task can wait for one or more signals from other tasks. Once a task receives a signal it waits for, execution continues. A task in an RTOS that waits for a signal does not use any processing time, which allows other tasks to execute. Simulator. A debugging tool that runs on the host and behaves as similar to the target processor as possible. A simulator is used to debug the application when the hardware is unavailable, or not needed for proper debugging. A simulator is usually not connected to any physical peripheral devices. A simulated processor is often slower, or even much slower, than the real hardware.
dsPIC IAR Embedded Workbench™ IDE
234 User Guide
UDSPIC-1
Single stepping. Executing one instruction or one C statement at a time in the debugger. Skeleton code. An incomplete code framework that allows the user to specialize the code. Special function register (SFR). A register that is used to read and write to the hardware components of the microcontroller. Stack frames. Data structures containing data objects as preserved registers, local variables, and other data objects that need to be stored temporary for a particular scope (usually a function). Earlier compilers usually had a fixed size and layout on a stack frame throughout a complete function, while modern compilers may have a very dynamic layout and size that can change anywhere and anytime in a function. Stack segments. The segment or segments that reserve space for the stack(s). Most processors use the same stack for calls and parameters, but some have separate stacks. Statically allocated memory. This kind of memory is allocated once and for all at link-time, and remains valid all through the execution of the application. Variables that are either global or declared static are allocated this way. Static objects. An object whose memory is allocated at link-time and is created during system startup (or at first use). Compare Dynamic objects. Static overlay. Instead of using a dynamic allocation scheme for parameters and auto variables, the linker allocates space for parameters and auto variables at link time. This generates a worst-case scenario of stack usage, but may be preferable for small chips with expensive stack access or no stack access at all. Structure value. A collecting names for structs and unions. A struct is a collection of data object placed sequentially in memory (possibly with pad bytes between them). A union is a collection of data sharing the same memory location.
Glossary
Symbol. A name that represents a register, an absolute value, or a memory address (relative or absolute). Symbolic location. A location that uses a symbolic name because the exact address is unknown.
T Target. 1. An architecture. 2. A piece of hardware. The particular embedded system you are developing the application for. The term is usually used to distinguish the system from the host system. Target monitor. 1. A small application that is added to an embedded system to allow maintenance when the system is operational. The monitor has access to the main application’s variables and statistics. 2. A small application that allows a debugger to interface with the hardware, thus allowing simple debugging to be performed in a “live” system. See also ROM-monitor. Task (thread). A task is an execution thread in a system. Systems that contain many tasks that execute in parallel are called multitasking systems. Since a processor only executes one instruction stream at the time, most systems implement some sort of task-switch mechanism (often called context switch) so that all tasks get their share of processing time. The process of determining which task that should be allowed to run next is called scheduling. Two common scheduling methods are preemptive multitasking and Round Robin. Tentative definition. A variable that can be defined in multiple files, provided that the definition is identical and that it is an absolute variable. Terminal I/O. A simulated terminal window in the IAR C-SPY Debugger.
Timeslice. The (longest) time an RTOS allows a task to run without running the task-scheduling algorithm. It is possible that a task will be allowed to execute during several consecutive timeslices before being switched out. It is also possible that a task will not be allowed to use its entire time slice, e.g. if, in a preemptive system, a higher priority task is activated by an interrupt. Timer. A peripheral that counts independent of the program execution. Translation unit. A source file together with all the header files and source files included via the preprocessor directive #include, with the exception of the lines skipped by conditional preprocessor directives such as #if and #ifdef. Trap. A trap is an interrupt intiated by inserting a special instruction into the instruction stream. Many systems use traps to call operating system functions. Another name for trap is software interrupt. Type qualifiers. In standard C/C++, const or volatile. IAR compilers usually add target-specific type qualifiers for memory and other type attributes.
U UBROF (Universal Binary Relocatable Object Format). File format produced by the IAR programming tools.
V Virtual address (logical address). An address that needs to be translated by the compiler, linker or the runtime system into a physical memory address before it is used. The virtual address is the address seen by the application, which can be different from the address seen by other parts of the system. Virtual space. An IAR Embedded Workbench Editor feature which allows you to place the insertion point outside of the area where there are actual characters.
235
UDSPIC-1
Volatile storage. Data stored in a volatile storage device is not retained when the power to the device is turned off. In order to preserve data during a power-down cycle, you should store it in non-volatile storage. This should not be confused with the C keyword volatile. Compare Non-volatile storage. von Neumann architecture. A computer architecture where both instructions and data are transferred over a common data channel. Compare Harvard architecture.
W Watchpoints. Watchpoints keep track of the values of C variables or expressions in the C-SPY Watch window as the program is being executed.
X XLIB options. The set of commands that control how the IAR XLIB Librarian operates. XLINK options. Parameters you can specify to change the default behavior of the IAR XLINK Linker.
Z Zero-overhead loop. A loop in which the loop condition, including branching back to the beginning of the loop, does not take any time at all. This is usually implemented as a special hardware feature of the processor and is not available in all architectures. Zone. Different processors have widely differing memory architectures. Zone is the term C-SPY uses for a named memory area. For example, on processors with separately addressable code and data memory there would be at least two zones. A processor with an intricate banked memory scheme may have several zones.
dsPIC IAR Embedded Workbench™ IDE
236 User Guide
UDSPIC-1
Index
A About (Help menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 absolute location, definition of. . . . . . . . . . . . . . . . . . . . . 225 absolute segments, definition of. . . . . . . . . . . . . . . . . . . . 225 accumulated time (profiling) . . . . . . . . . . . . . . . . . . . . . . 207 actions (in Breakpoints dialog box) . . . . . . . . . . . . . . . . . 223 Activate (in Code Coverage window) . . . . . . . . . . . . . . . 206 Activate (in Profiling window). . . . . . . . . . . . . . . . . . . . . 208 activation time, in interrupts. . . . . . . . . . . . . . . . . . . . . . . 217 address expression, definition of . . . . . . . . . . . . . . . . . . . 225 address field, in assembler list file . . . . . . . . . . . . . . . . . . . 66 address range check, specifying in XLINK . . . . . . . . . . . 114 Allow directives in first column (assembler option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Allow mnemonics in first column (assembler option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Always generate output (XLINK option) . . . . . . . . . . . . 113 application built outside the IDE . . . . . . . . . . . . . . . . . . . 24, 137, 167 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 hardware-dependent aspects . . . . . . . . . . . . . . . . . . . . . 21 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 architecture, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 225 argument variables . . . . . . . . . . . . . . . . . . . . . . . . . . 160–161 in #include file paths . . . . . . . . . . . . . . . . . . . 98, 106, 116 asm (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 assembler diagnostics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . 164 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 assembler directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 assembler language, definition of . . . . . . . . . . . . . . . . . . 225 assembler list files address field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 conditional information, specifying . . . . . . . . . . . . . . 105
Index
data field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 in compiler, generating . . . . . . . . . . . . . . . . . . . . . . . . . 97 symbol and cross-reference table . . . . . . . . . . . . . . . . . 66 Assembler mnemonics (compiler option) . . . . . . . . . . . . . 97 assembler options . . . . . . . . . . . . . . . . . . . . . . . . . . . 101, 148 Allow directives in first column . . . . . . . . . . . . . . . . . 102 Allow mnemonics in first column . . . . . . . . . . . . . . . . 102 Defined symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Enable remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Factory settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Generate debug information . . . . . . . . . . . . . . . . . . . . 104 Include paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 inherited settings, overriding. . . . . . . . . . . . . . . . . . . . 101 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Macro quote characters . . . . . . . . . . . . . . . . . . . . . . . . 102 Make library module . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Object module name . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Output list fileC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Preprocessor output to file . . . . . . . . . . . . . . . . . . . . . 106 setting in Embedded Workbench. . . . . . . . . . . . . . . . . 101 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Suppress these diagnostics . . . . . . . . . . . . . . . . . . . . . 107 Treat these as errors. . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Treat these as remarks . . . . . . . . . . . . . . . . . . . . . . . . . 108 Treat these as warnings . . . . . . . . . . . . . . . . . . . . . . . . 108 Treat warnings as errors . . . . . . . . . . . . . . . . . . . . . . . 107 User symbols are case sensitive . . . . . . . . . . . . . . . . . 102 assembler output, including debug information. . . . . . . . 103 assembler preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Assembler Reference Guide (Help menu) . . . . . . . . . . . . 164 assembler symbols defining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
237
UDSPIC-1
using in C-SPY expressions . . . . . . . . . . . . . . . . . . . . 171 assembling a file, example . . . . . . . . . . . . . . . . . . . . . . . . . 64 assumptions, programming experience . . . . . . . . . . . . . xxiii Auto indent (editor option) . . . . . . . . . . . . . . . . . . . . . . . 155 Auto refresh (in Profiling window) . . . . . . . . . . . . . . . . . 209 auto variables, definition of . . . . . . . . . . . . . . . . . . . . . . . 225 Auto-refresh (in Code Coverage window) . . . . . . . . . . . . 206 a59 (file extension). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
B backtrace information definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 generated by compiler . . . . . . . . . . . . . . . . . . . . . . . 5, 170 bank switching, definition of . . . . . . . . . . . . . . . . . . . . . . 225 banked code, definition of . . . . . . . . . . . . . . . . . . . . . . . . 225 banked data, definition of. . . . . . . . . . . . . . . . . . . . . . . . . 225 banked memory, definition of . . . . . . . . . . . . . . . . . . . . . 225 bank-switching routines, definition of . . . . . . . . . . . . . . . 225 bar charts (in Profiling window) . . . . . . . . . . . . . . . . . . . 208 batch files definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 specifying in Embedded Workbench. . . . . . . . . . . . . . 162 bin, common (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . 14 bin, dspic (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . 15 bitfield, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 blocks, in C-SPY macros . . . . . . . . . . . . . . . . . . . . . . . . . 175 bookmarks, showing in editor . . . . . . . . . . . . . . . . . . . . . 155 brackets, matching (in editor) . . . . . . . . . . . . . . . . . . . . . 130 Break (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Break (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 actions to execute when breaking . . . . . . . . . . . . . . . . 223 adding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 categories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 conditional. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 defining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
dsPIC IAR Embedded Workbench™ IDE
238 User Guide
UDSPIC-1
example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 highlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 immediate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 memory access type guarded by . . . . . . . . . . . . . . . . . 223 memory zone name . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 modifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 removing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Breakpoints (dialog box) . . . . . . . . . . . . . . . . . . . . . . . . . 220 Breakpoints (Edit menu) . . . . . . . . . . . . . . . . . . . . . 143, 220 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Build All (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . 149 build messages, displaying in Embedded Workbench . . . 157 Build options, specifying . . . . . . . . . . . . . . . . . . . . . . . . . 157 build tree, viewing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Build (in Messages window) . . . . . . . . . . . . . . . . . . . . . . 134 building a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
C C compiler. See compiler C function information, in C-SPY . . . . . . . . . . . . . . . . . . 170 C symbols, using in C-SPY expressions . . . . . . . . . . . . . 171 C variables, using in C-SPY expressions . . . . . . . . . . . . . 171 c (file extension). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Call Stack window . . . . . . . . . . . . . . . . . . . . . . . . . . 170, 203 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57, 79 calling convention, definition of . . . . . . . . . . . . . . . . . . . 226 Calls, in Profiling window . . . . . . . . . . . . . . . . . . . . . . . . 207 _ _cancelAllInterrupts (C-SPY system macro) . . . . . . . . 178 _ _cancelInterrupt (C-SPY system macro) . . . . . . . . . . . 179 Cascade (Window menu) . . . . . . . . . . . . . . . . . . . . . . . . . 163 Category, in Options dialog box. . . . . . . . . . . . . . . . . . . . 148 cfg (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 157 characters, in assembler macro quotes . . . . . . . . . . . . . . . 102 cheap memory access, definition of . . . . . . . . . . . . . . . . . 226 checksum
Index
definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 generating in XLINK . . . . . . . . . . . . . . . . . . . . . . . . . 119 Clear (in Code Coverage window). . . . . . . . . . . . . . . . . . 206 _ _clearBreak (C-SPY system macro) . . . . . . . . . . . . . . . 179 CLIB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 CLIB/DLIB documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Close All (Window menu) . . . . . . . . . . . . . . . . . . . . . . . . 163 Close Project (File menu) . . . . . . . . . . . . . . . . . . . . . . . . 137 Close (File menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Close (Window menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 _ _closeFile (C-SPY system macro) . . . . . . . . . . . . . . . . 179 code banked, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . 225 skeleton, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 234 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Code Coverage window . . . . . . . . . . . . . . . . . . . . . . . . . . 205 pop-up menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 code generation assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 compiler features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 code memory, filling unused . . . . . . . . . . . . . . . . . . . . . . 119 code model, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 226 Code motion (compiler option) . . . . . . . . . . . . . . . . . . . . . 95 code pointers, definition of . . . . . . . . . . . . . . . . . . . . . . . 226 Code (compiler options). . . . . . . . . . . . . . . . . . . . . . . . . . . 93 colors and fonts, setting in editor . . . . . . . . . . . . . . . . . . . 156 command line commands, specifying in Embedded Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Common Fonts (IDE Options dialog) . . . . . . . . . . . . . . . 153 Common Sources (group) . . . . . . . . . . . . . . . . . . . . . . 22, 31 common (directory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Common-subexpr elimination (compiler option). . . . . . . . 94 Compile (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 149 compiler command line version . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9, 18 on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . 164 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 compiler diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 suppressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 compiler function directives, definition of . . . . . . . . . . . . 226 compiler list files assembler mnemonics, including . . . . . . . . . . . . . . . . . 97 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 source code, including. . . . . . . . . . . . . . . . . . . . . . . . . . 97 compiler options Assembler mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . 97 Code motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Common-subexpr elimination. . . . . . . . . . . . . . . . . . . . 94 Defined symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Diagnostics (in list file) . . . . . . . . . . . . . . . . . . . . . . . . . 97 Enable Embedded C++ syntax . . . . . . . . . . . . . . . . . . . 92 Enable language extensions . . . . . . . . . . . . . . . . . . . . . 92 Enable remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 factory settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Function inlining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Generate debug information . . . . . . . . . . . . . . . . . . . . . 97 Include paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Include source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 inherited, overriding . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Loop unrolling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Make library module . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Object module name . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Output assembler file . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Output list file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Preprocessor output to file . . . . . . . . . . . . . . . . . . . . . . 99 setting in Embedded Workbench. . . . . . . . . . . . . . . . . . 91 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Strict ISO/ANSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Suppress these diagnostics . . . . . . . . . . . . . . . . . . . . . 100 Treat all warnings as errors . . . . . . . . . . . . . . . . . . . . . 100
239
UDSPIC-1
Treat ‘char’ as ‘signed char’, specifying in compiler . . 93 Treat these as errors. . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Treat these as remarks . . . . . . . . . . . . . . . . . . . . . . . . . 100 Treat these as warnings . . . . . . . . . . . . . . . . . . . . . . . . 100 compiler output debug information, including . . . . . . . . . . . . . . . . . . . . 97 module name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 compiler preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 compiler symbols, defining . . . . . . . . . . . . . . . . . . . . . . . . 98 compiler tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 compiling a file or project . . . . . . . . . . . . . . . . . . . . . . . . 149 Complete (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 conditional breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . 222 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 conditional statements, in C-SPY macros . . . . . . . . . . . . 175 Condition, in Breakpoints dialog box . . . . . . . . . . . . . . . 222 config (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Configure Tools (Tools menu) . . . . . . . . . . . . . . . . . . . . . 160 contents, product package . . . . . . . . . . . . . . . . . . . . . . . . . 13 conventions, typographic . . . . . . . . . . . . . . . . . . . . . . . . . xxv converting old projects . . . . . . . . . . . . . . . . . . . . . . . . 17, 136 Copy (Edit menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 cost. See memory access cost Count, in Breakpoints dialog box . . . . . . . . . . . . . . . . . . 222 cpp (file extension). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 CPU variant, definition of . . . . . . . . . . . . . . . . . . . . . . . . 227 CRC definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 in assembler list file . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 cross-references in assembler list file . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 in map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Cstartup, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 current position in C-SPY Disassembly window . . . . . . . . . . . . . . . . . 197 in C-SPY source window example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 cursor, in C-SPY Disassembly window . . . . . . . . . . . . . . 197
dsPIC IAR Embedded Workbench™ IDE
240 User Guide
UDSPIC-1
$CUR_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 $CUR_LINE$ (argument variable) . . . . . . . . . . . . . . . . . 161 Custom Keyword File (editor option) . . . . . . . . . . . . . . . 155 Cut (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5, 167 exiting from example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5–6 reference information . . . . . . . . . . . . . . . . . . . . . . . . . 193 starting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 C-SPY expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 in C-SPY macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 watching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 C-SPY macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170, 173 blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 conditional statements. . . . . . . . . . . . . . . . . . . . . . . . . 175 C-SPY expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 defining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 execUserExit(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 execUserPreload() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 execUserReset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 execUserSetup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 executing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 loop statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 macro statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 printing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 registering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 _ _cancelAllInterrupts (system macro) . . . . . . . . . . . . 178 _ _cancelInterrupt (system macro) . . . . . . . . . . . . . . . 179 _ _clearBreak (system macro). . . . . . . . . . . . . . . . . . . 179 _ _closeFile (system macro) . . . . . . . . . . . . . . . . . . . . 180
Index
_ _disableInterrupts (system macro) . . . . . . . . . . . . . . 180 _ _driverType (system macro). . . . . . . . . . . . . . . . . . . 180 _ _enableInterrupts (system macro) . . . . . . . . . . . . . . 181 _ _openFile (system macro) . . . . . . . . . . . . . . . . . . . . 181 _ _orderInterrupt (system macro) . . . . . . . . . . . . . . . . 182 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 _ _readFileByte (system macro) . . . . . . . . . . . . . . . . . 183 _ _readMemoryByte (system macro) . . . . . . . . . . . . . 184 _ _registerMacroFile (system macro) . . . . . . . . . . . . . 184 _ _resetFile (system macro) . . . . . . . . . . . . . . . . . . . . 185 _ _setCodeBreak (system macro) . . . . . . . . . . . . . . . . 186 _ _setDataBreak (system macro) . . . . . . . . . . . . . . . . 186 _ _setSimBreak (system macro) . . . . . . . . . . . . . . . . . 187 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 _ _strFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 _ _subString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 _ _toLower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 _ _toUpper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 _ _writeFile (system macro) . . . . . . . . . . . . . . . . . . . . 190 _ _writeFileByte (system macro) . . . . . . . . . . . . . . . . 191 _ _writeMemoryByte (system macro) . . . . . . . . . . . . 191 C-SPY options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121, 148 C-SPY Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Device description file . . . . . . . . . . . . . . . . . . . . . . . . 123 Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Run to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 setting in Embedded Workbench. . . . . . . . . . . . . . . . . 121 Setup file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 C-SPY Settings (C-SPY option) . . . . . . . . . . . . . . . . . . . 122 C-SPY system macros. See C-SPY macros C-SPY windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Code Coverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Disassembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Locals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
main. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Profiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Quick Watch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Terminal I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Watch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 C-style preprocessor, definition of . . . . . . . . . . . . . . . . . . 226 C/EC++ Compiler Reference Guide (Help menu) . . . . . . 164 C/EC++ syntax styles, customizing . . . . . . . . . . . . . . . . . 156
D data field, in assembler list file. . . . . . . . . . . . . . . . . . . . . . 66 Data model (general option) . . . . . . . . . . . . . . . . . . . . . . . 88 data pointers, definition of . . . . . . . . . . . . . . . . . . . . . . . . 227 data representation, definition of . . . . . . . . . . . . . . . . . . . 227 DDE, calling external editor . . . . . . . . . . . . . . . . . . . . . . 150 ddf (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 123 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Debug info with terminal I/O (XLINK option) . . . . 111, 204 Debug info (XLINK option) . . . . . . . . . . . . . . . . . . . . . . 111 debug information generating in assembler. . . . . . . . . . . . . . . . . . . . . . . . 104 in compiler, generating . . . . . . . . . . . . . . . . . . . . . . . . . 97 Debug menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Debug target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Debugger Windows (View menu) . . . . . . . . . . . . . . . . . . 144 Debugger (IDE Options dialog) . . . . . . . . . . . . . . . . . . . . 158 Debugger (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . 149 debugger. See C-SPY debugging projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 externally built applications . . . . . . . . . . . . . . . . . . . . . 24 in disassembly mode . . . . . . . . . . . . . . . . . . . . . . . . . . 167 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 in source mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
241
UDSPIC-1
declaration, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 227 default installation path . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 #define options (XLINK) . . . . . . . . . . . . . . . . . . . . . . . . . 112 #define statement, in compiler . . . . . . . . . . . . . . . . . . . . . . 98 Define symbol (XLINK option). . . . . . . . . . . . . . . . . . . . 112 Defined symbols (assembler option) . . . . . . . . . . . . . . . . 106 Defined symbols (compiler option) . . . . . . . . . . . . . . . . . . 98 definition, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . 227 derivative, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . 227 development projects, examples . . . . . . . . . . . . . . . . . . . . 24 Device description file (C-SPY simulator option) . . . . . . 123 device description files. . . . . . . . . . . . . . . . . . . . . . . . 15, 123 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 special function registers. . . . . . . . . . . . . . . . . . . . . . . 172 specifying interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . 182 syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196, 198 using with memory maps . . . . . . . . . . . . . . . . . . . . . . 218 device driver, definition of . . . . . . . . . . . . . . . . . . . . . . . . 227 diagnostics assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 compiler including in list file . . . . . . . . . . . . . . . . . . . . . . . . . 97 suppressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 suppressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Diagnostics (assembler option) . . . . . . . . . . . . . . . . . . . . 107 Diagnostics (compiler option) . . . . . . . . . . . . . . . . . . . . . . 99 Diagnostics (XLINK option) . . . . . . . . . . . . . . . . . . . . . . 113 Diagnostics, in list file (compiler option) . . . . . . . . . . . . . 97 digital signal processor, definition of . . . . . . . . . . . . . . . . 227 directories bin (common) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 bin (dspic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 common. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 config. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 doc (common) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 doc (dspic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 dspic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 inc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
dsPIC IAR Embedded Workbench™ IDE
242 User Guide
UDSPIC-1
layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 lib. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15, 17 src (common) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 src (dspic) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 tutor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 _ _disableInterrupts (C-SPY system macro) . . . . . . . . . . 180 disassembly mode debugging . . . . . . . . . . . . . . . . . . . . . 167 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 toggling in C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Disassembly window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 DLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 dni (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–17 do (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 document conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 online. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–15 product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 runtime libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 XLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 doc, common (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . 14 doc, dspic (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Driver (C-SPY option) . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 _ _driverType (C-SPY system macro) . . . . . . . . . . . . . . . 180 dspic (directory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–15 DSP. See digital signal processor Dynamic Data Exchange (DDE), calling external editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 dynamic initialization, definition of . . . . . . . . . . . . . . . . . 227 dynamic memory allocation, definition of . . . . . . . . . . . . 227 dynamic object, definition of . . . . . . . . . . . . . . . . . . . . . . 227 d59 (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Index
E Edit menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 editing source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 editor external, specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 indentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 keyboard commands . . . . . . . . . . . . . . . . . . . . . . . . . . 131 options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Quick search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 shortcut to functions . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Editor Colors and Fonts, setting. . . . . . . . . . . . . . . . . . . . 156 editor window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 opening a new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 splitting into panes . . . . . . . . . . . . . . . . . . . . . . . 132, 163 Editor (IDE Options dialog box) . . . . . . . . . . . . . . . . . . . 155 EEPROM, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Embedded C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 syntax, enabling in compiler . . . . . . . . . . . . . . . . . . . . . 92 tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 embedded system, definition of . . . . . . . . . . . . . . . . . . . . 228 Embedded Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 exiting from . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 main window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 projects saved with previous version of, opening . 17, 136 reference information . . . . . . . . . . . . . . . . . . . . . . . . . 125 running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 version number, displaying . . . . . . . . . . . . . . . . . . . . . 164 Embedded Workbench Guide (Help menu) . . . . . . . . . . . 164 Embedded Workbench tutorial. . . . . . . . . . . . . . . . . . . . . . 29 emulator (C-SPY version) definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 third-party . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Enable Embedded C++ syntax (compiler option) . . . . . . . 92 Enable language extensions (compiler option) . . . . . . . . . 92 Enable remarks (assembler option) . . . . . . . . . . . . . . . . . 107
Enable remarks (compiler option) . . . . . . . . . . . . . . . . . . 100 Enable Virtual Space (editor option) . . . . . . . . . . . . . . . . 155 enabled transformations, in compiler. . . . . . . . . . . . . . . . . 94 _ _enableInterrupts (C-SPY system macro). . . . . . . . . . . 181 Enable/Disable Breakpoint (Edit menu) . . . . . . . . . . . . . 143 enumeration, definition of . . . . . . . . . . . . . . . . . . . . . . . . 228 EPROM, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 error messages assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 $EW_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . . 161 examples assembling a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 breakpoints, removing. . . . . . . . . . . . . . . . . . . . . . . . . . 47 compiling files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 creating a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 ddf file, using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 defining conditional breakpoints. . . . . . . . . . . . . . . . . . 76 defining interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 disassembly mode debugging . . . . . . . . . . . . . . . . . . . . 80 displaying function calls in C-SPY . . . . . . . . . . . . . 57, 79 displaying Terminal I/O . . . . . . . . . . . . . . . . . . . . . . . . 47 executing until a condition is true . . . . . . . . . . . . . . . . . 77 executing up to a breakpoint . . . . . . . . . . . . . . . . . . . . . 46 executing up to the cursor . . . . . . . . . . . . . . . . . . . . . . . 78 generating interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 linking a compiler program . . . . . . . . . . . . . . . . . . . . . . . . . 39 an assembler program . . . . . . . . . . . . . . . . . . . . . . . 67 monitoring memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 monitoring registers . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 running a compiler project in C-SPY . . . . . . . . . . . . . . 41 running an assembler program in C-SPY . . . . . . . . . . . 69 setting breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 simulating interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 specifying target options . . . . . . . . . . . . . . . . . . . . . . . . 32 stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 using C-SPY macros . . . . . . . . . . . . . . . . . . . . . . . . 49, 58
243
UDSPIC-1
using libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70–71 using the Embedded Workbench. . . . . . . . . . . . . . . . . . 29 using XLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 exceptions, definition of. . . . . . . . . . . . . . . . . . . . . . . . . . 228 execUserExit() (C-SPY setup macro) . . . . . . . . . . . . . . . 177 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 execUserPreload() (C-SPY setup macro). . . . . . . . . . . . . 177 execUserReset() (C-SPY setup macro) . . . . . . . . . . . . . . 177 execUserSetup() (C-SPY setup macro) . . . . . . . . . . . . . . 177 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Executables (output directory) . . . . . . . . . . . . . . . . . . . . . . 89 executing a program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 up to a breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 $EXE_DIR$ (argument variable). . . . . . . . . . . . . . . . . . . 161 Exit (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 EXIT (XLIB option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 expensive memory access, definition of. . . . . . . . . . . . . . 228 Export File List (pop-up menu command). . . . . . . . . . . . 128 expression syntax (C-SPY) . . . . . . . . . . . . . . . . . . . . . . . 171 expressions. See C-SPY expressions extended keywords, definition of . . . . . . . . . . . . . . . . . . . 228 extended linker command line file. See linker command file extensions. See filename extensions or language extensions External Editor (IDE Options dialog) . . . . . . . . . . . . . . . 150 external editor, specifying . . . . . . . . . . . . . . . . . . . . . . . . 150
F factory settings assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 features assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 XLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 FETCH-MODULES (XLIB option) . . . . . . . . . . . . . . . . . 72
dsPIC IAR Embedded Workbench™ IDE
244 User Guide
UDSPIC-1
file extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 a59 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 cfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 157 cpp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 ddf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16, 53 dni . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–17 d59. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 h. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 inc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 ini. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 lew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 lst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–17 pew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 r59 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 sfr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 s59 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 xcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 xlb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 File menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 file types configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 device description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 specifying in Embedded Workbench . . . . . . . . . . . 123 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 linker command file templates . . . . . . . . . . . . . . . . . . . 15 macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 read me . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–15 special function registers description files . . . . . . . . . . 15 syntax coloring configuration . . . . . . . . . . . . . . . . . . . . 15
Index
files adding to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 adding to group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 assembling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 compiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 readme.htm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 removing from group . . . . . . . . . . . . . . . . . . . . . . . . . 146 Files (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . 129, 145 $FILE_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 $FILE_FNAME$ (argument variable) . . . . . . . . . . . . . . . 161 $FILE_PATH$ (argument variable) . . . . . . . . . . . . . . . . . 161 Fill pattern (XLINK option). . . . . . . . . . . . . . . . . . . . . . . 119 Fill unused code memory (XLINK option) . . . . . . . . . . . 119 filters, register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Find in Files (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . 140 Find in Files (in Messages window) . . . . . . . . . . . . . . . . 134 Find (button). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Find (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 first.s59 (assembler tutorial file) . . . . . . . . . . . . . . . . . . . . 63 flat time (profiling). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Float size (general option) . . . . . . . . . . . . . . . . . . . . . . . . . 88 fonts, specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 for (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 format specifiers, definition of . . . . . . . . . . . . . . . . . . . . . 228 Format variant (XLINK option). . . . . . . . . . . . . . . . . . . . 111 Format (XLINK option). . . . . . . . . . . . . . . . . . . . . . . . . . 110 formats assembler list file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 compiler list file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 C-SPY input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 XLINK output default, overriding . . . . . . . . . . . . . . . . . . . . . . . . . 111 specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 function calls displaying in C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . 203
example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57, 79 See also Call Stack window Function inlining (compiler option) . . . . . . . . . . . . . . . . . . 95 functions C-SPY running to when starting . . . . . . . . . . . . . . . . . 122 intrinsic, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 229 shortcut to in editor windows . . . . . . . . . . . . . . . . . . . 130
G General options Data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Float size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Processor variant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Runtime library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 general options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87, 148 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 Generate checksum (XLINK option) . . . . . . . . . . . . . . . . 119 Generate debug information (assembler option) . . . . . . . 104 Generate debug information (compiler option) . . . . . . . . . 97 Generate linker listing (XLINK option). . . . . . . . . . . . . . 115 Generate Makefile (pop-up menu command) . . . . . . . . . 128 generic pointers, definition of . . . . . . . . . . . . . . . . . . . . . 228 glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Go to Bookmark (Edit menu). . . . . . . . . . . . . . . . . . . . . . 142 Go to function (editor button) . . . . . . . . . . . . . . . . . . . . . 130 Go to (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Go to, in C-SPY Disassembly window . . . . . . . . . . 196, 198 Go (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Go (Debug menu). . . . . . . . . . . . . . . . . . . . . . . . . . . 168, 210 Goto (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Graph (in Profiling window) . . . . . . . . . . . . . . . . . . . . . . 208 groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22, 129 adding files to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 removing files from . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
H h (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Harvard architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
245
UDSPIC-1
definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 heap memory, definition of . . . . . . . . . . . . . . . . . . . . . . . 229 heap size, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Help (Help menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 help, online. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 highlight color, paler variant of . . . . . . . . . . . . . . . . . . . . 169 host, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
I i (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 IAR Assembler Reference Guide. . . . . . . . . . . . . . . . . . . . 18 on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 IAR Compiler Reference Guide. . . . . . . . . . . . . . . . . . . . . 18 on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 IAR C-SPY Debugger. See C-SPY IAR Embedded Workbench Guide, on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 IAR on the Web (Help menu) . . . . . . . . . . . . . . . . . . . . . 165 IAR Systems website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 IAR XLINK Linker and IAR XLIB Librarian Reference Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 iaride.exe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 ICCDSPIC options. . . . . . . . . . . . . . . . . . . . . . . . . . . 91, 148 IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3–4 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 if else (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . 175 if (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Ignore CSTARTUP in library (XLINK option) . . . . . . . . 116 illegal access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 immediate breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Import File List (pop-up menu command). . . . . . . . . . . . 128 inc (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 inc (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 include files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 assembler, specifying path . . . . . . . . . . . . . . . . . . . . . 105 compiler, specifying path . . . . . . . . . . . . . . . . . . . . . . . 98
dsPIC IAR Embedded Workbench™ IDE
246 User Guide
UDSPIC-1
definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 XLINK, specifying path . . . . . . . . . . . . . . . . . . . . . . . 116 Include options (XLINK). . . . . . . . . . . . . . . . . . . . . . . . . 116 Include paths (assembler option) . . . . . . . . . . . . . . . . . . . 105 Include paths (compiler option) . . . . . . . . . . . . . . . . . . . . . 98 Include paths (XLINK option) . . . . . . . . . . . . . . . . . . . . . 116 Include source (compiler option) . . . . . . . . . . . . . . . . . . . . 97 Incremental Search (in Find) . . . . . . . . . . . . . . . . . . . . . . 139 Indent Size (editor option) . . . . . . . . . . . . . . . . . . . . . . . . 155 indentation, in Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 information, product. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Inherent (XLINK option) . . . . . . . . . . . . . . . . . . . . . . . . . 117 Inherent, no object code (XLINK option) . . . . . . . . . . . . 118 inherited settings assembler, overriding . . . . . . . . . . . . . . . . . . . . . . . . . 101 compiler, overriding . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 XLINK, overriding . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 ini (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 inline assembler, definition of . . . . . . . . . . . . . . . . . . . . . 229 inlining definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 of functions, in compiler . . . . . . . . . . . . . . . . . . . . . . . . 95 input formats, C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 input modules, specifying status in XLINK. . . . . . . . . . . 117 Input options (XLINK) . . . . . . . . . . . . . . . . . . . . . . . . . . 117 input, to Terminal I/O window. . . . . . . . . . . . . . . . . . . . . 204 installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 installation path, default . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 installed files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–15 executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 instruction mnemonics, definition of . . . . . . . . . . . . . . . . 229 Integrated Development Environment (IDE) . . . . . . . . . . 3–4 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Intel-extended, C-SPY input format . . . . . . . . . . . . . . . . . . 6 Internet, IAR Systems website. . . . . . . . . . . . . . . . . . . . . . 19 interrupt vector
Index
definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 interrupt vector table, definition of . . . . . . . . . . . . . . . . . 229 interrupts defining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 description, in Interrupts dialog box . . . . . . . . . . . . . . 217 editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 nested, definition of. . . . . . . . . . . . . . . . . . . . . . . . . . . 231 selecting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 simulation of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Interrupts (dialog box) . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Interrupts (Simulator menu). . . . . . . . . . . . . . . . . . . 215–216 intrinsic functions, definition of . . . . . . . . . . . . . . . . . . . . 229 intrinsic, definition of. . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 ISO/ANSI C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 adhering to. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 ISO/ANSI C mode, specifying in compiler . . . . . . . . . . . . 92
K key bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 key summary, editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 keywords, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . 230
L language extensions definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 enabling in compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 language facilities, in compiler . . . . . . . . . . . . . . . . . . . . . . 9 Language (assembler options) . . . . . . . . . . . . . . . . . . . . . 102 Language (compiler options) . . . . . . . . . . . . . . . . . . . . . . . 92 Latency (in Interrupt dialog box) . . . . . . . . . . . . . . . . . . . 217 layouts (for C-SPY windows) . . . . . . . . . . . . . . . . . . . . . 194 layouts (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 lew (file extension). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 lib (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
librarian. See XLIB libraries, runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 library files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11, 15 library functions, configurable . . . . . . . . . . . . . . . . . . . . . . 16 library modules creating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 loading in XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 specifying in assembler . . . . . . . . . . . . . . . . . . . . . . . . 103 specifying in compiler. . . . . . . . . . . . . . . . . . . . . . . . . . 96 Library (XLINK option) . . . . . . . . . . . . . . . . . . . . . . . . . 116 library, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 #line directives, generating in assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 in compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Lines/page (XLINK option). . . . . . . . . . . . . . . . . . . . . . . 115 line, moving to in Editor window. . . . . . . . . . . . . . . . . . . 142 Link (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 linker command file definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 path, specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 specifying in XLINK. . . . . . . . . . . . . . . . . . . . . . . . . . 117 templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 linker. See XLINK list files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 conditional information, specifying . . . . . . . . . . . . 105 in compiler, generating. . . . . . . . . . . . . . . . . . . . . . . 97 compiler assembler mnemonics, including . . . . . . . . . . . . . . . 97 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 source code, including . . . . . . . . . . . . . . . . . . . . . . . 97 XLINK generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 including segment map. . . . . . . . . . . . . . . . . . . . . . 115 specifying lines per page . . . . . . . . . . . . . . . . . . . . 115 List (assembler options) . . . . . . . . . . . . . . . . . . . . . . . . . . 104 List (compiler options). . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
247
UDSPIC-1
List (XLINK options). . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 LIST-MODULES (XLIB option). . . . . . . . . . . . . . . . . . . . 73 $LIST_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 Load as LIBRARY (XLINK option) . . . . . . . . . . . . . . . . 118 Load as PROGRAM (XLINK option) . . . . . . . . . . . . . . . 118 Load Default Layout (Debug menu) . . . . . . . . . . . . . . . . 215 Load Layout (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . 215 local variables C-SPY displaying info about . . . . . . . . . . . . . . . . . . . 168 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Locals window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 location breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 location counter, definition of . . . . . . . . . . . . . . . . . . . . . 232 log file, enabling in C-SPY . . . . . . . . . . . . . . . . . . . . . . . 214 Log window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Logging (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 214 logical address, definition of . . . . . . . . . . . . . . . . . . . . . . 235 loop statements, in C-SPY macros. . . . . . . . . . . . . . . . . . 175 Loop unrolling (compiler option) . . . . . . . . . . . . . . . . . . . 95 loop-invariant expressions . . . . . . . . . . . . . . . . . . . . . . . . . 95 low-level processor operations. . . . . . . . . . . . . . . . . . . . . . . 8 lst (file extension). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 L-value, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
M mac (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 machine-code programs. See assembler tutorials macro files, specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Macro quote characters (assembler option) . . . . . . . . . . . 102 macro statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 executing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 See also C-SPY macros Macros (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 MAC, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 mailbox (RTOS), definition of . . . . . . . . . . . . . . . . . . . . . 230 main function, C-SPY running to when starting . . . . . . . 122
dsPIC IAR Embedded Workbench™ IDE
248 User Guide
UDSPIC-1
main.s59 (assembler tutorial file). . . . . . . . . . . . . . . . . . . . 70 Make library module (assembler option) . . . . . . . . . . . . . 103 Make library module (compiler option). . . . . . . . . . . . . . . 96 Make options, specifying . . . . . . . . . . . . . . . . . . . . . . . . . 157 Make (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . 23, 149 managing projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 viewing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 map (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . 16–17 Match Brackets (Edit menu) . . . . . . . . . . . . . . . . . . 130, 143 Match Case (in Find in Files). . . . . . . . . . . . . . . . . . . . . . 141 Match Case (in Find) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Match Whole Word Only (in Find) . . . . . . . . . . . . . . . . . 139 Match Whole Word (in Find in Files) . . . . . . . . . . . . . . . 141 maxmin.s59 (assembler tutorial file) . . . . . . . . . . . . . . . . . 70 memory editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 filling unused. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 viewing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 memory access cost, definition of . . . . . . . . . . . . . . . . . . 231 memory access type (guarded by breakpoint) . . . . . . . . . 223 memory area, definition of . . . . . . . . . . . . . . . . . . . . . . . . 231 memory bank, definition of . . . . . . . . . . . . . . . . . . . . . . . 231 Memory Fill (C-SPY menu option) . . . . . . . . . . . . . . . . . 199 memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 memory model, definition of . . . . . . . . . . . . . . . . . . . . . . 231 Memory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 pop-up menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 memory zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196, 198 menu bar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 menus, C-SPY-specific. . . . . . . . . . . . . . . . . . . . . . . . . . . 195 message (C-SPY macro statement) . . . . . . . . . . . . . . . . . 176 messages displaying in Embedded Workbench. . . . . . . . . . . . . . 157
Index
printing during macro execution . . . . . . . . . . . . . . . . . 176 Messages window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Messages (View menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 144 microcontroller, definition of . . . . . . . . . . . . . . . . . . . . . . 231 microprocessor, definition of . . . . . . . . . . . . . . . . . . . . . . 231 module map, in map files . . . . . . . . . . . . . . . . . . . . . . . . . . 40 module name, specifying in compiler . . . . . . . . . . . . . . . . 96 Module status (XLINK option) . . . . . . . . . . . . . . . . . . . . 117 module types library loading in XLINK . . . . . . . . . . . . . . . . . . . . . . . . . 118 specifying in assembler . . . . . . . . . . . . . . . . . . . . . 103 specifying in compiler . . . . . . . . . . . . . . . . . . . . . . . 96 program, loading in XLINK . . . . . . . . . . . . . . . . . . . . 118 MODULE (assembler directive) . . . . . . . . . . . . . . . . . . . . 70 modules definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 including local symbols in input . . . . . . . . . . . . . . . . . 111 maintaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 specifying status in XLINK . . . . . . . . . . . . . . . . . . . . 117 Module-local symbols (XLINK option) . . . . . . . . . . . . . 111 Motorola, C-SPY input format. . . . . . . . . . . . . . . . . . . . . . . 6 Multiply and accumulate, definition of . . . . . . . . . . . . . . 230 multitasking, definition of . . . . . . . . . . . . . . . . . . . . . . . . 232
N nested interrupts, definition of . . . . . . . . . . . . . . . . . . . . . 231 New Group (Project menu) . . . . . . . . . . . . . . . . . . . . . . . 146 New measurement (in Profiling window) . . . . . . . . . . . . 208 New Project (dialog box) . . . . . . . . . . . . . . . . . . . . . . . . . . 29 New Window (Window menu). . . . . . . . . . . . . . . . . . . . . 163 New (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Next Error/Tag (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . 143 Next Statement (button) . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Next Statement (Debug menu). . . . . . . . . . . . . . . . . 168, 211 Next (Window menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 No global type checking (XLINK option) . . . . . . . . . . . . 113 non-banked memory, definition of . . . . . . . . . . . . . . . . . . 231 non-initialized memory, definition of . . . . . . . . . . . . . . . 231
non-volatile storage, definition of . . . . . . . . . . . . . . . . . . 231 NOP, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
O object files, specifying output directory. . . . . . . . . . . . . . . 89 Object module name (assembler option) . . . . . . . . . . . . . 104 Object module name (compiler option) . . . . . . . . . . . . . . . 96 object-oriented programming. . . . . . . . . . . . . . . . . . . . . . . . 8 $OBJ_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . . 161 old projects, converting . . . . . . . . . . . . . . . . . . . . . . . 17, 136 online documentation guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–15, 164 help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19, 164 Open Project (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . 136 Open (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 _ _openFile (C-SPY system macro). . . . . . . . . . . . . . . . . 181 operator precedence, definition of . . . . . . . . . . . . . . . . . . 231 operators, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 optimization levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 optimization models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 optimization techniques code motion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 common-subexpression elimination . . . . . . . . . . . . . . . 94 function inlining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 loop unrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 options assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101, 148 compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91, 148 C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121, 148 editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 file level. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 general . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87, 148 output directories. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 target level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109, 148 Options (dialog box) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Options (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 148 Options (Tools menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
249
UDSPIC-1
_ _orderInterrupt (C-SPY system macro) . . . . . . . . . . . . 182 Ouput assembler file (compiler option) . . . . . . . . . . . . . . . 97 output assembler generating library modules. . . . . . . . . . . . . . . . . . . 103 including debug information . . . . . . . . . . . . . . . . . 103 preprocessor, generating. . . . . . . . . . . . . . . . . . . . . 106 compiler including debug information . . . . . . . . . . . . . . . . . . 97 preprocessor, generating. . . . . . . . . . . . . . . . . . . . . . 99 XLINK generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 specifying filename . . . . . . . . . . . . . . . . . . . . . . . . 110 Output Directories (general option) . . . . . . . . . . . . . . . . . . 89 Output file (XLINK option) . . . . . . . . . . . . . . . . . . . . . . . 110 Output format (XLINK option) . . . . . . . . . . . . . . . . . . . . 111 output formats debug (ubrof). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110–111 Output list file (assembler option) . . . . . . . . . . . . . . . . . . 105 Output list file (compiler option) . . . . . . . . . . . . . . . . . . . . 97 Output options (XLINK) . . . . . . . . . . . . . . . . . . . . . . . . . 110 Output (assembler option) . . . . . . . . . . . . . . . . . . . . . . . . 103 Output (compiler options) . . . . . . . . . . . . . . . . . . . . . . . . . 96 Outside main, in Profiling window . . . . . . . . . . . . . . . . . 207 overview, product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
P package contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Page Setup (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Paste Special (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . 139 Paste (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 paths assembler include files . . . . . . . . . . . . . . . . . . . . . . . . 105 compiler include files . . . . . . . . . . . . . . . . . . . . . . . . . . 98 relative, in Embedded Workbench . . . . . . . . . . . . . . . 146 XLINK include files . . . . . . . . . . . . . . . . . . . . . . . . . . 116 peripherals, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 231 pew (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
dsPIC IAR Embedded Workbench™ IDE
250 User Guide
UDSPIC-1
pipeline, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 pointers, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 #pragma directive, definition of . . . . . . . . . . . . . . . . . . . . 232 precedence, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 231 preemptive multitasking, definition of . . . . . . . . . . . . . . . 232 preprocessing directives, definition of . . . . . . . . . . . . . . . 232 Preprocessor output to file (assembler option). . . . . . . . . 106 Preprocessor output to file (compiler option) . . . . . . . . . . 99 Preprocessor (assembler option) . . . . . . . . . . . . . . . . . . . 105 preprocessor (compiler options). . . . . . . . . . . . . . . . . . . . . 98 preprocessor, definition of. See C-style preprocessor prerequisites, programming experience . . . . . . . . . . . . . xxiii Previous (Window menu). . . . . . . . . . . . . . . . . . . . . . . . . 164 Print (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Probability, in Interrupt dialog box . . . . . . . . . . . . . . . . . 217 Processing options (XLINK) . . . . . . . . . . . . . . . . . . . . . . 119 processor operations, low-level . . . . . . . . . . . . . . . . . . . . . . 8 Processor variant (general option) . . . . . . . . . . . . . . . . . . . 88 processor variant, definition of. . . . . . . . . . . . . . . . . . . . . 232 product information, obtaining detailed. . . . . . . . . . . . . . 165 product overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Profiling window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 pop-up menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 program counter, definition of . . . . . . . . . . . . . . . . . . . . . 232 program execution, in C-SPY . . . . . . . . . . . . . . . . . . . . . 168 program location counter, definition of . . . . . . . . . . . . . . 232 program modules, loading in XLINK . . . . . . . . . . . . . . . 118 programming experience . . . . . . . . . . . . . . . . . . . . . . . . xxiii Project Manager windows Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Project menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 project model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 project options, definition of . . . . . . . . . . . . . . . . . . . . . . 232 Project window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Index
groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 source files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Project (menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 projects adding files to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 assembling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 building . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23, 149 compiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 creating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29, 71 debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 developing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 for debugging externally built applications. . 24, 137, 167 linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 managing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 mixed C and assembler, example . . . . . . . . . . . . . . . . . 82 moving files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 opening old versions . . . . . . . . . . . . . . . . . . . . . . . 17, 136 organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 removing items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 updating. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136, 149 $PROJ_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 $PROJ_FNAME$ (argument variable) . . . . . . . . . . . . . . 161 $PROJ_PATH$ (argument variable) . . . . . . . . . . . . . . . . 161 PROM, definition of. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 PUBLIC (assembler directive) . . . . . . . . . . . . . . . . . . . . . . 70
Q qualifiers, definition of. See type qualifiers Quick search (text box on toolbar). . . . . . . . . . . . . . . . . . 127 Quick Watch (Debug menu). . . . . . . . . . . . . . . . . . . . . . . 211 QuickStart Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
QUIT (XLIB option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
R Range checks (XLINK option) . . . . . . . . . . . . . . . . . . . . 114 _ _readFile (C-SPY system macro) . . . . . . . . . . . . . . . . . 183 _ _readFileByte (C-SPY system macro) . . . . . . . . . . . . . 183 readme files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14–15 readme.htm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 _ _readMemoryByte (C-SPY system macro) . . . . . . . . . 184 real-time operating system, definition of . . . . . . . . . . . . . 232 real-time system, definition of . . . . . . . . . . . . . . . . . . . . . 232 Recent Files (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . 137 Recent Projects (File menu) . . . . . . . . . . . . . . . . . . . . . . . 137 Redo (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 reference guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 reference information C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Embedded Workbench . . . . . . . . . . . . . . . . . . . . . . . . 125 Refresh (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Refresh (in Code Coverage window) . . . . . . . . . . . . . . . . 206 Refresh (in Profiling window) . . . . . . . . . . . . . . . . . . . . . 209 register constant, definition of . . . . . . . . . . . . . . . . . . . . . 232 Register Filter (IDE Options dialog) . . . . . . . . . . . . . . . . 159 register locking, definition of . . . . . . . . . . . . . . . . . . . . . . 232 register variables, definition of. . . . . . . . . . . . . . . . . . . . . 233 Register window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 register zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196, 198 _ _registerMacroFile (C-SPY system macro) . . . . . . . . . 184 registers customizing display of . . . . . . . . . . . . . . . . . . . . . . . . 159 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 viewing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 relative paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Release target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 relocatable segments, definition of . . . . . . . . . . . . . . . . . 233 remarks, assembler diagnostics . . . . . . . . . . . . . . . . . . . . 108 remarks, compiler diagnostics . . . . . . . . . . . . . . . . . . . . . 100
251
UDSPIC-1
repeat interval. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Replace (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Replace (Edit menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 reset definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Reset (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Reset (Debug menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 _ _resetFile (C-SPY system macro). . . . . . . . . . . . . . . . . 185 return (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . 175 ROM-monitor definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 root directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Round Robin, definition of . . . . . . . . . . . . . . . . . . . . . . . 233 routines, time-critical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 RTOS, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Run to Cursor (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Run to Cursor (Debug menu) . . . . . . . . . . . . . . . . . . . . . . 211 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Run to (C-SPY option). . . . . . . . . . . . . . . . . . . . . . . . . . . 122 runtime libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Runtime library (general option) . . . . . . . . . . . . . . . . . . . . 88 runtime library, definition of . . . . . . . . . . . . . . . . . . . . . . 233 runtime model attributes definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 in map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 R-value, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 r59 (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
S sample applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 saturated mathematics, definition of . . . . . . . . . . . . . . . . 233 Save All (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Save As (File menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Save As (in Code Coverage window) . . . . . . . . . . . . . . . 206 Save As (in Profiling window) . . . . . . . . . . . . . . . . . . . . . 209 Save Current Layout As Default (Debug menu) . . . . . . . 215
dsPIC IAR Embedded Workbench™ IDE
252 User Guide
UDSPIC-1
Save Layout As (Debug menu) . . . . . . . . . . . . . . . . . . . . 215 Save Project (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . 137 Save (File menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Scan for Changed Files (editor option) . . . . . . . . . . . . . . 155 scheduler (RTOS), definition of . . . . . . . . . . . . . . . . . . . . 233 scope, definition of. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Segment map (XLINK option). . . . . . . . . . . . . . . . . . . . . 115 segment map, definition of. . . . . . . . . . . . . . . . . . . . . . . . 233 Segment overlap warnings (XLINK option) . . . . . . . . . . 113 segments definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 overlap errors, reducing. . . . . . . . . . . . . . . . . . . . . . . . 113 range checks, controlling . . . . . . . . . . . . . . . . . . . . . . 114 section in map files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Select All (Edit menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 semaphores, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 233 Set Log File (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . 214 Set Next Statement (Debug menu). . . . . . . . . . . . . . . . . . 212 Set Terminal IO Log File (Debug menu) . . . . . . . . . . . . . 214 _ _setCodeBreak (C-SPY system macro) . . . . . . . . . . . . 185 _ _setDataBreak (C-SPY system macro) . . . . . . . . . . . . . 186 _ _setSimBreak (C-SPY system macro) . . . . . . . . . . . . . 187 settings (directory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 settings (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Setup file (C-SPY option) . . . . . . . . . . . . . . . . . . . . . . . . 123 setup macros, in C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . 177 See also C-SPY macros severity level, definition of. . . . . . . . . . . . . . . . . . . . . . . . 234 SFR definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 sfr (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 short addressing, definition of . . . . . . . . . . . . . . . . . . . . . 234 shortcut keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Show Bookmarks (editor option) . . . . . . . . . . . . . . . . . . . 155 Show details (in Profiling window) . . . . . . . . . . . . . . . . . 209 Show Line Number (editor option) . . . . . . . . . . . . . . . . . 155 showing build messages, in Embedded Workbench . . . . 157 side-effect, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Index
signals, definition of. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 simulation enabling/disabling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 of interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 of peripheral devices . . . . . . . . . . . . . . . . . . . . . . . . . . 170 simulator definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Simulator menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 size optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 skeleton code, definition of . . . . . . . . . . . . . . . . . . . . . . . 234 source code debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 including in compiler list file . . . . . . . . . . . . . . . . . . . . 97 source file paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22, 129 adding to a project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 moving between groups . . . . . . . . . . . . . . . . . . . . . . . 129 source mode debugging, example . . . . . . . . . . . . . . . . . . . 41 special function registers (SFR) definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 description files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 using as assembler symbols . . . . . . . . . . . . . . . . . . . . 172 speed optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Split (Window menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 src, common (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . 14 src, dspic (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 stack frames, definition of . . . . . . . . . . . . . . . . . . . . . . . . 234 stack segments, definition of . . . . . . . . . . . . . . . . . . . . . . 234 static objects, definition of . . . . . . . . . . . . . . . . . . . . . . . . 234 static overlay, definition of. . . . . . . . . . . . . . . . . . . . . . . . 234 statically allocated memory, definition of . . . . . . . . . . . . 234 status bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Status Bar (View menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Step Into (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Step Into (Debug menu) . . . . . . . . . . . . . . . . . . . . . . 168, 211 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Step Out (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Step Out (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Step Over (button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Step Over (Debug menu) . . . . . . . . . . . . . . . . . . . . . 168, 211 step points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 stepping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 stepping information, generated by compiler . . . . . . . . . 168 Stop Build (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . 149 Stop Debugging (button) . . . . . . . . . . . . . . . . . . . . . . . . . 195 Stop Debugging (Debug menu) . . . . . . . . . . . . . . . . . . . . 210 _ _strFind (C-SPY system macro) . . . . . . . . . . . . . . . . . . 188 Strict ISO/ANSI (compiler option) . . . . . . . . . . . . . . . . . . 93 structure value, definition of . . . . . . . . . . . . . . . . . . . . . . 234 _ _subString (C-SPY system macro) . . . . . . . . . . . . . . . . 189 support, technical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 important when contacting . . . . . . . . . . . . . . . . . . . . . 165 Suppress all warnings (XLINK option) . . . . . . . . . . . . . . 114 Suppress these diagnostics (assembler option) . . . . . . . . 107 Suppress these diagnostics (compiler option) . . . . . . . . . 100 Suppress these diagnostics (XLINK option) . . . . . . . . . . 114 symbol and cross-reference table, in assembler list file. . . 66 See also Include cross-reference (assembler option) symbolic location, definition of . . . . . . . . . . . . . . . . . . . . 235 symbols See also user symbols defining in assembler . . . . . . . . . . . . . . . . . . . . . . . . . 106 defining in compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 defining in XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 in input modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 using in C-SPY expressions . . . . . . . . . . . . . . . . . . . . 171 syntax coloring configuration files. . . . . . . . . . . . . . . . . . . 15 Syntax Highlighting (editor option) . . . . . . . . . . . . . . . . . 155 syntax highlighting, in Editor window. . . . . . . . . . . . . . . 129 system macros. See C-SPY macros s59 (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
253
UDSPIC-1
T Tab Key Function (editor option). . . . . . . . . . . . . . . . . . . 155 Tab Size (editor option) . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Target CPU Family. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 target monitor, definition of . . . . . . . . . . . . . . . . . . . . . . . 235 Target options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 target processors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Target (general options) . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21, 128 changing groups in . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 creating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Targets (Project menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 target, definition of. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 $TARGET_DIR$ (argument variable) . . . . . . . . . . . . . . . 161 $TARGET_FNAME$ (argument variable) . . . . . . . . . . . 161 $TARGET_PATH$ (argument variable) . . . . . . . . . . . . . 161 task, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 technical support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 important when contacting . . . . . . . . . . . . . . . . . . . . . 165 tentative definition, definition of . . . . . . . . . . . . . . . . . . . 235 terminal I/O definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 simulating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111, 170 Terminal I/O window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 testing, of code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 thread, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Tile Horizontally (Window menu) . . . . . . . . . . . . . . . . . . 163 Tile Vertically (Window menu) . . . . . . . . . . . . . . . . . . . . 163 time accumulated (profiling) . . . . . . . . . . . . . . . . . . . . . . . . 207 activation, in interrupts . . . . . . . . . . . . . . . . . . . . . . . . 217 flat (profiling) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
dsPIC IAR Embedded Workbench™ IDE
254 User Guide
UDSPIC-1
variance, in interrupts . . . . . . . . . . . . . . . . . . . . . . . . . 218 timer, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 timeslice, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 time-critical routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Toggle Bookmark (Edit menu). . . . . . . . . . . . . . . . . . . . . 142 Toggle Breakpoint (button) . . . . . . . . . . . . . . . . . . . . . . . 195 Toggle Breakpoint (Edit menu) . . . . . . . . . . . . . . . . 143, 169 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45, 55 _ _toLower (C-SPY system macro) . . . . . . . . . . . . . . . . . 189 Tool Output (in Messages window) . . . . . . . . . . . . . . . . . 134 toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Toolbars (View menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 $TOOLKIT_DIR$ (argument variable) . . . . . . . . . . . . . . 161 Tools menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 tools, user-configured. . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 _ _toUpper (C-SPY system macro) . . . . . . . . . . . . . . . . . 190 transformations, enabled in compiler. . . . . . . . . . . . . . . . . 94 translation unit, definition of . . . . . . . . . . . . . . . . . . . . . . 235 trap, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Treat all warnings as errors (compiler option) . . . . . . . . . 100 Treat ‘char’ as ‘signed char’ (compiler option) . . . . . . . . . 93 Treat these as errors (assembler option). . . . . . . . . . . . . . 108 Treat these as errors (compiler option) . . . . . . . . . . . . . . 100 Treat these as errors (XLINK option) . . . . . . . . . . . . . . . 114 Treat these as remarks (assembler option) . . . . . . . . . . . . 108 Treat these as remarks (compiler option). . . . . . . . . . . . . 100 Treat these as warnings (assembler option) . . . . . . . . . . . 108 Treat these as warnings (compiler option) . . . . . . . . . . . . 100 Treat these as warnings (XLINK option) . . . . . . . . . . . . . 114 Treat warnings as errors (assembler option) . . . . . . . . . . 107 tutor (subdirectory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 tutorial files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 tutorials assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Embedded Workbench . . . . . . . . . . . . . . . . . . . . . . . . . 29 type checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9, 11 disabling at link time. . . . . . . . . . . . . . . . . . . . . . . . . . 113
Index
type qualifiers, definition of . . . . . . . . . . . . . . . . . . . . . . . 235 typographic conventions . . . . . . . . . . . . . . . . . . . . . . . . . xxv
U UART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 UBROF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 10 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Undo (Edit menu). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Universal Binary Relocatable Object Format (UBROF) 6, 10 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Use Default Size (editor option) . . . . . . . . . . . . . . . . . . . 156 User symbols are case sensitive (assembler option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
V variables using in arguments . . . . . . . . . . . . . . . . . . . . . . . 160–161 using in C-SPY expressions . . . . . . . . . . . . . . . . . . . . 171 watching in C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 version number, of Embedded Workbench . . . . . . . . . . . 164 versions, of C-SPY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 View menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 virtual address, definition of . . . . . . . . . . . . . . . . . . . . . . 235 virtual space, definition of . . . . . . . . . . . . . . . . . . . . . . . . 235 volatile storage, definition of . . . . . . . . . . . . . . . . . . . . . . 236 von Neumann architecture . . . . . . . . . . . . . . . . . . . . . . . . 219 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
W warnings assembler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107–108 compiler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Warnings/Errors (XLINK option) . . . . . . . . . . . . . . . . . . 114 Watch window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 pop-up menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
watchpoints definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 website, IAR Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 while (macro statement). . . . . . . . . . . . . . . . . . . . . . . . . . 175 Window menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 windows. See Project Manager windows or C-SPY windows _ _writeFile (C-SPY system macro) . . . . . . . . . . . . . . . . 190 _ _writeFileByte (C-SPY system macro). . . . . . . . . . . . . 190 _ _writeMemoryByte (C-SPY system macro) . . . . . . . . . 191 www.iar.com . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
X XCL filename (XLINK option) . . . . . . . . . . . . . . . . . . . . 117 xcl (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 xlb (file extension) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 XLIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11, 70 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . 165 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 XLIB options definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 FETCH-MODULES . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 LIST-MODULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 XLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 on the Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . 165 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39, 67 XLINK and XLIB Reference Guide (Help menu). . . . . . 165 XLINK diagnostics suppressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 XLINK list files generating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 including segment map . . . . . . . . . . . . . . . . . . . . . . . . 115 specifying lines per page. . . . . . . . . . . . . . . . . . . . . . . 115
255
UDSPIC-1
XLINK options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109, 148 Always generate output. . . . . . . . . . . . . . . . . . . . . . . . 113 Debug info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Debug info with terminal I/O . . . . . . . . . . . . . . . 111, 204 Define symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 factory settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Fill pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Fill unused code memory . . . . . . . . . . . . . . . . . . . . . . 119 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Format variant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Generate checksum . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Generate linker listing . . . . . . . . . . . . . . . . . . . . . . . . . 115 Ignore CSTARTUP in library . . . . . . . . . . . . . . . . . . . 116 Include paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Inherent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Inherent, no object code . . . . . . . . . . . . . . . . . . . . . . . 118 Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Lines/page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Load as LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Load as PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Module status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Module-local symbols. . . . . . . . . . . . . . . . . . . . . . . . . 111 No global type checking . . . . . . . . . . . . . . . . . . . . . . . 113 Output file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Output format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 override inherited settings . . . . . . . . . . . . . . . . . . . . . . 109 Range checks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Segment map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Segment overlap warnings . . . . . . . . . . . . . . . . . . . . . 113 setting in Embedded Workbench. . . . . . . . . . . . . . . . . 109 Suppress all warnings . . . . . . . . . . . . . . . . . . . . . . . . . 114 Suppress these diagnostics . . . . . . . . . . . . . . . . . . . . . 114 Treat these as errors. . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Treat these as warnings . . . . . . . . . . . . . . . . . . . . . . . . 114 Warnings/Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 XCL filename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 XLINK output overriding default format . . . . . . . . . . . . . . . . . . . . . . 111
dsPIC IAR Embedded Workbench™ IDE
256 User Guide
UDSPIC-1
XLINK output formats specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 XLINK symbols, defining . . . . . . . . . . . . . . . . . . . . . . . . 112
Z zero-overhead loop, definition of . . . . . . . . . . . . . . . . . . . 236 zone in Breakpoints dialog box . . . . . . . . . . . . . . . . . . . . . . 222 zone, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Symbols #define options (XLINK). . . . . . . . . . . . . . . . . . . . . . . . . 112 #define statement, in compiler . . . . . . . . . . . . . . . . . . . . . . 98 #line directives, generating in assembler . . . . . . . . . . . . . 106 #line directives, generating in compiler . . . . . . . . . . . . . . . 99 #pragma directive, definition of . . . . . . . . . . . . . . . . . . . . 232 $CUR_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 $CUR_LINE$ (argument variable) . . . . . . . . . . . . . . . . . 161 $EW_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . . 161 $EXE_DIR$ (argument variable). . . . . . . . . . . . . . . . . . . 161 $FILE_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 $FILE_FNAME$ (argument variable) . . . . . . . . . . . . . . . 161 $FILE_PATH$ (argument variable) . . . . . . . . . . . . . . . . . 161 $LIST_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 $OBJ_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . . 161 $PROJ_DIR$ (argument variable) . . . . . . . . . . . . . . . . . . 161 $PROJ_FNAME$ (argument variable) . . . . . . . . . . . . . . 161 $PROJ_PATH$ (argument variable) . . . . . . . . . . . . . . . . 161 $TARGET_DIR$ (argument variable) . . . . . . . . . . . . . . . 161 $TARGET_FNAME$ (argument variable) . . . . . . . . . . . 161 $TARGET_PATH$ (argument variable) . . . . . . . . . . . . . 161 $TOOLKIT_DIR$ (argument variable) . . . . . . . . . . . . . . 161 _ _cancelAllInterrupts (C-SPY system macro) . . . . . . . . 178 _ _cancelInterrupt (C-SPY system macro) . . . . . . . . . . . 179 _ _clearBreak (C-SPY system macro) . . . . . . . . . . . . . . . 179 _ _closeFile (C-SPY system macro) . . . . . . . . . . . . . . . . 179 _ _disableInterrupts (C-SPY system macro) . . . . . . . . . . 180 _ _driverType (C-SPY system macro) . . . . . . . . . . . . . . . 180
Index
_ _enableInterrupts (C-SPY system macro). . . . . . . . . . . 181 _ _openFile (C-SPY system macro). . . . . . . . . . . . . . . . . 181 _ _orderInterrupt (C-SPY system macro) . . . . . . . . . . . . 182 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 _ _readFile (C-SPY system macro) . . . . . . . . . . . . . . . . . 183 _ _readFileByte (C-SPY system macro) . . . . . . . . . . . . . 183 _ _readMemoryByte (C-SPY system macro) . . . . . . . . . 184 _ _registerMacroFile (C-SPY system macro) . . . . . . . . . 184 _ _resetFile (C-SPY system macro). . . . . . . . . . . . . . . . . 185 _ _setCodeBreak (C-SPY system macro) . . . . . . . . . . . . 185 _ _setDataBreak (C-SPY system macro) . . . . . . . . . . . . . 186 _ _setSimBreak (C-SPY system macro) . . . . . . . . . . . . . 187 example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 _ _strFind (C-SPY system macro) . . . . . . . . . . . . . . . . . . 188 _ _subString (C-SPY system macro) . . . . . . . . . . . . . . . . 189 _ _toLower (C-SPY system macro) . . . . . . . . . . . . . . . . . 189 _ _toUpper (C-SPY system macro) . . . . . . . . . . . . . . . . . 190 _ _writeFile (C-SPY system macro) . . . . . . . . . . . . . . . . 190 _ _writeFileByte (C-SPY system macro). . . . . . . . . . . . . 190 _ _writeMemoryByte (C-SPY system macro) . . . . . . . . . 191
257
UDSPIC-1
dsPIC IAR Embedded Workbench™ IDE
258 User Guide
UDSPIC-1
