Getting Started with the Intel® JTAG Debugger

Document number: 317685-015US

The Intel® JTAG Debugger for Intel® Atom™ Processor (henceforth referred to as the JTAG debugger) supports system debugging on Intel Atom processor based Mobile Internet Devices (MID), including Linux* OS kernel and kernel object debugging (only when the Linux* OS Awareness plug-in is installed).

Technical Requirements

For technical requirements, see the installation guide for the JTAG Debugger.

This document assumes that all stated technical requirements are satisfied. All program examples are created with the Intel® C++ Compiler for Linux* OS. To change the set-up, an experienced engineer must make adjustments accordingly.

Connecting Host and Target System

The JTAG Debugger is a cross-debugger that runs on a host system and debugs an application on an external target. To use the JTAG Debugger, first the host and target system must be connected. The recommended connection sequence is as follows:

  1. Connect the JTAG hardware adapter to the target.
  2. Power on the adapter.
  3. Connect the USB cable to the adapter.
  4. Connect the USB cable to the host system.
  5. If you use XDP3, wait for the LEDs to change to red and green.
  6. Power on the target system.

Starting the JTAG Debugger on the Host System

To start the debugger, use the startup scripts according to your configuration as provided in the xdb install directory. Select the script xdb_<processor>_<adapter>.sh, where <processor> is the name of the processor you want to use as the target and <adapter> is the name of the JTAG probe you are using. If you are using XDP3, no adapter name is used. See xdb_install_dir/ for the exact names of the startup scripts.

To start the debugger:

Enter the following command in a shell:

xdb_install_dir/xdb/xdb_<processor>_<adapter>.sh

This script starts the debugger and the JTAG hardware adapter.

The debugger is now ready to be used.

Tip

Use the advanced options menu in the installation script to configure a default startup script. This will create a file xdb.sh in xdb_install_dir. With this option configured you can start the debugger by launching the xdb.sh script located in xdb_install_dir/xdb.sh

Note

If the debugger does not respond after start-up, terminate the debugger using the kill command from the command shell, unplug the JTAG adapter from the USB port, re-plug the JTAG adapter again, and restart the debugger.

Debugging Runtime Loaded Linux* OS Kernel Modules

This section describes how to use the JTAG Debugger and the Linux* kernel OS awareness plug-in, libguiialin.so, to do high level language debugging with full OS awareness and awareness of the load state and memory load location of all kernel modules.

The module is used by the JTAG Debugger as a target agent that provides specific (module related) kernel data. It uses the kernel's notification mechanism to trigger a JTAG event to the host debugger whenever a new module is loaded on the target system via the insmod mechanism.

The debugger then takes control over the target system and uploads all necessary data to its own data space. This consists of information related to the actually loaded module and an update of the list of modules that are currently loaded and running on the target system. The uploaded data is used on the host debugger to display the module list and to enable source level debugging within the loaded modules code including breakpoints on module initialization and cleanup procedures.

Prerequisites

Debugging the Linux* Loadable Driver (Kernel Object Module)

  1. On the target system, enter the command insmod idbntf.ko.
  2. In the debugger, select View > Linux Modules:

    3. The Kernel Modules window is opened.

    The Kernel Modules window displays the following values:

    Name Value Definition
    Module-Name String Name of the loaded module.
    Stop at Init< YES or NO Stop at the init function if it does exist.
    Stop at Exit YES or NO Stop prior to the exit call.
    Debug ID N/A or <number> Debug information is loaded to that debug ID.
    Kernel Object File N/A or "file not found" or <filename> Use the kernel object module to obtain debug information.
    Size 0x0 or <number> Size of the module without init size.
    Init-Method N/A or <address> or "post init" Address of the init method, if applicable. "Post init" occurs when there is an init function and the program is after the init function.
    Cleanup-Method N/A or <address> Address of the cleanup method.
    Arguments String Argument string stored in the module data structure.
  3. Right-click in the Kernel Modules window.

    4. The pop-up menu of the Kernel Modules windows appears:

  4. Click Add.

    5. The Module Settings dialog box is opened where you can predefine the plug-in behavior while loading the specified module.

  5. Specify the module name without extension and path.
  6. Check Stop at Init if you wish the debugger to stop the target when the kernel module is loaded.

    Note

    Stop at Init is a good break to set software breakpoints within this device driver. Since the driver is still present in memory, SW break points can be applied. Linux* OS 2.6 is paging out unused device drivers, which prevent setting breakpoints.

  7. Check Stop at Exit if you wish the debugger to stop prior calling the cleanup function and remove the module.

Example:

  1. Enter sum1 as a module name.
  2. Check Stop at Init.
  3. Choose Options > Source Directories and add the search path for the kernel module sum1.ko on the host system. For details refer to the debugger online help.

    4. This enables the debugger to load the debug symbols.

    The modules sum1.ko and sum2.ko are loaded via insmod to the target system.

    The debugger screen looks such as:

     

    The debugger stopped at the sum1.ko init function and you can now scroll through the source code and start usual debugging.

    Note

    Stopping at the init function updates the module list automatically, because the kernel notifies the debugger that it has loaded the module to the kernel space. Therefore, the Kernel Modules window might now contain more modules than only the two you entered in this example. Also note that the list only gets updated when a module is loaded on the target system. Removing one or more modules won’t trigger this mechanism.

    After the initial call of insmod idbntf.ko, the window will not update automatically. The window will refresh automatically upon the next insmod command issued on the target.

 

Further Information

For more information on the JTAG Debugger refer to the Intel® Debugger Online Help, document number 280198.

 

Legal Information

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL(R) PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
UNLESS OTHERWISE AGREED IN WRITING BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.
Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.
The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or by visiting Intel's Web Site.

Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. See http://www.intel.com/products/processor_number for details.

Cilk and Intel are trademarks of Intel Corporation in the U.S. and/or other countries.

* Other names and brands may be claimed as the property of others.

Copyright (C) 2001-2011, Intel Corporation. All rights reserved.