Intel IXP2400 User manual

Intel®IXP2400/IXP2800 Network
Processors
Development Tools User’s Guide
March 2004
Order Number: 278733-011

Development Tools User’s Guide
Intel®IXP2400/IXP2800 Network Processors
Information in this document is provided in connection with Intel® products.No license, express or implied, by estoppel or otherwise, to any intellectual
property rights is granted by this document. Except as provided in Intel's Terms and Conditions of Sale for such products, Intel assumes no liability
whatsoever, and Intel disclaims any express or implied warranty, relating to sale and/or use of Intel products including liability or warranties relating to
fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Intel products are not
intended for use in medical, life saving, or life sustaining applications.
Intel may make changes to specifications and product descriptions at any time, without notice.
The IXP2400 AND IXP2800 Network Processors may contain design defects or errors known as errata which may cause the product to deviate from
published specifications. Current characterized errata are available on request.
This document and the software described in it are furnished under license and may only be used or copied in accordance with the terms of the
license. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a
commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this
document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may
be reproduced, stored in a retrieval system, or transmitted in any form or by any means without the express written consent of Intel Corporation.
Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
Copies of documents which have an ordering number and are referenced in this document, or other Intel literature may be obtained by calling
1-800-548-4725 or by visiting Intel's Web site at http://www.intel.com.
Copyright © Intel Corporation, 2004
Intel and XScale are registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries
*Other names and brands may be claimed as the property of others.
Revision History
Revision Date Revision Description
3/04 011 Release for SDK 3.51.
1/04 010 Reserved.
11/03 009 Release for SDK 3.5 PR-2.
09/03 008 Release for SDK 3.5 PR-1.
07/03 007 SDK 3.1 Pre-Release 3.
06/03 006 SDK 3.1 Pre-Release 2.
01/03 005 Fifth release of documentation IXP2400/IXP2800 for IXA SDK 3.0 Pre-
Release 6.
10/02 004 Fourth release of documentation for IXP2400/IXP2800 for IXA SDK 3.0 Pre-
Release 5
08/02 003 Third release of documentation for IXP2400/IXP2800 for IXA SDK 3.0 Pre-
Release 4
05/02 002 Second release of documentation for IXP2400/IXP2800 for IXA SDK 3.0
1/25/02 001 First IXP2400/IXP2800 only release for Pre-Release II

Development Tools User’s Guide iii
Intel®IXP2400/IXP2800 Network Processors
Contents
1 Introduction............................................................................................................. 17
1.1 About this Document........................................................................................................ 17
1.2 Intended Audience............................................................................................................17
1.3 Related Documents.......................................................................................................... 17
2 Developer Workbench............................................................................................ 19
2.1 Overview........................................................................................................................... 19
2.2 About the Graphical User Interface (GUI) ........................................................................ 20
2.2.1 About Windows, Toolbars, and Menus ......................................................................... 20
2.2.2 Hiding and Showing Windows and Toolbars................................................................. 21
2.2.3 Customizing Toolbars and Menus................................................................................. 22
2.2.3.1 Creating Toolbars.................................................................................................. 22
2.2.3.2 Renaming Toolbars ............................................................................................... 23
2.2.3.3 Deleting Toolbars................................................................................................... 23
2.2.3.4 Adding and Removing Toolbar Buttons and Controls............................................ 23
2.2.3.5 Customizing Menus............................................................................................... 24
2.2.3.6 Returning to Default Toolbar Settings.................................................................... 24
2.2.4 GUI Toolbar Configurations .......................................................................................... 25
2.3 Workbench Projects ......................................................................................................... 25
2.3.1 Creating a New Project ................................................................................................. 25
2.3.1.1 Debug-only Projects .............................................................................................. 27
2.3.2 Opening a Project ......................................................................................................... 28
2.3.3 Saving a Project............................................................................................................ 28
2.3.4 Closing a Project........................................................................................................... 29
2.3.5 Specifying a Default Project Folder............................................................................... 29
2.4 About the Project Workspace........................................................................................... 30
2.4.1 About FileView .............................................................................................................. 30
2.4.2 About ThreadView......................................................................................................... 31
2.4.2.1 Expanding and Collapsing Thread Trees .............................................................. 31
2.4.2.2 Renaming a Thread............................................................................................... 31
2.4.3 About InfoView.............................................................................................................. 32
2.5 Working with Files ............................................................................................................ 32
2.5.1 Creating New Files........................................................................................................ 32
2.5.2 Opening Files................................................................................................................ 33
2.5.3 Closing Files.................................................................................................................. 33
2.5.4 Saving Files................................................................................................................... 33
2.5.5 Saving Copies of Files .................................................................................................. 34
2.5.6 Saving All Files at Once................................................................................................ 34
2.5.7 Working With File Windows........................................................................................... 34
2.5.8 Printing Files ................................................................................................................. 35
2.5.8.1 Setting Up the Printer ............................................................................................ 35
2.5.8.2 Printing the File...................................................................................................... 35
2.5.9 Inserting Into and Removing Files from a Project ......................................................... 36
2.5.9.1 Inserting Files Into a Project.................................................................................. 36
2.5.9.2 Removing Files From a Project ............................................................................. 36
2.5.10 Editing Files................................................................................................................... 36
2.5.10.1 Tab Configuration.................................................................................................. 36

