Creating an OS awareness extension
The debugger searches for OS awareness extensions in its configuration database. All files pertaining to a particular extension must be located in a folder or at the root of a Java Archive (JAR) file in the configuration database
The actual name of the folder or JAR file is not relevant and is not shown anywhere. Within this folder or JAR file, the debugger looks for a file named extension.xml to discover the OS awareness extension.
This file contains the following information:
- The OS name, description, and, optionally, a logo to display in the OS Awareness selection pane.
- The root Python script or Java class providing the actual implementation.
- The details of cores, architectures, or platforms this implementation applies to.
You can create a new OS awareness extension by directly modifying the configuration database in the DS-5 installation folder with appropriate access privileges, but this is not recommended.
Instead, create a new configuration database folder, containing an empty folder named OS (upper case):
<some folder> /mydb /OS
Then, add mydb to the known configuration databases in the Eclipse preferences panel for DS-5.
- In Eclipse, go to menu Windows > Preferences, then expand the DS-5 node and select Configuration Database.
- Then click Add and enter the path to
Figure 14-1 Eclipse preferences for mydb
NoteThe some folder entry is represented by /work/projects in the figure.
- Now, add the OS awareness extension in mydb/OS. To do so, create a new
folder named myos containing the following
<some folder> /mydb /OS /myos /extension.xml /messages.properties
As explained earlier, extension.xml declares the OS awareness extension. The schema describing the structure of file extension.xml can be found in the DS-5 installation folder at sw/debugger/configdb/Schemas/os_extension.xsd.
The file messages.properties contains all user-visible strings. The file format is documented here:
Having user-visible strings in a separate file allows them to be translated. The debugger searches for translations in the following order in the named files:
messages_<language code>_<country code>.properties,
- And finally in
Language and country codes are defined here respectively:
- Consider the following content to start adding support for
<?xml version="1.0" encoding="UTF-8"?> <os id="myos" version="5.15" xmlns="http://www.arm.com/os_extension"> <name>myos.title</name> <description>myos.desc</description> <provider><!-- todo --></provider> </os>
NoteThe version attribute in the
oselement refers to the API version, which is aligned with the version of DS-5 that the API was made public with. You must set the version attribute to the DS-5 version that the OS awareness extension was developed in, or the lowest version that it was tested with. The debugger does not display any extensions that require a higher version number. However, as the API is backwards compatible, the debugger displays extensions with earlier API versions. The earliest API version was 5.15.
myos.title=My OS myos.desc=This is My OS. myos.help=Displays information about My OS.
This is sufficient for the OS awareness extension to appear in the Eclipse debug configuration, even though the implementation is obviously not complete and would cause errors if it is used for an actual debugger connection at this stage:
Figure 14-2 Custom OS awareness displayed in Eclipse Debug Configurations dialog
myos.helpstring is only visible from the debugger's command line interface, for instance, when typing help myos once connected.
Using the extension.xml, you can include a reference to an image file to be shown above the description in the OS Awareness tab. Supported image formats are .BMP, .GIF, .JPEG, .PNG, and .TIFF.
Also, it is possible to control the targets for which the OS awareness extension is available.
The complete XML schema for extension.xml file is available in [DS-5 install folder]/sw/debugger/configdb/Schemas/os_extension.xsd.