Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.
Runtime Object View (ROV)
- 1 Introduction
- 2 Getting Started Video
- 3 Installation
- 4 Starting a ROV Session
- 5 Importing a ROV Dashboard
- 6 Opening Views
- 7 Refreshing Target Data
- 8 Managing Views
- 9 Useful Views
- 10 Saving Data from Views
- 11 Working with Dashboards
- 12 Roadmap
ROV has the following key benefits:
- ROV does not disturb the run-time behavior of the application on the target (when using a JTAG connection). ROV can read current memory from a running target. ROV also automatically refreshes all of its views whenever the target is stopped--for example when single stepping, when the target hits a breakpoint, or when you halt the target asynchronously.
- ROV adds zero footprint to the target code (when using a JTAG connection).
- ROV provides visual tools that show changes in the target state, memory use, and data structures on the host computer. The tool shows high-level information needed by embedded application developers.
- ROV is provided automatically with the TI-RTOS Kernel component of the SimpleLink SDK, the Processors SDK, TI-RTOS products, and stand-alone SYS/BIOS. If you use Code Composer Studio (CCS) and any of these software products, you have access to ROV. Nothing needs to be enabled in the application code.
- ROV can be extended to work with any embedded library. The examples on this page use the TI-RTOS Kernel, which includes ROV support for its entities including threads, heap memory, and CPU load.
ROV is available in CCS 7.1 or higher. The ROV interface features you see are determined by the version of XDCtools in use. (The images on this page were created with versions up to CCS 8.3 and XDCtools v3.51.) On this page, a dagger symbol (†) indicates that a feature is available only when using XDCtools 3.51 or later. A double dagger (‡) indicates that a feature is available only when using XDCtools 3.55 or later.
Runtime Object View is an enhanced version of the RTOS Object View tool, which has been available for several years. This page refers to Runtime Object View as ROV and the older RTOS Object View tool as "ROV Classic". For information about using ROV Classic, see the ROV Classic documentation.
Getting Started Video
For a quick way to get started, watch the How to use Runtime Object View video.
ROV is available in CCS 7.1 or higher. (The images on this page were created with CCS 8.3.)
You can use the CCS App Center or TI software download pages to make sure you have the most recent version of the SimpleLink SDK, the Processors SDK, TI-RTOS, or stand-alone SYS/BIOS. These products all contain TI-RTOS and support the use of ROV in real-time applications.
Starting a ROV Session
There are several ways to use ROV.
- You can use a CCS project to load and run the image on the target.
- You can connect to a running target without using a CCS project to load the image.
Using an Image Managed by the Active CCS Project
- Use the standard CCS development cycle to build an application and load its image onto the target device.
- Start ROV as described in Connecting to ROV.
Using an Image Without a CCS Project
If you build your applications using another tool (such as makefiles), you can still use CCS and ROV for debugging. Follow these steps to configure CCS with the version and path information needed to run ROV:
- Choose Windows->Preferences from the CCS menus.
- Move to the Code Composer Studio->Products->RTSC category.
- Select the XDCtools version and the product containing TI-RTOS for your application.
- Click OK.
- Connect the CCS debugger to your application. (See Debugging Without a CCS Project for detailed steps.)
- Start ROV as described in Connecting to ROV.
Debugging Without a CCS Project
In CCS, follow these steps to create a "Target Configuration" the first time you want to use ROV with the CCS Debugger:
- Use the Resource Explorer (choose View->Resource Explorer) to import the TI-RTOS "hello" project for the LaunchPad (or another target) you are using.
- Copy the .ccxml file contained in the
targetConfigssubdirectory of the "hello" project to the
C:\Users\<username>\user\CCSTargetConfigurationsdirectory (for Windows) or the
~/ti/CCSTargetConfigurationsdirectory (for Linux/UNIX).
- In CCS, choose View->Target Configurations and expand the "User Defined" branch of the tree.
- Double-click on your
*.ccxmlfile in CCS's Target Configurations list and edit the target configuration as needed. Click Save when you are finished.
- Right-click on your
*.ccxmlfile in CCS's Target Configurations list and choose Launch Selected Configuration. (If you choose Set as Default, you can later launch this target configuration by pressing F11 or choosing Run->Debug.)
Launching the Target Configuration moves you to the Debug Perspective. In the Debug Perspective, follow these steps:
- Choose Run->Connect Target.
- You may want to choose Run->Reset at this point to reset the target.
- Choose Run->Load->Load Program and browse for the program file.
- If you load the image externally or from Flash, you can choose Run->Load->Load Symbols instead to load just the symbol information. This does not modify the target, it simply tells the debugger how to display memory and what source file line should be shown for each code address in the memory map.
Connecting to ROV
After the target is loaded and you have connected to the target with the CCS debugger, you can start ROV as follows:
- Move to the CCS Debug perspective.
- Choose Tools->Runtime Object View or click the toolbar icon:
- ROV opens and prompts you to Connect to the target. (Check the "Do not show this again" box if you want to connect automatically in the future.) In the following figure,
Debuggeris the default name for the CCS project's JTAG connection.
The icon in the lower right allows you to import a ROV local storage file that was previously exported. See Managing Local Storage.‡
Importing a ROV Dashboard
ROV uses "dashboards" to store a set of views you want to use with an application. Many examples included with TI-RTOS provide a dashboard as part of the project you import into CCS. Dashboards are stored as
Importing a dashboard makes its views available to display and collect data. When you first import a dashboard, its views are opened automatically.
To import a dashboard when you open ROV, click Open a Dashboard in the Getting Started dialog.
.rov.jsonfile for the dashboard you want to import. Many example projects contain their own ROV dashboard file, which contains views that are useful for that example.
If your SDK or TI-RTOS installation does not include dashboard files in the TI-RTOS example projects, you can download and then import a Sample ROV Dashboard File.
ROV views are visualizations of data provided by a variety of data sources associated with the libraries linked into an application. TI-RTOS, for example, has a collection of modules (roughly equivalent to C++ classes). Each module provides several data sources related to the module's target functionality.
You can automatically reopen the views from your previous session when you start ROV by clicking the ROV options icon on the right end of the ROV toolbar, selecting Startup options, and checking the Restore open views option from the options menu.†
All data sources have tabular views. To open tabular views, you can click the items outlined in red below:
- Click the name of a module in the left pane to open that module's default view.
- Select a tabular subview from the drop-down list next to the module name.
ROV also allows graphical visualizations to be designed for any collection of data sources. These visualizations may be provided with the target library or by a third-party. These visualizations are called add-ons. TI-RTOS, for example, provides add-ons for viewing stack and heap usage along with the CPU load.
To open add-on views, you can click the items outlined in red below:
- dashboard you have imported. This refreshes the arrangement of views to match the arrangement stored the last time you saved the dashboard.
Creating Your Own Table Views
You can right-click on a numeric value in a table view and select Display this cell in a custom table. This opens a new table view containing that column.†
You can add more columns to a custom table view by right-clicking on another numeric value, selecting Display this cell in an existing custom table, and clicking on the name of your custom table.
Point to a heading in a custom table to see its source module and view.
Click Cell properties and then the name of a cell to open a dialog that lets you change which value is shown in that column and the heading of that column. Click the grid icon next to a cell to bring the original view that contains that column to the top. Click Table name to edit the name of the table window.
Creating Your Own Graphical Views
You can right-click on a numeric value in a table view and select Plot this cell. This opens a custom graph that shows changes to the value you selected.†
You can add more traces to a custom graph by right-clicking on another numeric value, selecting Plot this cell in an existing graph, and clicking on the name of your custom graph.
Click Trace properties and then the name of a trace to open a dialog that lets you change which value is shown by that trace and the legend label for that trace. Point to the name of a trace to see its source module and view. Click the grid icon next to a trace to bring the table view that contains that column to the top. Click Graph name to edit the name of the graph window and Axes labels to edit the X and Y axis labels.
Refreshing Target Data
ROV reads current memory from the running target without disturbing the run-time behavior of the application on the target (when using a JTAG connection).
ROV also automatically refreshes all of its views whenever the target is stopped--for example when single stepping, when the target hits a breakpoint, or when you halt the target asynchronously. But, ROV does not require the use of breakpoints or stop-mode.
To refresh data shown in the ROV views, run your target application and do any of the following:
To change the interval at which data is refreshed, click the ROV options icon on the right end of the ROV toolbar, and select the Data retrieval settings option. In the Data retrieval settings dialog, change the refresh interval in milliseconds.
The same dialog also allows you to change the timeout period for the initial connection to the target and for reading data from the target. By default, the connection timeout is 20 seconds and the timeout for reading data is 10 seconds. If a timeout occurs, either the target connection has failed or ROV requested more data from the target than could be transmitted over the target connection in use.
You can slow the refresh rate for an individual view by clicking the More view options icon for a view and setting a divide down value next to the Repeat divider option. Click the red stop button to disable automatic refreshing of this specific view.†
Value Change and Error Indicators
When a value changes from the value that was previously retrieved from the target, it is highlighted in yellow. Hover your cursor over the yellow field to see the previous value.
When an error such as a stack overflow occurs, the corresponding field is highlighted in red. Hover your cursor over a red field to see a brief description of the error.
ROV uses the debugger's connection to read device memory without causing the target CPU to run extra instructions. For example, ARM devices can provide Debug Access Ports (DAP) that the debugger uses to access the device's entire address space (but not the CPU's cache). There is a small chance of causing a brief CPU delay if the debugger and the CPU are accessing the same memory location at the same time.
When using ROV with targets other than ARM devices or when using other types of device connections, the intrusiveness of the debugger's access to device memory may vary.
ROV remembers your changes within the current CCS session. If you close and reopen a view, the changes you have made to the way that view is displayed are remembered.
The subsections that follow describe other ways to control the appearance of ROV views.
You can drag and resize ROV views as needed. To resize a view, drag its lower-right corner.
You can use Ctrl+Left Arrow and Ctrl+Right Arrow to step through the currently open views. (On MacOS, use Cmd+Left Arrow and Cmd+Right Arrow.)†
Modules provide several subviews of the information they gather from the target. Choose a subview from the drop-down list.
Most modules provide several of the following subviews:
- Basic – Provides the most commonly important information about the instances of the module's object.
- Detailed – Provides further information about the instances of the module's object.
- Module – Provides information about the properties of the module itself.
- Raw – Provides a JSON-formatted view of the current data for the module and its instances.
Modules provide additional subviews that apply to their functionality. For example, the Hwi module provides an "Exception" subview that lists any hardware interrupt exceptions that have occurred. The HeapMem module provides a "FreeList" subview that shows allocated blocks and free memory within the heap. The Timer module provides a "Device" subview that shows information about the timer devices and their addresses, modes, interrupt, periods, and counts.
Controlling the Column Display
You can drag column headings with your mouse to change the order of columns in table views.
For tabular views, you can hide columns that don't interest you and control whether numeric values are shown in decimal, hexadecimal, or scientific notation format. These settings are remembered whenever you reopen that view within the current CCS session. They are stored when you save the dashboard. To modify the columns in a view, follow these steps:
- Uncheck any Columns you don't want displayed. For example, in a Task view, you might want to hide the curCoreId and affinity columns if this is not a multicore application.
- Change the Format for numeric columns as desired. For example, in a Task view, you might want to view the Task arguments in hex, decimal, or scientific format.
- Changes to the view are made as you use the dialog. Click the "X" to close the dialog after you have made your changes.
Using Fixed Width Font
If you want a view to use a code font such as Courier, click the More view options icon for a view and check the Use fixed width font box.
This changes the current view to fixed width.
Notice that the change does not apply to other views of the same module. For example, if you set the font for the Basic view, the Detailed view is not changed automatically. To change the font for all newly opened views, click the ROV options icon on the right end of the ROV toolbar, and select the Use fixed width font in tables option from the menu.†
Controlling the Module List
If a view for the module is already open, clicking its name brings it to the top or steps through multiple views for the same module. To open an additional view for a module, hover over the module name and click New <module> view.‡
The module list in the left pane of the ROV display can list subsets of the available modules. Use the triangle icon to select which modules to display.
- All Modules – Shows all the modules found in the target application. A number of the modules will not have views defined for use by ROV. The only view available for such modules is the Raw JSON view.
- Viewable Modules – Shows only the modules for which views other than "Raw" are available. These are the views that are more likely to be useful for debugging.
- Favorite Modules – Shows modules you have marked as a favorite. To mark a favorite module, right-click on the module name and choose Add to Favorite Modules.
You can hide the module list to make more space for views by clicking the < icon in the upper-left corner of the right ROV pane.
Managing Local Storage
ROV stores information locally about how to display views for modules. You can import and export this information, which allows you to share settings with other users and other installations of CCS.‡
The following options are available:
- Delete module storage: Check the boxes for modules you want to reset to their factory defaults. Then click Delete Selected and Close.
- Clear all ROV storage: Select this option to reset all modules to their factory defaults.
- Import local storage: Select this option to import settings from a JSON file that has been exported. You can also import settings by clicking the icon in the lower-right corner of the Connect Target dialog that is shown when you open ROV.
- Export local storage: Select this option to save your current local settings to a file. The extension of the file will be
.ros.json(for Runtime Object Settings).
Real-time kernels provide a framework for organizing application into separate threads that execute concurrently and have their own run-time stack. The first step in diagnosing an application that fails is to determine the state of each thread in the application in order to answer several basic questions:
- Is each thread executing the function it should be?
- Has any thread overrun its allocated stack space?
- Are the threads in the expected state (blocked, running, ready, ...) and do they have the right priority?
The figure below shows three thread-related views provided by the TI-RTOS library that quickly answer the questions above.
One of the main responsibilities of a real-time kernel is to "allocate" or switch the CPU between the application's threads. As a result, real-time kernels can easily monitor an application's use of the CPU.
In applications that are not operating as expected, it is natural to ask whether there is sufficient CPU resource to execute the critical threads in the system, how close is the system to overloading the CPU, and are there unexpected loads in the system (perhaps due to interrupt service routines).
The figure below shows some of the CPU load related TI-RTOS library views that provide insight into these types of questions.
To enable shared access to global heap memory, real-time kernels provide an alternative implementation of the standard C runtime malloc(). When an application fails, it's important to know whether a lack of memory may have resulted in NULL being returned to some function that does not properly handle "out of memory" conditions.
So, it's natural to ask if the application has (or is about to) run out of memory, is the heap dangerously fragmented (that is, lacks usefully sized contiguous blocks of free memory), and is there a slow leak of memory during long runs of the application?
The figure below shows three of the memory related views provided by TI-RTOS library that help answer these types of questions.
Other Commonly Useful Subviews
Other modules with useful subviews include:
- BIOS module – The "Scan for errors" subview detects any errors that would be highlighted in red in any ROV subview, including subviews you have not opened. The "Module" subview shows the thread type of the currently executing thread.
- Startup module – The "Startup State" module shows the names of the modules that have run their startup functions.
- System module – The "XDCROOT" and "XDCPATH" subviews show the path to the version of XDCtools being used to run ROV and the path to the various repositories available to ROV. These paths allow you to determine which version of various software components is actually being used.
- Hwi module – The "Exception" subview lists any hardware interrupt exceptions that have occurred.
- HeapMem module – The "FreeList" subview shows allocated blocks and free memory within the heap.
- Timer modules – The "Device" subview shows information about the timer devices and their addresses, modes, interrupt, periods, and counts.
Saving Data from Views
ROV allows you to save all data contained in a view to a file in JSON format. By default, such files are saved in your CCS project's workspace directory. Files are saved with the
.rod.json extension. (ROD stands for Runtime Object Data).
To save ROV data, do one of the following:
- Click the More view options icon in an individual view. Choose the Save data displayed in view option. For modules, the default filename contains the module path and the view name.
Working with Dashboards
Use the dashboard toolbar for dashboard-related actions: You can "save" a dashboard or "export" a dashboard.
- Saving a dashboard makes your current settings available the next time you use CCS.
- Exporting a dashboard allows you to share your view settings with other people. For example, you might export a dashboard if you want a co-worker to use it when debugging an application.
- Type a name for this dashboard. You can click the triangle to select one of your current dashboards to update.
- Type a comment if you want to provide a description of the dashboard.
- If you want to export the dashboard to a separate file, check the Export file box. Otherwise, the dashboard is only saved in your CCS workspace, and so is only available to you within this CCS project on this computer.
- Click OK.
- If you checked the Export file box, browse to the location where you want to save the exported JSON file that contains the dashboard.
You can export multiple dashboards to a single file using these steps:
- Click the ROV options icon on the right end of the ROV toolbar, and select the Export dashboards to file option from the options menu.
- Type a filename for your exported file.
- Uncheck the boxes next to any dashboards you do not want to export.
- Click Export Selected.
- Browse to the location where you want to save the exported JSON file that contains the selected dashboards.
In the future, ROV may be extended to support the following:
- Connections via UART, WiFi, and other connections
- Use of ROV as a standalone tool outside of CCS
- Views for TI Drivers
- Extensions to work with additional libraries