summaryrefslogtreecommitdiffstats
path: root/doc/book-enea-nfv-access-reference-guide-intel/doc/using_nfv_access_sdks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/book-enea-nfv-access-reference-guide-intel/doc/using_nfv_access_sdks.xml')
-rw-r--r--doc/book-enea-nfv-access-reference-guide-intel/doc/using_nfv_access_sdks.xml549
1 files changed, 0 insertions, 549 deletions
diff --git a/doc/book-enea-nfv-access-reference-guide-intel/doc/using_nfv_access_sdks.xml b/doc/book-enea-nfv-access-reference-guide-intel/doc/using_nfv_access_sdks.xml
deleted file mode 100644
index 6280338..0000000
--- a/doc/book-enea-nfv-access-reference-guide-intel/doc/using_nfv_access_sdks.xml
+++ /dev/null
@@ -1,549 +0,0 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="using_sdks">
5 <title>Using the Enea NFV Access SDKs</title>
6
7 <para>Enea NFV Access comes with two Software Development Kits: the
8 <emphasis role="bold">Standard SDK </emphasis>and the <emphasis
9 role="bold">Extensible SDK</emphasis>.</para>
10
11 <para>The Standard SDK can be used to develop, debug and run on a target
12 device (i.e. Xeon D, Atom C3000) user-applications and kernel modules which
13 are specific to the target architecture on host. The Extensible SDK can be
14 used to add a new Yocto recipe, build, test and package software, and
15 optionally deploy it to a target device.</para>
16
17 <note>
18 <para>The Extensible SDK is based on core-i7 architecture and can't be
19 used for building kernel modules specific to other architectures.</para>
20 </note>
21
22 <para><emphasis role="bold">Benefits of the Extensible
23 SDK:</emphasis><itemizedlist>
24 <listitem>
25 <para>Shared development environment.</para>
26 </listitem>
27
28 <listitem>
29 <para>Ease in adding new applications and libraries, modifying the
30 source of an existing component or adding new Yocto
31 layers/recipes.</para>
32 </listitem>
33
34 <listitem>
35 <para>Shared state for faster builds.</para>
36 </listitem>
37
38 <listitem>
39 <para>Devtool support.</para>
40 </listitem>
41
42 <listitem>
43 <para>One-time SDK installation with easy updates and extensions
44 available as needed.</para>
45 </listitem>
46
47 <listitem>
48 <para>Runs on a range of host distributions.</para>
49 </listitem>
50 </itemizedlist></para>
51
52 <para>For additional information about SDKs, please refer to the <ulink
53 url="https://wiki.yoctoproject.org/wiki/Application_Development_with_Extensible_SDK#Extensible_SDK">Application
54 Development with Extensible SDK, </ulink> <ulink
55 url="https://wiki.yoctoproject.org/wiki/Extensible_SDK">Extensible SDK Wiki
56 page</ulink> and the <ulink
57 url="https://www.yoctoproject.org/docs/current/sdk-manual/sdk-manual.html">Yocto
58 SDK Manual</ulink>.</para>
59
60 <section id="std_sdk">
61 <title>Standard SDK</title>
62
63 <para>The Standard SDK consists of:</para>
64
65 <itemizedlist>
66 <listitem>
67 <para>A Cross-Development Toolchain. Comprised of a cross-compiler and
68 a cross-debugger.</para>
69 </listitem>
70
71 <listitem>
72 <para>Libraries, Headers and Symbols, specific to the image.</para>
73 </listitem>
74
75 <listitem>
76 <para>The <literal>environment-setup</literal> script. Defines the
77 environment variables.</para>
78 </listitem>
79
80 <listitem>
81 <para>The Element ODM SDK.</para>
82 </listitem>
83 </itemizedlist>
84
85 <section id="install-crosscomp">
86 <title>Installing the Cross-Compilation Toolchain</title>
87
88 <para>Before cross-compiling applications for your target, you need to
89 install the corresponding toolchain on your workstation.</para>
90
91 <para><emphasis role="bold">How to install a toolchain using the
92 Installer</emphasis></para>
93
94 <orderedlist>
95 <listitem>
96 <para>Download the zip image from <ulink
97 url="https://portal.enea.com/access/">portal.enea.com/access</ulink>
98 and unzip it on the host machine e.g. in the
99 <literal>Enea_NFV_Access_2.0 </literal>directory.</para>
100 </listitem>
101
102 <listitem>
103 <para>Run the install script located at
104 <literal>Enea_NFV_Access_2.0/x86_64/install/sdk</literal> directory,
105 when prompted, select to install the toolchain in a desired
106 directory, referred to henceforth as
107 <literal>[sdkdir]</literal>.</para>
108
109 <programlisting>$ ./install-sdk.sh</programlisting>
110
111 <para>A default path where the toolchain will be installed will be
112 shown in the prompt. The installer will unpack the
113 <literal>environment-setup</literal> script in
114 <literal>[sdkdir]</literal> and the toolchain under
115 <literal>[sdkdir]/sysroots</literal>.</para>
116
117 <note>
118 <para>Choose a unique directory for each toolchain. Installing a
119 second toolchain of any type in the same directory as a previously
120 installed one will break the <literal>$PATH</literal> variable of
121 the first one.</para>
122 </note>
123 </listitem>
124
125 <listitem>
126 <para>Set up the toolchain environment for your target by sourcing
127 the <literal>environment-setup</literal> script: <programlisting>$ source [sdkdir]/environment-setup-corei7-64-enea-linux</programlisting></para>
128 </listitem>
129
130 <listitem>
131 <para>Make sure you have <literal>libelf-dev</literal> installed
132 into your host distribution. This is needed for working with the
133 kernel and building kernel modules.<programlisting>$ sudo apt-get install libelf-dev</programlisting></para>
134 </listitem>
135 </orderedlist>
136 </section>
137
138 <section id="crosscomp-apps">
139 <title>Cross-Compiling Applications from the Command Line</title>
140
141 <para>Once the <literal>environment-setup</literal> script is sourced,
142 you can create and compile your applications for your target.</para>
143
144 <para><emphasis role="bold">How to cross-compile from the command
145 line</emphasis></para>
146
147 <orderedlist>
148 <listitem>
149 <para>Create a Makefile for your application, example:</para>
150
151 <programlisting>helloworld:helloworld.o
152 $(CC) -o helloworld helloworld.o
153clean:
154 rm -f *.o helloworld
155#include stdio.h;
156int main(void) {
157 printf("Hello World\n");
158 return 0;
159}</programlisting>
160 </listitem>
161
162 <listitem>
163 <para>Run <command>make</command> to cross-compile your application
164 according to the environment set up:</para>
165
166 <programlisting>$ make</programlisting>
167 </listitem>
168
169 <listitem>
170 <para>Deploy the application to your target and run it:</para>
171
172 <programlisting># ./helloworld
173hello world</programlisting>
174 </listitem>
175 </orderedlist>
176 </section>
177
178 <section id="crosscomp-kern-mod">
179 <title>Cross-Compiling Kernel Modules</title>
180
181 <para>Before cross-compiling kernel modules, inside the kernel source
182 tree in the installed SDK, available at
183 <literal>[sdkdir]/sysroots/targetarch-enea-linux/usr/src/kernel</literal>,
184 run the following command:</para>
185
186 <programlisting>make scripts prepare</programlisting>
187
188 <para>Once the <literal>environment-setup</literal> script is sourced,
189 you can make and compile your kernel modules as intended for your
190 target.</para>
191
192 <para><emphasis role="bold">How to cross-compile a kernel
193 module</emphasis></para>
194
195 <orderedlist>
196 <listitem>
197 <para>Create a Makefile for the kernel module, example:</para>
198
199 <programlisting>obj-m := hello.ko
200PWD := $(shell pwd)
201
202KERNEL_SRC := full path to kernel source tree
203
204all: scripts
205 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" modules
206scripts:
207 $(MAKE) -C $(KERNEL_SRC) scripts
208clean:
209 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" clean
210#include linux/module.h /* Needed by all modules */
211#include linux/kernel.h /* Needed for KERN_INFO */
212#include linux/init.h /* Needed for the macros */
213
214static int __init hello_start(void)
215{
216 printk(KERN_INFO "Loading hello module...\n");
217 printk(KERN_INFO "Hello, world\n");
218 return 0;
219}
220
221static void __exit hello_end(void)
222{
223 printk(KERN_INFO "Goodbye, world\n");
224}
225
226module_init(hello_start);
227module_exit(hello_end);
228
229MODULE_LICENSE("GPL");</programlisting>
230 </listitem>
231
232 <listitem>
233 <para>Run the <command>make</command> command to cross-compile your
234 kernel module according to the environment set up:</para>
235
236 <programlisting>$ make</programlisting>
237 </listitem>
238
239 <listitem>
240 <para>Deploy the kernel module <literal>hello.ko</literal> to your
241 target and install/remove it:</para>
242
243 <programlisting># insmod hello.ko
244# rmmod hello.ko
245# dmesg
246[...] Loading hello module...
247[...] Hello, world
248[...] Goodbye, world</programlisting>
249 </listitem>
250 </orderedlist>
251 </section>
252
253 <section id="deploy-artifacts">
254 <title>Deploying your artifacts</title>
255
256 <para>A network connection is needed to deploy the artifacts on the host
257 target. Use <command>scp</command> to copy it to the desired
258 location:</para>
259
260 <programlisting># scp helloworld root@[target_ip_address]:/tmp</programlisting>
261 </section>
262
263 <section id="install-odm-sdk">
264 <title>Element ODM SDK</title>
265
266 <para>The Element ODM SDK is included in the Enea NFV Access SDK. Please
267 refer to the Element ODM documentation located in the Documentation
268 folder included with your release, on how to use the ODM SDK and how to
269 build ODM applications:</para>
270
271 <programlisting>Documentation/
272 Element_ODM_Kick_Start_Guide.pdf
273 Element_On_Device_Mgmt_Guide.pdf</programlisting>
274
275 <para>To build the ODM target kit, access the location of the ODM SDK
276 and run the <command>make</command> command:</para>
277
278 <programlisting>$ cd [sdkdir]/sysroots/corei7-64-enea-linux/usr/local/odm/odm-sdk-4.0.3-x86_64/
279$ make</programlisting>
280 </section>
281 </section>
282
283 <section id="esdk">
284 <title>Extensible SDK</title>
285
286 <para>The Extensible SDK helps you easily build, test and package
287 software, and deploy it to the target device.</para>
288
289 <para><emphasis role="bold">The Extensible SDK consists
290 of:</emphasis></para>
291
292 <itemizedlist>
293 <listitem>
294 <para>A Cross-Development Toolchain.</para>
295 </listitem>
296
297 <listitem>
298 <para>Libraries, Headers and Symbols for the x86 architecture.</para>
299 </listitem>
300
301 <listitem>
302 <para>The <literal>environment-setup</literal> script. Defines the
303 environment variables.</para>
304 </listitem>
305
306 <listitem>
307 <para>Devtool. A command-line tool used to automatically create
308 recipes for an existing source code, modify an existing recipe, build
309 and deploy the application to target.</para>
310 </listitem>
311 </itemizedlist>
312
313 <section id="install-esdk">
314 <title>Installing the Extensible SDK</title>
315
316 <para>To install the Extensible SDK on your host development machine,
317 run the installation script provided in the
318 <literal>Enea_NFV_Access_2.0/x86_64/install/esdk</literal>
319 folder:</para>
320
321 <orderedlist>
322 <listitem>
323 <para><programlisting>$ ./install-sdk.sh</programlisting>When
324 prompted, select to install the toolchain in a desired directory,
325 referred to henceforth as <literal>[sdkdir]</literal>.</para>
326
327 <para>A default path where the toolchain will be installed will be
328 shown in the prompt. The installer unpacks the
329 <literal>environment-setup</literal> script in
330 <literal>[sdkdir]</literal> and the toolchain under
331 <literal>[sdkdir]/sysroots</literal>.</para>
332
333 <note>
334 <para>Choose a unique directory for each toolchain. Installing a
335 second toolchain of any type in the same directory as a previously
336 installed one will break the <literal>$PATH</literal> variable of
337 the first one.</para>
338 </note>
339 </listitem>
340
341 <listitem>
342 <para>Set up the toolchain environment for your target by sourcing
343 the <literal>environment-setup</literal> script. Example:
344 <programlisting>$ source [sdkdir]/environment-setup-corei7-64-enea-linux</programlisting></para>
345
346 <para>With the SDK environment now set up, you may run
347 <command>devtool</command> to perform development tasks. Run
348 <command>devtool --help</command> to display the command manual for
349 further options available for use.</para>
350 </listitem>
351 </orderedlist>
352 </section>
353
354 <section id="add_new_comp_esdk">
355 <title>Adding a new component</title>
356
357 <para>The <command>devtool add</command> command is used to create a new
358 recipe and the <command>devtool modify</command> command is used to work
359 on an existing recipe.</para>
360
361 <para>To add a component, you can do the following:</para>
362
363 <itemizedlist>
364 <listitem>
365 <para><emphasis role="bold">Generate a recipe from an existing
366 application code and Makefile</emphasis></para>
367
368 <para>Run <command>devtool add [recipe]
369 [/path/to/your_application]</command> to generate a recipe:</para>
370
371 <programlisting>$ devtool add bbexample /path/to/bbexample</programlisting>
372
373 <para>Or alternatively, you can download from an upstream git
374 repository:<programlisting>$ devtool add bbexample https://github.com/whbruce/bbexample.git</programlisting></para>
375
376 <para><literal><command>devtool</command></literal> creates a Git
377 repository locally during extraction at:
378 <literal>[sdkdir]/workspace/source/bbexample</literal>, where the
379 recipe will be created automatically. E.g:
380 <literal>[sdkdir]/workspace/recipes/bbexample/bbexample.bb</literal>.</para>
381 </listitem>
382
383 <listitem>
384 <para><emphasis role="bold">Use an existing recipe from a Yocto
385 layer</emphasis></para>
386
387 <para>Use <command>devtool modify [recipe]</command> on any recipe
388 from <literal>[sdkdir]/layers/poky/meta*</literal>, example:</para>
389
390 <programlisting>$ devtool modify curl</programlisting>
391 </listitem>
392
393 <listitem>
394 <para><emphasis role="bold">Clone a new recipe from the upstream
395 Yocto project if the recipe is not included in your Extensible SDK
396 </emphasis></para>
397
398 <orderedlist>
399 <listitem>
400 <para>Clone a recipe from the upstream Yocto project, e.g.
401 <literal>meta-security</literal>:</para>
402
403 <programlisting>$ pushd [sdkdir]/layers/poky
404$ git clone -b rocko git://git.yoctoproject.org/meta-security
405$ popd</programlisting>
406 </listitem>
407
408 <listitem>
409 <para>Use the <literal>bitbake-layers</literal> script to add
410 <literal>meta-security</literal> to BBLAYERS:</para>
411
412 <programlisting>$ layers/poky/bitbake/bin/bitbake-layers add-layer layers/poky/meta-security</programlisting>
413
414 <para>If all required layers are not present you can get a
415 dependency ERROR:<programlisting>ERROR: Layer 'security' depends on layer 'perl-layer', but this layer is not \
416enabled in your configuration</programlisting>To rectify the dependency issue
417 exemplified above, clone <literal>meta-perl</literal> from
418 openembedded and run <command>add-layers</command>
419 again:<programlisting>$ layers/poky/bitbake/bin/bitbake-layers add-layer layers/poky/meta-security</programlisting>Now
420 <literal>[sdkdir]/layers/poky/meta-security</literal> is created
421 and the layer has been added to
422 <literal>[sdkdir]/conf/bblayers.conf</literal>:</para>
423
424 <note condition="hidden">
425 <para>The image build result can be seen at:
426 <literal>[sdkdir]/tmp/deploy/images/qemux86-64</literal></para>
427 </note>
428 </listitem>
429
430 <listitem>
431 <para>Use <command>devtool modify [recipe]</command> to change
432 an existing recipe inside the <literal>meta-security</literal>
433 layer:</para>
434
435 <programlisting>$ devtool modify isic</programlisting>
436
437 <para>The following directories and files will be created:
438 <literal>[sdkdir]/workspace/appends/isic_0.07.bbappend</literal>
439 and <literal>[sdkdir]/workspace/sources/isic</literal>.</para>
440 </listitem>
441 </orderedlist>
442 </listitem>
443 </itemizedlist>
444 </section>
445
446 <section id="devtool_build">
447 <title>Building an application</title>
448
449 <para>Use <command>devtool build [recipe]</command> to build the an
450 application:</para>
451
452 <para><programlisting>$ devtool build bbexample</programlisting><note>
453 <para>The image build result can be seen at
454 <literal>&lt;[sdkdir]&gt;/tmp/work/&lt;arch&gt;/&lt;recipe&gt;</literal>.
455 E.g.
456 <literal>[sdkdir]/tmp/work/corei7-64-enea-linux/bbexample</literal>.</para>
457 </note></para>
458 </section>
459 </section>
460
461 <section id="deploy">
462 <title>Deploy your application to a target</title>
463
464 <para>Deploy your application to a target by using the <command>devtool
465 deploy-target</command> command or by building a docker image and
466 deploying it.</para>
467
468 <section id="deploy-artifacts-esdk">
469 <title>Using devtool deploy-target</title>
470
471 <para>When deploying an application to a target device two scenarios can
472 occur.</para>
473
474 <itemizedlist>
475 <listitem>
476 <para>Example 1, where application deployment has no
477 issues:<programlisting>$ devtool deploy-target bbexample root@[target_ip_address]</programlisting>Now
478 run bbexample application on target:<programlisting># bbexample
479Hello Yocto World...
480Hello World (from a shared library!)</programlisting></para>
481 </listitem>
482
483 <listitem>
484 <para>Example 2, where application deployment encounters dependency
485 issues:<programlisting>$ devtool deploy-target isic root@[target_ip_address]
486# isic
487isic: error while loading shared libraries: libnet.so.9: cannot open shared
488object file: No such file or directory</programlisting>It is mandatory to add
489 required dependecies. The example application used above is
490 dependent on <literal>libnet</literal>, and requires you to build
491 and deploy libnet separately to the target in order for the
492 application to work:<programlisting>$ devtool modify libnet
493$ devtool build libnet
494$ devtool deploy-target libnet root@[target_ip_address]</programlisting>Now
495 run the application on target again:<programlisting># isic
496usage: isic [-v] [-D] -s [source ip] -d [destination ip] [-r [random seed]]
497...</programlisting></para>
498 </listitem>
499
500 <listitem>
501 <para>Remove/uninstall the application from target as needed:</para>
502
503 <programlisting>$ devtool undeploy-target isic root@[target_ip_address]</programlisting>
504 </listitem>
505 </itemizedlist>
506 </section>
507
508 <section id="docker_deploy">
509 <title>Creating and deploying a Docker image</title>
510
511 <para>You can build a docker container image from your Extensible SDK
512 and add your application into the container image.</para>
513
514 <orderedlist>
515 <listitem>
516 <para>Create a container image recipe in the workspace layer, e.g.
517 <literal>cont-image</literal> and add the following lines:</para>
518
519 <programlisting>IMAGE_INSTALL += "your_application"
520
521LICENSE = "MIT"
522
523IMAGE_FSTYPES = "container"
524
525inherit core-image</programlisting>
526 </listitem>
527
528 <listitem>
529 <para>Build the container image:</para>
530
531 <programlisting>$ devtool build-image cont-image </programlisting>
532
533 <note>
534 <para>The image build result can be seen at:
535 <literal>[sdkdir]/tmp/deploy/images/&lt;target&gt;</literal>.
536 E.g.:
537 <literal>[sdkdir]/tmp/deploy/images/qemux86-64</literal></para>
538 </note>
539 </listitem>
540
541 <listitem>
542 <para>Copy the image to the target and import it into Docker:</para>
543
544 <programlisting># docker import cont-image-qemux86.tar.bz2 [your_application]</programlisting>
545 </listitem>
546 </orderedlist>
547 </section>
548 </section>
549</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-17 20:15:06 +0000