Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Summary
Application Note AP0166 (v1.0) September 05, 2008

This document takes a look at the range of tools available to aide in the debugging of your embedded intelligence the FPGA design itself and any embedded program code required by processors within that design.

Debugging is the act of testing your hardware design and any embedded software (running on 'soft' processors therein), to obtain the desired (correct) performance and functionality. Debugging is an important element of the overall design strategy, and effective debugging can save a lot of time and money when it comes time to deploy your end design in the field. This document takes a look at the various debugging tools available within Altium Designer.

Virtual Instrumentation
In Altium Designer, debugging of hardware is provided courtesy of 'virtual' instrument components which are 'wired' into the actual FPGA design but which, on programming the physical device, offer software-based controls for interrogation and control of nodes within the design. Imagine being able to walk around inside the physical FPGA device, armed with your favorite test instruments, and you'll have some idea of what these instruments can offer as part of a 'live' debugging environment. Virtual instruments are placed from the \Library\Fpga\FPGA Instruments.IntLib library. How do I use instruments in my FPGA design? this video looks at the use of embedded instruments in an FPGA design.

Accessing Virtual Instruments at Runtime

Before looking at the instruments themselves, it is worth taking the time to see how instruments are accessed from within Altium Designer and the underlying communications scheme that makes this possible. Communications from the Altium Designer software environment to embedded processors and virtual instruments in an FPGA design, is carried out over a JTAG communications link. This is referred to on the Desktop NanoBoard NB2DSK01 as the Soft JTAG (or Nexus) chain. Within Altium Designer, such devices included in the chain are presented in the Devices view (View Devices View) as part of the Soft Devices chain (the bottom-most chain in the view), as shown in Figure 1.

Figure 1. Example virtual instruments appearing in the Soft Devices chain of the Devices view.

Note: The Soft Devices chain only becomes populated with the Nexus-enabled devices for a design, once that design has been programmed into the target device.
AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence The interface for a virtual instrument is accessed by double-clicking on the corresponding icon for it. Doing so will give access to its associated instrument panel (Figure 2). Use the panel to interactively debug your design as required.

Figure 2. Example of a virtual instrument's associated panel, which provides the necessary controls to actively debug your design.

For information on working in the Devices view, refer to the document AP0103 Processing the Captured FPGA Design. How do I build an FPGA design? this video looks at processing a design from within the Devices view and running it on some target hardware.

Enabling the Soft Devices JTAG Chain

The Soft JTAG chain signals (NEXUS_TMS, NEXUS_TCK, NEXUS_TDI and NEXUS_TDO) are derived in the NB2DSK01's NanoTalk Controller (Xilinx Spartan-3). As part of the communications chain, these signals are wired to four pins of the daughter board FPGA. To interface to these pins, you need to place the NEXUS_JTAG_CONNECTOR design interface component (Figure 3). This can be found in the FPGA NB2DSK01 Port-Plugin Figure 3. Nexus JTAG Connector. integrated library (\Library\Fpga\FPGA NB2DSK01 Port-Plugin.IntLib). This component 'brings' the Soft JTAG chain into the design. In order to wire all relevant Nexus-enabled devices (processors, virtual instruments) into this chain, you need to also place a NEXUS_JTAG_PORT component (Figure 4), and connect this directly to the NEXUS_JTAG_CONNECTOR (Figure 5). This component can be found in the FPGA Generic integrated library (\Library\Fpga\FPGA Generic.IntLib). The presence of the NEXUS_JTAG_PORT component instructs the software to wire all components that possess the parameter NEXUS_JTAG_DEVICE=True into the Soft JTAG chain.
Figure 4. Nexus JTAG Port.

Figure 5. Connecting JTAG devices into the Soft JTAG chain.

For information on the JTAG communications, refer to the document AR0130 PC to NanoBoard Communications. How do I hook up the JTAG chains in my target system? this video looks at how the JTAG communications protocol is used with FPGAs and how you can take advantage of Altium Designer's LiveDesign debugging features in a target system on your production or third party development board.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Custom Instrument
The Custom Instrument component is a fully-customizable 'virtual' instrument with which to monitor and control signals within an FPGA design. As part of the instrument's configuration you are able to create your own GUI the interface that is seen once the design is programmed into the target device and the instrument is accessed. A palette of standard components and instrument controls enable you to quickly construct the instrument panel, while various properties associated with a control allow you to make fine-tuning adjustments.

