From 22083287912ebd552e33b79f7c567bc966376d43 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Fri, 15 Oct 2010 11:55:59 +0100 Subject: handbook: Move into documentation directory Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/Makefile | 38 + documentation/poky-ref-manual/TODO | 11 + documentation/poky-ref-manual/bsp-guide.xml | 61 + documentation/poky-ref-manual/bsp.xml | 451 +++++++ documentation/poky-ref-manual/development.xml | 825 +++++++++++++ .../examples/hello-autotools/hello_2.3.bb | 7 + .../examples/hello-single/files/helloworld.c | 8 + .../poky-ref-manual/examples/hello-single/hello.bb | 16 + .../examples/libxpm/libxpm_3.5.6.bb | 13 + .../examples/mtd-makefile/mtd-utils_1.0.0.bb | 13 + documentation/poky-ref-manual/extendpoky.xml | 1040 ++++++++++++++++ documentation/poky-ref-manual/faq.xml | 314 +++++ documentation/poky-ref-manual/introduction.xml | 352 ++++++ documentation/poky-ref-manual/poky-beaver.png | Bin 0 -> 26252 bytes documentation/poky-ref-manual/poky-handbook.png | Bin 0 -> 17829 bytes documentation/poky-ref-manual/poky-handbook.xml | 102 ++ documentation/poky-ref-manual/poky-logo.svg | 117 ++ documentation/poky-ref-manual/ref-bitbake.xml | 348 ++++++ documentation/poky-ref-manual/ref-classes.xml | 455 +++++++ documentation/poky-ref-manual/ref-features.xml | 302 +++++ documentation/poky-ref-manual/ref-images.xml | 72 ++ documentation/poky-ref-manual/ref-structure.xml | 514 ++++++++ documentation/poky-ref-manual/ref-variables.xml | 879 ++++++++++++++ documentation/poky-ref-manual/ref-varlocality.xml | 211 ++++ documentation/poky-ref-manual/resources.xml | 142 +++ .../screenshots/ss-anjuta-poky-1.png | Bin 0 -> 96531 bytes .../screenshots/ss-anjuta-poky-2.png | Bin 0 -> 76419 bytes .../screenshots/ss-oprofile-viewer.png | Bin 0 -> 51240 bytes .../poky-ref-manual/screenshots/ss-sato.png | Bin 0 -> 38689 bytes documentation/poky-ref-manual/style.css | 953 +++++++++++++++ documentation/poky-ref-manual/usingpoky.xml | 316 +++++ documentation/template/Vera.ttf | Bin 0 -> 65932 bytes documentation/template/Vera.xml | 1 + documentation/template/VeraMoBd.ttf | Bin 0 -> 49052 bytes documentation/template/VeraMoBd.xml | 1 + documentation/template/VeraMono.ttf | Bin 0 -> 49224 bytes documentation/template/VeraMono.xml | 1 + documentation/template/draft.png | Bin 0 -> 24847 bytes documentation/template/fop-config.xml | 58 + documentation/template/ohand-color.svg | 150 +++ documentation/template/poky-db-pdf.xsl | 64 + documentation/template/poky-handbook.png | Bin 0 -> 32145 bytes documentation/template/poky.svg | 163 +++ documentation/template/titlepage.templates.xml | 1240 ++++++++++++++++++++ documentation/tools/poky-docbook-to-pdf | 45 + 45 files changed, 9283 insertions(+) create mode 100644 documentation/poky-ref-manual/Makefile create mode 100644 documentation/poky-ref-manual/TODO create mode 100644 documentation/poky-ref-manual/bsp-guide.xml create mode 100644 documentation/poky-ref-manual/bsp.xml create mode 100644 documentation/poky-ref-manual/development.xml create mode 100644 documentation/poky-ref-manual/examples/hello-autotools/hello_2.3.bb create mode 100644 documentation/poky-ref-manual/examples/hello-single/files/helloworld.c create mode 100644 documentation/poky-ref-manual/examples/hello-single/hello.bb create mode 100644 documentation/poky-ref-manual/examples/libxpm/libxpm_3.5.6.bb create mode 100644 documentation/poky-ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb create mode 100644 documentation/poky-ref-manual/extendpoky.xml create mode 100644 documentation/poky-ref-manual/faq.xml create mode 100644 documentation/poky-ref-manual/introduction.xml create mode 100644 documentation/poky-ref-manual/poky-beaver.png create mode 100644 documentation/poky-ref-manual/poky-handbook.png create mode 100644 documentation/poky-ref-manual/poky-handbook.xml create mode 100644 documentation/poky-ref-manual/poky-logo.svg create mode 100644 documentation/poky-ref-manual/ref-bitbake.xml create mode 100644 documentation/poky-ref-manual/ref-classes.xml create mode 100644 documentation/poky-ref-manual/ref-features.xml create mode 100644 documentation/poky-ref-manual/ref-images.xml create mode 100644 documentation/poky-ref-manual/ref-structure.xml create mode 100644 documentation/poky-ref-manual/ref-variables.xml create mode 100644 documentation/poky-ref-manual/ref-varlocality.xml create mode 100644 documentation/poky-ref-manual/resources.xml create mode 100644 documentation/poky-ref-manual/screenshots/ss-anjuta-poky-1.png create mode 100644 documentation/poky-ref-manual/screenshots/ss-anjuta-poky-2.png create mode 100644 documentation/poky-ref-manual/screenshots/ss-oprofile-viewer.png create mode 100644 documentation/poky-ref-manual/screenshots/ss-sato.png create mode 100644 documentation/poky-ref-manual/style.css create mode 100644 documentation/poky-ref-manual/usingpoky.xml create mode 100644 documentation/template/Vera.ttf create mode 100644 documentation/template/Vera.xml create mode 100644 documentation/template/VeraMoBd.ttf create mode 100644 documentation/template/VeraMoBd.xml create mode 100644 documentation/template/VeraMono.ttf create mode 100644 documentation/template/VeraMono.xml create mode 100644 documentation/template/draft.png create mode 100644 documentation/template/fop-config.xml create mode 100644 documentation/template/ohand-color.svg create mode 100644 documentation/template/poky-db-pdf.xsl create mode 100644 documentation/template/poky-handbook.png create mode 100644 documentation/template/poky.svg create mode 100644 documentation/template/titlepage.templates.xml create mode 100755 documentation/tools/poky-docbook-to-pdf (limited to 'documentation') diff --git a/documentation/poky-ref-manual/Makefile b/documentation/poky-ref-manual/Makefile new file mode 100644 index 0000000000..b023045d0e --- /dev/null +++ b/documentation/poky-ref-manual/Makefile @@ -0,0 +1,38 @@ +all: html pdf tarball + +pdf: + cd ..; ./tools/poky-docbook-to-pdf ./poky-ref-manual/poky-handbook.xml ./template + cd..; ./tools/poky-docbook-to-pdf ./poky-ref-manual/bsp-guide.xml ./template + +XSLTOPTS = --stringparam html.stylesheet style.css \ + --stringparam chapter.autolabel 1 \ + --stringparam appendix.autolabel 1 \ + --stringparam section.autolabel 1 \ + --stringparam section.label.includes.component.label 1 \ + --xinclude + +## +# These URI should be rewritten by your distribution's xml catalog to +# match your localy installed XSL stylesheets. +XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current +XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl + +html: +# See http://www.sagehill.net/docbookxsl/HtmlOutput.html + xsltproc $(XSLTOPTS) -o poky-handbook.html $(XSL_XHTML_URI) poky-handbook.xml + xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSL_XHTML_URI) bsp-guide.xml + +tarball: html + tar -cvzf poky-handbook.tgz poky-handbook.html style.css screenshots/ss-sato.png poky-beaver.png poky-handbook.png + +validate: + xmllint --postvalid --xinclude --noout poky-handbook.xml + +OUTPUTS = poky-handbook.tgz poky-handbook.html poky-handbook.pdf bsp-guide.pdf +SOURCES = *.png *.xml *.css *.svg + +publish: + scp -r $(OUTPUTS) $(SOURCES) o-hand.com:/srv/www/pokylinux.org/doc/ + +clean: + rm $(OUTPUTS) diff --git a/documentation/poky-ref-manual/TODO b/documentation/poky-ref-manual/TODO new file mode 100644 index 0000000000..ee0db977cc --- /dev/null +++ b/documentation/poky-ref-manual/TODO @@ -0,0 +1,11 @@ +Handbook Todo List: + + * Document adding a new IMAGE_FEATURE to the customising images section + * Add instructions about using zaurus/openmoko emulation + * Add component overview/block diagrams + * Software Deevelopment intro should mention its software development for + intended target and could be a different arch etc and thus special case. + * Expand insane.bbclass documentation to cover tests + * Document remaining classes (see list in ref-classes) + * Document formfactor + diff --git a/documentation/poky-ref-manual/bsp-guide.xml b/documentation/poky-ref-manual/bsp-guide.xml new file mode 100644 index 0000000000..2f4906c173 --- /dev/null +++ b/documentation/poky-ref-manual/bsp-guide.xml @@ -0,0 +1,61 @@ + + + + + + + + + + + + Board Support Package (BSP) Developers Guide + + + + Richard Purdie + + Intel Corporation + + richard@linux.intel.com + + + + + + 0.4 + 26 May 2010 + Alpha Draft + + + + + 2010 + Intel Corporation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England & Wales as published by Creative Commons. + + + + + + + + + Index + + + + diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml new file mode 100644 index 0000000000..e0ca31732b --- /dev/null +++ b/documentation/poky-ref-manual/bsp.xml @@ -0,0 +1,451 @@ + + + + + Board Support Packages (BSP) - Developers Guide + + + A Board Support Package (BSP) is a collection of information which together + defines how to support a particular hardware device, set of devices, or + hardware platform. It will include information about the hardware features + present on the device and kernel configuration information along with any + additional hardware drivers required. It will also list any additional software + components required in addition to a generic Linux software stack for both + essential and optional platform features. + + + + The intent of this document is to define a structure for these components + so that BSPs follow a commonly understood layout, allowing them to be + provided in a common form that everyone understands. It also allows end-users + to become familiar with one common format and encourages standardisation + of software support of hardware. + + + + The proposed format does have elements that are specific to the Poky and + OpenEmbedded build systems. It is intended that this information can be + used by other systems besides Poky/OpenEmbedded and that it will be simple + to extract information and convert to other formats if required. The format + described can be directly accepted as a layer by Poky using its standard + layers mechanism, but it is important to recognise that the BSP captures all + the hardware specific details in one place in a standard format, which is + useful for any person wishing to use the hardware platform regardless of + the build system in use. + + + + The BSP specification does not include a build system or other tools - + it is concerned with the hardware specific components only. At the end + distribution point the BSP may be shipped combined with a build system + and other tools, but it is important to maintain the distinction that these + are separate components which may just be combined in certain end products. + + +
+ Example Filesystem Layout + + + The BSP consists of a file structure inside a base directory, meta-bsp in this example, where "bsp" is a placeholder for the machine or platform name. Examples of some files that it could contain are: + + + + +meta-bsp/ +meta-bsp/binary/zImage +meta-bsp/binary/poky-image-minimal.directdisk +meta-bsp/conf/layer.conf +meta-bsp/conf/machine/*.conf +meta-bsp/conf/machine/include/tune-*.inc +meta-bsp/packages/bootloader/bootloader_0.1.bb +meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch +meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp +meta-bsp/packages/linux/linux-bsp_2.6.50.bb +meta-bsp/packages/modem/modem-driver_0.1.bb +meta-bsp/packages/modem/modem-daemon_0.1.bb +meta-bsp/packages/image-creator/image-creator-native_0.1.bb +meta-bsp/prebuilds/ + + + + + + The following sections detail what these files and directories could contain. + + +
+ +
+ Prebuilt User Binaries (meta-bsp/binary/*) + + + This optional area contains useful prebuilt kernels and userspace filesystem + images appropriate to the target system. Users could use these to get a system + running and quickly get started on development tasks. The exact types of binaries + present will be highly hardware-dependent but a README file should be present + explaining how to use them with the target hardware. If prebuilt binaries are + present, source code to meet licensing requirements must also be provided in + some form. + + +
+ +
+ Layer Configuration (meta-bsp/conf/layer.conf) + + + This file identifies the structure as a Poky layer. This file identifies the + contents of the layer and contains information about how Poky should use + it. In general it will most likely be a standard boilerplate file consisting of: + + + + +# We have a conf directory, add to BBPATH +BBPATH := "${BBPATH}${LAYERDIR}" + +# We have a packages directory, add to BBFILES +BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb" + +BBFILE_COLLECTIONS += "bsp" +BBFILE_PATTERN_bsp := "^${LAYERDIR}/" +BBFILE_PRIORITY_bsp = "5" + + + + + which simply makes bitbake aware of the packages and conf directories. + + + + This file is required for recognition of the BSP by Poky. + + +
+ +
+ Hardware Configuration Options (meta-bsp/conf/machine/*.conf) + + + The machine files bind together all the information contained elsewhere + in the BSP into a format that Poky/OpenEmbedded can understand. If + the BSP supports multiple machines, multiple machine configuration files + can be present. These filenames correspond to the values users set the + MACHINE variable to. + + + + These files would define things like which kernel package to use + (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to + include in different types of images, any special software components + that are needed, any bootloader information, and also any special image + format requirements. + + + + At least one machine file is required for a Poky BSP layer but more than one may be present. + + +
+ +
+ Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc) + + + These are shared hardware "tuning" definitions and are commonly used to + pass specific optimisation flags to the compiler. An example is + tune-atom.inc: + + + +BASE_PACKAGE_ARCH = "core2" +TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" + + + + which defines a new package architecture called "core2" and uses the + optimization flags specified, which are carefully chosen to give best + performance on atom cpus. + + + The tune file would be included by the machine definition and can be + contained in the BSP or reference one from the standard core set of + files included with Poky itself. + + + These files are optional for a Poky BSP layer. + +
+
+ Linux Kernel Configuration (meta-bsp/packages/linux/*) + + + These files make up the definition of a kernel to use with this + hardware. In this case it is a complete self-contained kernel with its own + configuration and patches but kernels can be shared between many + machines as well. Taking some specific example files: + + + +meta-bsp/packages/linux/linux-bsp_2.6.50.bb + + + + which is the core kernel recipe which firstly details where to get the kernel + source from. All standard source code locations are supported so this could + be a release tarball, some git repository, or source included in + the directory within the BSP itself. It then contains information about which + patches to apply and how to configure and build it. It can reuse the main + Poky kernel build class, so the definitions here can remain very simple. + + + +linux-bsp-2.6.50/*.patch + + + + which are patches which may be applied against the base kernel, wherever + they may have been obtained from. + + + +meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp + + + + which is the configuration information to use to configure the kernel. + + + Examples of kernel recipes are available in Poky itself. These files are + optional since a kernel from Poky itself could be selected, although it + would be unusual not to have a kernel configuration. + +
+ +
+ Other Software (meta-bsp/packages/*) + + + This area includes other pieces of software which the hardware may need for best + operation. These are just examples of the kind of things that may be + encountered. These are standard .bb file recipes in the usual Poky format, + so for examples, see standard Poky recipes. The source can be included directly, + referred to in source control systems or release tarballs of external software projects. + + + +meta-bsp/packages/bootloader/bootloader_0.1.bb + + + + Some kind of bootloader recipe which may be used to generate a new + bootloader binary. Sometimes these are included in the final image + format and needed to reflash hardware. + + + +meta-bsp/packages/modem/modem-driver_0.1.bb +meta-bsp/packages/modem/modem-daemon_0.1.bb + + + + These are examples of a hardware driver and also a hardware daemon which + may need to be included in images to make the hardware useful. "modem" + is one example but there may be other components needed like firmware. + + + +meta-bsp/packages/image-creator/image-creator-native_0.1.bb + + + + Sometimes the device will need an image in a very specific format for + its update mechanism to accept and reflash with it. Recipes to build the + tools needed to do this can be included with the BSP. + + + These files only need be provided if the platform requires them. + +
+ +
+ Append BSP specific information to existing recipes + + + Say you have a recipe like pointercal which has machine-specific information in it, + and then you have your new BSP code in a layer. Before the .bbappend extension was + introduced, you'd have to copy the whole pointercal recipe and files into your layer, + and then add the single file for your machine, which is ugly. + + .bbappend makes the above work much easier, to allow BSP-specific information to be merged + with the original recipe easily. When bitbake finds any X.bbappend files, they will be + included after bitbake loads X.bb but before finalise or anonymous methods run. + This allows the BSP layer to poke around and do whatever it might want to customise + the original recipe. + + .bbappend is expected to include the below two lines in the head (which may be changed + in the future): + + + +THISDIR := "${@os.path.dirname(bb.data.getVar('FILE', d, True))}" +FILESPATH =. "${@base_set_filespath(["${THISDIR}/${PN}"], d)}:" + + + + Then the BSP could add machine-specific config files in layer directory, which will be + added by bitbake. You can look at meta-emenlow/packages/formfactor as an example. + +
+ +
+ Prebuild Data (meta-bsp/prebuilds/*) + + + The location can contain a precompiled representation of the source code + contained elsewhere in the BSP layer. It can be processed and used by + Poky to provide much faster build times, assuming a compatible configuration is used. + + + + These files are optional. + + +
+ +
+ BSP 'Click-through' Licensing Procedure + + This section is here as a description of how + click-through licensing is expected to work, and is + not yet not impemented. + + + + In some cases, a BSP may contain separately licensed IP + (Intellectual Property) for a component, which imposes + upon the user a requirement to accept the terms of a + 'click-through' license. Once the license is accepted + (in whatever form that may be, see details below) the + Poky build system can then build and include the + corresponding component in the final BSP image. Some + affected components may be essential to the normal + functioning of the system and have no 'free' replacement + i.e. the resulting system would be non-functional + without them. Other components may be simply + 'good-to-have' or purely elective, or if essential + nonetheless have a 'free' (possibly less-capable) + version which may substituted for in the BSP recipe. + + + + For the latter cases, where it is possible to do so from + a functionality perspective, the Poky website will make + available a 'de-featured' BSP completely free of + encumbered IP, which can be used directly and without + any further licensing requirements. If present, this + fully 'de-featured' BSP will be named meta-bsp (i.e. the + normal default naming convention). This is the simplest + and therefore preferred option if available, assuming + the resulting functionality meets requirements. + + + + If however, a non-encumbered version is unavailable or + the 'free' version would provide unsuitable + functionality or quality, an encumbered version can be + used. Encumbered versions of a BSP are given names of + the form meta-bsp-nonfree. There are several ways + within the Poky build system to satisfy the licensing + requirements for an encumbered BSP, in roughly the + following order of preference: + + + + + + + Get a license key (or keys) for the encumbered BSP + by + visiting https://pokylinux.org/bsp-keys.html + and give the web form there the name of the BSP + and your e-mail address. + + + + [screenshot of dialog box] + + + + After agreeing to any applicable license terms, the + BSP key(s) will be immediately sent to the address + given and can be used by specifying BSPKEY_<keydomain> + environment variables when building the image: + + + + $ BSPKEY_<keydomain>=<key> bitbake poky-image-sato + + + + This will allow the encumbered image to be built + with no change at all to the normal build process. + + + + Equivalently and probably more conveniently, a line + for each key can instead be put into the user's + local.conf file. + + + + The <keydomain> component of the + BSPKEY_<keydomain> is required because there + may be multiple licenses in effect for a give BSP; a + given <keydomain> in such cases corresponds to + a particular license. In order for an encumbered + BSP encompassing multiple key domains to be built + successfully, a <keydomain> entry for each + applicable license must be present in local.conf or + supplied on the command-line. + + + + + Do nothing - build as you normally would, and follow + any license prompts that originate from the + encumbered BSP (the build will cleanly stop at this + point). These usually take the form of instructions + needed to manually fetch the encumbered package(s) + and md5 sums into e.g. the poky/build/downloads + directory. Once the manual package fetch has been + completed, restarting the build will continue where + it left off, this time without the prompt since the + license requirements will have been satisfied. + + + + + Get a full-featured BSP recipe rather than a key, by + visiting + https://pokylinux.org/bsps.html. + Accepting the license agreement(s) presented will + subsequently allow you to download a tarball + containing a full-featured BSP legally cleared for + your use by the just-given license agreement(s). + This method will also allow the encumbered image to + be built with no change at all to the normal build + process. + + + + + Note that method 3 is also the only option available + when downloading pre-compiled images generated from + non-free BSPs. Those images are likewise available at + https://pokylinux.org/bsps.html. + +
+ + diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml new file mode 100644 index 0000000000..a383a2f4a8 --- /dev/null +++ b/documentation/poky-ref-manual/development.xml @@ -0,0 +1,825 @@ + + + +Platform Development with Poky + +
+ Software development + + Poky supports several methods of software development. These different + forms of development are explained below and can be switched + between as needed. + + +
+ Developing externally using the Poky SDK + + + The meta-toolchain and meta-toolchain-sdk targets (see + the images section) build tarballs which contain toolchains and + libraries suitable for application development outside Poky. These unpack into the + /opt/poky directory and contain + a setup script, e.g. + /opt/poky/environment-setup-i586-poky-linux which + can be sourced to initialise a suitable environment. After sourcing this, the + compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other + useful utilities are added to the PATH. Variables to assist pkgconfig and + autotools are also set so that, for example, configure can find pre-generated test + results for tests which need target hardware to run. + + + + Using the toolchain with autotool enabled packages is straightforward, just pass the + appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi". + For other projects it is usually a case of ensuring the cross tools are used e.g. + CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld. + +
+ +
+ Developing externally using the Anjuta plugin + + + An Anjuta IDE plugin exists to make developing software within the Poky framework + easier for the application developer. It presents a graphical IDE from which the + developer can cross compile an application then deploy and execute the output in a QEMU + emulation session. It also supports cross debugging and profiling. + + + + To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta it's development + headers and the Anjuta plugin. The Poky Anjuta plugin is available to download as a tarball at the + OpenedHand labs page or + directly from the Poky Git repository located at git://git.pokylinux.org/anjuta-poky; a web interface + to the repository can be accessed at . + + + See the README file contained in the project for more information on dependencies and building + the plugin. If you want to disable remote gdb debugging, please pass --diable-gdb-integration + switch when doing configure. + + +
+ Setting up the Anjuta plugin + + Extract the tarball for the toolchain into / as root. The + toolchain will be installed into + /opt/poky. + + To use the plugin, first open or create an existing + project. If creating a new project the "C GTK+" project type + will allow itself to be cross-compiled. However you should be + aware that this uses glade for the UI. + + To activate the plugin go to + EditPreferences, + then choose General from the left hand side. Choose the + Installed plugins tab, scroll down to Poky + SDK and check the + box. The plugin is now activated but first it must be + configured. +
+ +
+ Configuring the Anjuta plugin + + The configuration options for the SDK can be found by choosing + the Poky SDK icon from the left hand side. The following options + need to be set: + + + + SDK root: If we use external toolchain, we need to set SDK root. + this is the root directory of the SDK's sysroot. For an i586 SDK this will be /opt/poky/. + This directory will contain directories named like "bin", + "include", "var", etc. under your selected target architecture subdirectory + /opt/poky/sysroot/i586-poky-linux/. Needed cross compile tools are under + /opt/poky/sysroot/i586-pokysdk-linux/ + + + Poky root: If we have local poky build tree, we need to set the Poky root. + this is the root directory of the poky build tree, if you build your i586 target architecture + under the subdirectory of build_x86 within your poky tree, the Poky root directory should be + ${Poky_tree}/build_x86/. + + + Target Architecture: this is the cross compile + triplet, e.g. "i586-poky-linux". This target triplet is the prefix extracted from + the set up script file name. For examle, "i586-poky-linux" is extracted from set up script file + /opt/poky/environment-setup-i586-poky-linux + + + Kernel: use the file chooser to select the kernel + to use with QEMU + + Root filesystem: use the file chooser to select + the root filesystem directory, this is the directory where you use "poky-extract-sdk" command to + extract the poky-image-sdk tarball. + + + +
+ +
+ Using the Anjuta plugin + + As an example, cross-compiling a project, deploying it into + QEMU and running a debugger against it and then doing a system + wide profile. + + Choose BuildRun + Configure or + BuildRun + Autogenerate to run "configure" + (or to run "autogen") for the project. This passes command line + arguments to instruct it to cross-compile. + + Next do + BuildBuild + Project to build and compile the + project. If you have previously built the project in the same + tree without using the cross-compiler you may find that your + project fails to link. Simply do + BuildClean + Project to remove the old + binaries. You may then try building again. + + Next start QEMU by using + ToolsStart + QEMU, this will start QEMU and + will show any error messages in the message view. Once Poky has + fully booted within QEMU you may now deploy into it. + + Once built and QEMU is running, choose + ToolsDeploy, + this will install the package into a temporary directory and + then copy using rsync over SSH into the target. Progress and + messages will be shown in the message view. + + To debug a program installed into onto the target choose + ToolsDebug + remote. This prompts for the + local binary to debug and also the command line to run on the + target. The command line to run should include the full path to + the to binary installed in the target. This will start a + gdbserver over SSH on the target and also an instance of a + cross-gdb in a local terminal. This will be preloaded to connect + to the server and use the SDK root to find + symbols. This gdb will connect to the target and load in + various libraries and the target program. You should setup any + breakpoints or watchpoints now since you might not be able to + interrupt the execution later. You may stop + the debugger on the target using + ToolsStop + debugger. + + It is also possible to execute a command in the target over + SSH, the appropriate environment will be be set for the + execution. Choose + ToolsRun + remote to do this. This will open + a terminal with the SSH command inside. + + To do a system wide profile against the system running in + QEMU choose + ToolsProfile + remote. This will start up + OProfileUI with the appropriate parameters to connect to the + server running inside QEMU and will also supply the path to the + debug information necessary to get a useful profile. + +
+
+ + +
+ Developing externally in QEMU + + Running Poky QEMU images is covered in the Running an Image section. + + + Poky's QEMU images contain a complete native toolchain. This means + that applications can be developed within QEMU in the same was as a + normal system. Using qemux86 on an x86 machine is fast since the + guest and host architectures match, qemuarm is slower but gives + faithful emulation of ARM specific issues. To speed things up these + images support using distcc to call a cross-compiler outside the + emulated system too. If runqemu was used to start + QEMU, and distccd is present on the host system, any bitbake cross + compiling toolchain available from the build system will automatically + be used from within qemu simply by calling distcc + (export CC="distcc" can be set in the enviroment). + Alterntatively, if a suitable SDK/toolchain is present in + /opt/poky it will also + automatically be used. + + + + There are several options for connecting into the emulated system. + QEMU provides a framebuffer interface which has standard consoles + available. There is also a serial connection available which has a + console to the system running on it and IP networking as standard. + The images have a dropbear ssh server running with the root password + disabled allowing standard ssh and scp commands to work. The images + also contain an NFS server exporting the guest's root filesystem + allowing that to be made available to the host. + +
+ +
+ Developing in Poky directly + + Working directly in Poky is a fast and effective development technique. + The idea is that you can directly edit files in + WORKDIR + or the source directory S + and then force specific tasks to rerun in order to test the changes. + An example session working on the matchbox-desktop package might + look like this: + + + + +$ bitbake matchbox-desktop +$ sh +$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/ +$ cd matchbox-desktop-2 +$ vi src/main.c +$ exit +$ bitbake matchbox-desktop -c compile -f +$ bitbake matchbox-desktop + + + + + Here, we build the package, change into the work directory for the package, + change a file, then recompile the package. Instead of using sh like this, + you can also use two different terminals. The risk with working like this + is that a command like unpack could wipe out the changes you've made to the + work directory so you need to work carefully. + + + + It is useful when making changes directly to the work directory files to do + so using quilt as detailed in the + modifying packages with quilt section. The resulting patches can be copied + into the recipe directory and used directly in the SRC_URI. + + + For a review of the skills used in this section see Sections 2.1.1 and 2.4.2. + + +
+ +
+ Developing with 'devshell' + + + When debugging certain commands or even to just edit packages, the + 'devshell' can be a useful tool. To start it you run a command like: + + + + +$ bitbake matchbox-desktop -c devshell + + + + + which will open a terminal with a shell prompt within the Poky + environment. This means PATH is setup to include the cross toolchain, + the pkgconfig variables are setup to find the right .pc files, + configure will be able to find the Poky site files etc. Within this + environment, you can run configure or compile command as if they + were being run by Poky itself. You are also changed into the + source (S) + directory automatically. When finished with the shell just exit it + or close the terminal window. + + + + The default shell used by devshell is the gnome-terminal. Other + forms of terminal can also be used by setting the + TERMCMD and + TERMCMDRUN variables + in local.conf. For examples of the other options available, see + meta/conf/bitbake.conf. An external shell is + launched rather than opening directly into the original terminal + window to make interaction with bitbakes multiple threads easier + and also allow a client/server split of bitbake in the future + (devshell will still work over X11 forwarding or similar). + + + + It is worth remembering that inside devshell you need to use the full + compiler name such as arm-poky-linux-gnueabi-gcc + instead of just gcc and the same applies to other + applications from gcc, bintuils, libtool etc. Poky will have setup + environmental variables such as CC to assist applications, such as make, + find the correct tools. + + +
+ +
+ Developing within Poky with an external SCM based package + + + If you're working on a recipe which pulls from an external SCM it + is possible to have Poky notice new changes added to the + SCM and then build the latest version. This only works for SCMs + where its possible to get a sensible revision number for changes. + Currently it works for svn, git and bzr repositories. + + + + To enable this behaviour it is simply a case of adding + SRCREV_pn- + PN = "${AUTOREV}" to + local.conf where PN + is the name of the package for which you want to enable automatic source + revision updating. + +
+ +
+ +
+ Debugging with GDB Remotely + + + GDB (The GNU Project Debugger) + allows you to examine running programs to understand and fix problems and + also to perform postmortem style analsys of program crashes. It is available + as a package within poky and installed by default in sdk images. It works best + when -dbg packages for the application being debugged are installed as the + extra symbols give more meaningful output from GDB. + + + + Sometimes, due to memory or disk space constraints, it is not possible + to use GDB directly on the remote target to debug applications. This is + due to the fact that + GDB needs to load the debugging information and the binaries of the + process being debugged. GDB then needs to perform many + computations to locate information such as function names, variable + names and values, stack traces, etc. even before starting the debugging + process. This places load on the target system and can alter the + characteristics of the program being debugged. + + + This is where GDBSERVER comes into play as it runs on the remote target + and does not load any debugging information from the debugged process. + Instead, the debugging information processing is done by a GDB instance + running on a distant computer - the host GDB. The host GDB then sends + control commands to GDBSERVER to make it stop or start the debugged + program, as well as read or write some memory regions of that debugged + program. All the debugging information loading and processing as well + as the heavy debugging duty is done by the host GDB, giving the + GDBSERVER running on the target a chance to remain small and fast. + + + As the host GDB is responsible for loading the debugging information and + doing the necessary processing to make actual debugging happen, the + user has to make sure it can access the unstripped binaries complete + with their debugging information and compiled with no optimisations. The + host GDB must also have local access to all the libraries used by the + debugged program. On the remote target the binaries can remain stripped + as GDBSERVER does not need any debugging information there. However they + must also be compiled without optimisation matching the host's binaries. + + + + The binary being debugged on the remote target machine is hence referred + to as the 'inferior' in keeping with GDB documentation and terminology. + Further documentation on GDB, is available on + on their site. + + +
+ Launching GDBSERVER on the target + + First, make sure gdbserver is installed on the target. If not, + install the gdbserver package (which needs the libthread-db1 + package). + + + To launch GDBSERVER on the target and make it ready to "debug" a + program located at /path/to/inferior, connect + to the target and launch: + $ gdbserver localhost:2345 /path/to/inferior + After that, gdbserver should be listening on port 2345 for debugging + commands coming from a remote GDB process running on the host computer. + Communication between the GDBSERVER and the host GDB will be done using + TCP. To use other communication protocols please refer to the + GDBSERVER documentation. + +
+ +
+ Launching GDB on the host computer + + + Running GDB on the host computer takes a number of stages, described in the + following sections. + + +
+ Build the cross GDB package + + A suitable gdb cross binary is required which runs on your host computer but + knows about the the ABI of the remote target. This can be obtained from + the the Poky toolchain, e.g. + /opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/armv5te-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb + which "x86_64" is the host architecture, "arm" is the target architecture and "linux-gnueabi" the target ABI. + + + + Alternatively this can be built directly by Poky. To do this you would build + the gdb-cross package so for example you would run: + bitbake gdb-cross + Once built, the cross gdb binary can be found at + tmp/sysroots/<host-arch>/usr/bin/\ +<target-arch>-poky-<target-abi>/<target-arch>-poky-<target-abi>-gdb + + +
+
+ + Making the inferior binaries available + + + The inferior binary needs to be available to GDB complete with all debugging + symbols in order to get the best possible results along with any libraries + the inferior depends on and their debugging symbols. There are a number of + ways this can be done. + + + + Perhaps the easiest is to have an 'sdk' image corresponding to the plain + image installed on the device. In the case of 'pky-image-sato', + 'poky-image-sdk' would contain suitable symbols. The sdk images already + have the debugging symbols installed so its just a question expanding the + archive to some location and telling GDB where this is. + + + + Alternatively, poky can build a custom directory of files for a specific + debugging purpose by reusing its tmp/rootfs directory, on the host computer + in a slightly different way to normal. This directory contains the contents + of the last built image. This process assumes the image running on the + target was the last image to be built by Poky, the package foo + contains the inferior binary to be debugged has been built without without + optimisation and has debugging information available. + + + Firstly you want to install the foo package to tmp/rootfs + by doing: + + tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ +tmp/work/<target-abi>/poky-image-sato-1.0-r0/opkg.conf -o \ +tmp/rootfs/ update + + then, + + tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ +tmp/work/<target-abi>/poky-image-sato-1.0-r0/opkg.conf \ +-o tmp/rootfs install foo + +tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ +tmp/work/<target-abi>/poky-image-sato-1.0-r0/opkg.conf \ +-o tmp/rootfs install foo-dbg + + which installs the debugging information too. + + +
+
+ + Launch the host GDB + + To launch the host GDB, run the cross gdb binary identified above with + the inferior binary specified on the commandline: + <target-arch>-poky-<target-abi>-gdb rootfs/usr/bin/foo + This loads the binary of program foo + as well as its debugging information. Once the gdb prompt + appears, you must instruct GDB to load all the libraries + of the inferior from tmp/rootfs: + set solib-absolute-prefix /path/to/tmp/rootfs + where /path/to/tmp/rootfs must be + the absolute path to tmp/rootfs or wherever the + binaries with debugging information are located. + + + Now, tell GDB to connect to the GDBSERVER running on the remote target: + target remote remote-target-ip-address:2345 + Where remote-target-ip-address is the IP address of the + remote target where the GDBSERVER is running. 2345 is the + port on which the GDBSERVER is running. + + +
+
+ + Using the Debugger + + Debugging can now proceed as normal, as if the debugging were being done on the + local machine, for example to tell GDB to break in the main + function, for instance: + break main + and then to tell GDB to "continue" the inferior execution, + continue + + + For more information about using GDB please see the + project's online documentation at . + +
+
+ +
+ +
+ Profiling with OProfile + + + OProfile is a + statistical profiler well suited to finding performance + bottlenecks in both userspace software and the kernel. It provides + answers to questions like "Which functions does my application spend + the most time in when doing X?". Poky is well integrated with OProfile + to make profiling applications on target hardware straightforward. + + + + To use OProfile you need an image with OProfile installed. The easiest + way to do this is with "tools-profile" in IMAGE_FEATURES. You also + need debugging symbols to be available on the system where the analysis + will take place. This can be achieved with "dbg-pkgs" in IMAGE_FEATURES or by + installing the appropriate -dbg packages. For + successful call graph analysis the binaries must preserve the frame + pointer register and hence should be compiled with the + "-fno-omit-framepointer" flag. In Poky this can be achieved with + SELECTED_OPTIMIZATION + = "-fexpensive-optimizations -fno-omit-framepointer + -frename-registers -O2" or by setting DEBUG_BUILD = "1" in + local.conf (the latter will also add extra debug information making the + debug packages large). + + +
+ Profiling on the target + + + All the profiling work can be performed on the target device. A + simple OProfile session might look like: + + + + +# opcontrol --reset +# opcontrol --start --separate=lib --no-vmlinux -c 5 +[do whatever is being profiled] +# opcontrol --stop +$ opreport -cl + + + + + Here, the reset command clears any previously profiled data, + OProfile is then started. The options used to start OProfile mean + dynamic library data is kept separately per application, kernel + profiling is disabled and callgraphing is enabled up to 5 levels + deep. To profile the kernel, you would specify the + --vmlinux=/path/to/vmlinux option (the vmlinux file is usually in + /boot/ in Poky and must match the running kernel). The profile is + then stopped and the results viewed with opreport with options + to see the separate library symbols and callgraph information. + + + Callgraphing means OProfile not only logs infomation about which + functions time is being spent in but also which functions + called those functions (their parents) and which functions that + function calls (its children). The higher the callgraphing depth, + the more accurate the results but this also increased the loging + overhead so it should be used with caution. On ARM, binaries need + to have the frame pointer enabled for callgraphing to work (compile + with the gcc option -fno-omit-framepointer). + + + For more information on using OProfile please see the OProfile + online documentation at . + +
+ +
+ Using OProfileUI + + + A graphical user interface for OPr