- Todo:
- review this section before release and update all screen captures
The following steps enable the MDK Debugger views for static information and dynamic events.
For User Code:
- Add Event Recorder to the project.
- Event Annotations in the C source stream dynamic event information.
- Format Event Information to match it with application code.
- Static Information of the application is formatted for ease-of-use.
During this process an *.SCVD file is created that formats the output in the MDK Debugger views.
For MDK Middleware and CMSIS-RTOS2 RTX:
The Software Packs for MDK middleware and CMSIS already contain the *.SCVD files and the related event annotations in the C source code.
- Add Event Recorder to the project.
- Debug Variants of the RTOS and middleware libraries enable event information.
Add Event Recorder
To use the Event Recorder in an application, you need to:
- Select the software component Compiler:Event Recorder using the RTE management dialog.
- Add initialization for the Event Recorder as shown below.
:
:
int main (void) {
:
HAL_Init();
SystemClock_Config();
MemoryBus_Config();
:
}
- Todo:
- other configuration requirements (i.e. for Cortex-M0/M0+)
Event Annotations
To to stream dynamic event information insert calls to the Event Data Recording functions on relevant code locations:
These Event Data Recording functions receive as first parameter an id event identifier used for filtering and displaying. The macro EventID may be used to compose id values as level and component number may be included.
Example:
int some_error = 0;
char string[10] = "MyTest";
void MyFunction (int parameter) {
:
if (some_error) {
return;
}
return;
}
int main (void) {
MyFunction (0x10);
some_error = 1;
MyFunction (0x60);
}
When executing this example in the uVision Debugger, use the menu command View - Analysis Windows - Event Recorder to open the Event Recorder window. This should show the following output:
Output shown in Event Recorder window
Format Event Information
You may create an *.SVCD (Software Component View Description) file to format the event output so that matches the application. The event output is created using the /component_viewer/events element. Sample.SVCD file
<?xml version="1.0" encoding="utf-8"?>
<component_viewer schemaVersion="0.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="Component_Viewer.xsd">
<component name="MyExample" version="1.0.0"/> <!-- name and version of the component -->
<events>
<event id="1" level="API" property="MyFunction" value="parameter=%x[val1]" info="Event on start of MyFunction" />
<event id="2" level="Error" property="MyFunctionError" info="Event on error in MyFunction" />
<event id="3" level="Op" property="MyFunctionProcess" value="string=%t[val1]" info="Event on operation in MyFunction" />
</events>
</component_viewer>
- Todo:
- use a simple file name, i.e. Sample.SVCD
In the uVision Debugger this *.SVCD file is specified in the dialog Options for Target -> Debug -> Manage Component Viewer Description Files. Click on Add Component Viewer Description File and add the related *.SVCD file.
Manage *.SVCD files
Using the above *.SVCD file displays the events as shown below.
Event Recorder output formatted with *.SVCD file
- Todo:
- show filter once it is implemented in MDK
Static Information
The *.SVCD file may also format other static information of the application using the /component_viewer/objects element.
Sample.SVCD file extended with static information
<?xml version="1.0" encoding="utf-8"?>
<component_viewer schemaVersion="0.1" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance" xs:noNamespaceSchemaLocation="Component_Viewer.xsd">
<component name="MyExample" version="1.0.0"/> <!-- name and version of the component -->
<objects>
<object name="MyProgram">
<read name="error_val" type="int32_t" symbol="some_error" />
<read name="string_val" type="int8_t" symbol="string" size="10" />
<out name="MyProgram">
<item property="some_error" value="%d[error_val]" />
<item property="string" value="%t[string_val]" />
</out>
</object>
</objects>
<events>
<event id="1" level="API" property="MyFunction" value="parameter=%x[val1]" info="Event on start of MyFunction" />
<event id="2" level="API" property="MyFunctionError" info="Event on error in MyFunction" />
<event id="3" level="Error" property="MyFunctionProcess" value="string=%t[val1]" info="Event on operation in MyFunction" />
</events>
</component_viewer>
Using the above *.SVCD file shows static information about the program. The view opens with View - Watch Windows - MyProgram.
Event Recorder output formatted with *.SVCD file
Debug Variants
The Software Packs for MDK middleware and CMSIS already contain the *.SCVD files and the related event annotations in the C source code. However you need to select Debug variants for the related software component to enable MDK Debugger views.
This example below enables event recording for the MDK-Middleware File System.
- Todo:
- explain how to enable recording once it is available in uVision
However, for more complex software components, it makes sense to use a structured approach as described in the following. Software components are frequently a black-box to the application programmer and event annotations need additional descriptions that interlinks with API related documentation.
Doxygen is frequently used to generate API documentation and event annotations may be documented in a similar way. Once the software component is framed as CMSIS-Pack, the documentation for event annotations opens using hyper-links in the Event Recorder.
Add Event Annotations
Event annotation should deliver meaningful information about the dynamic execution of a software component and can be group into the following categories using level information in the EventID.
- EventLevelError indicates when an event relates to run-time errors in the component.
- EventLevelAPI should be used when an event relates to API function calls.
- EventLevelOp refers to events that related to internal operations.
- EventLevelDetail allows to provided events with additional detailed information of operations.
The EventID also contains Event level information and s are important as then
Create *.SVCD files