Copyright © 2012 ARM Limited. All rights reserved.
Removed broken install option from section 4
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.
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 firstname.lastname@example.org 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
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
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/update-site.zip 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
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
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:
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