AM263x MCU+ SDK  10.00.00
Using SDK with Real-time Object View (ROV)

Table of Contents

Note
The steps on this page show screen shots and description based on Windows. However the steps in Linux would remain the same, unless mentioned otherwise.
The screen shots shown on this page are for AM64x MCU+ SDK v7.3.1. You would see your specific SOC and SDK version that is installed. However the instructions and steps mentioned remain the same, unless mentioned otherwise.

Introduction

Real-time Object View (ROV) in CCS IDE allows user to view the state of a executing application via different easy to understand views. These views are generated by reading information from the running SW program using the JTAG debugger port.

This section explains,

  • Using ROV with SDK examples
  • Enabling ROV in your project
  • Other important usage guidelines

Features Supported

Some of the supported ROV views are listed below

  • View task state, including free stack size (only for FreeRTOS based application)
  • View semaphore, mutex state, including which task is blocked on a semaphore and which task is holding onto a mutex (only for FreeRTOS based application)
  • View SW timer state, including the callbacks that are registered, timer period (only for FreeRTOS based application)
  • View HW interrupt state, including the ISRs that are registered and interrupt numbers that have ISRs registered. (FreeRTOS, NORTOS)
  • View system heap and common stack information like ISR stack (FreeRTOS, NORTOS)
  • View logs logged to CPU local memory via Debug module in DPL.

Features NOT Supported

  • NORTOS ROV views are limited to heap, stack, HW interrupts, memory logs.
  • ROV views for projects built using makefiles. ROV only works when the application is loaded and run via a CCS project

Using ROV with SDK examples

Attention
ROV only works when the application is loaded and run via a CCS project
  • Make sure you are able to load and run SDK examples using CCS projects (see Getting Started)
  • Halt the program as shown below. This is important, since otherwise the JTAG debugger cannot read memory for the running CPU to get the state information that ROV needs.

Halt the CPU
  • To launch ROV views, click on CCS Menu > Tools > Runtime Object View as shown below

Start ROV from CCS Menu
  • Alternatively, you can click on the "ROV" button in the CCS toolbar as shown below

Start ROV from CCS Toolbar
  • You will see a ROV window in CCS as shown below, click on "CONNECT"

ROV Window
  • This will launch the ROV viewer as shown below

ROV after its started
  • You can click on various "Viewable Modules". In current SDK, "OS Kernel" is the one which has useful views
  • After clicking on "OS Kernel", click on the drop down to see all the supported ROV views

ROV views
  • Show below is a sample after "Task Instances" view is selected

ROV task view
  • You can click on the button below to launch a new view keeping the previous view still visible

ROV new view
  • Shown below is sample with many views shown in ROV

ROV multiple active views
  • You can run the halted program after you seen the state you want to see. After running for some time, to see updated state, simply halt the CPU again, the ROV window will show the updated state.

Enabling ROV in your project

  • It is HIGHLY recommended to create your custom project using the Empty Project included in the SDK. This will not only get you all the normal project settings you need for your project but will also enable ROV in your project
  • If you have created a project on your own then, make sure
    • you add the file examples\empty\{board}\{cpu_os}\{compiler}\syscfg_c.rov.xs to your project. This file is independent of SOC, CPU, OS, compiler, so you can add this file to any of your project
    • and make sure your project points to MCU+ SDK as a dependant product. The ROV views are generated using the backend file {SDK_INSTALL_PATH}\source\kernel\freertos\rov\FreeRTOS.rov.js which is referenced by syscfg_c.rov.xs, hence the project needs to know the location of the SDK.
  • When using CCS projectspec, the line below in the .projectspec file adds the SysConfig and AM64x MCU+ SDK as dependant products for example, 
      products="sysconfig;com.ti.MCU_PLUS_SDK_AM263X"

Enabling ROV with makefile

  • Makefile examples also use the syscfg_c.rov.xs and FreeRTOS.rov.js as described in above section. In addition to this user needs to set the XDCpath to {SDK_INSTALL_PATH} in CCS preferences to enable ROV. Please note that this setting needs to be done only once per CCS installation for a given SDK release.

XDCpath addition for ROV

Important Usage Guidelines

  • You need to be connected via JTAG for ROV to read and display information from the loaded program.
  • The program needs to be in a halted state, else the JTAG debugger cannot read the SOC memory which it needs to update its views.
  • When you reload and run the program again OR you load and run a new program, you need to close current ROV window and launch ROV again.
  • Many of the FreeRTOS ROV views rely on certain FreeRTOS config to be enabled in order to show the information correctly. So if you are changing any of the below FreeRTOS config, the ROV views many NOT show all information correctly.
    • configQUEUE_REGISTRY_SIZE controls the maximum semaphores, queues, mutex's that can be viewed by ROV. If your semaphore, queue, mutex's count is more than this value then the additional objects wont be seen. In this case go and increase this value in the FreeRTOSConfig.h (source\kernel\freertos\config\{soc}\{cpu}\FreeRTOSConfig.h). Note, this only affect the objects seen in ROV view and has no effect on functionality of the created object in the program.
    • configUSE_TRACE_FACILITY MUST be 1 for ROV to show estimated free stack size for tasks. This option writes a known pattern to the task stack and ROV then checks the point at which the pattern is overwritten to find the stack used so far by the task. If you disable configUSE_TRACE_FACILITY, the free stack size may show "STACK OVERFLOW", but you can ignore this since it is not able to find a known pattern at the top of stack and concludes its a stack overflow. The other task information displayed will still be correct.
  • To make a semaphore, mutex or queue visible in ROV, you need to register the object using the below function else this object wont be visible in ROV 
      vQueueAddToRegistry(gMySemHandle, "My object name");
  • To make FreeRTOS SW timer to be visible in ROV view, it needs to be started using below function. 
      xTimerStart(gMyTimerHandle, portMAX_DELAY);
  • And when the SW timer is stopped on its own or is stopped via xTimerStop, it is no longer visible in the ROV views.
  • When using DPL Semaphore APIs, internally it calls vQueueAddToRegistry to register semaphore's and mutex's with a default name.
  • The free stack size shown for a task in ROV views, is a estimated value, and it should be used with care as listed below,
    • To reduce the time needed to read the stack memory for a known pattern and compute the free stack size, the ROV logic reads 4 bytes every 128 bytes, this allows the stack free space computation to be fast but with a accuracy loss of 128 bytes at most.
    • In some cases, if the stack truly has the pattern to be checked for ( 0xa5a5a5a5 ), then ROV views may wrongly compute that 128 bytes stack chunk as "free" when really it is not free.
  • If you have tasks with very large stacks or lot of tasks, then when task view is opened in ROV it may take a some time to compute the task stack size. In worst case, it may also timeout.
  • See Debug for more information on logging to memory.