diff options
Diffstat (limited to 'doc/book-enea-nfv-access-platform-guide')
14 files changed, 1800 insertions, 0 deletions
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/benchmarks.xml b/doc/book-enea-nfv-access-platform-guide/doc/benchmarks.xml new file mode 100644 index 0000000..0db4fa4 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/benchmarks.xml | |||
@@ -0,0 +1,14 @@ | |||
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>Benchmarks</title> | ||
6 | |||
7 | <para></para> | ||
8 | |||
9 | <section id="relinfo-getting-pre-built-images"> | ||
10 | <title></title> | ||
11 | |||
12 | <para></para> | ||
13 | </section> | ||
14 | </chapter> \ No newline at end of file | ||
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/book.xml b/doc/book-enea-nfv-access-platform-guide/doc/book.xml new file mode 100644 index 0000000..9b0cc4a --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/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 | ]> | ||
5 | <book id="book_enea_nfv_access_platform_guide"> | ||
6 | <title><trademark class="registered">Enea</trademark> NFV Access Platform Guide</title> | ||
7 | <subtitle>Release Version | ||
8 | <xi:include href="eltf_params_updated.xml" xpointer="element(EneaLinux_REL_VER/1)" | ||
9 | xmlns:xi="http://www.w3.org/2001/XInclude" /></subtitle> | ||
10 | <xi:include href="../../s_docbuild/template/docsrc_common/bookinfo_userdoc.xml" | ||
11 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
12 | <xi:include href="platform_overview.xml" | ||
13 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
14 | <xi:include href="getting_started.xml" | ||
15 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
16 | <xi:include href="hypervisor_virtualization.xml" | ||
17 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
18 | <xi:include href="container_virtualization.xml" | ||
19 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
20 | <xi:include href="ovs.xml" | ||
21 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
22 | <xi:include href="dpdk.xml" | ||
23 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
24 | <xi:include href="benchmarks.xml" | ||
25 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
26 | <xi:include href="using_nfv_access_platform_sdks.xml" | ||
27 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
28 | <xi:include href="../../s_docbuild/template/docsrc_common/contacting_enea_enea_linux.xml" | ||
29 | xmlns:xi="http://www.w3.org/2001/XInclude" /> | ||
30 | </book> | ||
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/container_virtualization.xml b/doc/book-enea-nfv-access-platform-guide/doc/container_virtualization.xml new file mode 100644 index 0000000..6f74061 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/container_virtualization.xml | |||
@@ -0,0 +1,8 @@ | |||
1 | <?xml version="1.0" encoding="UTF-8"?> | ||
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 condition="hidden" id="workflow"> | ||
5 | <title>Container Virtualization</title> | ||
6 | |||
7 | <para></para> | ||
8 | </chapter> \ No newline at end of file | ||
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/dpdk.xml b/doc/book-enea-nfv-access-platform-guide/doc/dpdk.xml new file mode 100644 index 0000000..91b36d3 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/dpdk.xml | |||
@@ -0,0 +1,118 @@ | |||
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.02/index.html">http://dpdk.org/doc/guides-17.02/index.html</ulink></para> | ||
24 | |||
25 | <section id="pktgen"> | ||
26 | <title>Pktgen</title> | ||
27 | |||
28 | <para>In addition to DPDK, Enea NFV Access Platform 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.02/tools/devbind.html">http://dpdk.org/doc/guides-17.02/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 | [FIXME]:</para> | ||
92 | </listitem> | ||
93 | |||
94 | <listitem> | ||
95 | <para>On board 1, start the Pktgen application:</para> | ||
96 | |||
97 | <programlisting>cd /usr/share/apps/pktgen/./pktgen -c 0x7 -n 4 --socket-mem 1024 -- -P -m "[1:2].0"</programlisting> | ||
98 | |||
99 | <para>In the Pktgen console, run:</para> | ||
100 | |||
101 | <programlisting>start 0</programlisting> | ||
102 | |||
103 | <para>The Pktgen output will display the traffic configuration and | ||
104 | statistics.</para> | ||
105 | </listitem> | ||
106 | |||
107 | <listitem> | ||
108 | <para>On board 2, start the testpmd application:</para> | ||
109 | |||
110 | <programlisting>testpmd -c 0x7 -n 4 -- --txd=512 --rxd=512 --port-topology=chained</programlisting> | ||
111 | |||
112 | <para>For more information, refer to the testpmd application user | ||
113 | guide: <ulink | ||
114 | url="http://dpdk.org/doc/guides-17.02/testpmd_app_ug/index.html">http://dpdk.org/doc/guides-17.02/testpmd_app_ug/index.html</ulink>.</para> | ||
115 | </listitem> | ||
116 | </orderedlist> | ||
117 | </section> | ||
118 | </chapter> \ No newline at end of file | ||
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/eltf_params_template.xml b/doc/book-enea-nfv-access-platform-guide/doc/eltf_params_template.xml new file mode 100644 index 0000000..278ad71 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/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 Linux 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 | Linux 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-platform-guide/doc/eltf_params_updated.xml b/doc/book-enea-nfv-access-platform-guide/doc/eltf_params_updated.xml new file mode 100644 index 0000000..31a251d --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/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.0</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/el_manifests-networking.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 Linux 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 Targets with Parameters</title> | ||
93 | |||
94 | <para>The tables below describes the target(s) supported in this Enea | ||
95 | Linux 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-platform-guide/doc/eltf_params_updated_template_how_to_use.txt b/doc/book-enea-nfv-access-platform-guide/doc/eltf_params_updated_template_how_to_use.txt new file mode 100644 index 0000000..7f1d3cb --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/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 Linux 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 | Linux 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 Linux 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/el_manifests-standard.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-platform-guide/doc/getting_started.xml b/doc/book-enea-nfv-access-platform-guide/doc/getting_started.xml new file mode 100644 index 0000000..b534e20 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/getting_started.xml | |||
@@ -0,0 +1,127 @@ | |||
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 ENFV Access Platform</title> | ||
6 | |||
7 | <section id="release-content"> | ||
8 | <title>NFV Access Platform Release content</title> | ||
9 | |||
10 | <para>The NFV Access Platform 1.0 Release contains along with other items, | ||
11 | documentation, pre-built kernels and images, a bootloader and a | ||
12 | SDK.</para> | ||
13 | |||
14 | <para>The directories structure is detailed below:</para> | ||
15 | |||
16 | <programlisting>-- documentation/ | ||
17 | /* NFV Access Platform documentation */ | ||
18 | -- inteld1521/ | ||
19 | /* artifacts for the host side */ | ||
20 | -- deb/ | ||
21 | /* deb packages */ | ||
22 | -- images/ | ||
23 | -- enea-image-virtualization-host | ||
24 | /* precompiled artifacts for the Host release image */ | ||
25 | -- various artifacts | ||
26 | -- enea-image-virtualization-host-sdk | ||
27 | /* precompiled artifacts for the Host SDK image. | ||
28 | The SDK image contains userspace tools and kernel | ||
29 | configurations necessary for developing, debugging | ||
30 | and profiling applications and kernel modules */ | ||
31 | -- various artifacts | ||
32 | -- sdk | ||
33 | /* NFV Access Platform SDK for the host */ | ||
34 | -- enea-glibc-x86_64-enea-image-virtualization-host-sdk / | ||
35 | -corei7-64-toolchain-7.0.sh | ||
36 | /* self-extracting archive installing | ||
37 | cross-compilation toolchain for the host */ | ||
38 | -- qemux86-64 | ||
39 | /* artifacts for the guest side */ | ||
40 | -- deb/ | ||
41 | /* deb packages */ | ||
42 | -- images/ | ||
43 | -- enea-image-virtualization-guest | ||
44 | /* precompiled artifacts for the Guest image */ | ||
45 | -- various artifacts | ||
46 | -- sdk | ||
47 | /* NFV Access Platform SDK for the guest */ | ||
48 | -- enea-glibc-x86_64-enea-image-virtualization-guest-sdk / | ||
49 | -core2-64-toolchain-7.0.sh | ||
50 | /* self-extracting archive installing cross-compilation | ||
51 | toolchain for the guest (QEMU x86-64) */ | ||
52 | </programlisting> | ||
53 | |||
54 | <para>For each combination of image and target, the following set of | ||
55 | artifacts is available:</para> | ||
56 | |||
57 | <programlisting>-- bzImage | ||
58 | /* kernel image */ | ||
59 | -- bzImage-<target>.bin | ||
60 | /* kernel image, same as above */ | ||
61 | -- config-<target>.config | ||
62 | /* kernel configuration file */ | ||
63 | -- core-image-minimal-initramfs-<target>.cpio.gz | ||
64 | /* cpio archive of the initramfs */ | ||
65 | -- core-image-minimal-initramfs-<target>.qemuboot.conf | ||
66 | /* qemu config file for the initramfs image */ | ||
67 | -- <image-name>-<target>.ext4 | ||
68 | /* EXT4 image of the rootfs */ | ||
69 | -- <image-name>-<target>.hddimg | ||
70 | /* msdos filesystem containing syslinux, kernel, initrd and rootfs image */ | ||
71 | -- <image-name>-<target>.iso | ||
72 | /* CD .iso image */ | ||
73 | -- <image-name>-<target>.qemuboot.conf | ||
74 | /* qemu config file for the image */ | ||
75 | -- <image-name>-<target>.tar.gz | ||
76 | /* tar archive of the image */ | ||
77 | -- <image-name>-<target>.wic | ||
78 | /* Wic image */ | ||
79 | -- microcode.cpio | ||
80 | /* kernel microcode data */ | ||
81 | -- modules-<target>.tgz | ||
82 | /* external kernel modules */ | ||
83 | -- ovmf.*.qcow2 | ||
84 | /* ovmf firmware for uefi support in qemu */ | ||
85 | -- rmc.db | ||
86 | /* Central RMC Database */ | ||
87 | -- systemd-bootx64.efi | ||
88 | /* systemd-boot EFI file */</programlisting> | ||
89 | </section> | ||
90 | |||
91 | <section id="docs"> | ||
92 | <title>Included Documention</title> | ||
93 | |||
94 | <para>Enea NFV Access is provided with the following set of | ||
95 | documents:</para> | ||
96 | |||
97 | <itemizedlist> | ||
98 | <listitem> | ||
99 | <para>Enea NFV Access Guide – A document describing the Enea NFV | ||
100 | Access release content and how to use it, as well as benchmark | ||
101 | results.</para> | ||
102 | </listitem> | ||
103 | |||
104 | <listitem> | ||
105 | <para>Enea NFV Access Open Source Report – A document containing | ||
106 | the open source and license information pertaining to packages | ||
107 | provided with Enea NFV Access 1.0.</para> | ||
108 | </listitem> | ||
109 | |||
110 | <listitem> | ||
111 | <para>Enea NFV Access Test Report – The document that summarizes | ||
112 | the test results for the Enea NFV Access release.</para> | ||
113 | </listitem> | ||
114 | |||
115 | <listitem> | ||
116 | <para>Enea NFV Access Security Report – The document that lists | ||
117 | all security fixes included in the Enea NFV Access 1.0 release.</para> | ||
118 | </listitem> | ||
119 | </itemizedlist> | ||
120 | </section> | ||
121 | |||
122 | <section id="prebuilt-artifacts"> | ||
123 | <title>How to use Prebuilt Artifacts</title> | ||
124 | |||
125 | <para></para> | ||
126 | </section> | ||
127 | </chapter> \ No newline at end of file | ||
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/hypervisor_virtualization.xml b/doc/book-enea-nfv-access-platform-guide/doc/hypervisor_virtualization.xml new file mode 100644 index 0000000..092b52f --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/hypervisor_virtualization.xml | |||
@@ -0,0 +1,328 @@ | |||
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 Linux 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-image-virtualization-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 | <section id="qemu-multiqueue-support"> | ||
197 | <title>QEMU multi queue support configuration</title> | ||
198 | |||
199 | <programlisting>-chardev socket,id=char0,path=/var/run/openvswitch/vhost-user1 \ | ||
200 | -netdev type=vhost-user,id=net0,chardev=char0,queues=2 \ | ||
201 | -device virtio-net-pci,netdev=net0,mac=22:EA:FB:A8:25:AE,mq=on,vectors=6 | ||
202 | where vectors is calculated as: 2 + 2 * queues number.</programlisting> | ||
203 | </section> | ||
204 | |||
205 | <section id="inside-guest"> | ||
206 | <title>Inside guest</title> | ||
207 | |||
208 | <para>Linux kernel virtio-net driver (one queue is enabled by | ||
209 | default):</para> | ||
210 | |||
211 | <programlisting>$ ethtool -L combined 2 eth0 | ||
212 | DPDK Virtio PMD | ||
213 | $ testpmd -c 0x7 -- -i --rxq=2 --txq=2 --nb-cores=2 ...</programlisting> | ||
214 | |||
215 | <para>For QEMU documentation please see: <ulink | ||
216 | url="https://qemu.weilnetz.de/doc/qemu-doc.html">https://qemu.weilnetz.de/doc/qemu-doc.html</ulink>.</para> | ||
217 | </section> | ||
218 | </section> | ||
219 | </section> | ||
220 | |||
221 | <section id="libvirt"> | ||
222 | <title>Libvirt</title> | ||
223 | |||
224 | <para>One way to manage guests in Enea NFV Access is by using | ||
225 | <literal>libvirt</literal>. Libvirt is used in conjunction with a daemon | ||
226 | (<literal>libvirtd</literal>) and a command line utility (virsh) to manage | ||
227 | virtualized environments.</para> | ||
228 | |||
229 | <para>The libvirt library is a hypervisor-independent virtualization API | ||
230 | and toolkit that is able to interact with the virtualization capabilities | ||
231 | of a range of operating systems. Libvirt provides a common, generic and | ||
232 | stable layer to securely manage domains on a node. As nodes may be | ||
233 | remotely located, libvirt provides all methods required to provision, | ||
234 | create, modify, monitor, control, migrate and stop the domains, within the | ||
235 | limits of hypervisor support for these operations.</para> | ||
236 | |||
237 | <para>The libvirt daemon runs on the Enea NFV Access host. All tools built | ||
238 | on libvirt API connect to the daemon to request the desired operation, and | ||
239 | to collect information about the configuration and resources of the host | ||
240 | system and guests. <literal>virsh</literal> is a command line interface | ||
241 | tool for managing guests and the hypervisor. The virsh tool is built on | ||
242 | the libvirt management API.</para> | ||
243 | |||
244 | <para><emphasis role="bold">Major functionality provided by | ||
245 | libvirt</emphasis></para> | ||
246 | |||
247 | <para>The following is a summary from the libvirt <ulink | ||
248 | url="http://wiki.libvirt.org/page/FAQ#What_is_libvirt.3F">home | ||
249 | page</ulink> describing the major libvirt features:</para> | ||
250 | |||
251 | <itemizedlist> | ||
252 | <listitem> | ||
253 | <para><emphasis role="bold">VM management:</emphasis> Various domain | ||
254 | lifecycle operations such as start, stop, pause, save, restore, and | ||
255 | migrate. Hotplug operations for many device types including disk and | ||
256 | network interfaces, memory, and cpus.</para> | ||
257 | </listitem> | ||
258 | |||
259 | <listitem> | ||
260 | <para><emphasis role="bold">Remote machine support:</emphasis> All | ||
261 | libvirt functionality is accessible on any machine running the libvirt | ||
262 | daemon, including remote machines. A variety of network transports are | ||
263 | supported for connecting remotely, with the simplest being | ||
264 | <literal>SSH</literal>, which requires no extra explicit | ||
265 | configuration. For more information, see: <ulink | ||
266 | url="http://libvirt.org/remote.html">http://libvirt.org/remote.html</ulink>.</para> | ||
267 | </listitem> | ||
268 | |||
269 | <listitem> | ||
270 | <para><emphasis role="bold">Network interface management:</emphasis> | ||
271 | Any host running the libvirt daemon can be used to manage physical and | ||
272 | logical network interfaces. Enumerate existing interfaces, as well as | ||
273 | configure (and create) interfaces, bridges, vlans, and bond devices. | ||
274 | For more details see: <ulink | ||
275 | url="https://fedorahosted.org/netcf/">https://fedorahosted.org/netcf/</ulink>.</para> | ||
276 | </listitem> | ||
277 | |||
278 | <listitem> | ||
279 | <para><emphasis role="bold">Virtual NAT and Route based | ||
280 | networking:</emphasis> Any host running the libvirt daemon can manage | ||
281 | and create virtual networks. Libvirt virtual networks use firewall | ||
282 | rules to act as a router, providing VMs transparent access to the host | ||
283 | machines network. For more information, see: <ulink | ||
284 | url="http://libvirt.org/archnetwork.html">http://libvirt.org/archnetwork.html</ulink>.</para> | ||
285 | </listitem> | ||
286 | |||
287 | <listitem> | ||
288 | <para><emphasis role="bold">Storage management:</emphasis> Any host | ||
289 | running the libvirt daemon can be used to manage various types of | ||
290 | storage: create file images of various formats (raw, qcow2, etc.), | ||
291 | mount NFS shares, enumerate existing LVM volume groups, create new LVM | ||
292 | volume groups and logical volumes, partition raw disk devices, mount | ||
293 | iSCSI shares, and much more. For more details, see: <ulink | ||
294 | url="http://libvirt.org/storage.html">http://libvirt.org/storage.html</ulink>.</para> | ||
295 | </listitem> | ||
296 | |||
297 | <listitem> | ||
298 | <para><emphasis role="bold">Libvirt Configuration:</emphasis> A | ||
299 | properly running libvirt requires that the following elements be in | ||
300 | place:</para> | ||
301 | |||
302 | <itemizedlist> | ||
303 | <listitem> | ||
304 | <para>Configuration files, located in the directory | ||
305 | <literal>/etc/libvirt</literal>. They include the daemon's | ||
306 | configuration file <literal>libvirtd.conf</literal>, and | ||
307 | hypervisor-specific configuration files, like | ||
308 | <literal>qemu.conf</literal> for the QEMU.</para> | ||
309 | </listitem> | ||
310 | |||
311 | <listitem> | ||
312 | <para>A running libvirtd daemon. The daemon is started | ||
313 | automatically in Enea NFV Access host.</para> | ||
314 | </listitem> | ||
315 | |||
316 | <listitem> | ||
317 | <para>Configuration files for the libvirt domains, or guests, to | ||
318 | be managed by the KVM host. The specifics for guest domains shall | ||
319 | be defined in an XML file of a format specified at <ulink | ||
320 | url="http://libvirt.org/formatdomain.html">http://libvirt.org/formatdomain.html</ulink>. | ||
321 | XML formats for other structures are specified at <ulink type="" | ||
322 | url="http://libvirt.org/format.html">http://libvirt.org/format.html</ulink>.</para> | ||
323 | </listitem> | ||
324 | </itemizedlist> | ||
325 | </listitem> | ||
326 | </itemizedlist> | ||
327 | </section> | ||
328 | </chapter> \ No newline at end of file | ||
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/images/virtual_network_functions.png b/doc/book-enea-nfv-access-platform-guide/doc/images/virtual_network_functions.png new file mode 100644 index 0000000..4011de8 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/images/virtual_network_functions.png | |||
Binary files differ | |||
diff --git a/doc/book-enea-nfv-access-platform-guide/doc/ovs.xml b/doc/book-enea-nfv-access-platform-guide/doc/ovs.xml new file mode 100644 index 0000000..3400975 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/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 | [FIXME] 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 [FIXME] 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-platform-guide/doc/platform_overview.xml b/doc/book-enea-nfv-access-platform-guide/doc/platform_overview.xml new file mode 100644 index 0000000..945e25b --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/platform_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="platform_overview"> | ||
5 | <title>Platform Overview</title> | ||
6 | |||
7 | <para>The NFV Access Platform Guide available with this release of Enea | ||
8 | Linux, 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>NFV Access Platform Description</title> | ||
13 | |||
14 | <para>Enea NFV Access is a lightweight virtualization software platform | ||
15 | designed for deployment on edge devices at customer premises. Streamlined | ||
16 | for high networking performance and minimal footprints for both platform | ||
17 | and VNFs, it enables very high compute density.</para> | ||
18 | |||
19 | <para>ENFV 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="platform_components"> | ||
63 | <title>NFV Access Platform 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-platform-guide/doc/using_nfv_access_platform_sdks.xml b/doc/book-enea-nfv-access-platform-guide/doc/using_nfv_access_platform_sdks.xml new file mode 100644 index 0000000..9f0f3f5 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/doc/using_nfv_access_platform_sdks.xml | |||
@@ -0,0 +1,203 @@ | |||
1 | <?xml version="1.0" encoding="UTF-8"?> | ||
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 NFV Access Platform SDKs</title> | ||
6 | |||
7 | <para>Enea NFV Access Platform comes with two different toolchains, one for | ||
8 | developing applications for the host and one for applications running in the | ||
9 | guest VM. Each is wrapped together with an environment-setup script into a | ||
10 | shell archive and is available under the Download section on | ||
11 | portal.enea.com. They have self explanatory names.</para> | ||
12 | |||
13 | <itemizedlist> | ||
14 | <listitem> | ||
15 | <para><literal>inteld1521/sdk/enea-glibc-x86_64-enea-image-virtualization-host-sdk-corei7-64-toolchain-7.0.sh</literal> | ||
16 | - for host applications.</para> | ||
17 | </listitem> | ||
18 | |||
19 | <listitem> | ||
20 | <para><literal>qemux86-64/sdk/enea-glibc-x86_64-enea-image-virtualization-guest-sdk-core2-64-toolchain-7.0.sh</literal> | ||
21 | - for guest applications.</para> | ||
22 | </listitem> | ||
23 | </itemizedlist> | ||
24 | |||
25 | <section id="install-crosscomp"> | ||
26 | <title>Installing the Cross-Compilation Toolchain</title> | ||
27 | |||
28 | <para>Before cross-compiling applications for your target, you need to | ||
29 | install the corresponding toolchain on your workstation. To do that, | ||
30 | simply run the installer and follow the steps included with it:</para> | ||
31 | |||
32 | <orderedlist> | ||
33 | <listitem> | ||
34 | <para><programlisting>$ ./enea-glibc-x86_64-enea-image-virtualization-guest-sdk-core2-64-toolchain-7.0.sh</programlisting>When | ||
35 | prompted, select to install the toolchain in the desired directory, | ||
36 | referred to as <literal><sdkdir></literal>. </para> | ||
37 | |||
38 | <para>A default path where the toolchain will be installed will be | ||
39 | shown in the prompt. The installer unpacks the environment setup | ||
40 | script in <literal><sdkdir></literal> and the toolchain under | ||
41 | <literal><sdkdir>/sysroots</literal>.</para> | ||
42 | |||
43 | <note> | ||
44 | <para>Choose a unique directory for each toolchain. Installing a | ||
45 | second toolchain of any type in the same directory as a previously | ||
46 | installed one will break the <literal>$PATH</literal> variable of | ||
47 | the first one.</para> | ||
48 | </note> | ||
49 | </listitem> | ||
50 | |||
51 | <listitem> | ||
52 | <para>Setup the toolchain environment for your target by sourcing the | ||
53 | environment-setup script. Example: <programlisting>$ source <sdkdir>/environment-setup-core2-64-enea-linux</programlisting></para> | ||
54 | </listitem> | ||
55 | </orderedlist> | ||
56 | </section> | ||
57 | |||
58 | <section id="crosscomp-apps"> | ||
59 | <title>Cross-Compiling Applications from Command Line</title> | ||
60 | |||
61 | <para>Once the environment-setup script is sourced, you can make your | ||
62 | applications as per usual and get them compiled for your target. Below you | ||
63 | see how to cross-compile from command line.</para> | ||
64 | |||
65 | <orderedlist> | ||
66 | <listitem> | ||
67 | <para>Create a Makefile for your application. Example: a simple | ||
68 | Makefile and application:</para> | ||
69 | |||
70 | <programlisting>helloworld:helloworld.o | ||
71 | $(CC) -o helloworld helloworld.o | ||
72 | clean: | ||
73 | rm -f *.o helloworld | ||
74 | #include <stdio.h> | ||
75 | int main(void) { | ||
76 | printf("Hello World\n"); | ||
77 | return 0; | ||
78 | }</programlisting> | ||
79 | </listitem> | ||
80 | |||
81 | <listitem> | ||
82 | <para>Run <command>make</command> to cross-compile your application | ||
83 | according to the environment set up:</para> | ||
84 | |||
85 | <programlisting>$ make</programlisting> | ||
86 | </listitem> | ||
87 | |||
88 | <listitem> | ||
89 | <para>Deploy the helloworld program to your target and run it:</para> | ||
90 | |||
91 | <programlisting># ./helloworld | ||
92 | hello world</programlisting> | ||
93 | </listitem> | ||
94 | </orderedlist> | ||
95 | </section> | ||
96 | |||
97 | <section id="crosscomp-kern-mod"> | ||
98 | <title>Cross-Compiling Kernel Modules</title> | ||
99 | |||
100 | <para>Before cross-compiling kernle modules, you need to make sure the | ||
101 | installed toolchain includes the kernel source tree, which should be | ||
102 | available at: | ||
103 | <literal><sdkdir>/sysroots/<targetarch>-enea-linux/usr/src/kernel</literal>.</para> | ||
104 | |||
105 | <para>Once the environment-setup script is sourced, you can make your | ||
106 | kernel modules as usual and get them compiled for your target. Below you | ||
107 | see how to cross-compile a kernel module.</para> | ||
108 | |||
109 | <orderedlist> | ||
110 | <listitem> | ||
111 | <para>Create a Makefile for the kernel module. Example: a simple | ||
112 | Makefile and kernel module:</para> | ||
113 | |||
114 | <programlisting>obj-m := hello.o | ||
115 | PWD := $(shell pwd) | ||
116 | |||
117 | KERNEL_SRC := <full path to kernel source tree> | ||
118 | |||
119 | all: scripts | ||
120 | $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" modules | ||
121 | scripts: | ||
122 | $(MAKE) -C $(KERNEL_SRC) scripts | ||
123 | clean: | ||
124 | $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" clean | ||
125 | #include <linux/module.h> /* Needed by all modules */ | ||
126 | #include <linux/kernel.h> /* Needed for KERN_INFO */ | ||
127 | #include <linux/init.h> /* Needed for the macros */ | ||
128 | |||
129 | static int __init hello_start(void) | ||
130 | { | ||
131 | printk(KERN_INFO "Loading hello module...\n"); | ||
132 | printk(KERN_INFO "Hello, world\n"); | ||
133 | return 0; | ||
134 | } | ||
135 | |||
136 | static void __exit hello_end(void) | ||
137 | { | ||
138 | printk(KERN_INFO "Goodbye, world\n"); | ||
139 | } | ||
140 | |||
141 | module_init(hello_start); | ||
142 | module_exit(hello_end); | ||
143 | |||
144 | MODULE_LICENSE("GPL");</programlisting> | ||
145 | </listitem> | ||
146 | |||
147 | <listitem> | ||
148 | <para>Run <command>make</command> to cross-compile your kernel module | ||
149 | according to the environment set up:</para> | ||
150 | |||
151 | <programlisting>$ make</programlisting> | ||
152 | </listitem> | ||
153 | |||
154 | <listitem> | ||
155 | <para>Deploy the kernel module <literal>hello.ko</literal> to your | ||
156 | target and install/remove it:</para> | ||
157 | |||
158 | <programlisting># insmod hello.ko | ||
159 | # rmmod hello.ko | ||
160 | # dmesg | ||
161 | [...] Loading hello module... | ||
162 | [...] Hello, world | ||
163 | [...] Goodbye, world</programlisting> | ||
164 | </listitem> | ||
165 | </orderedlist> | ||
166 | </section> | ||
167 | |||
168 | <section id="deploy-artifacts"> | ||
169 | <title>Deploying your artifacts</title> | ||
170 | |||
171 | <orderedlist> | ||
172 | <listitem> | ||
173 | <para>Deploying on host</para> | ||
174 | |||
175 | <para>You can use <literal>ssh</literal> to deploy your artifacts on | ||
176 | the host target. For this you will need a network connection to the | ||
177 | target and to use <literal>scp</literal> to copy to the desired | ||
178 | location.</para> | ||
179 | </listitem> | ||
180 | |||
181 | <listitem> | ||
182 | <para>Deploying on guest</para> | ||
183 | |||
184 | <para>You can deploy your artifacts onto the guest VM running on the | ||
185 | target in two steps:</para> | ||
186 | |||
187 | <itemizedlist> | ||
188 | <listitem> | ||
189 | <para>Deploy the artifacts onto the target by using the method | ||
190 | described above or any other method.</para> | ||
191 | </listitem> | ||
192 | |||
193 | <listitem> | ||
194 | <para>On the target, copy the artifacts to the guest rootfs. For | ||
195 | this, you will need to shut down the guest VM, mount the file | ||
196 | system on the target, copy your files onto it, unmount it and then | ||
197 | restart the guest VM as usual.</para> | ||
198 | </listitem> | ||
199 | </itemizedlist> | ||
200 | </listitem> | ||
201 | </orderedlist> | ||
202 | </section> | ||
203 | </chapter> \ No newline at end of file | ||
diff --git a/doc/book-enea-nfv-access-platform-guide/swcomp.mk b/doc/book-enea-nfv-access-platform-guide/swcomp.mk new file mode 100644 index 0000000..4572144 --- /dev/null +++ b/doc/book-enea-nfv-access-platform-guide/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-platform-guide | ||
9 | BOOKDESC_$(BOOKPACKAGES) := "Enea NFV Access Platform $(PROD_VER) Guide" | ||
10 | BOOKDEFAULTCONDITION := $(DEFAULTCONDITIONS) | ||