Overview

This document describes the program ttc, which is a tool for developing Linux for embedded systems.

ttc is intended to be used in a host/target development
configuration, where one machine is the development host where software
is configured and built, and one or more machines are targets where
software is executed. This is the most common configuration for
embedded systems programming. The ttc program is run
on the host system in order to build software and interact with
target machines in a common way.

The ttc program can be run interactively, or as part of an automated
session. The purpose of target is to make it so that the same commands
can be used to build software and manipulate different target machines, independent of
differences in the configuration and setup of the machines. Certain details of
operation are hidden from the user by the ttc
command. This makes it possible to perform the same operations on different target
boards, using the same set of ttc commands.

When the ttc program runs, it reads the configuration file "/etc/ttc.conf".
Usually, it looks up the target to act upon (which is specified either on the command line
or in the environment), then sets up the environment for the desired sub-command.
(The set of supported sub-commands is listed below in the section "Commands".)
Finally, using the attributes specified in the configuration file, ttc
executes the specified sub-command.

The different operations (or sub-commands) of ttc are intended to support
the following major development activities related to a target:

retrieving kernel source

patching the kernel

configuring the kernel for the target, including both:

getting a default configuration for the target

modifying individual configuration options

building the kernel

installing the kernel on the target

rebooting the target machine

accessing the console for the target

copying files to and from the target

Note that there is NOT a one-to-one correspondence between the ttc
sub-commands and the activities listed above. This is because once the
environment is set up it is possible to perform some of these
activities in a target-independent way using normal Linux commands
(like "make" or "patch").

In reality, ttc is a rather thin wrapper program which
sets up the environment and performs some common operations.
The bulk of the "intelligence" (how to do the actual operations)
is contained in the configuration file in the form of Unix shell
commands.

In order to use ttc on your system, you need to install the
software and edit the configuration file to match your host/target
setup. You may also need to install various helper scripts, referenced
in your ttc.conf file, in your PATH.

Theory of operation

The most important aspect of ttc is that it hides certain
operational details from the user, so that common commands can be
used to perform operations related to an embedded development board.

The things that ttc hides, include things such as:

the location and name of the cross-compiler (and other toolchain programs)

the version and location of the Linux kernel source code

the menu location of kernel configuration options

the method of installing the kernel on the target board

the method of rebooting the target board

the method of installing files to the file system of the target

These things must be set up on the host machine, and then the
ttc configuration file must be written to take into account
the specific settings for each target connected to the host.

Downloading 'ttc'

Download the tarball from one of the following links and follow the instructions
in the README (and in this document).

Installing 'ttc'

Copy ttc to /usr/local/bin. If you want to use
any of the provided helper scripts on your system (ssh_exec, telnet_exec, powerswitch-cycle), you
should put them somewhere on your search PATH. /usr/local/bin would be a good
place to copy them to.

Configuring 'ttc'

In order to use 'ttc', you first need to set up the /etc/ttc.conf configuration file
for the targets attached to your host machine. This is usually a relatively easy thing
to do, but may require special hardware or software to provide the services
that 'ttc' needs to access the board.

The syntax of the configuration file, and a description of the required contents, is in
Appendix A. Also, a sample configuration file is provided, with definitions for several
targets.

Using 'ttc'

You can use 'ttc' interactively from the Linux command line, or you can
use it by running an automated test (which invokes target to perform various
parts of the test.)

Commands

Command overview

Here is the list of sub-commands available for user with the target command.

Command

Operation

Notes

console

Run a program to access the target console.

.

cp

Copy files to or from the target.

.

get_config

Install kernel config for target in the $KBUILD_OUTPUT directory

assumes the current directory is top kernel source dir.

get_kernel

Install kernel sources for target in the $KERNEL_SRC directory

.

help

Show this online help.

.

info

Show information about a target.

.

kbuild

Build kernel from source.

assumes the current directory is the top kernel source dir.

kinstall

Install kernel for use on target.

assumes the current directory is the top kernel source dir.

list

Show a list of available targets.

.

login

Run a program to perform a network login on the target.

.

reboot

Reboot (power on and off) target board.

.

release

Release a reservation of a target.

.

reserve

Reserve a target for use.

.

reset

Reset target board.

.

rm

Remove files from the target.

.

run

Run a command on the target, collecting it's output

.

set_config

Set an individual config option

assumes the current directory is top kernel source dir

setenv

Starts shell with environment for performing build and other operations

.

status

Show status of target, including reservations.

not implemented yet (currently only shows reservation, but not board status)

