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:

• Double-click the short-cut stored in the task-bar, on the desktop, or on a toolbar.
• Start INscope.exe from the Windows command line.

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.

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:

• Click the Pause/Continue button.
• Use pause_RT_trace.

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

• Click the Pause/Continue button.
• Use resume_RT_trace.

Stopping a trace

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

• Watchdog timer
• Buffer Full

To stop a trace, use one of these methods:

• Click the End Trace button.
• Use the watchdog expiration and full buffer events.
• Use stop_RT_trace from your code.

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.

Adding names to trace information

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

• To add process names, simply catalog the process handle in the process directory using CatalogRtHandle.
• To add thread names, catalog the thread handle in the process directory

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 these library functions, link traceapi.lib in the project properties.