Figure 6. Example Custom Instrument.

Defined IO signals, wired to the instrument on the schematic, can be hooked up directly to the various controls in your custom GUI, or you can write your own DelphiScript code to process IO as required. Scripts can be fired whenever the instrument polls, and in relation to specified events. One of the key features of this particular virtual instrument is that its configuration can be downloaded with the FPGA design and stored within the target physical device (in Block RAM). This allows for interaction with the design, through use of the Custom Instrument, directly in the field particularly attractive to Field Service Engineers! Configuration of the instrument is carried out using the Custom Instrument Configuration dialog (Figure 7).

Figure 7. Customize the look and feel of your Custom Instrument through the various tabs of its associated configuration dialog. The Signals tab allows you to define base instrument options, including specification of the configuration file and how it is retrieved by Altium Designer. The Design tab provides the canvas with which to create the customized GUI used to interact with the instrument at run-time. The Code tab offers an area in which to write any underlying script code used, for example, in the processing of instrument IO.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence Figure 8 illustrates an example of the run-time panel for this instrument, accessed by double-clicking on the icon for the instrument, in the Soft Devices chain of the Devices view.

Figure 8. Example instrument panel for the Custom Instrument.

Features at-a-glance
Fully customizable with configuration information stored in a separate .Instrument file Supports any number of input and output signals Customizable naming of signals Each signal can be configured to any number of bits Ability to set initial value for each output signal Defined signals can be reordered, graphically, as required

Customizable title for the instrument's panel Ability to use customized bitmap to represent instrument in the Devices view Configuration information can be retrieved from one of two locations: From Project: Configuration information retrieved from .Instrument file. FPGA project must be open From FPGA: Configuration information is downloaded with the design to the physical device, and stored in Block RAM. It is retrieved directly from here and the project need not be open Palette panel: offering a range of standard scripting components and instrument-specific controls Properties panel: for fine-tuning the presentation and/or functionality of form objects Events panel: for hooking-up script procedures or functions to form objects Within a dedicated coding tab as part of the instrument's configuration dialog Within a code-aware editor inside Altium Designer

Design form for creating instrument GUI with three dedicated panels: -

Supports use of scripting (DelphiScript), for example to manipulate signal IO to a greater degree. Script can be written: -

Ability to hook signal IO to required instrument controls either directly or through use of scripting OnReadWrite event for instrument panel form hard coded to 'fire' each time the instrument polls, allowing the synchronous calling of code which can process signal values at each poll point Provision of special global function SignalManager, which provides access to signals within a given Custom Instrument. This function allows you to easily get and set values for signals as part of your script functions. Can be accessed 'in the field' using the Viewer Edition of Altium Designer For more detailed information on this instrument, refer to the document TR0176 Custom Instrument Reference. For a tutorial that looks at using the Custom Instrument in an FPGA design, involving monitoring of input signals directly and control of output signals using scripting, refer to the document TU0135 Adding Custom Instrumentation to an FPGA Design.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Logic Analyzer
The configurable Logic Analyzer instrument is capable of supporting 8-, 16, 32- or 64-bit capture. The instrument can be configured to use predefined internal storage memories for captured data, or to connect to an external block of RAM. In each case, the required memory size is identified for you, based on the number of samples you specify to capture. Incorporating an internal multiplexer, the instrument can be configured to monitor any number of nets and buses fed into the device as signal sets with one set of signals nominated to be captured while the circuit is under test. Up to 16 signal sets are supported and the capture width is automatically determined and adjusted, based on the requirements of all defined signal sets. Indication of remaining width for a given set is provided, allowing you to quickly see how many channels you have left to 'play' with. As an added precaution, you are prevented from exceeding the maximum capture width for a set. Note: Connection of net and bus signals to the Logic Analyzer can be simplified through the use of Instrument Probe Directives. For more information, see the section Instrument Probe Directive, later in this document.
Figure 9. Example Logic Analyzer.