iv Development Tools User’s Guide
Intel®IXP2400/IXP2800 Network Processors
2.5.10.2 Go To Line............................................................................................................. 37
2.5.11 Bookmarks and Errors/Tags ......................................................................................... 38
2.5.12 About Find In Files........................................................................................................ 38
2.5.13 About Fonts and Syntax Coloring ................................................................................. 39
2.5.14 About Macros................................................................................................................ 40
2.6 The Assembler ................................................................................................................. 40
2.6.1 Root Files and Dependencies....................................................................................... 41
2.6.2 Selecting Assembler Build Settings .............................................................................. 41
2.6.2.1 General Build Settings........................................................................................... 42
2.6.2.2 Specifying Additional Include Paths ...................................................................... 42
2.6.2.3 Specifying Assembler Options............................................................................... 43
2.6.3 Invoking the Assembler................................................................................................. 45
2.6.4 Assembly Errors............................................................................................................46
2.7 The Microengine C Compiler............................................................................................ 47
2.7.1 Adding C Source Files to Your Project.......................................................................... 48
2.7.2 Selecting Compiler Build Settings................................................................................. 48
2.7.2.1 Selecting Additional Compiler Include Paths......................................................... 48
2.7.2.2 Selecting the target .list File .................................................................................. 49
2.7.2.3 Selecting C Source Files to Compile..................................................................... 49
2.7.2.4 Selecting C Object Files to Compile...................................................................... 50
2.7.2.5 Removing C Source Files to Compile.................................................................... 50
2.7.2.6 Selecting the Target .obj File................................................................................. 50
2.7.2.7 Deleting a Target .list or .obj File........................................................................... 51
2.7.2.8 Selecting Compile Options .................................................................................... 51
2.7.2.9 Saving Build Settings............................................................................................. 53
2.7.3 Invoking the Compiler ................................................................................................... 53
2.7.4 Compilation Errors ........................................................................................................ 53
2.8 The Linker ........................................................................................................................ 54
2.8.1 Customizing Linker Settings.......................................................................................... 54
2.8.2 Building and Rebuilding a Project................................................................................. 57
2.9 Configuring the IXP2400 Simulation Environment ........................................................... 58
2.9.1 IXP2400 Clock Frequencies.......................................................................................... 58
2.9.2 IXP2400 Memory .......................................................................................................... 59
2.9.3 IXP2400 MSF Device Configuration ............................................................................. 61
2.9.4 IXP2400 Network Connections..................................................................................... 65
2.9.5 IXP2400 CBUS Connections ........................................................................................ 67
2.10 Configuring the IXP2800 Simulation Environment........................................................... 68
2.10.1 IXP2800 Clock Frequencies.......................................................................................... 68
2.10.2 IXP2800 Memory .......................................................................................................... 69
2.10.3 IXP2800 MSF Device Configuration ............................................................................. 71
2.10.4 IXP2800 Network Connections..................................................................................... 76
2.10.5 IXP2800 CBUS Connections ........................................................................................ 77
2.11 Packet Simulation............................................................................................................. 78
2.11.1 General Options............................................................................................................ 79
2.11.2 Traffic Interface Logging ............................................................................................... 80
2.11.3 Stop Control.................................................................................................................. 82
2.11.4 Traffic Assignment ........................................................................................................83
2.11.5 Manage NTS Plug-ins................................................................................................... 88
2.11.5.1 Network Traffic Simulation DLLs........................................................................... 89
2.12 Data Streams ................................................................................................................... 90
2.12.1 Creating and Editing a POS IP Data Stream ................................................................ 92

Development Tools User’s Guide v
Intel®IXP2400/IXP2800 Network Processors
2.12.2 Creating and Editing an ATM Data Stream................................................................... 94
2.12.3 Creating and Editing a Custom Ethernet TCP/IP Data Stream..................................... 95
2.12.4 Creating and Editing an Ethernet IP Data Stream ........................................................ 97
2.12.5 Creating and Editing an Ethernet TCP/IP Data Stream ................................................ 98
2.12.6 Creating and Editing a PPP TCP/IP Data Stream......................................................... 99
2.12.7 Creating an IP Packet Pool......................................................................................... 101
2.12.8 Specifying an Ethernet Header ................................................................................... 102
2.12.9 Specifying an IP Header ............................................................................................. 102
2.12.10 Specifying a TCP Header............................................................................................ 103
2.12.11 Specifying a Data Payload.......................................................................................... 103
2.12.12 Specifying Frame Size ................................................................................................ 104
2.13 Debugging...................................................................................................................... 104
2.13.1 Local Simulation Debugging with a Local Foreign Model............................................ 106
2.13.1.1 Local Simulation Debugging with a Remote Foreign Model................................ 107
2.13.1.2 Hardware Debugging........................................................................................... 107
2.13.1.3 Portmapper.......................................................................................................... 108
2.13.2 Starting and Stopping the Debugger........................................................................... 108
2.13.3 Changing Simulation Options...................................................................................... 108
2.13.3.1 Marking Instructions............................................................................................. 108
2.13.3.2 Changing the Colors for Execution State............................................................. 110
2.13.3.3 Initializing Simulation Startup Options................................................................. 110
2.13.3.4 Using Imported Variable Data.............................................................................. 111
2.13.4 Exporting the Startup Script ........................................................................................ 113
2.13.5 Changing Hardware Options....................................................................................... 113
2.13.5.1 Specifying Hardware Startup Options.................................................................. 113
2.13.6 The Command Line Interface...................................................................................... 114
2.13.7 Command Scripts........................................................................................................ 114
2.13.8 Thread Windows ......................................................................................................... 115
2.13.8.1 Controlling Thread Window Activation................................................................. 115
2.13.8.2 Thread Window Controls..................................................................................... 117
2.13.8.3 Tracking the Active Thread.................................................................................. 119
2.13.8.4 Running to Cursor................................................................................................ 119
2.13.8.5 Toggle View......................................................................................................... 119
2.13.8.6 Activating Thread Windows................................................................................. 120
2.13.8.7 Displaying, Expanding, and Collapsing Macros (Assembled Threads Only)....... 121
2.13.8.8 Displaying and Hiding Instruction Addresses ...................................................... 122
2.13.8.9 Instruction Markers.............................................................................................. 123
2.13.8.10 Viewing Instruction Execution in the Thread Window.......................................... 123
2.13.8.11 Document and Thread Window History............................................................... 124
2.13.9 Run Control................................................................................................................. 125
2.13.9.1 Single Stepping.................................................................................................... 125
2.13.9.2 Stepping Microengines........................................................................................ 125
2.13.9.3 Stepping Over...................................................................................................... 126
2.13.9.4 Stepping Into (Compiled Threads Only) .............................................................. 126
2.13.9.5 Stepping Out (Compiled Threads Only)............................................................... 126
2.13.9.6 Executing Multiple Cycles.................................................................................... 127
2.13.9.7 Running to a Specific Cycle................................................................................. 127
2.13.9.8 Running to a Label or Microword Address........................................................... 127
2.13.9.9 Running Indefinitely............................................................................................. 127
2.13.9.10 Stopping Execution.............................................................................................. 128
2.13.9.11 Resetting the Simulation...................................................................................... 128
2.13.10 About Breakpoints....................................................................................................... 129

