summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/benchmarks.xml1637
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/book.xml30
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/container_virtualization.xml136
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/dpdk.xml119
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/eltf_params_template.xml151
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/eltf_params_updated.xml165
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/getting_started.xml639
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/hypervisor_virtualization.xml744
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.pngbin0 -> 6403 bytes
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg3
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/images/virtual_network_functions.pngbin0 -> 24106 bytes
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/overview.xml165
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/ovs.xml161
-rw-r--r--doc/book-enea-nfv-access-guide-intel/doc/using_nfv_access_sdks.xml472
-rw-r--r--doc/book-enea-nfv-access-guide-intel/swcomp.mk10
-rw-r--r--doc/book-enea-nfv-access-guide/doc/getting_started.xml360
-rw-r--r--doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.pngbin0 -> 6403 bytes
-rw-r--r--doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg3
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/about_release.xml272
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/book.xml36
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_template.xml151
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated.xml156
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated_template_how_to_use.txt320
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/getting_enea_nfv_access.xml31
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/jiraissues_override.xml36
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/known_bugs_and_limitations.xml53
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/main_changes.xml114
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/system_requirements.xml162
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/doc/system_requirements_prerequisites.xml61
-rw-r--r--doc/book-enea-nfv-access-release-info-intel/swcomp.mk10
30 files changed, 6056 insertions, 141 deletions
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/benchmarks.xml b/doc/book-enea-nfv-access-guide-intel/doc/benchmarks.xml
new file mode 100644
index 0000000..3279601
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/benchmarks.xml
@@ -0,0 +1,1637 @@
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="benchmarks">
5 <title>Benchmarks</title>
6
7 <section id="hw-setup">
8 <title>Hardware Setup</title>
9
10 <para>The following table describes all the needed prequisites for an apt
11 hardware setup:</para>
12
13 <table>
14 <title>Hardware Setup</title>
15
16 <tgroup cols="2">
17 <colspec align="left" />
18
19 <thead>
20 <row>
21 <entry align="center">Item</entry>
22
23 <entry align="center">Description</entry>
24 </row>
25 </thead>
26
27 <tbody>
28 <row>
29 <entry align="left">Server Platform</entry>
30
31 <entry align="left">Supermicro X10SDV-4C-TLN2F
32 http://www.supermicro.com/products/motherboard/xeon/d/X10SDV-4C-TLN2F.cfm</entry>
33 </row>
34
35 <row>
36 <entry align="left">ARCH</entry>
37
38 <entry>x86-64</entry>
39 </row>
40
41 <row>
42 <entry align="left">Processor</entry>
43
44 <entry>1 x Intel Xeon D-1521 (Broadwell), 4 cores, 8
45 hyper-threaded cores per processor</entry>
46 </row>
47
48 <row>
49 <entry align="left">CPU freq</entry>
50
51 <entry>2.40 GHz</entry>
52 </row>
53
54 <row>
55 <entry align="left">RAM</entry>
56
57 <entry>16GB</entry>
58 </row>
59
60 <row>
61 <entry align="left">Network</entry>
62
63 <entry>Dual integrated 10G ports</entry>
64 </row>
65
66 <row>
67 <entry align="left">Storage</entry>
68
69 <entry>Samsung 850 Pro 128GB SSD</entry>
70 </row>
71 </tbody>
72 </tgroup>
73 </table>
74
75 <para>Generic tests configuration:</para>
76
77 <itemizedlist>
78 <listitem>
79 <para>All tests use one port, one core and one Rx/TX queue for fast
80 path traffic.</para>
81 </listitem>
82 </itemizedlist>
83 </section>
84
85 <section id="bios">
86 <title>BIOS Settings</title>
87
88 <para>The table below details the BIOS settings for which the default
89 values were changed when doing performance measurements.</para>
90
91 <table>
92 <title>BIOS Settings</title>
93
94 <tgroup cols="4">
95 <colspec align="left" />
96
97 <thead>
98 <row>
99 <entry align="center">Menu Path</entry>
100
101 <entry align="center">Setting Name</entry>
102
103 <entry align="center">Enea NFV Access value</entry>
104
105 <entry align="center">BIOS Default value</entry>
106 </row>
107 </thead>
108
109 <tbody>
110 <row>
111 <entry align="left">CPU Configuration</entry>
112
113 <entry align="left">Direct Cache Access (DCA)</entry>
114
115 <entry>Enable</entry>
116
117 <entry>Auto</entry>
118 </row>
119
120 <row>
121 <entry>CPU Configuration / Advanced Power Management
122 Configuration</entry>
123
124 <entry align="left">EIST (P-States)</entry>
125
126 <entry>Disable</entry>
127
128 <entry>Enable</entry>
129 </row>
130
131 <row>
132 <entry>CPU Configuration / Advanced Power Management Configuration
133 / CPU C State Control</entry>
134
135 <entry align="left">CPU C State</entry>
136
137 <entry>Disable</entry>
138
139 <entry>Enable</entry>
140 </row>
141
142 <row>
143 <entry>CPU Configuration / Advanced Power Management Configuration
144 / CPU Advanced PM Turning / Energy Perf BIAS</entry>
145
146 <entry align="left">Energy Performance Tuning</entry>
147
148 <entry>Disable</entry>
149
150 <entry>Enable</entry>
151 </row>
152
153 <row>
154 <entry>CPU Configuration / Advanced Power Management Configuration
155 / CPU Advanced PM Turning / Energy Perf BIAS</entry>
156
157 <entry align="left">Energy Performance BIAS Setting</entry>
158
159 <entry>Performance</entry>
160
161 <entry>Balanced Performance</entry>
162 </row>
163
164 <row>
165 <entry>CPU Configuration / Advanced Power Management Configuration
166 / CPU Advanced PM Turning / Energy Perf BIAS</entry>
167
168 <entry align="left">Power/Performance Switch</entry>
169
170 <entry>Disable</entry>
171
172 <entry>Enable</entry>
173 </row>
174
175 <row>
176 <entry>CPU Configuration / Advanced Power Management Configuration
177 / CPU Advanced PM Turning / Program PowerCTL _MSR</entry>
178
179 <entry align="left">Energy Efficient Turbo</entry>
180
181 <entry>Disable</entry>
182
183 <entry>Enable</entry>
184 </row>
185
186 <row>
187 <entry>Chipset Configuration / North Bridge / IIO
188 Configuration</entry>
189
190 <entry align="left">EV DFX Features</entry>
191
192 <entry>Enable</entry>
193
194 <entry>Disable</entry>
195 </row>
196
197 <row>
198 <entry>Chipset Configuration / North Bridge / Memory
199 Configuration</entry>
200
201 <entry align="left">Enforce POR</entry>
202
203 <entry>Disable</entry>
204
205 <entry>Enable</entry>
206 </row>
207
208 <row>
209 <entry>Chipset Configuration / North Bridge / Memory
210 Configuration</entry>
211
212 <entry align="left">Memory Frequency</entry>
213
214 <entry>2400</entry>
215
216 <entry>Auto</entry>
217 </row>
218
219 <row>
220 <entry>Chipset Configuration / North Bridge / Memory
221 Configuration</entry>
222
223 <entry align="left">DRAM RAPL Baseline</entry>
224
225 <entry>Disable</entry>
226
227 <entry>DRAM RAPL Mode 1</entry>
228 </row>
229 </tbody>
230 </tgroup>
231 </table>
232 </section>
233
234 <section id="use-cases">
235 <title>Use Cases</title>
236
237 <section id="docker-benchmarks">
238 <title>Docker related benchmarks</title>
239
240 <section>
241 <title>Forward traffic in Docker</title>
242
243 <para>Benchmarking traffic forwarding using testpmd in a Docker
244 container.</para>
245
246 <para>Pktgen is used to generate UDP traffic that will reach testpmd,
247 running in a Docker image. It will then be forwarded back to source on
248 the return trip (<emphasis role="bold">Forwarding</emphasis>).</para>
249
250 <para>This test measures:</para>
251
252 <itemizedlist>
253 <listitem>
254 <para>pktgen TX, RX in packets per second (pps) and Mbps</para>
255 </listitem>
256
257 <listitem>
258 <para>testpmd TX, RX in packets per second (pps)</para>
259 </listitem>
260
261 <listitem>
262 <para>divide testpmd RX / pktgen TX in pps to obtain throughput in
263 percentages (%)</para>
264 </listitem>
265 </itemizedlist>
266
267 <section id="usecase-one">
268 <title>Test Setup for Target 1</title>
269
270 <para>Start by following the steps below:</para>
271
272 <para>SSD boot using the following <literal>grub.cfg</literal>
273 entry: <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
274isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
275clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
276processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
277intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
278hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting></para>
279
280 <para>Kill unnecessary services:<programlisting>killall ovsdb-server ovs-vswitchd
281rm -rf /etc/openvswitch/*
282mkdir -p /var/run/openvswitch</programlisting>Mount hugepages and configure
283 DPDK:<programlisting>mkdir -p /mnt/huge
284mount -t hugetlbfs nodev /mnt/huge
285modprobe igb_uio
286dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Run
287 pktgen:<programlisting>cd /usr/share/apps/pktgen/
288./pktgen -c 0xF -n 1 -- -P -m "[3:2].0"</programlisting>In the pktgen console
289 run:<programlisting>str</programlisting>To change framesize for
290 pktgen, from [64, 128, 256, 512]:<programlisting>set 0 size &amp;lt;number&amp;gt;</programlisting></para>
291 </section>
292
293 <section id="usecase-two">
294 <title>Test Setup for Target 2</title>
295
296 <para>Start by following the steps below:</para>
297
298 <para>SSD boot using the following <literal>grub.cfg</literal>
299 entry:</para>
300
301 <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
302isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
303clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
304processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
305intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
306hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>
307
308 <para>It is expected to have Docker/guest image on target. Configure
309 the OVS bridge:<programlisting># OVS old config clean-up
310killall ovsdb-server ovs-vswitchd
311rm -rf /etc/openvswitch/*
312mkdir -p /var/run/openvswitch
313
314# Mount hugepages and bind interfaces to dpdk
315mkdir -p /mnt/huge
316mount -t hugetlbfs nodev /mnt/huge
317modprobe igb_uio
318dpdk-devbind --bind=igb_uio 0000:03:00.0
319
320# configure openvswitch with DPDK
321export DB_SOCK=/var/run/openvswitch/db.sock
322ovsdb-tool create /etc/openvswitch/conf.db /
323/usr/share/openvswitch/vswitch.ovsschema
324ovsdb-server --remote=punix:$DB_SOCK /
325--remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach
326ovs-vsctl --no-wait init
327ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10
328ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc
329ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048
330ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true
331ovs-vswitchd unix:$DB_SOCK --pidfile --detach /
332--log-file=/var/log/openvswitch/ovs-vswitchd.log
333
334ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev
335ovs-vsctl add-port ovsbr0 vhost-user1 /
336-- set Interface vhost-user1 type=dpdkvhostuser ofport_request=1
337ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface /
338dpdk0 type=dpdk options:dpdk-devargs=0000:03:00.0 ofport_request=2
339
340# configure static flows
341ovs-ofctl del-flows ovsbr0
342ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2
343ovs-ofctl add-flow ovsbr0 in_port=2,action=output:1</programlisting>Import a
344 Docker container:<programlisting>docker import enea-nfv-access-guest-qemux86-64.tar.gz el7_guest</programlisting>Start
345 the Docker container:<programlisting>docker run -it --rm -v /var/run/openvswitch/:/var/run/openvswitch/ /
346-v /mnt/huge:/mnt/huge el7_guest /bin/bash</programlisting>Start the testpmd
347 application in Docker:<programlisting>testpmd -c 0x30 -n 2 --file-prefix prog1 --socket-mem 512 --no-pci /
348--vdev=virtio_user0,path=/var/run/openvswitch/vhost-user1 /
349-d /usr/lib/librte_pmd_virtio.so.1.1 -- --burst 64 --disable-hw-vlan /
350--disable-rss -i --portmask=0x1 --coremask=0x20 --nb-cores=1 /
351--rxq=1 --txq=1 --txd=512 --rxd=512 --txqflags=0xf00 --port-topology=chained</programlisting>To
352 start traffic <emphasis role="bold">forwarding</emphasis>, run the
353 following command in testpmd CLI:<programlisting>start</programlisting>To
354 start traffic but in <emphasis role="bold">termination</emphasis>
355 mode (no traffic sent on TX), run following command in testpmd
356 CLI:<programlisting>set fwd rxonly
357start</programlisting><table>
358 <title>Results in forwarding mode</title>
359
360 <tgroup cols="8">
361 <tbody>
362 <row>
363 <entry align="center"><emphasis
364 role="bold">Bytes</emphasis></entry>
365
366 <entry align="center"><emphasis role="bold">pktgen pps
367 TX</emphasis></entry>
368
369 <entry align="center"><emphasis role="bold">pktgen MBits/s
370 TX</emphasis></entry>
371
372 <entry align="center"><emphasis role="bold">pktgen pps
373 RX</emphasis></entry>
374
375 <entry align="center"><emphasis role="bold">pktgen MBits/s
376 RX</emphasis></entry>
377
378 <entry align="center"><emphasis role="bold">testpmd pps
379 RX</emphasis></entry>
380
381 <entry align="center"><emphasis role="bold">testpmd pps
382 TX</emphasis></entry>
383
384 <entry align="center"><emphasis role="bold">throughput
385 (%)</emphasis></entry>
386 </row>
387
388 <row>
389 <entry role="bold"><emphasis
390 role="bold">64</emphasis></entry>
391
392 <entry>14877658</entry>
393
394 <entry>9997</entry>
395
396 <entry>7832352</entry>
397
398 <entry>5264</entry>
399
400 <entry>7831250</entry>
401
402 <entry>7831250</entry>
403
404 <entry>52,65%</entry>
405 </row>
406
407 <row>
408 <entry><emphasis role="bold">128</emphasis></entry>
409
410 <entry>8441305</entry>
411
412 <entry>9994</entry>
413
414 <entry>7533893</entry>
415
416 <entry>8922</entry>
417
418 <entry>7535127</entry>
419
420 <entry>7682007</entry>
421
422 <entry>89,27%</entry>
423 </row>
424
425 <row>
426 <entry role="bold"><emphasis
427 role="bold">256</emphasis></entry>
428
429 <entry>4528831</entry>
430
431 <entry>9999</entry>
432
433 <entry>4528845</entry>
434
435 <entry>9999</entry>
436
437 <entry>4528738</entry>
438
439 <entry>4528738</entry>
440
441 <entry>100%</entry>
442 </row>
443 </tbody>
444 </tgroup>
445 </table><table>
446 <title>Results in termination mode</title>
447
448 <tgroup cols="4">
449 <tbody>
450 <row>
451 <entry align="center"><emphasis
452 role="bold">Bytes</emphasis></entry>
453
454 <entry align="center"><emphasis role="bold">pktgen pps
455 TX</emphasis></entry>
456
457 <entry align="center"><emphasis role="bold">testpmd pps
458 RX</emphasis></entry>
459
460 <entry align="center"><emphasis role="bold">throughput
461 (%)</emphasis></entry>
462 </row>
463
464 <row>
465 <entry role="bold"><emphasis
466 role="bold">64</emphasis></entry>
467
468 <entry>14877775</entry>
469
470 <entry>8060974</entry>
471
472 <entry>54,1%</entry>
473 </row>
474
475 <row>
476 <entry><emphasis role="bold">128</emphasis></entry>
477
478 <entry>8441403</entry>
479
480 <entry>8023555</entry>
481
482 <entry>95,0%</entry>
483 </row>
484
485 <row>
486 <entry role="bold"><emphasis
487 role="bold">256</emphasis></entry>
488
489 <entry>4528864</entry>
490
491 <entry>4528840</entry>
492
493 <entry>99,9%</entry>
494 </row>
495 </tbody>
496 </tgroup>
497 </table></para>
498 </section>
499 </section>
500
501 <section id="usecase-three-four">
502 <title>Forward traffic from Docker to another Docker on the same
503 host</title>
504
505 <para>Benchmark a combo test using testpmd running in two Docker
506 instances, one which Forwards traffic to the second one, which
507 Terminates it.</para>
508
509 <para>Packets are generated with pktgen and TX-d to the first testpmd,
510 which will RX and Forward them to the second testpmd, which will RX
511 and terminate them.</para>
512
513 <para>Measurements are made in:</para>
514
515 <itemizedlist>
516 <listitem>
517 <para>pktgen TX in pps and Mbits/s</para>
518 </listitem>
519
520 <listitem>
521 <para>testpmd TX and RX pps in Docker1</para>
522 </listitem>
523
524 <listitem>
525 <para>testpmd RX pps in Docker2</para>
526 </listitem>
527 </itemizedlist>
528
529 <para>Throughput found as a percent, by dividing Docker2 <emphasis
530 role="bold">testpmd RX pps</emphasis> by <emphasis role="bold">pktgen
531 TX pps</emphasis>.</para>
532
533 <section id="target-one-usecase-three">
534 <title>Test Setup for Target 1</title>
535
536 <para>Start by following the steps below:</para>
537
538 <para>SSD boot using the following <literal>grub.cfg</literal>
539 entry:</para>
540
541 <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
542isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
543clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
544processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
545intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
546hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>
547
548 <para>Configure DPDK:<programlisting>mkdir -p /mnt/huge
549mount -t hugetlbfs nodev /mnt/huge
550modprobe igb_uio
551dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Run
552 pktgen:<programlisting>cd /usr/share/apps/pktgen/
553./pktgen -c 0xF -n 1 -- -P -m "[3:2].0"</programlisting>Choose one of the
554 values from [64, 128, 256, 512] to change the packet
555 size:<programlisting>set 0 size &lt;number&gt;</programlisting></para>
556 </section>
557
558 <section id="target-two-usecase-four">
559 <title>Test Setup for Target 2</title>
560
561 <para>Start by following the steps below:</para>
562
563 <para>SSD boot using the following <literal>grub.cfg</literal>
564 entry:</para>
565
566 <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
567isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
568clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
569processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 /
570iommu=pt intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
571hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>
572
573 <para><programlisting>killall ovsdb-server ovs-vswitchd
574rm -rf /etc/openvswitch/*
575mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge
576mount -t hugetlbfs nodev /mnt/huge
577modprobe igb_uio
578dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Configure the OVS
579 bridge:<programlisting>export DB_SOCK=/var/run/openvswitch/db.sock
580ovsdb-tool create /etc/openvswitch/conf.db /
581/usr/share/openvswitch/vswitch.ovsschema
582ovsdb-server --remote=punix:$DB_SOCK /
583--remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach
584ovs-vsctl --no-wait init
585ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10
586ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xcc
587ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048
588ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true
589ovs-vswitchd unix:$DB_SOCK --pidfile --detach /
590--log-file=/var/log/openvswitch/ovs-vswitchd.log
591ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev
592ovs-vsctl add-port ovsbr0 vhost-user1 -- set Interface /
593vhost-user1 type=dpdkvhostuser ofport_request=1
594ovs-vsctl add-port ovsbr0 vhost-user2 -- set Interface /
595vhost-user2 type=dpdkvhostuser ofport_request=2
596ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface dpdk0 /
597type=dpdk options:dpdk-devargs=0000:03:00.0 ofport_request=3
598ovs-ofctl del-flows ovsbr0
599ovs-ofctl add-flow ovsbr0 in_port=3,action=output:2
600ovs-ofctl add-flow ovsbr0 in_port=2,action=output:1</programlisting>Import a
601 Docker container:<programlisting>docker import enea-nfv-access-guest-qemux86-64.tar.gz el7_guest</programlisting>Start
602 the first Docker:<programlisting>docker run -it --rm --cpuset-cpus=4,5 /
603-v /var/run/openvswitch/:/var/run/openvswitch/ /
604-v /mnt/huge:/mnt/huge el7_guest /bin/bash</programlisting>Start the testpmd
605 application in Docker1:<programlisting>testpmd -c 0x30 -n 2 --file-prefix prog1 --socket-mem 512 --no-pci /
606--vdev=virtio_user0,path=/var/run/openvswitch/vhost-user1 /
607-d /usr/lib/librte_pmd_virtio.so.1.1 -- --burst 64 --disable-hw-vlan /
608--disable-rss -i --portmask=0x1 --coremask=0x20 --nb-cores=1 /
609--rxq=1 --txq=1 --txd=512 --rxd=512 --txqflags=0xf00 --port-topology=chained</programlisting>Configure
610 it in termination mode:<programlisting>set fwd rxonly</programlisting>Run
611 the testpmd application:<programlisting>start</programlisting>Open a
612 new console to the host and start the second Docker
613 instance:<programlisting>docker run -it --rm --cpuset-cpus=0,1 -v /var/run/openvswitch/:/var/run/openvswitch/ /
614-v /mnt/huge:/mnt/huge el7_guest /bin/bash</programlisting>In the second
615 container start testpmd:<programlisting>testpmd -c 0x0F --file-prefix prog2 --socket-mem 512 --no-pci /
616--vdev=virtio_user0,path=/var/run/openvswitch/vhost-user2 /
617-d /usr/lib/librte_pmd_virtio.so.1.1 -- -i --disable-hw-vlan</programlisting>Run
618 the TestPmd application in the second Docker:<programlisting>testpmd -c 0x3 -n 2 --file-prefix prog2 --socket-mem 512 --no-pci /
619--vdev=virtio_user0,path=/var/run/openvswitch/vhost-user2 /
620-d /usr/lib/librte_pmd_virtio.so.1.1 -- --burst 64 --disable-hw-vlan /
621--disable-rss -i --portmask=0x1 --coremask=0x2 --nb-cores=1 --rxq=1 /
622--txq=1 --txd=512 --rxd=512 --txqflags=0xf00 --port-topology=chained</programlisting>In
623 the testpmd shell, run:<programlisting>start</programlisting>Start
624 pktgen traffic by running the following command in pktgen
625 CLI:<programlisting>start 0</programlisting>To record traffic
626 results:<programlisting>show port stats 0</programlisting>This
627 should be used in testpmd applications.</para>
628
629 <table>
630 <title>Results</title>
631
632 <tgroup cols="5">
633 <tbody>
634 <row>
635 <entry align="center"><emphasis
636 role="bold">Bytes</emphasis></entry>
637
638 <entry align="center"><emphasis role="bold">Target 1 -
639 pktgen pps TX</emphasis></entry>
640
641 <entry align="center"><emphasis role="bold">Target 2 -
642 (forwarding) testpmd pps RX</emphasis></entry>
643
644 <entry align="center"><emphasis role="bold">Target 2 -
645 (forwarding) testpmd pps TX</emphasis></entry>
646
647 <entry align="center"><emphasis role="bold">Target 2 -
648 (termination) testpmd pps RX</emphasis></entry>
649 </row>
650
651 <row>
652 <entry role="bold"><emphasis
653 role="bold">64</emphasis></entry>
654
655 <entry>14877713</entry>
656
657 <entry>5031270</entry>
658
659 <entry>5031214</entry>
660
661 <entry>5031346</entry>
662 </row>
663
664 <row>
665 <entry><emphasis role="bold">128</emphasis></entry>
666
667 <entry>8441271</entry>
668
669 <entry>4670165</entry>
670
671 <entry>4670165</entry>
672
673 <entry>4670261</entry>
674 </row>
675
676 <row>
677 <entry role="bold"><emphasis
678 role="bold">256</emphasis></entry>
679
680 <entry>4528844</entry>
681
682 <entry>4490268</entry>
683
684 <entry>4490268</entry>
685
686 <entry>4490234</entry>
687 </row>
688
689 <row>
690 <entry><emphasis role="bold">512</emphasis></entry>
691
692 <entry>2349458</entry>
693
694 <entry>2349553</entry>
695
696 <entry>2349553</entry>
697
698 <entry>2349545</entry>
699 </row>
700 </tbody>
701 </tgroup>
702 </table>
703 </section>
704 </section>
705
706 <section id="pxe-config-docker">
707 <title>SR-IOV in in Docker</title>
708
709 <para>PCI passthrough tests using pktgen and testpmd in Docker.</para>
710
711 <para>pktgen[DPDK]Docker - PHY - Docker[DPDK] testpmd</para>
712
713 <para>Measurements:</para>
714
715 <itemizedlist>
716 <listitem>
717 <para>RX packets per second in testpmd (with testpmd configured in
718 rxonly mode).</para>
719 </listitem>
720 </itemizedlist>
721
722 <section id="target-setup">
723 <title>Test Setup</title>
724
725 <para>Boot Enea NFV Access from SSD:<programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
726isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable clocksource=tsc /
727tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 processor.max_cstate=0 /
728mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt intel_iommu=on hugepagesz=1GB /
729hugepages=8 default_hugepagesz=1GB hugepagesz=2M hugepages=2048 /
730vfio_iommu_type1.allow_unsafe_interrupts=1l</programlisting>Allow unsafe
731 interrupts:<programlisting>echo 1 &gt; /sys/module/vfio_iommu_type1/parameters/allow_unsafe_interrupts</programlisting>Configure
732 DPDK:<programlisting>mkdir -p /mnt/huge
733mount -t hugetlbfs nodev /mnt/huge
734dpdk-devbind.py --bind=ixgbe 0000:03:00.0
735ifconfig eno3 192.168.1.2
736echo 2 &gt; /sys/class/net/eno3/device/sriov_numvfs
737modprobe vfio-pci
738dpdk-devbind.py --bind=vfio-pci 0000:03:10.0
739dpdk-devbind.py --bind=vfio-pci 0000:03:10.2</programlisting>Start two docker
740 containers:<programlisting>docker run --privileged -it --rm -v /mnt/huge:/mnt/huge/ /
741--device /dev/vfio/vfio el7_guest /bin/bash
742docker run --privileged -it --rm -v /mnt/huge:/mnt/huge/ /
743--device /dev/vfio/vfio el7_guest /bin/bash</programlisting>In the first
744 container start pktgen:<programlisting>cd /usr/share/apps/pktgen/
745./pktgen -c 0x1f -w 0000:03:10.0 -n 1 --file-prefix pg1 /
746--socket-mem 1024 -- -P -m "[3:4].0"</programlisting>In the pktgen prompt set
747 the destination MAC address:<programlisting>set mac 0 XX:XX:XX:XX:XX:XX
748str</programlisting>In the second container start testpmd:<programlisting>testpmd -c 0x7 -n 1 -w 0000:03:10.2 -- -i --portmask=0x1 /
749--txd=256 --rxd=256 --port-topology=chained</programlisting>In the testpmd
750 prompt set <emphasis role="bold">forwarding</emphasis>
751 rxonly:<programlisting>set fwd rxonly
752start</programlisting><table>
753 <title>Results</title>
754
755 <tgroup cols="5">
756 <tbody>
757 <row>
758 <entry align="center"><emphasis
759 role="bold">Bytes</emphasis></entry>
760
761 <entry align="center"><emphasis role="bold">pktgen pps
762 TX</emphasis></entry>
763
764 <entry align="center"><emphasis role="bold">testpmd pps
765 RX</emphasis></entry>
766
767 <entry align="center"><emphasis role="bold">pktgen MBits/s
768 TX</emphasis></entry>
769
770 <entry align="center"><emphasis role="bold">throughput
771 (%)</emphasis></entry>
772 </row>
773
774 <row>
775 <entry role="bold"><emphasis
776 role="bold">64</emphasis></entry>
777
778 <entry>14204211</entry>
779
780 <entry>14204561</entry>
781
782 <entry>9545</entry>
783
784 <entry>100</entry>
785 </row>
786
787 <row>
788 <entry><emphasis role="bold">128</emphasis></entry>
789
790 <entry>8440340</entry>
791
792 <entry>8440201</entry>
793
794 <entry>9993</entry>
795
796 <entry>99.9</entry>
797 </row>
798
799 <row>
800 <entry role="bold"><emphasis
801 role="bold">256</emphasis></entry>
802
803 <entry>4533828</entry>
804
805 <entry>4533891</entry>
806
807 <entry>10010</entry>
808
809 <entry>100</entry>
810 </row>
811
812 <row>
813 <entry><emphasis role="bold">512</emphasis></entry>
814
815 <entry>2349886</entry>
816
817 <entry>2349715</entry>
818
819 <entry>10000</entry>
820
821 <entry>99.9</entry>
822 </row>
823 </tbody>
824 </tgroup>
825 </table></para>
826 </section>
827 </section>
828 </section>
829
830 <section id="vm-benchmarks">
831 <title>VM related benchmarks</title>
832
833 <section id="usecase-four">
834 <title>Forward/termination traffic in one VM</title>
835
836 <para>Benchmarking traffic (UDP) forwarding and termination using
837 testpmd in a virtual machine.</para>
838
839 <para>The Pktgen application is used to generate traffic that will
840 reach testpmd running on a virtual machine, and be forwarded back to
841 source on the return trip. With the same setup a second measurement
842 will be done with traffic termination in the virtual machine.</para>
843
844 <para>This test case measures:</para>
845
846 <itemizedlist>
847 <listitem>
848 <para>pktgen TX, RX in packets per second (pps) and Mbps</para>
849 </listitem>
850
851 <listitem>
852 <para>testpmd TX, RX in packets per second (pps)</para>
853 </listitem>
854
855 <listitem>
856 <para>divide <emphasis role="bold">testpmd RX</emphasis> by
857 <emphasis role="bold">pktgen TX</emphasis> in pps to obtain the
858 throughput in percentages (%)</para>
859 </listitem>
860 </itemizedlist>
861
862 <section id="targetone-usecasefour">
863 <title>Test Setup for Target 1</title>
864
865 <para>Start with the steps below:</para>
866
867 <para>SSD boot using the following <literal>grub.cfg
868 </literal>entry: <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
869isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
870clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
871processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
872intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
873hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting></para>
874
875 <para>Kill unnecessary services: <programlisting>killall ovsdb-server ovs-vswitchd
876rm -rf /etc/openvswitch/*
877mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge
878mount -t hugetlbfs nodev /mnt/huge
879modprobe igb_uio
880dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Run
881 pktgen:<programlisting>cd /usr/share/apps/pktgen/
882./pktgen -c 0x7 -n 4 --proc-type auto --socket-mem 256 /
883-w 0000:03:00.0 -- -P -m "[1:2].0"</programlisting>Set pktgen frame size to
884 use from [64, 128, 256, 512]:<programlisting>set 0 size 64</programlisting></para>
885 </section>
886
887 <section id="targettwo-usecasefive">
888 <title>Test Setup for Target 2</title>
889
890 <para>Start by following the steps below:</para>
891
892 <para>SSD boot using the following <literal>grub.cfg</literal>
893 entry: <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
894isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
895clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
896processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
897intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
898hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Kill
899 unnecessary services: <programlisting>killall ovsdb-server ovs-vswitchd
900rm -rf /etc/openvswitch/*
901mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge
902mount -t hugetlbfs nodev /mnt/huge
903modprobe igb_uio
904dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Configure
905 OVS:<programlisting>export DB_SOCK=/var/run/openvswitch/db.sock
906ovsdb-tool create /etc/openvswitch/conf.db /
907/usr/share/openvswitch/vswitch.ovsschema
908ovsdb-server --remote=punix:$DB_SOCK /
909--remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach
910ovs-vsctl --no-wait init
911ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10
912ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc
913ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048
914ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true
915ovs-vswitchd unix:$DB_SOCK --pidfile --detach /
916--log-file=/var/log/openvswitch/ovs-vswitchd.log
917
918ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev
919ovs-vsctl add-port ovsbr0 vhost-user1 /
920-- set Interface vhost-user1 type=dpdkvhostuser -- set Interface /
921vhost-user1 ofport_request=2
922ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface dpdk0 /
923type=dpdk options:dpdk-devargs=0000:03:00.0 /
924-- set Interface dpdk0 ofport_request=1
925chmod 777 /var/run/openvswitch/vhost-user1
926
927ovs-ofctl del-flows ovsbr0
928ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2
929ovs-ofctl add-flow ovsbr0 in_port=2,action=output:1</programlisting>Launch
930 QEMU:<programlisting>taskset -c 0,1 qemu-system-x86_64 -cpu host,+invtsc,migratable=no /
931-M q35 -smp cores=2,sockets=1 -vcpu 0,affinity=0 -vcpu 1,affinity=1 /
932-enable-kvm -nographic -realtime mlock=on -kernel /mnt/qemu/bzImage /
933-drive file=/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4,/
934if=virtio,format=raw -m 4096 -object memory-backend-file,id=mem,/
935size=4096M,mem-path=/mnt/huge,share=on -numa node,memdev=mem /
936-mem-prealloc -chardev socket,id=char0,path=/var/run/openvswitch/vhost-user1 /
937-netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce /
938-device virtio-net-pci,mac=52:54:00:00:00:01,netdev=mynet1,/
939mrg_rxbuf=on,rx_queue_size=1024,csum=off,gso=off,guest_tso4=off,/
940guest_tso6=off,guest_ecn=off -append 'root=/dev/vda console=ttyS0 /
941hugepagesz=2M hugepages=1024 isolcpus=1 nohz_full=1 rcu_nocbs=1 /
942irqaffinity=0 rcu_nocb_poll intel_pstate=disable intel_idle.max_cstate=0 /
943processor.max_cstate=0 mce=ignore_ce audit=0'</programlisting>Inside QEMU,
944 configure DPDK: <programlisting>mkdir -p /mnt/huge
945mount -t hugetlbfs nodev /mnt/huge
946modprobe igb_uio
947dpdk-devbind --bind=igb_uio 0000:00:02.0</programlisting>Inside QEMU, run
948 testpmd: <programlisting>testpmd -c 0x3 -n 2 -d librte_pmd_virtio.so.1.1 /
949-- --burst 64 --disable-hw-vlan --disable-rss -i --portmask=0x1 /
950--coremask=0x2 --nb-cores=1 --rxq=1 --txq=1 --txd=512 --rxd=512 /
951--txqflags=0xf00 --port-topology=chained</programlisting>For the <emphasis
952 role="bold">Forwarding test</emphasis>, start testpmd
953 directly:<programlisting>start</programlisting>For the <emphasis
954 role="bold">Termination test</emphasis>, set testpmd to only
955 receive, then start it:<programlisting>set fwd rxonly
956start</programlisting>On target 1, you may start pktgen traffic
957 now:<programlisting>start 0</programlisting>On target 2, use this
958 command to refresh the testpmd display and note the highest
959 values:<programlisting>show port stats 0</programlisting>To stop
960 traffic from pktgen, in order to choose a different frame
961 size:<programlisting>stop 0</programlisting>To clear numbers in
962 testpmd:<programlisting>clear port stats
963show port stats 0</programlisting><table>
964 <title>Results in forwarding mode</title>
965
966 <tgroup cols="8">
967 <tbody>
968 <row>
969 <entry align="center"><emphasis
970 role="bold">Bytes</emphasis></entry>
971
972 <entry align="center"><emphasis role="bold">pktgen pps
973 RX</emphasis></entry>
974
975 <entry align="center"><emphasis role="bold">pktgen pps
976 TX</emphasis></entry>
977
978 <entry align="center"><emphasis role="bold">testpmd pps
979 RX</emphasis></entry>
980
981 <entry align="center"><emphasis role="bold">testpmd pps
982 TX</emphasis></entry>
983
984 <entry align="center"><emphasis role="bold">pktgen MBits/s
985 RX</emphasis></entry>
986
987 <entry align="center"><emphasis role="bold">pktgen MBits/s
988 TX</emphasis></entry>
989
990 <entry align="center"><emphasis role="bold">throughput
991 (%)</emphasis></entry>
992 </row>
993
994 <row>
995 <entry role="bold"><emphasis
996 role="bold">64</emphasis></entry>
997
998 <entry>7926325</entry>
999
1000 <entry>14877576</entry>
1001
1002 <entry>7926515</entry>
1003
1004 <entry>7926515</entry>
1005
1006 <entry>5326</entry>
1007
1008 <entry>9997</entry>
1009
1010 <entry>53.2</entry>
1011 </row>
1012
1013 <row>
1014 <entry><emphasis role="bold">128</emphasis></entry>
1015
1016 <entry>7502802</entry>
1017
1018 <entry>8441253</entry>
1019
1020 <entry>7785983</entry>
1021
1022 <entry>7494959</entry>
1023
1024 <entry>8883</entry>
1025
1026 <entry>9994</entry>
1027
1028 <entry>88.8</entry>
1029 </row>
1030
1031 <row>
1032 <entry role="bold"><emphasis
1033 role="bold">256</emphasis></entry>
1034
1035 <entry>4528631</entry>
1036
1037 <entry>4528782</entry>
1038
1039 <entry>4529515</entry>
1040
1041 <entry>4529515</entry>
1042
1043 <entry>9999</entry>
1044
1045 <entry>9999</entry>
1046
1047 <entry>99.9</entry>
1048 </row>
1049 </tbody>
1050 </tgroup>
1051 </table><table>
1052 <title>Results in termination mode</title>
1053
1054 <tgroup cols="5">
1055 <tbody>
1056 <row>
1057 <entry align="center"><emphasis
1058 role="bold">Bytes</emphasis></entry>
1059
1060 <entry align="center"><emphasis role="bold">pktgen pps
1061 TX</emphasis></entry>
1062
1063 <entry align="center"><emphasis role="bold">testpmd pps
1064 RX</emphasis></entry>
1065
1066 <entry align="center"><emphasis role="bold">pktgen MBits/s
1067 TX</emphasis></entry>
1068
1069 <entry align="center"><emphasis role="bold">throughput
1070 (%)</emphasis></entry>
1071 </row>
1072
1073 <row>
1074 <entry role="bold"><emphasis
1075 role="bold">64</emphasis></entry>
1076
1077 <entry>14877764</entry>
1078
1079 <entry>8090855</entry>
1080
1081 <entry>9997</entry>
1082
1083 <entry>54.3</entry>
1084 </row>
1085
1086 <row>
1087 <entry><emphasis role="bold">128</emphasis></entry>
1088
1089 <entry>8441309</entry>
1090
1091 <entry>8082971</entry>
1092
1093 <entry>9994</entry>
1094
1095 <entry>95.7</entry>
1096 </row>
1097
1098 <row>
1099 <entry role="bold"><emphasis
1100 role="bold">256</emphasis></entry>
1101
1102 <entry>4528867</entry>
1103
1104 <entry>4528780</entry>
1105
1106 <entry>9999</entry>
1107
1108 <entry>99.9</entry>
1109 </row>
1110 </tbody>
1111 </tgroup>
1112 </table></para>
1113 </section>
1114 </section>
1115
1116 <section id="usecase-six">
1117 <title>Forward traffic between two VMs</title>
1118
1119 <para>Benchmark a combo test using two virtual machines, the first
1120 with traffic forwarding to the second, which terminates it.</para>
1121
1122 <para>Measurements are made in:</para>
1123
1124 <itemizedlist>
1125 <listitem>
1126 <para>pktgen TX in pps and Mbits/s</para>
1127 </listitem>
1128
1129 <listitem>
1130 <para>testpmd TX and RX pps in VM1</para>
1131 </listitem>
1132
1133 <listitem>
1134 <para>testpmd RX pps in VM2</para>
1135 </listitem>
1136
1137 <listitem>
1138 <para>throughput in percents, by dividing<emphasis role="bold">
1139 VM2 testpmd RX pps</emphasis> by <emphasis role="bold">pktgen TX
1140 pps</emphasis></para>
1141 </listitem>
1142 </itemizedlist>
1143
1144 <section id="targetone-usecase-five">
1145 <title>Test Setup for Target 1</title>
1146
1147 <para>Start by doing the following:</para>
1148
1149 <para>SSD boot using the following <literal>grub.cfg</literal>
1150 entry: <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
1151isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
1152clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
1153processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
1154intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
1155hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Kill
1156 Services:<programlisting>killall ovsdb-server ovs-vswitchd
1157rm -rf /etc/openvswitch/*
1158mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge
1159mount -t hugetlbfs nodev /mnt/huge
1160modprobe igb_uio
1161dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Run
1162 pktgen:<programlisting>cd /usr/share/apps/pktgen/
1163./pktgen -c 0x7 -n 4 --proc-type auto --socket-mem 256 /
1164-w 0000:03:00.0 -- -P -m "[1:2].0"</programlisting>Set pktgen frame size to
1165 use from [64, 128, 256, 512]:<programlisting>set 0 size 64</programlisting></para>
1166 </section>
1167
1168 <section id="targettwo-usecase-six">
1169 <title>Test Setup for Target 2</title>
1170
1171 <para>Start by doing the following:</para>
1172
1173 <para>SSD boot using the following <literal>grub.cfg</literal>
1174 entry: <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
1175isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
1176clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
1177processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
1178intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
1179hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Kill
1180 Services:<programlisting>killall ovsdb-server ovs-vswitchd
1181rm -rf /etc/openvswitch/*
1182mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge
1183mount -t hugetlbfs nodev /mnt/huge
1184modprobe igb_uio
1185dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Configure
1186 OVS:<programlisting>export DB_SOCK=/var/run/openvswitch/db.sock
1187ovsdb-tool create /etc/openvswitch/conf.db /
1188/usr/share/openvswitch/vswitch.ovsschema
1189ovsdb-server --remote=punix:$DB_SOCK /
1190--remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach
1191ovs-vsctl --no-wait init
1192ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10
1193ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc
1194ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048
1195ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true
1196ovs-vswitchd unix:$DB_SOCK --pidfile /
1197--detach --log-file=/var/log/openvswitch/ovs-vswitchd.log
1198
1199
1200ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev
1201ovs-vsctl add-port ovsbr0 dpdk0 /
1202-- set Interface dpdk0 type=dpdk options:dpdk-devargs=0000:03:00.0 ofport_request=1
1203ovs-vsctl add-port ovsbr0 vhost-user1 /
1204-- set Interface vhost-user1 type=dpdkvhostuser ofport_request=2
1205ovs-vsctl add-port ovsbr0 vhost-user2 /
1206-- set Interface vhost-user2 type=dpdkvhostuser ofport_request=3
1207
1208
1209ovs-ofctl del-flows ovsbr0
1210ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2
1211ovs-ofctl add-flow ovsbr0 in_port=2,action=output:3</programlisting>Launch
1212 first QEMU instance, VM1:<programlisting>taskset -c 0,1 qemu-system-x86_64 -cpu host,+invtsc,migratable=no -M q35 /
1213-smp cores=2,sockets=1 -vcpu 0,affinity=0 -vcpu 1,affinity=1 -enable-kvm /
1214-nographic -realtime mlock=on -kernel /home/root/qemu/bzImage /
1215-drive file=/home/root/qemu/enea-nfv-access-guest-qemux86-64.ext4,/
1216if=virtio,format=raw -m 2048 -object memory-backend-file,id=mem,/
1217size=2048M,mem-path=/mnt/huge,share=on -numa node,memdev=mem /
1218-mem-prealloc -chardev socket,id=char0,path=/var/run/openvswitch/vhost-user1 /
1219-netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce /
1220-device virtio-net-pci,mac=52:54:00:00:00:01,netdev=mynet1,/
1221mrg_rxbuf=on,rx_queue_size=1024,csum=off,gso=off,guest_tso4=off,/
1222guest_tso6=off,guest_ecn=off -append 'root=/dev/vda console=ttyS0 /
1223hugepagesz=2M hugepages=512 isolcpus=1 nohz_full=1 rcu_nocbs=1 /
1224irqaffinity=0 rcu_nocb_poll intel_pstate=disable intel_idle.max_cstate=0 /
1225processor.max_cstate=0 mce=ignore_ce audit=0'</programlisting>Connect to
1226 Target 2 through a new SSH session and run a second QEMU instance
1227 (to get its own console, separate from instance VM1). We shall call
1228 this VM2:<programlisting>taskset -c 4,5 qemu-system-x86_64 -cpu host,+invtsc,migratable=no /
1229-M q35 -smp cores=2,sockets=1 -vcpu 0,affinity=4 -vcpu 1,affinity=5 /
1230-enable-kvm -nographic -realtime mlock=on -kernel /home/root/qemu2/bzImage /
1231-drive file=/home/root/qemu2/enea-nfv-access-guest-qemux86-64.ext4,/
1232if=virtio,format=raw -m 2048 -object memory-backend-file,id=mem,size=2048M,/
1233mem-path=/mnt/huge,share=on -numa node,memdev=mem -mem-prealloc /
1234-chardev socket,id=char1,path=/var/run/openvswitch/vhost-user2 /
1235-netdev type=vhost-user,id=mynet1,chardev=char1,vhostforce /
1236-device virtio-net-pci,mac=52:54:00:00:00:02,netdev=mynet1,/
1237mrg_rxbuf=on,rx_queue_size=1024,csum=off,gso=off,guest_tso4=off,/
1238guest_tso6=off,guest_ecn=off -append 'root=/dev/vda console=ttyS0 /
1239hugepagesz=2M hugepages=512 isolcpus=1 nohz_full=1 rcu_nocbs=1 /
1240irqaffinity=0 rcu_nocb_poll intel_pstate=disable intel_idle.max_cstate=0 /
1241processor.max_cstate=0 mce=ignore_ce audit=0'</programlisting>Configure DPDK
1242 inside VM1:<programlisting>mkdir -p /mnt/huge
1243mount -t hugetlbfs nodev /mnt/huge
1244modprobe igb_uio
1245dpdk-devbind --bind=igb_uio 0000:00:02.0</programlisting>Run testpmd inside
1246 VM1:<programlisting>testpmd -c 0x3 -n 2 -d librte_pmd_virtio.so.1.1 /
1247-- --burst 64 --disable-hw-vlan --disable-rss -i /
1248--portmask=0x1 --coremask=0x2 --nb-cores=1 --rxq=1 /
1249--txq=1 --txd=512 --rxd=512 --txqflags=0xf00 --port-topology=chained</programlisting>Start
1250 testpmd inside VM1:<programlisting>start</programlisting>Configure
1251 DPDK inside VM2:<programlisting>mkdir -p /mnt/huge
1252mount -t hugetlbfs nodev /mnt/huge
1253modprobe igb_uio
1254dpdk-devbind --bind=igb_uio 0000:00:02.0</programlisting>Run testpmd inside
1255 VM2:<programlisting>testpmd -c 0x3 -n 2 -d librte_pmd_virtio.so.1.1 /
1256-- --burst 64 --disable-hw-vlan --disable-rss -i --portmask=0x1 /
1257--coremask=0x2 --nb-cores=1 --rxq=1 --txq=1 --txd=512 /
1258--rxd=512 --txqflags=0xf00 --port-topology=chained</programlisting>Set VM2 for
1259 termination and start testpmd:<programlisting>set fwd rxonly
1260start</programlisting>On target 1, start pktgen traffic:<programlisting>start 0</programlisting>Use
1261 this command to refresh testpmd display in VM1 and VM2 and note the
1262 highest values:<programlisting>show port stats 0</programlisting>To
1263 stop traffic from pktgen, in order to choose a different frame
1264 size:<programlisting>stop 0</programlisting>To clear numbers in
1265 testpmd:<programlisting>clear port stats
1266show port stats 0</programlisting>For VM1, we record the stats relevant for
1267 <emphasis role="bold">forwarding</emphasis>:</para>
1268
1269 <itemizedlist>
1270 <listitem>
1271 <para>RX, TX in pps</para>
1272 </listitem>
1273 </itemizedlist>
1274
1275 <para>Only Rx-pps and Tx-pps numbers are important here, they change
1276 every time stats are displayed as long as there is traffic. Run the
1277 command a few times and pick the best (maximum) values seen.</para>
1278
1279 <para>For VM2, we record the stats relevant for <emphasis
1280 role="bold">termination</emphasis>:</para>
1281
1282 <itemizedlist>
1283 <listitem>
1284 <para>RX in pps (TX will be 0)</para>
1285 </listitem>
1286 </itemizedlist>
1287
1288 <para>For pktgen, we record only the TX side, because flow is
1289 terminated, with no RX traffic reaching pktgen:</para>
1290
1291 <itemizedlist>
1292 <listitem>
1293 <para>TX in pps and Mbit/s</para>
1294 </listitem>
1295 </itemizedlist>
1296
1297 <table>
1298 <title>Results in forwarding mode</title>
1299
1300 <tgroup cols="7">
1301 <tbody>
1302 <row>
1303 <entry align="center"><emphasis
1304 role="bold">Bytes</emphasis></entry>
1305
1306 <entry align="center"><emphasis role="bold">pktgen pps
1307 TX</emphasis></entry>
1308
1309 <entry align="center"><emphasis role="bold">VM1 testpmd pps
1310 RX</emphasis></entry>
1311
1312 <entry align="center"><emphasis role="bold">VM1 testpmd pps
1313 TX</emphasis></entry>
1314
1315 <entry align="center"><emphasis role="bold">VM2 testpmd pps
1316 RX</emphasis></entry>
1317
1318 <entry align="center"><emphasis role="bold">pktgen MBits/s
1319 TX</emphasis></entry>
1320
1321 <entry align="center"><emphasis role="bold">throughput
1322 (%)</emphasis></entry>
1323 </row>
1324
1325 <row>
1326 <entry role="bold"><emphasis
1327 role="bold">64</emphasis></entry>
1328
1329 <entry>14877757</entry>
1330
1331 <entry>7712835</entry>
1332
1333 <entry>6024320</entry>
1334
1335 <entry>6015525</entry>
1336
1337 <entry>9997</entry>
1338
1339 <entry>40.0</entry>
1340 </row>
1341
1342 <row>
1343 <entry><emphasis role="bold">128</emphasis></entry>
1344
1345 <entry>8441333</entry>
1346
1347 <entry>7257432</entry>
1348
1349 <entry>5717540</entry>
1350
1351 <entry>5716752</entry>
1352
1353 <entry>9994</entry>
1354
1355 <entry>67.7</entry>
1356 </row>
1357
1358 <row>
1359 <entry role="bold"><emphasis
1360 role="bold">256</emphasis></entry>
1361
1362 <entry>4528865</entry>
1363
1364 <entry>4528717</entry>
1365
1366 <entry>4528717</entry>
1367
1368 <entry>4528621</entry>
1369
1370 <entry>9999</entry>
1371
1372 <entry>99.9</entry>
1373 </row>
1374 </tbody>
1375 </tgroup>
1376 </table>
1377 </section>
1378 </section>
1379
1380 <section id="pxe-config-vm">
1381 <title>SR-IOV in Virtual Machines</title>
1382
1383 <para>PCI passthrough tests using pktgen and testpmd in virtual
1384 machines.</para>
1385
1386 <para>pktgen[DPDK]VM - PHY - VM[DPDK] testpmd.</para>
1387
1388 <para>Measurements:</para>
1389
1390 <itemizedlist>
1391 <listitem>
1392 <para>pktgen to testpmd in <emphasis
1393 role="bold">forwarding</emphasis> mode.</para>
1394 </listitem>
1395
1396 <listitem>
1397 <para>pktgen to testpmd in <emphasis
1398 role="bold">termination</emphasis> mode.</para>
1399 </listitem>
1400 </itemizedlist>
1401
1402 <section id="test-setup-target-four">
1403 <title>Test Setup</title>
1404
1405 <para>SSD boot using the following <literal>grub.cfg</literal>
1406 entry: <programlisting>linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp nohz_full=1-7 /
1407isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable /
1408clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 /
1409processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt /
1410intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB /
1411hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Stop
1412 other services and mount hugepages: <programlisting>systemctl stop openvswitch
1413mkdir -p /mnt/huge
1414mount -t hugetlbfs hugetlbfs /mnt/huge</programlisting>Configure SR-IOV
1415 interfaces:<programlisting>/usr/share/usertools/dpdk-devbind.py --bind=ixgbe 0000:03:00.0
1416echo 2 &gt; /sys/class/net/eno3/device/sriov_numvfs
1417ifconfig eno3 10.0.0.1
1418modprobe vfio_pci
1419/usr/share/usertools/dpdk-devbind.py --bind=vfio-pci 0000:03:10.0
1420/usr/share/usertools/dpdk-devbind.py --bind=vfio-pci 0000:03:10.2
1421ip link set eno3 vf 0 mac 0c:c4:7a:E5:0F:48
1422ip link set eno3 vf 1 mac 0c:c4:7a:BF:52:E7</programlisting>Launch two QEMU
1423 instances: <programlisting>taskset -c 4,5 qemu-system-x86_64 -cpu host,+invtsc,migratable=no -M /
1424q35 -smp cores=2,sockets=1 -vcpu 0,affinity=4 -vcpu 1,affinity=5 -enable-kvm /
1425-nographic -kernel /mnt/qemu/bzImage /
1426-drive file=/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4,if=virtio,/
1427format=raw -m 4096 -object memory-backend-file,id=mem,size=4096M,mem-path=/mnt/huge,/
1428share=on -numa node,memdev=mem -mem-prealloc -device vfio-pci,host=03:10.0 /
1429-append 'root=/dev/vda console=ttyS0 hugepagesz=2M hugepages=1024 /
1430isolcpus=1 nohz_full=1 rcu_nocbs=1 irqaffinity=0 rcu_nocb_poll /
1431intel_pstate=disable intel_idle.max_cstate=0 /
1432processor.max_cstate=0 mce=ignore_ce audit=0'
1433
1434
1435taskset -c 2,3 qemu-system-x86_64 -cpu host,+invtsc,migratable=no -M /
1436q35 -smp cores=2,sockets=1 -vcpu 0,affinity=2 -vcpu 1,affinity=3 -enable-kvm /
1437-nographic -kernel /mnt/qemu/bzImage /
1438-drive file=/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4,if=virtio,/
1439format=raw -m 4096 -object memory-backend-file,id=mem,size=4096M,mem-path=/mnt/huge,/
1440share=on -numa node,memdev=mem -mem-prealloc -device vfio-pci,host=03:10.2 /
1441-append 'root=/dev/vda console=ttyS0 hugepagesz=2M hugepages=1024 /
1442isolcpus=1 nohz_full=1 rcu_nocbs=1 irqaffinity=0 rcu_nocb_poll /
1443intel_pstate=disable intel_idle.max_cstate=0 processor.max_cstate=0 /
1444mce=ignore_ce audit=0'</programlisting>In the first VM, mount hugepages and
1445 start pktgen:<programlisting>mkdir -p /mnt/huge &amp;&amp; \
1446mount -t hugetlbfs hugetlbfs /mnt/huge
1447modprobe igb_uio
1448/usr/share/usertools/dpdk-devbind.py --bind=igb_uio 0000:00:03.0
1449cd /usr/share/apps/pktgen
1450./pktgen -c 0x3 -- -P -m "1.0"</programlisting>In the pktgen console set the
1451 MAC of the destination and start generating
1452 packages:<programlisting>set mac 0 0C:C4:7A:BF:52:E7
1453str</programlisting>In the second VM, mount hugepages and start
1454 testpmd:<programlisting>mkdir -p /mnt/huge &amp;&amp; \
1455mount -t hugetlbfs hugetlbfs /mnt/huge
1456modprobe igb_uio
1457/usr/share/usertools/dpdk-devbind.py --bind=igb_uio 0000:00:03.0
1458testpmd -c 0x3 -n 2 -- -i --txd=512 --rxd=512 --port-topology=chained /
1459--eth-peer=0,0c:c4:7a:e5:0f:48</programlisting>In order to enable <emphasis
1460 role="bold">forwarding</emphasis> mode, in the testpmd console,
1461 run:<programlisting>set fwd mac
1462start</programlisting>In order to enable <emphasis
1463 role="bold">termination</emphasis> mode, in the testpmd console,
1464 run:<programlisting>set fwd rxonly
1465start</programlisting><table>
1466 <title>Results in forwarding mode</title>
1467
1468 <tgroup cols="5">
1469 <tbody>
1470 <row>
1471 <entry align="center"><emphasis
1472 role="bold">Bytes</emphasis></entry>
1473
1474 <entry align="center"><emphasis role="bold">VM1 pktgen pps
1475 TX</emphasis></entry>
1476
1477 <entry align="center"><emphasis role="bold">VM1 pktgen pps
1478 RX</emphasis></entry>
1479
1480 <entry align="center"><emphasis role="bold">VM2 testpmd
1481 pps RX</emphasis></entry>
1482
1483 <entry align="center"><emphasis role="bold">VM2 testpmd
1484 pps TX</emphasis></entry>
1485 </row>
1486
1487 <row>
1488 <entry role="bold"><emphasis
1489 role="bold">64</emphasis></entry>
1490
1491 <entry>7102096</entry>
1492
1493 <entry>7101897</entry>
1494
1495 <entry>7103853</entry>
1496
1497 <entry>7103793</entry>
1498 </row>
1499
1500 <row>
1501 <entry><emphasis role="bold">128</emphasis></entry>
1502
1503 <entry>5720016</entry>
1504
1505 <entry>5720256</entry>
1506
1507 <entry>5722081</entry>
1508
1509 <entry>5722083</entry>
1510 </row>
1511
1512 <row>
1513 <entry role="bold"><emphasis
1514 role="bold">256</emphasis></entry>
1515
1516 <entry>3456619</entry>
1517
1518 <entry>3456164</entry>
1519
1520 <entry>3456319</entry>
1521
1522 <entry>3456321</entry>
1523 </row>
1524
1525 <row>
1526 <entry role="bold"><emphasis
1527 role="bold">512</emphasis></entry>
1528
1529 <entry>1846671</entry>
1530
1531 <entry>1846628</entry>
1532
1533 <entry>1846652</entry>
1534
1535 <entry>1846657</entry>
1536 </row>
1537
1538 <row>
1539 <entry role="bold"><emphasis
1540 role="bold">1024</emphasis></entry>
1541
1542 <entry>940799</entry>
1543
1544 <entry>940748</entry>
1545
1546 <entry>940788</entry>
1547
1548 <entry>940788</entry>
1549 </row>
1550
1551 <row>
1552 <entry role="bold"><emphasis
1553 role="bold">1500</emphasis></entry>
1554
1555 <entry>649594</entry>
1556
1557 <entry>649526</entry>
1558
1559 <entry>649563</entry>
1560
1561 <entry>649563</entry>
1562 </row>
1563 </tbody>
1564 </tgroup>
1565 </table><table>
1566 <title>Results in termination mode</title>
1567
1568 <tgroup cols="3">
1569 <tbody>
1570 <row>
1571 <entry align="center"><emphasis
1572 role="bold">Bytes</emphasis></entry>
1573
1574 <entry align="center"><emphasis role="bold">VM1 pktgen pps
1575 TX</emphasis></entry>
1576
1577 <entry align="center"><emphasis role="bold">VM2 testpmd
1578 RX</emphasis></entry>
1579 </row>
1580
1581 <row>
1582 <entry role="bold"><emphasis
1583 role="bold">64</emphasis></entry>
1584
1585 <entry>14202904</entry>
1586
1587 <entry>14203944</entry>
1588 </row>
1589
1590 <row>
1591 <entry><emphasis role="bold">128</emphasis></entry>
1592
1593 <entry>8434766</entry>
1594
1595 <entry>8437525</entry>
1596 </row>
1597
1598 <row>
1599 <entry role="bold"><emphasis
1600 role="bold">256</emphasis></entry>
1601
1602 <entry>4532131</entry>
1603
1604 <entry>4532348</entry>
1605 </row>
1606
1607 <row>
1608 <entry><emphasis role="bold">512</emphasis></entry>
1609
1610 <entry>2349344</entry>
1611
1612 <entry>2349032</entry>
1613 </row>
1614
1615 <row>
1616 <entry><emphasis role="bold">1024</emphasis></entry>
1617
1618 <entry>1197293</entry>
1619
1620 <entry>1196699</entry>
1621 </row>
1622
1623 <row>
1624 <entry><emphasis role="bold">1500</emphasis></entry>
1625
1626 <entry>822321</entry>
1627
1628 <entry>822276</entry>
1629 </row>
1630 </tbody>
1631 </tgroup>
1632 </table></para>
1633 </section>
1634 </section>
1635 </section>
1636 </section>
1637</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/book.xml b/doc/book-enea-nfv-access-guide-intel/doc/book.xml
new file mode 100644
index 0000000..ca2f31c
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/book.xml
@@ -0,0 +1,30 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4<!ENTITY % local.common.attrib "xml:base CDATA #IMPLIED">
5]>
6<book id="book_enea_nfv_access_guide">
7 <title><trademark class="registered">Enea</trademark> NFV Access Guide</title>
8 <subtitle>Release Version
9 <xi:include href="eltf_params_updated.xml" xpointer="element(EneaLinux_REL_VER/1)"
10 xmlns:xi="http://www.w3.org/2001/XInclude" /></subtitle>
11 <!-- OLINKDBPATH_USED_BY_XMLMIND ../../s_docbuild/olinkdb -->
12 <xi:include href="../../s_docbuild/template/docsrc_common/bookinfo_userdoc.xml"
13 xmlns:xi="http://www.w3.org/2001/XInclude" />
14 <xi:include href="overview.xml"
15 xmlns:xi="http://www.w3.org/2001/XInclude" />
16 <xi:include href="getting_started.xml"
17 xmlns:xi="http://www.w3.org/2001/XInclude" />
18 <xi:include href="hypervisor_virtualization.xml"
19 xmlns:xi="http://www.w3.org/2001/XInclude" />
20 <xi:include href="container_virtualization.xml"
21 xmlns:xi="http://www.w3.org/2001/XInclude" />
22 <xi:include href="ovs.xml"
23 xmlns:xi="http://www.w3.org/2001/XInclude" />
24 <xi:include href="dpdk.xml"
25 xmlns:xi="http://www.w3.org/2001/XInclude" />
26 <xi:include href="benchmarks.xml"
27 xmlns:xi="http://www.w3.org/2001/XInclude" />
28 <xi:include href="using_nfv_access_sdks.xml"
29 xmlns:xi="http://www.w3.org/2001/XInclude" />
30</book>
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/container_virtualization.xml b/doc/book-enea-nfv-access-guide-intel/doc/container_virtualization.xml
new file mode 100644
index 0000000..2287146
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/container_virtualization.xml
@@ -0,0 +1,136 @@
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="container-virtualization">
5 <title>Container Virtualization</title>
6
7 <section id="docker">
8 <title>Docker</title>
9
10 <para>Docker is an open-source project that automates the deployment of
11 applications inside software containers, by providing an additional layer
12 of abstraction and automation of operating-system-level virtualization on
13 Linux.</para>
14
15 <para>The software container mechanism uses resource isolation features
16 inside the Linux kernel, such as cgroups and kernel namespaces to allow
17 multiple containers to run within a single Linux instance, avoiding the
18 overhead of starting and maintaining virtual machines.</para>
19
20 <para>Containers are lightweight and include everything needed to run
21 themselves: code, runtime, system tools, system libraries and settings.
22 The main advantage provided by containers is that the encapsulated
23 software is isolated from its surroundings. For example, differences
24 between development and staging environments can be kept separate in order
25 to reduce conflicts between teams running different software on the same
26 infrastructure.</para>
27
28 <para>For a better understanding of what Docker is and how it works, the
29 official documentation provided on the Docker website should be consulted:
30 <ulink
31 url="https://docs.docker.com/">https://docs.docker.com/</ulink>.</para>
32
33 <section id="launch-docker-container">
34 <title>Launching a Docker container</title>
35
36 <para>Docker provides a hello-world container which checks whether your
37 system is running the daemon correctly. This container can be launched
38 by simply running:</para>
39
40 <programlisting>docker run hello-world</programlisting>
41
42 <para>If your installation is working correctly, the following message
43 should be outputted:<programlisting>Hello from Docker!</programlisting></para>
44 </section>
45
46 <section id="run-enfv-guest-image">
47 <title>Run an Enea NFV Access guest image</title>
48
49 <para>Enea NFV Access guest images can run inside Docker as any other
50 container can. Before starting an Enea NFV Access guest image, a root
51 filesystem has to be imported in Docker:</para>
52
53 <programlisting>docker import enea-nfv-access-guest-qemux86-64.tar.gz el7guest</programlisting>
54
55 <para>To check that the Docker image has been imported successfully,
56 run:</para>
57
58 <programlisting>docker images</programlisting>
59
60 <para>Finally, start an Enea NFV Access container with
61 <literal>bash</literal> running as the shell, by running:</para>
62
63 <programlisting>docker run -it el7guest /bin/bash</programlisting>
64 </section>
65
66 <section id="attach-ext-resources-docker-containers">
67 <title>Attach external resources to Docker containers</title>
68
69 <para>Any system resource present on the host machine can be attached or
70 accessed by a Docker container.</para>
71
72 <para>Typically, if a file or folder on the host machine needs to be
73 attached to a container, that container should be launched with the
74 <literal>-v</literal> parameter. For example, to attach the
75 <literal>roots</literal> home folder to a container, the command line
76 for Docker should have the following format:</para>
77
78 <programlisting>docker run -it -v /home/root:/home/host_root/ el7guest /bin/bash</programlisting>
79
80 <para>To check that folders have been properly passed from the host to
81 the container, create a file in the source folder on the host root
82 filesystem and check for its existence inside the containers destination
83 location.</para>
84
85 <section id="attach-vhost-descriptors">
86 <title>Attach vhost file descriptors</title>
87
88 <para>If OVS is running on the host and vhost file descriptors need to
89 be passed to the container, this can be done by either mapping the
90 folder where all the file descriptors are located or mapping the file
91 descriptor itself:</para>
92
93 <itemizedlist>
94 <listitem>
95 <para>Mapping the folder can be done as exemplified above:</para>
96
97 <programlisting>docker run -it --rm -v /var/run/openvswitch/:/var/run/openvswitch/ el7guest /bin/bash</programlisting>
98 </listitem>
99
100 <listitem>
101 <para>Mapping a file descriptor is done in a similar way, but the
102 <literal>-v</literal> flag needs to point directly to it:</para>
103
104 <programlisting>docker run -it --rm -v /var/run/openvswitch/vhost-user1 el7guest /bin/bash</programlisting>
105 </listitem>
106 </itemizedlist>
107 </section>
108
109 <section id="attach-hugepages-mount-folders">
110 <title>Attach hugepages mount folders</title>
111
112 <para>Hugepages mount folders can also be accessed by a container
113 similarly to how a plain folder is mapped, as shown in 1.3.</para>
114
115 <para>For example, if the host system has hugepages mounted in the
116 <literal>/mnt/huge</literal> location, a container can also access
117 hugepages by being launched with:</para>
118
119 <programlisting>docker run -it -v /mnt/huge el7guest /bin/bash</programlisting>
120 </section>
121
122 <section id="access-pci-bus">
123 <title>Access the PCI bus</title>
124
125 <para>If the host machine has multiple SRIOV instances created, a
126 container can access the instances by being given privileged access to
127 the host system. Unlike folders, PCI devices do not have to be mounted
128 explicitly in order to be accessed and will be available to the
129 container if the <literal>--privileged</literal> flag is passed to the
130 command line:</para>
131
132 <programlisting>docker run --privileged -it el7guest /bin/bash</programlisting>
133 </section>
134 </section>
135 </section>
136</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/dpdk.xml b/doc/book-enea-nfv-access-guide-intel/doc/dpdk.xml
new file mode 100644
index 0000000..aa85317
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/dpdk.xml
@@ -0,0 +1,119 @@
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="dpdk">
5 <title>Data Plane Development Kit</title>
6
7 <para>The Intel Data Plane Development Kit (DPDK) is a set of user-space
8 libraries and drivers that provides a programming framework for high-speed
9 packet processing applications. The DPDK includes a number of Poll Mode
10 Drivers that enable direct packet transfer between the physical NIC and
11 user-space without using interrupts, bypassing the Linux kernel network
12 stack entirely.</para>
13
14 <para>In order to take advantage of DPDK, Linux <ulink
15 url="https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt">huge
16 pages</ulink> must be enabled in the system. The allocation of huge pages
17 should preferably be done at boot time by passing parameters on the kernel
18 command line. Add the following to the kernel boot parameters:</para>
19
20 <programlisting>default_hugepagesz=1GB hugepagesz=1GB hugepages=8 hugepagesz=2M hugepages=2048</programlisting>
21
22 <para>For DPDK documentation, see <ulink
23 url="http://dpdk.org/doc/guides-17.08/index.html">http://dpdk.org/doc/guides-17.08/index.html</ulink></para>
24
25 <section id="pktgen">
26 <title>Pktgen</title>
27
28 <para>In addition to DPDK, Enea NFV Access includes Pktgen, a
29 software traffic generator that is powered by the DPDK packet processing
30 framework. Pktgen can act as a transmitter or receiver and is capable of
31 generating 10Gbit wire rate traffic with 64 byte frames.</para>
32
33 <para>Pktgen is installed in <literal>/usr/share/apps/pktgen/</literal>
34 and needs to be executed from this directory.</para>
35
36 <para>For Pktgen documentation, see <ulink
37 url="http://pktgen-dpdk.readthedocs.io">http://pktgen-dpdk.readthedocs.io</ulink></para>
38 </section>
39
40 <section id="dpdk-setup">
41 <title>DPDK setup instructions</title>
42
43 <para>The following setup instructions apply to both host and
44 guest.</para>
45
46 <orderedlist>
47 <listitem>
48 <para>To make the hugepage memory available for DPDK, it must be
49 mounted:</para>
50
51 <programlisting>mkdir /mnt/huge
52mount -t hugetlbfs nodev /mnt/huge</programlisting>
53 </listitem>
54
55 <listitem>
56 <para>Load the DPDK igb_uio kernel module:</para>
57
58 <programlisting>modprobe igb_uio</programlisting>
59 </listitem>
60
61 <listitem>
62 <para>Bind the device to the igb_uio driver:</para>
63
64 <para><programlisting>dpdk-devbind --bind=igb_uio &lt;PCI device number&gt;</programlisting>The
65 DPDK provides the dpdk-devbind tool to help binding/unbinding devices
66 from specific drivers. See <ulink
67 url="http://dpdk.org/doc/guides-17.08/tools/devbind.html">http://dpdk.org/doc/guides-17.08/tools/devbind.html</ulink>
68 for more information.</para>
69 </listitem>
70 </orderedlist>
71
72 <para>To print the current status of all known network
73 interfaces:<programlisting>dpdk-devbind --status</programlisting></para>
74
75 <para>At this point the system is ready to run DPDK applications.</para>
76 </section>
77
78 <section id="dpdk-example-test-setup">
79 <title>DPDK example test setup</title>
80
81 <para>This is a simple DPDK test setup using two boards connected
82 back-to-back. One board generates traffic using the Pktgen application,
83 and the other board runs the DPDK testpmd example to forward packets back
84 on the same interface.</para>
85
86 <programlisting>Pktgen [DPDK] - Board 1 PHY &lt;--&gt; Board 2 PHY - [DPDK] testpmd</programlisting>
87
88 <orderedlist>
89 <listitem>
90 <para>Setup DPDK on both boards, following the instructions in
91 <xref linkend="dpdk-setup"/>.</para>
92 </listitem>
93
94 <listitem>
95 <para>On board 1, start the Pktgen application:</para>
96
97 <programlisting>cd /usr/share/apps/pktgen/
98./pktgen -c 0x7 -n 4 --socket-mem 1024 -- -P -m "[1:2].0"</programlisting>
99
100 <para>In the Pktgen console, run:</para>
101
102 <programlisting>start 0</programlisting>
103
104 <para>The Pktgen output will display the traffic configuration and
105 statistics.</para>
106 </listitem>
107
108 <listitem>
109 <para>On board 2, start the testpmd application:</para>
110
111 <programlisting>testpmd -c 0x7 -n 4 -- --txd=512 --rxd=512 --port-topology=chained</programlisting>
112
113 <para>For more information, refer to the testpmd application user
114 guide: <ulink
115 url="http://dpdk.org/doc/guides-17.08/testpmd_app_ug/index.html">http://dpdk.org/doc/guides-17.08/testpmd_app_ug/index.html</ulink>.</para>
116 </listitem>
117 </orderedlist>
118 </section>
119</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_template.xml b/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_template.xml
new file mode 100644
index 0000000..eaa7ebd
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_template.xml
@@ -0,0 +1,151 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<section id="eltf_created_params">
5 <title>File with Parameters in the Book Auto-updated by ELFT</title>
6
7 <note>
8 <para>See the <emphasis
9 role="bold">eltf_params_updated_template_howto_use.txt</emphasis> text
10 file for description of how to create the final <emphasis
11 role="bold">eltf_params_updated.xml</emphasis> from this template and for
12 all <emphasis role="bold">REQUIREMENTS</emphasis>. Use the command
13 "<emphasis role="bold">make eltf</emphasis>" to extract a full list of all
14 ELTF variables, which always begins with ELTF_ and don't only rely on the
15 howto text file list! The plan is that ELTF will auto-update this when
16 needed.</para>
17 </note>
18
19 <section id="host_prereq">
20 <title>Common Parameters</title>
21
22 <bridgehead>A programlisting, ID
23 "eltf-prereq-apt-get-commands-host"</bridgehead>
24
25 <para id="eltf-prereq-apt-get-commands-host"><programlisting>ELTF_PL_HOST_PREREQ</programlisting></para>
26
27 <bridgehead>A programlisting, ID
28 "eltf-getting-repo-install-command"</bridgehead>
29
30 <para id="eltf-getting-repo-install-command"><programlisting>ELTF_PL_GET_REPO</programlisting></para>
31
32 <bridgehead>Several phrase elements, various IDs. Ensure EL_REL_VER is
33 correct also compared to the "previous" REL VER in pardoc-distro.xml
34 "prev_baseline".</bridgehead>
35
36 <para id="EneaLinux_REL_VER"><phrase>ELTF_EL_REL_VER</phrase></para>
37
38 <para id="Yocto_VER"><phrase>ELTF_YOCTO_VER</phrase></para>
39
40 <para id="Yocto_NAME"><phrase>ELTF_YOCTO_NAME</phrase></para>
41
42 <para id="ULINK_YOCTO_PROJECT_DOWNLOAD"><ulink
43 url="ELTF_YOCTO_PROJ_DOWNLOAD_URL">ELTF_YOCTO_PROJ_DOWNLOAD_TXTURL</ulink></para>
44
45 <para id="ULINK_ENEA_LINUX_URL"><ulink
46 url="ELTF_EL_DOWNLOAD_URL">ELTF_EL_DOWNLOAD_TXTURL</ulink></para>
47
48 <bridgehead>A programlisting, ID "eltf-repo-cloning-enea-linux". Use
49 $MACHINE/default.xml as parameter, where MACHINE is one of the target
50 directory names in the manifest.</bridgehead>
51
52 <para id="eltf-repo-cloning-enea-linux"><programlisting>ELTF_PL_CLONE_W_REPO</programlisting></para>
53
54 <bridgehead>A table with ONE row, only the row with ID
55 "eltf-eclipse-version-row" is included in the book. MANUALLY BOTH in the
56 template.xml and in the updated.xml, set condition hidden on the
57 &lt;row&gt;, if eclipse is not in the release.</bridgehead>
58
59 <informaltable>
60 <tgroup cols="1">
61 <tbody>
62 <row id="eltf-eclipse-version-row">
63 <entry>Eclipse version ELTF_ECLIPSE_VERSION plus command line
64 development tools are included in this Enea NFV Access release.</entry>
65 </row>
66 </tbody>
67 </tgroup>
68 </informaltable>
69
70 <bridgehead>Below is one big section with title "Supported Targets with
71 Parameters". The entire section is included completely in the book via ID
72 "eltf-target-tables-section" and shall be LAST in the template. The
73 template contains ONE target subsection. COPY/APPEND it, if multiple
74 targets exist in the release and optionally add rows with additional
75 target parameters in each target subsection table.</bridgehead>
76 </section>
77
78 <section id="eltf-target-tables-section">
79 <title>Supported Targets with Parameters</title>
80
81 <para>The tables below describes the target(s) supported in this Enea
82 NFV Access release.</para>
83
84 <section id="eltf-target-table-ELTF_T_MANIFEST_DIR">
85 <title>MACHINE ELTF_T_MANIFEST_DIR - Information</title>
86
87 <para><informaltable>
88 <tgroup cols="2">
89 <colspec colwidth="6*" />
90
91 <colspec colwidth="9*" />
92
93 <tbody>
94 <row>
95 <entry>Target official name</entry>
96
97 <entry>ELTF_T_NAME</entry>
98 </row>
99
100 <row>
101 <entry>Architecture and Description</entry>
102
103 <entry>ELTF_T_ARC_DESC</entry>
104 </row>
105
106 <row>
107 <entry>Link to target datasheet</entry>
108
109 <entry>See <ulink
110 url="ELTF_T_DS_URL">ELTF_T_DS_TXTURL</ulink></entry>
111 </row>
112
113 <row>
114 <entry>Poky version</entry>
115
116 <entry>ELTF_T_POKY_VER</entry>
117 </row>
118
119 <row>
120 <entry>GCC version</entry>
121
122 <entry>ELTF_T_GCC_VER</entry>
123 </row>
124
125 <row>
126 <entry>Linux Kernel Version</entry>
127
128 <entry>ELTF_T_KERN_VER</entry>
129 </row>
130
131 <row>
132 <entry>Supported Drivers</entry>
133
134 <entry>ELTF_T_DRIVERS</entry>
135 </row>
136
137 <row>
138 <entry>Enea rpm folder for downloading RPM packages for this
139 target</entry>
140
141 <entry><ulink
142 url="ELTF_T_EL_RPM_URL">ELTF_T_EL_RPM_TXTURL</ulink></entry>
143 </row>
144 </tbody>
145 </tgroup>
146 </informaltable></para>
147 </section>
148
149 <!-- ELTFADD_MORE_TARGET_SECTIONS_BELOW_IF_NEEDED -->
150 </section>
151</section> \ No newline at end of file
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
new file mode 100644
index 0000000..1db30fd
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/eltf_params_updated.xml
@@ -0,0 +1,165 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<section id="eltf_created_params">
5 <title>File with Parameters in the Book Auto-updated by ELFT</title>
6
7 <note>
8 <para>See the <emphasis
9 role="bold">eltf_params_updated_template_howto_use.txt</emphasis> text
10 file for description of how to create the final <emphasis
11 role="bold">eltf_params_updated.xml</emphasis> from this template and for
12 all <emphasis role="bold">REQUIREMENTS</emphasis>. Use the command
13 "<emphasis role="bold">make eltf</emphasis>" to extract a full list of all
14 ELTF variables, which always begins with ELTF_ and don't only rely on the
15 howto text file list! The plan is that ELTF will auto-update this when
16 needed.</para>
17 </note>
18
19 <section id="host_prereq">
20 <title>Common Parameters</title>
21
22 <bridgehead>A programlisting, ID
23 "eltf-prereq-apt-get-commands-host"</bridgehead>
24
25 <para id="eltf-prereq-apt-get-commands-host"><programlisting># Host Ubuntu 14.04.5 LTS 64bit
26sudo apt-get -y update
27sudo apt-get -y install sed wget subversion git-core coreutils unzip texi2html \
28 texinfo libsdl1.2-dev docbook-utils fop gawk python-pysqlite2 diffstat \
29 make gcc build-essential xsltproc g++ desktop-file-utils chrpath \
30 libgl1-mesa-dev libglu1-mesa-dev autoconf automake groff libtool xterm \
31 libxml-parser-perl</programlisting></para>
32
33 <bridgehead>A programlisting, ID
34 "eltf-getting-repo-install-command"</bridgehead>
35
36 <para id="eltf-getting-repo-install-command"><programlisting>mkdir -p ~/bin
37curl https://storage.googleapis.com/git-repo-downloads/repo &gt; ~/bin/repo
38chmod a+x ~/bin/repo
39export PATH=~/bin:$PATH</programlisting></para>
40
41 <bridgehead>Several phrase elements, various IDs. Ensure EL_REL_VER is
42 correct also compared to the "previous" REL VER in pardoc-distro.xml
43 "prev_baseline".</bridgehead>
44
45 <para id="EneaLinux_REL_VER"><phrase>1.1</phrase></para>
46
47 <para id="Yocto_VER"><phrase>2.1</phrase></para>
48
49 <para id="Yocto_NAME"><phrase>krogoth</phrase></para>
50
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>
53
54 <para id="ULINK_ENEA_LINUX_URL"><ulink
55 url="https://linux.enea.com/6">https://linux.enea.com/6</ulink></para>
56
57 <bridgehead>A programlisting, ID "eltf-repo-cloning-enea-linux". Use
58 $MACHINE/default.xml as parameter, where MACHINE is one of the target
59 directory names in the manifest.</bridgehead>
60
61 <para id="eltf-repo-cloning-enea-linux"><programlisting>mkdir enea-linux
62cd enea-linux
63repo init -u git@git.enea.com:linux/manifests/el_manifests-virtualization.git \
64 -b refs/tags/EL6 -m $MACHINE/default.xml
65repo sync</programlisting></para>
66
67 <bridgehead>A table with ONE row, only the row with ID
68 "eltf-eclipse-version-row" is included in the book. MANUALLY in book, set
69 condition hidden if eclipse is not in the release. Do this both in
70 template.xml and updated.xml.</bridgehead>
71
72 <informaltable>
73 <tgroup cols="1">
74 <tbody>
75 <row condition="hidden" id="eltf-eclipse-version-row">
76 <entry>Eclipse version 4.3 (Mars) plus command line development
77 tools are included in this Enea NFV Access release.</entry>
78 </row>
79 </tbody>
80 </tgroup>
81 </informaltable>
82
83 <bridgehead>Below is one big section with title "Supported Targets with
84 Parameters". The entire section is included completely in the book via ID
85 "eltf-target-tables-section" and shall be LAST in the template. The
86 template contains ONE target subsection. COPY/APPEND it, if multiple
87 targets exist in the release and optionally add rows with additional
88 target parameters in each target subsection table.</bridgehead>
89 </section>
90
91 <section id="eltf-target-tables-section">
92 <title>Supported Reference Boards with Parameters</title>
93
94 <para>The tables below describes the target(s) supported in this Enea NFV
95 Access release.</para>
96
97 <section id="eltf-target-table-p2041rdb">
98 <title>MACHINE p2041rdb - Information</title>
99
100 <para><informaltable>
101 <tgroup cols="2">
102 <colspec colwidth="6*" />
103
104 <colspec colwidth="9*" />
105
106 <tbody>
107 <row>
108 <entry>Target official name</entry>
109
110 <entry>P2041RDB</entry>
111 </row>
112
113 <row>
114 <entry>Architecture and Description</entry>
115
116 <entry>Power, e500mc</entry>
117 </row>
118
119 <row>
120 <entry>Link to target datasheet</entry>
121
122 <entry>See <ulink
123 url="http://www.nxp.com/products/microcontrollers-and-processors/power-architecture-processors/qoriq-power-architecture-processors/p2041-qoriq-reference-design-board:RDP2041BOARD">link
124 to NXP's datasheet</ulink></entry>
125 </row>
126
127 <row>
128 <entry>Poky version</entry>
129
130 <entry>Git-commit-id:
131 75ca53211488a3e268037a44ee2a7ac5c7181bd2</entry>
132 </row>
133
134 <row>
135 <entry>GCC version</entry>
136
137 <entry>5.3</entry>
138 </row>
139
140 <row>
141 <entry>Linux Kernel Version</entry>
142
143 <entry>3.12</entry>
144 </row>
145
146 <row>
147 <entry>Supported Drivers</entry>
148
149 <entry>Ethernet, I2C, SPI, PCI Express, USB, Flash,
150 SD/SDHC/SDXC, RTC</entry>
151 </row>
152
153 <row>
154 <entry>Enea rpm folder for downloading RPM packages for this
155 target</entry>
156
157 <entry><ulink
158 url="https://linux.enea.com/6/p2041rgb/rpm">https://linux.enea.com/6/p2041rgb/rpm</ulink></entry>
159 </row>
160 </tbody>
161 </tgroup>
162 </informaltable></para>
163 </section>
164 </section>
165</section> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/getting_started.xml b/doc/book-enea-nfv-access-guide-intel/doc/getting_started.xml
new file mode 100644
index 0000000..dac3015
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/getting_started.xml
@@ -0,0 +1,639 @@
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="plat-release-content">
5 <title>Getting Started with Enea NFV Access</title>
6
7 <para>Using Enea NFV Access requires access to a Linux machine, which is
8 used for preparing a bootable drive or for developing applications. System
9 requirements for the development host are detailed in the <xi:include
10 href="../../s_docbuild/olinkdb/pardoc-common.xml"
11 xmlns:xi="http://www.w3.org/2001/XInclude"
12 xpointer="element(book_enea_nfv_access_release_info/1)" />.</para>
13
14 <section id="sysshell_config">
15 <title>Default Shell Configuration</title>
16
17 <para>Before installing Enea NFV Access, make sure that bash is the
18 default shell.</para>
19
20 <para><emphasis role="bold">To verify the default system
21 shell</emphasis></para>
22
23 <itemizedlist>
24 <listitem>
25 <para>If your system runs Ubuntu, use list to verify if
26 <filename>/usr/bin</filename> is a symbolic link to <emphasis
27 role="bold">bash</emphasis>:</para>
28
29 <programlisting># ls -l /bin/sh
30lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; bash</programlisting>
31 </listitem>
32
33 <listitem>
34 <para>Optionally, in case the link points to <literal>dash</literal>,
35 change it through the following steps:</para>
36
37 <programlisting># ls -l /bin/sh
38lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; dash
39# sudo dpkg-reconfigure dash
40Use dash as the default system shell (/bin/sh)? No</programlisting>
41 </listitem>
42 </itemizedlist>
43 </section>
44
45 <section id="access_installer">
46 <title>Enea NFV Access Installer</title>
47
48 <para>The easiest way to get started with Enea NFV Access is by using the
49 installer provided for each supported architecture in this release. Each
50 installer guides you in the creation of a bootable Enea NFV Access
51 installation on a physical media.</para>
52
53 <section id="prereq">
54 <title>Prerequisites</title>
55
56 <para>The following files are needed on the development host
57 machine:</para>
58
59 <itemizedlist>
60 <listitem>
61 <para>A GRUB.efi binary - available from the <ulink url="???">GNU
62 GRUB download page</ulink>.</para>
63 </listitem>
64
65 <listitem>
66 <para>For booting from an SSD/HDD: a rootfs that needs to be
67 installed on the board (e.g.
68 <filename>[path_to_EneaNFV_Access_folder]/[architecture]/inteld1521/images/enea-nfv-access/enea-nfv-access.tar.gz</filename>).</para>
69 </listitem>
70
71 <listitem>
72 <para>For USB booting: a development based rootfs (e.g.
73 <filename>[path_to_EneaNFV_Access_folder]/[architecture]/inteld1521/images/enea-nfv-access-dev/enea-nfv-access-dev-inteld1521.tar.gz</filename>).</para>
74 </listitem>
75 </itemizedlist>
76
77 <para>Using the installer on the development host requires the
78 following:</para>
79
80 <itemizedlist>
81 <listitem>
82 <para>A physical drive of 16GB or larger</para>
83 </listitem>
84
85 <listitem>
86 <para>Root permissions</para>
87 </listitem>
88 </itemizedlist>
89 </section>
90
91 <section id="installer_setup_usage">
92 <title>Installer Setup and Usage</title>
93
94 <para><emphasis role="bold">To install Enea NFV Access on a physical
95 drive</emphasis></para>
96
97 <orderedlist>
98 <listitem>
99 <para>Go to the installer location: <programlisting># cd [path_to_EneaNFV_Access_folder]/[architecture]/
100install/nfv-installer/script-installer</programlisting></para>
101 </listitem>
102
103 <listitem>
104 <para>Execute the script file, this will bring you to the installer
105 prompt: <programlisting># sudo ./nfv_installer.sh</programlisting></para>
106 </listitem>
107
108 <listitem>
109 <para>Optionally, press ENTER to see the list of available
110 commands:<programlisting>help - displays a guide on how to use the installer
111list-params - lists all available parameters
112list-steps - lists the installer steps and the parameters that they depend on
113set - sets a parameter (e.g. <literal>set drive=/dev/sda</literal>)
114clear - clears a parameter (e.g. <literal>clear drive</literal>)
115list-partitions - lists current drives and partitions
116dry - performs a simulation test run
117run - executes the installer, using the values you set for each parameter
118q or quit - exits the script</programlisting></para>
119 </listitem>
120
121 <listitem>
122 <para>Set the required parameters depending on what steps you want
123 to run:</para>
124
125 <note>
126 <para>When using the installer for the first time, make sure to
127 set ALL parameters in order to be able to run all steps. See <xref
128 linkend="example_two">
129 "Example 2"
130 </xref> for details.</para>
131 </note>
132
133 <para><programlisting># set &lt;parameter_name&gt;=&lt;parameter_value&gt;</programlisting></para>
134
135 <orderedlist>
136 <listitem>
137 <para><parameter>drive=&lt;/dev/sdaX&gt;</parameter> - the drive
138 to partition</para>
139 </listitem>
140
141 <listitem>
142 <para><parameter>grub_binary=&lt;file&gt;</parameter> - points
143 to the <filename>GRUB</filename> executable to be installed
144 where <filename>grub_destination</filename> is set.</para>
145 </listitem>
146
147 <listitem>
148 <para><parameter>grub_destination=&lt;drive&gt;</parameter> -
149 specifies the partition where <filename>GRUB</filename> will be
150 installed</para>
151 </listitem>
152
153 <listitem>
154 <para><parameter>rootfs_destination=&lt;drive&gt;</parameter> -
155 specifies the partition where the <filename>rootfs</filename>
156 will be deployed, used by <filename>GRUB</filename> to boot off
157 of.</para>
158 </listitem>
159
160 <listitem>
161 <para><parameter>rootfs_targz=&lt;rootfs.tar.gz
162 file&gt;</parameter> - the archive of the Enea NFV Access
163 <filename>rootfs</filename> you wish to unpack to where
164 <filename>rootfs_destination</filename> is set. Which file you
165 unpack depends on whether you booting from an SSD/HDD or from a
166 USB drive.</para>
167 </listitem>
168 </orderedlist>
169 </listitem>
170
171 <listitem>
172 <para>Optionally, perform a test run before affecting the actual
173 layout of the physical media with the command: <programlisting>dry</programlisting></para>
174 </listitem>
175
176 <listitem>
177 <para>Run the installer: <programlisting>run</programlisting></para>
178 </listitem>
179
180 <listitem>
181 <para>Exit the script: <programlisting>quit</programlisting></para>
182 </listitem>
183 </orderedlist>
184
185 <para>The Enea NFV Access installer creates a bootable media by
186 performing three steps. Each step is executed or not depending on
187 whether certain parameters are set:</para>
188
189 <orderedlist>
190 <listitem>
191 <para><command>Format drive</command> - creates a 512MB partition
192 which will be used by <filename>GRUB</filename>, and another to be
193 used for the <filename>rootfs</filename> (it should occupy the rest
194 of the physical media minus the first partition). This step depends
195 on the following parameter(s): <programlisting>drive=</programlisting></para>
196 </listitem>
197
198 <listitem>
199 <para><emphasis role="bold">GRUB install</emphasis> - Installs the
200 <literal>grub_binary</literal> on the drive set for
201 <literal>grub_destination</literal>. A <filename>grub.cfg</filename>
202 file will be created that will be configured to boot off of
203 <literal>rootfs_destination</literal>. This step depends on the
204 following parameters:<programlisting>grub_destination=
205grub_binary=
206rootfs_destination=</programlisting></para>
207 </listitem>
208
209 <listitem>
210 <para><emphasis role="bold">Root Filesystem install</emphasis> -
211 Copies and unpacks the files found in
212 <literal>rootfs_targz</literal> to the
213 <literal>rootfs_destination</literal>. This step depends on the
214 following parameters:<programlisting>rootfs_targz=
215rootfs_destination=</programlisting></para>
216 </listitem>
217 </orderedlist>
218
219 <para>After using the installer and setting up the bootable media,
220 connect it to the target machine and configure the target machine to use
221 it as a primary boot device.</para>
222 </section>
223
224 <section id="examples">
225 <title>Examples of Execution</title>
226
227 <para>Below are a few examples of setups that the Enea NFV Access
228 installer can be used for:</para>
229
230 <example id="example_one">
231 <title>Partitioning a drive</title>
232
233 <programlisting>set drive=/dev/sda
234run</programlisting>
235 </example>
236
237 <example id="example_two">
238 <title>Partitioning a drive, installing GRUB and a Root
239 Filesystem:</title>
240
241 <programlisting>set drive=/dev/sda
242set grub_destination=/dev/sda1
243set grub_binary=/home/user/grub-binary.efi
244set rootfs_destination=/dev/sda2
245set rootfs_targz=/home/user/rootfs.tar.gz
246run</programlisting>
247 </example>
248
249 <example id="example_three">
250 <title>Deploying ONLY a root filesystem:</title>
251
252 <programlisting>set rootfs_destination=/dev/sda2
253set rootfs_targz=/home/user/rootfs.tar.gz
254run</programlisting>
255 </example>
256 </section>
257
258 <section id="troubleshooting">
259 <title>Troubleshooting</title>
260
261 <para>GRUB might display the following errors if the default
262 configuration is set to use <filename>hd0</filename> as the primary
263 drive for booting:</para>
264
265 <itemizedlist>
266 <listitem>
267 <para><literal>error: no such partition</literal></para>
268 </listitem>
269
270 <listitem>
271 <para><literal>error: disk not found</literal></para>
272 </listitem>
273 </itemizedlist>
274
275 <para>These errors have two possible causes:</para>
276
277 <itemizedlist>
278 <listitem>
279 <para>The drive where Enea NFV Access was installed is not
280 identified as <literal>hd0</literal> by BIOS.</para>
281 </listitem>
282
283 <listitem>
284 <para>BIOS has assigned the <literal>hd0</literal> label to a
285 different drive (e.g. a USB stick) than the one where Enea NFV
286 Access was installed.</para>
287 </listitem>
288 </itemizedlist>
289
290 <para>To rectify these problems the primary boot drive must be assigned
291 to the correct partition.</para>
292
293 <para><emphasis role="bold">To change the partition for the primary boot
294 drive</emphasis></para>
295
296 <orderedlist>
297 <listitem>
298 <para>Restart the host and in the <filename>GRUB</filename>
299 selection screen, enter the command line by pressing
300 <command>C</command>:</para>
301
302 <mediaobject>
303 <imageobject>
304 <imagedata align="center" contentwidth="600"
305 fileref="images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg" />
306 </imageobject>
307 </mediaobject>
308 </listitem>
309
310 <listitem>
311 <para>List all of the available partitions with
312 <command>ls</command>: <programlisting>partition list example</programlisting></para>
313 </listitem>
314
315 <listitem>
316 <para>In order to identify where Enea NFV Access was installed, for
317 each available partition run <emphasis role="bold">ls
318 &lt;partition&gt;</emphasis>: <programlisting>ls hd0</programlisting></para>
319 </listitem>
320
321 <listitem>
322 <para>After identifying the partition, return to the GRUB selection
323 screen by pressing <command>esc</command></para>
324 </listitem>
325
326 <listitem>
327 <para>Press <command>e</command> to edit and set the boot partition
328 to the one identified previously: <programlisting>edit and set partition example</programlisting></para>
329 </listitem>
330
331 <listitem>
332 <para>To reboot to see if the change worked, press:
333 <command>F10</command></para>
334 </listitem>
335 </orderedlist>
336 </section>
337 </section>
338
339 <section condition="hidden" id="release-content">
340 <title>NFV Access Release content</title>
341
342 <para>The NFV Access 1.1 Release contains along with other items,
343 documentation, pre-built kernels and images, a bootloader and a
344 SDK.</para>
345
346 <para>The directories structure is detailed below:</para>
347
348 <programlisting>-- documentation/
349 /* NFV Access documentation */
350-- inteld1521/
351 /* artifacts for the host side */
352 -- deb/
353 /* deb packages */
354 -- images/
355 -- enea-image-virtualization-host
356 /* precompiled artifacts for the Host release image */
357 -- various artifacts
358 -- enea-image-virtualization-host-sdk
359 /* precompiled artifacts for the Host SDK image.
360 The SDK image contains userspace tools and kernel
361 configurations necessary for developing, debugging
362 and profiling applications and kernel modules */
363 -- various artifacts
364 -- sdk
365 /* NFV Access SDK for the host */
366 -- enea-glibc-x86_64-enea-image-virtualization-host-sdk /
367 -corei7-64-toolchain-7.0.sh
368 /* self-extracting archive installing
369 cross-compilation toolchain for the host */
370-- qemux86-64
371 /* artifacts for the guest side */
372 -- deb/
373 /* deb packages */
374 -- images/
375 -- enea-image-virtualization-guest
376 /* precompiled artifacts for the Guest image */
377 -- various artifacts
378 -- sdk
379 /* NFV Access SDK for the guest */
380 -- enea-glibc-x86_64-enea-image-virtualization-guest-sdk /
381 -core2-64-toolchain-7.0.sh
382 /* self-extracting archive installing cross-compilation
383 toolchain for the guest (QEMU x86-64) */</programlisting>
384
385 <para>For each combination of image and target, the following set of
386 artifacts is available:</para>
387
388 <programlisting>-- bzImage
389 /* kernel image */
390-- bzImage-&lt;target&gt;.bin
391 /* kernel image, same as above */
392-- config-&lt;target&gt;.config
393 /* kernel configuration file */
394-- core-image-minimal-initramfs-&lt;target&gt;.cpio.gz
395 /* cpio archive of the initramfs */
396-- core-image-minimal-initramfs-&lt;target&gt;.qemuboot.conf
397 /* qemu config file for the initramfs image */
398-- &lt;image-name&gt;-&lt;target&gt;.ext4
399 /* EXT4 image of the rootfs */
400-- &lt;image-name&gt;-&lt;target&gt;.hddimg
401 /* msdos filesystem containing syslinux, kernel, initrd and rootfs image */
402-- &lt;image-name&gt;-&lt;target&gt;.iso
403 /* CD .iso image */
404-- &lt;image-name&gt;-&lt;target&gt;.qemuboot.conf
405 /* qemu config file for the image */
406-- &lt;image-name&gt;-&lt;target&gt;.tar.gz
407 /* tar archive of the image */
408-- &lt;image-name&gt;-&lt;target&gt;.wic
409 /* Wic image */
410-- microcode.cpio
411 /* kernel microcode data */
412-- modules-&lt;target&gt;.tgz
413 /* external kernel modules */
414-- ovmf.*.qcow2
415 /* ovmf firmware for uefi support in qemu */
416-- rmc.db
417 /* Central RMC Database */
418-- systemd-bootx64.efi
419 /* systemd-boot EFI file */
420-- grub-efi-bootx64.efi
421 /* GRUB EFI file */</programlisting>
422 </section>
423
424 <section condition="hidden" id="prebuilt-artifacts">
425 <title>How to use the Prebuilt Artifacts</title>
426
427 <section id="boot-ramdisk">
428 <title>Booting Enea NFV Access using RAMDISK</title>
429
430 <para>There may be use cases, especially at first target ramp-up, where
431 the HDD/SDD has no partitions and you need to prepare the disks for
432 boot. Booting from ramdisk can help with this task.</para>
433
434 <para>The prerequisites needed to proceed:</para>
435
436 <itemizedlist>
437 <listitem>
438 <para>Enea NFV Access ext4 rootfs image -
439 enea-nfv-access-inteld1521.ext4.gz</para>
440 </listitem>
441
442 <listitem>
443 <para>Enea NFV Access kernel image - bzImage</para>
444 </listitem>
445
446 <listitem>
447 <para>BIOS has PXE boot enabled</para>
448 </listitem>
449
450 <listitem>
451 <para>PXE/tftp server configured and connected (ethernet) to
452 target.</para>
453 </listitem>
454 </itemizedlist>
455
456 <para>Unzip enea-nfv-access-inteld1521.ext4 and copy bzImage and
457 enea-nfv-access-inteld1521.ext4 images to the tftpserver configured for
458 PXE boot.</para>
459
460 <para>Use the following as an example for the PXE configuration
461 file:</para>
462
463 <programlisting>default vesamenu.c32
464prompt 1
465timeout 0
466
467label el_ramfs
468 menu label ^EneaLinux_RAMfs
469 kernel bzImage
470 append root=/dev/ram0 initrd=enea-nfv-access-inteld1521.ext4 /
471 ramdisk_size=1200000 console=ttyS0,115200 eralyprintk=ttyS0,115200</programlisting>
472
473 <para>Restart the target. Then enter (F11) in the Boot Menu and select
474 the Ethernet interface used for PXE boot. From the PXE Boot Menu select
475 <emphasis role="bold">Enea NFV Access_RAMfs</emphasis>. Once the Enea
476 NFV Access is started you can partition the HDD/SDD and install GRUB as
477 described in in the following section.</para>
478 </section>
479
480 <section id="install-grub">
481 <title>Partitioning a new harddisk and installing GRUB</title>
482
483 <para>The prerequisites needed:</para>
484
485 <itemizedlist>
486 <listitem>
487 <para>grub (<literal>grub-efi-bootx64.efi</literal>) - availalble as
488 a pre-built artifact under
489 <literal>inteld1521/images/enea-nfv-access</literal>.</para>
490 </listitem>
491
492 <listitem>
493 <para><literal>e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb,/</literal></para>
494
495 <para><literal>dosfstools_4.1-r0.0_amd64.deb</literal> - available
496 under <literal>inteld1521/deb</literal>.</para>
497 </listitem>
498 </itemizedlist>
499
500 <para>Proceed using the following steps:</para>
501
502 <orderedlist>
503 <listitem>
504 <para>Boot target with Enea NFV Access from RAMDISK</para>
505 </listitem>
506
507 <listitem>
508 <para>Install prerequisite packages:</para>
509
510 <programlisting>&gt; dpkg -i e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb
511&gt; dpkg -i dosfstools_4.1-r0.0_amd64.deb</programlisting>
512 </listitem>
513
514 <listitem>
515 <para>Partition the disk:</para>
516
517 <programlisting>&gt; fdisk /dev/sda
518fdisk&gt; g {GPT partition type}
519fdisk&gt; n
520fdisk&gt; 1
521fdisk&gt; {default start part}
522fdisk&gt; +512M
523fdisk&gt; t
524fdisk&gt; 1 {ESP/EFI partition}
525fdisk&gt; n
526fdisk&gt; 2
527fdisk&gt; {default start part}
528fdisk&gt; +18G
529fdisk&gt; 3
530fdisk&gt; {default start part}
531fdisk&gt; +20G
532...
533fdisk&gt; 7
534fdisk&gt; {default start part}
535fdisk&gt; {default end end part}
536
537fdisk&gt; p {print partion table}
538fdisk&gt; w {write to disk}
539fdisk&gt; q</programlisting>
540 </listitem>
541
542 <listitem>
543 <para>Format the partitions:</para>
544
545 <programlisting>&gt; mkfs.fat -F32 -nEFI /dev/sda1
546&gt; mkfs.ext4 -LROOT /dev/sda2
547&gt; mkfs.ext4 -LROOT /dev/sda3
548&gt; mkfs.ext4 -LROOT /dev/sda4
549&gt; mkfs.ext4 -LROOT /dev/sda5
550&gt; mkfs.ext4 -LROOT /dev/sda6
551&gt; mkfs.ext4 -LROOT /dev/sda7</programlisting>
552 </listitem>
553
554 <listitem>
555 <para>Create a GRUB partition:</para>
556
557 <programlisting>&gt; mkdir /mnt/boot
558&gt; mount /dev/sda1 /mnt/boot
559&gt; mkdir -p /mnt/boot/EFI/boot
560
561&gt; cp grub-efi-bootx64.efi /mnt/boot/EFI/boot/bootx64.efi
562&gt; vi /mnt/boot/EFI/boot/grub.cfg
563default=1
564
565menuentry "Linux Reference Image" {
566 linux (hd0,gpt2)/boot/bzImage root=/dev/sda2 ip=dhcp
567}
568
569menuentry "Linux sda3" {
570 linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp
571}
572
573menuentry "Linux sda4" {
574 linux (hd0,gpt4)/boot/bzImage root=/dev/sda4 ip=dhcp
575}
576
577menuentry "Linux sda5" {
578 linux (hd0,gpt5)/boot/bzImage root=/dev/sda5 ip=dhcp
579}
580
581menuentry "Linux sda6" {
582 linux (hd0,gpt6)/boot/bzImage root=/dev/sda6 ip=dhcp
583}
584
585menuentry "Linux sda7" {
586 linux (hd0,gpt7)/boot/bzImage root=/dev/sda7 ip=dhcp
587}</programlisting>
588 </listitem>
589 </orderedlist>
590 </section>
591
592 <section id="boot-hdd">
593 <title>Installing and booting Enea NFV Access on the harddisk</title>
594
595 <para>After partitioning the harddisk, boot Enea NFV Access from RAMFS
596 or from a reference image installed on one of the partitions.</para>
597
598 <para>To install Enea NFV Access image on a partition follow these
599 steps:</para>
600
601 <orderedlist>
602 <listitem>
603 <para>Copy your image on target:</para>
604
605 <programlisting>server&gt; scp ./enea-nfv-access-inteld1521.tar.gz /
606root@&lt;target_ip&gt;:/home/root/</programlisting>
607 </listitem>
608
609 <listitem>
610 <para>Extract image onto the desired partition:</para>
611
612 <programlisting>target&gt; mount /dev/sda3 /mnt/sda
613target&gt; tar -pzxf /home/root/enea-nfv-access-inteld1521.tar.gz /
614-C /mnt/sda</programlisting>
615
616 <para>Alternately, you can do both steps in one command from the
617 server:</para>
618
619 <programlisting>server&gt; cat ./enea-nfv-access-inteld1521.tar.gz | /
620ssh root@&lt;target_ip&gt; "cd /mnt/sda6; tar -zxf -"</programlisting>
621 </listitem>
622
623 <listitem>
624 <para>Reboot</para>
625 </listitem>
626
627 <listitem>
628 <para>From the GRUB menu select your partition</para>
629 </listitem>
630 </orderedlist>
631
632 <note>
633 <para>In order to change kernel boot parameters you need to mount the
634 GRUB partition (i.e. <literal>/dev/sda1</literal>) and change the
635 <literal>EFI/boot/grub.cfg</literal> file.</para>
636 </note>
637 </section>
638 </section>
639</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/hypervisor_virtualization.xml b/doc/book-enea-nfv-access-guide-intel/doc/hypervisor_virtualization.xml
new file mode 100644
index 0000000..9733544
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/hypervisor_virtualization.xml
@@ -0,0 +1,744 @@
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="hypervisor_virt">
5 <title>Hypervisor Virtualization</title>
6
7 <para>The KVM, Kernel-based Virtual Machine, is a virtualization
8 infrastructure for the Linux kernel which turns it into a hypervisor. KVM
9 requires a processor with a hardware virtualization extension.</para>
10
11 <para>KVM uses QEMU, an open source machine emulator and virtualizer, to
12 virtualize a complete system. With KVM it is possible to run multiple guests
13 of a variety of operating systems, each with a complete set of virtualized
14 hardware.</para>
15
16 <section id="launch_virt_machine">
17 <title>Launching a Virtual Machine</title>
18
19 <para>QEMU can make use of KVM when running a target architecture that is
20 the same as the host architecture. For instance, when running
21 qemu-system-x86_64 on an x86-64 compatible processor (containing
22 virtualization extensions Intel VT or AMD-V), you can take advantage of
23 the KVM acceleration, giving you benefit for your host and your guest
24 system.</para>
25
26 <para>Enea NFV Access includes an optimizied version of QEMU with KVM-only
27 support. To use KVM pass<command> --enable-kvm</command> to QEMU.</para>
28
29 <para>The following is an example of starting a guest:</para>
30
31 <programlisting>taskset -c 0,1 qemu-system-x86_64 \
32-cpu host -M q35 -smp cores=2,sockets=1 \
33-vcpu 0,affinity=0 -vcpu 1,affinity=1 \
34-enable-kvm -nographic \
35-kernel bzImage \
36-drive file=enea-nfv-access-guest-qemux86-64.ext4,if=virtio,format=raw \
37-append 'root=/dev/vda console=ttyS0,115200' \
38-m 4096 \
39-object memory-backend-file,id=mem,size=4096M,mem-path=/dev/hugepages,share=on \
40-numa node,memdev=mem -mem-prealloc</programlisting>
41 </section>
42
43 <section id="qemu_boot">
44 <title>Main QEMU boot options</title>
45
46 <para>Below are detailed all the pertinent boot options for the QEMU
47 emulator:</para>
48
49 <itemizedlist>
50 <listitem>
51 <para>SMP - at least 2 cores should be enabled in order to isolate
52 application(s) running in virtual machine(s) on specific cores for
53 better performance.</para>
54
55 <programlisting>-smp cores=2,threads=1,sockets=1 \</programlisting>
56 </listitem>
57
58 <listitem>
59 <para>CPU affinity - associate virtual CPUs with physical CPUs and
60 optionally assign a default real time priority to the virtual CPU
61 process in the host kernel. This option allows you to start qemu vCPUs
62 on isolated physical CPUs.</para>
63
64 <programlisting>-vcpu 0,affinity=0 \</programlisting>
65 </listitem>
66
67 <listitem>
68 <para>Hugepages - KVM guests can be deployed with huge page memory
69 support in order to reduce memory consumption and improve performance,
70 by reducing CPU cache usage. By using huge pages for a KVM guest, less
71 memory is used for page tables and TLB (Translation Lookaside Buffer)
72 misses are reduced, thereby significantly increasing performance,
73 especially for memory-intensive situations.</para>
74
75 <programlisting>-object memory-backend-file,id=mem,size=4096M,mem-path=/dev/hugepages,share=on \</programlisting>
76 </listitem>
77
78 <listitem>
79 <para>Memory preallocation - preallocate huge pages at startup time
80 can improve performance but it may affect the qemu boot time.</para>
81
82 <programlisting>-mem-prealloc \</programlisting>
83 </listitem>
84
85 <listitem>
86 <para>Enable realtime characteristics - run qemu with realtime
87 features. While that mildly implies that "-realtime" alone might do
88 something, it's just an identifier for options that are partially
89 realtime. If you're running in a realtime or low latency environment,
90 you don't want your pages to be swapped out and mlock does that, thus
91 mlock=on. If you want VM density, then you may want swappable VMs,
92 thus mlock=off.</para>
93
94 <programlisting>-realtime mlock=on \</programlisting>
95 </listitem>
96 </itemizedlist>
97
98 <para>If the hardware does not have an IOMMU (known as "Intel VT-d" on
99 Intel-based machines and "AMD I/O Virtualization Technology" on AMD-based
100 machines), it will not be possible to assign devices in KVM.
101 Virtualization Technology features (VT-d, VT-x, etc.) must be enabled from
102 BIOS on the host target before starting a virtual machine.</para>
103 </section>
104
105 <section id="net_in_guest">
106 <title>Networking in guest</title>
107
108 <section id="vhost-user-support">
109 <title>Using vhost-user support</title>
110
111 <para>The goal of vhost-user is to implement a Virtio transport, staying
112 as close as possible to the vhost paradigm of using shared memory,
113 ioeventfds and irqfds. A UNIX domain socket based mechanism allows the
114 set up of resources used by a number of Vrings shared between two
115 userspace processes, which will be placed in shared memory.</para>
116
117 <para>To run QEMU with the vhost-user backend, you have to provide the
118 named UNIX domain socket which needs to be already opened by the
119 backend:</para>
120
121 <programlisting>-object memory-backend-file,id=mem,size=4096M,mem-path=/dev/hugepages,share=on \
122-chardev socket,id=char0,path=/var/run/openvswitch/vhost-user1 \
123-netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce \
124-device virtio-net-pci,netdev=mynet1,mac=52:54:00:00:00:01 \</programlisting>
125
126 <para>The vHost User standard uses a client-server model. The server
127 creates and manages the vHost User sockets and the client connects to
128 the sockets created by the server. It is recommended to use QEMU as
129 server so the vhost-user client can be restarted without affecting the
130 server, otherwise if the server side dies all clients need to be
131 restarted.</para>
132
133 <para>Using vhost-user in QEMU as server will offer the flexibility to
134 stop and start the virtual machine with no impact on virtual switch from
135 the host (vhost-user-client).</para>
136
137 <programlisting>-chardev socket,id=char0,path=/var/run/openvswitch/vhost-user1,server \</programlisting>
138 </section>
139
140 <section id="tap-interface">
141 <title>Using TAP Interfaces</title>
142
143 <para>QEMU can use TAP interfaces to provide full networking capability
144 for the guest OS:</para>
145
146 <programlisting>-netdev tap,id=net0,ifname=tap0,script=no,downscript=no \
147-device virtio-net-pci,netdev=net0,mac=22:EA:FB:A8:25:AE \</programlisting>
148 </section>
149
150 <section id="vfio-passthrough">
151 <title>VFIO passthrough VF (SR-IOV) to guest</title>
152
153 <para>KVM hypervisor support for attaching PCI devices on the host
154 system to guests. PCI passthrough allows guests to have exclusive access
155 to PCI devices for a range of tasks. PCI passthrough allows PCI devices
156 to appear and behave as if they were physically attached to the guest
157 operating system.</para>
158
159 <para>Preparing an Intel system for PCI passthrough:</para>
160
161 <itemizedlist>
162 <listitem>
163 <para>Enable the Intel VT-d extensions in BIOS</para>
164 </listitem>
165
166 <listitem>
167 <para>Activate Intel VT-d in the kernel by using
168 <literal>intel_iommu=on</literal> as a kernel boot parameter</para>
169 </listitem>
170
171 <listitem>
172 <para>Allow unsafe interrupts in case the system doesn't support
173 interrupt remapping. This can be done using
174 <literal>vfio_iommu_type1.allow_unsafe_interrupts=1</literal> as a
175 boot kernel parameter.</para>
176 </listitem>
177 </itemizedlist>
178
179 <para>Create guest with direct passthrough via VFIO framework like
180 so:</para>
181
182 <programlisting>-device vfio-pci,host=0000:03:10.2 \</programlisting>
183
184 <para>On the host, one or more VirtualFunctions (VFs) must be created in
185 order to be allocated for a guest network to access, before starting
186 QEMU:</para>
187
188 <programlisting>$ echo 2 &gt; /sys/class/net/eno3/device/sriov_numvfs
189$ modprobe vfio_pci
190$ dpdk-devbind.py --bind=vfio-pci 0000:03:10.2</programlisting>
191 </section>
192
193 <section id="multiqueue">
194 <title>Multi-queue</title>
195
196 <para>In order to ensure that network performance scales as the number
197 of vCPUs increases, multi-queue support can be used in QEMU.</para>
198
199 <section id="qemu-multiqueue-support">
200 <title>QEMU multi queue support configuration</title>
201
202 <programlisting>-chardev socket,id=char0,path=/var/run/openvswitch/vhost-user1 \
203-netdev type=vhost-user,id=net0,chardev=char0,queues=2 \
204-device virtio-net-pci,netdev=net0,mac=22:EA:FB:A8:25:AE,mq=on,vectors=6
205where vectors is calculated as: 2 + 2 * queues number.</programlisting>
206 </section>
207
208 <section id="inside-guest">
209 <title>Inside guest</title>
210
211 <para>Linux kernel virtio-net driver (one queue is enabled by
212 default):</para>
213
214 <programlisting>$ ethtool -L combined 2 eth0
215DPDK Virtio PMD
216$ testpmd -c 0x7 -- -i --rxq=2 --txq=2 --nb-cores=2 ...</programlisting>
217
218 <para>For QEMU documentation please see: <ulink
219 url="https://qemu.weilnetz.de/doc/qemu-doc.html">https://qemu.weilnetz.de/doc/qemu-doc.html</ulink>.</para>
220 </section>
221 </section>
222 </section>
223
224 <section id="libvirt">
225 <title>Libvirt</title>
226
227 <para>One way to manage guests in Enea NFV Access is by using
228 <literal>libvirt</literal>. Libvirt is used in conjunction with a daemon
229 (<literal>libvirtd</literal>) and a command line utility (virsh) to manage
230 virtualized environments.</para>
231
232 <para>The libvirt library is a hypervisor-independent virtualization API
233 and toolkit that is able to interact with the virtualization capabilities
234 of a range of operating systems. Libvirt provides a common, generic and
235 stable layer to securely manage domains on a node. As nodes may be
236 remotely located, libvirt provides all methods required to provision,
237 create, modify, monitor, control, migrate and stop the domains, within the
238 limits of hypervisor support for these operations.</para>
239
240 <para>The libvirt daemon runs on the Enea NFV Access host. All tools built
241 on libvirt API connect to the daemon to request the desired operation, and
242 to collect information about the configuration and resources of the host
243 system and guests. <literal>virsh</literal> is a command line interface
244 tool for managing guests and the hypervisor. The virsh tool is built on
245 the libvirt management API.</para>
246
247 <para><emphasis role="bold">Major functionality provided by
248 libvirt</emphasis></para>
249
250 <para>The following is a summary from the libvirt <ulink
251 url="http://wiki.libvirt.org/page/FAQ#What_is_libvirt.3F">home
252 page</ulink> describing the major libvirt features:</para>
253
254 <itemizedlist>
255 <listitem>
256 <para><emphasis role="bold">VM management:</emphasis> Various domain
257 lifecycle operations such as start, stop, pause, save, restore, and
258 migrate. Hotplug operations for many device types including disk and
259 network interfaces, memory, and cpus.</para>
260 </listitem>
261
262 <listitem>
263 <para><emphasis role="bold">Remote machine support:</emphasis> All
264 libvirt functionality is accessible on any machine running the libvirt
265 daemon, including remote machines. A variety of network transports are
266 supported for connecting remotely, with the simplest being
267 <literal>SSH</literal>, which requires no extra explicit
268 configuration. For more information, see: <ulink
269 url="http://libvirt.org/remote.html">http://libvirt.org/remote.html</ulink>.</para>
270 </listitem>
271
272 <listitem>
273 <para><emphasis role="bold">Network interface management:</emphasis>
274 Any host running the libvirt daemon can be used to manage physical and
275 logical network interfaces. Enumerate existing interfaces, as well as
276 configure (and create) interfaces, bridges, vlans, and bond devices.
277 For more details see: <ulink
278 url="https://fedorahosted.org/netcf/">https://fedorahosted.org/netcf/</ulink>.</para>
279 </listitem>
280
281 <listitem>
282 <para><emphasis role="bold">Virtual NAT and Route based
283 networking:</emphasis> Any host running the libvirt daemon can manage
284 and create virtual networks. Libvirt virtual networks use firewall
285 rules to act as a router, providing VMs transparent access to the host
286 machines network. For more information, see: <ulink
287 url="http://libvirt.org/archnetwork.html">http://libvirt.org/archnetwork.html</ulink>.</para>
288 </listitem>
289
290 <listitem>
291 <para><emphasis role="bold">Storage management:</emphasis> Any host
292 running the libvirt daemon can be used to manage various types of
293 storage: create file images of various formats (raw, qcow2, etc.),
294 mount NFS shares, enumerate existing LVM volume groups, create new LVM
295 volume groups and logical volumes, partition raw disk devices, mount
296 iSCSI shares, and much more. For more details, see: <ulink
297 url="http://libvirt.org/storage.html">http://libvirt.org/storage.html</ulink>.</para>
298 </listitem>
299
300 <listitem>
301 <para><emphasis role="bold">Libvirt Configuration:</emphasis> A
302 properly running libvirt requires that the following elements be in
303 place:</para>
304
305 <itemizedlist>
306 <listitem>
307 <para>Configuration files, located in the directory
308 <literal>/etc/libvirt</literal>. They include the daemon's
309 configuration file <literal>libvirtd.conf</literal>, and
310 hypervisor-specific configuration files, like
311 <literal>qemu.conf</literal> for the QEMU.</para>
312 </listitem>
313
314 <listitem>
315 <para>A running libvirtd daemon. The daemon is started
316 automatically in Enea NFV Access host.</para>
317 </listitem>
318
319 <listitem>
320 <para>Configuration files for the libvirt domains, or guests, to
321 be managed by the KVM host. The specifics for guest domains shall
322 be defined in an XML file of a format specified at <ulink
323 url="http://libvirt.org/formatdomain.html">http://libvirt.org/formatdomain.html</ulink>.
324 XML formats for other structures are specified at <ulink type=""
325 url="http://libvirt.org/format.html">http://libvirt.org/format.html</ulink>.</para>
326 </listitem>
327 </itemizedlist>
328 </listitem>
329 </itemizedlist>
330
331 <section id="boot-kvm-guest">
332 <title>Booting a KVM Guest</title>
333
334 <para>There are several ways to boot a KVM guest. Here we describe how
335 to boot using a raw image. A direct kernel boot can be performed by
336 transferring the guest kernel and the file system files to the host and
337 specifying a <literal>&lt;kernel&gt;</literal> and an
338 <literal>&lt;initrd&gt;</literal> element inside the
339 <literal>&lt;os&gt;</literal> element of the guest XML file, as in the
340 following example:</para>
341
342 <programlisting>&lt;os&gt;
343 &lt;kernel&gt;bzImage&lt;/kernel&gt;
344&lt;/os&gt;
345&lt;devices&gt;
346 &lt;disk type='file' device='disk'&gt;
347 &lt;driver name='qemu' type='raw' cache='none'/&gt;
348 &lt;source file='enea-nfv-access-guest-qemux86-64.ext4'/&gt;
349 &lt;target dev='vda' bus='virtio'/&gt;
350 &lt;/disk&gt;
351&lt;/devices&gt;</programlisting>
352 </section>
353
354 <section id="start-guest">
355 <title>Starting a Guest</title>
356
357 <para>Command <command>virsh create</command> starts a guest:</para>
358
359 <programlisting>virsh create example-guest-x86.xml</programlisting>
360
361 <para>If further configurations are needed before the guest is reachable
362 through <literal>ssh</literal>, a console can be started using command
363 <command>virsh console</command>. The example below shows how to start a
364 console where kvm-example-guest is the name of the guest defined in the
365 guest XML file:</para>
366
367 <programlisting>virsh console kvm-example-guest</programlisting>
368
369 <para>This requires that the guest domain has a console configured in
370 the guest XML file:</para>
371
372 <programlisting>&lt;os&gt;
373 &lt;cmdline&gt;console=ttyS0,115200&lt;/cmdline&gt;
374&lt;/os&gt;
375&lt;devices&gt;
376 &lt;console type='pty'&gt;
377 &lt;target type='serial' port='0'/&gt;
378 &lt;/console&gt;
379&lt;/devices&gt;</programlisting>
380 </section>
381
382 <section id="isolation">
383 <title>Isolation</title>
384
385 <para>It may be desirable to isolate execution in a guest, to a specific
386 guest core. It might also be desirable to run a guest on a specific host
387 core.</para>
388
389 <para>To pin the virtual CPUs of the guest to specific cores, configure
390 the <literal>&lt;cputune&gt;</literal> contents as follows:</para>
391
392 <orderedlist>
393 <listitem>
394 <para>First explicitly state on which host core each guest core
395 shall run, by mapping <literal>vcpu</literal> to
396 <literal>cpuset</literal> in the <literal>&lt;vcpupin&gt;</literal>
397 tag.</para>
398 </listitem>
399
400 <listitem>
401 <para>In the <literal>&lt;cputune&gt;</literal> tag it is further
402 possible to specify on which CPU the emulator shall run by adding
403 the cpuset to the <literal>&lt;emulatorpin&gt;</literal> tag.</para>
404
405 <programlisting>&lt;vcpu placement='static'&gt;2&lt;/vcpu&gt;
406&lt;cputune&gt;
407 &lt;vcpupin vcpu='0' cpuset='2'/&gt;
408 &lt;vcpupin vcpu='1' cpuset='3'/&gt;
409 &lt;emulatorpin cpuset="2"/&gt;
410&lt;/cputune&gt;</programlisting>
411
412 <para><literal>libvirt</literal> will group all threads belonging to
413 a qemu instance into cgroups that will be created for that purpose.
414 It is possible to supply a base name for those cgroups using the
415 <literal>&lt;resource&gt;</literal> tag:</para>
416
417 <programlisting>&lt;resource&gt;
418 &lt;partition&gt;/rt&lt;/partition&gt;
419&lt;/resource&gt;</programlisting>
420 </listitem>
421 </orderedlist>
422 </section>
423
424 <section id="network-libvirt">
425 <title>Networking using libvirt</title>
426
427 <para>Command <command>virsh net-create</command> starts a network. If
428 any networks are listed in the guest XML file, those networks must be
429 started before the guest is started. As an example, if the network is
430 defined in a file named example-net.xml, it is started as
431 follows:</para>
432
433 <programlisting>virsh net-create example-net.xml
434&lt;network&gt;
435 &lt;name&gt;sriov&lt;/name&gt;
436 &lt;forward mode='hostdev' managed='yes'&gt;
437 &lt;pf dev='eno3'/&gt;
438 &lt;/forward&gt;
439&lt;/network&gt;</programlisting>
440
441 <para><literal>libvirt</literal> is a virtualization API that supports
442 virtual network creation. These networks can be connected to guests and
443 containers by referencing the network in the guest XML file. It is
444 possible to have a virtual network persistently running on the host by
445 starting the network with command <command>virsh net-define</command>
446 instead of the previously mentioned <command>virsh
447 net-create</command>.</para>
448
449 <para>An example for the sample network defined in
450 <literal>meta-vt/recipes-example/virt-example/files/example-net.xml</literal>:</para>
451
452 <programlisting>virsh net-define example-net.xml</programlisting>
453
454 <para>Command <command>virsh net-autostart</command> enables a
455 persistent network to start automatically when the libvirt daemon
456 starts:</para>
457
458 <programlisting>virsh net-autostart example-net</programlisting>
459
460 <para>Guest configuration file (xml) must be updated to access newly
461 created network like so:</para>
462
463 <programlisting> &lt;interface type='network'&gt;
464 &lt;source network='sriov'/&gt;
465 &lt;/interface&gt;</programlisting>
466
467 <para>The following presented here are a few modes of network access
468 from guest using <command>virsh</command>:</para>
469
470 <itemizedlist>
471 <listitem>
472 <para><emphasis role="bold">vhost-user interface</emphasis></para>
473
474 <para>See the Open vSwitch chapter on how to create vhost-user
475 interface using Open vSwitch. Currently there is no Open vSwitch
476 support for networks that are managed by libvirt (e.g. NAT). As of
477 now, only bridged networks are supported (those where the user has
478 to manually create the bridge).</para>
479
480 <programlisting> &lt;interface type='vhostuser'&gt;
481 &lt;mac address='00:00:00:00:00:01'/&gt;
482 &lt;source type='unix' path='/var/run/openvswitch/vhost-user1' mode='client'/&gt;
483 &lt;model type='virtio'/&gt;
484 &lt;driver queues='1'&gt;
485 &lt;host mrg_rxbuf='off'/&gt;
486 &lt;/driver&gt;
487 &lt;/interface&gt;</programlisting>
488 </listitem>
489
490 <listitem>
491 <para><emphasis role="bold">PCI passthrough
492 (SR-IOV)</emphasis></para>
493
494 <para>KVM hypervisor support for attaching PCI devices on the host
495 system to guests. PCI passthrough allows guests to have exclusive
496 access to PCI devices for a range of tasks. PCI passthrough allows
497 PCI devices to appear and behave as if they were physically attached
498 to the guest operating system.</para>
499
500 <para>Preparing an Intel system for PCI passthrough is done like
501 so:</para>
502
503 <itemizedlist>
504 <listitem>
505 <para>Enable the Intel VT-d extensions in BIOS</para>
506 </listitem>
507
508 <listitem>
509 <para>Activate Intel VT-d in the kernel by using
510 <literal>intel_iommu=on</literal> as a kernel boot
511 parameter</para>
512 </listitem>
513
514 <listitem>
515 <para>Allow unsafe interrupts in case the system doesn't support
516 interrupt remapping. This can be done using
517 <literal>vfio_iommu_type1.allow_unsafe_interrupts=1</literal> as
518 a boot kernel parameter.</para>
519 </listitem>
520 </itemizedlist>
521
522 <para>VFs must be created on the host before starting the
523 guest:</para>
524
525 <programlisting>$ echo 2 &gt; /sys/class/net/eno3/device/sriov_numvfs
526$ modprobe vfio_pci
527$ dpdk-devbind.py --bind=vfio-pci 0000:03:10.0
528 &lt;interface type='hostdev' managed='yes'&gt;
529 &lt;source&gt;
530 &lt;address type='pci' domain='0x0' bus='0x03' slot='0x10' function='0x0'/&gt;
531 &lt;/source&gt;
532 &lt;mac address='52:54:00:6d:90:02'/&gt;
533 &lt;/interface&gt;</programlisting>
534 </listitem>
535
536 <listitem>
537 <para><emphasis role="bold">Bridge interface</emphasis></para>
538
539 <para>In case an OVS bridge exists on host, it can be used to
540 connect the guest:</para>
541
542 <programlisting> &lt;interface type='bridge'&gt;
543 &lt;mac address='52:54:00:71:b1:b6'/&gt;
544 &lt;source bridge='ovsbr0'/&gt;
545 &lt;virtualport type='openvswitch'/&gt;
546 &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/&gt;
547 &lt;/interface&gt;</programlisting>
548
549 <para>For further details on the network XML format, see <ulink
550 url="http://libvirt.org/formatnetwork.html">http://libvirt.org/formatnetwork.html</ulink>.</para>
551 </listitem>
552 </itemizedlist>
553 </section>
554
555 <section id="libvirt-guest-config-ex">
556 <title>Libvirt guest configuration examples</title>
557
558 <section id="guest-config-vhost-user-interface">
559 <title>Guest configuration with vhost-user interface</title>
560
561 <programlisting>&lt;domain type='kvm'&gt;
562 &lt;name&gt;vm_vhost&lt;/name&gt;
563 &lt;uuid&gt;4a9b3f53-fa2a-47f3-a757-dd87720d9d1d&lt;/uuid&gt;
564 &lt;memory unit='KiB'&gt;4194304&lt;/memory&gt;
565 &lt;currentMemory unit='KiB'&gt;4194304&lt;/currentMemory&gt;
566 &lt;memoryBacking&gt;
567 &lt;hugepages&gt;
568 &lt;page size='1' unit='G' nodeset='0'/&gt;
569 &lt;/hugepages&gt;
570 &lt;/memoryBacking&gt;
571 &lt;vcpu placement='static'&gt;2&lt;/vcpu&gt;
572 &lt;cputune&gt;
573 &lt;shares&gt;4096&lt;/shares&gt;
574 &lt;vcpupin vcpu='0' cpuset='4'/&gt;
575 &lt;vcpupin vcpu='1' cpuset='5'/&gt;
576 &lt;emulatorpin cpuset='4,5'/&gt;
577 &lt;/cputune&gt;
578 &lt;os&gt;
579 &lt;type arch='x86_64' machine='pc'&gt;hvm&lt;/type&gt;
580 &lt;kernel&gt;/mnt/qemu/bzImage&lt;/kernel&gt;
581 &lt;cmdline&gt;root=/dev/vda console=ttyS0,115200&lt;/cmdline&gt;
582 &lt;boot dev='hd'/&gt;
583 &lt;/os&gt;
584 &lt;features&gt;
585 &lt;acpi/&gt;
586 &lt;apic/&gt;
587 &lt;/features&gt;
588 &lt;cpu mode='host-model'&gt;
589 &lt;model fallback='allow'/&gt;
590 &lt;topology sockets='2' cores='1' threads='1'/&gt;
591 &lt;numa&gt;
592 &lt;cell id='0' cpus='0-1' memory='4194304' unit='KiB' memAccess='shared'/&gt;
593 &lt;/numa&gt;
594 &lt;/cpu&gt;
595 &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
596 &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
597 &lt;on_crash&gt;destroy&lt;/on_crash&gt;
598 &lt;devices&gt;
599 &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt;
600 &lt;disk type='file' device='disk'&gt;
601 &lt;driver name='qemu' type='raw' cache='none'/&gt;
602 &lt;source file='/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4'/&gt;
603 &lt;target dev='vda' bus='virtio'/&gt;
604 &lt;/disk&gt;
605 &lt;interface type='vhostuser'&gt;
606 &lt;mac address='00:00:00:00:00:01'/&gt;
607 &lt;source type='unix' path='/var/run/openvswitch/vhost-user1' mode='client'/&gt;
608 &lt;model type='virtio'/&gt;
609 &lt;driver queues='1'&gt;
610 &lt;host mrg_rxbuf='off'/&gt;
611 &lt;/driver&gt;
612 &lt;/interface&gt;
613 &lt;serial type='pty'&gt;
614 &lt;target port='0'/&gt;
615 &lt;/serial&gt;
616 &lt;console type='pty'&gt;
617 &lt;target type='serial' port='0'/&gt;
618 &lt;/console&gt;
619 &lt;/devices&gt;
620&lt;/domain&gt;</programlisting>
621 </section>
622
623 <section id="guest-config-pci-passthrough">
624 <title>Guest configuration with PCI passthrough</title>
625
626 <programlisting>&lt;domain type='kvm'&gt;
627 &lt;name&gt;vm_sriov1&lt;/name&gt;
628 &lt;uuid&gt;4a9b3f53-fa2a-47f3-a757-dd87720d9d1d&lt;/uuid&gt;
629 &lt;memory unit='KiB'&gt;4194304&lt;/memory&gt;
630 &lt;currentMemory unit='KiB'&gt;4194304&lt;/currentMemory&gt;
631 &lt;memoryBacking&gt;
632 &lt;hugepages&gt;
633 &lt;page size='1' unit='G' nodeset='0'/&gt;
634 &lt;/hugepages&gt;
635 &lt;/memoryBacking&gt;
636 &lt;vcpu&gt;2&lt;/vcpu&gt;
637 &lt;os&gt;
638 &lt;type arch='x86_64' machine='q35'&gt;hvm&lt;/type&gt;
639 &lt;kernel&gt;/mnt/qemu/bzImage&lt;/kernel&gt;
640 &lt;cmdline&gt;root=/dev/vda console=ttyS0,115200&lt;/cmdline&gt;
641 &lt;boot dev='hd'/&gt;
642 &lt;/os&gt;
643 &lt;features&gt;
644 &lt;acpi/&gt;
645 &lt;apic/&gt;
646 &lt;/features&gt;
647 &lt;cpu mode='host-model'&gt;
648 &lt;model fallback='allow'/&gt;
649 &lt;topology sockets='1' cores='2' threads='1'/&gt;
650 &lt;numa&gt;
651 &lt;cell id='0' cpus='0' memory='4194304' unit='KiB' memAccess='shared'/&gt;
652 &lt;/numa&gt;
653 &lt;/cpu&gt;
654 &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
655 &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
656 &lt;on_crash&gt;destroy&lt;/on_crash&gt;
657 &lt;devices&gt;
658 &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt;
659 &lt;disk type='file' device='disk'&gt;
660 &lt;driver name='qemu' type='raw' cache='none'/&gt;
661 &lt;source file='/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4'/&gt;
662 &lt;target dev='vda' bus='virtio'/&gt;
663 &lt;/disk&gt;
664 &lt;interface type='hostdev' managed='yes'&gt;
665 &lt;source&gt;
666 &lt;address type='pci' domain='0x0' bus='0x03' slot='0x10' function='0x0'/&gt;
667 &lt;/source&gt;
668 &lt;mac address='52:54:00:6d:90:02'/&gt;
669 &lt;/interface&gt;
670 &lt;serial type='pty'&gt;
671 &lt;target port='0'/&gt;
672 &lt;/serial&gt;
673 &lt;console type='pty'&gt;
674 &lt;target type='serial' port='0'/&gt;
675 &lt;/console&gt;
676 &lt;/devices&gt;
677&lt;/domain&gt;</programlisting>
678 </section>
679
680 <section id="guest-config-bridge-interface">
681 <title>Guest configuration with bridge interface</title>
682
683 <programlisting>&lt;domain type='kvm'&gt;
684 &lt;name&gt;vm_bridge&lt;/name&gt;
685 &lt;uuid&gt;4a9b3f53-fa2a-47f3-a757-dd87720d9d1d&lt;/uuid&gt;
686 &lt;memory unit='KiB'&gt;4194304&lt;/memory&gt;
687 &lt;currentMemory unit='KiB'&gt;4194304&lt;/currentMemory&gt;
688 &lt;memoryBacking&gt;
689 &lt;hugepages&gt;
690 &lt;page size='1' unit='G' nodeset='0'/&gt;
691 &lt;/hugepages&gt;
692 &lt;/memoryBacking&gt;
693 &lt;vcpu placement='static'&gt;2&lt;/vcpu&gt;
694 &lt;cputune&gt;
695 &lt;shares&gt;4096&lt;/shares&gt;
696 &lt;vcpupin vcpu='0' cpuset='4'/&gt;
697 &lt;vcpupin vcpu='1' cpuset='5'/&gt;
698 &lt;emulatorpin cpuset='4,5'/&gt;
699 &lt;/cputune&gt;
700 &lt;os&gt;
701 &lt;type arch='x86_64' machine='q35'&gt;hvm&lt;/type&gt;
702 &lt;kernel&gt;/mnt/qemu/bzImage&lt;/kernel&gt;
703 &lt;cmdline&gt;root=/dev/vda console=ttyS0,115200&lt;/cmdline&gt;
704 &lt;boot dev='hd'/&gt;
705 &lt;/os&gt;
706 &lt;features&gt;
707 &lt;acpi/&gt;
708 &lt;apic/&gt;
709 &lt;/features&gt;
710 &lt;cpu mode='host-model'&gt;
711 &lt;model fallback='allow'/&gt;
712 &lt;topology sockets='2' cores='1' threads='1'/&gt;
713 &lt;numa&gt;
714 &lt;cell id='0' cpus='0-1' memory='4194304' unit='KiB' memAccess='shared'/&gt;
715 &lt;/numa&gt;
716 &lt;/cpu&gt;
717 &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
718 &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
719 &lt;on_crash&gt;destroy&lt;/on_crash&gt;
720 &lt;devices&gt;
721 &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt;
722 &lt;disk type='file' device='disk'&gt;
723 &lt;driver name='qemu' type='raw' cache='none'/&gt;
724 &lt;source file='/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4'/&gt;
725 &lt;target dev='vda' bus='virtio'/&gt;
726 &lt;/disk&gt;
727 &lt;interface type='bridge'&gt;
728 &lt;mac address='52:54:00:71:b1:b6'/&gt;
729 &lt;source bridge='ovsbr0'/&gt;
730 &lt;virtualport type='openvswitch'/&gt;
731 &lt;address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/&gt;
732 &lt;/interface&gt;
733 &lt;serial type='pty'&gt;
734 &lt;target port='0'/&gt;
735 &lt;/serial&gt;
736 &lt;console type='pty'&gt;
737 &lt;target type='serial' port='0'/&gt;
738 &lt;/console&gt;
739 &lt;/devices&gt;
740&lt;/domain&gt;</programlisting>
741 </section>
742 </section>
743 </section>
744</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.png b/doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.png
new file mode 100644
index 0000000..c28d643
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg b/doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg
new file mode 100644
index 0000000..319bf7e
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg
@@ -0,0 +1,3 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
3<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid meet" viewBox="0 0 640 640" width="640" height="640"><defs><path d="M0 93L640 93L640 547L0 547L0 93Z" id="b4lgbdl3I5"></path><clipPath id="clipbKzvApRlV"><use xlink:href="#b4lgbdl3I5" opacity="1"></use></clipPath></defs><g><g><g><g clip-path="url(#clipbKzvApRlV)" opacity="1"><image xlink:href="data:image/png;base64,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" x="0" y="0" width="640" height="454" transform="matrix(1 0 0 1 1.1368683772161603e-13 93.00000000000006)"></image></g></g></g></g></svg> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/images/virtual_network_functions.png b/doc/book-enea-nfv-access-guide-intel/doc/images/virtual_network_functions.png
new file mode 100644
index 0000000..4011de8
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/images/virtual_network_functions.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/overview.xml b/doc/book-enea-nfv-access-guide-intel/doc/overview.xml
new file mode 100644
index 0000000..961939c
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/overview.xml
@@ -0,0 +1,165 @@
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="overview">
5 <title>Overview</title>
6
7 <para>The Enea NFV Access Guide available with this release of the Enea NFV
8 Access seeks to provide further information that will help all intended
9 users make the most out of the virtualization features.</para>
10
11 <section id="description">
12 <title>Enea NFV Access Description</title>
13
14 <para>Enea NFV Access is a lightweight virtualization software designed
15 for deployment on edge devices at customer premises. Streamlined for high
16 networking performance and minimal footprints for both host platform and
17 VNFs, it enables very high compute density.</para>
18
19 <para>Enea NFV Access also provides a foundation for vCPE agility and
20 innovation, reducing cost and complexity for computing at the network
21 edge. It supports multiple architectures and scales from small white box
22 edge devices up to high-end network servers. Thanks to the streamlined
23 footprint, Enea NFV Access can be deployed on systems as small as single
24 2-core ARM devices. It scales up to clustered 24 core x86 Xeon servers and
25 beyond, allowing multiple VNFs on the same machine, and eliminating the
26 need to use different virtualization software for different hardware
27 platforms, saving costs through single source provisioning.</para>
28
29 <para>Optimized virtual networking performance provides low virtualized
30 networking latency, high virtualized networking throughput (10 Gb wire
31 speed), and low processing overhead. It allows high compute density on
32 white box hardware, maintaining performance when moving functionality from
33 application specific appliances to software on standard hardware. The
34 optimized boot speed minimizes the time from reboot to active services,
35 improving availability.</para>
36
37 <para>Enea NFV Access provides virtualization using both containers and
38 virtual machines. Containers provide lightweight virtualization for a
39 smaller VNF footprint and a very short time interval from start to enabled
40 network services. VMs provide virtualization with secure VNF sandboxing
41 and is the preferred virtualization method for OPNFV compliance. Enea NFV
42 Access allows combinations of containers and VMs for highest possible user
43 adaptability.</para>
44
45 <para>Flexible interfaces for VNF lifecycle management and service
46 function chaining, are important to allow a smooth transition from
47 traditional network appliances to virtualized network functions in
48 existing networks, as they plug into a variety of interfaces. Enea NFV
49 Access supports VNF lifecycle management and service function chaining
50 through OpenStack, NETCONF, REST, CLI and Docker. It integrates a powerful
51 device management framework that enables full FCAPS functionality for
52 powerful management of the platform.</para>
53
54 <para>Building on open source, Enea NFV Access prevents vendor lock-in
55 thanks to its completely open standards and interfaces. Unlike proprietary
56 platforms that either do not allow decoupling of software from hardware,
57 or prevent NVF portability, Enea NFV Access includes optimized components
58 with open interfaces to allow full portability and
59 interoperability.</para>
60 </section>
61
62 <section id="components">
63 <title>Components</title>
64
65 <para>Enea NFV Access is built on highly optimized open source and
66 value-adding components that provide standard interfaces but with boosted
67 performance.</para>
68
69 <mediaobject>
70 <imageobject>
71 <imagedata align="center"
72 fileref="images/virtual_network_functions.png" />
73 </imageobject>
74 </mediaobject>
75
76 <para>The Access Platform includes the following key components:</para>
77
78 <itemizedlist>
79 <listitem>
80 <para>Linux Kernel &ndash; Optimized Linux kernel with the focus on
81 vCPE systems characteristics.</para>
82 </listitem>
83
84 <listitem>
85 <para>KVM &ndash; Virtualization with virtual machines. KVM is the
86 standard virtualization engine for Linux based systems.</para>
87 </listitem>
88
89 <listitem>
90 <para>Docker &ndash; Docker provides a lightweight configuration using
91 containers. Docker is the standard platform for container
92 virtualization.</para>
93 </listitem>
94
95 <listitem>
96 <para>Virtual switching &ndash; Optimized OVS-DPDK provides high
97 throughput and low latency.</para>
98 </listitem>
99
100 <listitem>
101 <para>Edge Link &ndash; Edge Link provides interfaces to orchestration
102 for centralized VNF lifecycle management and service function
103 chaining:</para>
104
105 <orderedlist>
106 <listitem>
107 <para>NETCONF</para>
108 </listitem>
109
110 <listitem>
111 <para>OpenStack</para>
112 </listitem>
113
114 <listitem>
115 <para>Docker</para>
116 </listitem>
117
118 <listitem>
119 <para>REST</para>
120 </listitem>
121
122 <listitem>
123 <para>CLI</para>
124 </listitem>
125 </orderedlist>
126 </listitem>
127
128 <listitem>
129 <para>APT packet management &ndash; Feature rich repository of
130 prebuilt open source packages for extending and adapting the platform
131 using APT Package Management.</para>
132 </listitem>
133
134 <listitem>
135 <para>CLI based VNF management &ndash; CLI access over virsh and
136 libvirt.</para>
137 </listitem>
138
139 <listitem>
140 <para>FCAPS framework &ndash; The device management framework for
141 managing the platform is capable of providing full FCAPS functionality
142 to orchestration or network management systems.</para>
143 </listitem>
144
145 <listitem>
146 <para>Data plane &ndash; High performance data plane that includes the
147 following optimized data plane drivers:</para>
148
149 <orderedlist>
150 <listitem>
151 <para>DPDK</para>
152 </listitem>
153
154 <listitem>
155 <para>OpenFastPath (OFP)</para>
156 </listitem>
157
158 <listitem>
159 <para>ODP</para>
160 </listitem>
161 </orderedlist>
162 </listitem>
163 </itemizedlist>
164 </section>
165</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/doc/ovs.xml b/doc/book-enea-nfv-access-guide-intel/doc/ovs.xml
new file mode 100644
index 0000000..fdbd692
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/ovs.xml
@@ -0,0 +1,161 @@
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="ovs">
5 <title>Open Virtual Switch</title>
6
7 <para>Open vSwitch (OVS) is an open-source multilayer virtual switch
8 designed to be used in virtualized environments to forward traffic between
9 different VMs on the same host, and also between VMs and the physical
10 network.</para>
11
12 <para>Native OVS forwarding is handled by two major components: a user-space
13 daemon called <literal>ovs-vswitchd</literal> and a
14 <literal>fastpath</literal> kernel module used to accelerate the data path.
15 The fastpath kernel module will handle packets received on the NIC by simply
16 consulting a flow table with corresponding action rules (e.g to forward the
17 packet or modify its headers). If no matching entry is found in the flow
18 table, the packet is copied to the user-space and sent to the ovs-vswitchd
19 deamon which determines how it should be handled ("slowpath").</para>
20
21 <para>The packet is then passed back to the kernel module together with the
22 desired action and the flow table is updated, so that subsequent packets in
23 the same flow can be handled in fastpath without any user-space interaction.
24 In this way, OVS eliminates a lot of the context switching between
25 kernel-space and user-space, but the throughput is still limited by the
26 capacity of the Linux kernel stack.</para>
27
28 <section id="ovs-dpdk">
29 <title>OVS-DPDK</title>
30
31 <para>To improve performance, OVS supports integration with Intel DPDK
32 libraries to operate entirely in user-space (OVS-DPDK). DPDK Poll Mode
33 Drivers (PMDs) enable direct transfers of packets between the physical NIC
34 and user-space, thereby eliminating the overhead of interrupt handling and
35 Linux kernel network stack processing. OVS-DPDK provides DPDK-backed
36 vhost-user ports as the primary way to connect guests to this datapath.
37 The vhost-user interfaces are transparent to the guest.</para>
38 </section>
39
40 <section id="ovs-commands">
41 <title>OVS commands</title>
42
43 <para>OVS provides a rich set of command line management tools, most
44 importantly:</para>
45
46 <itemizedlist>
47 <listitem>
48 <para>ovs-vsctl: Used to manage and inspect switch configurations,
49 e.g. to create bridges and to add/remove ports.</para>
50 </listitem>
51
52 <listitem>
53 <para>ovs-ofctl: Used to configure and monitor flows.</para>
54 </listitem>
55 </itemizedlist>
56
57 <para>For more information about Open vSwitch, see <ulink
58 url="http://openvswitch.org">http://openvswitch.org</ulink>.</para>
59 </section>
60
61 <section id="config-ovs-dpdk">
62 <title>Configuring OVS-DPDK for improved performance</title>
63
64 <section id="dpdk-lcore-mask">
65 <title>dpdk-lcore-mask</title>
66
67 <para>Specifies the CPU core affinity for DPDK lcore threads. The lcore
68 threads are used for DPDK library tasks. For performance it is best to
69 set this to a single core on the system, and it should not overlap the
70 pmd-cpu-mask, as seen in the example below.</para>
71
72 <para>Example: To use core 1:</para>
73
74 <programlisting>ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x1</programlisting>
75 </section>
76
77 <section id="pmd-cpu-mask">
78 <title>pmd-cpu-mask</title>
79
80 <para>The DPDK PMD threads polling for incoming packets are CPU bound
81 and should be pinned to isolated cores for optimal performance.</para>
82
83 <para>If OVS-DPDK receives traffic on multiple ports, for example when
84 DPDK and vhost-user ports are used for bi-directional traffic, the
85 performance can be significantly improved by creating multiple PMD
86 threads and affinitizing them to separate cores in order to share the
87 workload, by each being responsible for an individual port. The cores
88 should not be hyperthreads on the same CPU.</para>
89
90 <para>The PMD core affinity is specified by setting an appropriate core
91 mask. Example: using cores 2 and 3:</para>
92
93 <programlisting>ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc</programlisting>
94 </section>
95 </section>
96
97 <section id="setup-ovs-dpdk">
98 <title>How to set up OVS-DPDK</title>
99
100 <para>The DPDK must be configured prior to setting up OVS-DPDK. See
101 <xref linkend="dpdk-setup"/> for DPDK setup instructions, then follow these steps:</para>
102
103 <orderedlist>
104 <listitem>
105 <para>Clean up the environment:</para>
106
107 <programlisting>killall ovsdb-server ovs-vswitchd
108rm -f /var/run/openvswitch/vhost-user*
109rm -f /etc/openvswitch/conf.db</programlisting>
110 </listitem>
111
112 <listitem>
113 <para>Start the ovsdb-server:</para>
114
115 <programlisting>export DB_SOCK=/var/run/openvswitch/db.sock
116ovsdb-tool create /etc/openvswitch/conf.db /usr/share/openvswitch/vswitch.ovsschema
117ovsdb-server --remote=punix:$DB_SOCK /
118--remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach</programlisting>
119 </listitem>
120
121 <listitem>
122 <para>Start ovs-vswitchd with DPDK support enabled:</para>
123
124 <programlisting>ovs-vsctl --no-wait init
125ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x1
126ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc
127ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true
128ovs-vswitchd unix:$DB_SOCK --pidfile --detach /
129--log-file=/var/log/openvswitch/ovs-vswitchd.log</programlisting>
130 </listitem>
131
132 <listitem>
133 <para>Create the OVS bridge and attach ports:</para>
134
135 <programlisting>ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev
136ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface dpdk0 type=dpdk /
137:dpdk-devargs=&lt;PCI device&gt;</programlisting>
138 </listitem>
139
140 <listitem>
141 <para>Add DPDK vhost-user ports:</para>
142
143 <programlisting>ovs-vsctl add-port ovsbr0 vhost-user1 -- set Interface vhost-user1 type=dpdkvhostuser</programlisting>
144
145 <para>This command creates a socket at
146 <literal>/var/run/openvswitch/vhost-user1</literal>, which can be
147 provided to the VM on the QEMU command line. See <xref linkend="net_in_guest"/> for
148 details.</para>
149 </listitem>
150
151 <listitem>
152 <para>Define flows:</para>
153
154 <programlisting>ovs-ofctl del-flows ovsbr0
155ovs-ofctl show ovsbr0
156ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2
157ovs-ofctl add-flow ovsbr0 in_port=2,action=output:1</programlisting>
158 </listitem>
159 </orderedlist>
160 </section>
161</chapter> \ No newline at end of file
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
new file mode 100644
index 0000000..4b10d2a
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/doc/using_nfv_access_sdks.xml
@@ -0,0 +1,472 @@
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="workflow">
5 <title>Using Enea NFV Access SDKs</title>
6
7 <para>Enea NFV Access comes with a standard SDK which can be used to develop
8 user-applications and kernel modules for both host and guest images.</para>
9
10 <para>The standard SDK consists of:</para>
11
12 <itemizedlist>
13 <listitem>
14 <para>Cross-Development Toolchain: cross-compiler and
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>
63 <para><programlisting>$ ./install-sdk.sh</programlisting>When
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>
79
80 <listitem>
81 <para>Setup the toolchain environment for your target by sourcing the
82 environment-setup script. Example: <programlisting>$ source sdkdir/environment-setup-corei7-64-enea-linux</programlisting></para>
83 </listitem>
84 </orderedlist>
85 </section>
86
87 <section id="crosscomp-apps">
88 <title>Cross-Compiling Applications from Command Line</title>
89
90 <para>Once the environment-setup script is sourced, you can make your
91 applications as per usual and get them compiled for your target. Below you
92 see how to cross-compile from command line.</para>
93
94 <orderedlist>
95 <listitem>
96 <para>Create a Makefile for your application. Example: a simple
97 Makefile and application:</para>
98
99 <programlisting>helloworld:helloworld.o
100 $(CC) -o helloworld helloworld.o
101clean:
102 rm -f *.o helloworld
103#include stdio.h;
104int main(void) {
105 printf("Hello World\n");
106 return 0;
107}</programlisting>
108 </listitem>
109
110 <listitem>
111 <para>Run <command>make</command> to cross-compile your application
112 according to the environment set up:</para>
113
114 <programlisting>$ make</programlisting>
115 </listitem>
116
117 <listitem>
118 <para>Deploy the helloworld program to your target and run it:</para>
119
120 <programlisting># ./helloworld
121hello world</programlisting>
122 </listitem>
123 </orderedlist>
124 </section>
125
126 <section id="crosscomp-kern-mod">
127 <title>Cross-Compiling Kernel Modules</title>
128
129 <para>Before cross-compiling kernle modules, you need to make sure the
130 installed toolchain includes the kernel source tree, which should be
131 available at:
132 <literal>sdkdir/sysroots/targetarch-enea-linux/usr/src/kernel</literal>.</para>
133
134 <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
136 see how to cross-compile a kernel module.</para>
137
138 <orderedlist>
139 <listitem>
140 <para>Create a Makefile for the kernel module. Example: a simple
141 Makefile and kernel module:</para>
142
143 <programlisting>obj-m := hello.o
144PWD := $(shell pwd)
145
146KERNEL_SRC := full path to kernel source tree
147
148all: scripts
149 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" modules
150scripts:
151 $(MAKE) -C $(KERNEL_SRC) scripts
152clean:
153 $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" clean
154#include linux/module.h /* Needed by all modules */
155#include linux/kernel.h /* Needed for KERN_INFO */
156#include linux/init.h /* Needed for the macros */
157
158static int __init hello_start(void)
159{
160 printk(KERN_INFO "Loading hello module...\n");
161 printk(KERN_INFO "Hello, world\n");
162 return 0;
163}
164
165static void __exit hello_end(void)
166{
167 printk(KERN_INFO "Goodbye, world\n");
168}
169
170module_init(hello_start);
171module_exit(hello_end);
172
173MODULE_LICENSE("GPL");</programlisting>
174 </listitem>
175
176 <listitem>
177 <para>Run <command>make</command> to cross-compile your kernel module
178 according to the environment set up:</para>
179
180 <programlisting>$ make</programlisting>
181 </listitem>
182
183 <listitem>
184 <para>Deploy the kernel module <literal>hello.ko</literal> to your
185 target and install/remove it:</para>
186
187 <programlisting># insmod hello.ko
188# rmmod hello.ko
189# dmesg
190[...] Loading hello module...
191[...] Hello, world
192[...] Goodbye, world</programlisting>
193 </listitem>
194 </orderedlist>
195 </section>
196
197 <section id="deploy-artifacts">
198 <title>Deploying your artifacts</title>
199
200 <section id="deploy_onhost">
201 <title>Deploying on host</title>
202
203 <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,
205 to use <literal>scp</literal> to copy to the desired location.</para>
206
207 <para><programlisting># scp helloworld root@&lt;target_ip_address&gt;:/tmp</programlisting></para>
208 </section>
209
210 <section id="deploy_onguest">
211 <title>Deploying on guest</title>
212
213 <para>You can deploy your artifacts onto the guest VM running on the
214 target, by using TAP Networking. You can use the
215 <filename>/etc/qemu-ifup</filename> script to create the tap interface
216 on the host and attach it to the existing virtual bridge
217 (<literal>virbr0</literal>). This bridge interface is created by the
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
224 <para>Follow the steps below to create this setup:</para>
225
226 <orderedlist>
227 <listitem>
228 <para>On the host, run the <literal>qemu-ifup</literal> script
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>
258
259 <listitem>
260 <para>Launch the virtual machine specifying the newly created tap
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>
266
267 <listitem>
268 <para>On the guest, after logging, configure the virtual network
269 device and set the default gateway as the <literal>virbr0</literal>
270 ip address:</para>
271
272 <para><programlisting>ip addr add 192.168.122.10/24 dev enp0s2
273ip link set enp0s2 up
274ip route add default via 192.168.122.1 dev enp0s2</programlisting></para>
275 </listitem>
276
277 <listitem>
278 <para>Now you can use <literal>scp</literal> from your development
279 machine to deploy your artifacts on the guest, by giving the host
280 port for forwarding as a command parameter: <programlisting>scp -P 1050 helloworld root@target_ip_address:/tmp</programlisting></para>
281 </listitem>
282
283 <listitem>
284 <para>On the host, after finishing the deployment session and
285 stopping the virtual machine, you can use the
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>
294 </section>
295
296 <section id="crossdebugging">
297 <title>Cross-Debugging on Enea NFV Access</title>
298
299 <para>The cross-debugger (<literal>x86_64-enea-linux-gdb</literal>) is
300 created when installing the SDK on the development machine. It is helpful
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
305 <itemizedlist>
306 <listitem>
307 <para>Kgdb &ndash; for kernel cross-debugging</para>
308 </listitem>
309
310 <listitem>
311 <para>GDBServer &ndash; for application cross-debugging</para>
312 </listitem>
313 </itemizedlist>
314
315 <para>The Host Development image provides both of these tools and has to
316 be booted on the target machine for cross-debugging sessions.</para>
317
318 <section id="ua_debug_host">
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
338 <section id="us_debug_guest">
339 <title>User-application Cross-Debugging on Guest</title>
340
341 <para>To debug a user-application on guest, a TCP connection has to be
342 established between the host and development machines. Similarly, as
343 when deploying artifacts on guest, for a cross-debugging session, TAP
344 Networking is required.</para>
345
346 <para>A tap interface should be added to the existing virtual bridge
347 (<literal>virbr0</literal>), along with port forwarding rules created in
348 iptables. In order to do this, the script
349 <filename>/etc/qemu-ifup</filename> can pe used:</para>
350
351 <orderedlist>
352 <listitem>
353 <para>On the host, run the script <literal>qemu-ifup</literal>
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>
355
356 <itemizedlist>
357 <listitem>
358 <para><emphasis role="bold">tap0</emphasis> - the tap interface
359 name which will be created and added to virtual bridge
360 (virbr0).</para>
361 </listitem>
362
363 <listitem>
364 <para><emphasis role="bold">192.168.122.10</emphasis> - the IP
365 address of the guest virtual network device. It has to be in the
366 same network with the IP address of the virbr0 interface.</para>
367 </listitem>
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>
381
382 <listitem>
383 <para>Launch the virtual machine, specifying the newly created tap
384 interface:<programlisting>-device e1000,netdev=net0 \
385-netdev tap,id=net0,ifname=tap0,script=no,downscript=no</programlisting></para>
386 </listitem>
387
388 <listitem>
389 <para>On the guest, after logging, configure the virtual network
390 device and set the default gateway to virbr0 ip
391 address:<programlisting>ip addr add 192.168.122.10/24 dev enp0s2
392ip link set enp0s2 up
393ip route add default via 192.168.122.1 dev enp0s2</programlisting></para>
394 </listitem>
395
396 <listitem>
397 <para>GDBserver is the program which runs on the guest VM and allows
398 you to run GDB on your workstation. On the guest, launch GBDserver
399 specifying how to communicate with GDB and the name of your program:
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>
404
405 <listitem>
406 <para>On the development machine, from the<filename>
407 &lt;sdkdir&gt;</filename>, start the cross-gdb:<programlisting># x86_64-enea-linux-gdb &lt;path_to_the_program&gt;/helloworld</programlisting></para>
408 </listitem>
409
410 <listitem>
411 <para>Connect GDB to the target:<programlisting>(gdb) target remote &lt;target_ip_address&gt;:1051</programlisting>Now
412 remote debugging is started and the GDB commands are available to
413 debug your program from the guest VM.</para>
414 </listitem>
415
416 <listitem>
417 <para>On the host, after finishing the cross-debugging session and
418 stopping the virtual machine, you can use the
419 <filename>qemu-ifdown</filename> script to clean up the
420 configuration on host:<programlisting># /etc/qemu-ifdown -t tap0 -a 192.168.122.10</programlisting></para>
421 </listitem>
422 </orderedlist>
423 </section>
424
425 <section id="kernel_crossdebug">
426 <title>Kernel Cross-Debugging</title>
427
428 <para>In order to debug the kernel, a serial connection is required
429 between the development and target machines. Debugging commands will be
430 sent from your workstation to the target machine via a serial
431 port.</para>
432
433 <para>The KGDB kernel options are enabled in the Enea NFV Access Host
434 SDK image and the tool can be used in the following way:</para>
435
436 <itemizedlist>
437 <listitem>
438 <para>On target, once serial communication is established, configure
439 <literal>kgdboc</literal> after the kernel boots:<programlisting># echo ttyS0,115200 &gt; /sys/module/kgdboc/parameters/kgdboc</programlisting></para>
440 </listitem>
441
442 <listitem>
443 <para>In order to connect to gdb via kgdboc, the kernel must first
444 be stopped:<programlisting># echo g &gt; /proc/sysrq-trigger</programlisting></para>
445 </listitem>
446
447 <listitem>
448 <para>Close the console to the target, eg.: <command>Ctrl +
449 ]</command> for a telnet session.</para>
450 </listitem>
451
452 <listitem>
453 <para>On your development machine, start cross-gdb using the vmlinux
454 kernel image as a parameter. The image is located in
455 <filename>&lt;sdkdir&gt;/sysroots/corei7-64-enea-linux/boot/</filename>
456 and should be the same as the image found in the
457 <literal>/boot</literal> directory from the target.<programlisting># x86_64-enea-linux-gdb /
458./sysroots/corei7-64-enea-linux/boot/vmlinux-4.9.30-intel-pk-standard</programlisting></para>
459 </listitem>
460
461 <listitem>
462 <para>Connect GDB to the target machine using target command and the
463 serial device:<programlisting>(gdb) set remotebaud 115200
464(gdb) target remote /dev/ttyS0</programlisting></para>
465 </listitem>
466 </itemizedlist>
467
468 <para>The kernel can now be debugged in a similar manner as an
469 application program.</para>
470 </section>
471 </section>
472</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-guide-intel/swcomp.mk b/doc/book-enea-nfv-access-guide-intel/swcomp.mk
new file mode 100644
index 0000000..0d205f3
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide-intel/swcomp.mk
@@ -0,0 +1,10 @@
1# Component build specification
2
3# Version of THIS book
4BOOK_VER ?= $(REL_VER)-dev
5
6DOCBOOK_SRC := $(COMP)/swcomp.mk $(COMP)/doc/book.xml $(shell find $(COMP)/doc -type f \( -name "*.xml" -o -name "*.svg" -o -name "*.png" \) ! -name "book.xml" -print)
7
8BOOKPACKAGES := book-enea-nfv-access-guide
9BOOKDESC_$(BOOKPACKAGES) := "Enea NFV Access $(PROD_VER) Guide"
10BOOKDEFAULTCONDITION := $(DEFAULTCONDITIONS)
diff --git a/doc/book-enea-nfv-access-guide/doc/getting_started.xml b/doc/book-enea-nfv-access-guide/doc/getting_started.xml
index ed74f48..b6cf927 100644
--- a/doc/book-enea-nfv-access-guide/doc/getting_started.xml
+++ b/doc/book-enea-nfv-access-guide/doc/getting_started.xml
@@ -5,254 +5,332 @@
5 <title>Getting Started with Enea NFV Access</title> 5 <title>Getting Started with Enea NFV Access</title>
6 6
7 <para>Using Enea NFV Access requires access to a Linux machine, which is 7 <para>Using Enea NFV Access requires access to a Linux machine, which is
8 used for preparing the bootable drive or for developing applications. System 8 used for preparing a bootable drive or for developing applications. System
9 requirements for the development host are detailed in the <xi:include 9 requirements for the development host are detailed in the <xi:include
10 href="../../s_docbuild/olinkdb/pardoc-common.xml" 10 href="../../s_docbuild/olinkdb/pardoc-common.xml"
11 xmlns:xi="http://www.w3.org/2001/XInclude" 11 xmlns:xi="http://www.w3.org/2001/XInclude"
12 xpointer="element(book_enea_nfv_access_release_info/1)" /> document included 12 xpointer="element(book_enea_nfv_access_release_info/1)" />.</para>
13 with this release.</para>
14 13
15 <section id="sysshell_config"> 14 <section id="sysshell_config">
16 <title>System Shell Configuration</title> 15 <title>Default Shell Configuration</title>
17 16
18 <para>Before installing Enea NFV Access, ensure that bash is the default 17 <para>Before installing Enea NFV Access, make sure that bash is the
19 shell.</para> 18 default shell.</para>
20 19
21 <para>If your system runs Ubuntu, you can use ls -l to ensure 20 <para><emphasis role="bold">To verify the default system
22 <filename>/usr/bin</filename> is a symbolic link to bash. In case the link 21 shell</emphasis></para>
23 points to dash, which is default in some Ubuntu versions, change it to
24 bash by running <emphasis role="bold">sudo dpkg-reconfigure
25 dash</emphasis> and answer <emphasis role="bold">No</emphasis> to the
26 question <literal>Use dash as the default system shell
27 (/bin/sh)?</literal>:</para>
28 22
29 <programlisting># ls -l /bin/sh 23 <itemizedlist>
24 <listitem>
25 <para>If your system runs Ubuntu, use list to verify if
26 <filename>/usr/bin</filename> is a symbolic link to <emphasis
27 role="bold">bash</emphasis>:</para>
28
29 <programlisting># ls -l /bin/sh
30lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; bash</programlisting> 30lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; bash</programlisting>
31 </listitem>
32
33 <listitem>
34 <para>Optionally, in case the link points to <literal>dash</literal>,
35 change it through the following steps:</para>
36
37 <programlisting># ls -l /bin/sh
38lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; dash
39# sudo dpkg-reconfigure dash
40Use dash as the default system shell (/bin/sh)? No</programlisting>
41 </listitem>
42 </itemizedlist>
31 </section> 43 </section>
32 44
33 <section id="access_installer"> 45 <section id="access_installer">
34 <title>Enea NFV Access Installer</title> 46 <title>Enea NFV Access Installer</title>
35 47
36 <para>The easiest way to get up and running with Enea NFV Access is to use 48 <para>The easiest way to get started with Enea NFV Access is by using the
37 the installer provided in the install directory for each supported 49 installer provided for each supported architecture in this release. Each
38 architecture in this release. The purpose of this installer is to guide 50 installer guides you in the creation of a bootable Enea NFV Access
39 you through creating a bootable Enea NFV Access installation on a physical 51 installation on a physical media.</para>
40 media (e.g. USB stick or HDD).</para>
41 52
42 <section id="installer_prereq"> 53 <section id="prereq">
43 <title>Installer Prerequisites</title> 54 <title>Prerequisites</title>
44 55
45 <para>Using the installer on the development host requires the 56 <para>The following files are needed on the development host
46 following:</para> 57 machine:</para>
47 58
48 <itemizedlist> 59 <itemizedlist>
49 <listitem> 60 <listitem>
50 <para>a GRUB .efi binary</para> 61 <para>A GRUB.efi binary - available from the <ulink url="???">GNU
62 GRUB download page</ulink>.</para>
51 </listitem> 63 </listitem>
52 64
53 <listitem> 65 <listitem>
54 <para>a physical drive of 16GB or larger</para> 66 <para>For booting from an SSD/HDD: a rootfs that needs to be
67 installed on the board (e.g.
68 <filename>[path_to_EneaNFV_Access_folder]/[architecture]/inteld1521/images/enea-nfv-access/enea-nfv-access.tar.gz</filename>).</para>
55 </listitem> 69 </listitem>
56 70
57 <listitem> 71 <listitem>
58 <para>For USB booting you will need: a development based rootfs, 72 <para>For USB booting: a development based rootfs (e.g.
59 provided with the release (e.g. 73 <filename>[path_to_EneaNFV_Access_folder]/[architecture]/inteld1521/images/enea-nfv-access-dev/enea-nfv-access-dev-inteld1521.tar.gz</filename>).</para>
60 <filename>enea-nfv-access-dev-inteld1521.tar.gz</filename>).</para>
61 </listitem> 74 </listitem>
75 </itemizedlist>
62 76
77 <para>Using the installer on the development host requires the
78 following:</para>
79
80 <itemizedlist>
63 <listitem> 81 <listitem>
64 <para>For booting from an SSD or HDD you will need: any rootfs that 82 <para>A physical drive of 16GB or larger</para>
65 needs to be installed on the board, provided with the release (e.g. 83 </listitem>
66 <filename>enea-nfv-access.tar.gz</filename>).</para> 84
85 <listitem>
86 <para>Root permissions</para>
67 </listitem> 87 </listitem>
68 </itemizedlist> 88 </itemizedlist>
69 </section> 89 </section>
70 90
71 <section id="installer_usage"> 91 <section id="installer_setup_usage">
72 <title>Installer Usage</title> 92 <title>Installer Setup and Usage</title>
73 93
74 <para>The <emphasis role="bold">Enea NFV Access installer</emphasis> 94 <para><emphasis role="bold">To install Enea NFV Access on a physical
75 shall be executed on the development host machine with root permissions. 95 drive</emphasis></para>
76 Once the <filename>nfv_installer</filename> prompt is displayed, press
77 <literal>ENTER</literal> to get the full list of built-in
78 commands:</para>
79
80 <programlisting>help - a guide on how to use the installer
81list-params - lists parameters
82list-steps - lists the available steps and the parameters that they depend on
83set - sets a parameter (e.g. "set drive=/dev/sda")
84clear - clears a parameter (e.g. "clear drive")
85list-partitions - lists current drives and partitions
86dry - describes the steps to be executed and checks if the files exist
87run - executes the steps
88q or quit - exits the script</programlisting>
89
90 <para>Enea NFV Access creates a bootable media by performing these
91 steps:</para>
92 96
93 <orderedlist> 97 <orderedlist>
94 <listitem> 98 <listitem>
95 <para>Create two partitions on a designated drive (e.g. 99 <para>Go to the installer location: <programlisting># cd [path_to_EneaNFV_Access_folder]/[architecture]/install/
96 /dev/sda):</para> 100nfv-installer/script-installer</programlisting></para>
101 </listitem>
102
103 <listitem>
104 <para>Execute the script file, this will bring you to the installer
105 prompt: <programlisting># sudo ./nfv_installer.sh</programlisting></para>
106 </listitem>
107
108 <listitem>
109 <para>Optionally, press ENTER to see the list of available
110 commands:<programlisting>help - displays a guide on how to use the installer
111list-params - lists all available parameters
112list-steps - lists the installer steps and the parameters that they depend on
113set - sets a parameter (e.g. <literal>set drive=/dev/sda</literal>)
114clear - clears a parameter (e.g. <literal>clear drive</literal>)
115list-partitions - lists current drives and partitions
116dry - performs a simulation test run
117run - executes the installer, using the values you set for each parameter
118q or quit - exits the script</programlisting></para>
119 </listitem>
120
121 <listitem>
122 <para>Set the required parameters depending on what steps you want
123 to run:</para>
124
125 <note>
126 <para>When using the installer for the first time, make sure to
127 set ALL parameters in order to be able to run all steps. See <xref
128 linkend="example_two">
129 "Example 2"
130 </xref> for details.</para>
131 </note>
132
133 <para><programlisting># set &lt;parameter_name&gt;=&lt;parameter_value&gt;</programlisting></para>
134
135 <orderedlist>
136 <listitem>
137 <para><parameter>drive=&lt;/dev/sdaX&gt;</parameter> - the drive
138 to partition</para>
139 </listitem>
140
141 <listitem>
142 <para><parameter>grub_binary=&lt;file&gt;</parameter> - points
143 to the <filename>GRUB</filename> executable to be installed
144 where <filename>grub_destination</filename> is set.</para>
145 </listitem>
146
147 <listitem>
148 <para><parameter>grub_destination=&lt;drive&gt;</parameter> -
149 specifies the partition where <filename>GRUB</filename> will be
150 installed</para>
151 </listitem>
97 152
98 <itemizedlist>
99 <listitem> 153 <listitem>
100 <para>a 512MB partition for GRUB</para> 154 <para><parameter>rootfs_destination=&lt;drive&gt;</parameter> -
155 specifies the partition where the <filename>rootfs</filename>
156 will be deployed, used by <filename>GRUB</filename> to boot off
157 of.</para>
101 </listitem> 158 </listitem>
102 159
103 <listitem> 160 <listitem>
104 <para>the rest of the drive is reserved for the rootfs</para> 161 <para><parameter>rootfs_targz=&lt;rootfs.tar.gz
162 file&gt;</parameter> - the archive of the Enea NFV Access
163 <filename>rootfs</filename> you wish to unpack to where
164 <filename>rootfs_destination</filename> is set. Which file you
165 unpack depends on whether you booting from an SSD/HDD or from a
166 USB drive.</para>
105 </listitem> 167 </listitem>
106 </itemizedlist> 168 </orderedlist>
107 </listitem> 169 </listitem>
108 170
109 <listitem> 171 <listitem>
110 <para>Configure GRUB on one partition (usually the first 172 <para>Optionally, perform a test run before affecting the actual
111 one).</para> 173 layout of the physical media with the command: <programlisting>dry</programlisting></para>
112 </listitem> 174 </listitem>
113 175
114 <listitem> 176 <listitem>
115 <para>Copy a root filesystem on the other partition.</para> 177 <para>Run the installer: <programlisting>run</programlisting></para>
116 </listitem> 178 </listitem>
117 </orderedlist>
118 179
119 <note> 180 <listitem>
120 <para>Running step 3 will implicitly copy the installer on that root 181 <para>Exit the script: <programlisting>quit</programlisting></para>
121 filesystem in 182 </listitem>
122 <filename>/usr/bin/install_nfvaccess.sh.</filename></para> 183 </orderedlist>
123 </note>
124 184
125 <para>Each step mentioned above is executed or not depending on whether 185 <para>The Enea NFV Access installer creates a bootable media by
126 certain parameters are set. Run the 186 performing three steps. Each step is executed or not depending on
127 <command><literal>list-steps</literal></command> command in order to 187 whether certain parameters are set:</para>
128 understand the built-in steps that the installer can execute and what
129 parameters they depend on. The command will print the following:</para>
130 188
131 <orderedlist> 189 <orderedlist>
132 <listitem> 190 <listitem>
133 <para><command>Format drive</command> - Uses the drive set for the 191 <para><command>Format drive</command> - creates a 512MB partition
134 <literal>drive</literal> parameter to create a 512MB partition for 192 which will be used by <filename>GRUB</filename>, and another to be
135 GRUB and another partition for the rootfs. The rootfs partition will 193 used for the <filename>rootfs</filename> (it should occupy the rest
136 be as large as the physical media minus 512MB. This step depends on 194 of the physical media minus the first partition). This step depends
137 the following parameter(s): <programlisting>drive=</programlisting></para> 195 on the following parameter(s): <programlisting>drive=</programlisting></para>
138 </listitem> 196 </listitem>
139 197
140 <listitem> 198 <listitem>
141 <para><emphasis role="bold">GRUB install</emphasis> - Installs the 199 <para><emphasis role="bold">GRUB install</emphasis> - Installs the
142 binary pointed to by <literal>grub_binary</literal> on the drive set 200 <literal>grub_binary</literal> on the drive set for
143 in <literal>grub_destination</literal>. A 201 <literal>grub_destination</literal>. A <filename>grub.cfg</filename>
144 <filename>grub.cfg</filename> file will be created that will be 202 file will be created that will be configured to boot off of
145 configured to boot off of <literal>rootfs_destination</literal>. 203 <literal>rootfs_destination</literal>. This step depends on the
146 This step depends on the following parameters:<programlisting>grub_destination= 204 following parameters:<programlisting>grub_destination=
147grub_binary= 205grub_binary=
148rootfs_destination=</programlisting></para> 206rootfs_destination=</programlisting></para>
149 </listitem> 207 </listitem>
150 208
151 <listitem> 209 <listitem>
152 <para><emphasis role="bold">Root filesystem install</emphasis> - 210 <para><emphasis role="bold">Root Filesystem install</emphasis> -
153 Copies the files found in <literal>rootfs_targz</literal> to the 211 Copies and unpacks the files found in
154 drive set in <literal>rootfs_destination</literal>. This step 212 <literal>rootfs_targz</literal> to the
155 depends on the following parameters:<programlisting>rootfs_targz= 213 <literal>rootfs_destination</literal>. This step depends on the
214 following parameters:<programlisting>rootfs_targz=
156rootfs_destination=</programlisting></para> 215rootfs_destination=</programlisting></para>
157 </listitem> 216 </listitem>
158 </orderedlist> 217 </orderedlist>
159 218
160 <para>Parameters can be set through the <command>set</command> command 219 <para>After using the installer and setting up the bootable media,
161 or cleared using the <command>clear</command> command. Since some 220 connect it to the target machine and configure the target machine to use
162 parameters are common for multiple steps, as is 221 it as a primary boot device.</para>
163 <literal>rootfs_destination</literal> for the GRUB and rootfs 222 </section>
164 installation steps, you can get a list of all the parameters, by running 223
165 <literal>list-params</literal>.</para> 224 <section id="examples">
166 225 <title>Examples of Execution</title>
167 <para>The following parameters can be configured:<programlisting>grub_destination=[drive] - specifies the drive where GRUB will be installed 226
168grub_binary=[file] - points to the GRUB executable to be installed 227 <para>Below are a few examples of setups that the Enea NFV Access
169 where grub_destination is set 228 installer can be used for:</para>
170rootfs_destination=[drive] - specifies where the rootfs will be deployed 229
171rootfs_targz=[.tar.gz file] - what file to unpack to where rootfs_destination is set 230 <example id="example_one">
172drive=[/dev/sdaX] - what drive to partition</programlisting></para> 231 <title>Partitioning a drive</title>
173 232
174 <para>Before performing the actual partitioning and copying, a dry run, 233 <programlisting>set drive=/dev/sda
175 using the <command>dry</command> command, can be executed without 234run</programlisting>
176 affecting the actual layout of the physical media. Once all the 235 </example>
177 parameters are set according to the intended scenario, simply execute 236
178 the <command>run</command> command to set up the bootable media. Below 237 <example id="example_two">
179 are a few examples of how the Enea NFV Access installer may be 238 <title>Partitioning a drive, installing GRUB and a Root
180 used.</para> 239 Filesystem:</title>
181 240
182 <para>Example of partitioning a drive:<programlisting>set drive=/dev/sda 241 <programlisting>set drive=/dev/sda
183run</programlisting></para>
184
185 <para>Example of partitioning a drive, installing GRUB and a root
186 filesystem:<programlisting>set drive=/dev/sda
187set grub_destination=/dev/sda1 242set grub_destination=/dev/sda1
188set grub_binary=/home/user/grub-binary.efi 243set grub_binary=/home/user/grub-binary.efi
189set rootfs_destination=/dev/sda2 244set rootfs_destination=/dev/sda2
190set rootfs_targz=/home/user/rootfs.tar.gz 245set rootfs_targz=/home/user/rootfs.tar.gz
191run</programlisting></para> 246run</programlisting>
247 </example>
192 248
193 <para>Example of deploying ONLY a root filesystem:<programlisting>set rootfs_destination=/dev/sda2 249 <example id="example_three">
194set rootfs_targz=/home/user/rootfs.tar.gz 250 <title>Deploying ONLY a root filesystem:</title>
195runs</programlisting></para>
196 251
197 <para>After using the installer and setting up the bootable media, 252 <programlisting>set rootfs_destination=/dev/sda2
198 connect it to the target machine and configure the target machine to use 253set rootfs_targz=/home/user/rootfs.tar.gz
199 it as a primary boot device.</para> 254run</programlisting>
255 </example>
200 </section> 256 </section>
201 257
202 <section id="troubleshooting"> 258 <section id="troubleshooting">
203 <title>Troubleshooting</title> 259 <title>Troubleshooting</title>
204 260
205 <para>GRUB might display the following: <literal>error: no such 261 <para>GRUB might display the following errors if the default
206 partition</literal> or <filename>error: disk not found</filename>, if 262 configuration is set to use <filename>hd0</filename> as the primary
207 the default GRUB config is set to use <filename>hd0</filename> as the 263 drive for booting:</para>
208 primary drive for booting. Due to this, the errors described above have 264
209 two possible causes:</para> 265 <itemizedlist>
266 <listitem>
267 <para><literal>error: no such partition</literal></para>
268 </listitem>
269
270 <listitem>
271 <para><literal>error: disk not found</literal></para>
272 </listitem>
273 </itemizedlist>
274
275 <para>These errors have two possible causes:</para>
210 276
211 <itemizedlist> 277 <itemizedlist>
212 <listitem> 278 <listitem>
213 <para>The drive where Enea NFV Access was installed is not 279 <para>The drive where Enea NFV Access was installed is not
214 identified as <literal>hd0</literal> by the BIOS.</para> 280 identified as <literal>hd0</literal> by BIOS.</para>
215 </listitem> 281 </listitem>
216 282
217 <listitem> 283 <listitem>
218 <para>The BIOS has assigned the <literal>hd0</literal> label to a 284 <para>BIOS has assigned the <literal>hd0</literal> label to a
219 different drive (e.g. a USB stick) than the one where Enea NFV 285 different drive (e.g. a USB stick) than the one where Enea NFV
220 Access was installed.</para> 286 Access was installed.</para>
221 </listitem> 287 </listitem>
222 </itemizedlist> 288 </itemizedlist>
223 289
224 <para>The solution for these errors is detailed below:</para> 290 <para>To rectify these problems the primary boot drive must be assigned
291 to the correct partition.</para>
292
293 <para><emphasis role="bold">To change the partition for the primary boot
294 drive</emphasis></para>
225 295
226 <orderedlist> 296 <orderedlist>
227 <listitem> 297 <listitem>
228 <para>In the GRUB selection screen press 298 <para>Restart the host and in the <filename>GRUB</filename>
229 <command><literal>c</literal></command> to enter the command 299 selection screen, enter the command line by pressing
230 line.</para> 300 <command>C</command>:</para>
301
302 <mediaobject>
303 <imageobject>
304 <imagedata align="center" contentwidth="600"
305 fileref="images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg" />
306 </imageobject>
307 </mediaobject>
231 </listitem> 308 </listitem>
232 309
233 <listitem> 310 <listitem>
234 <para>Run <command>ls</command> to list all of the available 311 <para>List all of the available partitions with
235 partitions</para> 312 <command>ls</command>: <programlisting>partition list example</programlisting></para>
236 </listitem> 313 </listitem>
237 314
238 <listitem> 315 <listitem>
239 <para>For each available partition run <command>ls 316 <para>In order to identify where Enea NFV Access was installed, for
240 PARTITION</command> in order to identify where Enea NFV Access was 317 each available partition run <emphasis role="bold">ls
241 installed.</para> 318 &lt;partition&gt;</emphasis>: <programlisting>ls hd0</programlisting></para>
242 </listitem> 319 </listitem>
243 320
244 <listitem> 321 <listitem>
245 <para>After identifying the partition, press <command>ESC</command> 322 <para>After identifying the partition, return to the GRUB selection
246 to return to the GRUB selection screen and press 323 screen by pressing <command>esc</command></para>
247 <command>e</command> to edit the boot command.</para>
248 </listitem> 324 </listitem>
249 325
250 <listitem> 326 <listitem>
251 <para>Set the boot partition to the one identified in step 3</para> 327 <para>Press <command>e</command> to edit and set the boot partition
328 to the one identified previously: <programlisting>edit and set partition example</programlisting></para>
252 </listitem> 329 </listitem>
253 330
254 <listitem> 331 <listitem>
255 <para>Press <literal>F10</literal> to boot</para> 332 <para>To reboot to see if the change worked, press:
333 <command>F10</command></para>
256 </listitem> 334 </listitem>
257 </orderedlist> 335 </orderedlist>
258 </section> 336 </section>
diff --git a/doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.png b/doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.png
new file mode 100644
index 0000000..c28d643
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.png
Binary files differ
diff --git a/doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg b/doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg
new file mode 100644
index 0000000..319bf7e
--- /dev/null
+++ b/doc/book-enea-nfv-access-guide/doc/images/select-linux-kernel-in-grub2-boot-loader-on-ubuntu-14.04.svg
@@ -0,0 +1,3 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
3<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid meet" viewBox="0 0 640 640" width="640" height="640"><defs><path d="M0 93L640 93L640 547L0 547L0 93Z" id="b4lgbdl3I5"></path><clipPath id="clipbKzvApRlV"><use xlink:href="#b4lgbdl3I5" opacity="1"></use></clipPath></defs><g><g><g><g clip-path="url(#clipbKzvApRlV)" opacity="1"><image xlink:href="data:image/png;base64,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" x="0" y="0" width="640" height="454" transform="matrix(1 0 0 1 1.1368683772161603e-13 93.00000000000006)"></image></g></g></g></g></svg> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/about_release.xml b/doc/book-enea-nfv-access-release-info-intel/doc/about_release.xml
new file mode 100644
index 0000000..b76f3ff
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/about_release.xml
@@ -0,0 +1,272 @@
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="relinfo-about-release">
5 <title>About This Release</title>
6
7 <para>Enea NFV Access <xi:include href="eltf_params_updated.xml"
8 xmlns:xi="http://www.w3.org/2001/XInclude"
9 xpointer="element(EneaLinux_REL_VER/1)" /> is a maintenance update to Enea
10 NFV Access 1.0 with the major changes listed below:<remark>INFO <emphasis
11 role="bold">eltf_params_updated.xml</emphasis> contains many parameters in
12 the book, also in the open source books, and MUST be created FROM <emphasis
13 role="bold">eltf_params_template.xml</emphasis>. The parameters are
14 automatically used in the books, via xi:include statements, similar to how
15 parameters from pardoc-distro.xml are included in the book. Read the file
16 <emphasis role="bold">eltf_params_updated_template_how_to_use.txt</emphasis>
17 for important details about formats and how to do! The idea is that ELTF
18 will auto-create/update it.</remark></para>
19
20 <itemizedlist>
21 <listitem>
22 <para>Key Component updates:</para>
23
24 <itemizedlist>
25 <listitem>
26 <para>DPDK 17.08</para>
27 </listitem>
28
29 <listitem>
30 <para>OVS 2.8</para>
31 </listitem>
32 </itemizedlist>
33 </listitem>
34
35 <listitem>
36 <para>Feature Extensions:</para>
37
38 <itemizedlist>
39 <listitem>
40 <para>Element ODM: FCAPS framework with NETCONF and Yang.</para>
41 </listitem>
42
43 <listitem>
44 <para>EdgeLink Netconf (beta): NETCONF based VNF lifecycle
45 Management Tool.</para>
46 </listitem>
47 </itemizedlist>
48 </listitem>
49
50 <listitem>
51 <para>Extended Tools Feature Set:</para>
52
53 <itemizedlist>
54 <listitem>
55 <para>python-pip</para>
56 </listitem>
57
58 <listitem>
59 <para>dosfstools</para>
60 </listitem>
61
62 <listitem>
63 <para>htop</para>
64 </listitem>
65 </itemizedlist>
66 </listitem>
67
68 <listitem>
69 <para>Unified cross-development SDK for host and virtualized
70 environments.</para>
71 </listitem>
72
73 <listitem>
74 <para>Native toolchain support on development image.</para>
75 </listitem>
76
77 <listitem>
78 <para>USB-stick based installation</para>
79 </listitem>
80
81 <listitem>
82 <para>Product Maintenance:</para>
83
84 <itemizedlist>
85 <listitem>
86 <para>Optimizations</para>
87 </listitem>
88
89 <listitem>
90 <para>Security patches</para>
91 </listitem>
92
93 <listitem>
94 <para>Bug fixes</para>
95 </listitem>
96
97 <listitem>
98 <para>Updated documentation</para>
99 </listitem>
100 </itemizedlist>
101 </listitem>
102 </itemizedlist>
103
104 <section id="release-content">
105 <title>Enea NFV Access Release Content</title>
106
107 <para>The current release contains along with other items, documentation,
108 pre-built kernels and images, a bootloader and a SDK. The directories
109 structure is detailed below:</para>
110
111 <programlisting>-- documentation/
112 /* Enea NFV Access documentation */
113-- x86-64 /* architecture */
114 -- inteld1521/
115 /* artifacts for the host side */
116 -- deb/
117 /* deb packages */
118 -- images/
119 -- enea-nfv-access
120 /* precompiled artifacts for the platform release image */
121 -- various artifacts (rootfs, kernel, config etc.)
122 -- enea-nfv-access-dev
123 /* precompiled artifacts for the development process. The image
124 contains userspace tools and kernel configurations necessary
125 for developing, debugging and profiling applications and
126 kernel modules */
127 -- various artifacts
128 -- qemux86-64
129 /* artifacts for the guest side */
130 -- deb/
131 /* deb packages */
132 -- images/
133 -- enea-nfv-access-guest
134 /* precompiled artifacts for the QEMU/Docker release image */
135 -- various artifacts
136 -- enea-nfv-access-guest-dev
137 /* precompiled artifacts for the development process. The image
138 contains userspace tools and kernel configurations necessary
139 for developing, debugging and profiling applications and
140 kernel modules */
141 -- various artifacts
142 -- install
143 -- sdk
144 /* SDK related artifacts including SDK installer and manifests */
145 -- install-sdk.sh
146 /* self-extracting archive installing cross-compilation
147 toolchain for the platform */
148 -- nfv-installer
149 /* Various tools assisting in booting Enea NFV Access */
150 -- script-installer
151 /* installer tool intended for creating a bootable Enea
152 NFV Access installation on a physical media */</programlisting>
153
154 <para>For each combination of image and target, the following set of
155 artifacts is available:</para>
156
157 <programlisting>-- bzImage
158 /* kernel image */
159-- bzImage-target.bin
160 /* kernel image, same as above */
161-- config-target.config
162 /* kernel configuration file */
163-- image-name-target.ext4.gz
164 /* compressed EXT4 image of the rootfs */
165-- image-name-target.qcow2
166 /* QCOW image for QEMU - only for guest images */
167-- image-name-target.qemuboot.conf
168 /* qemu config file for the guest images */
169-- image-name-target.tar.gz
170 /* tar archive of the image */
171-- modules-&lt;target&gt;.tgz
172 /* external kernel modules */
173-- grub-efi-bootx64.efi
174 /* GRUB EFI file */</programlisting>
175 </section>
176
177 <section id="relinfo-supported-host-environment">
178 <title>Supported Host Environment</title>
179
180 <para>The following environments have been validated as host environments
181 for Enea NFV Access 1.1: <emphasis role="bold">Ubuntu 16.04 LTS,
182 64bit</emphasis>.</para>
183
184 <para><remark>Hardcoded now in this XML file. Might be moved to the
185 parameter file later.</remark> <remark>INFO Below is a complete section
186 with ID "eltf-target-tables-section" included from
187 elft_params_updated.xml. It contains a variable number of target tables
188 and the section title should be "Supported Targets with Parameters". It
189 has have a short sentence about what it is in the beginning. The subtitles
190 shall have the directory name of the target in the manifest.</remark>For
191 more details on host requirements and how to configure the host
192 environment, please see <xref linkend="sys-req-prerequisites" />.</para>
193 </section>
194
195 <xi:include href="eltf_params_updated.xml"
196 xmlns:xi="http://www.w3.org/2001/XInclude"
197 xpointer="element(eltf-target-tables-section)" />
198
199 <section id="relinfo-provided-sdk">
200 <title>Provided Toolchain(s) (SDK)</title>
201
202 <para>The provided SDK contains toolchains supporting cross-compilation of
203 applications for both the host and the guest targets on an x86-64
204 machine.</para>
205
206 <para><remark>(Possibly add this in later) See the <trademark
207 class="registered">Enea</trademark> NFV Access Application Development
208 Guide for information on how to build and install a
209 toolchain.</remark></para>
210 </section>
211
212 <section id="relinfo-documentation">
213 <title>Provided Documentation</title>
214
215 <para>Enea NFV Access is provided with the following set of
216 documents:</para>
217
218 <itemizedlist>
219 <listitem>
220 <para>Enea NFV Access Release Information - This document, describing
221 the Enea NFV Access release content.</para>
222 </listitem>
223
224 <listitem>
225 <para>Enea NFV Access Guide - A document describing how to use Enea
226 NFV Access, as well as use cases and benchmark results.</para>
227 </listitem>
228
229 <listitem>
230 <para>Enea NFV Access Open Source Report - A document containing the
231 open source and license information pertaining to packages provided
232 with Enea NFV Access.</para>
233 </listitem>
234
235 <listitem>
236 <para>Enea NFV Access Development Open Source Report - A document
237 containing open source and license information pertaining to packages
238 provided with Enea NFV Access for application developers.</para>
239 </listitem>
240
241 <listitem>
242 <para>Enea NFV Access Guest Open Source Report - A document containing
243 open source and license information concerning packages provided with
244 Enea NFV Access for a guest target.</para>
245 </listitem>
246
247 <listitem>
248 <para>Enea NFV Access Guest Development Open Source Report - A
249 document detailing the open source and license information of packages
250 provided with Enea NFV Access for applications development on a guest
251 target.</para>
252 </listitem>
253
254 <listitem condition="hidden">
255 <para>Enea NFV Access Test Report - The document that summarizes the
256 test results for the Enea NFV Access release.</para>
257 </listitem>
258
259 <listitem>
260 <para>Enea NFV Access Security Report - The document that lists all
261 security fixes included in the Enea NFV Access release.</para>
262 </listitem>
263 </itemizedlist>
264 </section>
265
266 <section id="security_fixes">
267 <title>Security Fixes</title>
268
269 <para>A detailed list of all security patches included with this release
270 is available in the Enea NFV Access Security Report document.</para>
271 </section>
272</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/book.xml b/doc/book-enea-nfv-access-release-info-intel/doc/book.xml
new file mode 100644
index 0000000..1ce7046
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/book.xml
@@ -0,0 +1,36 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4<!ENTITY % local.common.attrib "xml:base CDATA #IMPLIED">
5]>
6<book id="book_enea_nfv_access_release_info">
7 <title><trademark class="registered">Enea</trademark> NFV Access Release
8 Information</title>
9
10 <subtitle>Release Version <xi:include href="eltf_params_updated.xml"
11 xmlns:xi="http://www.w3.org/2001/XInclude"
12 xpointer="element(EneaLinux_REL_VER/1)" /></subtitle>
13
14 <!-- OLINKDBPATH_USED_BY_XMLMIND ../../s_docbuild/olinkdb -->
15
16 <xi:include href="../../s_docbuild/template/docsrc_common/bookinfo_userdoc.xml"
17 xmlns:xi="http://www.w3.org/2001/XInclude" />
18
19 <xi:include href="about_release.xml"
20 xmlns:xi="http://www.w3.org/2001/XInclude" />
21
22 <xi:include href="system_requirements_prerequisites.xml"
23 xmlns:xi="http://www.w3.org/2001/XInclude" />
24
25 <xi:include href="getting_enea_nfv_access.xml"
26 xmlns:xi="http://www.w3.org/2001/XInclude" />
27
28 <xi:include href="main_changes.xml"
29 xmlns:xi="http://www.w3.org/2001/XInclude" />
30
31 <xi:include href="known_bugs_and_limitations.xml"
32 xmlns:xi="http://www.w3.org/2001/XInclude" />
33
34 <xi:include href="../../s_docbuild/template/docsrc_common/contacting_enea_enea_linux.xml"
35 xmlns:xi="http://www.w3.org/2001/XInclude" />
36</book> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_template.xml b/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_template.xml
new file mode 100644
index 0000000..eaa7ebd
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_template.xml
@@ -0,0 +1,151 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<section id="eltf_created_params">
5 <title>File with Parameters in the Book Auto-updated by ELFT</title>
6
7 <note>
8 <para>See the <emphasis
9 role="bold">eltf_params_updated_template_howto_use.txt</emphasis> text
10 file for description of how to create the final <emphasis
11 role="bold">eltf_params_updated.xml</emphasis> from this template and for
12 all <emphasis role="bold">REQUIREMENTS</emphasis>. Use the command
13 "<emphasis role="bold">make eltf</emphasis>" to extract a full list of all
14 ELTF variables, which always begins with ELTF_ and don't only rely on the
15 howto text file list! The plan is that ELTF will auto-update this when
16 needed.</para>
17 </note>
18
19 <section id="host_prereq">
20 <title>Common Parameters</title>
21
22 <bridgehead>A programlisting, ID
23 "eltf-prereq-apt-get-commands-host"</bridgehead>
24
25 <para id="eltf-prereq-apt-get-commands-host"><programlisting>ELTF_PL_HOST_PREREQ</programlisting></para>
26
27 <bridgehead>A programlisting, ID
28 "eltf-getting-repo-install-command"</bridgehead>
29
30 <para id="eltf-getting-repo-install-command"><programlisting>ELTF_PL_GET_REPO</programlisting></para>
31
32 <bridgehead>Several phrase elements, various IDs. Ensure EL_REL_VER is
33 correct also compared to the "previous" REL VER in pardoc-distro.xml
34 "prev_baseline".</bridgehead>
35
36 <para id="EneaLinux_REL_VER"><phrase>ELTF_EL_REL_VER</phrase></para>
37
38 <para id="Yocto_VER"><phrase>ELTF_YOCTO_VER</phrase></para>
39
40 <para id="Yocto_NAME"><phrase>ELTF_YOCTO_NAME</phrase></para>
41
42 <para id="ULINK_YOCTO_PROJECT_DOWNLOAD"><ulink
43 url="ELTF_YOCTO_PROJ_DOWNLOAD_URL">ELTF_YOCTO_PROJ_DOWNLOAD_TXTURL</ulink></para>
44
45 <para id="ULINK_ENEA_LINUX_URL"><ulink
46 url="ELTF_EL_DOWNLOAD_URL">ELTF_EL_DOWNLOAD_TXTURL</ulink></para>
47
48 <bridgehead>A programlisting, ID "eltf-repo-cloning-enea-linux". Use
49 $MACHINE/default.xml as parameter, where MACHINE is one of the target
50 directory names in the manifest.</bridgehead>
51
52 <para id="eltf-repo-cloning-enea-linux"><programlisting>ELTF_PL_CLONE_W_REPO</programlisting></para>
53
54 <bridgehead>A table with ONE row, only the row with ID
55 "eltf-eclipse-version-row" is included in the book. MANUALLY BOTH in the
56 template.xml and in the updated.xml, set condition hidden on the
57 &lt;row&gt;, if eclipse is not in the release.</bridgehead>
58
59 <informaltable>
60 <tgroup cols="1">
61 <tbody>
62 <row id="eltf-eclipse-version-row">
63 <entry>Eclipse version ELTF_ECLIPSE_VERSION plus command line
64 development tools are included in this Enea NFV Access release.</entry>
65 </row>
66 </tbody>
67 </tgroup>
68 </informaltable>
69
70 <bridgehead>Below is one big section with title "Supported Targets with
71 Parameters". The entire section is included completely in the book via ID
72 "eltf-target-tables-section" and shall be LAST in the template. The
73 template contains ONE target subsection. COPY/APPEND it, if multiple
74 targets exist in the release and optionally add rows with additional
75 target parameters in each target subsection table.</bridgehead>
76 </section>
77
78 <section id="eltf-target-tables-section">
79 <title>Supported Targets with Parameters</title>
80
81 <para>The tables below describes the target(s) supported in this Enea
82 NFV Access release.</para>
83
84 <section id="eltf-target-table-ELTF_T_MANIFEST_DIR">
85 <title>MACHINE ELTF_T_MANIFEST_DIR - Information</title>
86
87 <para><informaltable>
88 <tgroup cols="2">
89 <colspec colwidth="6*" />
90
91 <colspec colwidth="9*" />
92
93 <tbody>
94 <row>
95 <entry>Target official name</entry>
96
97 <entry>ELTF_T_NAME</entry>
98 </row>
99
100 <row>
101 <entry>Architecture and Description</entry>
102
103 <entry>ELTF_T_ARC_DESC</entry>
104 </row>
105
106 <row>
107 <entry>Link to target datasheet</entry>
108
109 <entry>See <ulink
110 url="ELTF_T_DS_URL">ELTF_T_DS_TXTURL</ulink></entry>
111 </row>
112
113 <row>
114 <entry>Poky version</entry>
115
116 <entry>ELTF_T_POKY_VER</entry>
117 </row>
118
119 <row>
120 <entry>GCC version</entry>
121
122 <entry>ELTF_T_GCC_VER</entry>
123 </row>
124
125 <row>
126 <entry>Linux Kernel Version</entry>
127
128 <entry>ELTF_T_KERN_VER</entry>
129 </row>
130
131 <row>
132 <entry>Supported Drivers</entry>
133
134 <entry>ELTF_T_DRIVERS</entry>
135 </row>
136
137 <row>
138 <entry>Enea rpm folder for downloading RPM packages for this
139 target</entry>
140
141 <entry><ulink
142 url="ELTF_T_EL_RPM_URL">ELTF_T_EL_RPM_TXTURL</ulink></entry>
143 </row>
144 </tbody>
145 </tgroup>
146 </informaltable></para>
147 </section>
148
149 <!-- ELTFADD_MORE_TARGET_SECTIONS_BELOW_IF_NEEDED -->
150 </section>
151</section> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated.xml b/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated.xml
new file mode 100644
index 0000000..e6d3929
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated.xml
@@ -0,0 +1,156 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<section id="eltf_created_params">
5 <title>File with Parameters in the Book Auto-updated by ELFT</title>
6
7 <note>
8 <para>See the <emphasis
9 role="bold">eltf_params_updated_template_howto_use.txt</emphasis> text
10 file for description of how to create the final <emphasis
11 role="bold">eltf_params_updated.xml</emphasis> from this template and for
12 all <emphasis role="bold">REQUIREMENTS</emphasis>. Use the command
13 "<emphasis role="bold">make eltf</emphasis>" to extract a full list of all
14 ELTF variables, which always begins with ELTF_ and don't only rely on the
15 howto text file list! The plan is that ELTF will auto-update this when
16 needed.</para>
17 </note>
18
19 <section id="host_prereq">
20 <title>Common Parameters</title>
21
22 <bridgehead>A programlisting, ID
23 "eltf-prereq-apt-get-commands-host"</bridgehead>
24
25 <para id="eltf-prereq-apt-get-commands-host"><programlisting># Host Ubuntu 16.04 LTS 64bit
26sudo apt-get -y update
27sudo apt-get -y install sed wget subversion git-core coreutils unzip texi2html \
28 texinfo libsdl1.2-dev docbook-utils fop gawk python-pysqlite2 diffstat \
29 make gcc build-essential xsltproc g++ desktop-file-utils chrpath \
30 libgl1-mesa-dev libglu1-mesa-dev autoconf automake groff libtool xterm \
31 libxml-parser-perl</programlisting></para>
32
33 <bridgehead>A programlisting, ID
34 "eltf-getting-repo-install-command"</bridgehead>
35
36 <para id="eltf-getting-repo-install-command"><programlisting>mkdir -p ~/bin
37curl https://storage.googleapis.com/git-repo-downloads/repo &gt; ~/bin/repo
38chmod a+x ~/bin/repo
39export PATH=~/bin:$PATH</programlisting></para>
40
41 <bridgehead>Several phrase elements, various IDs. Ensure EL_REL_VER is
42 correct also compared to the "previous" REL VER in pardoc-distro.xml
43 "prev_baseline".</bridgehead>
44
45 <para id="EneaLinux_REL_VER"><phrase>1.1</phrase></para>
46
47 <para id="Yocto_VER"><phrase>2.1</phrase></para>
48
49 <para id="Yocto_NAME"><phrase>krogoth</phrase></para>
50
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>
53
54 <para id="ULINK_ENEA_LINUX_URL"><ulink
55 url="https://linux.enea.com/6">https://linux.enea.com/6</ulink></para>
56
57 <bridgehead>A programlisting, ID "eltf-repo-cloning-enea-linux". Use
58 $MACHINE/default.xml as parameter, where MACHINE is one of the target
59 directory names in the manifest.</bridgehead>
60
61 <para id="eltf-repo-cloning-enea-linux"><programlisting>mkdir enea-linux
62cd enea-linux
63repo init -u git@git.enea.com:linux/manifests/el_manifests-virtualization.git \
64 -b refs/tags/EL6 -m $MACHINE/default.xml
65repo sync</programlisting></para>
66
67 <bridgehead>A table with ONE row, only the row with ID
68 "eltf-eclipse-version-row" is included in the book. MANUALLY in book, set
69 condition hidden if eclipse is not in the release. Do this both in
70 template.xml and updated.xml.</bridgehead>
71
72 <informaltable>
73 <tgroup cols="1">
74 <tbody>
75 <row condition="hidden" id="eltf-eclipse-version-row">
76 <entry>Eclipse version 4.3 (Mars) plus command line development
77 tools are included in this Enea NFV Access release.</entry>
78 </row>
79 </tbody>
80 </tgroup>
81 </informaltable>
82
83 <bridgehead>Below is one big section with title "Supported Targets with
84 Parameters". The entire section is included completely in the book via ID
85 "eltf-target-tables-section" and shall be LAST in the template. The
86 template contains ONE target subsection. COPY/APPEND it, if multiple
87 targets exist in the release and optionally add rows with additional
88 target parameters in each target subsection table.</bridgehead>
89 </section>
90
91 <section id="eltf-target-tables-section">
92 <title>Supported Reference Boards with Parameters</title>
93
94 <para>The table(s) below describes the target(s) supported in this Enea
95 NFV Access release.</para>
96
97 <section id="eltf-target-table-D-1521">
98 <title>MACHINE Intel Xeon D-1521 - Information</title>
99
100 <para><informaltable>
101 <tgroup cols="2">
102 <colspec colwidth="6*" />
103
104 <colspec colwidth="9*" />
105
106 <tbody>
107 <row>
108 <entry>Target official name</entry>
109
110 <entry>Intel Xeon D-1521</entry>
111 </row>
112
113 <row>
114 <entry>Architecture and Description</entry>
115
116 <entry>x86-64</entry>
117 </row>
118
119 <row>
120 <entry>Link to target datasheet</entry>
121
122 <entry>See link to <ulink
123 url="https://ark.intel.com/products/91202/Intel-Xeon-Processor-D-1521-6M-Cache-2_40-GHz">Intel's
124 datasheet</ulink></entry>
125 </row>
126
127 <row>
128 <entry>Poky version</entry>
129
130 <entry>Git-commit-id:
131 f01b909a266498853e6b3f10e6b39f2d95148129</entry>
132 </row>
133
134 <row>
135 <entry>GCC version</entry>
136
137 <entry>5.3<remark>FIXME</remark></entry>
138 </row>
139
140 <row>
141 <entry>Linux Kernel Version</entry>
142
143 <entry>3.12<remark>FIXME</remark></entry>
144 </row>
145
146 <row condition="hidden">
147 <entry>Supported Drivers</entry>
148
149 <entry>Ethernet, RTC, UART</entry>
150 </row>
151 </tbody>
152 </tgroup>
153 </informaltable></para>
154 </section>
155 </section>
156</section> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated_template_how_to_use.txt b/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated_template_how_to_use.txt
new file mode 100644
index 0000000..62e5d02
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/eltf_params_updated_template_how_to_use.txt
@@ -0,0 +1,320 @@
1eltf_params_template_updated_howto_use.txt
2
3This is a way to collect all parameters for an Enea NFV Access release
4in one parameter file, easy to automatically update by ELTF regularly.
5
6NOTE: Both the release info AND the open source books use parameters from
7 here, but the XML file is inside the release info book directory.
8
9NOTE: The manifest_conf.mk, or overridden by the environment variable
10 MANIFESTHASH, contains the full tag (or hashvalue) for downloading
11 the manifest when the books are built. The list of target
12 directories are fetched from the manifest into the book.
13 The eltf_params_updates.xml can all the time contain
14 the final next complete tag e.g. refs/tags/EL6 or similar
15 in the ELTF_PL_CLONE_W_REPO parameter command lines.
16
17The ordinary book XML files use xi:include statements to include elements
18from this parameter file. The book XML files can thus be manually edited.
19Before editing, you must run "make init".
20Any other text in the template or updated.xml file, outside the parts that
21are included in the book, are not used but still all must be correct
22DocBook XML files.
23
24ELTF work:
25 template => ELTF replaces ALL ELTF_xxx variables => updated XML file
26 => push to git only if changed
27
28
29eltf_params_template.xml (in git)
30 File used by ELTF to autocreate/update the real parameter
31 file eltf_params_updated.xml.
32
33eltf_params_updated.xml (in git)
34 Real parameter file where ELTF has replaced all ELTF_xx variables with
35 strings, in several cases with multiline strings.
36 No spaces or linefeed allowed in beginning or end of the variable values!
37
38
39xi:include: Each parameter is xi:include'ed in various book files, using
40 the IDs existing in the parameter files.
41 In most cases the 1:st element inside an element with an ID is included
42 using a format like eltf-prereq-apt-get-commands-host/1.
43 In very few cases the element with the ID is included in the book, one
44 example is the target section which has an ID, but which contains
45 multiple subsections, one per target.
46 All IDs in a book must be unique.
47
48DocBook XML: All XML files must be correct DocBook XML files.
49
50Do NOT edit/save the real *updated.xml file with XMLmind to avoid changes
51 not done by ELTF. But it is OK to open the real file in XMLmind to
52 check that the format is correct.
53
54ELTF should autocreate a temporary "real" file but only replace
55 and push the eltf_params_updated.xml if it is changed.
56
57
58make eltf
59 This lists all ELTF_xxx variables and some rules how to treat them
60
61DocBook Format: All elements - rules:
62 Several strict generic XML rules apply for all strings:
63 1. No TABs allowed or any other control chr than "linefeed"
64 2. Only 7-bit ASCII
65 3. Any < > & must be converted to &lt; &gt; and &amp;
66 Similar for any other non-7-bit-ASCII but avoid those!
67 4. No leading spaces or linefeeds when replacing the ELTF_* variable
68 5. No trailing spaces or linefeeds when replacing the ELTF_* variable
69 6. Note: Keep existing spaces before/efter ELTF_* in a few cases.
70
71DocBook Format: <programlisting> - rules: ELTF*PL* variables
72 Several strict rules apply for the multiline string in programlisting
73 in addition to the general XML rules above:
74 7. Max line length < 80 char
75 8. Use backslash (\) to break longer lines
76 9. Use spaces (e.g. 4) to indent continuation lines in programlistings
77 10. No trailing spaces on any line
78 11. No spaces or linefeed immediately after leading <programlisting>
79 12. No spaces or linefeed before trailing </programlisting>
80
81DocBook Format: <ulink> - rules: ELTF_*URL* variables
82 13. ELTF_*URL and corresponding ELTF_*TXTURL shall be identical strings
83 14. Only if the URL is extremely long, the TXTURL can be a separate string
84
85Each target has one section with target parameters:
86 <section id="eltf-target-table-ELTF_T_MANIFEST_DIR">
87 <title>MACHINE ELTF_T_MANIFEST_DIR - Information</title>
88 ..... with many ELTF_ variables ....
89 </section>
90
91 15. If there is only one target. ELTF just replaces ELTF parameters
92
93 16. It there are multiple targets. ELTF copies the section and appends the
94 section the required number of times.
95 Each section ID will become unique: eltf-target-table-ELTF_T_MANIFEST_DIR
96 Each section title will become unique
97
98Tables with target parameters in each target section:
99 17. It is possible for ELTF to append more rows with one parameter each
100 to these tables, because the entire tables are included in the book
101
102Special - NOT YET READY DEFINED how to handle the optionally included
103 Eclipse and its version, but this is a first suggestion:
104 18. Just now ELTF can define ELFT_ECLIPSE_VERSION as a full string
105 with both version number and name,
106 19. MANUALLY if Eclipse is NOT included in the release,
107 the release manager should manually set condition="hidden" on
108 the entire section in the book XML about Eclipse
109
110
111
112BELOW WE TRY TO EXPLAIN EACH ELTF_* variable, but always check with make eltf
113if there are more new variables, missing in this description file.
114
115_____________________________________________________________________________
116ELTF_PL_HOST_PREREQ Multiline list of host prerequisites, e.g. commands
117 like sudo apt-get install xxxx or similar.
118 First line = comment with the complete host name!
119 It is possible to include multiple hosts by just
120 adding an empty line, comment with host name, etc.
121 xi:include eltf-prereq-apt-get-commands-host/1
122 This is a <programlisting>...</programlisting>
123 Example:
124# Host Ubuntu 14.04.5 LTS 64bit
125sudo apt-get update
126sudo apt-get install sed wget subversion git-core coreutils unzip texi2html \
127 texinfo libsdl1.2-dev docbook-utils fop gawk python-pysqlite2 diffstat \
128 make gcc build-essential xsltproc g++ desktop-file-utils chrpath \
129 libgl1-mesa-dev libglu1-mesa-dev autoconf automake groff libtool xterm \
130 libxml-parser-perl
131
132_____________________________________________________________________________
133ELTF_PL_GET_REPO Multiline commands to download the repo tool
134 xi:include eltf-getting-repo-install-command/1
135 This is a <programlisting>...</programlisting>
136 Example:
137mkdir -p ~/bin
138curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
139chmod a+x ~/bin/repo
140export PATH=~/bin:$PATH
141
142_____________________________________________________________________________
143ELTF_EL_REL_VER General parameter string: The version of this Enea
144 NFV Access release. Major version and optional .Minor
145 Typically created from MAJOR and MINOR in enea.conf
146 MINOR in enea.conf is empty or contains a dot+minor
147 xi_include EneaLinux_REL_VER/1
148 This is a <phrase>X.x</phrase> used in many places.
149 Examples:
1506
151 or
1526.1
153
154_____________________________________________________________________________
155ELTF_YOCTO_VER General parameter string: Yocto version, created
156 from DISTRO in poky.ent
157 xi:include Yocto_VER/1
158 This is a <phrase>X.x</phrase> used in many places.
159 Example:
1602.1
161
162_____________________________________________________________________________
163ELTF_YOCTO_NAME General parameter string: Yocto name (branch), created
164 from DISTRO_NAME_NO_CAP in poky.ent
165 xi:include Yocto_NAME/1
166 This is a <phrase>X.x</phrase> used in many places.
167 Example:
168krogoth
169
170_____________________________________________________________________________
171ELTF_YOCTO_PROJ_DOWNLOAD_TXTURL General parameters. These two are IDENTICAL
172ELTF_YOCTO_PROJ_DOWNLOAD_URL strings with correct Yocto version string
173 at the end, typically without "dot".
174 xi:include ULINK_YOCTO_PROJECT_DOWNLOAD/1
175 This is an <ulink url="...">...</ulink>
176 Example:
177http://www.yoctoproject.org/downloads/core/krogoth/21
178
179_____________________________________________________________________________
180ELTF_EL_DOWNLOAD_TXTURL General parameters. These two are IDENTICAL strings
181ELTF_EL_DOWNLOAD_URL and shall be the http:/..... address where
182 Enea NFV Access can be downloaded
183 Often containing same version as in ELTF_EL_REL_VER
184 xi:include ULINK_ENEA_LINUX_URL/1
185 This is an <ulink url="...">...</ulink>
186 Example:
187http://linux.enea.com/6
188
189_____________________________________________________________________________
190ELTF_PL_CLONE_W_REPO Multiline commands to run repo to clone everything.
191 Use the variable $MACHINE/default.xml (the text in
192 the book will list the avaiable values of MACHINE,
193 taken from the manifest repository)
194 xi:include eltf-repo-cloning-enea-linux/1
195 This is a <programlisting>...</programlisting>
196 Example:
197mkdir enea-linux
198cd enea-linux
199repo init -u git@git.enea.com:linux/manifests/el_manifests-virtualization.git \
200 -b refs/tags/EL6 -m $MACHINE/default.xml
201repo sync
202
203_____________________________________________________________________________
204ELTF_ECLIPSE_VERSION Optional general parameter string.
205 NOT YET READY DEFINED
206 Just now a release manage must manually set
207 condition="hidden" on the Eclipse section,
208 if Eclipse is not included in the release.
209 ELTF just replaces ELTF_ECLIPSE_VERSION with a full
210 string with "X.Y (name)"
211 It includes the ID and can only be ONCE in the book.
212 xi:include eltf-eclipse-version-row
213 Example.
2144.5 (Mars)
215
216
217_____________________________________________________________________________
218ELTF_T_* All these are in each target (MACHINE) and ELTF
219 must separately replace them with strings for
220 each target
221 NOTE: All (except the MANIFEST_DIR) are in rows
222 in a table and ELTF can select to append
223 more parameters by adding more rows
224
225_____________________________________________________________________________
226ELTF_T_MANIFEST_DIR This happens to be in two places. Must be exactly
227ELTF_T_MANIFEST_DIR the directory name in the manifest, e.g. same
228 as the MACHINE names in $MACHINE/default.xml.
229 In book: a) Part of section ID
230 b) Part of section title
231 Examples:
232p2041rgb
233 or
234ls1021aiot
235 or
236qemuarm
237
238_____________________________________________________________________________
239ELTF_T_NAME Target specific: "Target Official Name"
240 NOT same as the target directory name in most cases.
241 In book: An <entry> element in a row
242 Examples:
243P2041RGB
244 or
245LS1021a-IoT
246 or
247qemuarm
248
249_____________________________________________________________________________
250ELTF_T_ARC_DESC Target specific: "Architecture and Description"
251 It can be a short identification string or
252 it can be a longer descriptive sentence.
253 In book: An <entry> element in a row
254 Examples:
255Power, e500mc
256 or
257ARM Cortex-A7
258
259_____________________________________________________________________________
260ELTF_T_DS_TXTURL Target specific: "Link to target datasheet. These
261ELTF_T_DS_URL two usually are IDENTICAL strings with correct
262 hyperlink to the target's official datasheet.
263 In book: an <ulink url="...">...</ulink>
264 Only if the link is VERY LONG, the text part shall
265 instead be a descriptive string (see 2:nd example).
266 NOTE: Also here no spaces or line-feeds!
267 Examples:
268url="http://wiki.qemu.org">http://wiki.qemu.org
269or
270url="http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/qoriq-arm-processors/qoriq-ls1021a-iot-gateway-reference-design:LS1021A-IoT">link to NXP's datasheet
271
272_____________________________________________________________________________
273ELTF_T_POKY_VER Target specific: "Poky version" created either
274 from POKYVERSION in poky.ent
275 or using a hashvalue with a leading string, in
276 which case it may be different per target.
277 In book: An <entry> in a row
278 Examples:
27915.0.0
280or
281Git commit id: 75ca53211488a3e268037a44ee2a7ac5c7181bd2
282
283_____________________________________________________________________________
284ELTF_T_GCC_VER Target specific: "GCC Version". Should be in poky
285 but not easy to find among various parameters.
286 ELTF would extract it from build logs building SDK
287 and it is possibly different per target.
288 In book: An <entry> in a row
289 Example:
2905.3
291
292_____________________________________________________________________________
293ELTF_T_KERN_VER Target specific: "Linux Kernel Version". Often
294 different per target.
295 In book: An <entry> in a row
296 Example:
2973.12
298
299_____________________________________________________________________________
300ELTF_T_DRIVERS Target specific: "Supported Drivers". This is a
301 comma-separated list of driver names.
302 ELTF should create the list in same order for each
303 target, e.g. alphabetic migth be OK.
304 In book: An <entry> in a row
305 Example:
306Ethernet, I2C, SPI, PCI, USB, SD/SDHC/SDXC
307
308
309_____________________________________________________________________________
310ELTF_T_EL_RPM_TXTURL Target specific: "Enea rpm folder for downloading
311ELTF_T_EL_RPM_URL RPM packages for this target". These two are
312 INDENTICAL strings with hyperlink to the web site
313 at Enea where the customer can download RPMs
314 Note: Often the ELFT_EL_REL_VER value and
315 the ELTF_T_MANIFEST_DIR are used in the link.
316 In book: an <ulink url="...">...</ulink>
317 Example:
318url="https://linux.enea.com/6/ls1021aiot/rpm">https://linux.enea.com/6/ls1021aiot/rpm
319
320_____________________________________________________________________________
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/getting_enea_nfv_access.xml b/doc/book-enea-nfv-access-release-info-intel/doc/getting_enea_nfv_access.xml
new file mode 100644
index 0000000..2bf9c22
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/getting_enea_nfv_access.xml
@@ -0,0 +1,31 @@
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="relinfo-getting-enea-nfv-access">
5 <title>Getting Enea NFV Access</title>
6
7 <para>Enea NFV Access releases are available as binaries ready for download
8 on the <ulink
9 url="https://portal.enea.com/login/?redirect_to=https%3A%2F%2Fportal.enea.com%2F">Enea
10 Download Portal</ulink>. Updates of Enea NFV Access are also available for
11 download through the portal.</para>
12
13 <para>Log in using the credentials provided by Enea. Using the menu at the
14 top, browse to the <literal>NFV</literal> section, which will provide access
15 to a <literal>Files</literal> section and an <literal>Online
16 Documentation</literal> section. The <literal>Files</literal> section lists
17 each Enea NFV Access release version as a separate download package.
18 Clicking on any of the release packages will provide further details such as
19 the date when it was made available, the file size and the changelog. Most
20 importantly, it provides access to the download links.</para>
21
22 <para>Each archive is mirrored in several places, geographically. Choose the
23 archive in the region closest to you for better download speeds. For details
24 about the contents of the release package, please refer to <xref
25 linkend="release-content" />.</para>
26
27 <para>The <literal>Online documentation</literal> section provides quick
28 access to the documents delivered with the release. For details about the
29 books delivered and their purpose, please refer to <xref
30 linkend="relinfo-documentation" />.</para>
31</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/jiraissues_override.xml b/doc/book-enea-nfv-access-release-info-intel/doc/jiraissues_override.xml
new file mode 100644
index 0000000..7282d0f
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/jiraissues_override.xml
@@ -0,0 +1,36 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<section id="relinfo-extracted-from-jira">
5 <title>Release-Specific Problems</title>
6
7 <informaltable>
8 <tgroup cols="2">
9 <colspec colwidth="6*" colname="c1"/>
10
11 <colspec align="center" colwidth="1*" colname="c2"/>
12
13 <thead>
14 <row>
15 <entry align="center">Summary</entry>
16
17 <entry>Enea Ref</entry>
18 </row>
19 </thead>
20
21 <tbody>
22 <row>
23 <entry>Eclipse Plug-Ins for Perf and Latencytop are not functioning properly on P2041RDB target.</entry>
24
25 <entry>LXCR-6936</entry>
26 </row>
27
28 <row>
29 <entry><para>LTTng kernel tracing from Eclipse does not work due to RSE connectivity problems.</para><para>As a workaround, traces can be collected on target and visualized on Eclipse, after copying the files on the host system.</para></entry>
30
31 <entry>LXCR-7166</entry>
32 </row>
33 </tbody>
34 </tgroup>
35 </informaltable>
36</section>
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/known_bugs_and_limitations.xml b/doc/book-enea-nfv-access-release-info-intel/doc/known_bugs_and_limitations.xml
new file mode 100644
index 0000000..67db036
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/known_bugs_and_limitations.xml
@@ -0,0 +1,53 @@
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="bugs-limitations">
5 <title>Known Problems in This Release</title>
6
7 <para>All known issues listed in this chapter will be addressed in
8 maintenance updates following the major release.<remark>INFO: The <emphasis
9 role="bold">Release-Specific Problems</emphasis> section further down is
10 generated from JIRA with gen_known_issues.py, but that script is HARDCODED
11 with affectedversion "EL7_3-virtualization" and needs to be adapted when a
12 release info for another ENFV Access version changes.</remark></para>
13
14 <section id="release-specific-limitations">
15 <title>Release-Specific Limitations</title>
16
17 <para><emphasis role="bold">Issues concerning the current
18 release</emphasis>:</para>
19
20 <itemizedlist>
21 <listitem>
22 <para>OFP and ODP are not included with the current release but they
23 will be included in a later maintenance update.<remark>FIXME,
24 requesting help from Ca</remark></para>
25 </listitem>
26 </itemizedlist>
27
28 <para><emphasis role="bold">Issues affecting
29 documentation</emphasis>:</para>
30
31 <itemizedlist>
32 <listitem>
33 <para>Documents provided in this release will continue to be regularly
34 updated with additional content. </para>
35 </listitem>
36
37 <listitem>
38 <para><emphasis role="bold">PDF navigation</emphasis>: When using
39 links to open other PDFs, or jump to another place in the same PDF,
40 jumping back sometimes fails. This has been observed when opening a
41 PDF in Adobe Reader, inside a browser with PDF add-on, as well as when
42 the browser is configured to open PDF files in an external PDF reader.
43 As a workaround, open the HTML version of the
44 document.<remark>LXCR-3283</remark></para>
45 </listitem>
46 </itemizedlist>
47 </section>
48
49 <!-- The file with a section below is autocreated by make init -->
50
51 <!-- <xi:include href="jiraissues_generated.xml"
52 xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
53</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/main_changes.xml b/doc/book-enea-nfv-access-release-info-intel/doc/main_changes.xml
new file mode 100644
index 0000000..a0cf1c5
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/main_changes.xml
@@ -0,0 +1,114 @@
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="relinfo-changes">
5 <title>Main Changes</title>
6
7 <para>This chapter provides information about the new features added in the
8 current release, as well as details on the provided packages and the
9 backwards compatibility with previous versions of Enea NFV Access.</para>
10
11 <section id="relinfo-changes-other">
12 <title>New Features</title>
13
14 <itemizedlist>
15 <listitem>
16 <para>Key Component updates:</para>
17
18 <itemizedlist>
19 <listitem>
20 <para>DPDK 17.08</para>
21 </listitem>
22
23 <listitem>
24 <para>OVS 2.8</para>
25 </listitem>
26 </itemizedlist>
27 </listitem>
28
29 <listitem>
30 <para>Feature Extensions:</para>
31
32 <itemizedlist>
33 <listitem>
34 <para>Element ODM: FCAPS framework with NETCONF and Yang.</para>
35 </listitem>
36
37 <listitem>
38 <para>EdgeLink Netconf (beta): NETCONF based VNF lifecycle
39 Management Tool.</para>
40 </listitem>
41 </itemizedlist>
42 </listitem>
43
44 <listitem>
45 <para>Extended Tools Feature Set:</para>
46
47 <itemizedlist>
48 <listitem>
49 <para>python-pip</para>
50 </listitem>
51
52 <listitem>
53 <para>dosfstools</para>
54 </listitem>
55
56 <listitem>
57 <para>htop</para>
58 </listitem>
59 </itemizedlist>
60 </listitem>
61
62 <listitem>
63 <para>Unified cross-development SDK for host and virtualized
64 environments.</para>
65 </listitem>
66
67 <listitem>
68 <para>Native toolchain support on development image.</para>
69 </listitem>
70
71 <listitem>
72 <para>USB-stick based installation</para>
73 </listitem>
74
75 <listitem>
76 <para>Product Maintenance:</para>
77
78 <itemizedlist>
79 <listitem>
80 <para>Optimizations</para>
81 </listitem>
82
83 <listitem>
84 <para>Security patches</para>
85 </listitem>
86
87 <listitem>
88 <para>Bug fixes</para>
89 </listitem>
90
91 <listitem>
92 <para>Updated documentation</para>
93 </listitem>
94 </itemizedlist>
95 </listitem>
96 </itemizedlist>
97 </section>
98
99 <section id="open_source">
100 <title>Open Source</title>
101
102 <para>For more information about the Open Source packages included, please
103 refer to the Enea NFV Access Open Source Reports provided with this
104 release.</para>
105 </section>
106
107 <section id="relinfo-backward-compat">
108 <title>Compatibility</title>
109
110 <para>Due to the fact that ODP and OFP are not included in this release,
111 any applications dependent on these components are not compatible with the
112 current release.</para>
113 </section>
114</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/system_requirements.xml b/doc/book-enea-nfv-access-release-info-intel/doc/system_requirements.xml
new file mode 100644
index 0000000..7bab63d
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/system_requirements.xml
@@ -0,0 +1,162 @@
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<section id="enea-nfv-access-sysreq">
5 <title>System Requirements</title>
6
7 <para>The host requirements listed below are extensive to allow for the
8 building of Linux images via the Yocto system, and not just
9 applications.</para>
10
11 <para>Please also see the system requirements in the Yocto 2.1 documents:
12 Yocto Project Start <ulink
13 url="http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html#yp-resources">
14 http://www.yoctoproject.org/docs/2.1/yocto-project-qs/yocto-project-qs.html#yp-resources</ulink>
15 and the Yocto Project Reference Manual <ulink
16 url="http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#intro-requirements">
17 http://www.yoctoproject.org/docs/2.1/ref-manual/ref-manual.html#intro-requirements</ulink>.
18 If needed, replace the Yocto version in the link(s) provided with a more
19 recent version.</para>
20
21 <informaltable>
22 <tgroup cols="2">
23 <colspec align="left" colname="1" colwidth="1*" />
24
25 <colspec align="left" colname="2" colwidth="3*" />
26
27 <spanspec nameend="2" namest="1" spanname="onetwo" />
28
29 <tbody>
30 <row>
31 <entry spanname="onetwo"><emphasis role="bold"> Build host
32 requirements<indexterm>
33 <primary>system requirements</primary>
34 </indexterm></emphasis></entry>
35 </row>
36
37 <row>
38 <entry>Linux distribution</entry>
39
40 <entry>The downloaded code shall be built on a Linux host to
41 generate images for your target or for emulation in QEMU. For
42 information about the supported hosts and targets, see the <emphasis
43 role="bold">Enea Linux Release Information</emphasis> in your Enea
44 Linux distribution.</entry>
45 </row>
46
47 <row>
48 <entry>Internet access</entry>
49
50 <entry>Internet access must be available when building an image,
51 since bitbake downloads source files from various servers during the
52 build.</entry>
53 </row>
54
55 <row>
56 <entry>Packages</entry>
57
58 <entry>Depending on the Linux distribution and version on host, some
59 packages may be required, by bitbake for example. You will install
60 any required packages while following the installation
61 instructions.</entry>
62 </row>
63
64 <row>
65 <entry>Targets</entry>
66
67 <entry>Images can be built or downloaded for any of the targets
68 supported in this release, as specified in the <emphasis
69 role="bold">Enea Linux Release Information</emphasis>.</entry>
70 </row>
71
72 <row>
73 <entry>Disk space</entry>
74
75 <entry><para>Your system should have at least 50 GB of free disk
76 space when bitbaking the basic enea-image-name kernel image.</para>
77 <para>For larger images and to allow for future package extensions
78 and variations in the build process, a minimum of 100 GB free disk
79 space is recommended.</para></entry>
80 </row>
81
82 <row>
83 <entry>Recommended RAM</entry>
84
85 <entry><para>Your system must have at least 4 GB available
86 RAM.</para> <para>It is recommended to have 8 GB RAM available for
87 parallel build jobs.</para></entry>
88 </row>
89
90 <row>
91 <entry>Java</entry>
92
93 <entry>Java <indexterm>
94 <primary>java</primary>
95 </indexterm>is required to run Eclipse. Currenly, Eclipse
96 generally recommends at least Java 6 JRE/JDK. More information
97 regarding operating environments for Eclipse, is provided in the
98 <emphasis>Eclipse Project Release Notes</emphasis> for the version
99 used. This can usually be found via
100 http://www.eclipse.org/eclipse/development/readme_eclipse_version.
101 See the <emphasis role="bold">Enea Linux Release Information
102 </emphasis>for the Eclipse Version.</entry>
103 </row>
104 </tbody>
105 </tgroup>
106 </informaltable>
107
108 <para>The build time depends on the capacity of the processor and other
109 hardware, available resources, speed of internet connection, load situation,
110 etc. E.g: on a fast 16 core machine with 16 GB RAM and SSD disks, a complete
111 build from source could take about two hours.</para>
112
113 <informaltable>
114 <tgroup cols="2">
115 <colspec align="left" colname="1" colwidth="1*" />
116
117 <colspec align="left" colname="2" colwidth="3*" />
118
119 <spanspec nameend="2" namest="1" spanname="onetwo" />
120
121 <tbody>
122 <row>
123 <entry spanname="onetwo"><emphasis role="bold">Target
124 Requirements</emphasis></entry>
125 </row>
126
127 <row>
128 <entry>External memory</entry>
129
130 <entry>To boot a CGL<indexterm>
131 <primary>CGL</primary>
132 </indexterm> image, you need at least 16 GB on a hard-disk
133 drive<indexterm>
134 <primary>HDD</primary>
135 </indexterm> on eSATA, USB drive, or SD card.<remark>INFO: (packed
136 rootfs 4.5 GB + unpacked rootfs 1.5 GB + good
137 margins)</remark><remark>INFO: NFS does not support SELinux. In
138 order to have a security-enhanced Linux, one must take off from an
139 NFS-booted system and proceed with boot from external
140 memory.</remark></entry>
141 </row>
142 </tbody>
143 </tgroup>
144 </informaltable>
145
146 <section id="ensure-bash">
147 <title>System Shell Configuration</title>
148
149 <para>Before installing Enea Linux, ensure that bash is the default
150 shell.</para>
151
152 <para>If your system runs Ubuntu, you can use ls -l to ensure
153 <filename>/usr/bin</filename> is a symbolic link to bash. In case the link
154 points to dash, which is default in some Ubuntu versions, change it to
155 bash by running <emphasis role="bold">sudo dpkg-reconfigure
156 dash</emphasis> and answer <emphasis role="bold">No</emphasis> to the
157 question "Use dash as the default system shell (/bin/sh)?":</para>
158
159 <programlisting># ls -l /bin/sh
160 lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -&gt; bash</programlisting>
161 </section>
162</section> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/doc/system_requirements_prerequisites.xml b/doc/book-enea-nfv-access-release-info-intel/doc/system_requirements_prerequisites.xml
new file mode 100644
index 0000000..44e70af
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/doc/system_requirements_prerequisites.xml
@@ -0,0 +1,61 @@
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="sys-req-prerequisites">
5 <title>Host Requirements</title>
6
7 <para>Using Enea NFV Access or compiling applications requires certain
8 packages to be installed on your build host. The requirements listed below
9 are extensive to allow getting Enea NFV Access to be booted on target
10 machines and for building applications.</para>
11
12 <informaltable>
13 <tgroup cols="2">
14 <colspec align="left" colname="1" colwidth="1*" />
15
16 <colspec align="left" colname="2" colwidth="3*" />
17
18 <spanspec nameend="2" namest="1" spanname="onetwo" />
19
20 <tbody>
21 <row>
22 <entry spanname="onetwo"><emphasis role="bold"> Build Host
23 Requirements<indexterm>
24 <primary>host requirements</primary>
25 </indexterm></emphasis></entry>
26 </row>
27
28 <row>
29 <entry>Linux distribution</entry>
30
31 <entry>The downloaded product can installed on the target machine
32 using a Linux host. For information about supported hosts and
33 targets, see <xref
34 linkend="relinfo-supported-host-environment" />.</entry>
35 </row>
36
37 <row>
38 <entry>Packages</entry>
39
40 <entry>Depending on the Linux distribution and version of the host,
41 certain packages may be required. See details on what packages are
42 needed and how to install them in the following sections.</entry>
43 </row>
44
45 <row>
46 <entry>Disk space</entry>
47
48 <entry>Your build host should have at least 50 GB of free disk space
49 for installing the SDK or cross-compiling applications.</entry>
50 </row>
51
52 <row>
53 <entry>Recommended RAM</entry>
54
55 <entry>Your build host must have at least 4 GB available
56 RAM.</entry>
57 </row>
58 </tbody>
59 </tgroup>
60 </informaltable>
61</chapter> \ No newline at end of file
diff --git a/doc/book-enea-nfv-access-release-info-intel/swcomp.mk b/doc/book-enea-nfv-access-release-info-intel/swcomp.mk
new file mode 100644
index 0000000..3ba7c8d
--- /dev/null
+++ b/doc/book-enea-nfv-access-release-info-intel/swcomp.mk
@@ -0,0 +1,10 @@
1# Component build specification
2
3# Version of THIS book
4BOOK_VER ?= $(REL_VER)-dev
5
6DOCBOOK_SRC := $(COMP)/swcomp.mk $(COMP)/doc/book.xml $(shell find $(COMP)/doc -type f \( -name "*.xml" -o -name "*.svg" -o -name "*.png" \) ! -name "book.xml" -print)
7
8BOOKPACKAGES := book-enea-nfv-access-release-info
9BOOKDESC_$(BOOKPACKAGES) := "Enea NFV Access $(PROD_VER) Release Information"
10BOOKDEFAULTCONDITION := $(DEFAULTCONDITIONS)