QBSP: include readme file in the QBSP image package

Add READMEs to be included in the QBSP image package,
machine specific instructions moved from the online docs.

Task-number: QTBUG-72815
Change-Id: I3af024aabb393eb32d866cd925e20d4f341f0d7d
Reviewed-by: Mikko Gronoff <mikko.gronoff@qt.io>
Reviewed-by: Tarja Sundqvist <tarja.sundqvist@qt.io>

11 files changed, 328 insertions, 0 deletions

diff --git a/meta-boot2qt/classes/qbsp.bbclass b/meta-boot2qt/classes/qbsp.bbclass
index 9f6a9216..b327bef6 100644
--- a/meta-boot2qt/classes/qbsp.bbclass
+++ b/meta-boot2qt/classes/qbsp.bbclass
@@ -31,6 +31,8 @@ inherit meta nopackages abi-arch siteinfo
 
 FILESEXTRAPATHS_prepend := "${BOOT2QTBASE}/files/qbsp:"
 
+QBSP_README ?= "README"
+
 SRC_URI = "\
     file://base_package.xml \
     file://base_installscript.qs \
@@ -47,6 +49,7 @@ do_qbsp[depends] += "\
     installer-framework-native:do_populate_sysroot \
     ${QBSP_SDK_TASK}:do_populate_sdk \
     ${QBSP_IMAGE_TASK}:do_image_complete \
+    qbsp-readme:do_deploy \
     "
 
 QBSP_VERSION ?= "${PV}${VERSION_AUTO_INCREMENT}"
