1 files changed, 320 insertions, 0 deletions

diff --git a/doc/eltf_params_updated_template_how_to_use.txt b/doc/eltf_params_updated_template_how_to_use.txt
new file mode 100644
index 0000000..97b07aa
--- /dev/null
+++ b/doc/eltf_params_updated_template_how_to_use.txt
@@ -0,0 +1,320 @@
+eltf_params_template_updated_howto_use.txt
+
+This is a way to collect all parameters for an Enea Edge release
+in one parameter file, easy to automatically update by ELTF regularly.
+
+NOTE: Both the release info AND the open source books use parameters from
+      here, but the XML file is inside the release info book directory.
+
+NOTE: The manifest_conf.mk, or overridden by the environment variable
+      MANIFESTHASH, contains the full tag (or hashvalue) for downloading
+      the manifest when the books are built. The list of target
+      directories are fetched from the manifest into the book.
+      The eltf_params_updates.xml can all the time contain
+      the final next complete tag e.g. refs/tags/EL6 or similar
+      in the ELTF_PL_CLONE_W_REPO parameter command lines.
+
+The ordinary book XML files use xi:include statements to include elements
+from this parameter file. The book XML files can thus be manually edited.
+Before editing, you must run "make init".
+Any other text in the template or updated.xml file, outside the parts that
+are included in the book, are not used but still all must be correct
+DocBook XML files.
+
+ELTF work:
+ template => ELTF replaces ALL ELTF_xxx variables => updated XML file
+    => push to git only if changed
+
+
+eltf_params_template.xml  (in git)
+   File used by ELTF to autocreate/update the real parameter
+   file eltf_params_updated.xml.
+
+eltf_params_updated.xml  (in git)
+   Real parameter file where ELTF has replaced all ELTF_xx variables with
+   strings, in several cases with multiline strings.
+   No spaces or linefeed allowed in beginning or end of the variable values!
+
+
+xi:include: Each parameter is xi:include'ed in various book files, using
+   the IDs existing in the parameter files.
+   In most cases the 1:st element inside an element with an ID is included
+   using a format like eltf-prereq-apt-get-commands-host/1.
+   In very few cases the element with the ID is included in the book, one
+   example is the target section which has an ID, but which contains
+   multiple subsections, one per target.
+   All IDs in a book must be unique.
+
+DocBook XML: All XML files must be correct DocBook XML files.
+
+Do NOT edit/save the real *updated.xml file with XMLmind to avoid changes
+   not done by ELTF. But it is OK to open the real file in XMLmind to
+   check that the format is correct.
+
+ELTF should autocreate a temporary "real" file but only replace
+   and push the eltf_params_updated.xml if it is changed.
+
+
+make eltf
+   This lists all ELTF_xxx variables and some rules how to treat them
+
+DocBook Format: All elements - rules:
+   Several strict generic XML rules apply for all strings:
+    1. No TABs allowed or any other control chr than "linefeed"
+    2. Only 7-bit ASCII
+    3. Any < > & must be converted to &lt; &gt; and &amp;
+       Similar for any other non-7-bit-ASCII but avoid those!
+    4. No leading spaces or linefeeds when replacing the ELTF_* variable
+    5. No trailing spaces or linefeeds when replacing the ELTF_* variable
+    6. Note: Keep existing spaces before/efter ELTF_* in a few cases.
+
+DocBook Format: <programlisting> - rules: ELTF*PL* variables
+   Several strict rules apply for the multiline string in programlisting
+   in addition to the general XML rules above:
+    7. Max line length < 80 char
+    8. Use backslash (\) to break longer lines
+    9. Use spaces (e.g. 4) to indent continuation lines in programlistings
+   10. No trailing spaces on any line
+   11. No spaces or linefeed immediately after leading <programlisting>
+   12. No spaces or linefeed before trailing </programlisting>
+
+DocBook Format: <ulink> - rules: ELTF_*URL* variables
+   13. ELTF_*URL and corresponding ELTF_*TXTURL shall be identical strings
+   14. Only if the URL is extremely long, the TXTURL can be a separate string
+
+Each target has one section with target parameters:
+       <section id="eltf-target-table-ELTF_T_MANIFEST_DIR">
+        <title>MACHINE ELTF_T_MANIFEST_DIR - Information</title>
+          ..... with many ELTF_ variables ....
+       </section>
+
+   15. If there is only one target. ELTF just replaces ELTF parameters
+
+   16. It there are multiple targets. ELTF copies the section and appends the
+       section the required number of times.
+       Each section ID will become unique: eltf-target-table-ELTF_T_MANIFEST_DIR
+       Each section title will become unique
+
+Tables with target parameters in each target section:
+   17. It is possible for ELTF to append more rows with one parameter each
+       to these tables, because the entire tables are included in the book
+
+Special - NOT YET READY DEFINED how to handle the optionally included
+   Eclipse and its version, but this is a first suggestion:
+   18. Just now ELTF can define ELFT_ECLIPSE_VERSION as a full string
+       with both version number and name,
+   19. MANUALLY if Eclipse is NOT included in the release,
+       the release manager should manually set condition="hidden" on
+       the entire section in the book XML about Eclipse
+
+
+
+BELOW WE TRY TO EXPLAIN EACH ELTF_* variable, but always check with make eltf
+if there are more new variables, missing in this description file.
+
+_____________________________________________________________________________
+ELTF_PL_HOST_PREREQ       Multiline list of host prerequisites, e.g. commands
+                          like sudo apt-get install xxxx or similar.
+                          First line = comment with the complete host name!
+                          It is possible to include multiple hosts by just
+                          adding an empty line, comment with host name, etc.
+                          xi:include eltf-prereq-apt-get-commands-host/1
+                          This is a <programlisting>...</programlisting>
+                          Example:
+# Host Ubuntu 14.04.5 LTS 64bit
+sudo apt-get update
+sudo apt-get install sed wget subversion git-core coreutils unzip texi2html \
+   texinfo libsdl1.2-dev docbook-utils fop gawk python-pysqlite2 diffstat \
+   make gcc build-essential xsltproc g++ desktop-file-utils chrpath  \
+   libgl1-mesa-dev libglu1-mesa-dev autoconf automake groff libtool xterm \
+   libxml-parser-perl
+
+_____________________________________________________________________________
+ELTF_PL_GET_REPO          Multiline commands to download the repo tool
+                          xi:include eltf-getting-repo-install-command/1
+                          This is a <programlisting>...</programlisting>
+                          Example:
+mkdir -p ~/bin
+curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
+chmod a+x ~/bin/repo
+export PATH=~/bin:$PATH
+
+_____________________________________________________________________________
+ELTF_EL_REL_VER           General parameter string: The version of this Enea
+                          NFV Access release. Major version and optional .Minor
+                          Typically created from MAJOR and MINOR in enea.conf
+                          MINOR in enea.conf is empty or contains a dot+minor
+                          xi_include EneaEdge_REL_VER/1
+                          This is a <phrase>X.x</phrase> used in many places.
+                          Examples:
+6
+  or
+6.1
+
+_____________________________________________________________________________
+ELTF_YOCTO_VER            General parameter string: Yocto version, created
+                          from DISTRO in poky.ent
+                          xi:include Yocto_VER/1
+                          This is a <phrase>X.x</phrase> used in many places.
+                          Example:
+2.1
+
+_____________________________________________________________________________
+ELTF_YOCTO_NAME           General parameter string: Yocto name (branch), created
+                          from DISTRO_NAME_NO_CAP in poky.ent
+                          xi:include Yocto_NAME/1
+                          This is a <phrase>X.x</phrase> used in many places.
+                          Example:
+krogoth
+
+_____________________________________________________________________________
+ELTF_YOCTO_PROJ_DOWNLOAD_TXTURL  General parameters. These two are IDENTICAL
+ELTF_YOCTO_PROJ_DOWNLOAD_URL     strings with correct Yocto version string
+                                 at the end, typically without "dot".
+                          xi:include ULINK_YOCTO_PROJECT_DOWNLOAD/1
+                          This is an <ulink url="...">...</ulink>
+                          Example:
+http://www.yoctoproject.org/downloads/core/krogoth/21
+
+_____________________________________________________________________________
+ELTF_EL_DOWNLOAD_TXTURL   General parameters. These two are IDENTICAL strings
+ELTF_EL_DOWNLOAD_URL      and shall be the http:/..... address where
+                          Enea NFV Access can be downloaded
+                          Often containing same version as in ELTF_EL_REL_VER
+                          xi:include ULINK_ENEA_LINUX_URL/1
+                          This is an <ulink url="...">...</ulink>
+                          Example:
+http://linux.enea.com/6
+
+_____________________________________________________________________________
+ELTF_PL_CLONE_W_REPO      Multiline commands to run repo to clone everything.
+                          Use the variable $MACHINE/default.xml (the text in
+                          the book will list the avaiable values of MACHINE,
+                          taken from the manifest repository)
+                          xi:include eltf-repo-cloning-enea-linux/1
+                          This is a <programlisting>...</programlisting>
+                          Example:
+mkdir enea-linux
+cd enea-linux
+repo init -u git@git.enea.com:linux/manifests/el_manifests-virtualization.git \
+    -b refs/tags/EL6 -m $MACHINE/default.xml
+repo sync
+
+_____________________________________________________________________________
+ELTF_ECLIPSE_VERSION      Optional general parameter string.
+                          NOT YET READY DEFINED
+                          Just now a release manage must manually set
+                          condition="hidden" on the Eclipse section,
+                          if Eclipse is not included in the release.
+                          ELTF just replaces ELTF_ECLIPSE_VERSION with a full
+                          string with "X.Y (name)"
+                          It includes the ID and can only be ONCE in the book.
+                          xi:include eltf-eclipse-version-row
+                          Example.
+4.5 (Mars)
+
+
+_____________________________________________________________________________
+ELTF_T_*                  All these are in each target (MACHINE) and ELTF
+                          must separately replace them with strings for
+                          each target
+                          NOTE: All (except the MANIFEST_DIR) are in rows
+                                in a table and ELTF can select to append
+                                more parameters by adding more rows
+
+_____________________________________________________________________________
+ELTF_T_MANIFEST_DIR       This happens to be in two places. Must be exactly
+ELTF_T_MANIFEST_DIR       the directory name in the manifest, e.g. same
+                          as the MACHINE names in $MACHINE/default.xml.
+                          In book: a) Part of section ID
+                                   b) Part of section title
+                          Examples:
+p2041rgb
+  or
+ls1021aiot
+  or
+qemuarm
+
+_____________________________________________________________________________
+ELTF_T_NAME               Target specific: "Target Official Name"
+                          NOT same as the target directory name in most cases.
+                          In book: An <entry> element in a row
+                          Examples:
+P2041RGB
+  or
+LS1021a-IoT
+  or
+qemuarm
+
+_____________________________________________________________________________
+ELTF_T_ARC_DESC           Target specific: "Architecture and Description"
+                          It can be a short identification string or
+                          it can be a longer descriptive sentence.
+                          In book: An <entry> element in a row
+                          Examples:
+Power, e500mc
+  or
+ARM Cortex-A7
+
+_____________________________________________________________________________
+ELTF_T_DS_TXTURL          Target specific: "Link to target datasheet. These
+ELTF_T_DS_URL             two usually are IDENTICAL strings with correct
+                          hyperlink to the target's official datasheet.
+                          In book: an <ulink url="...">...</ulink>
+                          Only if the link is VERY LONG, the text part shall
+                          instead be a descriptive string (see 2:nd example).
+                          NOTE: Also here no spaces or line-feeds!
+                          Examples:
+url="http://wiki.qemu.org">http://wiki.qemu.org
+or
+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
+
+_____________________________________________________________________________
+ELTF_T_POKY_VER           Target specific: "Poky version" created either
+                          from POKYVERSION in poky.ent
+                          or using a hashvalue with a leading string, in
+                          which case it may be different per target.
+                          In book: An <entry> in a row
+                          Examples:
+15.0.0
+or
+Git commit id: 75ca53211488a3e268037a44ee2a7ac5c7181bd2
+
+_____________________________________________________________________________
+ELTF_T_GCC_VER            Target specific: "GCC Version". Should be in poky
+                          but not easy to find among various parameters.
+                          ELTF would extract it from build logs building SDK
+                          and it is possibly different per target.
+                          In book: An <entry> in a row
+                          Example:
+5.3
+
+_____________________________________________________________________________
+ELTF_T_KERN_VER           Target specific: "Linux Kernel Version". Often
+                          different per target.
+                          In book: An <entry> in a row
+                          Example:
+3.12
+
+_____________________________________________________________________________
+ELTF_T_DRIVERS            Target specific: "Supported Drivers". This is a
+                          comma-separated list of driver names.
+                          ELTF should create the list in same order for each
+                          target, e.g. alphabetic migth be OK.
+                          In book: An <entry> in a row
+                          Example:
+Ethernet, I2C, SPI, PCI, USB, SD/SDHC/SDXC
+
+
+_____________________________________________________________________________
+ELTF_T_EL_RPM_TXTURL      Target specific: "Enea rpm folder for downloading
+ELTF_T_EL_RPM_URL         RPM packages for this target". These two are
+                          INDENTICAL strings with hyperlink to the web site
+                          at Enea where the customer can download RPMs
+                          Note: Often the ELFT_EL_REL_VER value and
+                                the ELTF_T_MANIFEST_DIR are used in the link.
+                          In book: an <ulink url="...">...</ulink>
+                          Example:
+url="https://linux.enea.com/6/ls1021aiot/rpm">https://linux.enea.com/6/ls1021aiot/rpm
+
+_____________________________________________________________________________