Updated documentation (Event Recorder configuration).

Author: VladimirUmek

DoxyGen/General/src/cmsis_freertos.txt

@@ -142,12 +142,11 @@ settings.
 
 \image html freertos_config_h_native.png
 
-  
+
 \subsection native_freertos_er Add Event Recorder Visibility
-- To use the Event Recorder together with FreeRTOS, add the software components <b>\::Compiler:Event Recorder</b> and
-  <b>\::RTOS:Event Groups</b> to your project.
-- Add this include: \c \#include \c "EventRecorder.h"
-- Call <b>EventRecorderInitialize(EventRecordAll, 1);</b> in your application code (ideally in \c main()).
+- To use the Event Recorder together with FreeRTOS, add the software component <b>\::Compiler:Event Recorder</b> to your project.
+- Edit \ref native_freertos_config "FreeRTOSConfig.h" and add Event Recorder configuration definitions (see \ref cmsis_freertos_evr_config)
+- Call <b>EvrFreeRTOSSetup();</b> in your application code (ideally in \c main()).
 - If you are using simulation mode, add an initialization file with the following content:
   \code
   MAP 0xE0001000, 0xE0001007 READ WRITE 
@@ -161,8 +160,7 @@ settings.
   \endcode
 - Build the application code and download it to the debug hardware or run it in simulation.
 
-Once the target application generates event information, it can be viewed in the µVision debugger using the \b Event
- \b Recorder.
+Once the target application generates event information, it can be viewed in the µVision debugger using the <b>Event Recorder</b>.
 
 
 \section cmsis_freertos Create a CMSIS-FreeRTOS project
@@ -193,28 +191,43 @@ When you have created the CMSIS-FreeRTOS project, you can configure the real-tim
 
 The following settings are available:
 
-Name                           | \#define                           | Description                                                |
--------------------------------|------------------------------------|------------------------------------------------------------|
-Minimal stack size [words]     | configMINIMAL_STACK_SIZE           | Stack for idle task and default task stack in words.       |
-Total heap size [bytes]        | configTOTAL_HEAP_SIZE              | Heap memory size in bytes.                                 |
-Kernel tick frequency [Hz]     | configTICK_RATE_HZ                 | Kernel tick rate in Hz.                                    |
-Timer task stack depth [words] | configTIMER_TASK_STACK_DEPTH       | Stack for timer task in words.                             |
-Timer task priority            | configTIMER_TASK_PRIORITY          | Timer task priority.                                       |
-Timer queue length             | configTIMER_QUEUE_LENGTH           | Timer command queue length.                                |
-Use time slicing               | configUSE_TIME_SLICING             | Enable setting to use time slicing.                        |
-Idle should yield              | configIDLE_SHOULD_YIELD            | Control Yield behavior of the idle task.                   |
-Check for stack overflow       | configCHECK_FOR_STACK_OVERFLOW     | Enable or disable stack overflow checking.                 |
-Use idle hook                  | configUSE_IDLE_HOOK                | Enable callback function call on each idle task iteration. |
-Use tick hook                  | configUSE_TICK_HOOK                | Enable callback function call during each tick interrupt.  |
-Use daemon task startup hook   | configUSE_DAEMON_TASK_STARTUP_HOOK | Enable callback function call when timer service starts.   |
-Use malloc failed hook         | configUSE_MALLOC_FAILED_HOOK       | Enable callback function call when out of dynamic memory.  |
+Name                           | \#define                             | Description                                                           |
+-------------------------------|--------------------------------------|-----------------------------------------------------------------------|
+Minimal stack size [words]     | configMINIMAL_STACK_SIZE             | Stack for idle task and default task stack in words.                  |
+Total heap size [bytes]        | configTOTAL_HEAP_SIZE                | Heap memory size in bytes.                                            |
+Kernel tick frequency [Hz]     | configTICK_RATE_HZ                   | Kernel tick rate in Hz.                                               |
+Timer task stack depth [words] | configTIMER_TASK_STACK_DEPTH         | Stack for timer task in words.                                        |
+Timer task priority            | configTIMER_TASK_PRIORITY            | Timer task priority.                                                  |
+Timer queue length             | configTIMER_QUEUE_LENGTH             | Timer command queue length.                                           |
+Preemption interrupt priority  | configMAX_SYSCALL_INTERRUPT_PRIORITY | Maximum priority of interrupts that are safe to call FreeRTOS API.    |
+Use time slicing               | configUSE_TIME_SLICING               | Enable setting to use time slicing.                                   |
+Idle should yield              | configIDLE_SHOULD_YIELD              | Control Yield behavior of the idle task.                              |
+Check for stack overflow       | configCHECK_FOR_STACK_OVERFLOW       | Enable or disable stack overflow checking.                            |
+Use idle hook                  | configUSE_IDLE_HOOK                  | Enable callback function call on each idle task iteration.            |
+Use tick hook                  | configUSE_TICK_HOOK                  | Enable callback function call during each tick interrupt.             |
+Use daemon task startup hook   | configUSE_DAEMON_TASK_STARTUP_HOOK   | Enable callback function call when timer service starts.              |
+Use malloc failed hook         | configUSE_MALLOC_FAILED_HOOK         | Enable callback function call when out of dynamic memory.             |
+Queue registry size            | configQUEUE_REGISTRY_SIZE            | Define maximum number of queue objects registered for debug purposes. |
+
+<b> Event Recorder Configuration </b>
+
+The following settings are available (see \ref cmsis_freertos_evr_config for details):
+
+Name                           | \#define                             | Description                                                                             |
+-------------------------------|--------------------------------------|-----------------------------------------------------------------------------------------|
+Initialize Event Recorder      | configEVR_INITIALIZE                 | Initialize Event Recorder before FreeRTOS kernel start.                                 |
+Setup recording level filter   | configEVR_SETUP_LEVEL                | Enable configuration of FreeRTOS events recording level.                                |
+Task functions                 | configEVR_LEVEL_TASKS                | Define event recording level bitmask for events generated from Tasks functions.         |
+Queue functions                | configEVR_LEVEL_QUEUE                | Define event recording level bitmask for events generated from Queue functions.         |
+Timer functions                | configEVR_LEVEL_TIMERS               | Define event recording level bitmask for events generated from Timer functions.         |
+Event Groups functions         | configEVR_LEVEL_EVENTGROUPS          | Define event recording level bitmask for events generated from Event Groups functions.  |
+Heap functions                 | configEVR_LEVEL_HEAP                 | Define event recording level bitmask for events generated from Heap functions.          |
+Stream Buffer functions        | configEVR_LEVEL_STREAMBUFFER         | Define event recording level bitmask for events generated from Stream Buffer functions. |
 
 
 \subsection cmsis_freertos_er Add Event Recorder Visibility
