path: root/doc/book-enea-linux-user-guide/doc/using_eclipse.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="use_eclipse">
  <title>Using Eclipse</title>

  <section id="install_eclipse">
    <title>Installing Eclipse</title>

    <para>For instructions on how to install Eclipse Oxygen, please refer to
    the <ulink
    url="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#adt-eclipse">Yocto
    Project Software Development Kit (SDK) Developer's Guide</ulink>, chapter
    4.3.2.1. Although the instructions listed there currently, refer to the
    Neon release of Eclipse, the same steps still apply to the Oxygen release,
    with some small differences:</para>

    <itemizedlist>
      <listitem>
        <para>In <emphasis role="bold">step 1</emphasis> from chapter
        4.3.2.1.1, the URL for downloading Eclipse should be <ulink
        url="http://www.eclipse.org/oxygen">http://www.eclipse.org/oxygen</ulink>
        instead.</para>
      </listitem>

      <listitem>
        <para>In <emphasis role="bold">step 3</emphasis> from chapter
        4.3.2.1.2, the correct option in the drop-down menu should look like:
        <emphasis>Oxygen -
        http://download.eclipse.org/releases/oxygen</emphasis>.</para>
      </listitem>

      <listitem>
        <para>In <emphasis role="bold">step 5</emphasis> from chapter
        4.3.2.1.2, under the category <emphasis role="bold">Mobile and Device
        Development</emphasis>, select <emphasis role="bold">C/C++ GDB
        Hardware Debugging</emphasis> as well.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="install_yocto">
    <title>Installing Yocto Plug-ins</title>

    <para>Retrieve the archive containing the Yocto Plug-ins from the Enea
    Linux release location and save it on your local machine. The archive file
    has the following format:
    <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>.</para>

    <para>To install the Yocto Plugins in Eclipse, follow the instructions in
    <ulink
    url="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#adt-eclipse">chapter
    4.3.2.1.3.2</ulink>. of the Yocto Manual, starting with <emphasis
    role="bold">step 8</emphasis>. In <emphasis role="bold">step 12</emphasis>
    use the local archive that you downloaded previously.</para>

    <para>To make sure that all required packages have been installed, go to
    the menu <emphasis role="bold">Help &gt; Install New Software &gt; Eclipse
    version</emphasis>, and select the version you use (e.g. Oxygen), to add
    any missing packages. You can also check what packages are currently
    installed by pressing the <emphasis role="bold">What is Already
    Installed?</emphasis> link, as seen below.</para>

    <mediaobject>
      <imageobject role="fo">
        <imagedata align="center" contentwidth="600"
                   fileref="images/install_new_sw.svg" />
      </imageobject>

      <imageobject role="html">
        <imagedata align="center" fileref="images/install_new_sw.png" />
      </imageobject>
    </mediaobject>
  </section>

  <section id="eclipse_remote_connection">
    <title>Setting up a TCF Connection from Eclipse</title>

    <para>Eclipse supports several types of remote connections to reference
    boards. Among these is the Target Communication Framework (TCF) type of
    connection. This information will be referenced throughout this guide, as
    it is used by several features.</para>

    <para><emphasis role="bold">How to set up a TCF connection to the target
    to be used later on</emphasis><remark>Should we add images to this
    procedure to make it easier to understand?</remark></para>

    <orderedlist>
      <listitem>
        <para>Make sure the <literal>tcf-agent</literal> is running on the
        target:</para>

        <programlisting>ps aux | grep tcf-agent
