summaryrefslogtreecommitdiffstats
path: root/doc/book-enea-linux-user-guide/doc/using_eclipse.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/book-enea-linux-user-guide/doc/using_eclipse.xml')
-rw-r--r--doc/book-enea-linux-user-guide/doc/using_eclipse.xml1225
1 files changed, 1225 insertions, 0 deletions
diff --git a/doc/book-enea-linux-user-guide/doc/using_eclipse.xml b/doc/book-enea-linux-user-guide/doc/using_eclipse.xml
new file mode 100644
index 0000000..f6c7759
--- /dev/null
+++ b/doc/book-enea-linux-user-guide/doc/using_eclipse.xml
@@ -0,0 +1,1225 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<chapter id="use_eclipse">
3 <title>Using Eclipse</title>
4
5 <section id="install_eclipse">
6 <title>Installing Eclipse</title>
7
8 <para>For instructions on how to install Eclipse Oxygen, please refer to
9 the <ulink
10 url="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#adt-eclipse">Yocto
11 Project Software Development Kit (SDK) Developer's Guide</ulink>, chapter
12 4.3.2.1. Although the instructions listed there currently, refer to the
13 Neon release of Eclipse, the same steps still apply to the Oxygen release,
14 with some small differences:</para>
15
16 <itemizedlist>
17 <listitem>
18 <para>In <emphasis role="bold">step 1</emphasis> from chapter
19 4.3.2.1.1, the URL for downloading Eclipse should be <ulink
20 url="http://www.eclipse.org/oxygen">http://www.eclipse.org/oxygen</ulink>
21 instead.</para>
22 </listitem>
23
24 <listitem>
25 <para>In <emphasis role="bold">step 3</emphasis> from chapter
26 4.3.2.1.2, the correct option in the drop-down menu should look like:
27 <emphasis>Oxygen -
28 http://download.eclipse.org/releases/oxygen</emphasis>.</para>
29 </listitem>
30
31 <listitem>
32 <para>In <emphasis role="bold">step 5</emphasis> from chapter
33 4.3.2.1.2, under the category <emphasis role="bold">Mobile and Device
34 Development</emphasis>, select <emphasis role="bold">C/C++ GDB
35 Hardware Debugging</emphasis> as well.</para>
36 </listitem>
37 </itemizedlist>
38 </section>
39
40 <section id="install_yocto">
41 <title>Installing Yocto Plug-ins</title>
42
43 <para>Retrieve the archive containing the Yocto Plug-ins from the Enea
44 Linux release location and save it on your local machine. The archive file
45 has the following format:
46 <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>.</para>
47
48 <para>To install the Yocto Plugins in Eclipse, follow the instructions in
49 <ulink
50 url="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#adt-eclipse">chapter
51 4.3.2.1.3.2</ulink>. of the Yocto Manual, starting with <emphasis
52 role="bold">step 8</emphasis>. In <emphasis role="bold">step 12</emphasis>
53 use the local archive that you downloaded previously.</para>
54
55 <para>To make sure that all required packages have been installed, go to
56 the menu <emphasis role="bold">Help &gt; Install New Software &gt; Eclipse
57 version</emphasis>, and select the version you use (e.g. Oxygen), to add
58 any missing packages. You can also check what packages are currently
59 installed by pressing the <emphasis role="bold">What is Already
60 Installed?</emphasis> link, as seen below.</para>
61
62 <mediaobject>
63 <imageobject role="fo">
64 <imagedata align="center" contentwidth="600"
65 fileref="images/install_new_sw.svg" />
66 </imageobject>
67
68 <imageobject role="html">
69 <imagedata align="center" fileref="images/install_new_sw.png" />
70 </imageobject>
71 </mediaobject>
72 </section>
73
74 <section id="eclipse_remote_connection">
75 <title>Setting up a TCF Connection from Eclipse</title>
76
77 <para>Eclipse supports several types of remote connections to reference
78 boards. Among these is the Target Communication Framework (TCF) type of
79 connection. This information will be referenced throughout this guide, as
80 it is used by several features.</para>
81
82 <para><emphasis role="bold">How to set up a TCF connection to the target
83 to be used later on</emphasis><remark>Should we add images to this
84 procedure to make it easier to understand?</remark></para>
85
86 <orderedlist>
87 <listitem>
88 <para>Make sure the <literal>tcf-agent</literal> is running on the
89 target:</para>
90
91 <programlisting>ps aux | grep tcf-agent
92root 329 0.0 0.2 1864824 2600 ? Ssl 12:47 0:08 /usr/sbin/tcf-agent -d -L- -l0</programlisting>
93 </listitem>
94
95 <listitem>
96 <para>Open the Target Explorer perspective from <emphasis
97 role="bold">Window &gt; Perspective &gt; Open Perspective &gt;
98 Other... &gt; Target Explorer</emphasis>.</para>
99
100 <para>This will open a new perspective, containing the <emphasis
101 role="bold">System Management</emphasis> view.</para>
102 </listitem>
103
104 <listitem>
105 <para>The <emphasis role="bold">System Management</emphasis> window
106 displays all existing TCF connections and allows you to manage them.
107 To create a new connection, go to <emphasis role="bold">Connections
108 &gt; Create New Connection...</emphasis></para>
109 </listitem>
110
111 <listitem>
112 <para>Type in an appropriate name in the <emphasis
113 role="bold">Connection Name</emphasis> field.</para>
114 </listitem>
115
116 <listitem>
117 <para>Select <literal>TCP</literal> in the <emphasis
118 role="bold">Transport Type</emphasis> section.</para>
119 </listitem>
120
121 <listitem>
122 <para>Fill in the target's IP address and leave the <emphasis
123 role="bold">Port</emphasis> as it is (1534).</para>
124 </listitem>
125
126 <listitem>
127 <para>Check the <emphasis role="bold">Connect on finish</emphasis>
128 checkbox and click <emphasis role="bold">Finish</emphasis>.</para>
129 </listitem>
130 </orderedlist>
131
132 <para>The connections created will be persistent and accessible from the
133 <emphasis role="bold">Debug Configurations</emphasis> plugins.</para>
134 </section>
135
136 <section id="eclipse_devapps">
137 <title>Developing Applications in Eclipse</title>
138
139 <section id="crosscomp">
140 <title>Cross-Compiling from Eclipse</title>
141
142 <tip>
143 <para>Watch Enea's video about <ulink
144 url="https://www.youtube.com/watch?v=i6KaMrhVOw8&amp;list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS">Cross-compiling
145 and Remote Debugging of Applications</ulink>.</para>
146 </tip>
147
148 <para>In order to use Eclipse to compile an application for a certain
149 target architecture, you need to first install a cross-compilation
150 toolchain<indexterm>
151 <primary>cross-compilation toolchain</primary>
152 </indexterm><indexterm>
153 <primary>toolchain</primary>
154
155 <secondary>cross-compilation</secondary>
156 </indexterm> (SDK<indexterm>
157 <primary>SDK</primary>
158 </indexterm>), configure the cross-compiler in Eclipse, and then
159 create a <emphasis>Yocto ADT Autotools project</emphasis> , which uses
160 the Yocto SDK.<remark>INFO: This project type is still called ADT in
161 Eclipse even though Yocto talks about standard and extentible
162 SDK</remark></para>
163
164 <para>Installing the cross-compilation toolchain is pretty
165 straightforward. All you have to do is to run the shell script provided
166 with the release and follow the instructions, see <link
167 linkend="install_el_sdk">Installing a Cross-Compilation Toolchain
168 (SDK)</link>.</para>
169
170 <para>Before creating the project, you must first configure the
171 cross-compiler<indexterm>
172 <primary>cross-compiler</primary>
173 </indexterm> in Eclipse:<remark>Should images be added to the
174 procedure below for ease of understanding?</remark></para>
175
176 <orderedlist>
177 <listitem>
178 <para>Select <emphasis role="bold">Window &gt; Preferences &gt;
179 Yocto Project ADT</emphasis> to open a dialog.<remark>INFO: This
180 project type is still called ADT in Eclipse even though Yocto talks
181 about standard and extentible SDK</remark></para>
182 </listitem>
183
184 <listitem>
185 <para>Choose a <emphasis role="bold">Stand-alone pre-built
186 toolchain</emphasis>.</para>
187 </listitem>
188
189 <listitem>
190 <para>For the <emphasis role="bold">Toolchain Root
191 Location</emphasis> option, specify the path to the
192 cross-compilation toolchain, e.g.
193 <filename>/opt/enea/&lt;sdkversion&gt;</filename>.</para>
194 </listitem>
195
196 <listitem>
197 <para>For the <emphasis role="bold">Sysroot Location</emphasis>
198 option, specify the path to the target sysroot directory inside the
199 toolchain root location e.g.
200 <literal>&lt;extsdkdir&gt;/tmp/sysroots/corei7-64-enea-linux/</literal></para>
201 </listitem>
202
203 <listitem>
204 <para>If multiple architectures are supported by the SDK, select the
205 desired target architecture from the drop-down list.</para>
206
207 <tip>
208 <para>You can save different profiles with different
209 configurations. This makes it easy to compile the same code for
210 different architectures by simply choosing the desired development
211 profile.</para>
212 </tip>
213 </listitem>
214
215 <listitem>
216 <para>In <emphasis role="bold">Target Options</emphasis>, select the
217 <emphasis role="bold">External HW</emphasis> option.</para>
218 </listitem>
219 </orderedlist>
220
221 <tip>
222 <para>More details on how to configure the cross-compiler can be found
223 in the <ulink
224 url="http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html"><emphasis>Yocto
225 Project Software Development Kit (SDK) Developer's Guide
226 2.5</emphasis></ulink>. Change the Yocto version in the link if
227 needed.</para>
228
229 <para>There is also a good cheat sheet available in Eclipse, under
230 <emphasis role="bold">Help &gt; Cheat Sheets &gt; Yocto Project &gt;
231 Creating a Hello World ANSI C or C++ Autotools Project</emphasis>.
232 This cheat sheet covers all the steps up to building the
233 project.</para>
234 </tip>
235
236 <para>Once you have configured the default options for the
237 cross-compiler you can create a project:</para>
238
239 <orderedlist>
240 <listitem>
241 <para>Follow the steps in the wizard to create the project:</para>
242
243 <orderedlist numeration="loweralpha" spacing="compact">
244 <listitem>
245 <para>Select <emphasis role="bold">File &gt; New &gt; Project
246 &gt; C Project</emphasis> and click <emphasis
247 role="bold">Next</emphasis>.</para>
248 </listitem>
249
250 <listitem>
251 <para>Select <emphasis role="bold">Yocto Project ADT Autotools
252 Project &gt; Hello World ANSI C Autotools Project</emphasis>,
253 and give the project a <emphasis role="bold">Project
254 name</emphasis> before clicking <emphasis
255 role="bold">Next</emphasis>.<note>
256 <para>Having a hyphen character '<literal>-</literal>' in
257 the name can cause configuration errors.</para>
258 </note></para>
259 </listitem>
260
261 <listitem>
262 <para>Enter the <emphasis role="bold">Author</emphasis> and
263 click <emphasis role="bold">Finish</emphasis>.</para>
264 </listitem>
265 </orderedlist>
266
267 <para>This will automatically generate all the files needed,
268 creating all necessary configurations for cross-compiling. For more
269 on how to create a project, watch <ulink
270 url="https://www.youtube.com/watch?v=2qxWae7srzE&amp;list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS">Enea's
271 video about setting up an ADT project</ulink>.</para>
272 </listitem>
273
274 <listitem>
275 <para>Optionally, if you want to have specific options for
276 cross-compiling this project, select <emphasis role="bold">Project
277 &gt; Change Yocto Project Settings</emphasis> and modify the options
278 for this project only.</para>
279 </listitem>
280
281 <listitem>
282 <para>Right-click on the project from the Project Explorer and
283 choose <emphasis role="bold">Reconfigure Project</emphasis>. This
284 will generate the necessary makefiles to build the project.</para>
285 </listitem>
286
287 <listitem>
288 <para>Finally, build the project from <emphasis role="bold">Project
289 &gt; Build Project</emphasis>, or by right-clicking on the project
290 in the Project Explorer and selecting <emphasis role="bold">Build
291 Project</emphasis>. A binary file for the target architecture is
292 created in the project directory.</para>
293 </listitem>
294 </orderedlist>
295
296 <tip>
297 <para>If you need to add more files or compiler flags or parameters to
298 the Makefile, edit <filename>Makefile.am</filename> accordingly and
299 then reconfigure the project.</para>
300 </tip>
301
302 <note>
303 <para>Eclipse displays the results from building a project in one
304 Eclipse console, and reconfiguring a project in another one. Switching
305 between the two consoles is necessary to view both outputs.</para>
306 </note>
307 </section>
308
309 <section id="eclipse_debug">
310 <title>Debugging Applications from Eclipse</title>
311
312 <tip>
313 <para>Watch Enea's video about <ulink
314 url="https://www.youtube.com/watch?v=i6KaMrhVOw8&amp;list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS">Cross-compiling
315 and Remote Debugging of Applications</ulink>.</para>
316 </tip>
317
318 <para>Using Eclipse you can build an application, deploy it on the
319 target, and debug <indexterm>
320 <primary>debug</primary>
321 </indexterm>the source code remotely, all with a single mouse click.
322 However, in order to achieve this you need to make certain
323 configurations.</para>
324
325 <para>When setting the cross-compiler options for a target, a run/debug
326 configuration is created as a <emphasis role="bold">C/C++ Remote
327 Application</emphasis> instance. The configuration is named according to
328 this syntax <literal>&lt;project&gt;_gdb_-&lt;suffix&gt;</literal>, for
329 example: <filename>hello_gdb_aarch64-enea-linux</filename>.</para>
330
331 <note>
332 <para>If a run/debug configuration is not created when setting the
333 cross-compiler options, perform the steps in <link
334 linkend="troubleshoot_build_debug_config">Run/Debug Configuration Not
335 Created</link>.</para>
336 </note>
337
338 <para>The instructions below describes how to use Eclipse to debug
339 single-process applications on a target. For information on how to debug
340 multi-process applications, see <link
341 linkend="eclipse_multi_debug">Debugging Multi-Process Applications from
342 Eclipse</link>.</para>
343
344 <para>Use the run/debug configuration to connect the Eclipse GDB
345 interface to the remote target, by doing the following:</para>
346
347 <remark>Should we add images for the procedure below as well?</remark>
348
349 <orderedlist>
350 <listitem>
351 <para>Select <emphasis role="bold">Run &gt; Debug Configurations
352 &gt; C/C++ Remote application</emphasis> from the menu and choose
353 the run/debug configuration from the instances under <literal>C/C++
354 Remote Application</literal> in the left pane. You can rename,
355 duplicate or remove the configuration as needed.</para>
356 </listitem>
357
358 <listitem>
359 <para>In the <emphasis role="bold">Main</emphasis> tab, do the
360 following:</para>
361
362 <orderedlist spacing="compact">
363 <listitem>
364 <para>Select an existing <emphasis
365 role="bold">Connection</emphasis> from the drop-down list, or
366 create a new one following the steps below:</para>
367
368 <orderedlist>
369 <listitem>
370 <para>To create a new connection, click the <emphasis
371 role="bold">New...</emphasis> button and select a connection
372 type. For debugging applications an <emphasis
373 role="bold">SSH</emphasis> connection is recommended.</para>
374 </listitem>
375
376 <listitem>
377 <para>Choose a connection name and fill in the <emphasis
378 role="bold">Host information</emphasis> section with the
379 target's IP and the username.</para>
380
381 <note>
382 <para>For Enea Linux, the default username is <emphasis
383 role="bold">root</emphasis> and there is no password
384 set.</para>
385 </note>
386 </listitem>
387
388 <listitem>
389 <para>Depending on your network setup, select either
390 <emphasis role="bold">Public key</emphasis> or <emphasis
391 role="bold">Password-based authentication</emphasis>. If
392 using Password-based authentication, leave the field empty
393 when using the default <emphasis role="bold">root</emphasis>
394 username.</para>
395 </listitem>
396
397 <listitem>
398 <para>Click Finish. The new connection should now be
399 available in the dropdown menu. This connection will be
400 persist through all Run/Debug configurations.</para>
401
402 <para>You can manage your saved connections in the <emphasis
403 role="bold">Connections </emphasis>view from <emphasis
404 role="bold">Window -&gt; Show View -&gt; Other... -&gt;
405 Connections</emphasis>.</para>
406 </listitem>
407 </orderedlist>
408 </listitem>
409
410 <listitem>
411 <para>Select the binary <emphasis role="bold">C/C++
412 Application</emphasis> you want to deploy.</para>
413
414 <para>If you click the <emphasis role="bold">Search
415 Project</emphasis> button, Eclipse will parse the project and
416 provide a list of all compiled binaries to choose from.
417 Alternatively, you can <emphasis role="bold">Browse</emphasis>
418 the file system for a binary, or use <emphasis
419 role="bold">Variables</emphasis> to manually define the
420 path.</para>
421 </listitem>
422
423 <listitem>
424 <para>The <emphasis role="bold">Remote Absolute File
425 Path</emphasis> is the path to which the binary on the target
426 shall be deployed. Type it directly or click the <emphasis
427 role="bold">Browse</emphasis> button and select a location on
428 the remote target. Note that you need to specify the path
429 including the filename.</para>
430 </listitem>
431
432 <listitem>
433 <para>Optionally, you may choose not to download the application
434 to the target, but instead debug an already downloaded
435 application.</para>
436 </listitem>
437
438 <listitem>
439 <para>You can also configure Eclipse to execute commands prior
440 to launching the application, by specifying the commands in the
441 corresponding field.</para>
442 </listitem>
443 </orderedlist>
444 </listitem>
445
446 <listitem>
447 <para>In the <emphasis role="bold">Arguments</emphasis> tab you can
448 specify various arguments to be passed to your application at
449 launch-time.</para>
450 </listitem>
451
452 <listitem>
453 <para>The <emphasis role="bold">Debugger</emphasis> tab deals with
454 GDB specific configurations. This is automatically populated when
455 configuring the cross-compiler. You may optionally choose
456 additionally useful options as with any Eclipse GDB interface, e.g.
457 whether to break at entering the main function or uploading shared
458 libraries.</para>
459 </listitem>
460
461 <listitem>
462 <para>To enable debugging with shared libraries, do the
463 following:</para>
464
465 <itemizedlist>
466 <listitem>
467 <para>Retrieve the debug sources from the target, and store them
468 in a dedicated folder on the local host. They are found in
469 <literal>/usr/src/debug</literal> in the target rootfs.</para>
470 </listitem>
471
472 <listitem>
473 <para>Set a path mapping your debug configuration. In the
474 <emphasis role="bold">Source</emphasis> tab, click <emphasis
475 role="bold">Add</emphasis>, select <emphasis role="bold">Path
476 Mapping</emphasis>, and assign paths to the mapping:</para>
477
478 <simplelist>
479 <member><emphasis role="bold">Compilation path</emphasis>:
480 <filename>/usr/src/debug</filename></member>
481
482 <member><emphasis role="bold">Local file system
483 path</emphasis> (path to the debug sources retrieved from the
484 target):<filename>
485 &lt;path_to_chosen_folder&gt;/usr/src/debug</filename></member>
486 </simplelist>
487 </listitem>
488
489 <listitem>
490 <para>In the <emphasis role="bold">Debugger/Shared
491 Libraries</emphasis> tab, select option <emphasis
492 role="bold">Load shared library symbols automatically</emphasis>
493 and set the path to the shared library. The path depends on the
494 processor architecture of your target.</para>
495
496 <para>For <emphasis role="bold">32-bit</emphasis> targets:
497 <filename>&lt;extsdkdir&gt;/sysroots/&lt;arch&gt;-enea-linux/lib/.debug
498 </filename></para>
499
500 <para>For <emphasis role="bold">64-bit</emphasis> targets:
501 <filename>&lt;extsdkdir&gt;/sysroots/&lt;arch&gt;-enea-linux/lib64/.debug</filename></para>
502
503 <para>Note that inside Eclipse you must load the shared
504 libraries with debug information (not stripped). Shared
505 libraries that get built into the rootfs of the target image
506 have debug information stripped off, for size and speed
507 optimizations.</para>
508 </listitem>
509
510 <listitem>
511 <para>To debug applications that depend on shared libraries
512 built outside the rootfs of the target image, the same procedure
513 applies, with the exception that you must upload the required
514 shared libraries to the target prior to starting the debugging
515 session.</para>
516
517 <para>If you upload them to <literal>/lib</literal> or
518 <literal>/lib64</literal> (depending on the target architecture)
519 they get loaded by default. Otherwise, you must correctly update
520 the <emphasis role="bold"><literal>
521 LD_LIBRARY_PATH</literal></emphasis> environment variable to
522 match their look-up path. In Eclipse, you can automatically
523 update this variable by setting the <emphasis
524 role="bold">Commands to execute before application</emphasis>
525 field to: <emphasis role="bold">export
526 <literal>LD_LIBRARY_PATH=&lt;path to uploaded shared
527 libs&gt;</literal> </emphasis></para>
528 </listitem>
529 </itemizedlist>
530 </listitem>
531
532 <listitem>
533 <para>Once you have set up all the debug configurations, click
534 <emphasis role="bold">Apply</emphasis> and <emphasis
535 role="bold">Debug</emphasis>. This will launch the GDB on the target
536 and open the <literal>Debug perspective</literal>. This is the
537 standard Eclipse GDB interface when debugging a remote target. You
538 can use all GDB features, such as setting breakpoints, stepping
539 through code, reading variable values, reading registers, viewing
540 memory, etc.</para>
541 </listitem>
542 </orderedlist>
543
544 <para>When the debugger starts, Eclipse opens three consoles:</para>
545
546 <orderedlist numeration="upperalpha" spacing="compact">
547 <listitem>
548 <para>The <emphasis role="bold">Remote Shell</emphasis> - used to
549 launch the application and display its output.</para>
550 </listitem>
551
552 <listitem>
553 <para>The <emphasis role="bold">GDB console</emphasis> - named as
554 the path to its GDB binary. You can use this console to control the
555 GDB from the command line.</para>
556 </listitem>
557
558 <listitem>
559 <para>The third console is named as the path of the binary on the
560 local machine, and is in fact an artifact that must be
561 ignored.</para>
562 </listitem>
563 </orderedlist>
564
565 <para>After having set up the debug configuration once, you can modify
566 and rebuild your application and then relaunch it by simply clicking the
567 <emphasis role="bold">Debug</emphasis> icon (the bug symbol) on the
568 toolbar. You can also select the drop-down list for more configurations,
569 and even add your configuration to the <emphasis
570 role="bold">Favorites</emphasis> to easily retrieve it next time.</para>
571
572 <para>If you only want to deploy and run the application, without
573 debugging, you can use the same configuration as the one set up for
574 debugging, but simply click the <emphasis role="bold">Run</emphasis>
575 icon (the Play button symbol) from the toolbar menu, or select <emphasis
576 role="bold">Run &gt; Run Configurations</emphasis> and Run the chosen
577 configuration.</para>
578 </section>
579
580 <section id="eclipse_multi_debug">
581 <title>Debugging Multi-Process Applications from Eclipse</title>
582
583 <para>In Eclipse, remote debugging of an application that uses multiple
584 processes<indexterm>
585 <primary>multiple processes</primary>
586 </indexterm> is slightly different compared to debugging a single
587 process application as described in <link
588 linkend="eclipse_debug">Debugging Applications from
589 Eclipse</link>.</para>
590
591 <para>The following limitations exist for multi-process
592 debugging:</para>
593
594 <itemizedlist spacing="compact">
595 <listitem>
596 <para>All debugged processes must share the same binary.</para>
597 </listitem>
598
599 <listitem>
600 <para>Debugging only works in non-stop mode, i.e. stopping at a
601 breakpoint only stops the current thread while other threads
602 continue to execute.</para>
603 </listitem>
604 </itemizedlist>
605
606 <note>
607 <para>When using the GDB to debug multiple instances of the same
608 process or thread, using the same symbols file, breakpoints will be
609 common to all instances. That is, when setting a breakpoint in the
610 code, all instances will stop there, and there is no way to filter
611 them. The current thread filter in Eclipse is ineffective.</para>
612 </note>
613
614 <para><emphasis role="bold">Use the run/debug configuration to connect
615 the Eclipse GDB client to the remote target</emphasis>:</para>
616
617 <orderedlist>
618 <listitem>
619 <para>Go to <emphasis role="bold">Window &gt; Preferences &gt;
620 Run/Debug &gt; Launching &gt; Default Launchers</emphasis>. Under
621 <emphasis role="bold">C/C++ Attach to Applicaton &gt;
622 Debug</emphasis> select the checkbox <emphasis role="bold">GDB (DSF)
623 Attach to Process via TCF/TE Launcher</emphasis>.</para>
624 </listitem>
625
626 <listitem>
627 <para>Select <emphasis role="bold">Run &gt; Debug Configurations...
628 </emphasis> from the menu and choose the run/debug configuration
629 from the instances under <literal>C/C++ Attach to
630 Application</literal> in the left pane. You can create, rename,
631 duplicate, or remove the configurations as needed.</para>
632 </listitem>
633
634 <listitem>
635 <para>If you followed <emphasis role="bold">step 1</emphasis>, in
636 the lower part of the dialog you will see that <emphasis
637 role="bold">Using GDB (DSF) Attach to Process via TCF/TE
638 Launcher</emphasis> is selected. If not, redo <emphasis
639 role="bold">step 1</emphasis> or click the <emphasis
640 role="bold">Select Other...</emphasis> link, and use configuration
641 specific settings by selecting the checkbox <emphasis
642 role="bold">GDB (DSF) Attach to Process via TCF/TE
643 Launcher</emphasis>.</para>
644 </listitem>
645
646 <listitem>
647 <para>In the <emphasis role="bold">Main</emphasis> tab, do the
648 following:</para>
649
650 <orderedlist spacing="compact">
651 <listitem>
652 <para>Select the binary <emphasis role="bold">C/C++
653 Application</emphasis> you want to deploy. If you click the
654 <emphasis role="bold">Search Project</emphasis> button, Eclipse
655 will parse the project and provide a list of all compiled
656 binaries to choose from. Alternatively, you can <emphasis
657 role="bold">Browse</emphasis> the file system for a binary, or
658 use <emphasis role="bold">Variables</emphasis> to manually
659 define the path.</para>
660 </listitem>
661
662 <listitem>
663 <para>Select an existing <emphasis
664 role="bold">Connection</emphasis> from the drop-down list. If a
665 connection is not available, create a new one following the
666 steps in <link linkend="eclipse_remote_connection">Setting up a
667 TCF Connection from Eclipse</link>.</para>
668 </listitem>
669
670 <listitem>
671 <para>The <emphasis role="bold">Remote Absolute File
672 Path</emphasis> is the path to the binary of the process you are
673 planning to debug. Type it directly or click the <emphasis
674 role="bold">Browse</emphasis> button and select a location on
675 the remote target. You need an active TCF connection to the
676 target for the <emphasis role="bold">Browse</emphasis> button to
677 work (see chapter <emphasis role="bold">Setting up a TCF
678 Connection from Eclipse</emphasis>). Note that you need to
679 specify the path including the filename.</para>
680 </listitem>
681
682 <listitem>
683 <para>Specify the PID of the remote process you are planning to
684 attach.</para>
685 </listitem>
686 </orderedlist>
687 </listitem>
688
689 <listitem>
690 <para>The <emphasis role="bold">Debugger</emphasis> tab deals with
691 GDB specific configurations. Select the <emphasis
692 role="bold">gdbserver</emphasis> in the Debugger dropdown. You may
693 also choose other useful options as with any Eclipse GDB interface,
694 e.g. whether to break at entering the main function or uploading
695 shared libraries. The following actions are important:</para>
696
697 <orderedlist spacing="compact">
698 <listitem>
699 <para>In the <emphasis role="bold">Main</emphasis> tab, enter
700 the path to the GDB binary in the SDK. For example:
701 <literal>&lt;extsdkdir&gt;/tmp/sysroots/x86_64-linux/usr/bin/&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</literal>.</para>
702 </listitem>
703
704 <listitem>
705 <para>Select option <literal>Non-stop mode</literal>.</para>
706 </listitem>
707 </orderedlist>
708 </listitem>
709
710 <listitem>
711 <para>Once you have set up all the debug configurations, click
712 <emphasis role="bold">Apply</emphasis> and <emphasis
713 role="bold">Debug</emphasis>. This will launch the GDB and
714 optionally open the <literal>Debug perspective</literal> for the
715 process you selected. This is the standard Eclipse GDB interface
716 when debugging a remote target. You can use all GDB features, such
717 as setting breakpoints, stepping through code, reading variable
718 values, reading registers, viewing memory, etc.</para>
719 </listitem>
720 </orderedlist>
721
722 <para>Repeat these steps for each process you want to debug. You can
723 have multiple debug sessions running simultaneously for multiple
724 processes sharing the same source code.</para>
725 </section>
726
727 <section id="eclipse_postmortem">
728 <title>Using the Postmortem Debugger</title>
729
730 <para>When a program crashes<indexterm>
731 <primary>post-mortem debugging</primary>
732 </indexterm><indexterm>
733 <primary>core dump</primary>
734 </indexterm>, it may leave a core dump which can be used to figure out
735 exactly why the program crashed. Core dumps are disabled by default and
736 have to be activated before debugging. After retrieving and transferring
737 a core dump file to a host machine, Eclipse and the SDK tool generated
738 for the target, can be used to analyze the application state at the time
739 of the crash.</para>
740
741 <para>If deep debugging within Linux libraries is needed, the debug SDK
742 is required. See <link linkend="install_el_sdk">Installing Enea Linux
743 SDK</link>.</para>
744
745 <para>To enable writing core dump files, two steps need to be performed
746 on the target: <emphasis>allowing resources for core dumps</emphasis>
747 and <emphasis>defining a core file name pattern</emphasis>. These
748 settings are valid until the next reboot, unless made permanent by
749 configuration changes in the root file system.</para>
750
751 <para>Use the <command>ulimit</command> command to allow the system to
752 use resources for core dumps. The <command>ulimit</command> command
753 controls the resources available to a process started by the shell, on
754 systems that allow such control. Type the following to use this
755 command:</para>
756
757 <programlisting>ulimit -c unlimited</programlisting>
758
759 <para>To verify the result, type <command>ulimit -a</command> and see if
760 the core file size is set to <literal>unlimited</literal>. User limits
761 can also be changed from the application code using the function
762 <function>setrlimit(...)</function> declared in the
763 <literal>sys/resource.h</literal> header (see the manual available
764 through <command>man setrlimit</command>). To make this permanent across
765 a reboot, adjust the configuration in
766 <filename>/etc/security/limits.conf</filename>.</para>
767
768 <para>The next step is to specify the core pattern which defines the
769 core dump file pattern name. The core pattern is defined in the
770 <literal>/proc/sys/kernel/core_pattern</literal>.</para>
771
772 <para>The format of a core pattern follows certain rules:</para>
773
774 <itemizedlist>
775 <listitem>
776 <para>The maximum length is 128 characters</para>
777 </listitem>
778
779 <listitem>
780 <para>Default core dump name is <filename>core</filename></para>
781 </listitem>
782
783 <listitem>
784 <para>The string stored in <literal>core_pattern</literal> is used
785 as a pattern template for the output filename. Certain string
786 patterns (beginning with <literal>%</literal>) are substituted with
787 their actual values. The patterns are:</para>
788
789 <programlisting>%&lt;NUL&gt; '%' is dropped
790%% output one '%'
791%p pid
792%P global pid (init PID namespace)
793%i tid
794%I global tid (init PID namespace)
795%u uid (in initial user namespace)
796%g gid (in initial user namespace)
797%d dump mode, matches PR_SET_DUMPABLE and /proc/sys/fs/suid_dumpable
798%s signal number
799%t UNIX time of dump
800%h hostname
801%e executable filename (may be shortened)
802%E executable path
803%&lt;OTHER&gt; both are dropped</programlisting>
804 </listitem>
805
806 <listitem>
807 <para>If the first character of the pattern is a
808 '<literal>|</literal>', the kernel will treat the rest of the
809 pattern as a command to run. The core dump will be written to the
810 standard input of that program instead of to a file.</para>
811 </listitem>
812
813 <listitem>
814 <para>By setting the value <literal>core_uses_pid</literal> to
815 <literal>1</literal>, the core dump filename gets the extension
816 <filename>.PID</filename>, if the <literal>core_pattern</literal>
817 does not contain "<literal><literal>%p</literal></literal>".</para>
818
819 <para>For example, the default file name <filename>core</filename>
820 becomes <filename>core.PID</filename> if the
821 <literal>core_uses_pid</literal> is set, and no
822 <literal>core_pattern</literal> is defined.</para>
823 </listitem>
824 </itemizedlist>
825
826 <para>Specify a core pattern by writing it to
827 <literal>/proc/sys/kernel/core_pattern</literal>. For example:
828 <programlisting><literal>echo "&lt;suitable_directory&gt;/core.%e.%p.%h.%t" &gt; /proc/sys/kernel/core_pattern</literal></programlisting></para>
829
830 <para>To make the core dump file name permanent across a reboot,
831 configure <filename>/etc/sysctl.conf</filename>. to reflect this choice,
832 by adding a line like in the following example:
833 <literal>kernel.core_pattern=&lt;suitable_directory&gt;/core.%e.%p.%h.%t</literal>.</para>
834
835 <para>How to use the Eclipse post mortem debug configuration in order to
836 view the call trace, for the core dump in the Eclipse GDB
837 interface:</para>
838
839 <orderedlist spacing="compact">
840 <listitem>
841 <para>Ensure a core dump can be created on the target, see the
842 information above. To see the full call stack, the application
843 object files, compiled with debug information, are needed (the
844 <literal>-g</literal> option in gcc).</para>
845 </listitem>
846
847 <listitem>
848 <para>After a core dump has been created, retrieve the core dump
849 file from the target and store it on the host.</para>
850 </listitem>
851
852 <listitem>
853 <para>In Eclipse on the host, you need the core dump file, the SDK
854 for the target, the application executable, and access to the source
855 code. Once you have those, do the following:<orderedlist
856 spacing="compact">
857 <listitem>
858 <para>Switch to the <literal>Debug</literal> perspective in
859 Eclipse.</para>
860 </listitem>
861
862 <listitem>
863 <para>Select <emphasis role="bold">Run -&gt; Debug
864 Configurations ...</emphasis> (scroll down if you don't see
865 the option at first glance) <emphasis role="bold">-&gt; C/C++
866 Postmortem Debugger</emphasis>.</para>
867 </listitem>
868
869 <listitem>
870 <para>Make sure the <literal>C/C++ Application</literal> field
871 refers to your project executable, and fill in the
872 <literal>Core file</literal> field with the path to the
873 downloaded core file.</para>
874 </listitem>
875
876 <listitem>
877 <para>Under the <emphasis role="bold">Debugger</emphasis> tab,
878 fill in the <literal>GDB Debugger</literal> field with the
879 path to the GDB binary from the SDK. Example path:
880 <filename>&lt;extsdkdir&gt;/tmp/sysroots/x86_64-linux/usr/bin/&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</filename></para>
881 </listitem>
882
883 <listitem>
884 <para>Click the <literal>Debug</literal> button. Eclipse
885 should switch into the <literal>Debug</literal> perspective
886 (if it hasn't already) and the debugging instance should break
887 somewhere inside the application. The call stack should be
888 observable in the console and should show a termination
889 message.</para>
890 </listitem>
891 </orderedlist></para>
892 </listitem>
893 </orderedlist>
894 </section>
895 </section>
896
897 <section id="eclipse_kern_debug">
898 <title>Debugging the Linux Kernel in Eclipse</title>
899
900 <para>In this section you learn to set up Eclipse for KGDB<indexterm>
901 <primary>KGDB</primary>
902 </indexterm> kernel debugging over the serial port, with examples for
903 the <literal>raspberrypi3</literal> target. This is only given as an
904 example, your Enea Linux distribution may contain other targets. The
905 corresponding instruction for debugging outside Eclipse is available in
906 Debugging the Linux Kernel (KGDB) from Command Line.<remark>LATER: Merge
907 the two instructions to shrink the amount of text; most of it is the
908 same.</remark></para>
909
910 <para>How to set up Eclipse for KGDB kernel debugging over a serial
911 port:</para>
912
913 <orderedlist>
914 <listitem>
915 <para>Make sure that the cross-compilation toolchain<indexterm>
916 <primary>cross-compilation toolchain</primary>
917 </indexterm><indexterm>
918 <primary>toolchain</primary>
919
920 <secondary>cross-compilation</secondary>
921 </indexterm> (SDK<indexterm>
922 <primary>SDK</primary>
923 </indexterm>) is installed on the host, see <link
924 linkend="install_el_sdk">Installing Enea Linux SDK</link>.</para>
925 </listitem>
926
927 <listitem>
928 <para>Ensure that the kernel debug image
929 (<literal>vmlinux)</literal>is accessible on the host where you run
930 Eclipse, and that you have permissions to execute it. You will later
931 point to it in Eclipse.</para>
932
933 <para>If you are using the default kernel delivered with Enea Linux,
934 you can find it in the rootfs under the <literal>/boot</literal>
935 folder. If you build your own kernel using bitbake, it should be
936 available in your build folder. Located in, for example:
937 <filename><filename>tmp/work/raspberrypi3_64-enea-linux/linux-raspberrypi/1_4.9.59+gitAUTOINC+meta_machine-r0/image/boot/vmlinux-4.9.59</filename></filename></para>
938 </listitem>
939
940 <listitem>
941 <para>In Eclipse:</para>
942
943 <orderedlist>
944 <listitem>
945 <para>Optional: The Linux kernel has a considerable amount of
946 sources, and indexing the whole of it might take a lot of time.
947 Save time by disabling C/C++ project indexing:<orderedlist
948 spacing="compact">
949 <listitem>
950 <para>Select <emphasis role="bold">Window &gt; Preferences
951 &gt; C/C++ &gt; Indexer</emphasis>.</para>
952 </listitem>
953
954 <listitem>
955 <para>Unselect the <emphasis role="bold">Enable
956 indexer</emphasis> checkbox.</para>
957 </listitem>
958 </orderedlist></para>
959 </listitem>
960
961 <listitem>
962 <para>Create a project from the kernel tree:</para>
963
964 <orderedlist spacing="compact">
965 <listitem>
966 <para>Select <emphasis role="bold">File &gt; New &gt; Project
967 &gt; C/C++ &gt; C project</emphasis>.</para>
968 </listitem>
969
970 <listitem>
971 <para>In the left panel, select <emphasis role="bold">Makefile
972 project &gt; Empty project</emphasis>, and give the project a
973 name.</para>
974 </listitem>
975
976 <listitem>
977 <para>Unselect the <emphasis role="bold">Use default
978 location</emphasis> option.</para>
979 </listitem>
980
981 <listitem>
982 <para>Click <emphasis role="bold">Browse</emphasis> and
983 navigate to the location of the kernel sources (git
984 folder).</para>
985 </listitem>
986
987 <listitem>
988 <para>Click <emphasis role="bold">Finish</emphasis>.</para>
989 </listitem>
990 </orderedlist>
991 </listitem>
992
993 <listitem>
994 <para>Create a C/C++ GDB Hardware Debugging configuration:</para>
995
996 <orderedlist spacing="compact">
997 <listitem>
998 <para>Go to <emphasis role="bold">Run -&gt; Debug
999 Configurations</emphasis>.</para>
1000 </listitem>
1001
1002 <listitem>
1003 <para>Double-click <emphasis role="bold">GDB Hardware
1004 Debugging</emphasis>.</para>
1005 </listitem>
1006 </orderedlist>
1007
1008 <para>This will create a default configuration named
1009 <literal>project_name Default</literal>.</para>
1010 </listitem>
1011
1012 <listitem>
1013 <para>In the <emphasis role="bold">Main</emphasis> tab:</para>
1014
1015 <orderedlist spacing="compact">
1016 <listitem>
1017 <para>Browse to the location of the
1018 <filename>vmlinux</filename> image. As an alternative, you may
1019 select a different project to debug, but if you followed the
1020 steps above you should not need to modify this.</para>
1021 </listitem>
1022
1023 <listitem>
1024 <para>Select the <emphasis role="bold">Disable auto
1025 build</emphasis> radio button.</para>
1026 </listitem>
1027
1028 <listitem>
1029 <para>At the bottom of the window, make sure <emphasis
1030 role="bold">GDB (DSF) Hardware Debugging Launcher</emphasis>
1031 is selected.</para>
1032 </listitem>
1033 </orderedlist>
1034 </listitem>
1035
1036 <listitem>
1037 <para>In the <emphasis role="bold">Debugger</emphasis> tab for
1038 <emphasis role="bold">C/C++ Application</emphasis>:</para>
1039
1040 <orderedlist spacing="compact">
1041 <listitem>
1042 <para>Browse to the location of the <emphasis role="bold">GDB
1043 binary</emphasis> installed by the cross-compilation toolchain
1044 installer, by default:
1045 <filename>&lt;extsdkdir&gt;/tmp/sysroots/x86_64-linux/usr/bin/&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</filename>.</para>
1046 </listitem>
1047
1048 <listitem>
1049 <para>Select option <emphasis role="bold">Use remote
1050 target</emphasis>.</para>
1051 </listitem>
1052
1053 <listitem>
1054 <para>In the <emphasis role="bold">JTAG Device</emphasis>,
1055 select <emphasis role="bold">Generic Serial</emphasis> from
1056 the dropdown list.</para>
1057 </listitem>
1058
1059 <listitem>
1060 <para>In the <emphasis role="bold">GDB Connection
1061 String</emphasis> field, type the host's tty device used for
1062 the serial connection to the target, e.g.
1063 <literal>/dev/ttyUSB0</literal>.</para>
1064 </listitem>
1065 </orderedlist>
1066 </listitem>
1067
1068 <listitem>
1069 <para>In the <emphasis role="bold">Startup</emphasis> tab:</para>
1070
1071 <orderedlist spacing="compact">
1072 <listitem>
1073 <para>Deselect the <emphasis role="bold">Load image</emphasis>
1074 option.</para>
1075 </listitem>
1076
1077 <listitem>
1078 <para>Select the <emphasis role="bold">Load symbols</emphasis>
1079 option.</para>
1080 </listitem>
1081
1082 <listitem>
1083 <para>Ensure that the <emphasis role="bold">Use project
1084 binary</emphasis> option defaults to your
1085 <literal>vmlinux</literal> image.</para>
1086 </listitem>
1087
1088 <listitem>
1089 <para>Click <emphasis role="bold">Apply</emphasis> to store
1090 the configurations above.</para>
1091 </listitem>
1092 </orderedlist>
1093 </listitem>
1094 </orderedlist>
1095 </listitem>
1096
1097 <listitem>
1098 <para>Prepare the target for KGDB debugging:</para>
1099
1100 <orderedlist>
1101 <listitem>
1102 <para>Configure a serial communication on the target, using the
1103 appropriate device for the target (e.g. <literal>ttyS0</literal>
1104 for <literal>p2020rdb</literal>, <literal>ttyS2</literal> for
1105 <literal>pandaboard</literal>, <literal>ttyPS0</literal> for
1106 <literal>zynq</literal>):</para>
1107
1108 <programlisting><command>echo ttyS0,115200 &gt; /sys/module/kgdboc/parameters/kgdboc</command></programlisting>
1109 </listitem>
1110
1111 <listitem>
1112 <para>Start KGDB on the target SysRq:</para>
1113
1114 <programlisting><command>echo g &gt; /proc/sysrq-trigger</command></programlisting>
1115 </listitem>
1116
1117 <listitem>
1118 <para>Keep the serial connection open, but close the terminal to
1119 the target.</para>
1120 </listitem>
1121 </orderedlist>
1122 </listitem>
1123
1124 <listitem>
1125 <para>Launch the debug session in Eclipse:</para>
1126
1127 <orderedlist spacing="compact">
1128 <listitem>
1129 <para>Select <emphasis role="bold">Run &gt; Debug
1130 Configurations</emphasis>.</para>
1131 </listitem>
1132
1133 <listitem>
1134 <para>Select the configuration created above.</para>
1135 </listitem>
1136
1137 <listitem>
1138 <para>Click the <emphasis role="bold">Debug</emphasis>
1139 button.</para>
1140 </listitem>
1141 </orderedlist>
1142
1143 <para>The target halts in function
1144 <literal>kgdb_breakpoint()</literal>. The GDB view opens in Eclipse,
1145 and from here you can debug the kernel by giving ordinary GDB commands
1146 (<command>resume</command>, <command>step</command>, <command>set
1147 breakpoint,</command> etc.).</para>
1148 </listitem>
1149 </orderedlist>
1150 </section>
1151
1152 <section id="workarounds">
1153 <title>Workarounds</title>
1154
1155 <section id="troubleshoot_build_debug_config">
1156 <title>Run/Debug Configuration Not Created</title>
1157
1158 <itemizedlist>
1159 <listitem>
1160 <para><emphasis role="bold">Description:</emphasis> When setting up
1161 <link linkend="eclipse_debug">Remote Debugging from Eclipse</link>,
1162 a run/debug configuration is not created when setting the
1163 cross-compiler options, thus there is nothing to select under
1164 <emphasis role="bold">C/C++ Remote Application</emphasis> in the
1165 first step.</para>
1166 </listitem>
1167
1168 <listitem>
1169 <para><emphasis role="bold">Solution:</emphasis> Manually create a
1170 run/debug configuration.</para>
1171
1172 <para>Perform the following steps:</para>
1173
1174 <orderedlist>
1175 <listitem>
1176 <para>Double-click the <emphasis role="bold">C/C++ Remote
1177 Application</emphasis>. This will create a new debug
1178 configuration named after your project.</para>
1179 </listitem>
1180
1181 <listitem>
1182 <para>In the <emphasis role="bold">Debugger</emphasis> tab,
1183 select a <emphasis role="bold">GDB debugger</emphasis> by
1184 browsing for and selecting the debugger of your
1185 cross-compilation toolchain, from your <emphasis
1186 role="bold">Sysroot Location</emphasis>. Example:</para>
1187
1188 <programlisting>$ &lt;extsdkdir&gt;/tmp/sysroots/x86_64-linux/usr/bin/\
1189&lt;arch&gt;-enea-linux/&lt;arch&gt;-enea-linux-gdb</programlisting>
1190
1191 <para>where <filename>&lt;sdkdir&gt;</filename> is e.g.
1192 <filename>/opt/enea/&lt;sdkversion&gt;</filename>.</para>
1193 </listitem>
1194
1195 <listitem>
1196 <para>Outside Eclipse, create a new file named
1197 <filename>.gdbinit</filename> within your Eclipse workspace,
1198 under your project directory, e.g. <filename>&lt;path to
1199 workspace&gt;/&lt;project name&gt;/.gdbinit</filename>, with the
1200 following command, using your <emphasis role="bold">Sysroot
1201 Location</emphasis>:</para>
1202
1203 <programlisting>$ set sysroot &lt;extsdkdir&gt;/sysroots</programlisting>
1204 </listitem>
1205
1206 <listitem>
1207 <para>Back in Eclipse in the <emphasis
1208 role="bold">Debugger</emphasis> tab, browse for the newly
1209 created <emphasis role="bold">.gdbinit</emphasis> file and
1210 select it under <emphasis role="bold">GDB command
1211 file</emphasis>.</para>
1212 </listitem>
1213
1214 <listitem>
1215 <para>Click <emphasis role="bold">Apply</emphasis>, then go back
1216 to the <emphasis role="bold">Main</emphasis> tab and continue
1217 with the remaining steps in the <emphasis role="bold">Remote
1218 Debugging</emphasis> section.</para>
1219 </listitem>
1220 </orderedlist>
1221 </listitem>
1222 </itemizedlist>
1223 </section>
1224 </section>
1225</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-06 13:50:05 +0000