MyComponent implements a data transfer using the functions MyComp_initialize, MyComp_send, and MyComp_receive. During operation, the component calls event functions that provide event data for recording by the Event Recorder.

This example shows how to:

add event annotations to a software component
create an SCVD file for status and event displays in the MDK debugger
create Doxygen documentation that utilizes the MDK context help system
create a software pack using the CMSIS-Pack standard

Add Event Annotations

It is possible to add Event Annotations pragmatical as explained in the section Using Event Recorder. However, for more complex software components, it makes sense to use a structured approach as described in the following.

Event annotation should deliver meaningful information about the dynamic execution of a software component and can be grouped 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.

Instead of using the general purpose Event Data Recording functions, specify component specific functions that can be tagged with an EventID. These component specific functions are calling then the Event Data Recording functions.

The event recorder functions for the MyComponent software component are using severity level information in their EventIDs (refer to the file EvrMyComponent.h in the example project):

#define EvtMyCo_No 0x0A     
 
// Event id list for "MyComponent"
#define EvtMyCo_InitEntry         EventID (EventLevelAPI,   EvtMyCo_No, 0x00)
#define EvtMyCo_InitStatus        EventID (EventLevelAPI,   EvtMyCo_No, 0x01)
#define EvtMyCo_SendNoData        EventID (EventLevelError, EvtMyCo_No, 0x0A)
#define EvtMyCo_SendComplete      EventID (EventLevelOp,    EvtMyCo_No, 0x0B)
#define EvtMyCo_SendFailed        EventID (EventLevelError, EvtMyCo_No, 0x0C)
#define EvtMyCo_ReceiveNoData     EventID (EventLevelError, EvtMyCo_No, 0x15)
#define EvtMyCo_ReceiveComplete   EventID (EventLevelAPI,   EvtMyCo_No, 0x16)
#define EvtMyCo_ReceiveFailed     EventID (EventLevelError, EvtMyCo_No, 0x17)

The EventID also contains information about the component number (to identify the event) and the specific message number that is used to display additional information in the Event Recorder window.

Create an SCVD file

The SCVD file for MyComponent uses this message number information to display the correct messages in Event Recorder.

<!-- event list for MyComponent -->
    <events>   
      <group>
        <component name="MyComponent"  brief="MyCo"    no="0x0A"  prefix="EvrMyCo_"     info="My Component - Demo example"/>
      </group>
      <event id="0xA00" level="API"    property="InitEntry"                             info="Event on MyComp_initialize start"/>
      <event id="0xA01" level="API"    property="InitStatus"                            info="Event on MyComp_initialize return"/>
      <event id="0xA0A" level="Error"  property="SendNoData"                            info="Event on MyComp_initialize return"/>
      <event id="0xA0B" level="Op"     property="SendComplete"    value="size=%d[val1]" info="Event on MyComp_send - completed"/>
      <event id="0xA0C" level="Error"  property="SendFailed"      value=""              info="Event on MyComp_send - send failed"/>
      <event id="0xA15" level="Error"  property="ReceiveNoData"   value=""              info="Event on MyComp_receive - no data received"/>
      <event id="0xA16" level="Op"     property="ReceiveComplete" value="size=%d[val1]" info="Event on MyComp_receive - completed"/>
      <event id="0xA17" level="Error"  property="ReceiveFailed"   value=""              info="Event on MyComp_receive - receive failed"/>
  </events>

Event Recorder displaying the event annotations

Generate documentation

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. Using this approach, event annotations can be documented in a similar way. Once the software component is framed as a CMSIS-Pack, the documentation for event annotations opens using hyperlinks in the Event Recorder.

A full documentation of the software component is available in the software pack that is built in the next step. You will find the Doxygen source code in ./SCVD_Examples/MyComponent/Doxygen. Run the script gen_doc.bat to create the documentation.

Create a pack

CMSIS-Pack describes a mechanism to deliver software components, device parameters, and evaluation board support. The XML-based package description file (PDSC) describes the content of a software pack (file collection) that may include:

Source code, header files, and software libraries
Documentation and source code templates
Device parameters along with startup code and programming algorithms
Example projects

For the software component "MyComponent", as pack is available in the directory ./SCVD_Examples/MyComponent_Pack. Double-click MyVendor.MyComponent.1.0.0.pack to install it on your system. It contains one software component called :MyVendor:MyComponent with related documentation.

MyComponent in the Manage Run-time Environment window

The PDSC file is very simple. It declares a single software component that comes with source files, SCVD and HTML documentation:

<component Cclass="MyVendor" Cgroup="MyComponent" Cversion="1.0.0" condition="Cortex-M Device">
  <description>MyComponent software component example</description>
  <files>
    <file category="header" name="Source/MyComponent.h"/>
    <file category="source" name="Source/MyComponent.c"/>
    <file category="doc"    name="html/index.html"/>
    <file category="other"  name="Source/MyComponent.scvd"/>
  </files>
</component>

An example project called "MyComponent Pack Example" is also part of the pack. It is basically the same example as SCVD in MyComponent, only that it is using the "MyComponent" software component.

If you build and run the example, you will see that the events that are recorded now contain hyperlinks that bring up the related documentation.

Event recorder links to related documentation

With this, you can create re-usable software components that can be equipped with Event Recorder information and related documentation. This is useful if you intend to share the software component within your company or with third parties.