root 329 0.0 0.2 1864824 2600 ? Ssl 12:47 0:08 /usr/sbin/tcf-agent -d -L- -l0</programlisting>
      </listitem>

      <listitem>
        <para>Open the Target Explorer perspective from <emphasis
        role="bold">Window &gt; Perspective &gt; Open Perspective &gt;
        Other... &gt; Target Explorer</emphasis>.</para>

        <para>This will open a new perspective, containing the <emphasis
        role="bold">System Management</emphasis> view.</para>
      </listitem>

      <listitem>
        <para>The <emphasis role="bold">System Management</emphasis> window
        displays all existing TCF connections and allows you to manage them.
        To create a new connection, go to <emphasis role="bold">Connections
        &gt; Create New Connection...</emphasis></para>
      </listitem>

      <listitem>
        <para>Type in an appropriate name in the <emphasis
        role="bold">Connection Name</emphasis> field.</para>
      </listitem>

      <listitem>
        <para>Select <literal>TCP</literal> in the <emphasis
        role="bold">Transport Type</emphasis> section.</para>
      </listitem>

      <listitem>
        <para>Fill in the target's IP address and leave the <emphasis
        role="bold">Port</emphasis> as it is (1534).</para>
      </listitem>

      <listitem>
        <para>Check the <emphasis role="bold">Connect on finish</emphasis>
        checkbox and click <emphasis role="bold">Finish</emphasis>.</para>
      </listitem>
    </orderedlist>

    <para>The connections created will be persistent and accessible from the
    <emphasis role="bold">Debug Configurations</emphasis> plugins.</para>
  </section>

  <section id="eclipse_devapps">
    <title>Developing Applications in Eclipse</title>

    <section id="crosscomp">
      <title>Cross-Compiling from Eclipse</title>

      <tip>
        <para>Watch Enea's video about <ulink
        url="https://www.youtube.com/watch?v=i6KaMrhVOw8&amp;list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS">Cross-compiling
        and Remote Debugging of Applications</ulink>.</para>
      </tip>

      <para>In order to use Eclipse to compile an application for a certain
      target architecture, you need to first install a cross-compilation
      toolchain<indexterm>
          <primary>cross-compilation toolchain</primary>
        </indexterm><indexterm>
          <primary>toolchain</primary>

          <secondary>cross-compilation</secondary>
        </indexterm> (SDK<indexterm>
          <primary>SDK</primary>
        </indexterm>), configure the cross-compiler in Eclipse, and then
      create a <emphasis>Yocto ADT Autotools project</emphasis> , which uses
      the Yocto SDK.<remark>INFO: This project type is still called ADT in
      Eclipse even though Yocto talks about standard and extentible
      SDK</remark></para>

      <para>Installing the cross-compilation toolchain is pretty
      straightforward. All you have to do is to run the shell script provided
      with the release and follow the instructions, see <link
      linkend="install_el_sdk">Installing a Cross-Compilation Toolchain
      (SDK)</link>.</para>

      <para>Before creating the project, you must first configure the
      cross-compiler<indexterm>
          <primary>cross-compiler</primary>
        </indexterm> in Eclipse:<remark>Should images be added to the
      procedure below for ease of understanding?</remark></para>

      <orderedlist>
        <listitem>
          <para>Select <emphasis role="bold">Window &gt; Preferences &gt;
          Yocto Project ADT</emphasis> to open a dialog.<remark>INFO: This
          project type is still called ADT in Eclipse even though Yocto talks
          about standard and extentible SDK</remark></para>
        </listitem>

        <listitem>
          <para>Choose a <emphasis role="bold">Stand-alone pre-built
          toolchain</emphasis>.</para>
        </listitem>

        <listitem>
          <para>For the <emphasis role="bold">Toolchain Root
          Location</emphasis> option, specify the path to the
          cross-compilation toolchain, e.g.
          <filename>/opt/enea/&lt;sdkversion&gt;</filename>.</para>
        </listitem>

        <listitem>
          <para>For the <emphasis role="bold">Sysroot Location</emphasis>
          option, specify the path to the target sysroot directory inside the
          toolchain root location e.g.
          <literal>&lt;extsdkdir&gt;/tmp/sysroots/corei7-64-enea-linux/</literal></para>
        </listitem>

        <listitem>
          <para>If multiple architectures are supported by the SDK, select the
          desired target architecture from the drop-down list.</para>

          <tip>
            <para>You can save different profiles with different
            configurations. This makes it easy to compile the same code for
            different architectures by simply choosing the desired development
            profile.</para>
          </tip>
        </listitem>

        <listitem>
          <para>In <emphasis role="bold">Target Options</emphasis>, select the
          <emphasis role="bold">External HW</emphasis> option.</para>
        </listitem>
      </orderedlist>

      <tip>
        <para>More details on how to configure the cross-compiler can be found
        in the <ulink
        url="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html"><emphasis>Yocto
        Project Software Development Kit (SDK) Developer's Guide
        2.5</emphasis></ulink>. Change the Yocto version in the link if
        needed.</para>

        <para>There is also a good cheat sheet available in Eclipse, under
        <emphasis role="bold">Help &gt; Cheat Sheets &gt; Yocto Project &gt;
        Creating a Hello World ANSI C or C++ Autotools Project</emphasis>.
        This cheat sheet covers all the steps up to building the
        project.</para>
      </tip>

      <para>Once you have configured the default options for the
      cross-compiler you can create a project:</para>

      <orderedlist>
        <listitem>
          <para>Follow the steps in the wizard to create the project:</para>

          <orderedlist numeration="loweralpha" spacing="compact">
            <listitem>
              <para>Select <emphasis role="bold">File &gt; New &gt; Project
              &gt; C Project</emphasis> and click <emphasis
              role="bold">Next</emphasis>.</para>
            </listitem>

            <listitem>
              <para>Select <emphasis role="bold">Yocto Project ADT Autotools
              Project &gt; Hello World ANSI C Autotools Project</emphasis>,
              and give the project a <emphasis role="bold">Project
              name</emphasis> before clicking <emphasis
              role="bold">Next</emphasis>.<note>
                  <para>Having a hyphen character '<literal>-</literal>' in
                  the name can cause configuration errors.</para>
                </note></para>
            </listitem>

            <listitem>
              <para>Enter the <emphasis role="bold">Author</emphasis> and
              click <emphasis role="bold">Finish</emphasis>.</para>
            </listitem>
          </orderedlist>

          <para>This will automatically generate all the files needed,
          creating all necessary configurations for cross-compiling. For more
          on how to create a project, watch <ulink
          url="https://www.youtube.com/watch?v=2qxWae7srzE&amp;list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS">Enea's
          video about setting up an ADT project</ulink>.</para>
        </listitem>

        <listitem>
          <para>Optionally, if you want to have specific options for
          cross-compiling this project, select <emphasis role="bold">Project
          &gt; Change Yocto Project Settings</emphasis> and modify the options
          for this project only.</para>
        </listitem>

        <listitem>
          <para>Right-click on the project from the Project Explorer and
          choose <emphasis role="bold">Reconfigure Project</emphasis>. This
          will generate the necessary makefiles to build the project.</para>
        </listitem>

        <listitem>
          <para>Finally, build the project from <emphasis role="bold">Project
          &gt; Build Project</emphasis>, or by right-clicking on the project
          in the Project Explorer and selecting <emphasis role="bold">Build
          Project</emphasis>. A binary file for the target architecture is
          created in the project directory.</para>
        </listitem>
      </orderedlist>

      <tip>
        <para>If you need to add more files or compiler flags or parameters to
        the Makefile, edit <filename>Makefile.am</filename> accordingly and
        then reconfigure the project.</para>
      </tip>

      <note>
        <para>Eclipse displays the results from building a project in one
        Eclipse console, and reconfiguring a project in another one. Switching
        between the two consoles is necessary to view both outputs.</para>
      </note>
    </section>

    <section id="eclipse_debug">
      <title>Debugging Applications from Eclipse</title>

      <tip>
        <para>Watch Enea's video about <ulink
        url="https://www.youtube.com/watch?v=i6KaMrhVOw8&amp;list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS">Cross-compiling
        and Remote Debugging of Applications</ulink>.</para>
      </tip>

      <para>Using Eclipse you can build an application, deploy it on the
      target, and debug <indexterm>
          <primary>debug</primary>
        </indexterm>the source code remotely, all with a single mouse click.
      However, in order to achieve this you need to make certain
      configurations.</para>

      <para>When setting the cross-compiler options for a target, a run/debug
      configuration is created as a <emphasis role="bold">C/C++ Remote
      Application</emphasis> instance. The configuration is named according to
      this syntax <literal>&lt;project&gt;_gdb_-&lt;suffix&gt;</literal>, for
      example: <filename>hello_gdb_aarch64-enea-linux</filename>.</para>

      <note>
        <para>If a run/debug configuration is not created when setting the
        cross-compiler options, perform the steps in <link
        linkend="troubleshoot_build_debug_config">Run/Debug Configuration Not
        Created</link>.</para>
      </note>

      <para>The instructions below describes how to use Eclipse to debug
      single-process applications on a target. For information on how to debug
      multi-process applications, see <link
      linkend="eclipse_multi_debug">Debugging Multi-Process Applications from
      Eclipse</link>.</para>

      <para>Use the run/debug configuration to connect the Eclipse GDB
      interface to the remote target, by doing the following:</para>

      <remark>Should we add images for the procedure below as well?</remark>

      <orderedlist>
        <listitem>
          <para>Select <emphasis role="bold">Run &gt; Debug Configurations
          &gt; C/C++ Remote application</emphasis> from the menu and choose
          the run/debug configuration from the instances under <literal>C/C++
          Remote Application</literal> in the left pane. You can rename,
          duplicate or remove the configuration as needed.</para>
        </listitem>

        <listitem>
          <para>In the <emphasis role="bold">Main</emphasis> tab, do the
          following:</para>

          <orderedlist spacing="compact">
            <listitem>
              <para>Select an existing <emphasis
              role="bold">Connection</emphasis> from the drop-down list, or
              create a new one following the steps below:</para>

              <orderedlist>
                <listitem>
                  <para>To create a new connection, click the <emphasis
                  role="bold">New...</emphasis> button and select a connection
                  type. For debugging applications an <emphasis
                  role="bold">SSH</emphasis> connection is recommended.</para>
                </listitem>

                <listitem>
                  <para>Choose a connection name and fill in the <emphasis
                  role="bold">Host information</emphasis> section with the
                  target's IP and the username.</para>

                  <note>
                    <para>For Enea Linux, the default username is <emphasis
                    role="bold">root</emphasis> and there is no password
                    set.</para>
                  </note>
                </listitem>

                <listitem>
                  <para>Depending on your network setup, select either
                  <emphasis role="bold">Public key</emphasis> or <emphasis
                  role="bold">Password-based authentication</emphasis>. If
                  using Password-based authentication, leave the field empty
                  when using the default <emphasis role="bold">root</emphasis>
                  username.</para>
                </listitem>

                <listitem>
                  <para>Click Finish. The new connection should now be
                  available in the dropdown menu. This connection will be
                  persist through all Run/Debug configurations.</para>

                  <para>You can manage your saved connections in the <emphasis
                  role="bold">Connections </emphasis>view from <emphasis
                  role="bold">Window -&gt; Show View -&gt; Other... -&gt;
                  Connections</emphasis>.</para>
                </listitem>
              </orderedlist>
            </listitem>

            <listitem>
              <para>Select the binary <emphasis role="bold">C/C++
              Application</emphasis> you want to deploy.</para>

              <para>If you click the <emphasis role="bold">Search
              Project</emphasis> button, Eclipse will parse the project and
              provide a list of all compiled binaries to choose from.
              Alternatively, you can <emphasis role="bold">Browse</emphasis>
              the file system for a binary, or use <emphasis
              role="bold">Variables</emphasis> to manually define the
              path.</para>
            </listitem>

            <listitem>
              <para>The <emphasis role="bold">Remote Absolute File
              Path</emphasis> is the path to which the binary on the target
              shall be deployed. Type it directly or click the <emphasis
              role="bold">Browse</emphasis> button and select a location on
              the remote target. Note that you need to specify the path
              including the filename.</para>
            </listitem>

            <listitem>
              <para>Optionally, you may choose not to download the application
              to the target, but instead debug an already downloaded
              application.</para>
            </listitem>

            <listitem>
              <para>You can also configure Eclipse to execute commands prior
              to launching the application, by specifying the commands in the
              corresponding field.</para>
            </listitem>
          </orderedlist>
        </listitem>

        <listitem>
          <para>In the <emphasis role="bold">Arguments</emphasis> tab you can
          specify various arguments to be passed to your application at
          launch-time.</para>
        </listitem>

        <listitem>
          <para>The <emphasis role="bold">Debugger</emphasis> tab deals with
          GDB specific configurations. This is automatically populated when
          configuring the cross-compiler. You may optionally choose
          additionally useful options as with any Eclipse GDB interface, e.g.
          whether to break at entering the main function or uploading shared
          libraries.</para>
        </listitem>

        <listitem>
          <para>To enable debugging with shared libraries, do the
          following:</para>

          <itemizedlist>
            <listitem>
              <para>Retrieve the debug sources from the target, and store them
              in a dedicated folder on the local host. They are found in
              <literal>/usr/src/debug</literal> in the target rootfs.</para>
            </listitem>

            <listitem>
              <para>Set a path mapping your debug configuration. In the
              <emphasis role="bold">Source</emphasis> tab, click <emphasis
              role="bold">Add</emphasis>, select <emphasis role="bold">Path
              Mapping</emphasis>, and assign paths to the mapping:</para>

              <simplelist>
                <member><emphasis role="bold">Compilation path</emphasis>:
                <filename>/usr/src/debug</filename></member>

                <member><emphasis role="bold">Local file system
                path</emphasis> (path to the debug sources retrieved from the
                target):<filename>
                &lt;path_to_chosen_folder&gt;/usr/src/debug</filename></member>
              </simplelist>
            </listitem>

            <listitem>
              <para>In the <emphasis role="bold">Debugger/Shared
              Libraries</emphasis> tab, select option <emphasis
              role="bold">Load shared library symbols automatically</emphasis>
              and set the path to the shared library. The path depends on the
              processor architecture of your target.</para>

              <para>For <emphasis role="bold">32-bit</emphasis> targets:
              <filename>&lt;extsdkdir&gt;/sysroots/&lt;arch&gt;-enea-linux/lib/.debug
              </filename></para>

              <para>For <emphasis role="bold">64-bit</emphasis> targets:
              <filename>&lt;extsdkdir&gt;/sysroots/&lt;arch&gt;-enea-linux/lib64/.debug</filename></para>

              <para>Note that inside Eclipse you must load the shared
              libraries with debug information (not stripped). Shared
              libraries that get built into the rootfs of the target image
              have debug information stripped off, for size and speed
              optimizations.</para>
            </listitem>

            <listitem>
              <para>To debug applications that depend on shared libraries
              built outside the rootfs of the target image, the same procedure
              applies, with the exception that you must upload the required
              shared libraries to the target prior to starting the debugging
              session.</para>

              <para>If you upload them to <literal>/lib</literal> or
              <literal>/lib64</literal> (depending on the target architecture)
              they get loaded by default. Otherwise, you must correctly update
              the <emphasis role="bold"><literal>
              LD_LIBRARY_PATH</literal></emphasis> environment variable to
              match their look-up path. In Eclipse, you can automatically
              update this variable by setting the <emphasis
              role="bold">Commands to execute before application</emphasis>
              field to: <emphasis role="bold">export
              <literal>LD_LIBRARY_PATH=&lt;path to uploaded shared
              libs&gt;</literal> </emphasis></para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>Once you have set up all the debug configurations, click
          <emphasis role="bold">Apply</emphasis> and <emphasis
          role="bold">Debug</emphasis>. This will launch the GDB on the target
          and open the <literal>Debug perspective</literal>. This is the
          standard Eclipse GDB interface when debugging a remote target. You
          can use all GDB features, such as setting breakpoints, stepping
          through code, reading variable values, reading registers, viewing
          memory, etc.</para>
        </listitem>
      </orderedlist>

      <para>When the debugger starts, Eclipse opens three consoles:</para>

      <orderedlist numeration="upperalpha" spacing="compact">
        <listitem>
          <para>The <emphasis role="bold">Remote Shell</emphasis> - used to
          launch the application and display its output.</para>
        </listitem>

        <listitem>
          <para>The <emphasis role="bold">GDB console</emphasis> - named as
          the path to its GDB binary. You can use this console to control the
          GDB from the command line.</para>
        </listitem>

        <listitem>
          <para>The third console is named as the path of the binary on the
          local machine, and is in fact an artifact that must be
          ignored.</para>
        </listitem>
      </orderedlist>

      <para>After having set up the debug configuration once, you can modify
      and rebuild your application and then relaunch it by simply clicking the
      <emphasis role="bold">Debug</emphasis> icon (the bug symbol) on the
      toolbar. You can also select the drop-down list for more configurations,
      and even add your configuration to the <emphasis
      role="bold">Favorites</emphasis> to easily retrieve it next time.</para>

      <para>If you only want to deploy and run the application, without
      debugging, you can use the same configuration as the one set up for
      debugging, but simply click the <emphasis role="bold">Run</emphasis>
      icon (the Play button symbol) from the toolbar menu, or select <emphasis
      role="bold">Run &gt; Run Configurations</emphasis> and Run the chosen
      configuration.</para>
    </section>

    <section id="eclipse_multi_debug">
      <title>Debugging Multi-Process Applications from Eclipse</title>

      <para>In Eclipse, remote debugging of an application that uses multiple
      processes<indexterm>
          <primary>multiple processes</primary>
        </indexterm> is slightly different compared to debugging a single
      process application as described in <link
      linkend="eclipse_debug">Debugging Applications from
      Eclipse</link>.</para>

      <para>The following limitations exist for multi-process
      debugging:</para>

      <itemizedlist spacing="compact">
        <listitem>
          <para>All debugged processes must share the same binary.</para>
        </listitem>

        <listitem>
          <para>Debugging only works in non-stop mode, i.e. stopping at a
          breakpoint only stops the current thread while other threads
          continue to execute.</para>
        </listitem>
      </itemizedlist>

      <note>
        <para>When using the GDB to debug multiple instances of the same
        process or thread, using the same symbols file, breakpoints will be
        common to all instances. That is, when setting a breakpoint in the
        code, all instances will stop there, and there is no way to filter
        them. The current thread filter in Eclipse is ineffective.</para>
      </note>

      <para><emphasis role="bold">Use the run/debug configuration to connect
      the Eclipse GDB client to the remote target</emphasis>:</para>

      <orderedlist>
        <listitem>
          <para>Go to <emphasis role="bold">Window &gt; Preferences &gt;
          Run/Debug &gt; Launching &gt; Default Launchers</emphasis>. Under
          <emphasis role="bold">C/C++ Attach to Applicaton &gt;
          Debug</emphasis> select the checkbox <emphasis role="bold">GDB (DSF)
          Attach to Process via TCF/TE Launcher</emphasis>.</para>
        </listitem>

        <listitem>
          <para>Select <emphasis role="bold">Run &gt; Debug Configurations...
          </emphasis> from the menu and choose the run/debug configuration
          from the instances under <literal>C/C++ Attach to
          Application</literal> in the left pane. You can create, rename,
          duplicate, or remove the configurations as needed.</para>
        </listitem>

        <listitem>
          <para>If you followed <emphasis role="bold">step 1</emphasis>, in
          the lower part of the dialog you will see that <emphasis
          role="bold">Using GDB (DSF) Attach to Process via TCF/TE
          Launcher</emphasis> is selected. If not, redo <emphasis
          role="bold">step 1</emphasis> or click the <emphasis
          role="bold">Select Other...</emphasis> link, and use configuration
          specific settings by selecting the checkbox <emphasis
          role="bold">GDB (DSF) Attach to Process via TCF/TE
          Launcher</emphasis>.</para>
        </listitem>

        <listitem>
          <para>In the <emphasis role="bold">Main</emphasis> tab, do the
          following:</para>

          <orderedlist spacing="compact">
            <listitem>
              <para>Select the binary <emphasis role="bold">C/C++
              Application</emphasis> you want to deploy. If you click the
              <emphasis role="bold">Search Project</emphasis> button, Eclipse
              will parse the project and provide a list of all compiled
              binaries to choose from. Alternatively, you can <emphasis
              role="bold">Browse</emphasis> the file system for a binary, or
              use <emphasis role="bold">Variables</emphasis> to manually
              define the path.</para>
            </listitem>

            <listitem>
              <para>Select an existing <emphasis
              role="bold">Connection</emphasis> from the drop-down list. If a
              connection is not available, create a new one following the
              steps in <link linkend="eclipse_remote_connection">Setting up a
              TCF Connection from Eclipse</link>.</para>
            </listitem>

            <listitem>
              <para>The <emphasis role="bold">Remote Absolute File
              Path</emphasis> is the path to the binary of the process you are
              planning to debug. Type it directly or click the <emphasis
              role="bold">Browse</emphasis> button and select a location on
              the remote target. You need an active TCF connection to the
              target for the <emphasis role="bold">Browse</emphasis> button to
              work (see chapter <emphasis role="bold">Setting up a TCF
              Connection from Eclipse</emphasis>). Note that you need to
              specify the path including the filename.</para>
            </listitem>

            <listitem>
              <para>Specify the PID of the remote process you are planning to
              attach.</para>
            </listitem>
          </orderedlist>
        </listitem>

        <listitem>
          <para>The <emphasis role="bold">Debugger</emphasis> tab deals with
          GDB specific configurations. Select the <emphasis
          role="bold">gdbserver</emphasis> in the Debugger dropdown. You may
          also choose other useful options as with any Eclipse GDB interface,
          e.g. whether to break at entering the main function or uploading
          shared libraries. The following actions are important:</para>

          <orderedlist spacing="compact">
            <listitem>
              <para>In the <emphasis role="bold">Main</emphasis> tab, enter
              the path to the GDB binary in the SDK. For example:
              <literal>&lt;extsdkdir&gt;/tmp/sysroots/x86_64-linux/usr/bin/&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</literal>.</para>
            </listitem>

            <listitem>
              <para>Select option <literal>Non-stop mode</literal>.</para>
            </listitem>
          </orderedlist>
        </listitem>

        <listitem>
          <para>Once you have set up all the debug configurations, click
          <emphasis role="bold">Apply</emphasis> and <emphasis
          role="bold">Debug</emphasis>. This will launch the GDB and
          optionally open the <literal>Debug perspective</literal> for the
          process you selected. This is the standard Eclipse GDB interface
          when debugging a remote target. You can use all GDB features, such
          as setting breakpoints, stepping through code, reading variable
          values, reading registers, viewing memory, etc.</para>
        </listitem>
      </orderedlist>

      <para>Repeat these steps for each process you want to debug. You can
      have multiple debug sessions running simultaneously for multiple
      processes sharing the same source code.</para>
    </section>

    <section id="eclipse_postmortem">
      <title>Using the Postmortem Debugger</title>

      <para>When a program crashes<indexterm>
          <primary>post-mortem debugging</primary>
        </indexterm><indexterm>
          <primary>core dump</primary>
        </indexterm>, it may leave a core dump which can be used to figure out
      exactly why the program crashed. Core dumps are disabled by default and
      have to be activated before debugging. After retrieving and transferring
      a core dump file to a host machine, Eclipse and the SDK tool generated
      for the target, can be used to analyze the application state at the time
      of the crash.</para>

      <para>If deep debugging within Linux libraries is needed, the debug SDK
      is required. See <link linkend="install_el_sdk">Installing Enea Linux
      SDK</link>.</para>

      <para>To enable writing core dump files, two steps need to be performed
      on the target: <emphasis>allowing resources for core dumps</emphasis>
      and <emphasis>defining a core file name pattern</emphasis>. These
      settings are valid until the next reboot, unless made permanent by
      configuration changes in the root file system.</para>

      <para>Use the <command>ulimit</command> command to allow the system to
      use resources for core dumps. The <command>ulimit</command> command
      controls the resources available to a process started by the shell, on
      systems that allow such control. Type the following to use this
      command:</para>

      <programlisting>ulimit -c unlimited</programlisting>

      <para>To verify the result, type <command>ulimit -a</command> and see if
      the core file size is set to <literal>unlimited</literal>. User limits
      can also be changed from the application code using the function
      <function>setrlimit(...)</function> declared in the
      <literal>sys/resource.h</literal> header (see the manual available
      through <command>man setrlimit</command>). To make this permanent across
      a reboot, adjust the configuration in
      <filename>/etc/security/limits.conf</filename>.</para>

      <para>The next step is to specify the core pattern which defines the
      core dump file pattern name. The core pattern is defined in the
      <literal>/proc/sys/kernel/core_pattern</literal>.</para>

      <para>The format of a core pattern follows certain rules:</para>

      <itemizedlist>
        <listitem>
          <para>The maximum length is 128 characters</para>
        </listitem>

        <listitem>
          <para>Default core dump name is <filename>core</filename></para>
        </listitem>

        <listitem>
          <para>The string stored in <literal>core_pattern</literal> is used
          as a pattern template for the output filename. Certain string
          patterns (beginning with <literal>%</literal>) are substituted with
          their actual values. The patterns are:</para>

          <programlisting>%&lt;NUL&gt;   '%' is dropped
