Event Recorder  Version 1.0.0
MDK Debugger Views for Status and Event Information
 All Files Functions Macros Groups Pages
Using Debug Views
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:

  1. Add Event Recorder to the project.
  2. Event Annotations in the C source stream dynamic event information.
  3. Format Event Information to match it with application code.
  4. 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.

  1. Add Event Recorder to the project.
  2. 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.
    SelEventRecorder.png
  • Add initialization for the Event Recorder as shown below.
    :
    #include "EventRecorder.h" // Keil::Compiler:Event Messaging
    :
    int main (void) {
    :
    HAL_Init(); // configure hardware abstraction layer
    SystemClock_Config(); // configure system clock
    MemoryBus_Config(); // configure external memory bus
    EventRecorderInitialize (EventRecordAll, 1); // initialize and start Event Recorder
    :
    // other application code
    }
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:

#include "EventRecorder.h" // Keil::Compiler:Event Messaging
int some_error = 0; // error flag
char string[10] = "MyTest"; // some test string
void MyFunction (int parameter) {
EventRecord2 (1+EventLevelAPI, parameter, 0); // Event at Start
:
if (some_error) {
EventRecord2 (2+EventLevelError, 0, 0); // Event at Error
return;
}
EventRecordData (3+EventLevelOp, string, sizeof(string)); // Event at Finish
return;
}
int main (void) {
EventRecorderInitialize (EventRecordAll, 1); // initialize and start Event Recorder
MyFunction (0x10);
some_error = 1; // set error flag
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:

EventOutput1.png
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_SCVD_Files.png
Manage *.SVCD files

Using the above *.SVCD file displays the events as shown below.

EventOutput2.png
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.

StaticOutput.png
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.

SelSWComp.png
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