vi Development Tools User’s Guide
Intel®IXP2400/IXP2800 Network Processors
2.13.10.1 Breakpoint Properties Dialog Box........................................................................ 131
2.13.10.2 Setting Breakpoints in Hardware Mode............................................................... 132
2.13.10.3 About Breakpoint Markers................................................................................... 132
2.13.10.4 Inserting and Removing Breakpoints................................................................... 134
2.13.10.5 Enabling and Disabling Breakpoints.................................................................... 135
2.13.10.6 Changing Breakpoint Properties.......................................................................... 135
2.13.10.7 About Multi-Microengine Breakpoint Support...................................................... 135
2.13.11 Displaying Register Contents...................................................................................... 137
2.13.12 Data Watch ................................................................................................................. 138
2.13.12.1 Data Watches in C Thread Windows................................................................... 139
2.13.12.2 Entering a New Data Watch ................................................................................ 139
2.13.12.3 Watching Control and Status Registers and Pins................................................ 140
2.13.12.4 Watching General Purpose and Transfer Registers............................................ 141
2.13.12.5 Deleting a Data Watch......................................................................................... 142
2.13.12.6 Changing a Data Watch ...................................................................................... 143
2.13.12.7 Changing the Data Watch Radix......................................................................... 143
2.13.12.8 Depositing Data................................................................................................... 143
2.13.12.9 Breaking on Data Changes ................................................................................. 143
2.13.13 Memory Watch............................................................................................................ 144
2.13.13.1 Entering a New Memory Watch........................................................................... 145
2.13.13.2 Adding a Memory Watch ..................................................................................... 146
2.13.13.3 Deleting a Memory Watch ................................................................................... 146
2.13.13.4 Changing a Memory Watch................................................................................. 146
2.13.13.5 Changing the Memory Watch Address Radix...................................................... 146
2.13.13.6 Changing the Memory Watch Value Radix.......................................................... 147
2.13.13.7 Depositing Memory Data..................................................................................... 147
2.13.14 Execution Coverage.................................................................................................... 147
2.13.14.1 Changing Execution Count Ranges and Colors.................................................. 149
2.13.14.2 Displaying and Hiding Instruction Addresses...................................................... 149
2.13.14.3 Instruction Markers.............................................................................................. 149
2.13.14.4 Miscellaneous Controls ....................................................................................... 150
2.13.14.5 Scaling the Bar Graph......................................................................................... 150
2.13.14.6 Resetting Execution Counts................................................................................ 150
2.13.15 Performance Statistics................................................................................................ 150
2.13.15.1 Displaying Statistics............................................................................................. 151
2.13.15.2 Resetting Statistics.............................................................................................. 154
2.13.16 Thread and Queue History.......................................................................................... 154
2.13.16.1 Displaying the History Window............................................................................ 156
2.13.16.2 Displaying Queues in the History Window........................................................... 156
2.13.16.3 Hardware Debugging Restrictions....................................................................... 156
2.13.16.4 Scaling the Display.............................................................................................. 156
2.13.16.5 Thread Display Property Page ............................................................................ 157
2.13.16.6 Displaying Code Labels....................................................................................... 157
2.13.16.7 Displaying Reference History .............................................................................. 158
2.13.16.8 Queue History...................................................................................................... 161
2.13.17 Queue Status .............................................................................................................. 162
2.13.17.1 Queue Status History .......................................................................................... 163
2.13.17.2 Setting Queue Breakpoints.................................................................................. 163
2.13.17.3 Changing Thread History Colors ......................................................................... 164
2.13.17.4 Displaying the History Legend............................................................................. 165
2.13.17.5 Tracing Instruction Execution .............................................................................. 165
2.13.17.6 History Collecting................................................................................................. 166
2.13.18 Thread Status.............................................................................................................. 167

