summaryrefslogtreecommitdiffstats
path: root/doc/book-enea-nfv-access-guide
diff options
context:
space:
mode:
authorMiruna Paun <Miruna.Paun@enea.com>2017-09-29 16:00:38 +0200
committerMiruna Paun <Miruna.Paun@enea.com>2017-09-29 16:00:38 +0200
commit561fc2769a9e42464729b49024883fcf29d07dd1 (patch)
treec02947dde5d13b0b757f17733441c76d3ff1ed00 /doc/book-enea-nfv-access-guide
parentce8e7fe907e2b44d483547955da60a19de5ed089 (diff)
downloadel_releases-nfv-access-561fc2769a9e42464729b49024883fcf29d07dd1.tar.gz
Added the latest changes from el_releases-virtualization.git
USERDOCAP-242 Signed-off-by: Miruna Paun <Miruna.Paun@enea.com>
Diffstat (limited to 'doc/book-enea-nfv-access-guide')
-rw-r--r--doc/book-enea-nfv-access-guide/doc/using_nfv_access_sdks.xml363
1 files changed, 320 insertions, 43 deletions
diff --git a/doc/book-enea-nfv-access-guide/doc/using_nfv_access_sdks.xml b/doc/book-enea-nfv-access-guide/doc/using_nfv_access_sdks.xml
index 18602a1..e5c28ea 100644
--- a/doc/book-enea-nfv-access-guide/doc/using_nfv_access_sdks.xml
+++ b/doc/book-enea-nfv-access-guide/doc/using_nfv_access_sdks.xml
@@ -4,24 +4,61 @@
4<chapter id="workflow"> 4<chapter id="workflow">
5 <title>Using NFV Access SDKs</title> 5 <title>Using NFV Access SDKs</title>
6 6
7 <para>Enea NFV Access comes with two different toolchains, one for 7 <para>Enea NFV Access comes with two standard SDKs which can be used to
8 developing applications for the host and one for applications running in the 8 develop user-applications and kernel modules for both host and guest
9 guest VM. Each is wrapped together with an environment-setup script into a 9 images.</para>
10 shell archive and is available under the Download section on 10
11 portal.enea.com. They have self explanatory names.</para> 11 <para>A standard SDK consists of:</para>
12 12
13 <itemizedlist> 13 <itemizedlist>
14 <listitem> 14 <listitem>
15 <para><literal>inteld1521/sdk/enea-glibc-x86_64-enea-image-virtualization-host-sdk-corei7-64-toolchain-7.0.sh</literal> 15 <para>Cross-Development Toolchain: cross-compiler and
16 cross-debugger</para>
17 </listitem>
18
19 <listitem>
20 <para>Libraries, Headers and Symbols that are specific to the
21 image</para>
22 </listitem>
23
24 <listitem>
25 <para>Environment Setup Script which defines the environment
26 variables</para>
27 </listitem>
28 </itemizedlist>
29
30 <para>To install the SDK on your host development machine, there are two
31 installation scripts available under the Download section on <emphasis
32 role="bold">portal.enea.com</emphasis>. They have self explanatory
33 names.</para>
34
35 <itemizedlist>
36 <listitem>
37 <para><literal>inteld1521/sdk/enea-glibc-x86_64-enea-image-virtualization-host-sdkcorei7-64-toolchain-7.0.sh</literal>
16 - for host applications.</para> 38 - for host applications.</para>
17 </listitem> 39 </listitem>
18 40
19 <listitem> 41 <listitem>
20 <para><literal>qemux86-64/sdk/enea-glibc-x86_64-enea-image-virtualization-guest-sdk-core2-64-toolchain-7.0.sh</literal> 42 <para><literal>qemux86-64/sdk/enea-glibc-x86_64-enea-image-virtualization-guestsdk-core2-64-toolchain-7.0.sh</literal>
21 - for guest applications.</para> 43 - for guest applications.</para>
22 </listitem> 44 </listitem>
23 </itemizedlist> 45 </itemizedlist>
24 46
47 <para>After installing the SDK, a developer will be able to compile and
48 generate executables for the preferred target machine. Cross-gdb
49 (<filename>x86_64-enea-linux-gdb</filename>) is created by the
50 Cross-Development toolchain. It can be used to debug applications on the
51 target platform from the development workstation. For kernel debugging,
52 <command>ftrace</command> and <command>kgdb</command> are enabled on the
53 host sdk image.</para>
54
55 <para>Various user-space tools helpful in the development process, are also
56 provided. The tools include <emphasis role="bold">LatencyTop</emphasis>,
57 <emphasis role="bold">Perf</emphasis>, <emphasis
58 role="bold">CrossTap</emphasis>, <emphasis role="bold">OProfile</emphasis>,
59 <emphasis role="bold">Lttng-ust</emphasis> and <emphasis
60 role="bold">GDBserver</emphasis>.</para>
61
25 <section id="install-crosscomp"> 62 <section id="install-crosscomp">
26 <title>Installing the Cross-Compilation Toolchain</title> 63 <title>Installing the Cross-Compilation Toolchain</title>
27 64
@@ -33,12 +70,12 @@
33 <listitem> 70 <listitem>
34 <para><programlisting>$ ./enea-glibc-x86_64-enea-image-virtualization-guest-sdk-core2-64-toolchain-7.0.sh</programlisting>When 71 <para><programlisting>$ ./enea-glibc-x86_64-enea-image-virtualization-guest-sdk-core2-64-toolchain-7.0.sh</programlisting>When
35 prompted, select to install the toolchain in the desired directory, 72 prompted, select to install the toolchain in the desired directory,
36 referred to as <literal>&lt;sdkdir&gt;</literal>. </para> 73 referred to as <literal>sdkdir</literal>.</para>
37 74
38 <para>A default path where the toolchain will be installed will be 75 <para>A default path where the toolchain will be installed will be
39 shown in the prompt. The installer unpacks the environment setup 76 shown in the prompt. The installer unpacks the environment setup
40 script in <literal>&lt;sdkdir&gt;</literal> and the toolchain under 77 script in <literal>sdkdir</literal> and the toolchain under
41 <literal>&lt;sdkdir&gt;/sysroots</literal>.</para> 78 <literal>sdkdir/sysroots</literal>.</para>
42 79
43 <note> 80 <note>
44 <para>Choose a unique directory for each toolchain. Installing a 81 <para>Choose a unique directory for each toolchain. Installing a
@@ -50,7 +87,7 @@
50 87
51 <listitem> 88 <listitem>
52 <para>Setup the toolchain environment for your target by sourcing the 89 <para>Setup the toolchain environment for your target by sourcing the
53 environment-setup script. Example: <programlisting>$ source &lt;sdkdir&gt;/environment-setup-core2-64-enea-linux</programlisting></para> 90 environment-setup script. Example: <programlisting>$ source sdkdir/environment-setup-core2-64-enea-linux</programlisting></para>
54 </listitem> 91 </listitem>
55 </orderedlist> 92 </orderedlist>
56 </section> 93 </section>
@@ -71,7 +108,7 @@
71 $(CC) -o helloworld helloworld.o 108 $(CC) -o helloworld helloworld.o
72clean: 109clean:
73 rm -f *.o helloworld 110 rm -f *.o helloworld
74#include &lt;stdio.h&gt; 111#include stdio.h;
75int main(void) { 112int main(void) {
76 printf("Hello World\n"); 113 printf("Hello World\n");
77 return 0; 114 return 0;
@@ -100,7 +137,7 @@ hello world</programlisting>
100 <para>Before cross-compiling kernle modules, you need to make sure the 137 <para>Before cross-compiling kernle modules, you need to make sure the
101 installed toolchain includes the kernel source tree, which should be 138 installed toolchain includes the kernel source tree, which should be
102 available at: 139 available at:
103 <literal>&lt;sdkdir&gt;/sysroots/&lt;targetarch&gt;-enea-linux/usr/src/kernel</literal>.</para> 140 <literal>sdkdir/sysroots/targetarch-enea-linux/usr/src/kernel</literal>.</para>
104 141
105 <para>Once the environment-setup script is sourced, you can make your 142 <para>Once the environment-setup script is sourced, you can make your
106 kernel modules as usual and get them compiled for your target. Below you 143 kernel modules as usual and get them compiled for your target. Below you
@@ -114,7 +151,7 @@ hello world</programlisting>
114 <programlisting>obj-m := hello.o 151 <programlisting>obj-m := hello.o
115PWD := $(shell pwd) 152PWD := $(shell pwd)
116 153
117KERNEL_SRC := &lt;full path to kernel source tree&gt; 154KERNEL_SRC := full path to kernel source tree
118 155
119all: scripts 156all: scripts
120 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" modules 157 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" modules
@@ -122,9 +159,9 @@ scripts:
122 $(MAKE) -C $(KERNEL_SRC) scripts 159 $(MAKE) -C $(KERNEL_SRC) scripts
123clean: 160clean:
124 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" clean 161 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" clean
125#include &lt;linux/module.h&gt; /* Needed by all modules */ 162#include linux/module.h /* Needed by all modules */
126#include &lt;linux/kernel.h&gt; /* Needed for KERN_INFO */ 163#include linux/kernel.h /* Needed for KERN_INFO */
127#include &lt;linux/init.h&gt; /* Needed for the macros */ 164#include linux/init.h /* Needed for the macros */
128 165
129static int __init hello_start(void) 166static int __init hello_start(void)
130{ 167{
@@ -168,36 +205,276 @@ MODULE_LICENSE("GPL");</programlisting>
168 <section id="deploy-artifacts"> 205 <section id="deploy-artifacts">
169 <title>Deploying your artifacts</title> 206 <title>Deploying your artifacts</title>
170 207
171 <orderedlist> 208 <section id="deploy_onhost">
172 <listitem> 209 <title>Deploying on host</title>
173 <para>Deploying on host</para> 210
211 <para>You can use <literal>ssh</literal> to deploy your artifacts on the
212 host target. For this you will need a network connection to the target,
213 to use <literal>scp</literal> to copy to the desired location.</para>
214
215 <para><programlisting># scp helloworld root@&lt;target_ip_address&gt;:/tmp</programlisting></para>
216 </section>
217
218 <section id="deploy_onguest">
219 <title>Deploying on guest</title>
220
221 <para>You can deploy your artifacts onto the guest VM running on the
222 target, by using TAP Networking. You can use the
223 <filename>/etc/qemu-ifup</filename> script to create the tap interface
224 on the host and attach it to the existing virtual bridge
225 (<literal>virbr0</literal>). This bridge interface is created by the
226 <filename>libvirt</filename> library and can be used to connect to the
227 outside network. To be able to transfer files to the guest via
228 <literal>scp</literal>, port forwarding should be enabled on the host.
229 The script sets iptables rules to forward traffic from a host port to
230 the guest default SSH port (22).</para>
231
232 <para>Follow the steps below to create this setup:</para>
233
234 <orderedlist>
235 <listitem>
236 <para>On the host, run the <literal>qemu-ifup</literal> script
237 located in <literal>/etc</literal> directory:</para>
238
239 <para><programlisting># /etc/qemu-ifup &ndash;t tap0 &ndash;a 192.168.122.10 &ndash;p 1050 &ndash;g 22</programlisting></para>
240
241 <itemizedlist>
242 <listitem>
243 <para><emphasis role="bold">tap0</emphasis> - the tap interface
244 name which will be created and added to the virtual bridge
245 (virbr0).</para>
246 </listitem>
247
248 <listitem>
249 <para><emphasis role="bold">192.168.122.10</emphasis> - the IP
250 address of the guest virtual network device. It has to be in the
251 same network with the IP address of the virbr0 interface.</para>
252 </listitem>
253
254 <listitem>
255 <para><emphasis role="bold">1050</emphasis> - the host port
256 which is set to forward traffic from the host to the
257 guest.</para>
258 </listitem>
259
260 <listitem>
261 <para><emphasis role="bold">22</emphasis> - the default SSH
262 guest port used in port forwarding.</para>
263 </listitem>
264 </itemizedlist>
265 </listitem>
266
267 <listitem>
268 <para>Launch the virtual machine specifying the newly created tap
269 interface:</para>
270
271 <para><programlisting>-device e1000,netdev=net0 \
272-netdev tap,id=net0,ifname=tap0,script=no,downscript=no</programlisting></para>
273 </listitem>
274
275 <listitem>
276 <para>On the guest, after logging, configure the virtual network
277 device and set the default gateway as the <literal>virbr0</literal>
278 ip address:</para>
279
280 <para><programlisting>ip addr add 192.168.122.10/24 dev enp0s2
281ip link set enp0s2 up
282ip route add default via 192.168.122.1 dev enp0s2</programlisting></para>
283 </listitem>
284
285 <listitem>
286 <para>Now you can use <literal>scp</literal> from your development
287 machine to deploy your artifacts on the guest, by giving the host
288 port for forwarding as a command parameter: <programlisting>scp -P 1050 helloworld root@target_ip_address:/tmp</programlisting></para>
289 </listitem>
290
291 <listitem>
292 <para>On the host, after finishing the deployment session and
293 stopping the virtual machine, you can use the
294 <literal>qemu-ifdown</literal> script to clean up the configuration
295 on host. The following command will remove the tap interface and all
296 the iptables rules for the specific ip address: <programlisting># /etc/qemu-ifdown &ndash;t tap0 &ndash;a 192.168.122.10</programlisting>If
297 we need to remove only a particular port forwarding rule from
298 iptables, this should be run: <programlisting># /etc/qemu-ifdown &ndash;t tap0 &ndash;a 192.168.122.10 &ndash;p 1050 &ndash;g 22</programlisting></para>
299 </listitem>
300 </orderedlist>
301 </section>
302 </section>
303
304 <section id="crossdebugging">
305 <title>Cross-Debugging on Enea NFV Access</title>
306
307 <para>The cross-debugger (<literal>x86_64-enea-linux-gdb</literal>) is
308 created when installing the SDK on the development machine. It is helpful
309 for debugging both the kernel and user-applications. In order to perform
310 this task, we need the following tools to be available on the target
311 machine:</para>
174 312
175 <para>You can use <literal>ssh</literal> to deploy your artifacts on 313 <itemizedlist>
176 the host target. For this you will need a network connection to the 314 <listitem>
177 target and to use <literal>scp</literal> to copy to the desired 315 <para>Kgdb &ndash; for kernel cross-debugging</para>
178 location.</para>
179 </listitem> 316 </listitem>
180 317
181 <listitem> 318 <listitem>
182 <para>Deploying on guest</para> 319 <para>GDBServer &ndash; for application cross-debugging</para>
183
184 <para>You can deploy your artifacts onto the guest VM running on the
185 target in two steps:</para>
186
187 <itemizedlist>
188 <listitem>
189 <para>Deploy the artifacts onto the target by using the method
190 described above or any other method.</para>
191 </listitem>
192
193 <listitem>
194 <para>On the target, copy the artifacts to the guest rootfs. For
195 this, you will need to shut down the guest VM, mount the file
196 system on the target, copy your files onto it, unmount it and then
197 restart the guest VM as usual.</para>
198 </listitem>
199 </itemizedlist>
200 </listitem> 320 </listitem>
201 </orderedlist> 321 </itemizedlist>
322
323 <para>The Host Development image provides both of these tools and has to
324 be booted on the target machine for cross-debugging sessions.</para>
325
326 <section id="ua_debug_host">
327 <title>User-application Cross-Debugging on Host</title>
328
329 <para>To debug a user-application on host, a TCP connection has to be
330 established between the host and development machines. GDBserver is the
331 program which runs on the target machine and allows you to run GDB on
332 your workstation. Below you can find how a simple
333 <filename>helloworld</filename> application can be debugged using
334 GDBServer and cross-gdb.</para>
335
336 <para>On target, launch the GDBServer, specifying how to communicate
337 with GDB and the name of your program:<programlisting># gdbserver :&lt;port_no&gt; /tmp/helloworld</programlisting>The
338 target will now be listening on the port given as a parameter to the
339 gdbserver. On the development machine, from the
340 <literal>&lt;sdkdir&gt;</literal>, start the cross-gdb:<programlisting># x86_64-enea-linux-gdb &lt;path_to_the_program&gt;/helloworld</programlisting>Connect
341 the GDB to the target: <programlisting>(gdb) target remote &lt;target_ip_address&gt;:&lt;port_no&gt;</programlisting>Now
342 remote debugging is started and the GDB commands are available to debug
343 your program from the target machine.</para>
344 </section>
345
346 <section id="us_debug_guest">
347 <title>User-application Cross-Debugging on Guest</title>
348
349 <para>To debug a user-application on guest, a TCP connection has to be
350 established between the host and development machines. Similarly, as
351 when deploying artifacts on guest, for a cross-debugging session, TAP
352 Networking is required.</para>
353
354 <para>A tap interface should be added to the existing virtual bridge
355 (<literal>virbr0</literal>), along with port forwarding rules created in
356 iptables. In order to do this, the script
357 <filename>/etc/qemu-ifup</filename> can pe used:</para>
358
359 <orderedlist>
360 <listitem>
361 <para>On the host, run the script <literal>qemu-ifup</literal>
362 located in <literal>/etc</literal> directory: <programlisting># /etc/qemu-ifup &ndash;t tap0 &ndash;a 192.168.122.10 &ndash;p 1051 &ndash;g 1025</programlisting></para>
363
364 <itemizedlist>
365 <listitem>
366 <para><emphasis role="bold">tap0</emphasis> - the tap interface
367 name which will be created and added to virtual bridge
368 (virbr0).</para>
369 </listitem>
370
371 <listitem>
372 <para><emphasis role="bold">192.168.122.10</emphasis> - the IP
373 address of the guest virtual network device. It has to be in the
374 same network with the IP address of the virbr0 interface.</para>
375 </listitem>
376
377 <listitem>
378 <para><emphasis role="bold">1051</emphasis> &ndash; the host
379 port which is set to forward traffic from the host to the guest
380 and is used by gdb target remote command.</para>
381 </listitem>
382
383 <listitem>
384 <para><emphasis role="bold">1025</emphasis>&ndash; the port used
385 by GDBServer on guest for listening.</para>
386 </listitem>
387 </itemizedlist>
388 </listitem>
389
390 <listitem>
391 <para>Launch the virtual machine, specifying the newly created tap
392 interface:<programlisting>-device e1000,netdev=net0 \
393-netdev tap,id=net0,ifname=tap0,script=no,downscript=no</programlisting></para>
394 </listitem>
395
396 <listitem>
397 <para>On the guest, after logging, configure the virtual network
398 device and set the default gateway to virbr0 ip
399 address:<programlisting>ip addr add 192.168.122.10/24 dev enp0s2
400ip link set enp0s2 up
401ip route add default via 192.168.122.1 dev enp0s2</programlisting></para>
402 </listitem>
403
404 <listitem>
405 <para>GDBserver is the program which runs on the guest VM and allows
406 you to run GDB on your workstation. On the guest, launch GBDserver
407 specifying how to communicate with GDB and the name of your program:
408 <programlisting># gdbserver :1025 /tmp/helloworld</programlisting>The
409 guest is now listening on port 1025, given as a parameter to the
410 gdbserver.</para>
411 </listitem>
412
413 <listitem>
414 <para>On the development machine, from the<filename>
415 &lt;sdkdir&gt;</filename>, start the cross-gdb:<programlisting># x86_64-enea-linux-gdb &lt;path_to_the_program&gt;/helloworld</programlisting></para>
416 </listitem>
417
418 <listitem>
419 <para>Connect GDB to the target:<programlisting>(gdb) target remote &lt;target_ip_address&gt;:1051</programlisting>Now
420 remote debugging is started and the GDB commands are available to
421 debug your program from the guest VM.</para>
422 </listitem>
423
424 <listitem>
425 <para>On the host, after finishing the cross-debugging session and
426 stopping the virtual machine, you can use the
427 <filename>qemu-ifdown</filename> script to clean up the
428 configuration on host:<programlisting># /etc/qemu-ifdown -t tap0 -a 192.168.122.10</programlisting></para>
429 </listitem>
430 </orderedlist>
431 </section>
432
433 <section id="kernel_crossdebug">
434 <title>Kernel Cross-Debugging</title>
435
436 <para>In order to debug the kernel, a serial connection is required
437 between the development and target machines. Debugging commands will be
438 sent from your workstation to the target machine via a serial
439 port.</para>
440
441 <para>The KGDB kernel options are enabled in the Enea NFV Access Host
442 SDK image and the tool can be used in the following way:</para>
443
444 <itemizedlist>
445 <listitem>
446 <para>On target, once serial communication is established, configure
447 <literal>kgdboc</literal> after the kernel boots:<programlisting># echo ttyS0,115200 &gt; /sys/module/kgdboc/parameters/kgdboc</programlisting></para>
448 </listitem>
449
450 <listitem>
451 <para>In order to connect to gdb via kgdboc, the kernel must first
452 be stopped:<programlisting># echo g &gt; /proc/sysrq-trigger</programlisting></para>
453 </listitem>
454
455 <listitem>
456 <para>Close the console to the target, eg.: <command>Ctrl +
457 ]</command> for a telnet session.</para>
458 </listitem>
459
460 <listitem>
461 <para>On your development machine, start cross-gdb using the vmlinux
462 kernel image as a parameter. The image is located in
463 <filename>&lt;sdkdir&gt;/sysroots/corei7-64-enea-linux/boot/</filename>
464 and should be the same as the image found in the
465 <literal>/boot</literal> directory from the target.<programlisting># x86_64-enea-linux-gdb /
466./sysroots/corei7-64-enea-linux/boot/vmlinux-4.9.30-intel-pk-standard</programlisting></para>
467 </listitem>
468
469 <listitem>
470 <para>Connect GDB to the target machine using target command and the
471 serial device:<programlisting>(gdb) set remotebaud 115200
472(gdb) target remote /dev/ttyS0</programlisting></para>
473 </listitem>
474 </itemizedlist>
475
476 <para>The kernel can now be debugged in a similar manner as an
477 application program.</para>
478 </section>
202 </section> 479 </section>
203</chapter> \ No newline at end of file 480</chapter> \ No newline at end of file