%%       output one '%'
%p       pid
%P       global pid (init PID namespace)
%i       tid
%I       global tid (init PID namespace)
%u       uid (in initial user namespace)
%g       gid (in initial user namespace)
%d       dump mode, matches PR_SET_DUMPABLE and /proc/sys/fs/suid_dumpable
%s       signal number
%t       UNIX time of dump
%h       hostname
%e       executable filename (may be shortened)
%E       executable path
%&lt;OTHER&gt; both are dropped</programlisting>
        </listitem>

        <listitem>
          <para>If the first character of the pattern is a
          '<literal>|</literal>', the kernel will treat the rest of the
          pattern as a command to run. The core dump will be written to the
          standard input of that program instead of to a file.</para>
        </listitem>

        <listitem>
          <para>By setting the value <literal>core_uses_pid</literal> to
          <literal>1</literal>, the core dump filename gets the extension
          <filename>.PID</filename>, if the <literal>core_pattern</literal>
          does not contain "<literal><literal>%p</literal></literal>".</para>

          <para>For example, the default file name <filename>core</filename>
          becomes <filename>core.PID</filename> if the
          <literal>core_uses_pid</literal> is set, and no
          <literal>core_pattern</literal> is defined.</para>
        </listitem>
      </itemizedlist>

      <para>Specify a core pattern by writing it to
      <literal>/proc/sys/kernel/core_pattern</literal>. For example:
      <programlisting><literal>echo "&lt;suitable_directory&gt;/core.%e.%p.%h.%t" &gt; /proc/sys/kernel/core_pattern</literal></programlisting></para>

      <para>To make the core dump file name permanent across a reboot,
      configure <filename>/etc/sysctl.conf</filename>. to reflect this choice,
      by adding a line like in the following example:
      <literal>kernel.core_pattern=&lt;suitable_directory&gt;/core.%e.%p.%h.%t</literal>.</para>

      <para>How to use the Eclipse post mortem debug configuration in order to
      view the call trace, for the core dump in the Eclipse GDB
      interface:</para>

      <orderedlist spacing="compact">
        <listitem>
          <para>Ensure a core dump can be created on the target, see the
          information above. To see the full call stack, the application
          object files, compiled with debug information, are needed (the
          <literal>-g</literal> option in gcc).</para>
        </listitem>

        <listitem>
          <para>After a core dump has been created, retrieve the core dump
          file from the target and store it on the host.</para>
        </listitem>

        <listitem>
          <para>In Eclipse on the host, you need the core dump file, the SDK
          for the target, the application executable, and access to the source
          code. Once you have those, do the following:<orderedlist
              spacing="compact">
              <listitem>
                <para>Switch to the <literal>Debug</literal> perspective in
                Eclipse.</para>
              </listitem>

              <listitem>
                <para>Select <emphasis role="bold">Run -&gt; Debug
                Configurations ...</emphasis> (scroll down if you don't see
                the option at first glance) <emphasis role="bold">-&gt; C/C++
                Postmortem Debugger</emphasis>.</para>
              </listitem>

              <listitem>
                <para>Make sure the <literal>C/C++ Application</literal> field
                refers to your project executable, and fill in the
                <literal>Core file</literal> field with the path to the
                downloaded core file.</para>
              </listitem>

              <listitem>
                <para>Under the <emphasis role="bold">Debugger</emphasis> tab,
                fill in the <literal>GDB Debugger</literal> field with the
                path to the GDB binary from the SDK. Example path:
                <filename>&lt;extsdkdir&gt;/tmp/sysroots/x86_64-linux/usr/bin/&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</filename></para>
              </listitem>

              <listitem>
                <para>Click the <literal>Debug</literal> button. Eclipse
                should switch into the <literal>Debug</literal> perspective
                (if it hasn't already) and the debugging instance should break
                somewhere inside the application. The call stack should be
                observable in the console and should show a termination
                message.</para>
              </listitem>
            </orderedlist></para>
        </listitem>
      </orderedlist>
    </section>
  </section>

  <section id="eclipse_kern_debug">
    <title>Debugging the Linux Kernel in Eclipse</title>

    <para>In this section you learn to set up Eclipse for KGDB<indexterm>
        <primary>KGDB</primary>
      </indexterm> kernel debugging over the serial port, with examples for
    the <literal>intel-corei7-64</literal> target. This is only given as an
    example, your Enea Linux distribution may contain other targets. The
    corresponding instruction for debugging outside Eclipse is available in
    Debugging the Linux Kernel (KGDB) from Command Line.<remark>LATER: Merge
    the two instructions to shrink the amount of text; most of it is the
    same.</remark></para>

    <para>How to set up Eclipse for KGDB kernel debugging over a serial
    port:</para>

    <orderedlist>
      <listitem>
        <para>Make sure that the cross-compilation toolchain<indexterm>
            <primary>cross-compilation toolchain</primary>
          </indexterm><indexterm>
            <primary>toolchain</primary>

            <secondary>cross-compilation</secondary>
          </indexterm> (SDK<indexterm>
            <primary>SDK</primary>
          </indexterm>) is installed on the host, see <link
        linkend="install_el_sdk">Installing Enea Linux SDK</link>.</para>
      </listitem>

      <listitem>
        <para>Ensure that the kernel debug image
        (<literal>vmlinux)</literal>is accessible on the host where you run
        Eclipse, and that you have permissions to execute it. You will later
        point to it in Eclipse.</para>

        <para>If you are using the default kernel delivered with Enea Linux,
        you can find it in the rootfs under the <literal>/boot</literal>
        folder. If you build your own kernel using bitbake, it should be
        available in your build folder. Located in, for example:
        <filename><filename>tmp/work/corei7-64-intel-common-enea-linux/linux-intel-rt/4.14.59+gitAUTOINC+d64aec9793_6a0fa58d9e-r0/linux-corei7-64-intel-common-preempt-rt-build/vmlinux</filename></filename></para>
      </listitem>

      <listitem>
        <para>In Eclipse:</para>

        <orderedlist>
          <listitem>
            <para>Optional: The Linux kernel has a considerable amount of
            sources, and indexing the whole of it might take a lot of time.
            Save time by disabling C/C++ project indexing:<orderedlist
                spacing="compact">
                <listitem>
                  <para>Select <emphasis role="bold">Window &gt; Preferences
                  &gt; C/C++ &gt; Indexer</emphasis>.</para>
                </listitem>

                <listitem>
                  <para>Unselect the <emphasis role="bold">Enable
                  indexer</emphasis> checkbox.</para>
                </listitem>
              </orderedlist></para>
          </listitem>

          <listitem>
            <para>Create a project from the kernel tree:</para>

            <orderedlist spacing="compact">
              <listitem>
                <para>Select <emphasis role="bold">File &gt; New &gt; Project
                &gt; C/C++ &gt; C project</emphasis>.</para>
              </listitem>

              <listitem>
                <para>In the left panel, select <emphasis role="bold">Makefile
                project &gt; Empty project</emphasis>, and give the project a
                name.</para>
              </listitem>

              <listitem>
                <para>Unselect the <emphasis role="bold">Use default
                location</emphasis> option.</para>
              </listitem>

              <listitem>
                <para>Click <emphasis role="bold">Browse</emphasis> and
                navigate to the location of the kernel sources (git
                folder).</para>
              </listitem>

              <listitem>
                <para>Click <emphasis role="bold">Finish</emphasis>.</para>
              </listitem>
            </orderedlist>
          </listitem>

          <listitem>
            <para>Create a C/C++ GDB Hardware Debugging configuration:</para>

            <orderedlist spacing="compact">
              <listitem>
                <para>Go to <emphasis role="bold">Run -&gt; Debug
                Configurations</emphasis>.</para>
              </listitem>

              <listitem>
                <para>Double-click <emphasis role="bold">GDB Hardware
                Debugging</emphasis>.</para>
              </listitem>
            </orderedlist>

            <para>This will create a default configuration named
            <literal>project_name Default</literal>.</para>
          </listitem>

          <listitem>
            <para>In the <emphasis role="bold">Main</emphasis> tab:</para>

            <orderedlist spacing="compact">
              <listitem>
                <para>Browse to the location of the
                <filename>vmlinux</filename> image. As an alternative, you may
                select a different project to debug, but if you followed the
                steps above you should not need to modify this.</para>
              </listitem>

              <listitem>
                <para>Select the <emphasis role="bold">Disable auto
                build</emphasis> radio button.</para>
              </listitem>

              <listitem>
                <para>At the bottom of the window, make sure <emphasis
                role="bold">GDB (DSF) Hardware Debugging Launcher</emphasis>
                is selected.</para>
              </listitem>
            </orderedlist>
          </listitem>

          <listitem>
            <para>In the <emphasis role="bold">Debugger</emphasis> tab for
            <emphasis role="bold">C/C++ Application</emphasis>:</para>

            <orderedlist spacing="compact">
              <listitem>
                <para>Browse to the location of the <emphasis role="bold">GDB
                binary</emphasis> installed by the cross-compilation toolchain
                installer, by default:
                <filename>&lt;extsdkdir&gt;/tmp/sysroots/x86_64/usr/bin/&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</filename>.</para>
              </listitem>

              <listitem>
                <para>Select option <emphasis role="bold">Use remote
                target</emphasis>.</para>
              </listitem>

              <listitem>
                <para>In the <emphasis role="bold">JTAG Device</emphasis>,
                select <emphasis role="bold">Generic Serial</emphasis> from
                the dropdown list.</para>
              </listitem>

              <listitem>
                <para>In the <emphasis role="bold">GDB Connection
                String</emphasis> field, type the host's tty device used for
                the serial connection to the target, e.g.
                <literal>/dev/ttyUSB0</literal>.</para>
              </listitem>
            </orderedlist>
          </listitem>

          <listitem>
            <para>In the <emphasis role="bold">Startup</emphasis> tab:</para>

            <orderedlist spacing="compact">
              <listitem>
                <para>Deselect the <emphasis role="bold">Load image</emphasis>
                option.</para>
              </listitem>

              <listitem>
                <para>Select the <emphasis role="bold">Load symbols</emphasis>
                option.</para>
              </listitem>

              <listitem>
                <para>Ensure that the <emphasis role="bold">Use project
                binary</emphasis> option defaults to your
                <literal>vmlinux</literal> image.</para>
              </listitem>

              <listitem>
                <para>Click <emphasis role="bold">Apply</emphasis> to store
                the configurations above.</para>
              </listitem>
            </orderedlist>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Prepare the target for KGDB debugging:</para>

        <orderedlist>
          <listitem>
            <para>Configure a serial communication on the target, using the
            appropriate device for the target (e.g. <literal>ttyS0</literal>
            for <literal>p2020rdb</literal>, <literal>ttyS2</literal> for
            <literal>pandaboard</literal>, <literal>ttyPS0</literal> for
            <literal>zynq</literal>):</para>

            <programlisting><command>echo ttyS0,115200 &gt; /sys/module/kgdboc/parameters/kgdboc</command></programlisting>
          </listitem>

          <listitem>
            <para>Start KGDB on the target SysRq:</para>

            <programlisting><command>echo g &gt; /proc/sysrq-trigger</command></programlisting>
          </listitem>

          <listitem>
            <para>Keep the serial connection open, but close the terminal to
            the target.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Launch the debug session in Eclipse:</para>

        <orderedlist spacing="compact">
          <listitem>
            <para>Select <emphasis role="bold">Run &gt; Debug
            Configurations</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Select the configuration created above.</para>
          </listitem>

          <listitem>
            <para>Click the <emphasis role="bold">Debug</emphasis>
            button.</para>
          </listitem>
        </orderedlist>

        <para>The target halts in function
        <literal>kgdb_breakpoint()</literal>. The GDB view opens in Eclipse,
        and from here you can debug the kernel by giving ordinary GDB commands
        (<command>resume</command>, <command>step</command>, <command>set
        breakpoint,</command> etc.).</para>
      </listitem>
    </orderedlist>
  </section>

  <section id="workarounds">
    <title>Workarounds</title>

    <section id="troubleshoot_build_debug_config">
      <title>Run/Debug Configuration Not Created</title>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">Description:</emphasis> When setting up
          <link linkend="eclipse_debug">Remote Debugging from Eclipse</link>,
          a run/debug configuration is not created when setting the
          cross-compiler options, thus there is nothing to select under
          <emphasis role="bold">C/C++ Remote Application</emphasis> in the
          first step.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Solution:</emphasis> Manually create a
          run/debug configuration.</para>

          <para>Perform the following steps:</para>

          <orderedlist>
            <listitem>
              <para>Double-click the <emphasis role="bold">C/C++ Remote
              Application</emphasis>. This will create a new debug
              configuration named after your project.</para>
            </listitem>

            <listitem>
              <para>In the <emphasis role="bold">Debugger</emphasis> tab,
              select a <emphasis role="bold">GDB debugger</emphasis> by
              browsing for and selecting the debugger of your
              cross-compilation toolchain, from your <emphasis
              role="bold">Sysroot Location</emphasis>. Example:</para>

              <programlisting>$ &lt;extsdkdir&gt;/tmp/sysroots/x86_64/usr/bin/\
&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</programlisting>

              <para>where <filename>&lt;sdkdir&gt;</filename> is e.g.
              <filename>/opt/enea/&lt;sdkversion&gt;</filename>.</para>
            </listitem>

            <listitem>
              <para>Outside Eclipse, create a new file named
              <filename>.gdbinit</filename> within your Eclipse workspace,
              under your project directory, e.g. <filename>&lt;path to
              workspace&gt;/&lt;project name&gt;/.gdbinit</filename>, with the
              following command, using your <emphasis role="bold">Sysroot
              Location</emphasis>:</para>

              <programlisting>$ set sysroot &lt;extsdkdir&gt;/sysroots</programlisting>
            </listitem>

            <listitem>
              <para>Back in Eclipse in the <emphasis
              role="bold">Debugger</emphasis> tab, browse for the newly
              created <emphasis role="bold">.gdbinit</emphasis> file and
              select it under <emphasis role="bold">GDB command
              file</emphasis>.</para>
            </listitem>

            <listitem>
              <para>Click <emphasis role="bold">Apply</emphasis>, then go back
              to the <emphasis role="bold">Main</emphasis> tab and continue
              with the remaining steps in the <emphasis role="bold">Remote
              Debugging</emphasis> section.</para>
            </listitem>
          </orderedlist>
        </listitem>
      </itemizedlist>
    </section>
  </section>
</chapter>