ref-manual: Updates to the migrating to YP 1.7 section.

Some minor wording changes and a new section added for local.conf QEMU changes. Also, reordered some sections. (From yocto-docs rev: 65207b6afa6df7d82cd3482d61f10b308da6fac7) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
dev-manual: Updates to "Performing Automated Runtime Testing"
2026-01-29 21:08:42 +01:00 · 2014-10-28 22:31:06 +00:00 · 2014-10-28 22:31:06 +00:00 · 2014-10-28 22:31:06 +00:00 · 2014-10-28 22:31:05 +00:00
4 changed files with 261 additions and 60 deletions
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7742,8 +7742,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis>
                    <filename>TEST_TARGET</filename> to an appropriate value.
                    For QEMU, you do not have to change anything, the default
                    value is "QemuTarget".
-                    For running tests on hardware, two options exist:
-                    "SimpleRemoteTarget" and "GummibootTarget".
+                    For running tests on hardware, the following options exist:
                    <itemizedlist>
                        <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
                            Choose "SimpleRemoteTarget" if you are going to
@@ -7770,6 +7769,45 @@ Gateways via their Web Interfaces</ulink>"</emphasis>
                            "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>"
                            section, which follows, for more information.
                            </para></listitem>
+                        <listitem><para><emphasis>"BeagleBoneTarget":</emphasis>
+                            Choose "BeagleBoneTarget" if you are deploying
+                            images and running tests on the BeagleBone
+                            "Black" or original "White" hardware.
+                            For information on how to use these tests, see the
+                            comments at the top of the BeagleBoneTarget
+                            <filename>meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py</filename>
+                            file.
+                            </para></listitem>
+                        <listitem><para><emphasis>"EdgeRouterTarget":</emphasis>
+                            Choose "EdgeRouterTarget" is you are deploying
+                            images and running tests on the Ubiquiti Networks
+                            EdgeRouter Lite.
+                            For information on how to use these tests, see the
+                            comments at the top of the EdgeRouterTarget
+                            <filename>meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py</filename>
+                            file.
+                            </para></listitem>
+                        <listitem><para><emphasis>"GrubTarget":</emphasis>
+                            Choose the "supports deploying images and running
+                            tests on any generic PC that boots using GRUB.
+                            For information on how to use these tests, see the
+                            comments at the top of the GrubTarget
+                            <filename>meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py</filename>
+                            file.
+                            </para></listitem>
+                        <listitem><para><emphasis>"<replaceable>your-target</replaceable>":</emphasis>
+                            Create your own custom target if you want to run
+                            tests when you are deploying images and running
+                            tests on a custom machine within your BSP layer.
+                            To do this, you need to add a Python unit that
+                            defines the target class under
+                            <filename>lib/oeqa/controllers/</filename> within
+                            your layer.
+                            You must also provide an empty
+                            <filename>__init__.py</filename>.
+                            For examples, see files in
+                            <filename>meta-yocto-bsp/lib/oeqa/controllers/</filename>.
+                            </para></listitem>
                    </itemizedlist>
                </para>
            </section>
@@ -7880,10 +7918,14 @@ Gateways via their Web Interfaces</ulink>"</emphasis>
                            </para></listitem>
                    </orderedlist>
                </para>
+            </section>
+
+            <section id='power-control'>
+                <title>Power Control</title>

                <para>
-                    Here is some additional information regarding running
-                    "GummibootTarget" as your test target:
+                    For most hardware targets other than SimpleRemoteTarget,
+                    you can control power:
                    <itemizedlist>
                        <listitem><para>
                            You can use
@@ -7928,6 +7970,63 @@ Gateways via their Web Interfaces</ulink>"</emphasis>
                            some manual interaction is okay from time to time.
                            </para></listitem>
                    </itemizedlist>
+                    If you have no hardware to automatically perform power
+                    control but still wish to experiment with automated
+                    hardware testing, you can use the dialog-power-control
+                    script that shows a dialog prompting you to perform the
+                    required power action.
+                    This script requires either KDialog or Zenity to be
+                    installed.
+                    To use this script, set the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink>
+                    variable as follows:
+                    <literallayout class='monospaced'>
+     TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control"
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='serial-console-connection'>
+                <title>Serial Console Connection</title>
+
+                <para>
+                    For test target classes requiring a serial console
+                    to interact with the bootloader (e.g. BeagleBoneTarget,
+                    EdgeRouterTarget, and GrubTarget), you need to
+                    specify a command to use to connect to the serial console
+                    of the target machine by using the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink>
+                    variable and optionally the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_EXTRA_ARGS'><filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename></ulink>
+                    variable.
+                </para>
+
+                <para>
+                    These cases could be a serial terminal program if the
+                    machine is connected to a local serial port, or a
+                    <filename>telnet</filename> or
+                    <filename>ssh</filename> command connecting to a remote
+                    console server.
+                    Regardless of the case, the command simply needs to
+                    connect to the serial console and forward that connection
+                    to standard input and output as any normal terminal
+                    program does.
+                    For example, to use the picocom terminal program on
+                    serial device <filename>/dev/ttyUSB0</filename>
+                    at 115200bps, you would set the variable as follows:
+                    <literallayout class='monospaced'>
+     TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
+                    </literallayout>
+                    For local devices where the serial port device disappears
+                    when the device reboots, an additional "serdevtry" wrapper
+                    script is provided.
+                    To use this wrapper, simply prefix the terminal command
+                    with
+                    <filename>${COREBASE}/scripts/contrib/serdevtry</filename>:
+                    <literallayout class='monospaced'>
+     TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b
+115200 /dev/ttyUSB0"
+                    </literallayout>
                </para>
            </section>
        </section>
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -168,6 +168,8 @@
                <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>
                <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>
                <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>
