Introduction

This specification describes the configuration and conventions used for a "Remote Board Access"
system. "Remote Board Access" (or RBA) is the name used to describe a configuration of
hardware and software which allows for an individual developer to build Linux software and test
it on a target machine (usually an embedded board), which is accessed remotely.

Related to this "access specification", is the definition of an automated test framework which
can be built upon it. Some aspects of this specification directly address the requirements
of such a framework. However, some aspects of this specification also support the activity of individual developers working interactively with embedded development boards.

This specification creates standards for two main activities:

building software for a target machine

accessing and controlling a target machine

Taming Variability in Embedded Configurations

The key idea of this specification is to create a uniform method of access to build tools,
software, and the board itself, for an embedded target board. A significant problem in the embedded space is the variety of configurations that are presented to a software developer for such boards. A large number of items in the configuration and setup of an embedded target board vary from board to board. This includes a such things as the bootloader, compiler (location, version and supported architecture), kernel version, kernel configuration, file system type, and methods of target access for software installation, console access, command invocation, file system access, etc.

It is very difficult for both a human engineer and an automated test system to deal with this large variety of factors. One of the primary purposes, then, of this specification is to create a model whereby these factors are masked and a uniform method is presented for building and installing software, and manipulating the target board.

Rationale

This specification is needed in order to:

to create a uniform method of building software and controlling a target board

to allow for automation of testing activities on a board

to eliminate or reduce the learning curve for using different boards

this specification deals with one area of interface (between a host and a target) that is part of the overall architecture of the CELF OpenTestLab

see TestLabArchitecture for more information.

Definitions

host

The machine used to control or access one or more target boards.

target

A development board which can be accessed remotely using the RBA system.

toolchain

The collection of programs used to create software for a target machine. This consists of the compiler (including preprocessor), assembler, linker and other programs used for manipulating source and machine code into a form usable on the target. This usually consists of software from the Linux packages for gcc, binutils, and glibc.

Use Cases - Interactive

basic remote board use

a developer wants to build a kernel, boot it on the target, and view the kernel bootup messages

also, the developer wants to log in to the new kernel, and run a variety of user space applications

Steps:

developer sets target-specific work environment

target setenv <target>

developer gets target-specific kernel source

target get_kernel

developer sets the kernel configuration

developer gets default kernel config for $TARGET

target get_config

or "make $TARGET_defconfig" should work

developer makes config modifications (by hand)

make menuconfig, or vi .config

developer builds the kernel

environment provides ARCH, CROSS_COMPILE, and kimage vars

make $kimage, or target kbuild

developer installs kernel on the target

target kinstall

developer gets a target console

target console

developer resets target board

target reset

developer logs into target board

(login on console) or target login

developer can now run commands interactively on the target

testing a kernel configuration

a developer wants to test a particular kernel configuration option on a target

developer needs a baseline configuration for that target, and a way to make modifications

alternatively, the developer needs a way to upload their own configuration to the host

Steps:

developer copies desired configuration file to RBA host

scp myconfig rbahost:/home/<user>/

developer logs into RBA host using ssh

developer sets target-specific work environment

target setenv <target>

developer gets target-specific kernel source

target get_kernel

developer sets the kernel configuration

developer uses default configuration with some modifications:

developer gets default kernel config for $TARGET

target get_config

or "make $TARGET_defconfig" should work

developer makes config modifications (by hand)

make menuconfig, or vi .config

OR developer uses their own configuration

cp /home/<user>/myconfig .

make oldconfig

developer builds the kernel

environment provides ARCH, CROSS_COMPILE, and kimage vars

make $kimage

developer locks target for use

developer installs kernel

target kinstall

developer gets a target console

target console

developer resets target board

target reset

developer logs into target board

(login on console) or target login

developer examines messages, runs tests, etc.

testing a new kernel patch

a developer wants to apply a patch to a target-specific kernel (to see if it applies) and run the new kernel on the target hardware (to see if the new feature works)

Steps:

developer copies desired configuration file to RBA host

scp myconfig rbahost:/home/<user>/

developer uploads a patch to the RBA host

scp foo.patch rbahost:/home/<user>/

developer logs into RBA host using ssh

developer sets target-specific work environment

target setenv <target>

developer gets target-specific kernel source

target get_kernel

developer applies patch to kernel source

