diff options
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 / | ||
274 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
275 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
276 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
277 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
278 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting></para> | ||
279 | |||
280 | <para>Kill unnecessary services:<programlisting>killall ovsdb-server ovs-vswitchd | ||
281 | rm -rf /etc/openvswitch/* | ||
282 | mkdir -p /var/run/openvswitch</programlisting>Mount hugepages and configure | ||
283 | DPDK:<programlisting>mkdir -p /mnt/huge | ||
284 | mount -t hugetlbfs nodev /mnt/huge | ||
285 | modprobe igb_uio | ||
286 | dpdk-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 &lt;number&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 / | ||
302 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
303 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
304 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
305 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
306 | hugepagesz=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 | ||
310 | killall ovsdb-server ovs-vswitchd | ||
311 | rm -rf /etc/openvswitch/* | ||
312 | mkdir -p /var/run/openvswitch | ||
313 | |||
314 | # Mount hugepages and bind interfaces to dpdk | ||
315 | mkdir -p /mnt/huge | ||
316 | mount -t hugetlbfs nodev /mnt/huge | ||
317 | modprobe igb_uio | ||
318 | dpdk-devbind --bind=igb_uio 0000:03:00.0 | ||
319 | |||
320 | # configure openvswitch with DPDK | ||
321 | export DB_SOCK=/var/run/openvswitch/db.sock | ||
322 | ovsdb-tool create /etc/openvswitch/conf.db / | ||
323 | /usr/share/openvswitch/vswitch.ovsschema | ||
324 | ovsdb-server --remote=punix:$DB_SOCK / | ||
325 | --remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach | ||
326 | ovs-vsctl --no-wait init | ||
327 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10 | ||
328 | ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc | ||
329 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048 | ||
330 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true | ||
331 | ovs-vswitchd unix:$DB_SOCK --pidfile --detach / | ||
332 | --log-file=/var/log/openvswitch/ovs-vswitchd.log | ||
333 | |||
334 | ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev | ||
335 | ovs-vsctl add-port ovsbr0 vhost-user1 / | ||
336 | -- set Interface vhost-user1 type=dpdkvhostuser ofport_request=1 | ||
337 | ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface / | ||
338 | dpdk0 type=dpdk options:dpdk-devargs=0000:03:00.0 ofport_request=2 | ||
339 | |||
340 | # configure static flows | ||
341 | ovs-ofctl del-flows ovsbr0 | ||
342 | ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2 | ||
343 | ovs-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 | ||
357 | start</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 / | ||
542 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
543 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
544 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
545 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
546 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting> | ||
547 | |||
548 | <para>Configure DPDK:<programlisting>mkdir -p /mnt/huge | ||
549 | mount -t hugetlbfs nodev /mnt/huge | ||
550 | modprobe igb_uio | ||
551 | dpdk-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 <number></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 / | ||
567 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
568 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
569 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 / | ||
570 | iommu=pt intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
571 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting> | ||
572 | |||
573 | <para><programlisting>killall ovsdb-server ovs-vswitchd | ||
574 | rm -rf /etc/openvswitch/* | ||
575 | mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge | ||
576 | mount -t hugetlbfs nodev /mnt/huge | ||
577 | modprobe igb_uio | ||
578 | dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Configure the OVS | ||
579 | bridge:<programlisting>export DB_SOCK=/var/run/openvswitch/db.sock | ||
580 | ovsdb-tool create /etc/openvswitch/conf.db / | ||
581 | /usr/share/openvswitch/vswitch.ovsschema | ||
582 | ovsdb-server --remote=punix:$DB_SOCK / | ||
583 | --remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach | ||
584 | ovs-vsctl --no-wait init | ||
585 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10 | ||
586 | ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xcc | ||
587 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048 | ||
588 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true | ||
589 | ovs-vswitchd unix:$DB_SOCK --pidfile --detach / | ||
590 | --log-file=/var/log/openvswitch/ovs-vswitchd.log | ||
591 | ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev | ||
592 | ovs-vsctl add-port ovsbr0 vhost-user1 -- set Interface / | ||
593 | vhost-user1 type=dpdkvhostuser ofport_request=1 | ||
594 | ovs-vsctl add-port ovsbr0 vhost-user2 -- set Interface / | ||
595 | vhost-user2 type=dpdkvhostuser ofport_request=2 | ||
596 | ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface dpdk0 / | ||
597 | type=dpdk options:dpdk-devargs=0000:03:00.0 ofport_request=3 | ||
598 | ovs-ofctl del-flows ovsbr0 | ||
599 | ovs-ofctl add-flow ovsbr0 in_port=3,action=output:2 | ||
600 | ovs-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 / | ||
726 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable clocksource=tsc / | ||
727 | tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 processor.max_cstate=0 / | ||
728 | mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt intel_iommu=on hugepagesz=1GB / | ||
729 | hugepages=8 default_hugepagesz=1GB hugepagesz=2M hugepages=2048 / | ||
730 | vfio_iommu_type1.allow_unsafe_interrupts=1l</programlisting>Allow unsafe | ||
731 | interrupts:<programlisting>echo 1 > /sys/module/vfio_iommu_type1/parameters/allow_unsafe_interrupts</programlisting>Configure | ||
732 | DPDK:<programlisting>mkdir -p /mnt/huge | ||
733 | mount -t hugetlbfs nodev /mnt/huge | ||
734 | dpdk-devbind.py --bind=ixgbe 0000:03:00.0 | ||
735 | ifconfig eno3 192.168.1.2 | ||
736 | echo 2 > /sys/class/net/eno3/device/sriov_numvfs | ||
737 | modprobe vfio-pci | ||
738 | dpdk-devbind.py --bind=vfio-pci 0000:03:10.0 | ||
739 | dpdk-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 | ||
742 | docker 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 | ||
748 | str</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 | ||
752 | start</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 / | ||
869 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
870 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
871 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
872 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
873 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting></para> | ||
874 | |||
875 | <para>Kill unnecessary services: <programlisting>killall ovsdb-server ovs-vswitchd | ||
876 | rm -rf /etc/openvswitch/* | ||
877 | mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge | ||
878 | mount -t hugetlbfs nodev /mnt/huge | ||
879 | modprobe igb_uio | ||
880 | dpdk-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 / | ||
894 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
895 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
896 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
897 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
898 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Kill | ||
899 | unnecessary services: <programlisting>killall ovsdb-server ovs-vswitchd | ||
900 | rm -rf /etc/openvswitch/* | ||
901 | mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge | ||
902 | mount -t hugetlbfs nodev /mnt/huge | ||
903 | modprobe igb_uio | ||
904 | dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Configure | ||
905 | OVS:<programlisting>export DB_SOCK=/var/run/openvswitch/db.sock | ||
906 | ovsdb-tool create /etc/openvswitch/conf.db / | ||
907 | /usr/share/openvswitch/vswitch.ovsschema | ||
908 | ovsdb-server --remote=punix:$DB_SOCK / | ||
909 | --remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach | ||
910 | ovs-vsctl --no-wait init | ||
911 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10 | ||
912 | ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc | ||
913 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048 | ||
914 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true | ||
915 | ovs-vswitchd unix:$DB_SOCK --pidfile --detach / | ||
916 | --log-file=/var/log/openvswitch/ovs-vswitchd.log | ||
917 | |||
918 | ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev | ||
919 | ovs-vsctl add-port ovsbr0 vhost-user1 / | ||
920 | -- set Interface vhost-user1 type=dpdkvhostuser -- set Interface / | ||
921 | vhost-user1 ofport_request=2 | ||
922 | ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface dpdk0 / | ||
923 | type=dpdk options:dpdk-devargs=0000:03:00.0 / | ||
924 | -- set Interface dpdk0 ofport_request=1 | ||
925 | chmod 777 /var/run/openvswitch/vhost-user1 | ||
926 | |||
927 | ovs-ofctl del-flows ovsbr0 | ||
928 | ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2 | ||
929 | ovs-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,/ | ||
934 | if=virtio,format=raw -m 4096 -object memory-backend-file,id=mem,/ | ||
935 | size=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,/ | ||
939 | mrg_rxbuf=on,rx_queue_size=1024,csum=off,gso=off,guest_tso4=off,/ | ||
940 | guest_tso6=off,guest_ecn=off -append 'root=/dev/vda console=ttyS0 / | ||
941 | hugepagesz=2M hugepages=1024 isolcpus=1 nohz_full=1 rcu_nocbs=1 / | ||
942 | irqaffinity=0 rcu_nocb_poll intel_pstate=disable intel_idle.max_cstate=0 / | ||
943 | processor.max_cstate=0 mce=ignore_ce audit=0'</programlisting>Inside QEMU, | ||
944 | configure DPDK: <programlisting>mkdir -p /mnt/huge | ||
945 | mount -t hugetlbfs nodev /mnt/huge | ||
946 | modprobe igb_uio | ||
947 | dpdk-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 | ||
956 | start</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 | ||
963 | show 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 / | ||
1151 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
1152 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
1153 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
1154 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
1155 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Kill | ||
1156 | Services:<programlisting>killall ovsdb-server ovs-vswitchd | ||
1157 | rm -rf /etc/openvswitch/* | ||
1158 | mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge | ||
1159 | mount -t hugetlbfs nodev /mnt/huge | ||
1160 | modprobe igb_uio | ||
1161 | dpdk-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 / | ||
1175 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
1176 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
1177 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
1178 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
1179 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Kill | ||
1180 | Services:<programlisting>killall ovsdb-server ovs-vswitchd | ||
1181 | rm -rf /etc/openvswitch/* | ||
1182 | mkdir -p /var/run/openvswitch</programlisting>Configure DPDK:<programlisting>mkdir -p /mnt/huge | ||
1183 | mount -t hugetlbfs nodev /mnt/huge | ||
1184 | modprobe igb_uio | ||
1185 | dpdk-devbind --bind=igb_uio 0000:03:00.0</programlisting>Configure | ||
1186 | OVS:<programlisting>export DB_SOCK=/var/run/openvswitch/db.sock | ||
1187 | ovsdb-tool create /etc/openvswitch/conf.db / | ||
1188 | /usr/share/openvswitch/vswitch.ovsschema | ||
1189 | ovsdb-server --remote=punix:$DB_SOCK / | ||
1190 | --remote=db:Open_vSwitch,Open_vSwitch,manager_options --pidfile --detach | ||
1191 | ovs-vsctl --no-wait init | ||
1192 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x10 | ||
1193 | ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc | ||
1194 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-socket-mem=2048 | ||
1195 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true | ||
1196 | ovs-vswitchd unix:$DB_SOCK --pidfile / | ||
1197 | --detach --log-file=/var/log/openvswitch/ovs-vswitchd.log | ||
1198 | |||
1199 | |||
1200 | ovs-vsctl add-br ovsbr0 -- set bridge ovsbr0 datapath_type=netdev | ||
1201 | ovs-vsctl add-port ovsbr0 dpdk0 / | ||
1202 | -- set Interface dpdk0 type=dpdk options:dpdk-devargs=0000:03:00.0 ofport_request=1 | ||
1203 | ovs-vsctl add-port ovsbr0 vhost-user1 / | ||
1204 | -- set Interface vhost-user1 type=dpdkvhostuser ofport_request=2 | ||
1205 | ovs-vsctl add-port ovsbr0 vhost-user2 / | ||
1206 | -- set Interface vhost-user2 type=dpdkvhostuser ofport_request=3 | ||
1207 | |||
1208 | |||
1209 | ovs-ofctl del-flows ovsbr0 | ||
1210 | ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2 | ||
1211 | ovs-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,/ | ||
1216 | if=virtio,format=raw -m 2048 -object memory-backend-file,id=mem,/ | ||
1217 | size=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,/ | ||
1221 | mrg_rxbuf=on,rx_queue_size=1024,csum=off,gso=off,guest_tso4=off,/ | ||
1222 | guest_tso6=off,guest_ecn=off -append 'root=/dev/vda console=ttyS0 / | ||
1223 | hugepagesz=2M hugepages=512 isolcpus=1 nohz_full=1 rcu_nocbs=1 / | ||
1224 | irqaffinity=0 rcu_nocb_poll intel_pstate=disable intel_idle.max_cstate=0 / | ||
1225 | processor.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,/ | ||
1232 | if=virtio,format=raw -m 2048 -object memory-backend-file,id=mem,size=2048M,/ | ||
1233 | mem-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,/ | ||
1237 | mrg_rxbuf=on,rx_queue_size=1024,csum=off,gso=off,guest_tso4=off,/ | ||
1238 | guest_tso6=off,guest_ecn=off -append 'root=/dev/vda console=ttyS0 / | ||
1239 | hugepagesz=2M hugepages=512 isolcpus=1 nohz_full=1 rcu_nocbs=1 / | ||
1240 | irqaffinity=0 rcu_nocb_poll intel_pstate=disable intel_idle.max_cstate=0 / | ||
1241 | processor.max_cstate=0 mce=ignore_ce audit=0'</programlisting>Configure DPDK | ||
1242 | inside VM1:<programlisting>mkdir -p /mnt/huge | ||
1243 | mount -t hugetlbfs nodev /mnt/huge | ||
1244 | modprobe igb_uio | ||
1245 | dpdk-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 | ||
1252 | mount -t hugetlbfs nodev /mnt/huge | ||
1253 | modprobe igb_uio | ||
1254 | dpdk-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 | ||
1260 | start</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 | ||
1266 | show 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 / | ||
1407 | isolcpus=1-7 rcu-nocbs=1-7 rcu_nocb_poll intel_pstate=disable / | ||
1408 | clocksource=tsc tsc=reliable nohpet nosoftlockup intel_idle.max_cstate=0 / | ||
1409 | processor.max_cstate=0 mce=ignore_ce audit=0 nmi_watchdog=0 iommu=pt / | ||
1410 | intel_iommu=on hugepagesz=1GB hugepages=8 default_hugepagesz=1GB / | ||
1411 | hugepagesz=2M hugepages=2048 vfio_iommu_type1.allow_unsafe_interrupts=1</programlisting>Stop | ||
1412 | other services and mount hugepages: <programlisting>systemctl stop openvswitch | ||
1413 | mkdir -p /mnt/huge | ||
1414 | mount -t hugetlbfs hugetlbfs /mnt/huge</programlisting>Configure SR-IOV | ||
1415 | interfaces:<programlisting>/usr/share/usertools/dpdk-devbind.py --bind=ixgbe 0000:03:00.0 | ||
1416 | echo 2 > /sys/class/net/eno3/device/sriov_numvfs | ||
1417 | ifconfig eno3 10.0.0.1 | ||
1418 | modprobe 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 | ||
1421 | ip link set eno3 vf 0 mac 0c:c4:7a:E5:0F:48 | ||
1422 | ip 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 / | ||
1424 | q35 -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,/ | ||
1427 | format=raw -m 4096 -object memory-backend-file,id=mem,size=4096M,mem-path=/mnt/huge,/ | ||
1428 | share=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 / | ||
1430 | isolcpus=1 nohz_full=1 rcu_nocbs=1 irqaffinity=0 rcu_nocb_poll / | ||
1431 | intel_pstate=disable intel_idle.max_cstate=0 / | ||
1432 | processor.max_cstate=0 mce=ignore_ce audit=0' | ||
1433 | |||
1434 | |||
1435 | taskset -c 2,3 qemu-system-x86_64 -cpu host,+invtsc,migratable=no -M / | ||
1436 | q35 -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,/ | ||
1439 | format=raw -m 4096 -object memory-backend-file,id=mem,size=4096M,mem-path=/mnt/huge,/ | ||
1440 | share=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 / | ||
1442 | isolcpus=1 nohz_full=1 rcu_nocbs=1 irqaffinity=0 rcu_nocb_poll / | ||
1443 | intel_pstate=disable intel_idle.max_cstate=0 processor.max_cstate=0 / | ||
1444 | mce=ignore_ce audit=0'</programlisting>In the first VM, mount hugepages and | ||
1445 | start pktgen:<programlisting>mkdir -p /mnt/huge && \ | ||
1446 | mount -t hugetlbfs hugetlbfs /mnt/huge | ||
1447 | modprobe igb_uio | ||
1448 | /usr/share/usertools/dpdk-devbind.py --bind=igb_uio 0000:00:03.0 | ||
1449 | cd /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 | ||
1453 | str</programlisting>In the second VM, mount hugepages and start | ||
1454 | testpmd:<programlisting>mkdir -p /mnt/huge && \ | ||
1455 | mount -t hugetlbfs hugetlbfs /mnt/huge | ||
1456 | modprobe igb_uio | ||
1457 | /usr/share/usertools/dpdk-devbind.py --bind=igb_uio 0000:00:03.0 | ||
1458 | testpmd -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 | ||
1462 | start</programlisting>In order to enable <emphasis | ||
1463 | role="bold">termination</emphasis> mode, in the testpmd console, | ||
1464 | run:<programlisting>set fwd rxonly | ||
1465 | start</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 | ||
52 | mount -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 <PCI device number></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 <--> 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 | <row>, 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 | ||
26 | sudo apt-get -y update | ||
27 | sudo 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 | ||
37 | curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo | ||
38 | chmod a+x ~/bin/repo | ||
39 | export 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 | ||
62 | cd enea-linux | ||
63 | repo init -u git@git.enea.com:linux/manifests/el_manifests-virtualization.git \ | ||
64 | -b refs/tags/EL6 -m $MACHINE/default.xml | ||
65 | repo 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 | ||
30 | lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -> 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 | ||
38 | lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -> dash | ||
39 | # sudo dpkg-reconfigure dash | ||
40 | Use 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]/ | ||
100 | install/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 | ||
111 | list-params - lists all available parameters | ||
112 | list-steps - lists the installer steps and the parameters that they depend on | ||
113 | set - sets a parameter (e.g. <literal>set drive=/dev/sda</literal>) | ||
114 | clear - clears a parameter (e.g. <literal>clear drive</literal>) | ||
115 | list-partitions - lists current drives and partitions | ||
116 | dry - performs a simulation test run | ||
117 | run - executes the installer, using the values you set for each parameter | ||
118 | q 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 <parameter_name>=<parameter_value></programlisting></para> | ||
134 | |||
135 | <orderedlist> | ||
136 | <listitem> | ||
137 | <para><parameter>drive=</dev/sdaX></parameter> - the drive | ||
138 | to partition</para> | ||
139 | </listitem> | ||
140 | |||
141 | <listitem> | ||
142 | <para><parameter>grub_binary=<file></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=<drive></parameter> - | ||
149 | specifies the partition where <filename>GRUB</filename> will be | ||
150 | installed</para> | ||
151 | </listitem> | ||
152 | |||
153 | <listitem> | ||
154 | <para><parameter>rootfs_destination=<drive></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=<rootfs.tar.gz | ||
162 | file></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= | ||
205 | grub_binary= | ||
206 | rootfs_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= | ||
215 | rootfs_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 | ||
234 | run</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 | ||
242 | set grub_destination=/dev/sda1 | ||
243 | set grub_binary=/home/user/grub-binary.efi | ||
244 | set rootfs_destination=/dev/sda2 | ||
245 | set rootfs_targz=/home/user/rootfs.tar.gz | ||
246 | run</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 | ||
253 | set rootfs_targz=/home/user/rootfs.tar.gz | ||
254 | run</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 | <partition></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-<target>.bin | ||
391 | /* kernel image, same as above */ | ||
392 | -- config-<target>.config | ||
393 | /* kernel configuration file */ | ||
394 | -- core-image-minimal-initramfs-<target>.cpio.gz | ||
395 | /* cpio archive of the initramfs */ | ||
396 | -- core-image-minimal-initramfs-<target>.qemuboot.conf | ||
397 | /* qemu config file for the initramfs image */ | ||
398 | -- <image-name>-<target>.ext4 | ||
399 | /* EXT4 image of the rootfs */ | ||
400 | -- <image-name>-<target>.hddimg | ||
401 | /* msdos filesystem containing syslinux, kernel, initrd and rootfs image */ | ||
402 | -- <image-name>-<target>.iso | ||
403 | /* CD .iso image */ | ||
404 | -- <image-name>-<target>.qemuboot.conf | ||
405 | /* qemu config file for the image */ | ||
406 | -- <image-name>-<target>.tar.gz | ||
407 | /* tar archive of the image */ | ||
408 | -- <image-name>-<target>.wic | ||
409 | /* Wic image */ | ||
410 | -- microcode.cpio | ||
411 | /* kernel microcode data */ | ||
412 | -- modules-<target>.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 | ||
464 | prompt 1 | ||
465 | timeout 0 | ||
466 | |||
467 | label 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>> dpkg -i e2fsprogs-mke2fs_1.43.4-r0.0_amd64.deb | ||
511 | > dpkg -i dosfstools_4.1-r0.0_amd64.deb</programlisting> | ||
512 | </listitem> | ||
513 | |||
514 | <listitem> | ||
515 | <para>Partition the disk:</para> | ||
516 | |||
517 | <programlisting>> fdisk /dev/sda | ||
518 | fdisk> g {GPT partition type} | ||
519 | fdisk> n | ||
520 | fdisk> 1 | ||
521 | fdisk> {default start part} | ||
522 | fdisk> +512M | ||
523 | fdisk> t | ||
524 | fdisk> 1 {ESP/EFI partition} | ||
525 | fdisk> n | ||
526 | fdisk> 2 | ||
527 | fdisk> {default start part} | ||
528 | fdisk> +18G | ||
529 | fdisk> 3 | ||
530 | fdisk> {default start part} | ||
531 | fdisk> +20G | ||
532 | ... | ||
533 | fdisk> 7 | ||
534 | fdisk> {default start part} | ||
535 | fdisk> {default end end part} | ||
536 | |||
537 | fdisk> p {print partion table} | ||
538 | fdisk> w {write to disk} | ||
539 | fdisk> q</programlisting> | ||
540 | </listitem> | ||
541 | |||
542 | <listitem> | ||
543 | <para>Format the partitions:</para> | ||
544 | |||
545 | <programlisting>> mkfs.fat -F32 -nEFI /dev/sda1 | ||
546 | > mkfs.ext4 -LROOT /dev/sda2 | ||
547 | > mkfs.ext4 -LROOT /dev/sda3 | ||
548 | > mkfs.ext4 -LROOT /dev/sda4 | ||
549 | > mkfs.ext4 -LROOT /dev/sda5 | ||
550 | > mkfs.ext4 -LROOT /dev/sda6 | ||
551 | > mkfs.ext4 -LROOT /dev/sda7</programlisting> | ||
552 | </listitem> | ||
553 | |||
554 | <listitem> | ||
555 | <para>Create a GRUB partition:</para> | ||
556 | |||
557 | <programlisting>> mkdir /mnt/boot | ||
558 | > mount /dev/sda1 /mnt/boot | ||
559 | > mkdir -p /mnt/boot/EFI/boot | ||
560 | |||
561 | > cp grub-efi-bootx64.efi /mnt/boot/EFI/boot/bootx64.efi | ||
562 | > vi /mnt/boot/EFI/boot/grub.cfg | ||
563 | default=1 | ||
564 | |||
565 | menuentry "Linux Reference Image" { | ||
566 | linux (hd0,gpt2)/boot/bzImage root=/dev/sda2 ip=dhcp | ||
567 | } | ||
568 | |||
569 | menuentry "Linux sda3" { | ||
570 | linux (hd0,gpt3)/boot/bzImage root=/dev/sda3 ip=dhcp | ||
571 | } | ||
572 | |||
573 | menuentry "Linux sda4" { | ||
574 | linux (hd0,gpt4)/boot/bzImage root=/dev/sda4 ip=dhcp | ||
575 | } | ||
576 | |||
577 | menuentry "Linux sda5" { | ||
578 | linux (hd0,gpt5)/boot/bzImage root=/dev/sda5 ip=dhcp | ||
579 | } | ||
580 | |||
581 | menuentry "Linux sda6" { | ||
582 | linux (hd0,gpt6)/boot/bzImage root=/dev/sda6 ip=dhcp | ||
583 | } | ||
584 | |||
585 | menuentry "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> scp ./enea-nfv-access-inteld1521.tar.gz / | ||
606 | root@<target_ip>:/home/root/</programlisting> | ||
607 | </listitem> | ||
608 | |||
609 | <listitem> | ||
610 | <para>Extract image onto the desired partition:</para> | ||
611 | |||
612 | <programlisting>target> mount /dev/sda3 /mnt/sda | ||
613 | target> 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> cat ./enea-nfv-access-inteld1521.tar.gz | / | ||
620 | ssh root@<target_ip> "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 > /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 | ||
205 | where 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 | ||
215 | DPDK 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><kernel></literal> and an | ||
338 | <literal><initrd></literal> element inside the | ||
339 | <literal><os></literal> element of the guest XML file, as in the | ||
340 | following example:</para> | ||
341 | |||
342 | <programlisting><os> | ||
343 | <kernel>bzImage</kernel> | ||
344 | </os> | ||
345 | <devices> | ||
346 | <disk type='file' device='disk'> | ||
347 | <driver name='qemu' type='raw' cache='none'/> | ||
348 | <source file='enea-nfv-access-guest-qemux86-64.ext4'/> | ||
349 | <target dev='vda' bus='virtio'/> | ||
350 | </disk> | ||
351 | </devices></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><os> | ||
373 | <cmdline>console=ttyS0,115200</cmdline> | ||
374 | </os> | ||
375 | <devices> | ||
376 | <console type='pty'> | ||
377 | <target type='serial' port='0'/> | ||
378 | </console> | ||
379 | </devices></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><cputune></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><vcpupin></literal> | ||
397 | tag.</para> | ||
398 | </listitem> | ||
399 | |||
400 | <listitem> | ||
401 | <para>In the <literal><cputune></literal> tag it is further | ||
402 | possible to specify on which CPU the emulator shall run by adding | ||
403 | the cpuset to the <literal><emulatorpin></literal> tag.</para> | ||
404 | |||
405 | <programlisting><vcpu placement='static'>2</vcpu> | ||
406 | <cputune> | ||
407 | <vcpupin vcpu='0' cpuset='2'/> | ||
408 | <vcpupin vcpu='1' cpuset='3'/> | ||
409 | <emulatorpin cpuset="2"/> | ||
410 | </cputune></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><resource></literal> tag:</para> | ||
416 | |||
417 | <programlisting><resource> | ||
418 | <partition>/rt</partition> | ||
419 | </resource></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 | <network> | ||
435 | <name>sriov</name> | ||
436 | <forward mode='hostdev' managed='yes'> | ||
437 | <pf dev='eno3'/> | ||
438 | </forward> | ||
439 | </network></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> <interface type='network'> | ||
464 | <source network='sriov'/> | ||
465 | </interface></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> <interface type='vhostuser'> | ||
481 | <mac address='00:00:00:00:00:01'/> | ||
482 | <source type='unix' path='/var/run/openvswitch/vhost-user1' mode='client'/> | ||
483 | <model type='virtio'/> | ||
484 | <driver queues='1'> | ||
485 | <host mrg_rxbuf='off'/> | ||
486 | </driver> | ||
487 | </interface></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 > /sys/class/net/eno3/device/sriov_numvfs | ||
526 | $ modprobe vfio_pci | ||
527 | $ dpdk-devbind.py --bind=vfio-pci 0000:03:10.0 | ||
528 | <interface type='hostdev' managed='yes'> | ||
529 | <source> | ||
530 | <address type='pci' domain='0x0' bus='0x03' slot='0x10' function='0x0'/> | ||
531 | </source> | ||
532 | <mac address='52:54:00:6d:90:02'/> | ||
533 | </interface></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> <interface type='bridge'> | ||
543 | <mac address='52:54:00:71:b1:b6'/> | ||
544 | <source bridge='ovsbr0'/> | ||
545 | <virtualport type='openvswitch'/> | ||
546 | <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/> | ||
547 | </interface></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><domain type='kvm'> | ||
562 | <name>vm_vhost</name> | ||
563 | <uuid>4a9b3f53-fa2a-47f3-a757-dd87720d9d1d</uuid> | ||
564 | <memory unit='KiB'>4194304</memory> | ||
565 | <currentMemory unit='KiB'>4194304</currentMemory> | ||
566 | <memoryBacking> | ||
567 | <hugepages> | ||
568 | <page size='1' unit='G' nodeset='0'/> | ||
569 | </hugepages> | ||
570 | </memoryBacking> | ||
571 | <vcpu placement='static'>2</vcpu> | ||
572 | <cputune> | ||
573 | <shares>4096</shares> | ||
574 | <vcpupin vcpu='0' cpuset='4'/> | ||
575 | <vcpupin vcpu='1' cpuset='5'/> | ||
576 | <emulatorpin cpuset='4,5'/> | ||
577 | </cputune> | ||
578 | <os> | ||
579 | <type arch='x86_64' machine='pc'>hvm</type> | ||
580 | <kernel>/mnt/qemu/bzImage</kernel> | ||
581 | <cmdline>root=/dev/vda console=ttyS0,115200</cmdline> | ||
582 | <boot dev='hd'/> | ||
583 | </os> | ||
584 | <features> | ||
585 | <acpi/> | ||
586 | <apic/> | ||
587 | </features> | ||
588 | <cpu mode='host-model'> | ||
589 | <model fallback='allow'/> | ||
590 | <topology sockets='2' cores='1' threads='1'/> | ||
591 | <numa> | ||
592 | <cell id='0' cpus='0-1' memory='4194304' unit='KiB' memAccess='shared'/> | ||
593 | </numa> | ||
594 | </cpu> | ||
595 | <on_poweroff>destroy</on_poweroff> | ||
596 | <on_reboot>restart</on_reboot> | ||
597 | <on_crash>destroy</on_crash> | ||
598 | <devices> | ||
599 | <emulator>/usr/bin/qemu-system-x86_64</emulator> | ||
600 | <disk type='file' device='disk'> | ||
601 | <driver name='qemu' type='raw' cache='none'/> | ||
602 | <source file='/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4'/> | ||
603 | <target dev='vda' bus='virtio'/> | ||
604 | </disk> | ||
605 | <interface type='vhostuser'> | ||
606 | <mac address='00:00:00:00:00:01'/> | ||
607 | <source type='unix' path='/var/run/openvswitch/vhost-user1' mode='client'/> | ||
608 | <model type='virtio'/> | ||
609 | <driver queues='1'> | ||
610 | <host mrg_rxbuf='off'/> | ||
611 | </driver> | ||
612 | </interface> | ||
613 | <serial type='pty'> | ||
614 | <target port='0'/> | ||
615 | </serial> | ||
616 | <console type='pty'> | ||
617 | <target type='serial' port='0'/> | ||
618 | </console> | ||
619 | </devices> | ||
620 | </domain></programlisting> | ||
621 | </section> | ||
622 | |||
623 | <section id="guest-config-pci-passthrough"> | ||
624 | <title>Guest configuration with PCI passthrough</title> | ||
625 | |||
626 | <programlisting><domain type='kvm'> | ||
627 | <name>vm_sriov1</name> | ||
628 | <uuid>4a9b3f53-fa2a-47f3-a757-dd87720d9d1d</uuid> | ||
629 | <memory unit='KiB'>4194304</memory> | ||
630 | <currentMemory unit='KiB'>4194304</currentMemory> | ||
631 | <memoryBacking> | ||
632 | <hugepages> | ||
633 | <page size='1' unit='G' nodeset='0'/> | ||
634 | </hugepages> | ||
635 | </memoryBacking> | ||
636 | <vcpu>2</vcpu> | ||
637 | <os> | ||
638 | <type arch='x86_64' machine='q35'>hvm</type> | ||
639 | <kernel>/mnt/qemu/bzImage</kernel> | ||
640 | <cmdline>root=/dev/vda console=ttyS0,115200</cmdline> | ||
641 | <boot dev='hd'/> | ||
642 | </os> | ||
643 | <features> | ||
644 | <acpi/> | ||
645 | <apic/> | ||
646 | </features> | ||
647 | <cpu mode='host-model'> | ||
648 | <model fallback='allow'/> | ||
649 | <topology sockets='1' cores='2' threads='1'/> | ||
650 | <numa> | ||
651 | <cell id='0' cpus='0' memory='4194304' unit='KiB' memAccess='shared'/> | ||
652 | </numa> | ||
653 | </cpu> | ||
654 | <on_poweroff>destroy</on_poweroff> | ||
655 | <on_reboot>restart</on_reboot> | ||
656 | <on_crash>destroy</on_crash> | ||
657 | <devices> | ||
658 | <emulator>/usr/bin/qemu-system-x86_64</emulator> | ||
659 | <disk type='file' device='disk'> | ||
660 | <driver name='qemu' type='raw' cache='none'/> | ||
661 | <source file='/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4'/> | ||
662 | <target dev='vda' bus='virtio'/> | ||
663 | </disk> | ||
664 | <interface type='hostdev' managed='yes'> | ||
665 | <source> | ||
666 | <address type='pci' domain='0x0' bus='0x03' slot='0x10' function='0x0'/> | ||
667 | </source> | ||
668 | <mac address='52:54:00:6d:90:02'/> | ||
669 | </interface> | ||
670 | <serial type='pty'> | ||
671 | <target port='0'/> | ||
672 | </serial> | ||
673 | <console type='pty'> | ||
674 | <target type='serial' port='0'/> | ||
675 | </console> | ||
676 | </devices> | ||
677 | </domain></programlisting> | ||
678 | </section> | ||
679 | |||
680 | <section id="guest-config-bridge-interface"> | ||
681 | <title>Guest configuration with bridge interface</title> | ||
682 | |||
683 | <programlisting><domain type='kvm'> | ||
684 | <name>vm_bridge</name> | ||
685 | <uuid>4a9b3f53-fa2a-47f3-a757-dd87720d9d1d</uuid> | ||
686 | <memory unit='KiB'>4194304</memory> | ||
687 | <currentMemory unit='KiB'>4194304</currentMemory> | ||
688 | <memoryBacking> | ||
689 | <hugepages> | ||
690 | <page size='1' unit='G' nodeset='0'/> | ||
691 | </hugepages> | ||
692 | </memoryBacking> | ||
693 | <vcpu placement='static'>2</vcpu> | ||
694 | <cputune> | ||
695 | <shares>4096</shares> | ||
696 | <vcpupin vcpu='0' cpuset='4'/> | ||
697 | <vcpupin vcpu='1' cpuset='5'/> | ||
698 | <emulatorpin cpuset='4,5'/> | ||
699 | </cputune> | ||
700 | <os> | ||
701 | <type arch='x86_64' machine='q35'>hvm</type> | ||
702 | <kernel>/mnt/qemu/bzImage</kernel> | ||
703 | <cmdline>root=/dev/vda console=ttyS0,115200</cmdline> | ||
704 | <boot dev='hd'/> | ||
705 | </os> | ||
706 | <features> | ||
707 | <acpi/> | ||
708 | <apic/> | ||
709 | </features> | ||
710 | <cpu mode='host-model'> | ||
711 | <model fallback='allow'/> | ||
712 | <topology sockets='2' cores='1' threads='1'/> | ||
713 | <numa> | ||
714 | <cell id='0' cpus='0-1' memory='4194304' unit='KiB' memAccess='shared'/> | ||
715 | </numa> | ||
716 | </cpu> | ||
717 | <on_poweroff>destroy</on_poweroff> | ||
718 | <on_reboot>restart</on_reboot> | ||
719 | <on_crash>destroy</on_crash> | ||
720 | <devices> | ||
721 | <emulator>/usr/bin/qemu-system-x86_64</emulator> | ||
722 | <disk type='file' device='disk'> | ||
723 | <driver name='qemu' type='raw' cache='none'/> | ||
724 | <source file='/mnt/qemu/enea-nfv-access-guest-qemux86-64.ext4'/> | ||
725 | <target dev='vda' bus='virtio'/> | ||
726 | </disk> | ||
727 | <interface type='bridge'> | ||
728 | <mac address='52:54:00:71:b1:b6'/> | ||
729 | <source bridge='ovsbr0'/> | ||
730 | <virtualport type='openvswitch'/> | ||
731 | <address type='pci' domain='0x0000' bus='0x00' slot='0x03' function='0x0'/> | ||
732 | </interface> | ||
733 | <serial type='pty'> | ||
734 | <target port='0'/> | ||
735 | </serial> | ||
736 | <console type='pty'> | ||
737 | <target type='serial' port='0'/> | ||
738 | </console> | ||
739 | </devices> | ||
740 | </domain></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 – Optimized Linux kernel with the focus on | ||
81 | vCPE systems characteristics.</para> | ||
82 | </listitem> | ||
83 | |||
84 | <listitem> | ||
85 | <para>KVM – Virtualization with virtual machines. KVM is the | ||
86 | standard virtualization engine for Linux based systems.</para> | ||
87 | </listitem> | ||
88 | |||
89 | <listitem> | ||
90 | <para>Docker – 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 – Optimized OVS-DPDK provides high | ||
97 | throughput and low latency.</para> | ||
98 | </listitem> | ||
99 | |||
100 | <listitem> | ||
101 | <para>Edge Link – 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 – 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 – CLI access over virsh and | ||
136 | libvirt.</para> | ||
137 | </listitem> | ||
138 | |||
139 | <listitem> | ||
140 | <para>FCAPS framework – 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 – 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 | ||
108 | rm -f /var/run/openvswitch/vhost-user* | ||
109 | rm -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 | ||
116 | ovsdb-tool create /etc/openvswitch/conf.db /usr/share/openvswitch/vswitch.ovsschema | ||
117 | ovsdb-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 | ||
125 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-lcore-mask=0x1 | ||
126 | ovs-vsctl --no-wait set Open_vSwitch . other_config:pmd-cpu-mask=0xc | ||
127 | ovs-vsctl --no-wait set Open_vSwitch . other_config:dpdk-init=true | ||
128 | ovs-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 | ||
136 | ovs-vsctl add-port ovsbr0 dpdk0 -- set Interface dpdk0 type=dpdk / | ||
137 | :dpdk-devargs=<PCI device></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 | ||
155 | ovs-ofctl show ovsbr0 | ||
156 | ovs-ofctl add-flow ovsbr0 in_port=1,action=output:2 | ||
157 | ovs-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 | ||
101 | clean: | ||
102 | rm -f *.o helloworld | ||
103 | #include stdio.h; | ||
104 | int 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 | ||
121 | hello 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 | ||
144 | PWD := $(shell pwd) | ||
145 | |||
146 | KERNEL_SRC := full path to kernel source tree | ||
147 | |||
148 | all: scripts | ||
149 | $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" modules | ||
150 | scripts: | ||
151 | $(MAKE) -C $(KERNEL_SRC) scripts | ||
152 | clean: | ||
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 | |||
158 | static 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 | |||
165 | static void __exit hello_end(void) | ||
166 | { | ||
167 | printk(KERN_INFO "Goodbye, world\n"); | ||
168 | } | ||
169 | |||
170 | module_init(hello_start); | ||
171 | module_exit(hello_end); | ||
172 | |||
173 | MODULE_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@<target_ip_address>:/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 –t tap0 –a 192.168.122.10 –p 1050 –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 | ||
273 | ip link set enp0s2 up | ||
274 | ip 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 –t tap0 –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 –t tap0 –a 192.168.122.10 –p 1050 –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 – for kernel cross-debugging</para> | ||
308 | </listitem> | ||
309 | |||
310 | <listitem> | ||
311 | <para>GDBServer – 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 :<port_no> /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><sdkdir></literal>, start the cross-gdb:<programlisting># x86_64-enea-linux-gdb <path_to_the_program>/helloworld</programlisting>Connect | ||
333 | the GDB to the target: <programlisting>(gdb) target remote <target_ip_address>:<port_no></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 –t tap0 –a 192.168.122.10 –p 1051 –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> – 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>– 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 | ||
392 | ip link set enp0s2 up | ||
393 | ip 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 | <sdkdir></filename>, start the cross-gdb:<programlisting># x86_64-enea-linux-gdb <path_to_the_program>/helloworld</programlisting></para> | ||
408 | </listitem> | ||
409 | |||
410 | <listitem> | ||
411 | <para>Connect GDB to the target:<programlisting>(gdb) target remote <target_ip_address>: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 > /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 > /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><sdkdir>/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 | ||
4 | BOOK_VER ?= $(REL_VER)-dev | ||
5 | |||
6 | DOCBOOK_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 | |||
8 | BOOKPACKAGES := book-enea-nfv-access-guide | ||
9 | BOOKDESC_$(BOOKPACKAGES) := "Enea NFV Access $(PROD_VER) Guide" | ||
10 | BOOKDEFAULTCONDITION := $(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 | ||
30 | lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -> bash</programlisting> | 30 | lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -> 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 | ||
38 | lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -> dash | ||
39 | # sudo dpkg-reconfigure dash | ||
40 | Use 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 | ||
81 | list-params - lists parameters | ||
82 | list-steps - lists the available steps and the parameters that they depend on | ||
83 | set - sets a parameter (e.g. "set drive=/dev/sda") | ||
84 | clear - clears a parameter (e.g. "clear drive") | ||
85 | list-partitions - lists current drives and partitions | ||
86 | dry - describes the steps to be executed and checks if the files exist | ||
87 | run - executes the steps | ||
88 | q 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> | 100 | 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 | ||
111 | list-params - lists all available parameters | ||
112 | list-steps - lists the installer steps and the parameters that they depend on | ||
113 | set - sets a parameter (e.g. <literal>set drive=/dev/sda</literal>) | ||
114 | clear - clears a parameter (e.g. <literal>clear drive</literal>) | ||
115 | list-partitions - lists current drives and partitions | ||
116 | dry - performs a simulation test run | ||
117 | run - executes the installer, using the values you set for each parameter | ||
118 | q 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 <parameter_name>=<parameter_value></programlisting></para> | ||
134 | |||
135 | <orderedlist> | ||
136 | <listitem> | ||
137 | <para><parameter>drive=</dev/sdaX></parameter> - the drive | ||
138 | to partition</para> | ||
139 | </listitem> | ||
140 | |||
141 | <listitem> | ||
142 | <para><parameter>grub_binary=<file></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=<drive></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=<drive></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=<rootfs.tar.gz |
162 | file></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= |
147 | grub_binary= | 205 | grub_binary= |
148 | rootfs_destination=</programlisting></para> | 206 | rootfs_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= | ||
156 | rootfs_destination=</programlisting></para> | 215 | rootfs_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 | |
168 | grub_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> |
170 | rootfs_destination=[drive] - specifies where the rootfs will be deployed | 229 | |
171 | rootfs_targz=[.tar.gz file] - what file to unpack to where rootfs_destination is set | 230 | <example id="example_one"> |
172 | drive=[/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 | 234 | run</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 |
183 | run</programlisting></para> | ||
184 | |||
185 | <para>Example of partitioning a drive, installing GRUB and a root | ||
186 | filesystem:<programlisting>set drive=/dev/sda | ||
187 | set grub_destination=/dev/sda1 | 242 | set grub_destination=/dev/sda1 |
188 | set grub_binary=/home/user/grub-binary.efi | 243 | set grub_binary=/home/user/grub-binary.efi |
189 | set rootfs_destination=/dev/sda2 | 244 | set rootfs_destination=/dev/sda2 |
190 | set rootfs_targz=/home/user/rootfs.tar.gz | 245 | set rootfs_targz=/home/user/rootfs.tar.gz |
191 | run</programlisting></para> | 246 | run</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"> |
194 | set rootfs_targz=/home/user/rootfs.tar.gz | 250 | <title>Deploying ONLY a root filesystem:</title> |
195 | runs</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 | 253 | set rootfs_targz=/home/user/rootfs.tar.gz |
199 | it as a primary boot device.</para> | 254 | run</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 | <partition></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-<target>.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 | <row>, 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 | ||
26 | sudo apt-get -y update | ||
27 | sudo 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 | ||
37 | curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo | ||
38 | chmod a+x ~/bin/repo | ||
39 | export 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 | ||
62 | cd enea-linux | ||
63 | repo init -u git@git.enea.com:linux/manifests/el_manifests-virtualization.git \ | ||
64 | -b refs/tags/EL6 -m $MACHINE/default.xml | ||
65 | repo 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 @@ | |||
1 | eltf_params_template_updated_howto_use.txt | ||
2 | |||
3 | This is a way to collect all parameters for an Enea NFV Access release | ||
4 | in one parameter file, easy to automatically update by ELTF regularly. | ||
5 | |||
6 | NOTE: 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 | |||
9 | NOTE: 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 | |||
17 | The ordinary book XML files use xi:include statements to include elements | ||
18 | from this parameter file. The book XML files can thus be manually edited. | ||
19 | Before editing, you must run "make init". | ||
20 | Any other text in the template or updated.xml file, outside the parts that | ||
21 | are included in the book, are not used but still all must be correct | ||
22 | DocBook XML files. | ||
23 | |||
24 | ELTF work: | ||
25 | template => ELTF replaces ALL ELTF_xxx variables => updated XML file | ||
26 | => push to git only if changed | ||
27 | |||
28 | |||
29 | eltf_params_template.xml (in git) | ||
30 | File used by ELTF to autocreate/update the real parameter | ||
31 | file eltf_params_updated.xml. | ||
32 | |||
33 | eltf_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 | |||
39 | xi: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 | |||
48 | DocBook XML: All XML files must be correct DocBook XML files. | ||
49 | |||
50 | Do 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 | |||
54 | ELTF should autocreate a temporary "real" file but only replace | ||
55 | and push the eltf_params_updated.xml if it is changed. | ||
56 | |||
57 | |||
58 | make eltf | ||
59 | This lists all ELTF_xxx variables and some rules how to treat them | ||
60 | |||
61 | DocBook 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 < > and & | ||
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 | |||
71 | DocBook 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 | |||
81 | DocBook 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 | |||
85 | Each 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 | |||
98 | Tables 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 | |||
102 | Special - 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 | |||
112 | BELOW WE TRY TO EXPLAIN EACH ELTF_* variable, but always check with make eltf | ||
113 | if there are more new variables, missing in this description file. | ||
114 | |||
115 | _____________________________________________________________________________ | ||
116 | ELTF_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 | ||
125 | sudo apt-get update | ||
126 | sudo 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 | _____________________________________________________________________________ | ||
133 | ELTF_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: | ||
137 | mkdir -p ~/bin | ||
138 | curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo | ||
139 | chmod a+x ~/bin/repo | ||
140 | export PATH=~/bin:$PATH | ||
141 | |||
142 | _____________________________________________________________________________ | ||
143 | ELTF_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: | ||
150 | 6 | ||
151 | or | ||
152 | 6.1 | ||
153 | |||
154 | _____________________________________________________________________________ | ||
155 | ELTF_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: | ||
160 | 2.1 | ||
161 | |||
162 | _____________________________________________________________________________ | ||
163 | ELTF_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: | ||
168 | krogoth | ||
169 | |||
170 | _____________________________________________________________________________ | ||
171 | ELTF_YOCTO_PROJ_DOWNLOAD_TXTURL General parameters. These two are IDENTICAL | ||
172 | ELTF_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: | ||
177 | http://www.yoctoproject.org/downloads/core/krogoth/21 | ||
178 | |||
179 | _____________________________________________________________________________ | ||
180 | ELTF_EL_DOWNLOAD_TXTURL General parameters. These two are IDENTICAL strings | ||
181 | ELTF_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: | ||
187 | http://linux.enea.com/6 | ||
188 | |||
189 | _____________________________________________________________________________ | ||
190 | ELTF_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: | ||
197 | mkdir enea-linux | ||
198 | cd enea-linux | ||
199 | repo init -u git@git.enea.com:linux/manifests/el_manifests-virtualization.git \ | ||
200 | -b refs/tags/EL6 -m $MACHINE/default.xml | ||
201 | repo sync | ||
202 | |||
203 | _____________________________________________________________________________ | ||
204 | ELTF_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. | ||
214 | 4.5 (Mars) | ||
215 | |||
216 | |||
217 | _____________________________________________________________________________ | ||
218 | ELTF_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 | _____________________________________________________________________________ | ||
226 | ELTF_T_MANIFEST_DIR This happens to be in two places. Must be exactly | ||
227 | ELTF_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: | ||
232 | p2041rgb | ||
233 | or | ||
234 | ls1021aiot | ||
235 | or | ||
236 | qemuarm | ||
237 | |||
238 | _____________________________________________________________________________ | ||
239 | ELTF_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: | ||
243 | P2041RGB | ||
244 | or | ||
245 | LS1021a-IoT | ||
246 | or | ||
247 | qemuarm | ||
248 | |||
249 | _____________________________________________________________________________ | ||
250 | ELTF_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: | ||
255 | Power, e500mc | ||
256 | or | ||
257 | ARM Cortex-A7 | ||
258 | |||
259 | _____________________________________________________________________________ | ||
260 | ELTF_T_DS_TXTURL Target specific: "Link to target datasheet. These | ||
261 | ELTF_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: | ||
268 | url="http://wiki.qemu.org">http://wiki.qemu.org | ||
269 | or | ||
270 | url="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 | _____________________________________________________________________________ | ||
273 | ELTF_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: | ||
279 | 15.0.0 | ||
280 | or | ||
281 | Git commit id: 75ca53211488a3e268037a44ee2a7ac5c7181bd2 | ||
282 | |||
283 | _____________________________________________________________________________ | ||
284 | ELTF_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: | ||
290 | 5.3 | ||
291 | |||
292 | _____________________________________________________________________________ | ||
293 | ELTF_T_KERN_VER Target specific: "Linux Kernel Version". Often | ||
294 | different per target. | ||
295 | In book: An <entry> in a row | ||
296 | Example: | ||
297 | 3.12 | ||
298 | |||
299 | _____________________________________________________________________________ | ||
300 | ELTF_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: | ||
306 | Ethernet, I2C, SPI, PCI, USB, SD/SDHC/SDXC | ||
307 | |||
308 | |||
309 | _____________________________________________________________________________ | ||
310 | ELTF_T_EL_RPM_TXTURL Target specific: "Enea rpm folder for downloading | ||
311 | ELTF_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: | ||
318 | url="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 -> 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 | ||
4 | BOOK_VER ?= $(REL_VER)-dev | ||
5 | |||
6 | DOCBOOK_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 | |||
8 | BOOKPACKAGES := book-enea-nfv-access-release-info | ||
9 | BOOKDESC_$(BOOKPACKAGES) := "Enea NFV Access $(PROD_VER) Release Information" | ||
10 | BOOKDEFAULTCONDITION := $(DEFAULTCONDITIONS) | ||