+                <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem>
+                <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem>
 <!--                <listitem><para>openSUSE 11.4</para></listitem>
                <listitem><para>openSUSE 12.1</para></listitem> -->
                <listitem><para>openSUSE 12.2</para></listitem>
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1701,6 +1701,45 @@
        Yocto Project 1.7 Release from the prior release.
    </para>

+    <section id='migration-1.7-changes-to-setting-qemu-packageconfig-options'>
+        <title>Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename></title>
+
+        <para>
+            The QEMU recipe now uses a number of
+            <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
+            options to enable various optional features.
+            The method used to set defaults for these options means that
+            existing
+            <filename>local.conf</filename> files will need to be be
+            modified to append to <filename>PACKAGECONFIG</filename> for
+            <filename>qemu-native</filename> and
+            <filename>nativesdk-qemu</filename> instead of setting it.
+            In other words, to enable graphical output for QEMU, you should
+            now have these lines in <filename>local.conf</filename>:
+            <literallayout class='monospaced'>
+     PACKAGECONFIG_append_pn-qemu-native = " sdl"
+     PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='migration-1.7-minimum-git-version'>
+        <title>Minimum Git version</title>
+
+        <para>
+            The minimum
+            <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> version required
+            on the build host is now 1.7.8 because the
+            <filename>&dash;&dash;list</filename> option is now required by
+            BitBake's Git fetcher.
+            As always, if your host distribution does not provide a version of
+            Git that meets this requirement, you can use the
+            <filename>buildtools-tarball</filename> that does.
+            See the
+            "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
+            section for more information.
+        </para>
+    </section>

    <section id='migration-1.7-autotools-class-changes'>
        <title>Autotools Class Changes</title>
@@ -1859,61 +1898,6 @@
        </para>
    </section>

-    <section id='migration-1.7-removed-recipes'>
-        <title>Removed Recipes</title>
-
-        <para>
-            The following recipes have been removed:
-            <itemizedlist>
-                <listitem><para>
-                    <filename>x-load</filename>:
-                    This recipe has been superseded by
-                    U-boot SPL for all Cortex-based TI SoCs.
-                    For legacy boards, the <filename>meta-ti</filename>
-                    layer, which contains a maintained recipe, should be used
-                    instead.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>ubootchart</filename>:
-                    This recipe is obsolete.
-                    A <filename>bootchart2</filename> recipe has been added
-                    to functionally replace it.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>linux-yocto 3.4</filename>:
-                    Support for the linux-yocto 3.4 kernel has been dropped.
-                    Support for the 3.10 and 3.14 kernels remains, while
-                    support for version 3.17 has been added.
-                    </para></listitem>
-                <listitem><para>
-                    <filename>eglibc</filename> has been removed in favor of
-                    <filename>glibc</filename>.
-                    See the
-                    "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>"
-                    section for more information.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='migration-1.7-minimum-git-version'>
-        <title>Minimum Git version</title>
-
-        <para>
-            The minimum
-            <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> version required
-            on the build host is now 1.7.8 because the
-            <filename>&dash;&dash;list</filename> option is now required by
-            BitBake's Git fetcher.
-            As always, if your host distribution does not provide a version of
-            Git that meets this requirement, you can use the
-            <filename>buildtools-tarball</filename> that does.
-            See the
-            "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
-            section for more information.
-        </para>
-    </section>
-
    <section id='migration-1.7-qa-check-changes'>
        <title>QA Check Changes</title>

@@ -1951,7 +1935,55 @@
                    Recipes should not be overwriting files written to the
                    sysroot by other recipes.
                    If you have these types of recipes, you need to alter them
