I am an FAE at ARM, and part of my job is to support users bringing up new silicon and hardware platforms, so that they can start to develop software on them. For this task, I use the ARM DSTREAM™ debug and trace unit and the various bring-up utilities provided with the DS-5 toolchain, which enable the creation of device support in the DS-5 Debugger. I decided to write this blog to describe how I use these tools, and to encourage you to do the same. Our configuration database is aware of over 100 standard platforms today, and we would like to add many more, and you can help.
I will talk about the configuration tools provided to get you going quickly and easy, as well as diagnosis tools should things go wrong. If you need to go further, the python based Debug and Trace Services Layer (DTSL) provides the key to unlocking all the debug features.
In the below examples I use the ARM Versatile™ Express platform with the ARM big.LITTLE™ CoreTile Express, but the principles apply to any ARM target.
UPDATE, April 2015
In DS-5 5.21 (and later) ARM provides a new utility named the Platform Configuration Editor, which supersedes the information below, and the below utilities are deprecated, and no longer recommended for use. If using this version of the tools, please read this tutorial instead.
The first thing we need to do is create a baseline configdb entry for the platform, to teach the debugger what it will be connecting to. Provided with DS-5, the Debug Hardware Configuration utility (debughwconfig on Linux) interrogates the target, and determines which ARM CoreSight™ debug components are implemented. Click on Auto-Configure and the tool reads the CoreSight ROM Table, and populates as below. Save the configuration as an rvc file, and we’re almost there. For convenience, I recommend saving to the cdbimport directory of your DS-5 installation.
We now need to import this rvc configuration to the database, and we provide a simple CLI utility called cdbimporter to do this. This utility will enable you to save the config to an appropriate location, and name the configuration. This name will be presented by the debugger to the user later on.
As an aside, if using a Fast Model, you can also use this tool, with cdbimporter --model <path_to_model_executable>. All other steps below are identical.
UPDATE
With DS-5 version 5.19 (and later), we provide a new utility to improve importing fast model debug configurations. You can download the latest version of DS-5 here.
Take note of the “DTSL script assumptions” as presented. While the tool can determine the CoreSight debug components implemented in the device; it cannot determine how they are all connected, as this information is not defined in the CoreSight ROM table. Also note some advanced features of this cdbimporter utility. Usually one simply selects the default options, but the utility enables you to do clever things, such as hiding particular CPUs from the debugger view.
We should now have the basis of a DS-5 configuration. Let’s try it out!
If you created your configuration in a different location to the default, you will need to add this to the Target Configuration Database. From the Eclipse GUI menu, select Window → Preferences → DS-5 → Configuration Database, to open this window:
Select User Configuration Databases → Add, and point to where you stored the configuration:
Click OK, and press Rebuild Database. DS-5 now knows about your configuration. Any subsequent configurations that you create at this location will be added to DS-5 each time you launch the GUI, or if you click Rebuild Database again. Click OK to close this window.
Next we need to make a DS-5 Debug Configuration. This defines the connection(s) from the debugger to the target, and will use the configuration database that we have just made. Select Debug Configurations… from the Run menu, and create a new DS-5 Debugger configuration. You can use the Filter platforms text box to jump to the configuration you just created, and select the CPU(s) you want to connect to, and any other necessary options.
DTSL has been mentioned in passing, but now we shall look at it in more detail. The DTSL Options Edit button above, allows you to enable certain features, depending on your target.
For example, you can enable trace for one or more of the CPUs, direct the trace data to an on-chip trace buffer, or off chip (for collection inside the DSTREAM debug and trace unit). You can also create multiple trace configurations (click the green + icon) if there are different trace scenarios that you use regularly. Configure as needed, and away you go!
The above is the general flow assuming is working straight out of the box. But if things do not proceed perfectly, the tools have been architected to allow manual intervention at all stages of the process.
In Debug Hardware Configuration, it is possible for you to manually configure, though this does require knowledge of the debug topology. This may not be documented in public documentation from a vendor, and so you may need to contact them (or ask them to contact ARM) to progress this further.
Assuming you have this information, you can use the “Devices” section above to add the various components, and then select it from the left hand side, and configure appropriately (setting CoreSight Addressing etc).
If you still have issues, lower level tools are available. You will find a command line tool called CoreSight Access Tool (CSAT), that enables you to connect to the CoreSight DAP, and manually read and write registers on the targets debug bus. For example, I commonly use this utility to verify that a processor has entered debug state correctly, or that a trace macrocell has been programmed correctly. Going to this level does require some advanced knowledge of the debug architecture.
If you do not make any progress, don’t hesitate to contact ARM, and we will be happy to get you up and running. We have diagnostic tools such as rvi_log_client to examine what is happening “under the hood” of the tools, so we can go to whatever depth is needed to work out what is happening.
The DTSL configuration is controlled by python scripts, and you will find a dtsl_config_script.py file within the configdb entry that you built above. At a first glance, this can be overwhelming, but in reality there are only a few edits that may be necessary.
The most common edit that users need to make is, when using TPIU trace, to set the width of the trace port appropriately. This is defined as 16-bit by default with the parameter:
DSTREAM_PORTWIDTH = 16
There are also times when the assumptions that cdbimporter makes regarding the debug topology are incorrect. For example, if the trace funnel ports are not connected in the order that the tool assumes. Here is the relevant section of the DTSL script (getFunnelPortForCore() method):
def getFunnelPortForCore(self, core):
''' Funnel port-to-core mapping can be customized here'''
port = core
return port
This can easily be changed as appropriate.
if core == 0:
port = 6
Exactly what edits, if any, are necessary in these scripts depend on the platform used, as well as the desired functionality. For a more thorough description, I strongly recommend reviewing this tutorial.
Once a configuration has been built, it is completely transferable. You can share the configuration with your colleagues, and they will be able to reuse the work that you have done, by adding the configuration to their database.
As mentioned at the top of this blog, we have over 100 out-of-the-box configurations in DS-5 today, but would like many more. ARM encourages platform owners to create configurations for their platforms, and to submit the configuration to the DS-5 team. We can then include the configuration in subsequent DS-5 releases, thus enabling a better out-of-the-box experience for your users. For example, Mindspeed created configurations that will be included in a forthcoming DS-5 release.
Alex Pynko, Director of System Engineering at Mindspeed said:
“Mindspeed Technologies is pleased with ARM’s initiative to include our ARM platform configurations in DS-5. We have released two new platforms, one with the dual Cortex-A9 (Transcede T2200), the second with two dual Cortex-A9 clusters (Transcede T3300). With ARM’s help in creating the debugger configurations, our customers can use the DS-5 debugger configurations for the new platforms without our direct support”.