INtime SDK Help
INScope
INtime SDK v6 > About INtime > Other system libraries > INScope
Items in this topic:

The INScope Real-time Performance Analyzer is a Windows application that allows you to trace execution of INtime applications. Trace information for thread switches, system calls, and interrupt handling appears in a graphical user interface with various tools available to allow system analysis. INScope also provides a set of interface libraries and an API that a user can call to instrument application code.

Operating INScope

Starting INScope

To start INScope, use one of these methods:

INScope's main screen displays.

Loading INScope on the target RT node

To open a new trace:

  1. Start INscope. The Trace Control dialog box, where you create a new trace, displays.
  2. Select the Target RT Node. Click on the "Nodes" button. The Node Browser dialog box displays.
  3. Select the node you want to connect to.

If you have not previously connected to the node, INscope may have to download its real-time server module (RTScope.TMP). Otherwise, INscope queries the state of the previously loaded real-time server module and makes the controls match the state.

For example, if a trace is already started, INScope detects a trace in progress and enables the Pause and End Trace buttons. Once the server is found and the state identified, the Status field displays "RTScope Loaded" and the other trace controls are enabled.

To open a saved trace:

  1. Start INscope. The Trace Control dialog box, where you create a new trace, displays
  2. Click the Cancel button.
  3. Select File>Open to open your saved trace.
Note: After an INscope session, you are prompted to close the real-time server modules.

Using the INscope API

In order to use the INscope API, include file traceapi.h and link to traceapi.lib.

Creating traces

Configuring a trace

Before running traces, you must configure the trace to meet your needs. To configure a trace:

  1. Go to the Trace Control dialog box.
  2. Click the Settings button. The Trace Configuration dialog box displays.
  3. Configure these items:
    • Trace Stop Controls tab: Specifies when to stop the trace and the maximum trace size.
    • System Layer Tracing tab: Specifies the system call layers you want to trace.
    • Interrupt Tracing tab: Specifies the interrupts you want to trace.
  4. Click the OK or Apply button to save your changes.

The main screen with the trace you specified displays.

Starting a trace

  1. Configure the trace as described in Configuring a trace
  2. Start the trace using one of these methods:
    • From the INscope User Interface by clicking the "Start Trace" button.
    • Use the trace API by having your application call start_RT_trace.

Pausing or continuing a trace

Once a trace starts, it runs until a stop condition is met or until it is explicitly stopped. To temporarily stop the trace, use one of these methods:

Once a trace is paused, you can resume it using one of these methods:

Stopping a trace

You can configure INscope traces to stop for any/none/all of the following conditions:

To stop a trace, use one of these methods:

Displaying a trace

To display a trace, stop the trace, as described in Stopping a trace (above).

If you use the options in INscope GUI to stop the trace, trace data automatically displays.

After stopping a trace using the INScope Graphical Interface or if a stop condition is achieved, the trace data automatically displays.

However, if you start a trace and leave it running when you exit INScope or if you start a trace and then cancel the "Trace Control Dialog", the trace may complete before you restart INScope. If when you start INScope a trace is available on the RT Node you have selected, you will be asked if you would like to view that trace. Click "Yes" to view the trace.

Manipulating traces

Capturing an event in a trace

You can instrument your application and use INscope to analyze trace data immediately leading up to a specific event. You can use the INscope API to programmatically start the trace when you have entered the critical part of your code, log user events for reference within the trace, and stop the trace when you detect the condition you want to analyze.

  1. Start INscope.
  2. Configure a trace with the following settings:
    Enable Watchdog Timer: No
    Watchdog Timeout Value: 0
    Stop on Buffer Full: No
    Interrupts: None
    Trace Layers: C-Library, INtime API
  3. Instrument your application code. As an example:
    // Initialization is complete, start the real work
      start_RT_trace();
    
      while(1) {
        log_RT_event(count++);
        GetAndProcessData();
        if( TestConditionsAreMet() )
          stop_RT_trace();
      }
    
  4. Start your application.
  5. When the conditions have been met and the trace is stopped, click on the "View Trace" button in the Trace Control Dialog.

Creating a general trace

To see general trends in processor usage and in execution flow for your application:

  1. Start INscope.
  2. Configure a trace with these settings:

    Enable Watchdog Timer: No
    Watchdog Timeout Value: 0
    Stop on Buffer Full: No
    Interrupts: None
    Trace Layers: C-Library, INtime API
  3. Start the trace.
  4. Start your application.
  5. Stop the trace.

You can use the thread menu items to navigate to different execution (run) segments of your application. The cursor measures times between events. To see properties of each run segment, thread, event, and trace, right click the element in question and select Properties.

Specifying interrupts to trace

To configure INscope to trace an interrupt:

  1. Highlight the desired interrupt.
  2. Click the Add button.
  3. Do one of these:
    • Select a different tab to further configure the trace.
    • Click the OK button.

Specifying system call layers to trace

To configure INscope to trace a system call layer:

  1. Highlight the desired layer in the Available Layers list.
  2. Click the Add button.
  3. Do one of these:
    • Select a different tab to further configure the trace.
    • Click the OK button.

Using the Watchdog Timer

In this scenario, an important thread in your application may be starved, suspended, or takes too long to process its data. The watchdog timer may be used to detect this condition and stop the trace so that you can observe what is causing the condition in the system.

  1. Start INscope.
  2. Configure a trace with these settings:
    Enable Watchdog Timer: Yes
    Watchdog Timeout Value: 1000 (ms)
    Stop on Buffer Full: No
    Interrupts: None
    Trace Layers: C-Library, INtime API
  3. Instrument your application code. As an example:
  4. // Inside Important Thread
    
      // Set the timeout value smaller than the timeout specified in INscope
      timeout = WATCHDOG_TIMEOUT / 2;
      start_RT_trace();
      while(1) {
        RT_I_am_alive();
        ret = ReceiveRtData(messageMailbox,&message,timeout);
        if( !ret && GetLastRtError()==E_TIME)
          continue;
    
        // Perform this thread's work...
        ProcessData();
      }
    
  5. Start the application
  6. Click View Trace data when the watchdog has timed out.
Note:   If this trace takes an extended time to complete, you can close INscope and leave the trace running. To do this, click the Trace Control Dialog box's Cancel button. You will be prompted to save the trace information in progress. Click Yes. From the menu select View>Options. Select "Cleanup RT Node Components" as "Never" or "Query on Exit" so that the RT Component will not close when you exit INscope.

Adding names to trace information

Adding names to processes and threads in the trace makes trace data more meaningful.

These names then display in the trace to help you identify the processes and threads of interest.

If you use the INscope API to start traces programmatically, you may notice that the names do not display in the trace. To force INscope to retrieve these names, use log_RT_app_start after cataloging the names you want to display.

INscope library functions

To . . . Use this system call . . .
Retrieve the current state of the INscope RT Server Component and any current traces get_RT_trace_state
Log a user-defined event in the trace buffer which can be used for reference when viewing the trace log_RT_event
Force INscope to get the filename (or cataloged name) of the running process. log_RT_app_start
Pause a trace, writing no new information to the trace buffer until the trace resumes pause_RT_trace
Reset the watchdog timer RT_I_am_alive
Start a trace using the current configuration settings start_RT_trace
Stop the trace, lock the buffer, and send a notification to INscope that a trace complete stop_RT_trace
Resume a paused trace resume_RT_trace
Save a trace file save_RT_trace