-                    so that they do not overwrite these files.
+                    so that they do not overwrite these files.</para>
+                    <para>You might now receive this error after changes in
+                    configuration or metadata resulting in orphaned files
+                    being left in the sysroot.
+                    If you do receive this error, the way to resolve the issue
+                    is to delete your
+                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+                    or to move it out of the way and then re-start the build.
+                    Anything that has been fully built up to that point and
+                    does not need rebuilding will be restored from the shared
+                    state cache and the rest of the build will be able to
+                    proceed as normal.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.7-removed-recipes'>
+        <title>Removed Recipes</title>
+
+        <para>
+            The following recipes have been removed:
+            <itemizedlist>
+                <listitem><para>
+                    <filename>x-load</filename>:
+                    This recipe has been superseded by
+                    U-boot SPL for all Cortex-based TI SoCs.
+                    For legacy boards, the <filename>meta-ti</filename>
+                    layer, which contains a maintained recipe, should be used
+                    instead.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>ubootchart</filename>:
+                    This recipe is obsolete.
+                    A <filename>bootchart2</filename> recipe has been added
+                    to functionally replace it.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>linux-yocto 3.4</filename>:
+                    Support for the linux-yocto 3.4 kernel has been dropped.
+                    Support for the 3.10 and 3.14 kernels remains, while
+                    support for version 3.17 has been added.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>eglibc</filename> has been removed in favor of
+                    <filename>glibc</filename>.
+                    See the
+                    "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>"
+                    section for more information.
                    </para></listitem>
            </itemizedlist>
        </para>
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9122,6 +9122,37 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
            </glossdef>
        </glossentry>

+        <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
+            <glossdef>
+                <para>
+                    For automated hardware testing, specifies the command to
+                    use to control the power of the target machine under test.
+                    Typically, this command would point to a script that
+                    performs the appropriate action (e.g. interacting
+                    with a web-enabled power strip).
+                    The specified command should expect to receive as the last
+                    argument "off", "on" or "cycle" specifying to power off,
+                    on, or cycle (power off and then power on) the device,
+                    respectively.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
+            <glossdef>
+                <para>
+                    For automated hardware testing, specifies additional
+                    arguments to pass through to the command specified in
+                    <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
+                    Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
+                    is optional.
+                    You can use it if you wish, for example, to separate the
+                    machine-specific and non-machine-specific parts of the
+                    arguments.
+                </para>
+            </glossdef>
+        </glossentry>
+
        <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
            <glossdef>
                <para>
@@ -9142,6 +9173,43 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
            </glossdef>
        </glossentry>

+        <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
+            <glossdef>
+                <para>
+                    For automated hardware testing, specifies the command
+                    to use to connect to the serial console of the target
+                    machine under test.
+                    This command simply needs to connect to the serial console
+                    and forward that connection to standard input and output
+                    as any normal terminal program does.
+                </para>
+
+                <para>
+                    For example, to use the Picocom terminal program on
+                    serial device <filename>/dev/ttyUSB0</filename> at
+                    115200bps, you would set the variable as follows:
+                    <literallayout class='monospaced'>
+     TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
+            <glossdef>
+                <para>
+                    For automated hardware testing, specifies additional
+                    arguments to pass through to the command specified in
+                    <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
+                    Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
+                    is optional.
+                    You can use it if you wish, for example, to separate the
+                    machine-specific and non-machine-specific parts of the
+                    command.
+                </para>
+            </glossdef>
+        </glossentry>
+
        <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
            <glossdef>
                <para>
Author	SHA1	Message	Date
Scott Rifenbark	9aff3a4ec0	ref-manual: Updates to the migrating to YP 1.7 section. Some minor wording changes and a new section added for local.conf QEMU changes. Also, reordered some sections. (From yocto-docs rev: 65207b6afa6df7d82cd3482d61f10b308da6fac7) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>	2014-10-28 22:31:06 +00:00
Scott Rifenbark	16ddd45421	dev-manual: Updates to "Performing Automated Runtime Testing" Updated the section to account for some new variables and several more ways to run tests against expanded targets. Also added power control section. (From yocto-docs rev: a0f08466c00ae51a99d790fa6c9dccef2e0f1518) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>	2014-10-28 22:31:06 +00:00
Scott Rifenbark	1a6c3a385c	ref-manual: Added some new test variables: * TEST_SERIALCONTROL_CMD * TEST_SERIALCONTROL_EXTRA_ARGS * TEST_POWERCONTROL_CMD * TEST_POWERCONTROL_EXTRA_ARGS (From yocto-docs rev: 25f196cc03178f07201ef183fb309721d412e971) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>	2014-10-28 22:31:06 +00:00
Scott Rifenbark	e95863cee0	ref-manual: Updated list of supported distros. Added Debian 7.5 and 7.6 to the list. (From yocto-docs rev: 35fd5d5399fe1759158aef19d7b6eb68f2a1af12) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>	2014-10-28 22:31:05 +00:00