Development Overview Tutorial 1 of 11

Microcode Development and Debug

Overview & Tutorial
Development and Debug of Microcode for the IXP1200
Microengines using the GUI Developers Workbench
Revision 0.2
November 2000
Development Overview Tutorial 2 of 11
Introduction
The IXP1200 Network Processor contains seven processors one StrongARM Core and six programmable
RISC Microengines. These Microengines provide the packet processing power behind the IXP1200 and are
programmed using a set of instructions in the form of microcode. These instructions are detailed in the IXP1200
Programmers Reference Manual. Each Microengine supports up to four program threads, or contexts, to
maximize processing capability while minimizing power and die space.
Note: The IXP1200 documentation refers to the Microengine code as microcode, however, this can
be misleading. The term symbolic code more aptly describes the code used.
Since this instruction set is unique to the IXP1200, the following questions can be asked:
How does one develop software for the IXP1200 using the microcode instructions?
Once one writes this code, how can it be verified and debugged?
Intel provides a powerful simulator, called the Transactor, that can be used to develop code for the Microengines
long before silicon or boards are available. The Transactor has a GUI front end called the Developers
Workbench, which allows a detailed view into the workings of the code and the chip. (The Developers
Workbench can also be used as a GUI interface to hardware, such as Intels Ethernet Evaluation System.) The
Transactor is a cycle, data accurate model of the IXP1200, which means that what is seen occurring in the
Transactor is what will be seen in the silicon. This, along with debug libraries provided by Intel, makes it a
powerful development and debugging tool.
Note: The only functionality not modeled by the Transactor is SDRAM refresh. Otherwise, all pins,
registers, and internal states are cycle and data accurate.
Development for the StrongARM Core is done separately using an industry standard toolkit such as WindRivers
Tornado 2.0 or the latest version of the ARM Software Development Kit. Once compiled into a binary file, this
code can be included in simulation on the Transactor. By default, the Developers Workbench will initialize the
chip in simulation, freeing the Microcode programmer from needing StrongARM Core code to do the initial
boot.
The Transactor, Workbench, and other IXP1200 software are provided to customers on the IXP1200 Developers
CD. This CD includes:
Transactor
Developers Workbench (GUI)
Software Reference Designs for Ethernet switching
StrongARM Core boot code
Route Table Manager
Drivers for IXF440 Octal MAC and IXF1002 Dual-port Gigabit MAC
Code and a GUI interface for the generation of packets in simulation
Schematics for hardware evaluation system
Hardware support
VxWorks BSP
Documentation for the IXP1200, IXF1002, IXF440, and IXB3208
There is much more on the Developers CD, but the above list gives an idea of the extent of information provided
to assist customers in their designs.
Development Overview Tutorial 3 of 11
Tutorial
Installation
The first step in developing code for the IXP1200 Microengines is to install the contents of the Developers CD
onto the users system. The required operating system is Windows NT running on a medium to high-end PC
with a CD-ROM. Once the CD is inserted, an interface will start automatically, giving the user the option to
install the software, look at the documentation, go to the learning center, etc.
Note: When installing, it is recommended that the user install the software in a new directory. This
will prevent any issues resulting from changed tree structures. The user can first remove the old version
by going to Add/Remove Programs on their PC. Also, because a new directory is used for each
installation, it is recommended that any files created by the user reside in a unique directory. This will
prevent the accidental deletion or overwriting of such files.
When installing, the full installation is recommended, including all of the code and libraries. (This is the
default.) Once the contents of the CD are installed, the CD is not necessary to run any simulations.
Getting Started
The first step in familiarizing oneself with the microcode development and debug environment is to open the
Developers Workbench, which is the GUI interface to either the Transactor or hardware. This can be done from
the Start menu.
Start -> Programs -> IXP1200 -> Developer Workbench
Notice that there are also links to a large amount of documentation including the release notes and a readme file
as well as the hardware schematics for our evaluation and validation boards.
The Workbench window includes several different windows or partitions, which can change whether its in
development or debug mode. Development mode is used to write or edit microcode and to alter any simulation
or hardware settings. In debug mode, debug libraries allow visibility into the chip and the Workbench provides
the resulting information in a useful, easy-to-read format.
The Workbench uses the notion of a project. A project is the top level of the design and consists of the
microcode files, script files, and any settings that are required. For example, microcode can be hierarchical and
partitioned into many separate files. A project keeps track of all of the microcode files that are run on the same
IXP1200 system. Therefore, rather than opening all of the appropriate files and altering the settings every time a
user returns to the Workbench, he/she only needs to open a project. When starting a new project, the user can
configure the project name, where the project files reside, the number of IXP1200s in the system and their
names, and which version of the chip is being used. The two versions available for simulation are the IXP1200
B0 part that runs at 166 or 200 MHz and has 1k control stores or Yarmouth (C0) that runs at 166, 200 or 232
MHz and has 2k control stores. The file extension for a project is .dwp Developers Workbench Project.
File -> New Project
Once the project is created, the user can create microcode, script, header or text files (or use existing files) to add
to the project. These files are not automatically part of the open project, they must be explicitly added. This
allows a user to view other code that is not part of the working project.
File -> New
Project -> Insert Microcode Files
Project -> Insert Script Files
Development Overview Tutorial 4 of 11
The following screen shows the Workbench in development mode. The Project Workspace window is on the
right and shows all of the microcode and script files associated with the current open project. By double clicking
on a filename, the contents of the file are shown on the left and can be edited. In the screen below, the Receive
microcode top-level file, rec.uc, is open.
An important part of setting up a simulation is configuring the system to look the same as the hardware system
will. This includes configuring the IX Bus interface, the SRAM and SDRAM interfaces, the PCI interface,
setting the bus frequencies, and determining whether or not the IXB3208 Bus Scaling Fabric device should be
included in the simulation.
Project -> System Configuration
By setting up the appropriate system configuration parameters, the Workbench can properly configure the
IXP1200 in debug mode to allow for accurate simulations.
Note: When the StrongARM Core is enabled in the simulation and boot code is provided, the
StrongARM Core will configure the system, overriding the Developers Workbench. In this situation, it
is not necessary to set the system configuration paramaters in the Workbench.
Development Overview Tutorial 5 of 11
Working with Reference Design Projects
The Developers CD installation contains several software reference designs in the form of projects. These can
be used with either the Transactor (for simulation) or the hardware. The Ethernet packet forwarding reference
design projects are:
Name Description
pfwd12.dwp 12 100 Mbps ports , L2/L3 processing
pfwd16.dwp 16 100 Mbps ports, L2/L3 processing
pfwd8_1f.dwp
8 100 Mbps ports and 1 Gigabit (fast) port, L2/L3
processing
pfwd8_1f_rx16_tx6.dwp
8 100 Mbps ports and 1 Gigabit (fast) port, L2/L3
processing. Uses 16 receive threads (no rx
scheduler) and 6 transmit threads
L2L3fwd16.dwp
16 100 Mbps ports, L2/L3 processing. Utilizes
macros.
L3fwd16.dwp 16 100 Mbps ports, L3 processing. Utilizes macros.
L3fwd2f.dwp 2 Gigabit ports, L3 processing. Utilizes macros.
They are provided with the Developers CD and can be used for reference. In addition, customers may freely
leverage any of the reference code for their designs, as stated in the license agreement thats part of the
Developer CD installation. The projects are located in a microcode directory.
File -> Open Project
Navigate to: /IXP1200/MicroCode/workbench_projects/
Choose appropriate reference design.
The source files, script files, and macros associated with the project are shown in the Project Workspace
window. If the window is not visible, the user can view it by going to:
View -> Project Workspace
There are settings that must be configured for a project. These settings include specifying which code runs in
which Microengines and whether the assembler will optimize the microcode. It is recommended that the
optimization always be used in order to minimize any branch and swap latencies in the microcode. The build
settings can also determine which version of the chip the code should be built for. The user selects a minimum
and maximum revision. The build settings should be set before the project code is built.
Build -> Settings
Once all of the code and script files are in place and the build settings are correct, the code is built and a loadable
image is created to run on the Transactor. During the build, the assembler will flag any errors or warnings in the
code.
Build -> Build
Once the code is built with no erros, the next step is to debug this code, whether it is on the Transactor or actual
hardware. This document focuses on simulation using the Workbench with the Transactor.
Simulation and Debugging Set-Up
The most powerful aspect of the IXP1200 development environment is its simulation and debugging capability.
Detailed information on the debug library can be found in the IXP1200 Software Reference Manual.
Development Overview Tutorial 6 of 11
The Developers Workbench can be used to debug microcode both in the simulation environment and the actual
hardware, such as the IXP1200 Ethernet Evaluation System. The target is chosen via the debug menu, and
options can be set accordingly.
Debug -> Simulation - or - Debug -> Hardware
Simulation -> Options Hardware -> Options
In a simulation, these options allow the user to view various pipeline stages, change default colors, tag memory
locations, choose between stepping via the Core clock or the IX Bus clock, allow the Workbench to do
initialization, add foreign models, collect history, enable the StrongARM Core or PCI Unit, enable the IX Bus
Device Simulator, etc. For hardware, the options set how the connection to hardware is made, if microcode is
loaded before debugging, and which ports stop when the Microengines stop.
Note: The foreign model option allows a user to connect an external model, such as a remote Verilog
model for an ASIC, to the IX Bus and simulate that model along with the IXP1200. This is extremely
useful in developing slave devices for the IX Bus. It is also used to connect a local foreign model, such
as Intels route table manager and packet generator (rtm_dll.dll).
Once the code is built and the options are set, debugging can begin.
Debug -> Start Debugging
It may take several seconds for the debug mode to start. During this time, the IXP1200 is being initialized based
on the system configuration and any start-up scripts, and the microcode is being downloaded to the
Microengines control stores. When finished, the simulation will be initialized and ready to simulate cycles for
debug, optimization, and performance characterization.
When debugging starts, various debug windows may or may not open in the Workbench interface, depending on
which were open when the project was last debugged. Debug windows can be displayed or hidden by using the
View menu options.
View -> Debug Windows -> (choose appropriate window)
By double clicking on the Thread tab in the Project Workspace window, the user can see the assembled code
used in each Microengine thread. When simulating, this window also shows which thread is currently running as
well as the different stages of the instruction pipeline on each Microengine. Note that the microword address can
be displayed by right-clicking in the code window and choosing Display Microword Address. This is a quick
way to see how much code is used in that Microengine. For example, the receive code running in Microengine 0
for the pfwd8_1f_rx16_tx6 reference design uses 621 instructions out of the available 1k instructions in the
control store.
Simulation and Debugging Options
At this point, the microcode can be simulated on the Transactor in order to confirm behavior, debug, examine
performance, and do any necessary optimization. The first step would be to simulate a number of cycles. One
way this is done is using the Run Control window, where the simulation can be stepped on a cycle basis, for a
specified number of cycles or to a specific cycle count, or indefinitely until stop is clicked. For example, to
run for 2000 cycles:
Run Control window: Go for 2000 cycles
Development Overview Tutorial 7 of 11
One of the debug windows is the History window. This window shows all of the Microengine threads and their
status of execution during the simulation as well as the fullness of the Microengine command queues in the
memory units. Each thread can be executing, aborting, idle, or stalled. Memory references can also be displayed
to show each step of the reference event for SRAM, SDRAM and FBI memory references. In addition, any
labels in the microcode can be displayed in order for the user to easily determine what is happening in the
microcode at that point in time. The display the memory references and labels, right click the mouse on the
appropriate thread name in the History window and choose the appropriate option.
The following screen shows the History window with memory references and labels displayed only for the first
thread in the first Microengine.
Development Overview Tutorial 8 of 11
The History window also has an option to show the queue fullness for the optimizing queues in the SRAM and
SDRAM Controllers. At a glance, the user can scroll through the simulated cycles and determine if the queues
have neared the maximum entry amount. The fullness bars will turn red when the queues are reaching their
maximum number of entries.
Development Overview Tutorial 9 of 11
The user can also look at the statistics for the memory queues and other IXP1200 internals when debugging.
Debug -> Statistics
For example, the following screen shows statistics for the SRAM Order Queue. This queue is 16 entries deep
and the statistics show the maximum number of entries that have been reached in the queue as well as the
percentage of simulation time where each number of entries occurred.
Development Overview Tutorial 10 of 11
Another debug feature is the use of breakpoints. By placing one or more breakpoints in the code, the user can
run the simulation until the breakpoint is reached. At this point, the simulation is automatically stopped and an
information message is given, as shown in the screen below.
The debug libraries also give the customer other debug capability.
First, data watches may be set on registers, internal signals and pins. The Data Watch window can also be used
to change the values on the fly.
Debug -> Data Watch -> Add Watch
Second, by right clicking on a thread in the History window, the user can choose whether or not to display
references and labels, open the code associated with that thread, or go to the instruction at the point in the history
window where the mouse was clicked.
Third, a simulation can be saved and restored at a later point in time. This maintains the current state, making it
unnecessary for a user to recreate the simulation to that point when they return to the Workbench.
Debug -> Simulation State -> Save
Debug -> Simulation State -> Restore
Development Overview Tutorial 11 of 11
Finally, there are many other features assist in debugging. These include the ability to go to the source code
from the thread history window, to display the microword addresses for each threads code, and to see the value
of a register in the thread window by positioning the mouse pointer over it.
Benchmarking Performance
The example software provided with the reference designs has built-in code to allow for benchmarking of the
performance of the IXP1200. There are three main functions defined.
run_receives(#);
run_transmits(#);
calc_rate(#);
Note: For each function, the # sign should be replaced with a number.
The run_receives function will run the full simulation (receives, processing, enqueuing and transmitting) until
the specified number of packets has been received. The run_transmit function works the same way but counts
the number of transmitted packets rather than ones that are received. The calc_rate function gives the packet
receipt rate when used with run_receives and the packet transmission rate when used with run_transmits. The
following example shows how to calculate the reception rate.
run_receives(1000);
calc_rate(1000);
The returned value is in packets per second. Because the Transactor is a cycle, data accurate model, the results
are actual performance benchmarks.
Summary
The IXP1200 Microengine threads are programmed using a microcode instruction set tuned for packet
processing. The microcode can be developed using the Developers Workbench provided by Intel, where the
Workbench is the GUI front end to the simulation environment or the hardware. By using the cycle and data
accurate Transactor for simulation, a customer can develop, simulate, and debug the microcode before running it
on actual silicon, thereby greatly decreasing hardware debug time. Intel provides example code, drivers, and all
other necessary software to get users up and running with our reference designs, any part of which may be
leveraged for a customers own system design. In addition, the Transactor supports hooks that allow the
connection of an ASIC model to the IX Bus in order to debug the interface between the IXP1200 and the slave
device.
Once the microcode is written and debugged via the Transactor, the GUI Workbench can also interface over an
Ethernet or serial connection to actual hardware, allowing many of the same debug capabilities to be performed.
All of these things contribute to the ease of development and debug on the IXP1200.