diff options
Diffstat (limited to 'handbook')
56 files changed, 0 insertions, 9165 deletions
diff --git a/handbook/ChangeLog b/handbook/ChangeLog deleted file mode 100644 index e0b51d4a12..0000000000 --- a/handbook/ChangeLog +++ /dev/null @@ -1,38 +0,0 @@ -2008-02-29 Matthew Allum <mallum@openedhand.com> - - * development.xml: - Disable images too big / lack context for now. - * introduction.xml: - Remove some OH specific stuff. - * style.css: - Remove limit on image size - -2008-02-15 Matthew Allum <mallum@openedhand.com> - - * introduction.xml: - Minor tweaks to 'What is Poky' - -2008-02-15 Matthew Allum <mallum@openedhand.com> - - * poky-handbook.xml: - * poky-handbook.png - * poky-beaver.png - * poky-logo.svg: - * style.css: - Add some title images. - -2008-02-14 Matthew Allum <mallum@openedhand.com> - - * development.xml: - remove uri's - * style.css: - Fix glossary - -2008-02-06 Matthew Allum <mallum@openedhand.com> - - * Makefile: - Add various xslto options for html. - * introduction.xml: - Remove link in title. - * style.css: - Add initial version diff --git a/handbook/Makefile b/handbook/Makefile deleted file mode 100644 index 01353b11af..0000000000 --- a/handbook/Makefile +++ /dev/null @@ -1,33 +0,0 @@ -all: html pdf tarball - -pdf: - - ./poky-doc-tools/poky-docbook-to-pdf poky-handbook.xml - ./poky-doc-tools/poky-docbook-to-pdf bsp-guide.xml -# -- old way -- -# dblatex poky-handbook.xml - -XSLTOPTS = --stringparam html.stylesheet style.css \ - --stringparam chapter.autolabel 1 \ - --stringparam appendix.autolabel 1 \ - --stringparam section.autolabel 1 -XSLTOPTS2 = --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl - -html: -# See http://www.sagehill.net/docbookxsl/HtmlOutput.html - xsltproc $(XSLTOPTS) -o poky-handbook.html $(XSLTOPTS2) poky-handbook.xml - xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSLTOPTS2) bsp-guide.xml -# -- old way -- -# xmlto xhtml-nochunks poky-handbook.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/ diff --git a/handbook/TODO b/handbook/TODO deleted file mode 100644 index ee0db977cc..0000000000 --- a/handbook/TODO +++ /dev/null @@ -1,11 +0,0 @@ -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/handbook/bsp-guide.xml b/handbook/bsp-guide.xml deleted file mode 100644 index e5933d7e9c..0000000000 --- a/handbook/bsp-guide.xml +++ /dev/null @@ -1,61 +0,0 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<book id='poky-handbook' lang='en' - xmlns:xi="http://www.w3.org/2003/XInclude" - xmlns="http://docbook.org/ns/docbook" - > - <bookinfo> - - <mediaobject> - <imageobject> - <imagedata fileref='common/poky-handbook.png' - format='SVG' - align='center' scalefit='1' width='100%'/> - </imageobject> - </mediaobject> - - <title>Board Support Package (BSP) Developers Guide</title> - - <authorgroup> - <author> - <firstname>Richard</firstname> <surname>Purdie</surname> - <affiliation> - <orgname>Intel Corporation</orgname> - </affiliation> - <email>richard@linux.intel.com</email> - </author> - </authorgroup> - - <revhistory> - <revision> - <revnumber>0.4</revnumber> - <date>26 May 2010</date> - <revremark>Alpha Draft</revremark> - </revision> - </revhistory> - - <copyright> - <year>2010</year> - <holder>Intel Corporation</holder> - </copyright> - - <legalnotice> - <para> - Permission is granted to copy, distribute and/or modify this document under - the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. - </para> - </legalnotice> - - </bookinfo> - - <xi:include href="bsp.xml"/> - - <index id='index'> - <title>Index</title> - </index> - -</book> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/handbook/bsp.xml b/handbook/bsp.xml deleted file mode 100644 index 37dd166749..0000000000 --- a/handbook/bsp.xml +++ /dev/null @@ -1,287 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='bsp'> - - <title>Board Support Packages (BSP) - Developers Guide</title> - - <para> - 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, kernel configuration information along with any - additional hardware drivers required and also any additional software - components required in addition to a generic Linux software stack for both - essential and optional platform features. - </para> - - <para> - The intend 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 way that everyone understands. It also allows end - users to become familiar with one common format and encourages standardisation - of software support of hardware. - </para> - - <para> - 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 - descriped can be directly accepted as a layer by Poky using its standard - layers mechanism but its 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. - </para> - - <para> - The BSP specification does not include a build system or other tooling, - 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. - </para> - - <section id='bsp-filelayout'> - <title>Example Filesystem Layout</title> - - <para> - 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: - </para> - - <para> - <programlisting> -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/ - - </programlisting> - </para> - - <para> - The following sections detail what these files and directories could contain. - </para> - - </section> - - <section id='bsp-filelayout-binary'> - <title>Prebuilt User Binaries (meta-bsp/binary/*)</title> - - <para> - This optional area cotains 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. - </para> - - </section> - - <section id='bsp-filelayout-layer'> - <title>Layer Configuration (meta-bsp/conf/layer.conf)</title> - - <para> - This file identifies the structure as a Poky layer. This file identifies the - contents of the layer and how contains information about how Poky should use - it. In general it will most likely be a standard boilerplate file consisting of: - </para> - - <para> - <programlisting> -# 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 += "meta-bsp" -BBFILE_PATTERN_meta-bsp := "^${LAYERDIR}/" -BBFILE_PRIORITY_meta-bsp = "5" - </programlisting> - </para> - - <para> - which simply makes bitbake aware of the packages and conf directories. - </para> - - <para> - This file is required for recognition of the BSP by Poky. - </para> - - </section> - - <section id='bsp-filelayout-machine'> - <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title> - - <para> - The machine files bind together all the information contained elsewhere - in the BSP into a format that Poky/OpenEmbedded can understand it in. 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. - </para> - - <para> - 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. - </para> - - <para> - At least one machine file is required for a Poky BSP layer but more than one may be present. - </para> - - </section> - - <section id='bsp-filelayout-tune'> - <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title> - - <para> - These are shared hardware "tuning" definitions and are commonly used to - pass specific optimisation flags to the compiler. An example is - tune-atom.inc: - </para> - <para> - <programlisting> -BASE_PACKAGE_ARCH = "core2" -TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse" - </programlisting> - </para> - <para> - which defines a new package architecture called "core2" and uses the - optimisation flags specified which are carefully chosen to give best - performance on atom cpus. - </para> - <para> - 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. - </para> - <para> - These files are optional for a Poky BSP layer. - </para> - </section> - <section id='bsp-filelayout-kernel'> - <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title> - - <para> - These files make up the definition of a kernel to use with this - hardware. In this case its 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: - </para> - <para> - <programlisting> -meta-bsp/packages/linux/linux-bsp_2.6.50.bb - </programlisting> - </para> - <para> - 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 meaning the definitions here can remain very simple. - </para> - <para> - <programlisting> -linux-bsp-2.6.50/*.patch - </programlisting> - </para> - <para> - which are patches which may be applied against the base kernel, wherever - that may have been obtained from. - </para> - <para> - <programlisting> -meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp - </programlisting> - </para> - <para> - which is the configuration information to use to configure the kernel. - </para> - <para> - 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. - </para> - </section> - - <section id='bsp-filelayout-packages'> - <title>Other Software (meta-bsp/packages/*)</title> - - <para> - 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. The 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. - </para> - <para> - <programlisting> -meta-bsp/packages/bootloader/bootloader_0.1.bb - </programlisting> - </para> - <para> - 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. - </para> - <para> - <programlisting> -meta-bsp/packages/modem/modem-driver_0.1.bb -meta-bsp/packages/modem/modem-daemon_0.1.bb - </programlisting> - </para> - <para> - 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. - </para> - <para> - <programlisting> -meta-bsp/packages/image-creator/image-creator-native_0.1.bb - </programlisting> - </para> - <para> - 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. - </para> - <para> - These files only need be provided if the platform requires them. - </para> - </section> - - <section id='bsp-filelayout-prebuilds'> - <title>Prebuild Data (meta-bsp/prebuilds/*)</title> - - <para> - The location can contains 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. - </para> - - <para> - These files are optional. - </para> - - </section> - -</chapter> diff --git a/handbook/development.xml b/handbook/development.xml deleted file mode 100644 index e6fb826d33..0000000000 --- a/handbook/development.xml +++ /dev/null @@ -1,856 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id="platdev"> -<title>Platform Development with Poky</title> - -<section id="platdev-appdev"> - <title>Software development</title> - <para> - Poky supports several methods of software development. These different - forms of development are explained below and can be switched - between as needed. - </para> - - <section id="platdev-appdev-external-sdk"> - <title>Developing externally using the Poky SDK</title> - - <para> - The meta-toolchain and meta-toolchain-sdk targets (<link linkend='ref-images'>see - the images section</link>) build tarballs which contain toolchains and - libraries suitable for application development outside Poky. These unpack into the - <filename class="directory">/usr/local/poky</filename> directory and contain - a setup script, e.g. - <filename>/usr/local/poky/eabi-glibc/arm/environment-setup</filename> 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. - </para> - - <para> - 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. - </para> - </section> - - <section id="platdev-appdev-external-anjuta"> - <title>Developing externally using the Anjuta plugin</title> - - <para> - 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. - </para> -<!-- DISBALED, TOO BIG! - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="screenshots/ss-anjuta-poky-1.png" format="PNG"/> - </imageobject> - <caption> - <para>The Anjuta Poky SDK plugin showing an active QEMU session running Sato</para> - </caption> - </mediaobject> - </screenshot> ---> - <para> - 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 - <ulink url='http://labs.o-hand.com/sources/anjuta-plugin-sdk/'>OpenedHand labs</ulink> 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 <ulink url='http://git.pokylinux.org/cgit.cgi/anjuta-poky/'/>. - </para> - <para> - See the README file contained in the project for more information on dependencies and building - the plugin. It's recommended you enable the experimental gdb integration by passing configure the - --enable-gdb-integration switch. - </para> - - <section id="platdev-appdev-external-anjuta-setup"> - <title>Setting up the Anjuta plugin</title> - - <para>Extract the tarball for the toolchain into / as root. The - toolchain will be installed into - <filename class="directory">/usr/local/poky</filename>.</para> - - <para>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.</para> - - <para>To activate the plugin go to - <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>, - then choose <guilabel>General</guilabel> from the left hand side. Choose the - Installed plugins tab, scroll down to <guilabel>Poky - SDK</guilabel> and check the - box. The plugin is now activated but first it must be - configured.</para> - </section> - |