Installing and Using a DS-5 Platform Configuration
A platform configuration contains all the information that DS-5 Development Studio needs in order to connect to a target platform for trace and debug.
If an Arm representative or colleague has sent you a new or modified DS-5 platform configuration to provide you with new or better debug or trace functionality for your Arm-based target platform, then follow this guide to installing and using it with DS-5 Development Studio.
This tutorial is intended as a general guide, since every target platform supports different functionality and presents a debugger with different challenges.
If you experience problems, check that you have followed each step carefully and in the right order. Collect as much information as possible so that your Arm representative can investigate the problems.
The Platform Configuration
The configuration takes the form of a set of cascaded directories:
- The main directory, which contains:
- The boards directory, which contains:
- The manufacturer directory, which contains:
- The platform directory, which contains:
- The platform configuration files
The size, number and type of configuration files may vary for different types of platform connection, and the manufacturer and platform directories will have appropriate names for your target platform. So a typical platform configuration (for the “Super Board” platform from the “Amazing Board Company”) might look like this:
Typically, this will need to be extracted from a .zip or .tar file.
Installing your Platform Configuration
Before you can debug or trace your target platform using DS-5, you have to install your new DS-5 platform configuration. There are a number of steps which must be followed in order:
- Remove any previous versions of the platform configuration, both by deleting the configuration directories and files from your file system and by removing the configurations from the DS-5 Configuration Database Preferences dialog. This step isn't essential, but it certainly helps to prevent confusion and ensure that all tests are performed with the latest version of the platform configuration.
- Unzip the platform configuration to a convenient location in your file system.
- Add the entire unzipped directory as a new DS-5 configuration database using the DS-5 Configuration Database Preferences dialog (you can reach this through Window > Preferences in the main DS-5 menu). Be sure to add the entire unzipped directory – not the Boards directory or any other directory or file.
- Rebuild the database using the button provided in the Configuration Database Preferences dialog.
This screenshot shows the DS-5 Configuration Database preferences dialog after adding our new “Super Board” platform:
DS-5 ships with large configuration databases which contain configuration information for many platforms. You can see two such configuration databases in the screenshot, one for Android and Linux application targets, and one for Linux and bare-metal targets.
we highly recommend that you do not simply copy new configuration files directly into these existing databases for a number of reasons:
- You may well encounter read-only directory permissions.
- If you are using a shared installation of DS-5, your new platform configuration will become visible to other users, possibly causing confusion and conflicts.
- You will still need to rebuild the configuration database. However this is also done automatically when you restart DS-5.
- The database structure of the DS-5 configuration database is quite rigid. You would need to copy only some of the directories and files from your new platform configuration into the right places in the existing configuration databases, this can cause confusion.
- If you copy files directly into the existing DS-5 installation, they will be lost when you upgrade to a newer version of DS-5 (or they may interfere with the upgrade process). If you add your platform configuration as a new DS-5 configuration database, it will still be available after you upgrade DS-5.
Testing your Platform Configuration
Once you have installed your new DS-5 platform configuration, you can configure a DS-5 debug and trace session using the DS-5 Run > Debug Configurations... menu item. This enables you to select your platform and choose the debug operation you want, for example:
The DTSL Options Edit button opens a dialog that contains custom controls for your platform. Since these controls are customized for your platform, what you will see here will vary from the screenshots below. Your Arm representative will be able to give you all the information you need about the custom controls in your new platform configuration. However, nearly all platform configurations contain two types of controls:
- Controls to select where trace is stored, for example in an on-chip buffer or in the DSTREAM trace buffer. One selection may apply to trace from all trace sources, or it may be possible to make individual choices for different core clusters and trace sources – depending on the functionality supported by your target platform:
- Controls to configure trace generation. There may be different controls for different core clusters and trace sources, again depending on the functionality supported by your target platform:
To generate and capture trace, it is necessary to select the trace destination and to configure trace generation.
Suggested Test Procedure
We recommend that you follow these guidelines when testing your platform configuration:
- Ensure that the target is fully powered and connected to the debug hardware (e.g. DSTREAM) using the appropriate cable(s).
- Ensure that all cores and all debug & trace devices are fully powered up and have not been powered down or un-clocked. If possible, stop the target at the boot prompt and ensure that it is still responsive.
- Start with the most simple debug operation first: debug-only of a single core. Then move to SMP cluster or big.LITTLE debug.
- Test trace only after testing basic debug functionality. Again, start with a single core, test on-chip trace capture (ETB, ETF) before system memory trace capture (ETR) and finally TPIU trace (to the DSTREAM trace buffer). Remember that you'll need a trace cable to test TPIU trace, not just the JTAG cable needed for debug and on-chip trace. Test local cluster trace capture before testing system trace capture.
- In each test, choose the Connect only option in the Debugger tab. Halt the target if it is running, then test single instruction step, run and halt. Finally test running to a breakpoint.
Power-cycling Target Boards
Under some circumstances, after a loss of debug control it is possible for the debug bus on the target to become locked. DS-5 will be unable to regain debug control of the target until the bus is unlocked, and this generally can only be done by power-cycling the target.
So, if you notice a regression in DS-5 debug and trace functionality after a loss of debug control (for example a debug connection that previously worked now doesn't work), you need to consider power-cycling the target.
In rare cases, it has been possible to damage some of the circuits in the DSTREAM debug probe while power-cycling a target platform. This particularly applies to target boards where the following are true:
- The power supply voltage is greater than 5 V.
- The positive pin of the power supply cable can make contact with the target board before the ground pin.
- There are large capacitors in the board power circuit.
To prevent possible damage to the DSTREAM debug probe, we recommend taking one of the following precautions when power-cycling a target board:
- Disconnect the JTAG and trace cables between the target and the DSTREAM probe when power-cycling the target.
- Power-cycle the target by disconnecting the power adapter from the mains electricity supply, not by disconnecting the target from the power adapter.
Reporting a Problem
It may be that you don't experience 100% success with your new DS-5 platform configuration. Each target platform is different and modern silicon designs can be large and complex, so some changes may be necessary to give better debug or trace support.
When reporting difficulties with a platform configuration, the following information makes it easier to diagnose the problem:
- A complete, detailed reproduction guide. Your ARM representative will need to know the exact set of steps you followed to reproduce the problem.
- It's often useful to know what does work, as well as what doesn't work. For example, it's extremely useful to know when:
- Single core debug is OK, but SMP debug is not.
- Some cores can be debugged, but some cannot.
- On-chip trace capture is OK, but off-chip trace capture is not.
- You can connect to a core, but you can't halt it.
- Is the problem intermittent, or is it 100% repeatable?
- What is the state of the target after the problem occurs? Can you disconnect and re-connect with a previously working debug operation, or is the target now locked and needs to be power-cycled?
- DS-5 may display error messages. Try to provide the complete wording of every error or warning message, including any error numbers. A screenshot of the entire DS-5 screen may prove to be very useful.
- The DS-5 Error Log view contains detailed error information. We need the full details for the error, which may well include a stack dump and much more information than is displayed in other parts of the DS-5 display. To ensure that you have the details of the right error, you may find it useful to clear the Error Log view before reproducing the problem.
Using a generated platform configuration
It may be that you're using a platform configuration that you have generated using the cdbimporter tool that is shipped with DS-5. This guide and all of the information and guidelines that it contains, apply to platform configurations that you have generated exactly as they apply to platform configurations provided by an Arm representative. However, when reporting a problem, you should also send the entire generated platform configuration to your Arm representative.