Triggering of the instrument can be external (hardware triggering) or internal (software triggering based on values of incoming signals). You can define any trigger pattern on any of the available sets of signals allowing you to trigger off one set and capture data for the same or different set. The instrument also offers the ability to interpret the data being captured as the code under execution, using data disassembly.

Figure 10. The LAX panel 'control central' for software triggering of the instrument and tabular analysis of the captured data.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence The signals within a signal set can be associated with a specific wave style, which will be used when displaying the generated waveforms in the Digital Waveform Viewer. The styles themselves can be defined as required, from the Wave General page of the Preferences dialog (DXP Preferences). Assignment of styles to signals is carried as part of the instrument's configuration, using the Configure (Logic Analyzer) dialog, an example of which is shown in Figure 11.

Figure 11. Assignable signal styles putting you in the driver's seat for captured digital waveform display!

Figure 12 illustrates an example of the run-time panel for this instrument, accessed by double-clicking on the icon for the instrument, in the Soft Devices chain of the Devices view.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Figure 12. Instrument panel for the configurable Logic Analyzer.

Features at-a-glance
Ability to define up to 16 signal sets for monitoring Supports 8-, 16-, 32- or 64-bit capture width how many signal channels each defined signal set can contain automatically selected based on the requirements of all defined signal sets Ability to store captured samples in internal or external memory, with an indication of the memory size required Internal Memory: Choose from 1K, 2K or 4K samples External Memory: Choose from 16 samples all the way up to 1024K samples (4 to 20 bit address bus respectively)

Indication of used width for a signal set and prevention to exceed the maximum 64-bit capture width Ability to assign wave styles to signals (for display in the Digital Waveform Viewer) Ability to trigger off one signal set and capture data from same or different signal set Ability to use each configuration in split mode External (Hardware) or internal (Software) triggering Ability to capture data at rate of system clock Ability to keep the instrument 'armed' indefinitely Ability to disassemble captured data Analog and digital waveform generation Support for continuous data capture from within waveform views Cursor synchronization between waveform views Pan and zoom synchronization between waveform views

For more detailed information on this instrument, refer to the document CR0158 LAX Configurable Logic Analyzer. A number of legacy logic analyzer instruments are also available. For more information, refer to the document CR0103 LAX_x Logic Analyzer. How do I setup and use the LAX instrument? this video looks at how the Logic Analyzer can be used to store and observe signals from within the FPGA.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Digital I/O Module

The configurable Digital I/O instrument provides separated inputs and outputs, allowing you to monitor and display signal levels, as well as define control signals for use elsewhere in the design. Any number of signals may be added, and any number of bits can be assigned to a single signal. You may also have different numbers of input and output signals. The instrument also supports a variety of graphical formats in which the inputs and outputs can be displayed.
Figure 13. Example Digital I/O Module.

Configuration of the instrument is carried out using the Digital I/O Configuration dialog, an example of which is shown in Figure 14.

Figure 14. Configuration dialog for the Digital I/O Module.

Figure 15 illustrates an example of the run-time panel for this instrument, accessed by double-clicking on the icon for the instrument, in the Soft Devices chain of the Devices view.

Figure 15. Example instrument panel for the configurable Digital IO Module.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Features at-a-glance
Supports any number of input and output signals Each signal can be configured to any number of bits (typically 8, 16, 32) Customizable naming of input and output signals Defined signals can be reordered, graphically, as required Two-level display of inputs Hexadecimal value configurable graphic display Numeric, LEDs, LED Digits, Bar Hexadecimal entry of entire value Configurable graphic control Numeric, LEDs, LED Digits, Slider

Two-level control of outputs

Ability to set initial value for each output signal For more detailed information on this instrument, refer to the document CR0179 DIGITAL_IO Configurable Digital IO Module. A number of legacy digital I/O instruments are also available. For more information, refer to the document CR0102 IOB_x Digital IO Module. How do I use the Digital IO instrument? this video looks at using the Digital IO Module as a set of virtual switches and LEDs in your design.

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Crosspoint Switch Module