Development Tools User’s Guide vii
Intel®IXP2400/IXP2800 Network Processors
2.13.19 Packet Simulation Status............................................................................................ 169
2.14 Running in Batch Mode.................................................................................................. 170
3 Performance Monitoring Unit................................................................................ 173
3.1 Introduction..................................................................................................................... 173
3.2 PMU Limitations ............................................................................................................. 173
3.3 Sampling Modes............................................................................................................. 173
3.3.1 Time Based Sampling................................................................................................. 174
3.3.1.1 Point Sampling..................................................................................................... 174
3.3.1.2 Window Sampling................................................................................................ 175
3.3.2 Random Based, or Statistical Sampling...................................................................... 175
3.4 PMU Graphical User Interface (GUI).............................................................................. 176
3.4.1 Canned Analysis Property Sheet ................................................................................ 177
3.4.2 Sampling Method Property Pages .............................................................................. 178
3.4.2.1 Time Based Sampling (TBS)............................................................................... 178
3.4.2.2 Random Based Sampling (RBS)......................................................................... 181
3.4.3 Sampling Macros Dialog ............................................................................................. 183
3.4.3.1 Monitor Sampling Macro...................................................................................... 184
3.4.3.2 Threshold Sampling Macro.................................................................................. 185
3.4.3.3 Sampling Considerations..................................................................................... 186
3.4.4 Event Selection Dialog Box......................................................................................... 186
3.5 Output Formats...............................................................................................................187
4 Assembler............................................................................................................. 189
4.1 Assembly Process.......................................................................................................... 189
4.1.1 Command Line Arguments ......................................................................................... 189
4.1.2 Assembler Steps......................................................................................................... 191
4.1.3 Case Sensitivity...........................................................................................................192
4.1.4 Assembler Optimizations ............................................................................................ 192
4.1.5 Processor Type and Revision ..................................................................................... 192
5 Microengine C Compiler....................................................................................... 193
5.1 The Command Line........................................................................................................ 193
5.2 Supported Compilations................................................................................................. 193
5.3 Supported Option Switches............................................................................................ 194
5.4 Compiler Steps...............................................................................................................198
5.5 Case Sensitivity.............................................................................................................. 199
6 Linker.................................................................................................................... 201
6.1 About the Linker .............................................................................................................201
6.1.1 Configuration and Data Accessed by the Linker......................................................... 201
6.1.2 Shared Address Update (Flow)................................................................................... 201
6.2 Microengine Image Linker (UCLD)................................................................................. 202
6.2.1 Usage.......................................................................................................................... 202
6.2.2 Command Line Options .............................................................................................. 202
6.3 Generating a Microengine Application............................................................................ 203
6.4 Syntax Definitions...........................................................................................................203
6.4.1 Image Name Definition................................................................................................ 203
6.4.2 Import Variable Definition............................................................................................ 203
6.4.3 Microengine Assignment............................................................................................. 204
6.4.4 Code Entry Point Definition......................................................................................... 204
6.5 Examples........................................................................................................................ 204

viii Development Tools User’s Guide
Intel®IXP2400/IXP2800 Network Processors
6.5.1 Uca Source File (*.uc) Example.................................................................................. 204
6.5.2 Uca Output File (*.list) Example.................................................................................. 205
6.5.3 .map File Example ...................................................................................................... 205
6.6 Memory Segment Usage................................................................................................ 206
6.7 Microcode Object File (UOF) Format ............................................................................. 207
6.7.1 File Header.................................................................................................................. 207
6.7.2 File Chunk Header...................................................................................................... 207
6.7.2.1 UOF Object Header............................................................................................. 207
6.7.2.2 UOF Object Chunk Header ................................................................................. 208
6.7.2.3 UOF_STRT.......................................................................................................... 208
6.7.2.4 UOF_IMEM.......................................................................................................... 208
6.7.2.5 Memory Initialization Value Attributes ................................................................. 209
6.7.2.6 uof_initRegSym................................................................................................... 209
6.7.2.7 UOF_MSEG ........................................................................................................ 209
6.7.2.8 UOF_GTID .......................................................................................................... 210
6.7.2.9 UOF_IMAG.......................................................................................................... 210
6.7.2.10 uof_codePage ..................................................................................................... 211
6.7.2.11 uof_meRegTab.................................................................................................... 211
6.7.2.12 uof_meReg.......................................................................................................... 211
6.7.2.13 uof_neighReg...................................................................................................... 212
6.7.2.14 uof_neighRegTab................................................................................................ 212
6.7.2.15 uof_importExpr .................................................................................................... 212
6.7.2.16 uof_impExprTabTab............................................................................................ 212
6.7.2.17 uof_xferReflectTab .............................................................................................. 212
6.7.2.18 uof_UcVar............................................................................................................ 212
6.7.2.19 uof_ucVarTab...................................................................................................... 212
6.7.2.20 uof_initRegSymTab............................................................................................. 213
6.7.2.21 uof_uwordFixup................................................................................................... 213
6.7.2.22 uof_codeArea ...................................................................................................... 213
6.8 DBG_OBJS .................................................................................................................... 213
6.8.1 Debug Objects Header................................................................................................ 213
6.8.2 Debug Object Chunk Header...................................................................................... 214
6.8.3 DBG_STRT................................................................................................................. 214
6.8.4 dbg_RegTab ............................................................................................................... 214
6.8.5 dbg_LblTab.................................................................................................................214
6.8.6 dbg_SymTab............................................................................................................... 215
6.8.7 dbg_SrcTab.................................................................................................................215
6.8.8 dbg_TypTab................................................................................................................ 215
6.8.9 dbg_ScopeTab............................................................................................................ 215
6.8.10 dbg_Image.................................................................................................................. 215
6.8.11 dbg_Label ................................................................................................................... 216
6.8.12 dbg_Source................................................................................................................. 216
6.8.13 dbg_Symb................................................................................................................... 216
6.8.14 dbg_Type.................................................................................................................... 217
6.8.15 dbg_StructDef.............................................................................................................217
6.8.16 dbg_StructField...........................................................................................................217
6.8.17 dbg_EnumDef............................................................................................................. 217
6.8.18 dbg_EnumValue.......................................................................................................... 218
6.8.19 dbg_Scope.................................................................................................................. 218
6.8.20 dbg_ValueLoc............................................................................................................. 218
6.8.21 dbg_Variable............................................................................................................... 218
6.8.22 dbg_Sloc..................................................................................................................... 219