patch -p1 /home/<user>/foo.patch

developer sets the kernel configuration

developer uses default configuration with some modifications:

developer gets default kernel config for $TARGET

target get_config

or "make $TARGET_defconfig" should work

developer makes config modifications (by hand)

make menuconfig, or vi .config

OR developer uses their own configuration

cp /home/<user>/myconfig .

make oldconfig

developer builds the kernel

environment provides ARCH, CROSS_COMPILE, and kimage vars

make $kimage

developer locks target for use

developer installs kernel

target kinstall

developer gets a target console

target console

developer resets target board

target reset

developer logs into target board

login on console) or target login

developer examines messages, runs tests, etc.

testing user-space software

a developer wants to test a user-space program on the target

developer needs target-specific kernel running on target

developer needs to be able to upload user-space program to RBA host

developer needs build environment for user-space program

developer needs a way to install program on the target

should be able to put program in already-available root filesystem

developer needs a way to run program on target, and gather results

testing a new baseline kernel

A target maintainer may want acquire target-specific patches, and apply to a new kernel.org baseline

this is to see which target-specific patches do not apply cleanly any more.

target-specific patches should be separated from baseline kernel

target-specific kernel source should be available as baseline kernel + patches

Steps (summary):

login to rba host

get kernel

get target (old/existing) baseline

install new baseline

diff old-baseline kernel >target-patch

patch new-baseline <target-patch

report problems

compile

report problems

Use Cases - Automated

automated unit test

A developer wants to test a particular feature of the kernel or default software, in a unit test. A series of tests are to be performed, without user interaction.

need to put test script on target (target cp)

need to initiate test on target (target reset, target run)

need to handle watchdogging the program/target

need external reset control (external power control is also desirable)

need to get results from target

need to set a config option

need to patch the kernel

need to compile, install, start the kernel

automated patch test

a developer wants to test that a patch can be compiled for a number of different architectures and platforms

the developer submits the patch to a patch server

the patch server iterates through a list of registered RBA sites, for each site:

the patch server obtains the kernel source for the target (on the RBA host, under the patch server account)

the patch server uploads the patch

the patch server compiles the kernel

=== automated regression test

lab software checks for update to linux kernel (or other software)

when new version is detected, code is downloaded and test is run automatically

run test suite on a non-lab node

developer accesses test server and selects a test run download and run on their local host/target combination

pre-requisite - user verifies that their host/target combination interoperates with the RBA system

user downloads an interoperability test and runs it

web server provides list of available tests

client can download and run a test from the server

test programs for target must be packaged somehow [need specification for format]

Supported operations (tasks)

verify that the target machine is available for use (target status)

reserve target for use (target acquire [timeout])

unreserve target (target release)

build kernel

obtain kernel source for target (target get_kernel)

set up build environment for kernel (target setenv)

get default kernel configuration (target get_config)

build root filesystem for target

build program for target

upload source for program for target (scp)

set up build environment for programs (target setup_build_environment)

Specifications

Machine configuration

Model: an RBA site consists of a single host, connected to one or more target machines.

A host has sufficient software to perform a number of development activities
relative to its target machines. Specifically, the host MUST provide
software and mechanisms to:

acquire, build and install the Linux kernel software for the target

reset and power-cycle the target

access the boot console of the target (for interactive use)

copy files to and from the target

execute commands on the target

A lab host, in practice, is expected to be a normal PC machine running the Linux operating system. It should have sufficient performance and disk space to build the Linux kernel, and to host a number of copies of the Linux kernel source tree (and other source and binaries used for both host and target operation.) A minimum of 10 gigs of free hard disk space is recommenced on a lab host.

All remote board access operations must be available from the Linux command line, and runnable in a batch mode (without interaction).

Required/Recommended software for RBA host

toolchains - minimally capable of building a Linux kernel

toolchain source (for compliance with GPL)

toolchain binaries

kernel source

default config for target

"target" command, with following sub-commands:

target name is specified on command line

optional RBA_TARGET environment variable can specify the target being used

References

Related work

Device Software Development Platform - proposal for target development model and system for use with Eclipse. See:
[1]

Remaining Issues

[this is a placeholder section for listing issues while the spec is under development.
It should be empty when the spec is completed (or the issues should be deferable to
a subsequent version of the spec).]