AP0166 Testing and Debugging Your Embedded Intelligence

Testing and Debugging Your Embedded IntelligenceSummaryApplication NoteAP0166 (v1.0) September 05, 2008This document takes a look at the range of tools available to aide in the debugging ofyour embedded intelligence – the FPGA design itself and any embedded programcode 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 InstrumentationIn 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 RuntimeBefore 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.Testing and Debugging Your Embedded IntelligenceThe interface for a virtual instrument is accessed by double-clicking on the corresponding icon for it. Doing so will give access toits 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 onsome target hardware.Enabling the Soft Devices JTAG ChainThe 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 thecommunications 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 designinterface component (Figure 3). This can be found in the FPGA NB2DSK01 Port-Plugin 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-enableddevices (processors, virtual instruments) into this chain, you need to also place a NEXUS_JTAG_PORTcomponent (Figure 4), and connect this directly to the NEXUS_JTAG_CONNECTOR (Figure 5). Thiscomponent can be found in the FPGA Generic integrated library (\Library\Fpga\FPGAGeneric.IntLib ).Figure 3. Nexus JTAG Connector. The presence of the NEXUS_JTAG_PORT component instructs the software to wire all components thatpossess the parameter NEXUS_JTAG_DEVICE=True into the Soft JTAG chain. Figure 4. NexusJTAG 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 systemon your production or third party development board.Testing and Debugging Your Embedded IntelligenceCustom InstrumentThe Custom Instrument component is a fully-customizable 'virtual'instrument with which to monitor and control signals within an FPGAdesign.As part of the instrument's configuration you are able to create your ownGUI – the interface that is seen once the design is programmed into thetarget device and the instrument is accessed. A palette of standardcomponents and instrument controls enable you to quickly construct theinstrument panel, while various properties associated with a control allowyou 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 Configurationdialog (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. TheDesign 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.Testing and Debugging Your Embedded IntelligenceFigure 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•Design form for creating instrument GUI with three dedicated panels:-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•Supports use of scripting (DelphiScript), for example to manipulate signal IO to a greater degree. Script can be written: -Within a dedicated coding tab as part of the instrument's configuration dialog-Within a code-aware editor inside Altium Designer•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 DesignerFor 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.Testing and Debugging Your Embedded IntelligenceLogic AnalyzerThe configurable Logic Analyzer instrument is capable of supporting 8-, 16-, 32- or 64-bit capture. The instrument can be configured to use predefinedinternal storage memories for captured data, or to connect to an externalblock 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 tomonitor 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 undertest.Up to 16 signal sets are supported and the capture width is automaticallydetermined and adjusted, based on the requirements of all defined signalsets. Indication of remaining width for a given set is provided, allowing youto quickly see how many channels you have left to 'play' with. As an addedprecaution, you are prevented from exceeding the maximum capture widthfor a set.Note: Connection of net and bus signals to the Logic Analyzer can besimplified through the use of Instrument Probe Directives. For moreinformation, see the section Instrument Probe Directive , later in thisdocument. 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.Testing and Debugging Your Embedded IntelligenceThe 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.Testing and Debugging Your Embedded IntelligenceFigure 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 viewsFor 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 CR0103LAX_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.Testing and Debugging Your Embedded IntelligenceDigital I/O ModuleThe configurable Digital I/O instrument provides separated inputs andoutputs, allowing you to monitor and display signal levels, as well as definecontrol signals for use elsewhere in the design.Any number of signals may be added, and any number of bits can beassigned to a single signal. You may also have different numbers of inputand output signals.The instrument also supports a variety of graphical formats in which theFigure 13. Example Digital I/O Module.inputs and outputs can be displayed.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.Testing and Debugging Your Embedded IntelligenceFeatures 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•Two-level control of outputs-Hexadecimal entry of entire value-Configurable graphic control – Numeric, LEDs, LED Digits, Slider•Ability to set initial value for each output signalFor 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_xDigital 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.Testing and Debugging Your Embedded IntelligenceCrosspoint Switch ModuleThe Crosspoint Switch instrument facilitates signal switching within an FPGAdesign. It allows you to specify any number of input and output blocks, all ofwhich share a common signal block structure – the external input signalsinvolved – which is definable as part of the instrument's configuration.The interconnection between input and output blocks is completelyconfigurable. Initial connections can be defined as part of design-timeconfiguration, but can be changed on-the-fly at run-time, from the device'sassociated instrument panel. The latter enables you to switch signals withouthaving to resynthesize and download the entire design to the FPGA.Configuration of the instrument is carried out using the Crosspoint SwitchConfiguration 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.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•Block structure (the external input signals) defined and shared by all I/O blocks-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•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 themFor more detailed information on this instrument, refer to the document CR0182 CROSSPOINT_SWITCH Configurable Signal Switching Module.Terminal ModuleConsole I/O is a common way of debugging processor systems. The Terminal instrumentprovides you with a debug console with which to interact with your system directly. It allowsyou to type text directly in its associated instrument panel, which is then sent directly to theprocessor 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 consoleinstrument is really a hybrid – part instrument and part Wishbone-compliant slave peripheral.Whereas other instruments are configured and operated directly from a GUI, the debugconsole instrument requires interaction at the code level, to initialize internal registers and towrite to/read from its internal storage buffers.In terms of functionality as a peripheral, the Terminal instrument is similar to the WB_UART8Serial Communications Port peripheral. Whereas the WB_UART8 facilitates serialcommunication between a processor and a remote device, the Terminal instrument is, inessence, the remote device as well as the facilitator of communications. The processorsimply 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-compliantFor more detailed information on this instrument, refer to the document CR0180 TERMINAL Debug Console Instrument .Frequency Generator ModuleThe frequency generator instrument takes a reference clock as its input (time-base)and produces output frequencies that are even divisors of this frequency. By wiringthe generator up to have a higher frequency time-base, a greater range of outputfrequencies can be generated, and with greater accuracy.Predefined frequencies can be chosen at the click of a button. You can also choosefrom a range of common Baud Rates. For even greater control, you have the option tospecify your own required frequency – the actual frequency generated in each casewill be displayed directly on the panel. If the required frequency is not an even divisorof the time base frequency, the nearest frequency that is will be used, and the percentage difference also shown.Figure 21. Frequency Generator Module.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 tocreate a periodic signal at a prescribed frequency.Counter ModuleThe Counter instrument provides a two-channel, three-mode frequency counter. Foreach input signal, the device counts the number of edges – rising or falling – detectedwithin a specified gating period. Depending on the mode of operation selected, eachchannel can display the frequency of the signal, its period, or the total number ofedges counted.Figure 24 illustrates an example of the run-time panel for this instrument, accessed bydouble-clicking on the icon for the instrument, in the Soft Devices chain of theFigure 23. Counter Module.Devices view.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 signalsFor 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.Additional Hardware Monitoring ToolsIn 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 - LiveOnce 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 NetsAs 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.Probe DirectiveThe days of being able to attach fly-lead probes physically to the pins ofa chip and analyze states is fast nearing the doors of antiquity. Devices –especially FPGAs – are becoming pin-saturated beasts which, even ifyou could 'see' the pins, they are undoubtedly too finely pitched toaccess externally. So how about monitoring pins from within the design –directly from the schematic sheet? It's a vision made real with LiveDesignand a well-placed Probe directive.Place a Probe directive on any net (wire or bus) in the design thatconnects directly to a pin of the physical FPGA device. Once the designhas been programmed into the device, the state of such a pin can bemonitored, in real-time, directly on the schematic sheet (Figure 26).Figure 26. FPGA pin status monitoring using Probe directives. The key to the pin-state display is the directive's ProbeValueDisplay parameter. In fact you could place a Parameter Set directive instead, andas long as this parameter is defined for it, the result would be the same.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 DirectiveProbing device pins from the schematic is great, but what about being able to analyze andpotentially fault-find further back into the design circuitry? No problem. Simply place anInstrument Probe directive, which allows you to monitor any point in a design – not just thestatus of FPGA device pins. Placed on a net object, such as a wire or bus, it instructs thesystem to connect the associated net directly to the input of a monitoring instrument (e.g. alogic analyzer) – without having to explicitly wire that net up through the design hierarchy tothe sheet with the instrument on it. 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 monitoringinstrument and attach a net label to the wire, the name of which is the same name you have defined for the InstrumentProbeparameter (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.。