Development Tools User’s Guide ix
Intel®IXP2400/IXP2800 Network Processors
6.8.23 dbg_Tloc ..................................................................................................................... 219
6.8.24 dbg_RlocTab...............................................................................................................219
6.8.25 dbg_Lmloc................................................................................................................... 219
6.8.26 dbg_Liverange ............................................................................................................ 219
6.8.27 dbg_Range.................................................................................................................. 220
6.8.28 dbg_InstOprnd ............................................................................................................ 220
7 Foreign Model Simulation Extensions.................................................................. 221
7.1 Overview......................................................................................................................... 221
7.2 Integrating Foreign Models with the Transactor............................................................. 222
7.3 Foreign Model Dynamic-Link Library (DLL).................................................................... 223
7.4 Simulating Media Devices.............................................................................................. 223
7.5 Creating A Foreign Model DLL....................................................................................... 223
7.5.1 DLL Sample Code....................................................................................................... 224
8 Transactor ............................................................................................................ 229
8.1 Overview......................................................................................................................... 229
8.2 Invoking the Transactor.................................................................................................. 230
8.3 Transactor Commands................................................................................................... 231
8.3.1 #define ........................................................................................................................ 232
8.3.2 #undef ......................................................................................................................... 233
8.3.3 @................................................................................................................................. 233
8.3.4 benchmark ..................................................................................................................234
8.3.5 cd ................................................................................................................................ 234
8.3.6 close............................................................................................................................ 234
8.3.7 connect........................................................................................................................ 234
8.3.8 deposit......................................................................................................................... 235
8.3.9 dir ................................................................................................................................ 236
8.3.10 examine....................................................................................................................... 236
8.3.11 exit............................................................................................................................... 237
8.3.12 force ............................................................................................................................ 237
8.3.13 foreign_model .............................................................................................................238
8.3.14 go ................................................................................................................................ 239
8.3.15 go_thread.................................................................................................................... 239
8.3.16 gop .............................................................................................................................. 239
8.3.17 goto ............................................................................................................................. 239
8.3.18 goto_addr.................................................................................................................... 240
8.3.19 help ............................................................................................................................. 240
8.3.20 init................................................................................................................................ 241
8.3.21 inst............................................................................................................................... 241
8.3.22 load_ixc....................................................................................................................... 242
8.3.23 log ............................................................................................................................... 242
8.3.24 logical.......................................................................................................................... 242
8.3.25 path ............................................................................................................................. 243
8.3.26 pwd.............................................................................................................................. 243
8.3.27 remove ........................................................................................................................ 243
8.3.28 root_init ....................................................................................................................... 244
8.3.29 set_clock ..................................................................................................................... 244
8.3.30 set_default_go_clk ...................................................................................................... 244
8.3.31 set_default_goto_filter................................................................................................. 244
8.3.32 set_float_threshold...................................................................................................... 245

xDevelopment Tools User’s Guide
Intel®IXP2400/IXP2800 Network Processors
8.3.33 show_clocks................................................................................................................ 245
8.3.34 sim_delete................................................................................................................... 245
8.3.35 sim_reset..................................................................................................................... 246
8.3.36 time ............................................................................................................................. 246
8.3.37 trace............................................................................................................................ 246
8.3.38 type ............................................................................................................................. 247
8.3.39 ubreak......................................................................................................................... 247
8.3.40 unforce........................................................................................................................ 248
8.3.41 version......................................................................................................................... 248
8.3.42 watch........................................................................................................................... 248
8.4 C Interpreter ................................................................................................................... 249
8.4.1 C macros supported.................................................................................................... 250
8.4.2 Supported Data Types................................................................................................ 250
8.5 Simulation Switches ....................................................................................................... 251
8.6 Predefined C Functions.................................................................................................. 252
8.7 Error Handling................................................................................................................ 254
8.8 Printing Statistics from the Transactor ........................................................................... 255
8.8.1 perf_stat_set( )............................................................................................................ 255
8.8.2 perf_stat_print( ).......................................................................................................... 255
9 Simulator APIs ......................................................................................................257
9.1 Foreign Model API.......................................................................................................... 257
9.1.1 FOR_MOD_INITIALIZE .............................................................................................. 257
9.1.2 FOR_MOD_PRE_SIM ................................................................................................ 257
9.1.3 FOR_MOD_POST_SIM.............................................................................................. 257
9.1.4 FOR_MOD_EXIT........................................................................................................ 257
9.1.5 FOR_MOD_RESET.................................................................................................... 258
9.1.6 FOR_MOD_DELETE.................................................................................................. 258
9.2 Overview of XACT API Functions .................................................................................. 258
9.3 State Name Reference Routines.................................................................................... 260
9.3.1 XACT_find_wildcard_state_name............................................................................... 260
9.3.2 XACT_get_handle....................................................................................................... 261
9.3.3 XACT_delete_handle.................................................................................................. 261
9.3.4 XACT_get_state_info.................................................................................................. 261
9.3.5 XACT_get_state_value............................................................................................... 262
9.3.6 XACT_get_state_field................................................................................................. 262
9.3.7 XACT_get_array_state_value..................................................................................... 262
9.3.8 XACT_set_state_value ............................................................................................... 263
9.3.9 XACT_set_state_field ................................................................................................. 263
9.3.10 XACT_set_array_state_value ..................................................................................... 263
9.3.11 XACT_add_sim_state................................................................................................. 263
9.3.12 XACT_HANDLE XACT_alloc_user_sim_state............................................................ 264
9.3.13 XACT_start_of_cycle .................................................................................................. 264
9.3.14 XACT_full_cycle_simulated ........................................................................................ 264
9.3.15 XACT_clock_cycle...................................................................................................... 264
9.3.16 XACT_clock_cycle_with_remainder............................................................................ 265
9.3.17 XACT_get_top_level_inst............................................................................................ 265
9.4 Callback Creation and Deletion Functions ..................................................................... 265
9.4.1 XACT_Define_Callback_Create_Chip ........................................................................ 265
9.4.2 XACT_Define_Callback_Init_Sim ............................................................................... 265