@@ -129,6 +132,10 @@ prepare_qbsp() {
     mkdir -p ${B}/images/${QBSP_INSTALL_PATH}/images
     7zr x ${DEPLOY_DIR_IMAGE}/${IMAGE_PACKAGE} -o${B}/images/${QBSP_INSTALL_PATH}/images/
 
+    if [ -n "${QBSP_README}" ]; then
+        cp ${DEPLOY_DIR_IMAGE}/${QBSP_README} ${B}/images/${QBSP_INSTALL_PATH}/images/
+    fi
+
     cd ${B}/images
     7zr a ${COMPONENT_PATH}/data/image.7z *
 
diff --git a/meta-boot2qt/recipes-qt/boot2qt-addons/qbsp-readme.bb b/meta-boot2qt/recipes-qt/boot2qt-addons/qbsp-readme.bb
new file mode 100644
index 00000000..197c5ff6
--- /dev/null
+++ b/meta-boot2qt/recipes-qt/boot2qt-addons/qbsp-readme.bb
@@ -0,0 +1,44 @@
+############################################################################
+##
+## Copyright (C) 2019 The Qt Company Ltd.
+## Contact: https://www.qt.io/licensing/
+##
+## This file is part of the Boot to Qt meta layer.
+##
+## $QT_BEGIN_LICENSE:GPL$
+## Commercial License Usage
+## Licensees holding valid commercial Qt licenses may use this file in
+## accordance with the commercial license agreement provided with the
+## Software or, alternatively, in accordance with the terms contained in
+## a written agreement between you and The Qt Company. For licensing terms
+## and conditions see https://www.qt.io/terms-conditions. For further
+## information use the contact form at https://www.qt.io/contact-us.
+##
+## GNU General Public License Usage
+## Alternatively, this file may be used under the terms of the GNU
+## General Public License version 3 or (at your option) any later version
+## approved by the KDE Free Qt Foundation. The licenses are as published by
+## the Free Software Foundation and appearing in the file LICENSE.GPL3
+## included in the packaging of this file. Please review the following
+## information to ensure the GNU General Public License requirements will
+## be met: https://www.gnu.org/licenses/gpl-3.0.html.
+##
+## $QT_END_LICENSE$
+##
+############################################################################
+
+SUMMARY = "Device specific installation instructions for the QBSP"
+LICENSE = "The-Qt-Company-Commercial"
+LIC_FILES_CHKSUM = "file://${BOOT2QTBASE}/licenses/The-Qt-Company-Commercial;md5=948f8877345cd66106f11031977a4625"
+
+inherit deploy nopackages
+
+SRC_URI = "file://README"
+QBSP_README ?= "README"
+
+do_deploy() {
+    install -d ${DEPLOYDIR}
+    install -m 0644 ${WORKDIR}/${QBSP_README} ${DEPLOYDIR}
+}
+
+addtask do_deploy after do_compile before do_build
diff --git a/meta-boot2qt/recipes-qt/boot2qt-addons/qbsp-readme/README b/meta-boot2qt/recipes-qt/boot2qt-addons/qbsp-readme/README
new file mode 100644
index 00000000..fb7d63c1
--- /dev/null
+++ b/meta-boot2qt/recipes-qt/boot2qt-addons/qbsp-readme/README
@@ -0,0 +1,2 @@
+To successfully set up the Boot to Qt software stack,
+follow the instructions in https://doc.qt.io/QtForDeviceCreation/qtdc-qbsp-installation-guide.html#.
diff --git a/meta-fsl-extras/recipes/qbsp-readme/imx7s-warp/README b/meta-fsl-extras/recipes/qbsp-readme/imx7s-warp/README
new file mode 100644
index 00000000..ee4f7bab
--- /dev/null
+++ b/meta-fsl-extras/recipes/qbsp-readme/imx7s-warp/README
@@ -0,0 +1,21 @@
+To successfully set up the Boot to Qt software stack,
+follow the instructions in https://doc.qt.io/QtForDeviceCreation/qtdc-qbsp-installation-guide.html#.
+
+In 2. Installing Boot to Qt on Target Device, see also the WaRP7 specific instructions:
+
+
+2. Installing Boot to Qt on Target Device
+
+Follow the steps in this documentation to flash your WaRP7 with an image containing
+the Boot to Qt stack:
+
+1.Use the USB cable to access the serial terminal on WaRP7.
+2. Power on your WaRP7 device and press any key to stop the autoboot.
+3. Run the following command in U-Boot:
+
+ ums 0 mmc 0
+
+4. Use Flashing Wizard to flash the image to the device:
+   4.1 Launch Qt Creator.
+   4.2 Select Tools > Flash Boot to Qt Device, and follow the instructions in Flashing Wizard.
+5. Press Ctrl+C in the U-Boot console and run the reset command.
diff --git a/meta-fsl-extras/recipes/qbsp-readme/nitrogen6x/README b/meta-fsl-extras/recipes/qbsp-readme/nitrogen6x/README
new file mode 100644
index 00000000..70639d52
--- /dev/null
+++ b/meta-fsl-extras/recipes/qbsp-readme/nitrogen6x/README
@@ -0,0 +1,69 @@
+To successfully set up the Boot to Qt software stack,
+follow the instructions in https://doc.qt.io/QtForDeviceCreation/qtdc-qbsp-installation-guide.html#.
+
+In Boundary Devices i.MX6 Board target devices, see also the U-Boot and
+Nitrogen6_Lite device specific instructions:
+
+
+2. Installing QBSP on Host Platform
+
+After you have flashed the device with Flashing Wizard, you may need to update U-Boot:
+
+* If you are updating your Boundary Devices i.MX6 Board from an older image,
+update the U-Boot version on the device. See 2.1 Updating U-Boot.
+* If your target device is Nitrogen6_Lite Device, see 1.2 Setup for Nitrogen6_Lite Device.
+
+Note: Sometimes U-Boot fails to select a suitable display for your target device
+and sets an incorrect display resolution.
+https://doc.qt.io/QtForDeviceCreation/qtee-customization.html#configuring-display-resolution
+instructs how you can configure the display and resolution used in your target device.
+
+
+2.1 Updating U-Boot
+
+If you are updating from an older image, you may also need to update the version
+of U-Boot on the device.
+
+The prebuilt image already contains U-Boot versions for most of the device variants
+from Boundary Devices, but the update needs to be done manually when first starting
+the device. Correct device type is selected by setting the uboot_defconfig
+U-Boot environment variable.
+
+More information available from https://boundarydevices.com/compiling-latest-u-boot-for-i-mx6-2015-edition/.
+
+Access the device's console and run the following commands on the U-Boot prompt:
+
+setenv uboot_defconfig <device type>
+setenv devnum 1 # or 0, if using SD slot
+setenv devtype mmc
+run upgradeu
+
+Reset or power cycle the device to start the new U-Boot. To reset the U-Boot
+environment to new default values, enter the following commands in the U-Boot
+command line:
+
+env default -a
+saveenv
+
+
+2.2 Setup for Nitrogen6_Lite Device
+
+The boot script requires the environment variables, dtbname and gpumem, to identify
+the device as Nitrogen6_Lite. Otherwise, the device is booted with the default
+GPU memory setting of 512MiB, which is more than what is available on the
+Nitrogen_Lite devices (128MibB).
+
+Use one of the two following options to enable the scripts boot the device with
+correct GPU memory setting:
+
+* Write a uEnv.txt file on to the boot partition of SD card with the following content:
+
+gpumem=67108864
+dtbname=imx6dl-nit6xlite.dtb
+
+* Access the device's console and run the following commands on the U-Boot prompt:
+
+U-Boot > setenv gpumem 67108864
+U-Boot > setenv dtbname imx6dl-nit6xlite.dtb
+U-Boot > saveenv
+
diff --git a/meta-fsl-extras/recipes/qbsp-readme/qbsp-readme.bbappend b/meta-fsl-extras/recipes/qbsp-readme/qbsp-readme.bbappend
new file mode 100644
index 00000000..64d9670e
--- /dev/null
+++ b/meta-fsl-extras/recipes/qbsp-readme/qbsp-readme.bbappend
@@ -0,0 +1,30 @@
+############################################################################
+##
+## Copyright (C) 2019 The Qt Company Ltd.
+## Contact: https://www.qt.io/licensing/
+##
+## This file is part of the Boot to Qt meta layer.
+##
+## $QT_BEGIN_LICENSE:GPL$
+## Commercial License Usage
+## Licensees holding valid commercial Qt licenses may use this file in
+## accordance with the commercial license agreement provided with the
+## Software or, alternatively, in accordance with the terms contained in
+## a written agreement between you and The Qt Company. For licensing terms
+## and conditions see https://www.qt.io/terms-conditions. For further
+## information use the contact form at https://www.qt.io/contact-us.
+##
+## GNU General Public License Usage
+## Alternatively, this file may be used under the terms of the GNU
+## General Public License version 3 or (at your option) any later version
+## approved by the KDE Free Qt Foundation. The licenses are as published by
+## the Free Software Foundation and appearing in the file LICENSE.GPL3
+## included in the packaging of this file. Please review the following
+## information to ensure the GNU General Public License requirements will
+## be met: https://www.gnu.org/licenses/gpl-3.0.html.
+##
+## $QT_END_LICENSE$
+##
+############################################################################
+
+FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
diff --git a/meta-raspberrypi-extras/recipes/qbsp-readme/qbsp-readme.bbappend b/meta-raspberrypi-extras/recipes/qbsp-readme/qbsp-readme.bbappend
new file mode 100644
index 00000000..64d9670e
--- /dev/null
+++ b/meta-raspberrypi-extras/recipes/qbsp-readme/qbsp-readme.bbappend
@@ -0,0 +1,30 @@
+############################################################################
+##
+## Copyright (C) 2019 The Qt Company Ltd.
+## Contact: https://www.qt.io/licensing/
+##
+## This file is part of the Boot to Qt meta layer.
+##
+## $QT_BEGIN_LICENSE:GPL$
+## Commercial License Usage
+## Licensees holding valid commercial Qt licenses may use this file in
+## accordance with the commercial license agreement provided with the
+## Software or, alternatively, in accordance with the terms contained in
+## a written agreement between you and The Qt Company. For licensing terms
+## and conditions see https://www.qt.io/terms-conditions. For further
+## information use the contact form at https://www.qt.io/contact-us.
+##
+## GNU General Public License Usage
+## Alternatively, this file may be used under the terms of the GNU
+## General Public License version 3 or (at your option) any later version
+## approved by the KDE Free Qt Foundation. The licenses are as published by
+## the Free Software Foundation and appearing in the file LICENSE.GPL3
+## included in the packaging of this file. Please review the following
+## information to ensure the GNU General Public License requirements will
+## be met: https://www.gnu.org/licenses/gpl-3.0.html.
+##
+## $QT_END_LICENSE$
+##
+############################################################################
+
+FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
diff --git a/meta-raspberrypi-extras/recipes/qbsp-readme/qbsp-readme/README b/meta-raspberrypi-extras/recipes/qbsp-readme/qbsp-readme/README
new file mode 100644
index 00000000..2095db24
--- /dev/null
+++ b/meta-raspberrypi-extras/recipes/qbsp-readme/qbsp-readme/README
@@ -0,0 +1,4 @@
+To successfully set up the Boot to Qt software stack,
+follow the instructions in https://doc.qt.io/QtForDeviceCreation/qtdc-qbsp-installation-guide.html#.
+
+In 3. Configuring a Device Kit in Qt Creator, you should note that Raspberry Pi does not support USB OTG.
diff --git a/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme.bbappend b/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme.bbappend
new file mode 100644
index 00000000..64d9670e
--- /dev/null
+++ b/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme.bbappend
@@ -0,0 +1,30 @@
+############################################################################
+##
+## Copyright (C) 2019 The Qt Company Ltd.
+## Contact: https://www.qt.io/licensing/
+##
+## This file is part of the Boot to Qt meta layer.
+##
+## $QT_BEGIN_LICENSE:GPL$
+## Commercial License Usage
+## Licensees holding valid commercial Qt licenses may use this file in
+## accordance with the commercial license agreement provided with the
+## Software or, alternatively, in accordance with the terms contained in
+## a written agreement between you and The Qt Company. For licensing terms
+## and conditions see https://www.qt.io/terms-conditions. For further
+## information use the contact form at https://www.qt.io/contact-us.
+##
+## GNU General Public License Usage
+## Alternatively, this file may be used under the terms of the GNU
+## General Public License version 3 or (at your option) any later version
+## approved by the KDE Free Qt Foundation. The licenses are as published by
+## the Free Software Foundation and appearing in the file LICENSE.GPL3
+## included in the packaging of this file. Please review the following
+## information to ensure the GNU General Public License requirements will
+## be met: https://www.gnu.org/licenses/gpl-3.0.html.
+##
+## $QT_END_LICENSE$
+##
+############################################################################
+
+FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
diff --git a/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme/README b/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme/README
new file mode 100644
index 00000000..f91fd080
--- /dev/null
+++ b/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme/README
@@ -0,0 +1,66 @@
+To successfully set up the Boot to Qt software stack,
+follow the instructions in https://doc.qt.io/QtForDeviceCreation/qtdc-qbsp-installation-guide.html#.
+
+In 2. Installing Boot to Qt on Target Device, see also the following device specific instructions:
+
+
+2. Installing Boot to Qt on Target Device
+
+To flash the image, you can use either Toradex Easy Installer
+(https://developer.toradex.com/software/toradex-easy-installer#) or Qt's Flashing Wizard.
+With Toradex Easy Installer, the image is flashed to the device's internal eMMC
+flash memory.
+
+
+2.1 Flashing with Toradex Easy Installer:
+
+When Toradex Easy Installer is connected to the Internet, it automatically provides
+the latest Boot to Qt image in its image list but that is not necessarily compatible
+with your Boot to Qt installation. When you flash with Toradex Easy Installer,
+you should always use the *.tezi.tar package that is included into the Boot to Qt
+installation.
+
+Flash the Boot to Qt image with Toradex Easy Installer as follows:
+
+1. If your target device does not have the pre-installed Toradex Easy Installer,
+follow instructions in https://developer.toradex.com/software/toradex-easy-installer#load-toradex-easy-installer#
+to load Toradex Easy Installer.
+2. Your Boot to Qt installation has the *.tezi.tar package under
+<Qt installation directory>/<Qt version>/Boot2Qt/<target>/images. Extract the package
+to an SD card or a USB flash drive.
+3. Flash the image from the SD card or the USB flash drive with Toradex Easy Installer.
+See https://developer.toradex.com/software/toradex-easy-installer#installing-the-images.
+
+
+2.2 Flashing with Qt's Flashing Wizard
+
+Use Flashing Wizard to flash the image to your device:
+
+1. Connect your SD card reader to the development host. Make sure that the SD card size is at least 4 GB.
+2. Launch Qt Creator.
+3. Select Tools > Flash Boot to Qt Device, and follow the instructions in Flashing Wizard.
+
+In order to boot from the external SD card, U-Boot needs to be updated.
+
+
+2.3 Booting from External SD Card
+
+Connect a serial cable to the device and enter into the U-Boot environment by
+pressing any key before the autoboot.
+
+Enter following commands into U-Boot:
+
+run setupdate
+run update
+
+Reset or power cycle the device to start the new U-Boot.
+To reset the U-Boot environment to new default values, enter the following commands in the U-Boot command line:
+
+env default -a
+saveenv
+
+New U-Boot commands are now stored into the device.
+
+For more information about the boot process on the Toradex Colibri devices,
+see https://developer.toradex.com/knowledge-base/linux-booting.
+
diff --git a/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme/mx8/README b/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme/mx8/README
new file mode 100644
index 00000000..d51a4847
--- /dev/null
+++ b/meta-toradex-extras/recipes/qbsp-readme/qbsp-readme/mx8/README
@@ -0,0 +1,25 @@
+To successfully set up the Boot to Qt software stack,
+follow the instructions in https://doc.qt.io/QtForDeviceCreation/qtdc-qbsp-installation-guide.html#.
+
+In 2. Installing Boot to Qt on Target Device, see also the following device specific instructions.
+
+
+2. Installing Boot to Qt on Target Device
+
+Use Flashing Wizard to flash the image to your Toradex board:
+
+1. Use the RS-232 cable to access the serial terminal on Toradex board.
+2. Power on your device and press any key to stop the autoboot.
+3. Run the following command in U-Boot:
+
+ums 0 mmc 0
+
+4. Use Flashing Wizard to flash the image to the device:
+   4.1 Launch Qt Creator.
+   4.2 Select Tools > Flash Boot to Qt Device, and follow the instructions in Flashing Wizard.
+5. Press Ctrl+C in the U-Boot console and run the reset command.
+
+For more information about flashing the Toradex devices,
+see https://developer.toradex.com/software/linux/linux-software/build-apalis-imx8-yoctoopenembedded-bring-up-image#emmc-boot#.
+
+Note: The Boot to Qt software stack supports only the v1.0B silicon.