The Crosspoint Switch instrument facilitates signal switching within an FPGA design. It allows you to specify any number of input and output blocks, all of which share a common signal block structure the external input signals involved which is definable as part of the instrument's configuration. The interconnection between input and output blocks is completely configurable. Initial connections can be defined as part of design-time configuration, but can be changed on-the-fly at run-time, from the device's associated instrument panel. The latter enables you to switch signals without having to resynthesize and download the entire design to the FPGA. Configuration of the instrument is carried out using the Crosspoint Switch Configuration dialog, an example of which is shown in Figure 17.
Figure 16. Example Crosspoint Switch Module.

Figure 17. Configuration dialog for the Crosspoint Switch Module.

Figure 18 illustrates an example of the run-time panel for this instrument, accessed by double-clicking on the icon for the instrument, in the Soft Devices chain of the Devices view.

Figure 18. Instrument panel for the Crosspoint Switch Module.

10

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Features at-a-glance
Supports any number of input and output blocks Customizable naming of input and output blocks Defined blocks can be reordered as required Customizable naming of block signals Each signal can be configured to any number of bits (typically 8, 16, 32) Defined signals in block can be reordered as required

Block structure (the external input signals) defined and shared by all I/O blocks

Ability to define initial interconnection of I/O blocks Ability to change interconnection of I/O blocks at run-time through the instrument panel Unconnected output blocks will retain the previous value that was output from them For more detailed information on this instrument, refer to the document CR0182 CROSSPOINT_SWITCH Configurable Signal Switching Module.

AP0166 (v1.0) September 05, 2008

11

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Terminal Module
Console I/O is a common way of debugging processor systems. The Terminal instrument provides you with a debug console with which to interact with your system directly. It allows you to type text directly in its associated instrument panel, which is then sent directly to the processor in your design, to be handled by the embedded software code running therein. Conversely, it allows the display of text sent from that processor. Although classed as one of Altium Designer's virtual instruments, the debug console instrument is really a hybrid part instrument and part Wishbone-compliant slave peripheral. Whereas other instruments are configured and operated directly from a GUI, the debug console instrument requires interaction at the code level, to initialize internal registers and to write to/read from its internal storage buffers. In terms of functionality as a peripheral, the Terminal instrument is similar to the WB_UART8 Serial Communications Port peripheral. Whereas the WB_UART8 facilitates serial communication between a processor and a remote device, the Terminal instrument is, in essence, the remote device as well as the facilitator of communications. The processor simply communicates directly (and serially) with the Terminal instrument.
Figure 19. Terminal Module.

Figure 20 illustrates an example of the run-time panel for this instrument, accessed by double-clicking on the icon for the instrument, in the Soft Devices chain of the Devices view.

Figure 20. Instrument panel for the Terminal Module.

Features at-a-glance
Based on, and functionally similar to, the WB_UART8 peripheral Type and send text to processor directly from instrument panel Receive text from the processor and display in instrument panel Full Duplex Ability to save text to a log file Ability to copy selected text to the clipboard Wishbone-compliant For more detailed information on this instrument, refer to the document CR0180 TERMINAL Debug Console Instrument.

12

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Frequency Generator Module

The frequency generator instrument takes a reference clock as its input (time-base) and produces output frequencies that are even divisors of this frequency. By wiring the generator up to have a higher frequency time-base, a greater range of output frequencies can be generated, and with greater accuracy. Predefined frequencies can be chosen at the click of a button. You can also choose from a range of common Baud Rates. For even greater control, you have the option to specify your own required frequency the actual frequency generated in each case Figure 21. Frequency Generator Module. will be displayed directly on the panel. If the required frequency is not an even divisor of the time base frequency, the nearest frequency that is will be used, and the percentage difference also shown. The option to use a 50/50 duty cycle for the generated output is also provided. Figure 22 illustrates an example of the run-time panel for this instrument, accessed by double-clicking on the icon for the instrument, in the Soft Devices chain of the Devices view.

Figure 22. Instrument panel for the Frequency Generator Module.

Features at-a-glance
Ability to request common predefined frequencies at the touch of a button Common frequencies in Hz, kHz and MHz ranges User-definable frequency requests Ability to select from a range of common Baud Rate frequencies Option to set 50/50 Duty cycle Generated frequency output can be inverted (180 Degree phase shift). For more detailed information on this instrument, refer to the document CR0100 CLKGEN Frequency Generator. How do I use the Signal Generator instrument? this video looks at how the Frequency Generator Module can be used to create a periodic signal at a prescribed frequency.