Development Tools User’s Guide xi
Intel®IXP2400/IXP2800 Network Processors
9.4.3 XACT_Define_Callback_Sim_Reset........................................................................... 265
9.4.4 XACT_Define_Callback_Sim_Delete.......................................................................... 266
9.4.5 XACT_Define_Callback_Restore................................................................................ 266
9.4.6 XACT_Define_Callback_Sim_In_Progress................................................................. 266
9.4.7 XACT_Define_Callback_Default_Go_Clock_Domain................................................. 266
9.4.8 XACT_Define_Callback_State_Transition .................................................................. 266
9.4.9 XACT_Define_Cancel_Callback_State_Transition..................................................... 267
9.4.10 XACT_Cancel_State_Transition_Callback.................................................................. 267
9.4.11 XACT_Define_Handle_Invalidation_Callback............................................................. 267
9.4.12 XACT_Define_Callback_Output_Message................................................................. 267
9.4.13 XACT_Define_Callback_Set_Prompt ......................................................................... 267
9.4.14 XACT_Define_Callback_Get_Console_Input ............................................................. 268
9.5 Miscellaneous Functions................................................................................................ 268
9.5.1 XACT_Define_Automatic_Sim_Halt............................................................................ 268
9.5.2 XACT_output_to_console ........................................................................................... 268
9.5.3 XACT_printf................................................................................................................. 268
9.5.4 XACT_printf_error....................................................................................................... 268
9.5.5 XACT_register_console_function................................................................................ 268
9.5.6 XACT_register_console_function_w_arrayed_args.................................................... 269
9.5.7 XACT_unregister_console_function............................................................................ 269
9.5.8 XACT_ExecuteCommandStr ...................................................................................... 269
9.5.9 XACT_init_gui_console............................................................................................... 270
9.5.10 XACT_gui_execute_command ................................................................................... 270
9.5.11 XACT_start_console()................................................................................................. 270
9.5.12 XACT_initialize() .........................................................................................................270
9.5.13 XACT_stop_execution_at_clk..................................................................................... 270
9.5.14 XACT_exit_transactor................................................................................................. 271
9.5.15 XACT_CTRL_C_SWITCH........................................................................................... 271
9.5.16 XACT_stop_execution ................................................................................................ 271
9.5.17 XACT_gui_interface.................................................................................................... 271
A Transactor States .............................................................................................................273
A.1 About States.................................................................................................................... 273
A.1.1 State Definition Format ............................................................................................... 273
A.2 Memory Setup.................................................................................................................273
A.3 Hardware States..............................................................................................................274
A.3.1 Chip Reference ........................................................................................................... 274
A.3.2 SRAM.......................................................................................................................... 274
A.3.3 Scratchpad.................................................................................................................. 274
A.3.4 DRAM.......................................................................................................................... 275
A.3.5 RBUF .......................................................................................................................... 275
A.3.6 TBUF........................................................................................................................... 276
A.3.7 FIFO............................................................................................................................ 276
A.4 Microengine Registers..................................................................................................... 277
A.4.1 Local Memory.............................................................................................................. 277
A.4.2 GPR A bank ................................................................................................................ 277
A.4.3 GPR B bank ................................................................................................................ 278
A.4.4 Transfer Register S In................................................................................................. 278
A.4.5 Transfer Register S Out .............................................................................................. 278
A.4.6 Transfer Register D In................................................................................................. 279

xii Development Tools User’s Guide
Intel®IXP2400/IXP2800 Network Processors
A.4.7 Transfer Register D Out.............................................................................................. 279
A.4.8 Next Neighbor Registers............................................................................................. 280
A.5 CSRs............................................................................................................................... 280
A.6 Intel XScale®Memory Map Access................................................................................. 280
A.7 IXP2400 and IXP2800 Transactor States ....................................................................... 281
A.8 Transactor States for PCI Pins........................................................................................ 285
B Developer Workbench Shortcuts....................................................................................... 289
B.1 Introduction...................................................................................................................... 289
C Intel XScale® Core Memory Bus Functional Model .......................................................... 295
C.1 Summary of APIs ............................................................................................................ 295
C.1.1 XACT_IO API.............................................................................................................. 296
C.1.2 simRead32 / simWrite32............................................................................................. 296
C.1.3 simIntConnect / simIntEnable / simIntDisable
cmbIntConnect/cmbIntEnable/cmbIntDisable............................................................. 296
C.1.4 simIntEnableIRQ / simIntEnableFIQ / simIntDisableIRQ /
simIntDisableFIQcmbIntEnableIRQ / cmbIntEnableFIQ / cmbIntDisableIRQ /
cmbIntDisableFIQ ....................................................................................................... 297
C.1.5 IS_CMB_ADDR_RESERVED / IS_CMB_INT_RESERVED....................................... 297
C.1.6 Additional CMB_IO API............................................................................................... 298
C.1.7 cmbRead32 / cmbWrite32........................................................................................... 298
C.1.8 cmbSetCb ...................................................................................................................299
C.1.9 cmbSwapRead32 / cmbSwapWrite32......................................................................... 299
C.1.10 cmbBFMRead32 / cmbBFMWrite32 ........................................................................... 300
C.2 ENUMs............................................................................................................................ 301
C.3 Defines ............................................................................................................................ 301
D PCI Bus Functional Model................................................................................................. 303
D.1 Loading the BFM............................................................................................................. 303
D.2 Initializing the BFM.......................................................................................................... 303
D.3 Creating a Device............................................................................................................303
D.4 Calling Console Functions from Another Foreign Model................................................. 304
D.5 Setting a Callback Function............................................................................................. 304
D.6 Header file pciconfx.h...................................................................................................... 304
E SPI4 Bus Functional Model ............................................................................................... 311
E.1 Overview ......................................................................................................................... 311
E.2 SPI4 BFM Help................................................................................................................311
E.3 Console Functions........................................................................................................... 312
E.3.1 Device/Port Configuration........................................................................................... 312
E.3.1.1spi4_define_device.......................................................................................... 312
E.3.1.2spi4_set_device_X_param/spi4_set_port_X_param....................................... 313
E.3.1.3spi4_create_device.......................................................................................... 314
E.3.1.4spi4_connect_device....................................................................................... 314
E.3.1.5spi4_enable_X................................................................................................. 314
E.3.2 Simulation Control....................................................................................................... 315
E.3.2.1spi4_set_X_stop_control ................................................................................. 315
E.3.2.2spi4_set_sim_options...................................................................................... 315
E.3.3 Flow Control................................................................................................................ 316
E.3.3.1spi4_set_rx_fc_info/spi4_set_tx_fc_info/spi4_set_rx_calendar/
spi4_set_tx_calendar.................................................................................................. 316

