.. _sec-rov:

TI-RTOS Object Viewer
=====================

Debuggers may include the RTOS Object Viewer (ROV) plug-in that provides
insight into the current state of TI-RTOS, including task states, stacks, and
so forth.

This section discusses some ROV views useful for debugging and profiling. More
details can be found in the TI-RTOS User's Guide, including documentation on
how to add log events to application code.

.. ifconfig:: device == 'cc2640'

  There exists a known issue when using the auto sized heap configuration
  (default) with ROV for IAR.

  .. code-block:: none

      Caught exception in view init code: "C:/ti/xdctools_x_xx_xx_xx_core/packages/xdc/rov/StructureDecoder.xs",
      line 518: java.lang.Exception: Target memory read failed at address:
      <VALID_ADDR>, length: 32 This read is at an INVALID address according to the
      application's section map. The application is likely either uninitialized or
      corrupt."

  Where <VALID_ADDR> refers to a valid address within the device's memory, and
  xdctools_x_xx_xx_xx_core is the specific version of XDCTools that is used.

  This error is benign and caused because ROV is unable to find symbols related
  to the start and end of the heap in the .out file. There are two ways to work
  around this.

   1. Use statically sized heap
   2. Apply the fix in `This E2E thread <https://e2e.ti.com/support/wireless-connectivity/bluetooth/f/538/t/770333>`_.


Scanning the BIOS for Errors
----------------------------

The BIOS ``Scan for errors`` view goes through the available ROV modules and
reports on errors. This functionality can be a good point to start if anything
has gone wrong. This scan only shows errors related to TI-RTOS modules and only
the errors it can catch.

.. figure:: /debugging/resources/rov_bios_scan.png
    :align: center

    Scan for errors. Here a Task Stack has been overrun.


Viewing the State of Each Task
------------------------------

.. XXX BLE only example with reference to ICall

The Task ``Detailed`` view is useful for seeing the state of each task and its
related runtime stack usage. This example shows the state the first time the
user-thread is called. :numref:`fig_rov_task_detailed` shows the Bluetooth low
energy stack task, represented by its ICall proxy, the Idle task, the
simple\_peripheral task and the GAPRole task.

.. _fig_rov_task_detailed:
.. figure:: /debugging/resources/rov_task_detailed.png
    :align: center

    Detailed view of the Tasks. Notice the address of the overrun task matches
    the instance id from Scan for errors.

The following list explains the column in :numref:`fig_rov_task_detailed`

address

    This column shows the memory location of the ``Task_Struct`` instance for
    each task.

priority

    This column shows the TI-RTOS priority for the task.

mode

    This column shows the current state of the task.

fxn

    This column shows the name of the entry function of the task.

arg0, arg1

    These columns show arbitrary values that can be given to entry function of
    the task. In the image, the ICall\_taskEntry is given 0xb001, which is the
    flash location of the entry function of the RF stack image and 0x20003a30
    (the location of bleUserCfg\_t user0Cfg, defined in main()).

stackPeak

    This column shows the maximum run-time stack memory used based on watermark
    in RAM, where the stacks are prefilled with 0xBE and there is a sentinel
    word at the end of the run-time stack.

.. note::
    Function calls may push the stack pointer out of the run-time stack, but
    not actually write to the entire area. A stack peak near stackSize but not
    exceeding it may indicate stack overflow.

stackSize

    This column shows the size of the runtime stack, configured when
    instantiating a task.

stackBase

    This column shows the logical top of the runtime stack of the task (usage
    starts at stackBase + stackSize and grows down to this address).


Viewing the System Stack
------------------------

The Hwi ``Module`` view allows profiling of the system stack used during boot
or for main(), Hwi execution, and Swi execution.  See
:ref:`sec-memory-management-system-stack` for more information on the system
stack.

.. figure:: /debugging/resources/rov_hwi_module.png
    :align: center

    Viewing the System Stack in Hwi

The hwiStackPeak, hwiStackSize, and hwiStackBase can be used to check for
system stack overflow.
