===== Preface =====
<WRAP info round>
The instructions on this page have been tested on <label host_os_name>HOST_OS_NAME</label> <label host_os_version>HOST_OS_VERSION</label> (<label host_os_bits>HOST_OS_BITS</label>) in a VMWare virtual machine.
</WRAP>

The //meta-tq-powerarch// layer extends the //Yocto Project's// reference system //Poky// to provide support for a selection of TQ Embedded CPU Modules, including the <label mod_name>MOD_NAME</label>.

The instructions on this page refer to the BSP and ancillary tools listed in the following table:

^ BSP Revision  ^  <label bsp_rev>BSP_REV</label>  ^
^ Yocto Project / Poky Release  |  ++<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label> - <label yocto_rel_name>YOCTO_REL_NAME</label>|\\ ''git clone -b <label yocto_rel_branch>YOCTO_REL_BRANCH</label> git:%%//%%git.yoctoproject.org%%/%%poky.git''\\ [[http://<label yocto_rel_base_url>YOCTO_REL_BASE_URL</label>/yocto-<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>/<label yocto_rel_tarball>YOCTO_REL_TARBALL</label>|<label yocto_rel_tarball>YOCTO_REL_TARBALL</label>]]++  |
^ Target machine((i.e. value for [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/ref-manual/ref-manual.html#var-MACHINE|MACHINE]] variable))  |  <label mtq_machines>MTQ_MACHINES</label>  |
^ U-Boot  |  <label uboot_version>UBOOT_VERSION</label>  |
^ Linux Kernel  |  <label linux_kernel>LINUX_KERNEL</label>  |

\\
<WRAP important round>It's strongly recommended to use **git** for downloading the //Yocto Project / Poky// Release (instead of downloading an archive and extracting it).</WRAP>

<WRAP info round>
The goal of these wiki pages is to get you started using //meta-tq-powerarch// with the <label stk_name>STK_NAME</label>, so instead of reinventing the wheel we will adhere to the very compact [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html|Yocto Project Quick Start]] and supply details specific to the <label stk_name>STK_NAME</label> where necessary.\\
\\
For further details regarding //Yocto Project// <label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label> - <label yocto_rel_name>YOCTO_REL_NAME</label> please refer to its [[https://www.yoctoproject.org/documentation/archived|official documentation]].
</WRAP>


===== Prerequisites  =====

//Yocto Project / Poky// requires a Linux build host, so first of all you need a development workstation (or a virtual machine((for testing purposes //Yocto Project// provides a ready to use virtual machine called [[https://www.yoctoproject.org/tools-resources/projects/build-appliance|Build Appliance]]))) with a (preferably) recent Linux distribution installed.

Please refer to section [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html#the-linux-distro|The Linux Distribution]] of the //Yocto Project Quick Start// for supported linux distributions and section [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html#packages|The Build Host Packages]] for required build host packages for those distributions.

Although not required by //Yocto Project / Poky//, we also recommend to configure and run a [[en:tftp|tftp server]] (for image download / update) and an [[en:nfs|nfs server]] (for network mounted root filesystem) on your development host.

===== Yocto Project / Poky set-up =====

The [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html|Yocto Project Quick Start]] document explains how to set up //Yocto Project / Poky// and how to build images using the //meta-intel// layer.
Using this as a guideline, the following table describes how to use the //meta-tq-powerarch// layer for the <label stk_name>STK_NAME</label>.

^ Section  ^ Remarks / Instructions for //meta-tq-powerarch// & <label stk_name>STK_NAME</label>  ^
| [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html#welcome|Welcome!]]  | <wrap info round>Introduction and basic information about the //Yocto Project//</wrap>  |
| [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html#yp-intro|Introducing the Yocto Project Development Environment]]  | :::  |
| [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html#yp-resources|Setting Up to Use the Yocto Project]]  | <wrap info round>Description of basic requirements for using the //Yocto Project// (also cf. [[..:arm:<label mod_name>MOD_NAME</label>:yocto:meta-tq_qs#Prerequisites]] above)</wrap>  |
| [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html#releases|Yocto Project Release]]  | <wrap info round>Instructions on how to install a release of the //Yocto Project// on the Build Host</wrap>\\ \\ <WRAP alert round>
<code>
$ git checkout <label yocto_rel_branch>YOCTO_REL_BRANCH</label>
</code>will not work unless you change into the ''poky'' directory (i.e. the freshly cloned //Poky// repository).
</WRAP><WRAP tip round>
Alternatively you can clone the Poky repository and checkout branch <label yocto_rel_branch>YOCTO_REL_BRANCH</label> in one step by executing
<code>
$ git clone -b <label yocto_rel_branch>YOCTO_REL_BRANCH</label> git://git.yoctoproject.org/poky.git
</code>
</WRAP>  |
| [[http://<label yocto_doc_base_url>YOCTO_DOC_BASE_URL</label>/<label yocto_rel_ver_major>YOCTO_REL_VER_MAJOR</label>.<label yocto_rel_ver_minor>YOCTO_REL_VER_MINOR</label>/yocto-project-qs/yocto-project-qs.html#qs-building-images|Building Images]]  | <WRAP info round>
This section provides step-by-step instructions for
  - //Building An Image for Emulation//((7 steps, explicitly aims at emulation using //qemu//))
  - //Building An Image for Hardware//((5 steps, targets real hardware ))
</WRAP><WRAP important round>
To sucessfully build an image for hardware you have to carry out steps from both subsections((subsection headings may be missing in //Yocto Project Quick Start// (depends on //Poky// version) )) as follows.</WRAP><WRAP block>
==== Building an Image for Emulation ====
1. Be sure your build host is set up:
<wrap info round center 80%>See above</wrap>\\ 
2. Check out your branch:
<code>
$ git checkout <label yocto_rel_branch>YOCTO_REL_BRANCH</label>
</code>
<wrap tip round center 80%>You can skip this step if you checked out branch <label yocto_rel_branch>YOCTO_REL_BRANCH</label> already when/after cloning the //poky// repository.</wrap>\\ 
3. Initialize the Build Environment:
<wrap important round center 80%>The build environment will be initialised at a later step, do not run ''source oe-init-build-env'' yet!</wrap>\\ 
Create a file called ''environment'' as follows:
<code>
$ cat > environment
export TEMPLATECONF=meta-tq-powerarch/conf
source poky/oe-init-build-env
export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE FSL_RCW"
</code>
Press //CTRL+D// to close the file.\\
5. - 7. You can skip these steps, they are not required for using //meta-tq-powerarch//.
</WRAP><WRAP block>
==== Building an Image for Hardware ====
1. Create a Local Copy of <label mtq_repos>MTQ_REPOS</label>:
<code>
$ cd poky
$ tar xvf <path>/<to>/<tarball>/<label mtq_tarball>MTQ_TARBALL</label>
$ git clone -b <label yocto_rel_branch>YOCTO_REL_BRANCH</label><label yocto_rel_branch_module>YOCTO_REL_BRANCH_MODULE</label> git://git.yoctoproject.org/meta-fsl-ppc
</code>
2. Configure the Build:
<code>
$ cd ..
$ . environment
</code>
<wrap important round center 80%>When building for another machine((valid machines are\\ <label mtq_machines>MTQ_MACHINES</label>)) make sure that your //local.conf// contains a valid combination of ''MACHINE'', ''FSL_RCW'' and ''KERNEL_DEVICETREE''!</wrap>\\
3. Build an Image for <label stk_name>STK_NAME</label>:
<code>
$ bitbake <label mtq_image>MTQ_IMAGE</label>
</code>
<wrap help round center 80%>The resulting image is ''tmp/deploy/images/<label mtq_machine_default>MTQ_MACHINE_DEFAULT</label>((valid machines are\\ <label mtq_machines>MTQ_MACHINES</label>))/<label mtq_image>MTQ_IMAGE</label>-<label mtq_machine_default>MTQ_MACHINE_DEFAULT</label>((valid machines are\\ <label mtq_machines>MTQ_MACHINES</label>)).wic''</wrap>\\ 
4. Write the Image((valid machines are\\ <label mtq_machines>MTQ_MACHINES</label>))((''TARGET_DEVICE'' has to be an SD card))
<code>
$ sudo dd if=tmp/deploy/images/<label mtq_machine_default>MTQ_MACHINE_DEFAULT</label>/<label mtq_image>MTQ_IMAGE</label>-<label mtq_machine_default>MTQ_MACHINE_DEFAULT</label>.wic of=TARGET_DEVICE
</code>
5. Boot the <label stk_name>STK_NAME</label> from SD card (cf. [[..:arm:<label mod_name>MOD_NAME</label>:<label mb_name_code>MB_NAME_CODE</label>:dip_switches|<label mb_name>MB_NAME</label> DIP switche settings]])
</WRAP>  |