summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/eltf_params_updated.xml10
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/using_nfv_access_sdks.xml796
-rw-r--r--doc/book-enea-nfv-access-release-info/doc/about_release.xml6
-rw-r--r--doc/book-enea-nfv-access-release-info/doc/main_changes.xml10
4 files changed, 483 insertions, 339 deletions
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_updated.xml b/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_updated.xml
index 1db30fd..9143847 100644
--- a/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_updated.xml
+++ b/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_updated.xml
@@ -42,14 +42,14 @@ export PATH=~/bin:$PATH</programlisting></para>
42 correct also compared to the "previous" REL VER in pardoc-distro.xml 42 correct also compared to the "previous" REL VER in pardoc-distro.xml
43 "prev_baseline".</bridgehead> 43 "prev_baseline".</bridgehead>
44 44
45 <para id="EneaLinux_REL_VER"><phrase>1.1</phrase></para> 45 <para id="EneaLinux_REL_VER"><phrase>2.0</phrase></para>
46 46
47 <para id="Yocto_VER"><phrase>2.1</phrase></para> 47 <para id="Yocto_VER"><phrase>2.4</phrase></para>
48 48
49 <para id="Yocto_NAME"><phrase>krogoth</phrase></para> 49 <para id="Yocto_NAME"><phrase>rocko</phrase></para>
50 50
51 <para id="ULINK_YOCTO_PROJECT_DOWNLOAD"><ulink 51 <para id="ULINK_YOCTO_PROJECT_DOWNLOAD"><ulink
52 url="http://www.yoctoproject.org/downloads/core/krogoth/21">http://www.yoctoproject.org/downloads/core/krogoth/21</ulink></para> 52 url="http://www.yoctoproject.org/downloads/core/rocko/242">http://www.yoctoproject.org/downloads/core/rocko/242</ulink></para>
53 53
54 <para id="ULINK_ENEA_LINUX_URL"><ulink 54 <para id="ULINK_ENEA_LINUX_URL"><ulink
55 url="https://linux.enea.com/6">https://linux.enea.com/6</ulink></para> 55 url="https://linux.enea.com/6">https://linux.enea.com/6</ulink></para>
@@ -162,4 +162,4 @@ repo sync</programlisting></para>
162 </informaltable></para> 162 </informaltable></para>
163 </section> 163 </section>
164 </section> 164 </section>
165</section> \ No newline at end of file 165</section>
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/using_nfv_access_sdks.xml b/doc/book-enea-nfv-access-guide-intel/doc/using_nfv_access_sdks.xml
index 4b10d2a..25090c6 100644
--- a/doc/book-enea-nfv-access-guide-intel/doc/using_nfv_access_sdks.xml
+++ b/doc/book-enea-nfv-access-guide-intel/doc/using_nfv_access_sdks.xml
@@ -1,102 +1,137 @@
1<?xml version="1.0" encoding="ISO-8859-1"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="workflow"> 4<chapter id="using_sdks">
5 <title>Using Enea NFV Access SDKs</title> 5 <title>Using the Enea NFV Access SDKs</title>
6 6
7 <para>Enea NFV Access comes with a standard SDK which can be used to develop 7 <para>Enea NFV Access comes with two Software Development Kits (SDK), the
8 user-applications and kernel modules for both host and guest images.</para> 8 "Standard SDK" and the "Extensible SDK". Standard SDK can be used to develop
9 9 user-applications and kernel modules on host to run on target device (i.e.
10 <para>The standard SDK consists of:</para> 10 on ARM, PPC, x86, ..). The standard SDK can also be used for cross debugging
11 11 your kernel or application.</para>
12 <itemizedlist> 12
13 <listitem> 13 <para><emphasis role="bold">Benefits of Extensible
14 <para>Cross-Development Toolchain: cross-compiler and 14 SDK:</emphasis><orderedlist>
15 cross-debugger</para>
16 </listitem>
17
18 <listitem>
19 <para>Libraries, Headers and Symbols that are specific to the
20 image</para>
21 </listitem>
22
23 <listitem>
24 <para>Environment Setup Script which defines the environment
25 variables</para>
26 </listitem>
27 </itemizedlist>
28
29 <para>To install the SDK on your host development machine, there is an
30 installation script available under the Download section on <emphasis
31 role="bold">portal.enea.com</emphasis>:</para>
32
33 <itemizedlist>
34 <listitem>
35 <para>x86_64/install/install-sdk.sh</para>
36 </listitem>
37 </itemizedlist>
38
39 <para>After installing the SDK, a developer will be able to compile and
40 generate executables for the preferred target machine. Cross-gdb
41 (<filename>x86_64-enea-linux-gdb</filename>) is created by the
42 Cross-Development toolchain. It can be used to debug applications on the
43 target platform from the development workstation. For kernel debugging,
44 <command>ftrace</command> and <command>kgdb</command> are enabled on the
45 host sdk image.</para>
46
47 <para>Various user-space tools helpful in the development process, are also
48 provided. The tools include <emphasis role="bold">LatencyTop</emphasis>,
49 <emphasis role="bold">Perf</emphasis>, <emphasis
50 role="bold">CrossTap</emphasis>, <emphasis role="bold">OProfile</emphasis>,
51 <emphasis role="bold">Lttng-ust</emphasis> and <emphasis
52 role="bold">GDBserver</emphasis>.</para>
53
54 <section id="install-crosscomp">
55 <title>Installing the Cross-Compilation Toolchain</title>
56
57 <para>Before cross-compiling applications for your target, you need to
58 install the corresponding toolchain on your workstation. To do that,
59 simply run the installer and follow the steps included with it:</para>
60
61 <orderedlist>
62 <listitem> 15 <listitem>
63 <para><programlisting>$ ./install-sdk.sh</programlisting>When 16 <para>Shared development environment</para>
64 prompted, select to install the toolchain in the desired directory,
65 referred to as <literal>sdkdir</literal>.</para>
66
67 <para>A default path where the toolchain will be installed will be
68 shown in the prompt. The installer unpacks the environment setup
69 script in <literal>sdkdir</literal> and the toolchain under
70 <literal>sdkdir/sysroots</literal>.</para>
71
72 <note>
73 <para>Choose a unique directory for each toolchain. Installing a
74 second toolchain of any type in the same directory as a previously
75 installed one will break the <literal>$PATH</literal> variable of
76 the first one.</para>
77 </note>
78 </listitem> 17 </listitem>
79 18
80 <listitem> 19 <listitem>
81 <para>Setup the toolchain environment for your target by sourcing the 20 <para>Easy to add new apps and libraries, modify source of an existing
82 environment-setup script. Example: <programlisting>$ source sdkdir/environment-setup-corei7-64-enea-linux</programlisting></para> 21 component or add new layers/recipes</para>
22 </listitem>
23
24 <listitem>
25 <para>Shared state for faster builds</para>
26 </listitem>
27
28 <listitem>
29 <para>Devtool support</para>
30 </listitem>
31
32 <listitem>
33 <para>Install SDK once, update, extend as needed</para>
34 </listitem>
35
36 <listitem>
37 <para>Runs on a range of host operating systems (Windows, Mac)</para>
38 </listitem>
39 </orderedlist></para>
40
41 <section id="std_sdk">
42 <title>Standard SDK</title>
43
44 <para>The Standard SDK consists of:</para>
45
46 <itemizedlist>
47 <listitem>
48 <para>Cross-Development Toolchain: cross-compiler and
49 cross-debugger</para>
83 </listitem> 50 </listitem>
84 </orderedlist>
85 </section>
86 51
87 <section id="crosscomp-apps"> 52 <listitem>
88 <title>Cross-Compiling Applications from Command Line</title> 53 <para>Libraries, Headers and Symbols that are specific to the
54 image</para>
55 </listitem>
56
57 <listitem>
58 <para>Environment Setup Script which defines the environment
59 variables</para>
60 </listitem>
61 </itemizedlist>
89 62
90 <para>Once the environment-setup script is sourced, you can make your 63 <para>To install the SDK on your host development machine, there is an
91 applications as per usual and get them compiled for your target. Below you 64 installation script available under the Download section on <emphasis
92 see how to cross-compile from command line.</para> 65 role="bold">portal.enea.com</emphasis>:</para>
93 66
94 <orderedlist> 67 <itemizedlist>
95 <listitem> 68 <listitem>
96 <para>Create a Makefile for your application. Example: a simple 69 <para>x86_64/install/install-sdk.sh</para>
97 Makefile and application:</para> 70 </listitem>
71 </itemizedlist>
72
73 <para>After installing the SDK, a developer will be able to compile and
74 generate executables for the preferred target machine. Cross-gdb
75 (<filename>x86_64-enea-linux-gdb</filename>) is created by the
76 Cross-Development toolchain. It can be used to debug applications on the
77 target platform from the development workstation. For kernel debugging,
78 <command>ftrace</command> and <command>kgdb</command> are enabled on the
79 host sdk image.</para>
80
81 <para>Various user-space tools helpful in the development process, are
82 also provided. The tools include <emphasis
83 role="bold">LatencyTop</emphasis>, <emphasis role="bold">Perf</emphasis>,
84 <emphasis role="bold">CrossTap</emphasis>, <emphasis
85 role="bold">OProfile</emphasis>, <emphasis
86 role="bold">Lttng-ust</emphasis> and <emphasis
87 role="bold">GDBserver</emphasis>.</para>
88
89 <section id="install-crosscomp">
90 <title>Installing the Cross-Compilation Toolchain</title>
91
92 <para>Before cross-compiling applications for your target, you need to
93 install the corresponding toolchain on your workstation. To do that,
94 simply run the installer and follow the steps included with it:</para>
95
96 <orderedlist>
97 <listitem>
98 <para><programlisting>$ ./install-sdk.sh</programlisting>When
99 prompted, select to install the toolchain in the desired directory,
100 referred to as <literal>sdkdir</literal>.</para>
101
102 <para>A default path where the toolchain will be installed will be
103 shown in the prompt. The installer unpacks the environment setup
104 script in <literal>sdkdir</literal> and the toolchain under
105 <literal>sdkdir/sysroots</literal>.</para>
106
107 <note>
108 <para>Choose a unique directory for each toolchain. Installing a
109 second toolchain of any type in the same directory as a previously
110 installed one will break the <literal>$PATH</literal> variable of
111 the first one.</para>
112 </note>
113 </listitem>
114
115 <listitem>
116 <para>Setup the toolchain environment for your target by sourcing
117 the environment-setup script. Example: <programlisting>$ source sdkdir/environment-setup-corei7-64-enea-linux</programlisting></para>
118 </listitem>
119 </orderedlist>
120 </section>
98 121
99 <programlisting>helloworld:helloworld.o 122 <section id="crosscomp-apps">
123 <title>Cross-Compiling Applications from Command Line</title>
124
125 <para>Once the environment-setup script is sourced, you can make your
126 applications as per usual and get them compiled for your target. Below
127 you see how to cross-compile from command line.</para>
128
129 <orderedlist>
130 <listitem>
131 <para>Create a Makefile for your application. Example: a simple
132 Makefile and application:</para>
133
134 <programlisting>helloworld:helloworld.o
100 $(CC) -o helloworld helloworld.o 135 $(CC) -o helloworld helloworld.o
101clean: 136clean:
102 rm -f *.o helloworld 137 rm -f *.o helloworld
@@ -105,42 +140,43 @@ int main(void) {
105 printf("Hello World\n"); 140 printf("Hello World\n");
106 return 0; 141 return 0;
107}</programlisting> 142}</programlisting>
108 </listitem> 143 </listitem>
109 144
110 <listitem> 145 <listitem>
111 <para>Run <command>make</command> to cross-compile your application 146 <para>Run <command>make</command> to cross-compile your application
112 according to the environment set up:</para> 147 according to the environment set up:</para>
113 148
114 <programlisting>$ make</programlisting> 149 <programlisting>$ make</programlisting>
115 </listitem> 150 </listitem>
116 151
117 <listitem> 152 <listitem>
118 <para>Deploy the helloworld program to your target and run it:</para> 153 <para>Deploy the helloworld program to your target and run
154 it:</para>
119 155
120 <programlisting># ./helloworld 156 <programlisting># ./helloworld
121hello world</programlisting> 157hello world</programlisting>
122 </listitem> 158 </listitem>
123 </orderedlist> 159 </orderedlist>
124 </section> 160 </section>
125 161
126 <section id="crosscomp-kern-mod"> 162 <section id="crosscomp-kern-mod">
127 <title>Cross-Compiling Kernel Modules</title> 163 <title>Cross-Compiling Kernel Modules</title>
128 164
129 <para>Before cross-compiling kernle modules, you need to make sure the 165 <para>Before cross-compiling kernle modules, you need to make sure the
130 installed toolchain includes the kernel source tree, which should be 166 installed toolchain includes the kernel source tree, which should be
131 available at: 167 available at:
132 <literal>sdkdir/sysroots/targetarch-enea-linux/usr/src/kernel</literal>.</para> 168 <literal>sdkdir/sysroots/targetarch-enea-linux/usr/src/kernel</literal>.</para>
133 169
134 <para>Once the environment-setup script is sourced, you can make your 170 <para>Once the environment-setup script is sourced, you can make your
135 kernel modules as usual and get them compiled for your target. Below you 171 kernel modules as usual and get them compiled for your target. Below you
136 see how to cross-compile a kernel module.</para> 172 see how to cross-compile a kernel module.</para>
137 173
138 <orderedlist> 174 <orderedlist>
139 <listitem> 175 <listitem>
140 <para>Create a Makefile for the kernel module. Example: a simple 176 <para>Create a Makefile for the kernel module. Example: a simple
141 Makefile and kernel module:</para> 177 Makefile and kernel module:</para>
142 178
143 <programlisting>obj-m := hello.o 179 <programlisting>obj-m := hello.o
144PWD := $(shell pwd) 180PWD := $(shell pwd)
145 181
146KERNEL_SRC := full path to kernel source tree 182KERNEL_SRC := full path to kernel source tree
@@ -171,302 +207,414 @@ module_init(hello_start);
171module_exit(hello_end); 207module_exit(hello_end);
172 208
173MODULE_LICENSE("GPL");</programlisting> 209MODULE_LICENSE("GPL");</programlisting>
174 </listitem> 210 </listitem>
175 211
176 <listitem> 212 <listitem>
177 <para>Run <command>make</command> to cross-compile your kernel module 213 <para>Run <command>make</command> to cross-compile your kernel
178 according to the environment set up:</para> 214 module according to the environment set up:</para>
179 215
180 <programlisting>$ make</programlisting> 216 <programlisting>$ make</programlisting>
181 </listitem> 217 </listitem>
182 218
183 <listitem> 219 <listitem>
184 <para>Deploy the kernel module <literal>hello.ko</literal> to your 220 <para>Deploy the kernel module <literal>hello.ko</literal> to your
185 target and install/remove it:</para> 221 target and install/remove it:</para>
186 222
187 <programlisting># insmod hello.ko 223 <programlisting># insmod hello.ko
188# rmmod hello.ko 224# rmmod hello.ko
189# dmesg 225# dmesg
190[...] Loading hello module... 226[...] Loading hello module...
191[...] Hello, world 227[...] Hello, world
192[...] Goodbye, world</programlisting> 228[...] Goodbye, world</programlisting>
193 </listitem> 229 </listitem>
194 </orderedlist> 230 </orderedlist>
195 </section> 231 </section>
196
197 <section id="deploy-artifacts">
198 <title>Deploying your artifacts</title>
199 232
200 <section id="deploy_onhost"> 233 <section id="deploy-artifacts">
201 <title>Deploying on host</title> 234 <title>Deploying your artifacts</title>
202 235
203 <para>You can use <literal>ssh</literal> to deploy your artifacts on the 236 <para>You can use <literal>ssh</literal> to deploy your artifacts on the
204 host target. For this you will need a network connection to the target, 237 host target. For this you will need a network connection to the target,
205 to use <literal>scp</literal> to copy to the desired location.</para> 238 to use <literal>scp</literal> to copy to the desired location.</para>
206 239
207 <para><programlisting># scp helloworld root@&lt;target_ip_address&gt;:/tmp</programlisting></para> 240 <programlisting># scp helloworld root@&lt;target_ip_address&gt;:/tmp</programlisting>
208 </section> 241 </section>
209 242
210 <section id="deploy_onguest"> 243 <section id="crossdebugging">
211 <title>Deploying on guest</title> 244 <title>Cross-Debugging on Enea NFV Access</title>
212 245
213 <para>You can deploy your artifacts onto the guest VM running on the 246 <para>The cross-debugger (<literal>x86_64-enea-linux-gdb</literal>) is
214 target, by using TAP Networking. You can use the 247 created when installing the SDK on the development machine. It is
215 <filename>/etc/qemu-ifup</filename> script to create the tap interface 248 helpful for debugging both the kernel and user-applications. In order to
216 on the host and attach it to the existing virtual bridge 249 perform this task, we need the following tools to be available on the
217 (<literal>virbr0</literal>). This bridge interface is created by the 250 target machine:</para>
218 <filename>libvirt</filename> library and can be used to connect to the
219 outside network. To be able to transfer files to the guest via
220 <literal>scp</literal>, port forwarding should be enabled on the host.
221 The script sets iptables rules to forward traffic from a host port to
222 the guest default SSH port (22).</para>
223 251
224 <para>Follow the steps below to create this setup:</para> 252 <itemizedlist>
225
226 <orderedlist>
227 <listitem> 253 <listitem>
228 <para>On the host, run the <literal>qemu-ifup</literal> script 254 <para>Kgdb – for kernel cross-debugging</para>
229 located in <literal>/etc</literal> directory:</para>
230
231 <para><programlisting># /etc/qemu-ifup &ndash;t tap0 &ndash;a 192.168.122.10 &ndash;p 1050 &ndash;g 22</programlisting></para>
232
233 <itemizedlist>
234 <listitem>
235 <para><emphasis role="bold">tap0</emphasis> - the tap interface
236 name which will be created and added to the virtual bridge
237 (virbr0).</para>
238 </listitem>
239
240 <listitem>
241 <para><emphasis role="bold">192.168.122.10</emphasis> - the IP
242 address of the guest virtual network device. It has to be in the
243 same network with the IP address of the virbr0 interface.</para>
244 </listitem>
245
246 <listitem>
247 <para><emphasis role="bold">1050</emphasis> - the host port
248 which is set to forward traffic from the host to the
249 guest.</para>
250 </listitem>
251
252 <listitem>
253 <para><emphasis role="bold">22</emphasis> - the default SSH
254 guest port used in port forwarding.</para>
255 </listitem>
256 </itemizedlist>
257 </listitem> 255 </listitem>
258 256
259 <listitem> 257 <listitem>
260 <para>Launch the virtual machine specifying the newly created tap 258 <para>GDBServer – for application cross-debugging</para>
261 interface:</para>
262
263 <para><programlisting>-device e1000,netdev=net0 \
264-netdev tap,id=net0,ifname=tap0,script=no,downscript=no</programlisting></para>
265 </listitem> 259 </listitem>
260 </itemizedlist>
266 261
267 <listitem> 262 <para>The Host Development image provides both of these tools and has to
268 <para>On the guest, after logging, configure the virtual network 263 be booted on the target machine for cross-debugging sessions.</para>
269 device and set the default gateway as the <literal>virbr0</literal> 264
270 ip address:</para> 265 <section id="ua_debug_host">
271 266 <title>User-application Cross-Debugging</title>
272 <para><programlisting>ip addr add 192.168.122.10/24 dev enp0s2 267
273ip link set enp0s2 up 268 <para>To debug a user-application on host, a TCP connection has to be
274ip route add default via 192.168.122.1 dev enp0s2</programlisting></para> 269 established between the host and development machines. GDBserver is
275 </listitem> 270 the program which runs on the target machine and allows you to run GDB
271 on your workstation. Below you can find how a simple
272 <filename>helloworld</filename> application can be debugged using
273 GDBServer and cross-gdb.</para>
274
275 <para>On target, launch the GDBServer, specifying how to communicate
276 with GDB and the name of your program:<programlisting># gdbserver :&lt;port_no&gt; /tmp/helloworld</programlisting>The
277 target will now be listening on the port given as a parameter to the
278 gdbserver. On the development machine, from the
279 <literal>&lt;sdkdir&gt;</literal>, start the
280 cross-gdb:<programlisting># x86_64-enea-linux-gdb &lt;path_to_the_program&gt;/helloworld</programlisting>Connect
281 the GDB to the target: <programlisting>(gdb) target remote &lt;target_ip_address&gt;:&lt;port_no&gt;</programlisting>Now
282 remote debugging is started and the GDB commands are available to
283 debug your program from the target machine.</para>
284 </section>
285
286 <section id="kernel_crossdebug">
287 <title>Kernel Cross-Debugging</title>
288
289 <para>In order to debug the kernel, a serial connection is required
290 between the development and target machines. Debugging commands will
291 be sent from your workstation to the target machine via a serial
292 port.</para>
293
294 <para>The KGDB kernel options are enabled in the Enea NFV Access Host
295 SDK image and the tool can be used in the following way:</para>
296
297 <itemizedlist>
298 <listitem>
299 <para>On target, once serial communication is established,
300 configure <literal>kgdboc</literal> after the kernel
301 boots:<programlisting># echo ttyS0,115200 &gt; /sys/module/kgdboc/parameters/kgdboc</programlisting></para>
302 </listitem>
303
304 <listitem>
305 <para>In order to connect to gdb via kgdboc, the kernel must first
306 be stopped:<programlisting># echo g &gt; /proc/sysrq-trigger</programlisting></para>
307 </listitem>
308
309 <listitem>
310 <para>Close the console to the target, eg.: <command>Ctrl +
311 ]</command> for a telnet session.</para>
312 </listitem>
313
314 <listitem>
315 <para>On your development machine, start cross-gdb using the
316 vmlinux kernel image as a parameter. The image is located in
317 <filename>&lt;sdkdir&gt;/sysroots/corei7-64-enea-linux/boot/</filename>
318 and should be the same as the image found in the
319 <literal>/boot</literal> directory from the
320 target.<programlisting># x86_64-enea-linux-gdb /
321./sysroots/corei7-64-enea-linux/boot/vmlinux-4.9.30-intel-pk-standard</programlisting></para>
322 </listitem>
276 323
277 <listitem> 324 <listitem>
278 <para>Now you can use <literal>scp</literal> from your development 325 <para>Connect GDB to the target machine using target command and
279 machine to deploy your artifacts on the guest, by giving the host 326 the serial device:<programlisting>(gdb) set remotebaud 115200
280 port for forwarding as a command parameter: <programlisting>scp -P 1050 helloworld root@target_ip_address:/tmp</programlisting></para> 327(gdb) target remote /dev/ttyS0</programlisting></para>
281 </listitem> 328 </listitem>
329 </itemizedlist>
282 330
283 <listitem> 331 <para>The kernel can now be debugged in a similar manner as an
284 <para>On the host, after finishing the deployment session and 332 application program.</para>
285 stopping the virtual machine, you can use the 333 </section>
286 <literal>qemu-ifdown</literal> script to clean up the configuration
287 on host. The following command will remove the tap interface and all
288 the iptables rules for the specific ip address: <programlisting># /etc/qemu-ifdown &ndash;t tap0 &ndash;a 192.168.122.10</programlisting>If
289 we need to remove only a particular port forwarding rule from
290 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>
291 </listitem>
292 </orderedlist>
293 </section> 334 </section>
294 </section> 335 </section>
295 336
296 <section id="crossdebugging"> 337 <section id="esdk">
297 <title>Cross-Debugging on Enea NFV Access</title> 338 <title>Extensible SDK</title>
298 339
299 <para>The cross-debugger (<literal>x86_64-enea-linux-gdb</literal>) is 340 <para>The Extensible SDK provides features that help you easily build an
300 created when installing the SDK on the development machine. It is helpful 341 exsiting or a new component. The Extensible SDK consits of:</para>
301 for debugging both the kernel and user-applications. In order to perform
302 this task, we need the following tools to be available on the target
303 machine:</para>
304 342
305 <itemizedlist> 343 <itemizedlist>
306 <listitem> 344 <listitem>
307 <para>Kgdb &ndash; for kernel cross-debugging</para> 345 <para>Cross-Development Toolchain</para>
308 </listitem> 346 </listitem>
309 347
310 <listitem> 348 <listitem>
311 <para>GDBServer &ndash; for application cross-debugging</para> 349 <para>Libraries, Headers and Symbols for x86 architecture</para>
312 </listitem> 350 </listitem>
313 </itemizedlist>
314 351
315 <para>The Host Development image provides both of these tools and has to 352 <listitem>
316 be booted on the target machine for cross-debugging sessions.</para> 353 <para>Environment Setup Script which defines the environment
317 354 variables</para>
318 <section id="ua_debug_host"> 355 </listitem>
319 <title>User-application Cross-Debugging on Host</title>
320
321 <para>To debug a user-application on host, a TCP connection has to be
322 established between the host and development machines. GDBserver is the
323 program which runs on the target machine and allows you to run GDB on
324 your workstation. Below you can find how a simple
325 <filename>helloworld</filename> application can be debugged using
326 GDBServer and cross-gdb.</para>
327
328 <para>On target, launch the GDBServer, specifying how to communicate
329 with GDB and the name of your program:<programlisting># gdbserver :&lt;port_no&gt; /tmp/helloworld</programlisting>The
330 target will now be listening on the port given as a parameter to the
331 gdbserver. On the development machine, from the
332 <literal>&lt;sdkdir&gt;</literal>, start the cross-gdb:<programlisting># x86_64-enea-linux-gdb &lt;path_to_the_program&gt;/helloworld</programlisting>Connect
333 the GDB to the target: <programlisting>(gdb) target remote &lt;target_ip_address&gt;:&lt;port_no&gt;</programlisting>Now
334 remote debugging is started and the GDB commands are available to debug
335 your program from the target machine.</para>
336 </section>
337 356
338 <section id="us_debug_guest"> 357 <listitem>
339 <title>User-application Cross-Debugging on Guest</title> 358 <para>Devtool (to add, build and deploy the application to target
359 device)</para>
360 </listitem>
361 </itemizedlist>
340 362
341 <para>To debug a user-application on guest, a TCP connection has to be 363 <section id="install-esdk">
342 established between the host and development machines. Similarly, as 364 <title>Installing the Extensible SDK</title>
343 when deploying artifacts on guest, for a cross-debugging session, TAP
344 Networking is required.</para>
345 365
346 <para>A tap interface should be added to the existing virtual bridge 366 <para>To install the Extensible SDK on your host development machine run
347 (<literal>virbr0</literal>), along with port forwarding rules created in 367 the installation script and follow the steps included with it:</para>
348 iptables. In order to do this, the script
349 <filename>/etc/qemu-ifup</filename> can pe used:</para>
350 368
351 <orderedlist> 369 <orderedlist>
352 <listitem> 370 <listitem>
353 <para>On the host, run the script <literal>qemu-ifup</literal> 371 <para><programlisting>$ ./install-esdk.sh</programlisting>When
354 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> 372 prompted, select to install the toolchain in the desired directory,
355 373 referred to as <literal>sdkdir</literal>.</para>
356 <itemizedlist> 374
357 <listitem> 375 <para>A default path where the toolchain will be installed will be
358 <para><emphasis role="bold">tap0</emphasis> - the tap interface 376 shown in the prompt. The installer unpacks the environment setup
359 name which will be created and added to virtual bridge 377 script in <literal>sdkdir</literal> and the toolchain under
360 (virbr0).</para> 378 <literal>sdkdir/sysroots</literal>.</para>
361 </listitem> 379
362 380 <note>
363 <listitem> 381 <para>Choose a unique directory for each toolchain. Installing a
364 <para><emphasis role="bold">192.168.122.10</emphasis> - the IP 382 second toolchain of any type in the same directory as a previously
365 address of the guest virtual network device. It has to be in the 383 installed one will break the <literal>$PATH</literal> variable of
366 same network with the IP address of the virbr0 interface.</para> 384 the first one.</para>
367 </listitem> 385 </note>
368
369 <listitem>
370 <para><emphasis role="bold">1051</emphasis> &ndash; the host
371 port which is set to forward traffic from the host to the guest
372 and is used by gdb target remote command.</para>
373 </listitem>
374
375 <listitem>
376 <para><emphasis role="bold">1025</emphasis>&ndash; the port used
377 by GDBServer on guest for listening.</para>
378 </listitem>
379 </itemizedlist>
380 </listitem> 386 </listitem>
381 387
382 <listitem> 388 <listitem>
383 <para>Launch the virtual machine, specifying the newly created tap 389 <para>Setup the toolchain environment for your target by sourcing
384 interface:<programlisting>-device e1000,netdev=net0 \ 390 the environment-setup script. Example: <programlisting>$ source sdkdir/environment-setup-corei7-64-enea-linux
385-netdev tap,id=net0,ifname=tap0,script=no,downscript=no</programlisting></para> 391SDK environment now set up; additionally you may now run devtool to
392perform development tasks.
393Run devtool --help for further details.</programlisting></para>
386 </listitem> 394 </listitem>
395 </orderedlist>
396 </section>
397
398 <section id="mod_comp_esdk">
399 <title>Modifying an existing component</title>
387 400
401 <orderedlist>
388 <listitem> 402 <listitem>
389 <para>On the guest, after logging, configure the virtual network 403 <para>Extract source and add recipe to workspace:</para>
390 device and set the default gateway to virbr0 ip 404
391 address:<programlisting>ip addr add 192.168.122.10/24 dev enp0s2 405 <programlisting>$ devtool modify -x recipename myapp /path/to/source</programlisting>
392ip link set enp0s2 up
393ip route add default via 192.168.122.1 dev enp0s2</programlisting></para>
394 </listitem> 406 </listitem>
395 407
396 <listitem> 408 <listitem>
397 <para>GDBserver is the program which runs on the guest VM and allows 409 <para>Edit the source code and build it:</para>
398 you to run GDB on your workstation. On the guest, launch GBDserver 410
399 specifying how to communicate with GDB and the name of your program: 411 <programlisting>$ devtool build recipename </programlisting>
400 <programlisting># gdbserver :1025 /tmp/helloworld</programlisting>The
401 guest is now listening on port 1025, given as a parameter to the
402 gdbserver.</para>
403 </listitem> 412 </listitem>
404 413
405 <listitem> 414 <listitem>
406 <para>On the development machine, from the<filename> 415 <para>Push source code changes, or generate as patches on top of
407 &lt;sdkdir&gt;</filename>, start the cross-gdb:<programlisting># x86_64-enea-linux-gdb &lt;path_to_the_program&gt;/helloworld</programlisting></para> 416 recipe:</para>
417
418 <programlisting>$ devtool update­recipe recipename</programlisting>
408 </listitem> 419 </listitem>
420 </orderedlist>
421 </section>
422
423 <section id="add_comp_esdk">
424 <title>Adding a new component</title>
409 425
426 <orderedlist>
410 <listitem> 427 <listitem>
411 <para>Connect GDB to the target:<programlisting>(gdb) target remote &lt;target_ip_address&gt;:1051</programlisting>Now 428 <para>Add application to workspace:</para>
412 remote debugging is started and the GDB commands are available to 429
413 debug your program from the guest VM.</para> 430 <programlisting>$ devtool add myapp /path/to/source</programlisting>
414 </listitem> 431 </listitem>
415 432
416 <listitem> 433 <listitem>
417 <para>On the host, after finishing the cross-debugging session and 434 <para>Build it:</para>
418 stopping the virtual machine, you can use the 435
419 <filename>qemu-ifdown</filename> script to clean up the 436 <programlisting>$ devtool build myapp </programlisting>
420 configuration on host:<programlisting># /etc/qemu-ifdown -t tap0 -a 192.168.122.10</programlisting></para>
421 </listitem> 437 </listitem>
422 </orderedlist> 438 </orderedlist>
423 </section> 439 </section>
424 440
425 <section id="kernel_crossdebug"> 441 <section id="create_recipe_esdk">
426 <title>Kernel Cross-Debugging</title> 442 <title>Creating recipe for a new application </title>
427 443
428 <para>In order to debug the kernel, a serial connection is required 444 <para>Devtool provides a number of features that help you easily to
429 between the development and target machines. Debugging commands will be 445 build, test and package software within the extensible SDK, and
430 sent from your workstation to the target machine via a serial 446 optionally deploy it to target device:</para>
431 port.</para>
432 447
433 <para>The KGDB kernel options are enabled in the Enea NFV Access Host 448 <para>This example will show how to generate a recipe from the existing
434 SDK image and the tool can be used in the following way:</para> 449 application code and Makefile, edit the recipe in order to provide an
450 installation path for the application, build the recipe, and deploy the
451 output on a target, or create a DEB package from the recipe and install
452 the package.</para>
435 453
436 <itemizedlist> 454 <orderedlist>
437 <listitem> 455 <listitem>
438 <para>On target, once serial communication is established, configure 456 <para>Create a simple application and Makefile in
439 <literal>kgdboc</literal> after the kernel boots:<programlisting># echo ttyS0,115200 &gt; /sys/module/kgdboc/parameters/kgdboc</programlisting></para> 457 <literal>&lt;workspace_dir&gt;/my_app</literal>:</para>
458
459 <para><literal>&lt;workspace_dir&gt;/my_app/my_hello_app.c</literal></para>
460
461 <programlisting>#include &lt;stdio.h&gt;
462
463int main(void)
464{
465 printf("Hello world!\n");
466 return 0;
467}</programlisting>
468
469 <para><literal>&lt;workspace_dir&gt;/my_app/Makefile</literal></para>
470
471 <programlisting>my_hello_app:</programlisting>
440 </listitem> 472 </listitem>
441 473
442 <listitem> 474 <listitem>
443 <para>In order to connect to gdb via kgdboc, the kernel must first 475 <para>Generate a recipe (my-hello-recipe) using the source tree of
444 be stopped:<programlisting># echo g &gt; /proc/sysrq-trigger</programlisting></para> 476 the application
477 (<literal>&lt;workspace_dir&gt;/my_app</literal>):</para>
478
479 <programlisting>$ devtool add my-hello-recipe &lt;workspace_dir&gt;/my_app
480NOTE: Using source tree as build directory since that would be the default for this
481recipe
482NOTE: Recipe &lt;SDK_dir&gt;/workspace/recipes/my-hello-recipe/my-hello-recipe.bb has been
483automatically created; further editing may be required to make it fully functional</programlisting>
484
485 <programlisting>$ cat &lt;SDK_dir&gt;/workspace/recipes/my-hello-recipe/my-hello-recipe.bb
486# Recipe created by recipetool
487# This is the basis of a recipe and may need further editing in order to be fully
488# functional.
489# (Feel free to remove these comments when editing.)
490#
491# Unable to find any files that looked like license statements. Check the
492# accompanying documentation and source headers and set LICENSE and
493# LIC_FILES_CHKSUM accordingly.
494#
495# NOTE: LICENSE is being set to "CLOSED" to allow you to at least start building - if
496# this is not accurate with respect to the licensing of the software being built (it
497# will not be in most cases) you must specify the correct value before using this
498# recipe for anything other than initial testing/development!
499LICENSE = "CLOSED"
500LIC_FILES_CHKSUM = ""
501
502# No information for SRC_URI yet (only an external source tree was specified)
503SRC_URI = ""
504
505
506# NOTE: this is a Makefile-only piece of software, so we cannot generate much of the
507# recipe automatically - you will need to examine the Makefile yourself and ensure
508# that the appropriate arguments are passed in.
509
510do_configure () {
511 # Specify any needed configure commands here
512 :
513}
514
515do_compile () {
516 # You will almost certainly need to add additional arguments here
517 oe_runmake
518}
519
520do_install () {
521 # NOTE: unable to determine what to put here - there is a Makefile but no
522 # target named "install", so you will need to define this yourself
523 :
524}</programlisting>
445 </listitem> 525 </listitem>
446 526
447 <listitem> 527 <listitem>
448 <para>Close the console to the target, eg.: <command>Ctrl + 528 <para>Edit the recipe to provide an installation path for the
449 ]</command> for a telnet session.</para> 529 application:</para>
530
531 <programlisting>$ devtool edit-recipe my-hello-recipe</programlisting>
532
533 <programlisting>$ cat &lt;SDK_dir&gt;/workspace/recipes/my-hello-recipe/my-hello-recipe.bb
534...
535do_install () {
536 # NOTE: unable to determine what to put here - there is a Makefile but no
537 # target named "install", so you will need to define this yourself
538 install -d ${D}${bindir}
539 install -m 0777 ${S}/my_hello_app ${D}${bindir}
540}
541...</programlisting>
450 </listitem> 542 </listitem>
451 543
452 <listitem> 544 <listitem>
453 <para>On your development machine, start cross-gdb using the vmlinux 545 <para>Build the recipe:</para>
454 kernel image as a parameter. The image is located in 546
455 <filename>&lt;sdkdir&gt;/sysroots/corei7-64-enea-linux/boot/</filename> 547 <programlisting>$ devtool build my-hello-recipe</programlisting>
456 and should be the same as the image found in the 548
457 <literal>/boot</literal> directory from the target.<programlisting># x86_64-enea-linux-gdb / 549 <para>The recipe build results can be seen here:
458./sysroots/corei7-64-enea-linux/boot/vmlinux-4.9.30-intel-pk-standard</programlisting></para> 550 <literal>&lt;SDK_dir&gt;/tmp/work/&lt;arch&gt;-enea-linux/my-hello-recipe/1.0-r0/</literal></para>
459 </listitem> 551 </listitem>
460 552
461 <listitem> 553 <listitem>
462 <para>Connect GDB to the target machine using target command and the 554 <para>Deploy the output (in this case, the application) on
463 serial device:<programlisting>(gdb) set remotebaud 115200 555 target:</para>
464(gdb) target remote /dev/ttyS0</programlisting></para> 556
557 <programlisting>$ devtool deploy-target my-hello-recipe root@&lt;target_ip_address&gt;
558Parsing recipes..done.
559NOTE: Successfully deployed
560&lt;SDK_dir&gt;/tmp/work/&lt;arch&gt;-enea-linux/my-hello-recipe/1.0-r0/image</programlisting>
561
562 <para>As an alternative you can create a DEB package:</para>
563
564 <programlisting>$ devtool package my-hello-recipe
565...NOTE: Your packages are in &lt;SDK_dir&gt;/tmp/deploy/deb</programlisting>
566
567 <para>Then copy the DEB package on the target and install it using
568 dpkg:</para>
569
570 <programlisting># dpkg -i my-hello-recipe-1.0-r0.1.&lt;arch&gt;.deb</programlisting>
465 </listitem> 571 </listitem>
466 </itemizedlist> 572 </orderedlist>
573 </section>
574
575 <section id="update_esdk">
576 <title>Updating and Extending the Extensible SDK</title>
577
578 <para>Update and Extend your Extensible SDK:</para>
579
580 <orderedlist>
581 <listitem>
582 <para>Update your SDK</para>
583
584 <programlisting>$ devtool sdk-update [url]</programlisting>
585
586 <para>The recipe build results can be seen here:
587 <literal>&lt;SDK_dir&gt;/tmp/work/&lt;arch&gt;-enea-linux/my-hello-recipe/1.0-r0/</literal></para>
588 </listitem>
589
590 <listitem>
591 <para>Extend your SDK</para>
592
593 <programlisting>$ devtool search package-name
594$ devtool sdk -install [-s] recipe-name
595Ex:
596$ devtool sdk-install meta-extsdk-toolchain</programlisting>
597
598 <para>The recipe build results can be seen here:
599 <literal>&lt;SDK_dir&gt;/tmp/work/&lt;arch&gt;-enea-linux/my-hello-recipe/1.0-r0/</literal></para>
600 </listitem>
601 </orderedlist>
602 </section>
603
604 <section id="deploy-artifacts-esdk">
605 <title>Deploying your artifacts</title>
606
607 <para>You can use <literal>ssh</literal> to deploy your artifacts on the
608 host target. For this you will need a network connection to the target
609 device: </para>
610
611 <programlisting>$ devtool deploy­target myapp device</programlisting>
612 </section>
613
614 <section id="create_docker_image">
615 <title>Creating and Deploying a Docker image </title>
467 616
468 <para>The kernel can now be debugged in a similar manner as an 617 <para>You can build a docker image ....</para>
469 application program.</para>
470 </section> 618 </section>
471 </section> 619 </section>
472</chapter> \ No newline at end of file 620</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info/doc/about_release.xml b/doc/book-enea-nfv-access-release-info/doc/about_release.xml
index 5e48116..0f5e5e5 100644
--- a/doc/book-enea-nfv-access-release-info/doc/about_release.xml
+++ b/doc/book-enea-nfv-access-release-info/doc/about_release.xml
@@ -19,11 +19,11 @@
19 19
20 <itemizedlist> 20 <itemizedlist>
21 <listitem> 21 <listitem>
22 <para>DPDK 17.08</para> 22 <para>DPDK 18.02</para>
23 </listitem> 23 </listitem>
24 24
25 <listitem> 25 <listitem>
26 <para>OVS 2.8</para> 26 <para>OVS 2.9</para>
27 </listitem> 27 </listitem>
28 28
29 <listitem condition="intel"> 29 <listitem condition="intel">
@@ -320,4 +320,4 @@
320 <para>A detailed list of all security patches included with this release 320 <para>A detailed list of all security patches included with this release
321 is available in the Enea NFV Access Security Report document.</para> 321 is available in the Enea NFV Access Security Report document.</para>
322 </section> 322 </section>
323</chapter> \ No newline at end of file 323</chapter>
diff --git a/doc/book-enea-nfv-access-release-info/doc/main_changes.xml b/doc/book-enea-nfv-access-release-info/doc/main_changes.xml
index 00cf31f..48e913f 100644
--- a/doc/book-enea-nfv-access-release-info/doc/main_changes.xml
+++ b/doc/book-enea-nfv-access-release-info/doc/main_changes.xml
@@ -17,15 +17,11 @@
17 17
18 <itemizedlist> 18 <itemizedlist>
19 <listitem> 19 <listitem>
20 <para>DPDK 17.08</para> 20 <para>DPDK 18.02</para>
21 </listitem> 21 </listitem>
22 22
23 <listitem> 23 <listitem>
24 <para>OVS 2.8</para> 24 <para>OVS 2.9</para>
25 </listitem>
26
27 <listitem condition="arm">
28 <para>ODP</para>
29 </listitem> 25 </listitem>
30 </itemizedlist> 26 </itemizedlist>
31 </listitem> 27 </listitem>
@@ -119,4 +115,4 @@
119 in this release, any applications dependent on these components are not 115 in this release, any applications dependent on these components are not
120 compatible with the current release.</para> 116 compatible with the current release.</para>
121 </section> 117 </section>
122</chapter> \ No newline at end of file 118</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-05-16 18:58:18 +0000