- 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
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.