-- To use the Event Recorder together with FreeRTOS, add the software component <b>\::Compiler:Event Recorder</b> to your
-  project.
-- Add this include: \c \#include \c "EventRecorder.h"
-- Call <b>EventRecorderInitialize(EventRecordAll, 1);</b> in your application code (ideally in \c main()).
+- To use the Event Recorder together with FreeRTOS, add the software component <b>\::Compiler:Event Recorder</b> to your project.
+- Call <b>osKernelInitialize</b> in your application code (ideally in \c main()) to setup Event Recorder according to configuration settings. 
 - If you are using simulation mode, add an initialization file with the following content:
   \code
   MAP 0xE0001000, 0xE0001007 READ WRITE 
@@ -228,8 +241,56 @@ Use malloc failed hook         | configUSE_MALLOC_FAILED_HOOK       | Enable cal
   \endcode
 - Build the application code and download it to the debug hardware or run it in simulation.
 
-Once the target application generates event information, it can be viewed in the µVision debugger using the \b Event
- \b Recorder.
+Once the target application generates event information, it can be viewed in the µVision debugger using the <b>Event Recorder.</b>
+
+\section cmsis_freertos_evr_config Configure Event Recorder
+
+This section describes the configuration settings for the <a href="http://www.keil.com/pack/doc/compiler/EventRecorder/html/index.html" target="_blank">Event Recorder</a>
+annotations. For more information refer to section \ref native_freertos_er "Add Event Recorder Visibility to native FreeRTOS project" or
+\ref cmsis_freertos_er "Add Event Recorder Visibility to CMSIS-FreeRTOS project".
+
+Use below definitions to configure Event Recorder initialization and recording level filter setup.
+
+\code
+#define configEVR_INITIALIZE
+\endcode
+
+Value  | Description                           |
+-------|---------------------------------------|
+0      | Disable Event Recorder initialization |
+1      | Enable Event Recorder initialization  |
+
+Definition configEVR_INITIALIZE enables Event Recorder initialization during execution of function \ref EvrFreeRTOSSetup. Default value is \token{1}.
+
+\code
+#define configEVR_SETUP_LEVEL
+\endcode
+
+Value  | Description                           |
+-------|---------------------------------------|
+0      | Disable recording level filter setup  |
+1      | Enable recording level filter setup   |
+
+Definition configEVR_SETUP_LEVEL enables setup of recording level filter for events generated by FreeRTOS. Recording level is configured during execution of function \ref EvrFreeRTOSSetup. Default value is \token{1}.
+
+\code
+#define configEVR_LEVEL_TASKS
+#define configEVR_LEVEL_QUEUE
+#define configEVR_LEVEL_TIMERS
+#define configEVR_LEVEL_EVENTGROUPS
+#define configEVR_LEVEL_HEAP
+#define configEVR_LEVEL_STREAMBUFFER
+\endcode
+
+Value  | Description                                       |
+-------|---------------------------------------------------|
+0x00   | Disable event generation                          |
+0x01   | Enable generation of error events                 |
+0x05   | Enable generation of error and operational events |
+0x0F   | Enable generation of all events                   |
+
+Definitions configEVR_LEVEL_x set the recording level bitmask for events generated by each function group. They are taken into account only when recording level filter setup is enabled. Default value is \token{0x05}.
+
 */
 
 

DoxyGen/General/src/freertos_evr.txt

@@ -1,3 +1,36 @@
+
+/**
+\defgroup freertos_setup Event Recorder Setup
+\ingroup freertos_specific
+\brief Information about Event Recorder configuration and setup
+\details
+CMSIS-FreeRTOS interfaces to the
+<a href="http://www.keil.com/pack/doc/compiler/EventRecorder/html/index.html" target="_blank"><b>Event Recorder</b></a>
+to provide event information which helps you to understand and analyze the operation.
+
+To use the Event Recorder together with CMSIS-FreeRTOS, it is required to create an image that generates event information.
+The steps are described under \ref cre_freertos_proj.
+@{
+*/
+
+/**
+\fn void EvrFreeRTOSSetup (void)
+\details
+The function \b EvrFreeRTOSSetup initializes Event Recorder and configures recording level filter. It must be called before any event is sent to the Event Recorder.
+
+Behavior of this function execution is defined with Event Recorder Configuration (\ref cmsis_freertos_evr_config). Calling this function has
+no effect when Event Recorder component is not selected.
+
+\note \b EvrFreeRTOSSetup is called by function \b osKernelInitialize when CMSIS-RTOS2 API is in use and should not be called explicitly.
+
+
+
+*/
+
+/**
+@}
+*/
+
 /** 
 \defgroup freertos_evr Event functions
 \ingroup freertos_specific