AN329 - Contributing a Configuration Database to DS-5

Application Node 329


Application Note 329
Contributing a Configuration Database to DS-5

Copyright © 2012 ARM Limited. All rights reserved.

                                                Release information

Change history




August 2012

October 2012



First release

Removed broken install option from section 4

                                                Proprietary notice

Words and logos marked with Ó and Ô are registered trademarks owned by ARM Limited, except as otherwise stated below in this proprietary notice. Other brands and names mentioned herein may be the trademarks of their respective owners.

Neither the whole nor any part of the information contained in, or the product described in, this document may be adapted or reproduced in any material form except with the prior written permission of the copyright holder.

The product described in this document is subject to continuous developments and improvements. All particulars of the product and its use contained in this document are given by ARM in good faith. However, all warranties implied or expressed, including but not limited to implied warranties of merchantability, or fitness for purpose, are excluded.

This document is intended only to assist the reader in the use of the product. ARM Limited shall not be liable for any loss or damage arising from the use of any information in this document, or any error or omission in such information, or any incorrect use of the product.

                                                Confidentiality status

This document is Open Access. This document has no restriction on distribution.

                                                Feedback on this Application Note

If you have any comments on this Application Note, please send email to giving:

·                     the document title

·                     the document number

·                     the page number(s) to which your comments refer

·                     an explanation of your comments.

General suggestions for additions and improvements are also welcome.

                                                ARM web address

1.   Introduction

This Application Note describes how to add a default Configuration Database to DS-5. A Configuration Database describes target-specific information, such as how to connect and the register and peripherals that are made accessible within DS-5 Debugger. The intention is to enable third-party installers to add platform support to an already installed DS-5 installation.

A default Configuration Database can be added to DS-5 via an Eclipse extension point contributed from a plug-in. The extension point consists of a single Java interface, which provides an ordered list of Configuration Database paths when requested by DS-5. A provider is expected to implement the interface, produce the plug-in declaring the extension and add the plug-in to DS-5.

This Application Note is split into the following sections:

·         Configure a DS-5 development environment

Describes how to set-up an Eclipse environment to build plug-ins depending on DS-5

·         Create the Configuration Database extension

Describes how to create the provider extension and produce a plug-in

·         Add the Configuration Database extension to DS-5

Describes how to install the provider plug-in into an existing DS-5 installation


You must have:

·         An Eclipse installation containing the Plug-in Development Environment (PDE)

·         A DS-5 installation

·         A Configuration Database

2.   Configure a DS-5 development environment

                                                The first task is to configure your development environment for building a plug-in that contributes to DS-5 by creating a PDE target definition. A target definition will ensure plug-in projects are built against the exact plug-in set that defines DS-5.

1.     Start Eclipse and use a new workspace

2.     Select Window → Preferences

3.     Expand the Plug-in Development group and select Target Platform


4.     Click Add

5.     Select Nothing: Start with an empty target definition


6.     Click Next

7.     Enter a name for the new definition


8.     On the Locations tab, Click Add

9.     Select Installation and click Next


10.  Click Browse and navigate to sw/eclipse relative to root of your DS-5 installation


11.  Click Finish

12.  Click Add again


13.  Select Software Site and click Next

14.  Click Add

15.  Click Archive… and navigate to sw/eclipse/ relative to the root of your DS-5 installation


16.  Give the Repository a name and click OK

17.  Select the Eclipse plug-ins for DS-5 check box

18.  Deselect the Include required software check box


19.  Click Finish

20.  Select the Environment tab

21.  Under Java Runtime Environment, select the Execution Environment check box and JavaSE-1.6 from the drop down


22.  Click Finish

23.  Select the check box of the new definition to make it active


3.   Create the Configuration Database extension

The second step is to create a new plug-in that implements the extension point for contributing Configuration Database paths.

1.     Create a new project

a)     Select File → New → Project

b)    Select Plug-in Project and click Next


c)     Give the project a name


d)    Click Next

e)     Deselect the Generate an activator… and This plug-in will make contributions to the UI check boxes


f)     Click Finish

The plug-in editor should automatically open, if it does not, open the META-INF/MANIFEST.MF file from the newly created project.

2.     Add the required plug-in dependencies

a)     Click on the Dependencies tab


b)    Click the Add button under Required Plug-ins


c)     Type com.arm.ds.extension into the text field and click Ok

d)    Click Add again

e)     Type org.eclipse.core.runtime into the text field and click Ok


3.     Declare the extension

a)     Click on the Extensions tab


b)    Click Add


c)     Select com.arm.ds.extension.configdb.pathprovider from the list and click Finish

d)    Right-click on the com.arm.ds.extension.configdb.pathprovider entry and select New → provider


e)     Change the name of the class field to the name to be given to the provider implementation class


f)     Save the project

4.     Implement the provider class

a)     Click on the class link next to the provider class name, the New Java Class dialog will open with appropriate defaults


b)    Click Finish

c)     Complete the provider implementation to return the configuration database paths as required. Below is a simple example returning a hard-coded path.


5.     Export the plug-in

a)     In the Package Explorer, right-click on the project and select Export

b)    Open the Plug-in Development group, select Deployable plug-ins and fragments and Click Next


c)     Select a directory to export the plug-in in to


d)    Click Finish

4.   Add the Configuration Database extension to DS-5

The final task is to add your Configuration Database extension to DS-5 by installing the plug-in into the existing installation.

There are several mechanisms available to install a plug-in into Eclipse, which one is most appropriate depends on the particular requirements of the provider.

·         Watched directories

Eclipse supports watched directories where a plug-in can be placed to be automatically installed when Eclipse is started. DS-5 provides two such directories:

·         Install for single user

The plug-in is placed in a user-specific configuration area, ~/.ds-5/workbench/dropins/plugins (Linux) or %APPDATA%/ARM/DS-5/workbench/dropins/plugins (Windows), and is installed for that user only.

·         Install for all users

The plug-in is placed in the main DS-5 configuration area, <DS-5 Root>/sw/eclipse/dropins/plugins, and will be available to all users.

There are two things to consider when installing plug-ins into the main DS-5 configuration area. Firstly, write permissions on the DS-5 installation are needed, which on Windows means Administrator rights are required to perform the install. Secondly, any files added to the DS-5 installation will not be removed if DS-5 is un-installed, it is the responsibility of the provider to manage the additional files.

·         Eclipse p2 director application

The p2 director application allows plug-ins to be installed into Eclipse in the same manner as plug-ins from the Software Updates dialog.

<DS-5 Root>/bin/eclipse –application org.eclipse.equinox.p2.director –nosplash   –consolelog –repository file:///work/export -installIU com.acme.configdb

The above command would install the provider plug-in into the user-specific configuration area, as DS-5 uses a cascaded configuration by default. To perform the same install for all users and install into the main configuration area, add the following options to the end of the command line:

–vmargs –Dosgi.configuration.cascaded=false

The considerations regarding permissions and un-installation discussed for the watched directories also apply to the p2 director installation.

The steps below show a simple example of using the DS-5 dropins directory, write permission to this directory is assumed.

1.     Drop the plug-in jar file from the export directory into the sw/eclipse/dropins/plugins directory relative to the root of your DS-5 installation.

2.     Start Eclipse for DS-5

3.     Select Window → Preferences

4.     Open the DS-5 group and select Configuration Database

5.     The contributed Configuration Database will be visible in the Default Configuration Databases table


Copyright © 2013 ARM Limited. All rights reserved. ARM DAI0329B