git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-Trace/tracealyzer_readme.txt

   1 -------------------------------------------------------------------------------\r
   2           Tracealyzer Recorder Library for FreeRTOS\r
   3 -------------------------------------------------------------------------------\r
   4 \r
   5 Tracealyzer is a sophisticated tool for tracing and visualization\r
   6 of FreeRTOS-based software systems.\r
   7 \r
   8 Tracealyzer gives an unprecedented insight into the runtime behavior, which \r
   9 speeds up debugging, validation and optimization. \r
  10 \r
  11 This, the Trace Recorder Library, is the target-side part of Tracealyzer, that\r
  12 performs the actual tracing. The resulting data can then be viewed in the\r
  13 Tracealyzer PC application, found at https://percepio.com/tracealyzer\r
  14 \r
  15 To learn more, see these links.\r
  16 \r
  17  - Getting Started (videos etc): https://percepio.com/gettingstarted\r
  18 \r
  19  - FAQ: https://percepio.com/category/faq\r
  20 \r
  21 In case you have any questions, don't hesitate to contact support@percepio.com\r
  22 \r
  23 Tracealyzer supports FreeRTOS v7.3 and newer, including Amazon FreeRTOS.\r
  24 \r
  25 -------------------------------------------------------------------------------\r
  26 Changes, v4.1.4 -> v4.1.5\r
  27 \r
  28 - Fixed a bug in the ITM stream port, that required Port 0 to be enabled.\r
  29 - Added missing include of stdio.h (needed by vTraceConsoleChannelPrintF).\r
  30 - Moved standard includes from trcRecorder.h into the .c files needing them.\r
  31 \r
  32 -------------------------------------------------------------------------------\r
  33 \r
  34 Changes, v4.1.2 -> v4.1.4\r
  35 \r
  36 - Fixed a compile error when certain FreeRTOS settings were used\r
  37 - Disabled filter support for FreeRTOS v7.3 since it uses "char" for object id\r
  38 \r
  39 -------------------------------------------------------------------------------\r
  40 \r
  41 Changes, v4.1.0 -> v4.1.2\r
  42 \r
  43 - Added vTraceConsoleChannelPrintF(...)\r
  44 \r
  45 -------------------------------------------------------------------------------\r
  46 \r
  47 Changes, v4.0.3 -> v4.1.0\r
  48 \r
  49 - Improved performance of User Events\r
  50 - Fixed handling of format strings ending with '%'\r
  51 - Improved handling of creative user configuration macros\r
  52 \r
  53 -------------------------------------------------------------------------------\r
  54 \r
  55 Changes, v4.0.2 -> v4.0.3\r
  56 \r
  57 - Minor fix for TCP/IP stream port.\r
  58 - Corrected default RTT mode setting.\r
  59 \r
  60 -------------------------------------------------------------------------------\r
  61 \r
  62 Changes, v4.0.1 -> v4.0.2\r
  63 \r
  64 - Memory allocation trace events now ignore filters.\r
  65 \r
  66 -------------------------------------------------------------------------------\r
  67 \r
  68 Changes, v4.0.0 -> v4.0.1\r
  69 \r
  70 - Minor fixes to default values.\r
  71 \r
  72 -------------------------------------------------------------------------------\r
  73 \r
  74 Changes, v3.3.0 -> v4.0.0\r
  75 \r
  76 - Fixed some issues with filters.\r
  77 \r
  78 -------------------------------------------------------------------------------\r
  79 \r
  80 Changes, v3.2.0 -> v3.3.0\r
  81 \r
  82 - Added support for FreeRTOS v10, including the new object types Message Buffer\r
  83   and Stream Buffer.\r
  84 \r
  85 - Improved the object-level filtering to also support Timer, Event Group, \r
  86   Message Buffer and Stream Buffer objects.\r
  87 \r
  88 - Fixed a few remaining build problems with older FreeRTOS versions (v7.x).\r
  89 \r
  90 - vTraceStoreISRBegin now reports an error on invalid handles, i.e., if the \r
  91   initialization of the handle (xTraceSetISRProperties) had not been made.\r
  92 \r
  93 -------------------------------------------------------------------------------\r
  94 \r
  95 Changes, v3.1.2 -> v3.2.0\r
  96 \r
  97 - Added new filtering system - that works in both snapshot and streaming mode.\r
  98   Filtering was previously not supported in streaming mode, but can be very\r
  99   useful for slower streaming interfaces. By exluding irrelevant events, the\r
 100   amount of data produced can be reduced a lot.\r
 101 \r
 102     * New functions vTraceSetFilterGroup and vTraceSetFilterMask allows for\r
 103       excluding all events from specific objects (like a semaphore or queue).\r
 104 \r
 105     * Added new "generic" filters (preprocessor level) to trcConfig.h, that\r
 106       exclude all events of a particular types.\r
 107       - TRC_CFG_INCLUDE_NOTIFY_EVENTS\r
 108       - TRC_CFG_INCLUDE_EVENT_GROUP_EVENTS\r
 109       - TRC_CFG_INCLUDE_PEND_FUNC_CALL_EVENTS\r
 110       - TRC_CFG_INCLUDE_TIMER_EVENTS\r
 111 \r
 112     * Upgraded some previous filters from "Snapshot only" to the Common API \r
 113       and thereby moved them from trcSnapshotConfig.h to trcConfig.h.\r
 114        - TRC_CFG_SCHEDULING_ONLY\r
 115        - TRC_CFG_INCLUDE_MEMMANG_EVENTS\r
 116        - TRC_CFG_INCLUDE_USER_EVENTS\r
 117        - TRC_CFG_INCLUDE_ISR_TRACING\r
 118        - TRC_CFG_INCLUDE_READY_EVENTS\r
 119        - TRC_CFG_INCLUDE_OSTICK_EVENTS\r
 120 \r
 121     * Removed the old filter system from trcSnapshotRecorder.c.\r
 122 \r
 123 - Improved streaming interface - Now only two (2) macros are needed to be \r
 124   defined in most cases, read and write. This makes it a lot easier to make\r
 125   custom stream ports.\r
 126 \r
 127     * Many definitions that were identical in most stream ports, have been\r
 128       replaced by default definitions in the recorder core. If needed, they\r
 129       can be overriden by custom definitions in trcStreamingPort.h.\r
 130 \r
 131     * Stream ports are now assumed to use recorder's internal event buffer.\r
 132       Other stream ports that writes directly to the streaming interface\r
 133       (like J-Link) should define TRC_STREAM_PORT_USE_INTERNAL_BUFFER\r
 134       as zero (0) to make it work correctly.\r
 135 \r
 136     * Macro TRC_STREAM_PORT_PERIODIC_SEND_DATA has been replaced by\r
 137       TRC_STREAM_PORT_WRITE_DATA. Together with TRC_STREAM_PORT_READ_DATA,\r
 138       this is all that is necessary for a typical stream port.\r
 139 \r
 140     * Return values from the stream port macros READ_DATA and WRITE_DATA are\r
 141       now checked. Expects 0 on success, anything else produces a warning\r
 142       that can be retrived using xTraceGetLastError() and also seen in\r
 143       Tracealyzer if a trace was produced.\r
 144 \r
 145     * Stream ports should no longer call prvPagedEventBufferInit explicitly\r
 146       (e.g. in TRC_STREAM_PORT_ON_TRACE_BEGIN). This is now called \r
 147       automatically if TRC_STREAM_PORT_USE_INTERNAL_BUFFER == 1.\r
 148 \r
 149     * Macros TRC_STREAM_PORT_ON_TRACE_BEGIN and TRC_STREAM_PORT_ON_TRACE_END\r
 150       are now unused by default and don't need to be defined.\r
 151       You can however use them to hook in some own function at these events.\r
 152 \r
 153 - Added two new stream ports\r
 154 \r
 155     * TCPIP-Win32: allows for testing the streaming on Windows ports of your\r
 156       RTOS, using Winsock.\r
 157 \r
 158     * File: example of streaming to a local file system (tested on Windows,\r
 159       but easy to modify).\r
 160 \r
 161 - Added support for FreeRTOS v9.0.1\r
 162 \r
 163     * Replaced FreeRTOS version code TRC_FREERTOS_VERSION_9_X with\r
 164       - TRC_FREERTOS_VERSION_9_0_0\r
 165       - TRC_FREERTOS_VERSION_9_0_1\r
 166 \r
 167     * Using TRC_FREERTOS_VERSION_9_X is no longer allowed.\r
 168 \r
 169 - Added additional events for xQueuePeek, for blocking and timeouts events.\r
 170 \r
 171 - Added event for traceTIMER_EXPIRED, showing when the timer callback\r
 172   function is called.\r
 173 \r
 174 - Improved diagnostics in streaming mode, in case of errors in the recorder.\r
 175 \r
 176     * Added prvTraceWarning() - registers a "warning" error code, without\r
 177       stopping the recorder. Called if READ_DATA or WRITE_DATA returns a\r
 178       non-zero value, and in several other cases where the recorder \r
 179       configuration is incorrect (e.g., too small symbol table). \r
 180 \r
 181     * Added several new warning codes (PSF_WARNING_XYZ), corresponding to the\r
 182     issues detected by prvCheckRecorderStatus.\r
 183 \r
 184     * Fixed duplicate definitions of warning messages, so the warnings reported\r
 185       to Tracealyzer are the same as those provided in xTraceGetLastError().\r
 186 \r
 187     * Added better explainations of warning/error messages in the body of\r
 188       xTraceGetLastError (in streaming mode).\r
 189 \r
 190 - Added xTraceIsRecordingEnabled() to Common API.\r
 191 \r
 192 - Added "unofficial" hardware port for Altera Nios-II. \r
 193   This is a user contribition, not yet verified by Percerpio.\r
 194 \r
 195 - Fixed bug in vTraceEnable - option TRC_START_AWAIT_HOST was ignored if already initialized. \r
 196 \r
 197 - Fixed a few remaining compiler warnings.\r
 198 \r
 199 - Changed order of some settings in trcConfig.h - moved advanced stuff to the\r
 200   bottom.\r
 201 \r
 202 - Removed SEGGER_RTT_Printf.c from the J-Link stream port since not required\r
 203   for Tracealyzer.\r
 204 \r
 205 -------------------------------------------------------------------------------\r
 206 \r
 207 Changes, v3.1.1 -> v3.1.2\r
 208 - Fixed two bugs related to User Events, one in vTracePrintF and other in vTracePrint.\r
 209 \r
 210 - Fixed a build problem related to a single reference of the old FreeRTOS type "xTaskHandle", in trcKernelPort.c.\r
 211   Changed to "TaskHandle_t", unless if using an older FreeRTOS kernel or the "compatibility mode".\r
 212 \r
 213 - Removed traceCREATE_MUTEX hook for FreeRTOS v9 or later (no longer required)\r
 214 \r
 215 - Updated the User Manual regarding snapshot trace via IAR Embedded Workbench.\r
 216 \r
 217 - Renamed vTraceGetTraceBuffer to xTraceGetTraceBuffer, since returning a pointer.\r
 218 \r
 219 -------------------------------------------------------------------------------\r
 220 \r
 221 Changes, v3.1.0 -> v3.1.1\r
 222 \r
 223 After the major changes in the v3.1.0 trace recorder library, this update \r
 224 corrects a number of minor issues. Only minor functional improvements.\r
 225 \r
 226 - You can now use TRC_ALLOC_CUSTOM_BUFFER to declare a trace buffer on a custom\r
 227   location (using linker directives). \r
 228   The related function vTraceSetRecorderDataBuffer has been promoted to the\r
 229   Common API (previously only supported in snapshot mode, but custom allocation\r
 230   is now generally supported also in streaming mode).\r
 231   \r
 232 - Removed TRC_CFG_USE_LINKER_PRAGMA. No longer necessary thanks to the custom\r
 233   allocation mode.\r
 234   \r
 235 - Added support for timestamping from custom periodic timers, required for\r
 236   accurate timestamping on Cortex-M0/M0+ devices when using tickless idle.\r
 237   Only for streaming mode so far. See TRC_CUSTOM_TIMER_INCR / DECR.\r
 238 \r
 239 - ARM Cortex-M port: Made sure the DWT unit is initialized properly, in case\r
 240   the debugger doesn't handle this.\r
 241 \r
 242 - ARM Cortex-M port: Added possibility to use Systick timestamping also on\r
 243   Cortex-M3/M4/M7 devices (that otherwise use DWT timestamping by default).\r
 244   To use this option, define the macro TRC_CFG_ARM_CM_USE_SYSTICK.\r
 245 \r
 246 - J-Link streaming: The default RTT buffer has been changed from 0 to 1.\r
 247 \r
 248 - J-Link streaming: The RTT buffer settings for buffer 1 and higher, are now\r
 249   found in trcStreamingPort.h. Note: These settings don't apply to buffer 0.\r
 250 \r
 251 - vTracePrint has been optimized for better performance in string logging.\r
 252 \r
 253 - Minor performance improvement related to symbol table transfer in streaming mode.\r
 254 \r
 255 - Timer names now registered also in streaming mode.\r
 256 \r
 257 - Timer start and stop event are now traced.\r
 258 \r
 259 - Implemented support for queue registry (traceQUEUE_REGISTRY_ADD) also for streaming.\r
 260 \r
 261 - Fixed a bug related to repeated calls of vTraceEnable.\r
 262 \r
 263 - Fixed a bug where task-switches seemed to occur even though the scheduler was disabled.\r
 264 \r
 265 - Renamed HARDWARE_PORT_TEXAS_INSTRUMENTS_TMS570_RM48, added prefix TRC.\r
 266 \r
 267 - Fixed several language issues in the comments and documentation.\r
 268 \r
 269 - Fixed several minor issues and warnings from different compilers\r
 270  (including PowerPC/gcc) and configurations.\r
 271 \r
 272 -------------------------------------------------------------------------------\r
 273  \r
 274 Changes, v3.0.9 -> v3.1.0\r
 275 \r
 276 - Merge of previously separated snapshot and streaming recorders into a single\r
 277   recorder supporting both streaming and snapshot as different modes.\r
 278   \r
 279 - New common API for supporting both streaming and snapshot modes.\r
 280   \r
 281 - New integration guide, see the User Manual.\r
 282 \r
 283 - Major improvement of API documentation in source files and User Manual.\r
 284   \r
 285 - New concept of "stream ports", giving a better structure defining streaming\r
 286   interfaces, and restructured the J-Link and TCP/IP streaming as stream ports.\r
 287   \r
 288 - Added a stream port for USB CDC connections, with STM32 as example.\r
 289   Since Tracealyzer now can receive serial data on Windows COM ports, this is\r
 290   really easy to use.\r
 291 \r
 292 - Added a warning (#error) for cases where FreeRTOS tickless idle mode is used\r
 293   together with timestamping using SysTick or other periodic interrupt timers,\r
 294   Tracing with tickless idle requires an independent time source to correctly\r
 295   capture the length of the idle periods.\r
 296  \r
 297 - Major changes in the recorder API. Important examples are:\r
 298 \r
 299   * Some configuration macros have changed names, e.g. for "hardware port".\r
 300     Make sure to remove any old "trcConfig.h" files if upgrading from an\r
 301     earlier version!\r
 302 \r
 303   * Recorder configuration in trcConfig.h has been minimized and now only \r
 304     includes the important settings that are independent of recorder mode.\r
 305     Advanced settings for each mode are found in trcSnapshotConfig.h and\r
 306     trcStreamingConfig.h.\r
 307         \r
 308   * vTraceEnable replaces Trace_Init and vTraceInitTraceData, as well as\r
 309     vTraceStart and uiTraceStart.\r
 310   \r
 311   * vTraceStop now part of the common API and thereby available also in\r
 312     streaming. And since vTraceEnable can start the streaming directly\r
 313     you have the option control the tracing from target, e.g., for\r
 314     streaming to a device file system.\r
 315   \r
 316   * vTraceStoreKernelObjectName from old streaming recorder has been replaced\r
 317     by vTraceSetQueueName, vTraceSetSemaphoreName, etc.\r
 318      \r
 319   * vTraceSetISRProperties now returns a "traceHandle" that should be passed as\r
 320     parameter to vTraceStoreISRBegin and vTraceStoreISREnd.\r
 321     \r
 322   * xTraceRegisterString has replaced the old functions xTraceOpenLabel and \r
 323     vTraceStoreUserEventChannelName. This now returns a "traceString" for use\r
 324     as "channel" parameter in vTracePrintF, and in other places where strings\r
 325     are stored.\r
 326     \r
 327   * Removed vTraceStoreISREndManual and vTraceStoreISREndAuto, use\r
 328     vTraceStoreISREnd instead.\r
 329   \r
 330   * Renamed the functions for saving User Events in a separate buffer:\r
 331      - xTraceRegisterChannelFormat  -> xTraceRegisterUBChannel\r
 332      - vTraceChannelPrintF          -> vTraceUBData\r
 333      - vTraceChannelUserEvent       -> vTraceUBEvent\r
 334   \r
 335  \r
 336 -------------------------------------------------------------------------------\r
 337 Copyright Percepio AB, 2018.