Tracealyzer for Cesium RTOS

tracealyzer logo

 Integration Guide For Cesium RTOS

Cesium RTOS provides developers with extensive trace capabilities for monitoring the creation, use, and deletion of tasks and kernel objects. Taking advantage of these capabilities requires that a suitable trace recorder be added to your project. For a seamless experience, Cesium RTOS has been redesigned to support Percepio Tracealyzer® out-of-the-box. This guide will walk you through the steps involved in integrating this powerful tool into your Cesium-based products.

Cs/OS3

For projects using the Cesium Cs/OS3 kernel, verify that you are using v3.09.04 or later.

    1. Download Weston Embedded's fork of the TraceRecorder repository.
    2. Copy the .c/.h files from the following folders to your Build. The streamport you choose will depend on your debug environment; in this example we use are using the Jlink_RTT port.  
      \
      \include
      \kernelports\Cs-OS3
      \kernelports\Cs-OS3\include
      \streamports\<*>
      \streamports\<*>\include

      Screenshot_2025-02-17_134011.png

    3. Copy the configuration files from the following folders to your application's central config folder.
      \config
      \kernelports\Cs-OS3\config
      \streamports\<*>\config
      Screenshot_2025-02-17_142337.png

    4. Add the appropriate include paths to your preprocessor configuration.
      Screenshot_2025-02-17_143202.png

    5. Modify os_cfg.h to enable kernel tracing by setting OS_CFG_TRACE_EN to 1.
      Screenshot_2025-02-17_143510.png

      1. You may choose to enable Enter and Exit trace points by setting OS_CFG_TRACE_API_ENTER_EN and OS_CFG_TRACE_API_EXIT_EN to 1 respectively.
        This will add additional context to your traces, but may overwhelm some debuggers when using streaming trace.

    6.  In trcConfig.h set TRC_CFG_HARDWARE_PORT to the architecture used. For some hardware ports you need to #include the processor header file by replacing the row #error "Trace Recorder: Please include your processor's header file here and remove this line.". If the error line is removed and your project compiles, the header file isn’t needed. All available hardware ports can be found at the bottom of trcDefines.h.
      Screenshot_2025-02-17_152540.png

    7. In trcKernelPortConfig.h, make sure TRC_CFG_CPU_CLOCK_HZ is set to the CPU clock frequency in Hz and TRC_CFG_USE_TRACEALYZER_RECORDER is set to 1.
      Screenshot_2025-02-17_154453.png

    8. In your application code, insert a call to OS_TRACE_INIT() before the call to OSInit().
      Screenshot_2025-02-17_154949.png

    9. Place a call to OS_TRACE_START() at the point which you wish to start recording trace events. For streaming trace, this is all you need to do.
      However, if you use the RingBuffer streamport to take snapshot traces you must include a call to OS_TRACE_STOP() where you wish the snapshot to conclude.
      Screenshot_2025-02-17_160259.png

    10. In certain situations, you may wish to pass an option to the Trace Start function to control when and how tracing begins. You may do so using the native Trace API instead of OS_TRACE_START().
      Screenshot_2025-02-19_143522.png

 

Cs/OS2

For projects using the Cesium Cs/OS2 kernel, verify that you are using v2.93.07 or later.

    1. Download Weston Embedded's fork of the TraceRecorder repository.
    2. Copy the .c/.h files from the following folders to your Build. The streamport you choose will depend on your debug environment; in this example we use are using the Jlink_RTT port.  
      \
      \include
      \kernelports\Cs-OS2
      \kernelports\Cs-OS2\include
      \streamports\<*>
      \streamports\<*>\include

      Screenshot_2025-02-17_144909.png

    3. Copy the configuration files from the following folders to your application's central config folder.
      \config
      \kernelports\Cs-OS2\config
      \streamports\<*>\config
      Screenshot_2025-02-17_145153.png

    4. Add the appropriate include paths to your preprocessor configuration.
      Screenshot_2025-02-17_145704.png

    5. Modify os_cfg.h to enable kernel tracing by setting OS_TRACE_EN to 1.
      Screenshot_2025-02-17_145910.png

      1. You may choose to enable Enter and Exit trace points by setting OS_TRACE_API_ENTER_EN and OS_TRACE_API_EXIT_EN to 1 respectively.
        This will add additional context to your traces, but may overwhelm some debuggers when using streaming trace.

    6.  In trcConfig.h set TRC_CFG_HARDWARE_PORT to the architecture used. For some hardware ports you need to #include the processor header file by replacing the row #error "Trace Recorder: Please include your processor's header file here and remove this line.". If the error line is removed and your project compiles, the header file isn’t needed. All available hardware ports can be found at the bottom of trcDefines.h.
      Screenshot_2025-02-17_152540.png

    7. In trcKernelPortConfig.h, make sure TRC_CFG_CPU_CLOCK_HZ is set to the CPU clock frequency in Hz and TRC_CFG_USE_TRACEALYZER_RECORDER is set to 1.
      Screenshot_2025-02-17_154453.png

    8. In your application code, insert a call to OS_TRACE_INIT() before the call to OSInit().
      Screenshot_2025-02-17_160040.png

    9. Place a call to OS_TRACE_START() at the point which you wish to start recording trace events. For streaming trace, this is all you need to do.
      However, if you use the RingBuffer streamport to take snapshot traces you must include a call to OS_TRACE_STOP() where you wish the snapshot to conclude.
      Screenshot_2025-02-17_160152.png

    10. In certain situations, you may wish to pass an option to the Trace Start function to control when and how tracing begins. You may do so using the native Trace API instead of OS_TRACE_START().
      Screenshot_2025-02-19_144940.png
CONTACT US FOR MORE INFORMATION