AP0166 (v1.0) September 05, 2008

13

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Counter Module
The Counter instrument provides a two-channel, three-mode frequency counter. For each input signal, the device counts the number of edges rising or falling detected within a specified gating period. Depending on the mode of operation selected, each channel can display the frequency of the signal, its period, or the total number of edges counted. Figure 24 illustrates an example of the run-time panel for this instrument, accessed by double-clicking on the icon for the instrument, in the Soft Devices chain of the Devices view.
Figure 23. Counter Module.

Figure 24. Instrument panel for the Counter Module.

Features at-a-glance
2-Channel, 3-Mode counter Frequency Mode (with a range of 0 to (TIMEBASE / 2)) Period Mode (with a resolution of 1 / (TIMEBASE / 2) Seconds) Event (edge) Counter Mode (able to count up to 9,999,999,999 edges)

Selectable gating period Ability to count rising or falling edges of incoming signals For more detailed information on this instrument, refer to the document CR0101 FRQCNT2 Frequency Counter. How do I use the Frequency Counter instrument? this video looks at how the Counter Module can be used to capture periodic signals or count events.

14

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Additional Hardware Monitoring Tools

In addition to the range of virtual instrumentation available for use in an FPGA design, there are also tools available to interrogate the activity at the pins of the physical FPGA device, or to probe nets within the design. The following sections take a closer look at these tools.

Monitoring the State of Device Pins - Live

Once the design has been downloaded to the FPGA, the Hard Devices JTAG chain can be used to monitor the state of the FPGA pins, in real-time. This is achieved using the device's associated JTAG Viewer panel (accessible from its instrument panel), set to operate in Live Update mode (Figure 25).

Figure 25. Enable the Live Update option in the device's associated JTAG Viewer panel to monitor the state of the FPGA pins in real-time!

Where high-density component packaging makes physical probing of device pins impossible, the JTAG Viewer panel facilitates physical design debugging, 'virtual-style'. It uses the JTAG communications standard to interrogate the state of the pins in any JTAG compliant device in your design, not just the FPGAs. It presents the state of each pin, and includes an image of both the schematic symbol and the footprint, helping you to analyze and debug your design.

Analyzing Design Nets

As part of its LiveDesign methodology, Altium Designer provides you with the ability to analyze nets in an FPGA design, while it is running on the target physical device. Where a design net is connected directly to a pin of the physical device, you have the ability to monitor the status of that pin in real-time. By using a virtual instrument, such as a logic analyzer, you can gain valuable operational information about your design. The ability to 'reach in' and interactively analyze design nets can give you the edge needed to finalize development prior to manufacture, leading to shorter time-to-market and making a good product great. To aid in this analysis, Altium Designer provides the Probe and Instrument Probe directives.

AP0166 (v1.0) September 05, 2008

15

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Probe Directive
The days of being able to attach fly-lead probes physically to the pins of a chip and analyze states is fast nearing the doors of antiquity. Devices especially FPGAs are becoming pin-saturated beasts which, even if you could 'see' the pins, they are undoubtedly too finely pitched to access externally. So how about monitoring pins from within the design directly from the schematic sheet? It's a vision made real with LiveDesign and a well-placed Probe directive. Place a Probe directive on any net (wire or bus) in the design that connects directly to a pin of the physical FPGA device. Once the design has been programmed into the device, the state of such a pin can be monitored, in real-time, directly on the schematic sheet (Figure 26). The key to the pin-state display is the directive's ProbeValueDisplay parameter. In fact you could place a Parameter Set directive instead, and as long as this parameter is defined for it, the result would be the same.
Figure 26. FPGA pin status monitoring using Probe directives.

For the pin state to be updated in real-time on the schematic, the source FPGA design must be downloaded to the physical FPGA device and the associated JTAG Viewer panel (see previous section) for that device must be open and remain open.

Instrument Probe Directive

