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