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