Probing device pins from the schematic is great, but what about being able to analyze and potentially fault-find further back into the design circuitry? No problem. Simply place an Instrument Probe directive, which allows you to monitor any point in a design not just the status of FPGA device pins. Placed on a net object, such as a wire or bus, it instructs the system to connect the associated net directly to the input of a monitoring instrument (e.g. a logic analyzer) without having to explicitly wire that net up through the design hierarchy to the sheet with the instrument on it.
In addition, when attached to a net that connects directly to an FPGA device pin, the Instrument Probe directive behaves as per the Probe directive. Again, the JTAG Viewer panel must be open.

The key element that turns this directive from being a simple probe into a powerful point-monitoring aid, is its possession of the additional InstrumentProbe parameter. Once the directive is placed at the point of interest, it is this parameter that is used to effectively 'link' that point to the monitoring device. Simply enter a meaningful name for the probe point such as the name of the associated net or the particular signal being monitored then connect a wire to the required input of the monitoring instrument and attach a net label to the wire, the name of which is the same name you have defined for the InstrumentProbe parameter (Figure 27).

Figure 27. Monitoring select points in a design without excessive wiring overhead.

Measurement information obtained through the directive's ProbeValueDisplay parameter is, like the Probe directive, displayed in real-time, over the Hard Devices JTAG chain. In contrast, measurement information obtained through the directive's InstrumentProbe parameter is ONLY displayed after compilation, over the Soft Devices JTAG chain.

16

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence A word about probing buses When an Instrument Probe directive is attached to a bus, the entire bus is taken up to the top-level sheet, irrespective of the name you assign to the InstrumentProbe parameter. When you add a net label to the input for the monitoring instrument, you must define the bus width required. Consider, for example, having attached an Instrument Probe directive to a bus with identifier Port1_Out[7..0] on a lowerlevel sheet. The value for the InstrumentProbe parameter could be simply set to Port1_Out. The entire bus will be connected up to the sheet with the monitoring device (e.g. a configurable Logic Analyzer). Should you wish to wire up the whole bus as an input signal to the device, you would place a bus to the required input and add a net label of Port1_Out[7..0]. If you only wanted a particular signal or range of signals from the bus, you can simply define the width required in the attached net label (e.g. Port1_Out[4..2]).

AP0166 (v1.0) September 05, 2008

17

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Embedded Software Debugging Tools

Debugging of the hardware side of an electronic product is, to coin a phrase, only half the battle. The intelligence of the product and the source of real sustainable differentiation, is the embedded software code running on a processor in the design. It is this code that gives the product it's 'smarts' the basis of the product's functionality. Altium Designer provides extensive on-chip debugging capabilities for each available 32-bit processor, allowing you to examine and change memory and register values in real-time, as well as performing source-level debugging of your embedded code.

Facilitating Real-Time Debugging of a Processor

To facilitate real-time debugging of a 32-bit processor, the processor must be configured to include JTAG-based On-Chip Debug System (OCDS) hardware. For the following processors, this hardware is permanently installed: CoreMP7 PPC405A PPC405CR ARM720T_LH79520

For other supported 32-bit processors (TSK3000A, MicroBlaze, NiosII), this hardware is a configurable option, defined for the processor in its associated Configure (32-bit Processors) dialog (Figure 28). The option to include the debug hardware is enabled by default.

Figure 28. Enabling the On-Chip Debug System for a 32-bit processor (TSK3000A).

With the debug hardware installed, the following set of functional features are provided: Reset, Go, Halt processor control Single or multi-step debugging Read-Write access for internal processor registers Read-Write access for memory and I/O space Unlimited software breakpoints.

Accessing the Debug Environment

Debugging of the embedded code within a 32-bit processor is carried out by starting a debug session. Prior to starting the session, you must ensure that the design, including one or more debug-enabled processors and their respective embedded code, has been downloaded to the target physical FPGA device. To start a debug session for the embedded code of a specific processor in the design directly from the Devices view simply right-click on the icon for that processor, in the Soft Devices chain of the Devices view, and choose the Debug command from the pop-up menu that appears.

18

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence The embedded project for the software running in the processor will initially be recompiled and the debug session will commence. The relevant source code document (either Assembly or C) will be opened and the current execution point will be set to the first line of executable code (Figure 29). Note: You can have multiple debug sessions running simultaneously one per embedded software project associated with a processor in the Soft Devices chain.

Figure 29. Starting an embedded code debug session.