vars

Show information about environment vars used by 'ttc'

.

version

Show version information and exit.

.

wait_for

Wait for a condition to be true.

command is executed on host (not on the target)

Use cases

Example 1: build and install a kernel and log on to the target to use it

A normal sequence of operations for an interactive user of ttc would be:

get a list of targets connected to this host

select a target to work on, and set up the environment for it

get the kernel sources for a build

(optionally) apply patches to the kernel sources

get a (default) kernel configuration for this target

set specific configuration options

build the kernel, and install it

reboot the target with the new kernel

(optionally) put additional files on the target

access the target console and do work

Here are the ttc commands one would use to accomplish this:

get a list of targets connected to this host

$ ttc list
Targets on this host:
ebony
innovator
nut
osk
test

select a target to work on, and set up environment for it

$ ttc ebony setenv

get the kernel sources for a build

$ ttc get_kernel -o linux-test
$ cd linux-test

(optionally) apply patches to the kernel sources

$ patch -p1 <../printk-times.patch

get a default kernel configuration for this target

$ ttc get_config

set specific configuration options

$ ttc set_config CONFIG_PRINTK_TIME==y

build the kernel, and install it

$ ttc kbuild
$ ttc kinstall

reboot the target with the new kernel

(either one of: On the target board, type "reboot":

$ reboot

or from the host, use:

$ ttc reset

(optionally) put additional files on the target

$ ttc cp foo bar target:/tmp
$ ttc cp test.sh target_bin:

login to the console and do some work

$ ttc console
<do interactive work on the target>

Commands

console

Runs a program to access the target console.

Usage: ttc [<target>] console

A program is run to provide interactive access to the target
console. It is not possible to predict what program will be
used. Often it is minicom, talking to a serial console
on the target. But the access program could be something else,
so no assumptions should be made. This command is not intended
to support automated access to the target console. Use
'ttc run' for that.

cp

Copy files to or from the target.

Usage: ttc [<target>] cp <src1> [<src2> ...] <dest>

The last path specified determines the direction of the copy.
Use the prefix "target:" to specify a filepath
on the target. "target_bin:" can be used to put a file on the target
in a directory on the PATH.

Ex: ttc cp test_data test_data2 target:/tmp

Ex: ttc cp test.sh target_bin:

get_config

Install kernel config for target in the $KBUILD_OUTPUT directory

Usage: ttc [<target>] get_config [-o <otherdir>]

Use -o to specify an alternate KBUILD_OUTPUT directory (default is '.')
Assumes the current directory is the top kernel source dir.

get_kernel

Install kernel sources for target in the $KERNEL_SRC directory

Usage: ttc [<target>] get_kernel [-o <outputdir>]

Use -o to specify a specific output kernel source directory.
The default output directory, if none is specified, is 'linux'.

help

Show the online help.

Usage: ttc help [<command>]

If a command is specified, show help Release a reservation of a target.and usage information for that command.

info

Show information about a target.

Usage ttc [<target>] info [-v] [-n <attr>]

Show information about a target. The '-v' (verbose) option will show all the
attributes for the target (from the configuration file). Use the '-n' option
to display the value of a single attribute, <attr>.

kinstall

Install kernel for use on target.

Usage: ttc [<target>] kinstall

Assumes the current directory is the top kernel source directory.

list

Show a list of available targets.

Usage: ttc list [-q]

Use -q for "quiet" mode. This suppresses extraneous output. The resulting
list can be parsed more easily by other programs.

login

Run a program to perform a network login on the target.

Usage: ttc [<target>] login

reset

Reset target board.

Usage: ttc [<target>] login

rm

Remove files from the target.

Usage: ttc [<target>] rm <file1> [<file2>...]

run

Run a command on the target, and return it's output.

Usage: ttc [<target>] run "command <args>"

set_config

Set one or more individual config options

Usage: ttc [<target>] set_config [-o <outputdir>] <option-def> ...

Use -o to specify a non-default KBUILD_OUTPUT directory. (The default is '.'
if none is specified in the environment or the target.conf file.)

Multiple <option-defs> may be specified with one command. Each
<option-def> has the syntax: <option-name><operation><value>.i
Operations are: '=' for assignment, and '+=' for a string append.
Boolean or tristate values should be one of "y", "n", and "n".
String values must be enclosed in quotes, which usually requires shell
escaping of the quote characters (see below).

A backup is made of the .config file.

Examples:

ttc set_config CONFIG_FOO=y

ttc set_config CONFIG_BAR=n CONFIG_BAZ=1234

ttc set_config "CONFIG_STR=\"foo bar\""

ttc set_config "CONFIG_STR+=\" quiet\""

Assumes the current directory is the top kernel source dir.

setenv

Prepare environment for building for the target

Usage: ttc [<target>] setenv [-o >file]

This command starts a new shell, with an environment that is
prepared for building for the target. That is, things like
KBUILD_OUTPUT, CROSS_COMPILE, and ARCH are set in the environment,
and PATH has been adjusted to include the appropriate toolchain
directory.

When -o is used, no new sub-shell is started. Rather,
-o causes target to output the required environment variables
as a series of shell export statements. These can be
'sourced' into the current shell rather than starting a new
sub-shell.

Ex: ttc ebony setenv -o >foo ; source foo

status

Show status of target, including reservations.

Usage: ttc [<target>] status

This command shows the the status of the indicated target.
The full command for showing status is not implemented yet. Currently, this command shows the reservation
status of the target, but not any online/network/booted status for the target board.

version

Show version information and exit.

Usage: ttc version

wait_for

Wait for a condition to be true.

Usage: ttc [<target>] wait_for [-i <interval>] [-t <timeout>] <command>
The command is run periodically until it returns 0. By default,
the interval between executing the command is 5 seconds.
Use -i to specify a different interval, and -t to specify a
maximum time to wait. Both are expressed in seconds.

Ex: ttc wait_for -i 2 -t 100 "test -f /target/ebony/tmp/outfile"

This will check every two seconds to see if /target/ebony/tmp/outfile exists,
waiting no longer than 100 seconds total. The exit code from
of 'ttc' is the exit code of the last invocation of the
command (0 on success).

Note that this command operates on the host. The above example would
be most useful for an 'ebony' target with an NFS-mounted root filesystem
that had "/tmp" on the target mapped to "/target/ebony/tmp" on the host.
If you need to run a command on the target, you can use 'ttc run' for
that. Some similar to the above, but running a command on the target
to check for the presence of a file would be:

Ex: ttc wait_for -i 2 -t 100 "ttc run \"test -f /tmp/outfile\""

Automated use of 'ttc'

interactive vs. automated use

Some tricks for automated use:

use the -o option with "ttc setenv" to output the environment variables to a file, then source that file in the current environment

This solves the problem of setting environment variables in the current shell, rather than in a sub-shell started via "ttc".
Here's a line which does this:
ttc foo setenv -o >tmp ; source tmp ; rm tmp ; make $kimage

Appendix A: Configuration file specification

The configuration file for ttc is named "ttc.conf", and
is located in the /etc directory.

This file contains a list of the targets attached to this host, and their
attributes. An attribute can be a static data value, such as the name of the target,
its description, or its IP address. Or an attribute can be a list of one or more commands
that perform an operation related to the target.

The file contains a list of name-value pairs. It supports single-line and multi-line
values. A single-line name-value pair has the syntax:

name==value

A multi-line name-value pair has the syntax:

name=="""first line
second line
etc."""

In other words, three double-quotes are used to denote the start and end of
a multi-line value.

Lines starting with a '#' are comments.

The file is divided into sections, one for each target described. Each section
begins with a target declaration, of the form: "target==<name>". This
line specifies the end of the previous section (if any) and the start of a
new section. The attributes that follow this line in the file are associated
with the indicated target, up to the next target declaration line.

Some values are sequences of shell script commands, which are used to
implement a single ttc sub-command.
By convention, the names of an attribute which implement a command
ends with "_cmd".

If an attribute name is all upper-case, this denotes
a value that is placed in the environment. (There are, however, some
environment variable values which are NOT denoted by an
upper-case attribute name).

Configuration attributes summary

Supported attributes are:

Attribute Name

Meaning of value

Notes

target

Short (one-word) name of the target

.

description

A description of the target board. Usually multi-line

.

TOOL_PATH

Path where toolchain tools are located. This appended to the PATH env. variable

.

ARCH

Architecture specifier for the kernel build (eg. arm, ppc, i386)

.

CROSS_COMPILE

Toolchain prefix used with kernel builds (eg. arm-sony-linux- )

.

INSTALL_PATH

Place where kernel is installed

.

KERNEL_SRC

Default name to use for kernel source directory

.

KBUILD_OUTPUT

Default directory for kernel build output

.

kimage

Name of the kernel image file (eg. bzImage, uImage)

.

kinstall_cmd

Command(s) to install the kernel image. (Assumes that the current working dir is $KERNEL_SRC)