View source

= How to add a new platform to foonas-em =

== About ==

This developer targeted document outlines the changes required to add foonas-em support to your device. Note that this guide is work in progress and currently does not explain all the steps required to add a new platform at this time. This guide assumes that you have already installed the OpenEmbedded based development tools from the foonas subversion repository and have a basic knowledge of its layout and function.

== Document your platform ==

Go to [http://nas-central.org nas-central] and document as much hardware and bootloader configuration information as possible.

== Create a machine config file ==

OpenEmbedded needs to know a bit about the platform it is building a distribution for. This information is provided by a machine configuration file in conf/machine/, the name of this file also provides the machine name for your device as far as OpenEmbedded is concerned. Have a look at some of the files in this directory for platforms supported by foonas-em as a starting point. 

This is an example of a machine config for the PowerPC based QNAP TurboStation TS-101:

 #@TYPE: Machine configuration
 #@Name: QNAP Turbostation TS-101
 #@DESCRIPTION: Generic Machine configuration for QNAP TS-101
 
 TARGET_ARCH = "powerpc"
 TARGET_FPU = "hard"
 
 PACKAGE_EXTRA_ARCHS = "ppc ppc603e"
 
 MACHINE_FEATURES                = "kernel26 usbhost ext2 pci uboot"
 MACHINE_FEATURES_foonas-em      = "kernel26"
 MACHINE_FEATURES_foonas-iscsi   = "kernel26"
 MACHINE_TASK_PROVIDER           = "task-base"
 MACHINE_EXTRA_RDEPENDS          = "uboot-utils"
 
 USE_DEVFS = "0"
 
 PREFERRED_PROVIDER_virtual/kernel = "linux-ts101"
 PREFERRED_VERSION_u-boot = "1.2.0"
 PREFERRED_VERSION_linux-ts101 = "2.6.20.2"
 
 #don't try to access tty1
 USE_VT = "0"
 
 IMAGE_DEVICE_TABLES = "files/device_table-slugos.txt"
 IMAGE_FSTYPES                   = "tar.gz"
 IMAGE_FSTYPES_foonas-em         = "cpio.gz"
 IMAGE_FSTYPES_foonas-iscsi      = "cpio.gz"
 
 # Is this right?
 SERIAL_CONSOLE = "ttyS1 115200"
 
 require conf/machine/include/tune-ppc603e.conf
 
 BB_EMMODE = "small"
 UBOOT_MACHINE = "qnap_config"
 INHERIT += "ts101-image"

For machines of other architectures it is a good idea to copy a configuration from a device with some kind of foonas-em support - this one is for PowerPC 603e based devices and so will not work on MIPS or ARM based platforms, but there are working examples for each of these architectures in svn.

If you copy an existing machine configuration remove any MACHINE_EXTRA_RDEPENDS variable specified there. These dependency packages tend to be machine specific daemons for controlling AVR/micro-controllers in the device for LED/button/etc support and will most likely not work at all on your platform and possibly cause you some strange issues.

Look at other platforms similar to your device that share similar configuration items. For example, all supported Orion based platforms use a generic include in conf/machine/include/orion.conf, taking some of the work away from configuration creation and leading to less duplication.

== Create platform specific classes ==

Create a new file in /stuff/org.openembedded.dev/classes/[platform]-image.bbclass with this minimun content:

 [platform]_pre_image() {
 :
 }
 
 [platform]_post_image() {
 :
 }
 
 [platform]_post_image_ramdisk() {
 :
 }

Change [platform] for your platform name.

== Kernel requirements and configuration ==


Open the file /stuff/org.openembedded.dev/packages/linux/linux-orion_*.bb and add your platform in line:
 
 COMPATIBLE_MACHINE = "(dns323|mv2120|kuropro|lspro|ts109|ts209|ts409...



== U-Boot user space utilities configuration ==

If your device uses the U-Boot boot-loader it is necessary to provide a machine specific configuration file containing information on where to find where the U-Boot environment is stored in flash. Currently this involves adding a platform specific directory in packages/uboot/uboot-utils-1.1.2/ and a fw_env.config file containing the relevant configuration items.

More information on this configuration file can be found on the Denx website [http://www.denx.de/wiki/view/DULG/HowCanIAccessUBootEnvironmentVariablesInLinux here].

Ultimately the OS installers for foonas-em for your device will use this to configure U-Boot as part of the installation process so that your device automatically boots into any operating system you might install via foonas-em.

Also note that the package uboot-utils should be included in your machine configuration file (created in step 1) or another file included inside this config in the MACHINE_EXTRA_RDEPENDS variable:

 MACHINE_EXTRA_RDEPENDS          = "u-boot-utils"

== Add a machine specific icon ==

All devices in foonas-em have a device specific image. This is in the packages/openlink-machine-pics package and is used by all of the foonas distributions per supported device. This file should be a JPEG image called machine.jpg 48 x 48 pixels and live in files/platform-name under the openlink-machine-pics package directory. 

Please ensure the icon image has a white background, fills the area as well as possible and includes the whole device in the picture. Remember to bump the package PR after you add your image so the auto-builder doesn't use the unknown pic that may have possibly been compiled for your device already.

== Configure foonas-em appropriately for flash size and device memory ==

=== Busybox Configuration ===

We provide  [[Foonas-em:BusyboxConfigs|three busybox configurations]] of different sizes for foonas-em - small, medium and large. You may select any one of these in your machine configuration file, for example:

 BB_EMMODE = "small"

The above command in org.openembedded.dev/conf/machine/blah.conf would set a small busybox size for platform blah.

== Ensure your device meets foonas-em support requirements ==

The following are requirements for a platform to be listed as supported:

* Must use a recent 2.6 kernel with no issues in our configuration
* Platform must have daemon to manage button presses and LEDs for shutdown/reboot
* Bootloader is able to be replaced/easily reconfigured to boot foonas-em, even if this is by serial
* Platform should ideally be maintained or it will lose support eventually
* Platform specific stuff is all under a compatible license
* A method of flashing/tftp-booting foonas-em should be provided in this wiki
[[Image:Foonas-em.png|right]]
[[Category:Foonas-em]]