The debug environment offers the full suite of tools you would expect to see in order to efficiently debug the embedded code. These features include: Setting Breakpoints Adding Watches Stepping into and over at both the source (*.C) and instruction (*.asm) level Reset, Run and Halt code execution Run to cursor

All of these and other feature commands can be accessed from the Debug menu or the associated Debug toolbar (Figure 30).

As with all menu commands and toolbar buttons in Altium Designer, hover the cursor over an entry to access information in the Knowledge Center panel.

Figure 30. Accessing debug-related commands at the source-code level.

A debug session can be ended in one of three ways: By invoking the End Debug command from the right-click menu for the processor in the Devices view By invoking the Stop Debugging command, from the main Debug menu within the source code editor By clicking the button on the Debug toolbar associated with the source code editor.

AP0166 (v1.0) September 05, 2008

19

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence Various workspace panels are accessible in the debug environment, allowing you to view/control code-specific features, such as Breakpoints, Watches and Local variables, as well as information specific to the processor in which the code is running, such as memory spaces and registers. These panels can be accessed from the View Workspace Panels Embedded sub menu, or by clicking on the Embedded button at the bottom of the application window and choosing the required panel from the subsequent pop-up menu.

Figure 31. Example workspace panels offering code-specific information and controls

Figure 32. Example workspace panels offering information specific to the parent processor.

For more information on the content and use of workspace panels used to debug embedded source code, press F1 when the cursor is over one of these panels. How do I navigate around my source code? this video looks at using advanced text editor features to navigate across source code functions and files.

20

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence Full-feature debugging is of course enjoyed at the source code level from within the source code file itself. To a lesser extent, debugging can also be carried out from a dedicated debug panel for the processor. To access 1 this panel, first double-click on the icon representing the processor to be debugged, in the Soft Devices chain of the Devices view. The Instrument Rack Soft Devices panel will appear, with the chosen processor instrument added to the rack (Figure 33).

Figure 33. Accessing debug features from the processor's instrument panel

Note: Each core processor that you have included in the design will appear, when double-clicked, as an Instrument in the rack (along with any other Nexus-enabled devices). The Nexus Debugger button provides access to the associated debug panel (Figure 34), which in turn allows you to interrogate and to a lighter extent control, debugging of the processor and its embedded code, notably with respect to the registers and memory. One key feature of the debug panel is that it enables you to specify (and therefore change) the embedded code (HEX file) that is downloaded to the processor, quickly and efficiently. For more information on the content and use of processor debug panels, press F1 when the cursor is over one of these panels. Additional information on debugging an embedded application can be found in the tutorial document TU0122 Getting Started with Embedded Software. For comprehensive information with respect to the embedded tools available for a 32-bit processor, navigate to the relevant subfolder for the target processor, in the Documentation Library Embedded Intelligence Processor-based FPGA Design area of the Knowledge Center panel.

Figure 34. Processor debugging using the associated processor debug panel.

How do I debug my design? this video looks at the use of standard software debugging techniques, along with virtual instruments, to debug your embedded software within Altium Designer.

The debug panels for each of the debug-enabled microcontrollers/processors are standard panels and, as such, can be readily accessed from

the View Workspace Panels Instruments sub menu, or by clicking on the Instruments button at the bottom of the application window and choosing the required panel for the processor you wish to debug from the subsequent pop-up menu.

AP0166 (v1.0) September 05, 2008

21

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Profiling
When writing the embedded source code to run on a target processor within a design, the 'holy grail' is to implement the required algorithms as efficiently and as optimizable as possible. An elegant algorithm may turn out to be time-inefficient, leading to overall performance degradation. Multiple slow-executing algorithms will only serve to compound the problem. As a further aid in debugging your embedded code, Altium Designer provides Profiling technology. Profiling is the process of collecting statistical data about a running program and can be used to determine functions of the embedded code are called, how often they are called, and how long they take to execute. The Profiling technology provides a number of profiling tools that together enable you to fine tune the performance of your code. Performance problems can be solved by: Identifying time-consuming algorithms and rewriting the code using more time-efficient algorithms. Identifying time-consuming functions and selecting the appropriate Compiler optimizations for these functions (e.g. enable loop unrolling or function inlining). Identifying time-consuming loops and adding the appropriate pragmas to enable the Compiler to further optimize these loops.