Development Tools User’s Guide xiii
Intel®IXP2400/IXP2800 Network Processors
E.3.4 Statistical Information Access ..................................................................................... 317
E.3.4.1spi4_get_receive_stats_X/spi4_get_transmit_stats_X .................................... 317
E.3.4.2spi4_get_rx_buffer_byte/ spi4_get_tx_buffer_byte and
spi4_get_rx_buffer_int32/spi4_get_tx_buffer_int32 .................................................... 318
E.3.4.3spi4_get_rx_clock_cycle/spi4_get_tx_cycle_count.......................................... 319
E.3.4.4spi4_reset_stat ................................................................................................ 319
E.3.4.5spi4_version..................................................................................................... 319
E.4 C-API............................................................................................................................... 319
Figures
1 The Developer Workbench GUI..........................................................................20
2 Floating Window, Tool Bar, and Menu Bar..........................................................21
3 Specify Debug-only UOF Files Dialog Box..........................................................28
4 Configure Tabs Dialog Box .................................................................................37
5 Go To Line Dialog Box........................................................................................37
6 Clock Frequencies for the IXP2400.....................................................................59
7 IXP2400 Memory Options...................................................................................60
8 IXP2400 MSF Device Configuration....................................................................61
9 The Create Media Bus Device Dialog Box for CSIX ...........................................62
10 The Create Media Bus Device Dialog Box for x32MPHY16................................63
11 Port Characteristics Edit Port Dialog Box............................................................65
12 Network Connections Property Page - IXP2400.................................................66
13 CBUS Connections Property Page - IXP2400 ....................................................67
14 Clock Frequencies for the IXP2800.....................................................................69
15 IXP2800 Memory Options...................................................................................70
16 IXP2800 MSF Devices........................................................................................71
17 The Create Media Bus Device Dialog Box for SPI-4...........................................72
18 The Create Media Bus Device Dialog Box for CSIX ...........................................73
19 Port Characteristics Edit Port Dialog Box............................................................75
20 Network Connections Property Page - IXP2800.................................................76
21 CBUS Connections Property Page - IXP2800 ....................................................77
22 Packet Simulation Options Property Sheet- General Tab...................................79
23 Packet Simulation Options Dialog Box (IXP2400 and IXP2800) - Traffic
Interface Logging.................................................................................................81
24 Packet Simulation Options (IXP2400 IXP2800) - Stop Control Tab....................82
25 Packet Simulation Options (IXP2400 and IXP2800) - The Traffic Assignment
Tab......................................................................................................................84
26 Assign Input to Port - DataStreams.....................................................................85
27 Assign Input to Port - Network Traffic..................................................................85
28 Assign Output from Port......................................................................................87
29 Manage NTS Plug-ins Property Page.................................................................88
30 Define Network Traffic - Data Stream Dialog Box...............................................91
31 Create Stream Pop-up ........................................................................................91
32 Marking Instructions for the Network Processor................................................109
33 Using Imported Variable Data at Startup in Simulation Mode...........................112
34 Using Imported Variable Data at Startup in Hardware Mode............................112
35 The Assembler Thread Window........................................................................117
36 The Compiled Thread Window..........................................................................118

xiv Development Tools User’s Guide
Intel®IXP2400/IXP2800 Network Processors
37 Expanding Macros ............................................................................................121
38 Inline Function Breakpoints in Source and List Views ......................................130
39 Breakpoint Properties Dialog Box.....................................................................131
40 Multi-Microengine Breakpoint Dialog Box .........................................................137
41 The Execution Coverage Window.....................................................................148
42 Performance Statistics - Summary Tab ............................................................151
43 Save Packet Simulation Stats to a File.............................................................152
44 Performance Statistics - MicroengineTab .........................................................153
45 Performance Statistics - All Tab........................................................................154
46 History Window .................................................................................................155
47 Queue Display Property Sheet..........................................................................156
48 Display Threads Property Page ........................................................................157
49 Customize History.............................................................................................161
50 Queue Status Window ......................................................................................162
51 History Dialog Box.............................................................................................167
52 The Thread Status Window...............................................................................168
53 Packet Simulation Status Debug Window.........................................................169
54 Save Packet Simulation Stats to a File.............................................................170
55 TBS Point Sampling..........................................................................................174
56 TBS Window Sampling .....................................................................................175
57 Random Based Sampling .................................................................................175
58 Canned Analysis Property Page .......................................................................177
59 Time-Based Sampling Property Page...............................................................179
60 Random Based Sampling Property Page .........................................................181
61 Sampling Macros .............................................................................................183
62 Monitor Sampling Macro...................................................................................184
63 Threshold Sampling Macro ...............................................................................185
64 Event Selection Dialog Box...............................................................................187
65 Assembly Process.............................................................................................191
66 Compilation Steps.............................................................................................198
67 Example of Foreign Model Usage.....................................................................221
Tables
1 Simulation and Hardware Mode Features.........................................................105
2 Instruction Markers............................................................................................123
3 Canned Analysis Property Page Entries and Buttons.......................................177
4 TBS Property Page Entries and Buttons...........................................................179
5 RBS Property Page Entries and Buttons ..........................................................181
6 Monitor Sampling Macro Dialog Box.................................................................184
7 Threshold Sampling Macro Dialog Box.............................................................185
8 Supported uccl CLI Option Switches.................................................................194
9 Linker Command Line Options..........................................................................202
10 Transactor Optional Switches ...........................................................................231
11 Transactor Command ......................................................................................231
12 XACT API Functions .........................................................................................258
1 IXP2400 Transactor States for QDR and MSF Pins .........................................281
2 IXP2800 Transactor States for QDR and MSF Pins .........................................283

