Test Lab Board Suppliers Guide

Table Of Contents:

Introduction
This document describes the features required and procedures to follow to put a board in the CELF open test lab (see Open Test Lab). This document is primarily targeted at semi-conductor vendors or product vendors who wish to add a board to the lab.

The requirements section describes:
 * what is required of the firmware
 * what is required on the host
 * what is required on the target
 * hardware required to control reset and power on the target

The procedures section describes: [ more stuff, see below]

Overview
Each target board in the lab will be connected to a single Linux host, which will be an x86 Linux desktop machine. A single host may connect to more than one target. On the host will be installed a complete Linux development environment, as well as cross-compilers, tools, and any special programs required to access and control the target board.

Because the lab uses the boards in an automated fashion it is required that the host be able to perform a number of control operations via (unattended) Linux command line programs. This includes:
 * compiling and installing a kernel for use on the board,
 * installing a new root filesystem for use on the board,
 * compiling and installing user-space programs for use on the board

Preferred configuration (1)
The preferred configuration for testing most features of the board will be as follows:
 * target connected to host via ethernet
 * target connected to host via serial line
 * kernel loaded from host via tftp
 * root file system mounted from host via NFS
 * root account with no password
 * telnetd running on target, with root account accessible
 * ability to reboot target from target command line
 * ability to reset target from host command line
 * ability to power cycle target from host command line
 * Linux console available over serial line connected to host

Desired alternate configuration (2)
Some tests results will be better if the kernel and root filesystem more closely match those of a shipping product. For these tests, the following configuration is highly desirable: [ same as above, except:]
 * kernel loaded from local storage (either flash or rotating media)
 * root file system accessed/loaded from local storage
 * mechanism for file transfer to/from target

This will require programs on the host to install the kernel and root filesystem to target-local storage. This can be accomplished via any one of: interaction with a known-good Linux system operating on target, serial output to target firmware, or interaction with board via secondary hardware (such as a jtag module, if one is provided to the lab). However, in any case, the control of these operations needs to be automatable, and needs to be operable in spite of previous Linux kernel boot failures. (That is, the control program on the host needs to be able to reboot the machine and re-install the kernel via good-kernel, firmware or hardware (even if the last Linux kernel on the hardware was dead), WITHOUT manual user intervention (such as changing board pins).)

Requirements
The following items are needed for each board: the host Linux command line. http://tree.celinuxforum.org/CelfPubWiki/TargetSwitchControlFromParallelPort
 * cross-compile toolchains
 * gcc is required
 * kernel source code (and a location to get updates)
 * default kernel configuration for the target board
 * libraries and headers for user-space applications
 * glibc is required
 * uclibc as an alternate option is desirable but not required
 * a binary distribution (user-space libraries and programs) for the board
 * glibc is required
 * busybox is required
 * uclibc is desirable but optional
 * mechanism to install a kernel via host command line
 * mechanism to install a root filesystem via host command line
 * mechanism to copy a program to the target file system
 * mechanism to copy a program from the target filesystem to the host
 * mechanism to reset and/or reboot the machine from
 * Sony has used a very simple control module connected to the parallel port of the host machine and the reset switch and power switch pins on the target board, with information available at:
 * anything similar would be fine.
 * if absolutely required, we can install a console switcher (which allows for power cycling via a telnet command), but I'd prefer something less drastic than cutting and restoring wall power to the board.

Procedures
This section documents the following procedures related to board management in the CELF Open Test Lab:
 * pre-testing a board in a lab configuration
 * adding a board to the lab
 * maintaining Linux software for the board in the lab
 * providing hardware support for the board in the lab
 * removing a board from the lab

Board pre-test
The board supplier should pre-test their configuration of the board by running a sample test at their own facility, prior to sending the board to the CELF open test lab facility.

This can be done by installing the necessary software on the host machine and target machines, connecting the machines together, and running the sample test. If the sample test is successful, then the board can be sent to the lab with greater assurance that it can be integrated without problems.

Here is an outline of the steps involved: (this can be as simple as putting the kernel source in a tar file)
 * 1) download the 'target' program (with sample test: 'preset-test.py')
 * 2) install the cross toolchains
 * 3) install the kernel source
 * it is preferable that the kernel source be in the format: baseline (kernel.org) source + patches
 * 1) install the root filesystem
 * 2) install (or create) auxiliary programs for resetting and rebooting the target
 * 3) install the 'target' program
 * 4) configure the 'target' program by creating an appropriate '/etc/target.conf' file
 * 5) run preset-test.py

Adding a board to the lab
Here are the steps for adding a new board to the CELF open test lab: please send it to:
 * perform the board pre-test
 * package the software for lab
 * create tar files for toolchains
 * create patch sets for kernel
 * create tar file with auxiliary programs
 * send the software to the lab:
 * testlabmanager@tree.celinuxforum.org
 * [or upload it to the lab web site - when web site is active - not yet]
 * ship the board
 * San Jose lab address:

attn: Tim Bird Sony Electronics 3300 Zanker Road, SJ3B6 San Jose, CA, 95134

or directly to the lab at:

CE Linux Forum Lab Manager Office #171 50 Airport Parkway San Jose, CA 95110-1011

Since the lab is unmanned most days, please notify the lab manager when you sending hardware directly to the lab, so we can know to go in to the office to receive it.


 * Tokyo lab address:

[ need Tokyo lab address here ]


 * provide a board support contact

Updating board-specific software the lab
[describe updating kernel source or patches here.]

Providing hardware support to the lab
Each board supplier should provide contact information for a person from their organization that can provide support assistance for their target board in the lab. This person will be contacted by the lab manager of the lab where their board is located, in the event that there is an unrecoverable hardware failure of the board.

Removing a board from the lab

 * contact the lab manager
 * provide shipping information