Adding Profiling Functionality to an Embedded Project

The C Compiler in the toolchain of each 32-bit target processor platform contains an option to add code to your embedded software project, which handles the profiling process for you. This method of profiling is often referred to as code instrumentation. From within Altium Designer, this option Generate profiling information is enabled as part of the project options for the embedded software project (Figure 35). Further sub-options are provided, which allow you to specify what kind of information is profiled.

Figure 35. Accessing debug features from the processor's instrument panel

With profiling enabled, code is added to the original program code that is needed to gather the required profiling data. The code size of your program will therefore be increased. Profiling data is captured in real-time, as the program executes. This will result in longer execution time for the program. In addition, dynamically allocated target memory is used to initially store the data. The heap of your program must therefore be large enough to store this captured data. The more detailed the profiling information you specify, the larger the overhead in terms of execution time, code size and heap space required. Since code instrumentation is performed by the C Compiler, any Assembly code functions in your program will not appear in the profiling data. Also, as profiling data is gathered during program execution, the input of the program directly influences the results. For example, if a function within the program is not activated while the program is being profiled, then no profile data for that function will be generated.

22

AP0166 (v1.0) September 05, 2008

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Viewing Profiling Results

When the debug session is stopped, the profiling data is written from target memory to an intermediate file and then ultimately translated into an XML file (ProfilerResult_DateTime.xml). The data is then loaded, and displayed, in the Profiler view (Figure 36), accessible from the Debug toolbar. Runtime profiling information is only generated when a program finishes execution either by reaching the end of main() or by specifically calling the exit() function. Simply stopping the debug session while the program is still running will yield no profiling results.

Figure 36. Peruse profiling results in the Profiler view.

Three tabs are provided (All Functions, Files, Functions) allowing you to quickly view profiling data for all functions across all C source files, or only those functions resident in specified source file(s). The main Results region of a tab is where the timing information can be found. By selecting a particular function in this region, you can also gain further information related to that function, such as which functions call it, or are called by it. Use the associated Profiling Target panel (Figure 37) to reduce what can be an overwhelming amount of profiling information. Initially all functions in all C source files for the embedded software project are enabled for display in the Profiler view. Disable the entries for those you wish to remove as required. The lower region of the Profiling Target panel lists all previous profiling results. Double-clicking on an entry will load the results in the associated file, displaying them in the Profiler view. In this way, you can switch between sets of results that may have been captured using different profiling options. For more detailed information with respect to profiling, refer to the Profiling section of the embedded tool user guide for a target processor. The guide can be found by navigating to the relevant sub-folder for the target processor, in the Documentation Library Embedded Intelligence Processor-based FPGA Design area of the Knowledge Center panel.

Figure 37. Profiling Target panel.

AP0166 (v1.0) September 05, 2008

23

Legacy documentation refer to the Altium Wiki for current information

Testing and Debugging Your Embedded Intelligence

Revision History
Date 05-Sep-2008 Version No. 1.0 Revision Initial release

Software, hardware, documentation and related materials: Copyright 2008 Altium Limited. All Rights Reserved. The material provided with this notice is subject to various forms of national and international intellectual property protection, including but not limited to copyright protection. You have been granted a non-exclusive license to use such material for the purposes stated in the end-user license agreement governing its use. In no event shall you reverse engineer, decompile, duplicate, distribute, create derivative works from or in any way exploit the material licensed to you except as expressly permitted by the governing agreement. Failure to abide by such restrictions may result in severe civil and criminal penalties, including but not limited to fines and imprisonment. Provided, however, that you are permitted to make one archival copy of said materials for back up purposes only, which archival copy may be accessed and used only in the event that the original copy of the materials is inoperable. Altium, Altium Designer, Board Insight, DXP, Innovation Station, LiveDesign, NanoBoard, NanoTalk, OpenBus, P-CAD, SimCode, Situs, TASKING, and Topological Autorouting and their respective logos are trademarks or registered trademarks of Altium Limited or its subsidiaries. All other registered or unregistered trademarks referenced herein are the property of their respective owners and no trademark rights to the same are claimed. v8.0 31/3/08.

24

AP0166 (v1.0) September 05, 2008