Development Tools User’s Guide xv
Intel®IXP2400/IXP2800 Network Processors
3 IXP2400 Transactor States for PCI PIns...........................................................285
4 IXP2800 Transactor States for PCI PIns...........................................................287
5 Developer Workbench Shortcuts—Files ...........................................................289
6 Developer Workbench Shortcuts—Projects.....................................................290
7 Developer Workbench Shortcuts—Edit............................................................290
8 Developer Workbench Shortcuts—Bookmarks.................................................291
9 Developer Workbench Shortcuts—Breakpoints...............................................291
10 Developer Workbench Shortcuts—Builds........................................................292
11 Developer Workbench Shortcuts—Debug .......................................................292
12 Developer Workbench Shortcuts—Run Control...............................................292
13 Developer Workbench Shortcuts—View..........................................................293

Developer’s Manual 17
Introduction 1
1.1 About this Document
This manual is a reference for network processor development tools and is organized as follows:
•Chapter 2, “Developer Workbench” - Describes the Workbench and its graphical user interface
(GUI).
•Chapter 3, “Performance Monitoring Unit” - Describes the Performance Monitoring Unit
(PMU)
•Chapter 4, “Assembler” - Describes how to run the Assembler.
•Chapter 5, “Microengine C Compiler” - Describes how to run the Microengine C Compiler.
•Chapter 6, “Linker” - Describes how to run the Linker.
•Chapter 7, “Foreign Model Simulation Extensions” - Provides information on interfacing the
Network Processor to foreign models.
•Chapter 8, “Transactor” - Describes the Transactor and its commands.
•Chapter 9, “Simulator APIs” - Desribes the Simulation APIs.
•Appendix A, “Transactor States” - Describes the Transactor internal states.
•Appendix B, “Developer Workbench Shortcuts” - Contains a listing and description of
commonly used shortcuts.
•Appendix C, “Intel XScale® Core Memory Bus Functional Model” - Describes the Intel
XScaleBus Functional Model.
•Appendix D, “PCI Bus Functional Model” - Describes the PCI Bus Functional Model.
•Appendix E, “SPI4 Bus Functional Model” - Describes the SPI4 Bus Functional Model.
1.2 Intended Audience
The intended audience for this book is Developers and Systems Programmers.
1.3 Related Documents
Further information on the network processors is available in the following documents:
Intel IXP2400/IXP2800 Network Processor Programmer’s Reference Manual—Contains detailed
programming information for designers.
Intel IXP2800 Network Processor Datasheet—Contains summary information on the IXP2800
Network Processor including a functional description, signal descriptions, electrical specifications,
and mechanical specifications.

18 Developer’sManual
IXP2400/IXP2800 Network Processors
Introduction
Intel IXP2400 Network Processor Datasheet—Contains summary information on the IXP2400
Network Processor including a functional description, signal descriptions, electrical specifications,
and mechanical specifications.
Intel Intel IXP2400/IXP2800 Microengine C Compiler LIBC Library Reference Manual -
Contains a modified subset of standard C Library functions supported on the IXP2400 and
IXP2800 Network Processors
Intel IXP2400 Network Processor Hardware Reference Manual -Contains detailed hardware
technical information about the IXP2400 Network Processor for designers.
Intel IXP2800 Network Processor Hardware Reference Manual - Contains detailed hardware
technical information about the IXP2800 Network Processor for designers.

Development Tools User’s Manual 19
Developer Workbench 2
2.1 Overview
The Developer Workbench is an integrated development environment for assembling, compiling,
linking, and debugging microcode that runs on the IXP2400 and IXP2800 Network Processor
Microengines.
Features:
Important Workbench features include:
•Source level debugging.
•Debug-only project creation mode.
•Execution history.
•Statistics.
•Media Bus device and network traffic simulation for the Network Processors
•Command line interface to the Network Processor simulators (Transactors).
•Customizable graphical user interface (GUI) components.
Debugging Support:
The Workbench supports debugging in four different configurations:
•Local simulation with no foreign model, in which the Workbench and the Network
Processor simulator (Transactor) both run on the same Microsoft Windows* platform.
•Local simulation with local foreign models, in which the Workbench, the Transactor, and
one or more foreign model Dynamic-Link Libraries all run on the same Windows platform.
•Local simulation with a remote foreign model, in which the Workbench and the Transactor
both run on the same Windows platform and communicate over the network with a foreign
model running on a remote system.
•Hardware, in which the Workbench runs on a Windows host and communicates over a
network or a serial port with a subsystem containing actual Network Processors.
Getting Help:
You can get help about the Developer Workbench and the Network Processors in several ways:
•On the Help menu, click Help Topics. This opens the Developer Workbench online help tool.
•In the Project Workspace window (see Figure 1), click the InfoView tab. This give you
access to documentation installed along with the Software Development Kit (SDK). See
Section 2.4.3, “About InfoView.”
•On the Web, go to http://developer.intel.com/design/network/products/npfamily/index.htm to
get more information about Intel products.

20 DevelopmentTools User’sManual
IXP2400/IXP2800 Network Processors
Developer Workbench
Developer Workbench Revision Information:
To determine the revision:
•On the Help menu, click About Developer Workbench.
The About Developer Workbench information box appears displaying the revision of your
Developer Workbench.
2.2 About the Graphical User Interface (GUI)
The Workbench GUI (Figure 1) conforms to the standard Windows look and feel. You can do the
following:
•Dock and undock (float) windows, menu bars, and toolbars (see Section 2.2.1).
•Hide and show windows and toolbars (see Section 2.2.2).
•Customize toolbars and menu bars (see Section 2.2.3).
•Save and restore GUI customizations (see Section 2.2.3.6).
2.2.1 About Windows, Toolbars, and Menus
Dockable windows contain controls and data. You can attach them to a location on the Workbench
main window or you can float them over the main window. All toolbars and menu bars are
dockable. (See Figure 2.)
To float, or undock, a window or toolbar, double-click its gripper bar (see Figure 1). To restore it to
its previously docked location, double-click its title bar. You can also drag the window to a new
docking location.
Figure 1. The Developer Workbench GUI
Toolbar
Title Bar
Minimize
Maximize
Close
Project Workspace Window
View/Edit Area
Output Window
Menu Bar
Gripper Bar
Run Control Window Command Line Window