Difference between revisions of "Target Program Usage Guide"

From eLinux.org
Jump to: navigation, search
(Example 1: build and install a kernel and log on to the target to use it =)
(Configuration attribute details)
 
(4 intermediate revisions by the same user not shown)
Line 246: Line 246:
  
 
==== Commands ====
 
==== Commands ====
====== console ======
+
===== console =====
 
Runs a program to access the target console.
 
Runs a program to access the target console.
  
Line 259: Line 259:
 
'target run' for that.
 
'target run' for that.
  
====== cp ======
+
===== cp =====
 
Copy files to or from the target.
 
Copy files to or from the target.
  
Line 272: Line 272:
 
Ex: target cp test.sh target_bin:
 
Ex: target cp test.sh target_bin:
  
====== get_config ======
+
===== get_config =====
 
Install kernel config for target in the $KBUILD_OUTPUT directory
 
Install kernel config for target in the $KBUILD_OUTPUT directory
  
Line 280: Line 280:
 
Assumes the current directory is the top kernel source dir.
 
Assumes the current directory is the top kernel source dir.
  
====== get_kernel ======
+
===== get_kernel =====
 
Install kernel sources for target in the $KERNEL_SRC directory
 
Install kernel sources for target in the $KERNEL_SRC directory
  
Line 288: Line 288:
 
The default output directory, if none is specified, is 'linux'.
 
The default output directory, if none is specified, is 'linux'.
  
====== help ======
+
===== help =====
 
Show the online help.
 
Show the online help.
  
Line 295: Line 295:
 
If a command is specified, show help and usage information for that command.
 
If a command is specified, show help and usage information for that command.
  
====== info ======
+
===== info =====
 
Show information about a target.
 
Show information about a target.
  
Line 304: Line 304:
 
to display the value of a single attribute, <attr>.
 
to display the value of a single attribute, <attr>.
  
====== kinstall ======
+
===== kinstall =====
 
Install kernel for use on target.
 
Install kernel for use on target.
  
Line 311: Line 311:
 
Assumes the current directory is the top kernel source directory.
 
Assumes the current directory is the top kernel source directory.
  
====== list ======
+
===== list =====
 
Show a list of available targets.
 
Show a list of available targets.
  
Line 319: Line 319:
 
list can be parsed more easily by other programs.
 
list can be parsed more easily by other programs.
  
====== login ======
+
===== login =====
 
Run a program to perform a network login on the target.
 
Run a program to perform a network login on the target.
  
 
Usage: target [<target>] login
 
Usage: target [<target>] login
  
====== reset ======
+
===== reset =====
 
Reset target board.
 
Reset target board.
  
 
Usage: target [<target>] login
 
Usage: target [<target>] login
  
====== rm ======
+
===== rm =====
 
Remove files from the target.
 
Remove files from the target.
  
 
Usage: target [<target>] rm <file1> [<file2>...]
 
Usage: target [<target>] rm <file1> [<file2>...]
  
====== run ======
+
===== run =====
 
Run a command on the target, and return it's output.
 
Run a command on the target, and return it's output.
  
 
Usage: target [<target>] run "command <args>"
 
Usage: target [<target>] run "command <args>"
  
====== set_config ======
+
===== set_config =====
 
Set one or more individual config options
 
Set one or more individual config options
  
Line 365: Line 365:
 
Assumes the current directory is the top kernel source dir.
 
Assumes the current directory is the top kernel source dir.
  
====== setenv ======
+
===== setenv =====
 
Prepare environment for building for the target
 
Prepare environment for building for the target
  
Line 384: Line 384:
 
(Ex: target ebony setenv -o >foo ; source foo)
 
(Ex: target ebony setenv -o >foo ; source foo)
 
   
 
   
====== status ======
+
===== status =====
 
Show status of target, including reservations.
 
Show status of target, including reservations.
  
Line 391: Line 391:
 
(not implemented yet)
 
(not implemented yet)
  
====== version ======
+
===== version =====
 
Show version information and exit.
 
Show version information and exit.
  
 
Usage: target version
 
Usage: target version
  
====== wait_for ======
+
===== wait_for =====
 
Wait for a condition to be true.
 
Wait for a condition to be true.
  
 
Usage: target [<target>] wait_for [-i <interval>] [-t <timeout>] <command>
 
Usage: target [<target>] wait_for [-i <interval>] [-t <timeout>] <command>
The command is run periodically until it returns 0.  By default,
+
The command is run periodically until it returns 0.  By default,
the interval between executing the command is 5 seconds.
+
the interval between executing the command is 5 seconds.
Use -i to specify a different interval, and -t to specify a
+
Use -i to specify a different interval, and -t to specify a
maximum time to wait.  Both are expressed in seconds.
+
maximum time to wait.  Both are expressed in seconds.
  
  ex: target wait_for -i 2 -t 100 "test -f /tmp/outfile"
+
ex: target wait_for -i 2 -t 100 "test -f /tmp/outfile"
  
This will check every two seconds to see if /tmp/outfile exists,
+
This will check every two seconds to see if /tmp/outfile exists,
waiting no longer than 100 seconds total. The exit code from
+
waiting no longer than 100 seconds total. The exit code from
of 'target' is the exit code of the last invocation of the
+
of 'target' is the exit code of the last invocation of the
command (0 on success).
+
command (0 on success).
  
 
(Works on host right now, not target.)
 
(Works on host right now, not target.)
 
  
 
== Automated use of 'target' ==
 
== Automated use of 'target' ==
 
==== interactive vs. automated use ====
 
==== interactive vs. automated use ====
 
Some tricks for automated use:
 
Some tricks for automated use:
* use the -o option with "target setenv" to output the environment variables to a file, then source that file in the current environment
+
*use the -o option with "target 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 "target".
+
This solves the problem of setting environment variables in the current shell, rather than in a sub-shell started via "target".
  Here's a line which does this:
+
Here's a line which does this:
 
<code>
 
<code>
 
target foo setenv -o >tmp ; source tmp ; rm tmp ; make $kimage
 
target foo setenv -o >tmp ; source tmp ; rm tmp ; make $kimage
Line 436: Line 435:
 
The file contains a list of name-value pairs.  It supports single-line and multi-line
 
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:
 
values.  A single-line name-value pair has the syntax:
<code>
+
<pre>
 
name==value
 
name==value
</code>
+
</pre>
 +
 
 
A multi-line name-value pair has the syntax:
 
A multi-line name-value pair has the syntax:
<code>
+
<pre>
 
name=="""first line
 
name=="""first line
 
second line
 
second line
 
etc."""
 
etc."""
</code>
+
</pre>
 +
 
 
In other words, three double-quotes are used to denote the start and end of
 
In other words, three double-quotes are used to denote the start and end of
 
a multi-line value.
 
a multi-line value.
Line 467: Line 468:
  
 
==== Configuration attributes summary ====
 
==== Configuration attributes summary ====
 +
 
Supported attributes are:
 
Supported attributes are:
||<rowbgcolor=="#88ffbb">Attribute Name||Meaning of value||
+
 
||target        ||Short (one-word) name of the target||
+
{| border="1" cellpadding="5" cellspacing="0" align="center"
||description  ||A description of the target board.  Usually multi-line||
+
!style="background:#80cccc;"|'''Attribute Name'''
||TOOL_PATH    ||Path where toolchain tools are located.  This appended to the PATH env. variable||
+
!style="background:#80cccc;"|'''Meaning of value'''
||ARCH          ||Architecture specifier for the kernel build (eg. arm, ppc, i386)||
+
!style="background:#80cccc;"|'''Notes'''
||CROSS_COMPILE ||Toolchain prefix used with kernel builds (eg. arm-sony-linux- )||
+
|-
||INSTALL_PATH  ||Place where kernel is installed||
+
|target        ||Short (one-word) name of the target||.
||KERNEL_SRC    ||Default name to use for kernel source directory||
+
|-
||KBUILD_OUTPUT ||Default directory for kernel build output||
+
|description  ||A description of the target board.  Usually multi-line||.
||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)||
+
|TOOL_PATH    ||Path where toolchain tools are located.  This appended to the PATH env. variable||.
||get_config_cmd||Command(s) to put a default kernel configuration file (.config) in $KBUILD_OUTPUT||
+
|-
||get_kernel_cmd||Command(s) to put the kernel source code in $KERNEL_SRC||
+
|ARCH          ||Architecture specifier for the kernel build (eg. arm, ppc, i386)||.
||copy_to_cmd  ||Command(s) to copy files from host to target||
+
|-
||copy_from_cmd ||Command(s) to copy files from target to host||
+
|CROSS_COMPILE ||Toolchain prefix used with kernel builds (eg. arm-sony-linux- )||.
||rm_cmd        ||Command(s) to remove files from target||
+
|-
||ipaddr        ||Target IP address||
+
|INSTALL_PATH  ||Place where kernel is installed||.
||reset_cmd    ||Command(s) to reset the target, from the host||
+
|-
||console_cmd  ||Command(s) to start an interactive console for the target (usually minicom)||
+
|KERNEL_SRC    ||Default name to use for kernel source directory||.
||login_cmd    ||Command(s) to start an interactive login session with the target (usually telnet)||
+
|-
||target_bin    ||Directory on target where binary files are located||
+
|KBUILD_OUTPUT ||Default directory for kernel build output||.
||fsinstall_cmd ||Command(s) to install a root filesystem to the target||
+
|-
 +
|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)||.
 +
|-
 +
|get_config_cmd||Command(s) to put a default kernel configuration file (.config) in $KBUILD_OUTPUT||.
 +
|-
 +
|get_kernel_cmd||Command(s) to put the kernel source code in $KERNEL_SRC||.
 +
|-
 +
|copy_to_cmd  ||Command(s) to copy files from host to target||.
 +
|-
 +
|copy_from_cmd ||Command(s) to copy files from target to host||.
 +
|-
 +
|rm_cmd        ||Command(s) to remove files from target||.
 +
|-
 +
|ipaddr        ||Target IP address||.
 +
|-
 +
|reset_cmd    ||Command(s) to reset the target, from the host||.
 +
|-
 +
|console_cmd  ||Command(s) to start an interactive console for the target (usually minicom)||.
 +
|-
 +
|login_cmd    ||Command(s) to start an interactive login session with the target (usually telnet)||.
 +
|-
 +
|target_bin    ||Directory on target where binary files are located||.
 +
|-
 +
|fsinstall_cmd ||Command(s) to install a root filesystem to the target||.
 +
|}
  
 
==== Configuration Example ====
 
==== Configuration Example ====
 
Here is a sample:
 
Here is a sample:
<code>
+
 
 +
<pre>
 
# Some notes on syntax and conventions
 
# Some notes on syntax and conventions
 
# Attributes that end in "_cmd" are assumed to be shell
 
# Attributes that end in "_cmd" are assumed to be shell
Line 504: Line 533:
 
# The get_kernel_cmd should output the kernel source
 
# The get_kernel_cmd should output the kernel source
 
# to the directory specified by $KERNEL_SRC
 
# to the directory specified by $KERNEL_SRC
#======================================================================================================================
+
#======================================================
 
target==innovator
 
target==innovator
 
description=="""TI OMAP Innovator board, with:
 
description=="""TI OMAP Innovator board, with:
Line 531: Line 560:
 
rm_cmd==rm /target/inno-1/$dest
 
rm_cmd==rm /target/inno-1/$dest
  
#======================================================================================================================
+
#=================================================================================
  
 
target==osk
 
target==osk
Line 564: Line 593:
 
rm_cmd==rm /target/osk2/$dest
 
rm_cmd==rm /target/osk2/$dest
  
#======================================================================================================================
+
#==================================================================================================
 
target==nut
 
target==nut
 
description=="""Nut is an x86-based desktop computer, with:
 
description=="""Nut is an x86-based desktop computer, with:
Line 593: Line 622:
 
rm_cmd==rm /target/nut/$dest
 
rm_cmd==rm /target/nut/$dest
  
#======================================================================================================================
+
#=======================================================================================
 
target==ebony
 
target==ebony
 
description=="""Ebony (San Jose) is an IBM PowerPC development baord, with:
 
description=="""Ebony (San Jose) is an IBM PowerPC development baord, with:
Line 621: Line 650:
 
copy_from_cmd==cp /target/ebony$src $dest
 
copy_from_cmd==cp /target/ebony$src $dest
 
rm_cmd==rm -f /target/ebony/$dest
 
rm_cmd==rm -f /target/ebony/$dest
</code>
+
</pre>
  
 
==== Configuration attribute details ====
 
==== Configuration attribute details ====
 
This section lists each configuration attribute, and what its value should be.
 
This section lists each configuration attribute, and what its value should be.
  
target::: Short (one-word) name of the target
+
; target: Short (one-word) name of the target
description::: A description of the target board.  Usually this is a multi-line value.
+
; description: A description of the target board.  Usually this is a multi-line value.
TOOL_PATH::: Path where toolchain tools are located.  This appended to the PATH env. variable
+
; 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)
+
; ARCH: Architecture specifier for the kernel build (eg. arm, ppc, i386)
CROSS_COMPILE::: Toolchain prefix used with kernel builds (eg. arm-sony-linux- )
+
; CROSS_COMPILE: Toolchain prefix used with kernel builds (eg. arm-sony-linux- )
INSTALL_PATH::: Place where kernel is installed
+
; INSTALL_PATH: Place where kernel is installed
KERNEL_SRC::: Default name to use for kernel source directory
+
; KERNEL_SRC: Default name to use for kernel source directory
KBUILD_OUTPUT::: Default directory for kernel build output
+
; KBUILD_OUTPUT: Default directory for kernel build output
kimage::: Name of the kernel image file (eg. bzImage, uImage)
+
; 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)
+
; kinstall_cmd: Command(s) to install the kernel image.  (Assumes that the current working dir is $KERNEL_SRC)
get_config_cmd::: Command(s) to put a default kernel configuration file (.config) in $KBUILD_OUTPUT
+
; get_config_cmd: Command(s) to put a default kernel configuration file (.config) in $KBUILD_OUTPUT
get_kernel_cmd::: Command(s) to put the kernel source code in $KERNEL_SRC.
+
; get_kernel_cmd: Command(s) to put the kernel source code in $KERNEL_SRC.
copy_to_cmd::: Command(s) to copy files from host to target
+
; copy_to_cmd: Command(s) to copy files from host to target
copy_from_cmd::: Command(s) to copy files from target to host
+
; copy_from_cmd: Command(s) to copy files from target to host
rm_cmd::: Command(s) to remove files from target
+
; rm_cmd: Command(s) to remove files from target
ipaddr::: Target IP address
+
; ipaddr: Target IP address
reset_cmd::: Command(s) to reset the target, from the host
+
; reset_cmd: Command(s) to reset the target, from the host
console_cmd::: Command(s) to start an interactive console for the target (usually minicom)
+
; console_cmd: Command(s) to start an interactive console for the target (usually minicom)
login_cmd::: Command(s) to start an interactive login session with the target (usually telnet)
+
; login_cmd: Command(s) to start an interactive login session with the target (usually telnet)
target_bin::: Directory on target where binary files are located
+
; target_bin: Directory on target where binary files are located
fsinstall_cmd::: Command(s) to install a root filesystem to the target
+
; fsinstall_cmd: Command(s) to install a root filesystem to the target

Latest revision as of 16:50, 12 December 2006

Overview

This page describes the "target" program, which is used for performing operations on a target board.

This document describes the program target, which can be used as a tool in developing Linux for embedded systems.

Target 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 target program is run on the host system in order to build software and interact with target machines in a common way.

The target 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 target command. This makes it possible to perform the same operations on different target boards, using the same set of target commands.

When the target program runs, it reads the configuration file "/etc/target.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, target executes the specified sub-command.

The different operations (or sub-commands) of target 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 target 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, target 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 target on your system, you need to install the software and edit the configuration file to match your host/target setup.

Theory of operation

The most important aspect of target 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 target 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 target configuration file must be written to take into account the specific settings for each target connected to the host.

Downloading 'target'

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

Version Description Download Link
0.8.1 Fixed telnet_exec bug, add sample test script preset-test.py target-0.8.1.tgz
0.8 First public release target-0.8.tgz

Installing 'target'

Copy target to /usr/local/bin.

Configuring 'target'

In order to use 'target', you first need to set up the /etc/target.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 'target' 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 'target'

You can use 'target' 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. .
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
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 target 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 target commands one would use to accomplish this:

  • get a list of targets connected to this host
$ target list
Targets on this host:
    ebony
    innovator
    nut
    osk
    test
  • select a target to work on, and set up environment for it
$ target ebony setenv
  • get the kernel sources for a build
$ target 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
$ target get_config
  • set specific configuration options
$ target set_config CONFIG_PRINTK_TIME==y
  • build the kernel, and install it
$ target kbuild
$ target kinstall
  • reboot the target with the new kernel

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

$ reboot

or from the host, use:

$ target reset
  • (optionally) put additional files on the target
$ target cp foo bar target:/tmp
$ target cp test.sh target_bin:
  • login to the console and do some work
$ target console
<do interactive work on the target>

Commands

console

Runs a program to access the target console.

Usage: target [<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 'target run' for that.

cp

Copy files to or from the target.

Usage: target [<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: target cp test_data test_data2 target:/tmp Ex: target cp test.sh target_bin:

get_config

Install kernel config for target in the $KBUILD_OUTPUT directory

Usage: target [<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: target [<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: target help [<command>]

If a command is specified, show help and usage information for that command.

info

Show information about a target.

Usage target [<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: target [target] kinstall

Assumes the current directory is the top kernel source directory.

list

Show a list of available targets.

Usage: target 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: target [<target>] login

reset

Reset target board.

Usage: target [<target>] login

rm

Remove files from the target.

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

run

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

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

set_config

Set one or more individual config options

Usage: target [<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: target set_config CONFIG_FOO==y target set_config CONFIG_BAR==n CONFIG_BAZ==1234 target set_config "CONFIG_STR==\"foo bar\"" target set_config "CONFIG_STR+==\" quiet\""

Assumes the current directory is the top kernel source dir.

setenv

Prepare environment for building for the target

Usage: target [<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: target ebony setenv -o >foo ; source foo)

status

Show status of target, including reservations.

Usage: target [<target>] status

(not implemented yet)

version

Show version information and exit.

Usage: target version

wait_for

Wait for a condition to be true.

Usage: target [<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: target wait_for -i 2 -t 100 "test -f /tmp/outfile"

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

(Works on host right now, not target.)

Automated use of 'target'

interactive vs. automated use

Some tricks for automated use:

  • use the -o option with "target 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 "target". Here's a line which does this: target foo setenv -o >tmp ; source tmp ; rm tmp ; make $kimage

Appendix A: Configuration file specification

The configuration file for target is named "target.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 target 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) .
get_config_cmd Command(s) to put a default kernel configuration file (.config) in $KBUILD_OUTPUT .
get_kernel_cmd Command(s) to put the kernel source code in $KERNEL_SRC .
copy_to_cmd Command(s) to copy files from host to target .
copy_from_cmd Command(s) to copy files from target to host .
rm_cmd Command(s) to remove files from target .
ipaddr Target IP address .
reset_cmd Command(s) to reset the target, from the host .
console_cmd Command(s) to start an interactive console for the target (usually minicom) .
login_cmd Command(s) to start an interactive login session with the target (usually telnet) .
target_bin Directory on target where binary files are located .
fsinstall_cmd Command(s) to install a root filesystem to the target .

Configuration Example

Here is a sample:

# Some notes on syntax and conventions
# Attributes that end in "_cmd" are assumed to be shell
# commands, which will be executed in shell context
# Each line of a multi-line _cmd will be executed
# in its own sub-shell.  (i.e. don't count on
# exports or cd's being persistent from one line to
# the next)
#
# The get_kernel_cmd should output the kernel source
# to the directory specified by $KERNEL_SRC
#======================================================
target==innovator
description=="""TI OMAP Innovator board, with:
OMAP1510 processor (ARM925T core and a C55x DSP)
The ARM core runs at 168 MHZ.
The board has 32 meg. of flash (in 2 16M banks) and
32 meg. of SDRAM."""

ipaddr==192.168.1.61
login_cmd==telnet inno-1
console_cmd==minicom inno

TOOL_PATH==/usr/local/arm-sony-linux/devel/bin
ARCH==arm
CROSS_COMPILE==arm-sony-linux-
kimage==uImage
kinstall_cmd==cp -v arch/arm/boot/uImage /target/inno-1/boot
reset_cmd==omap-reset
get_kernel_cmd==export CVSRSH==/usr/bin/ssh ; cvs -d :ext:oak.sm.sony.co.jp:/var/cvsroot co -r branch_ALP_LINUX -d $KERNEL_SRC linux-2.6
get_config_cmd=="""export CVSRSH==/usr/bin/ssh ; cvs -d :ext:oak.sm.sony.co.jp:/var/cvsroot co local-dev/team/configs
        cp local-dev/team/configs/config-innovator-baseline $KERNEL_SRC/.config"""

target_bin==/devel/usr/bin
copy_to_cmd==cp $src /target/inno-1/$dest
copy_from_cmd==cp /target/inno-1/$src $dest
rm_cmd==rm /target/inno-1/$dest

#=================================================================================

target==osk
description=="""TI OMAP Starter Kit (OSK):
OMAP5912 processor (ARM926EJ-S core and a C55x DSP)
The ARM core runs at 192 MHZ.
The board has 32 meg. of flash and 32 meg. Mobile DDR SDRAM,
10 Mbit Ethernet interface, USB Host interface
and a AIC23 stereo codec."""

ipaddr==192.168.1.72
login_cmd==telnet osk2
console_cmd==echo "console is on timdesk" ; false

TOOL_PATH==/usr/local/arm-sony-linux/devel/bin
ARCH==arm
CROSS_COMPILE==arm-sony-linux-
kimage==uImage
KERNEL_SRC==linux
TMPDIR==/tmp
KBUILD_OUTPUT==../build/osk
kinstall_cmd==cp -v $KBUILD_OUTPUT/arch/arm/boot/uImage /target/osk2/boot
reset_cmd==echo "remote reset not supported" ; false
old_get_kernel_cmd==export CVSRSH==/usr/bin/ssh ; cvs -d :ext:oak.sm.sony.co.jp:/var/cvsroot co -r branch_ALP_LINUX -d $KERNEL_SRC linux-2.6
get_kernel_cmd==tla get -A alp@oak--trial-5 alp-linux--dev $KERNEL_SRC
get_config_cmd=="""export CVSRSH==/usr/bin/ssh ; cd $TMPDIR ; cvs -d :ext:oak.sm.sony.co.jp:/var/cvsroot co local-dev/team/configs/config-osk-baseline ; cd -
        cp $TMPDIR/local-dev/team/configs/config-osk-baseline $KBUILD_OUTPUT/.config"""

target_bin==/devel/usr/bin
copy_to_cmd==cp $src /target/osk2/$dest
copy_from_cmd==cp /target/osk2/$src $dest
rm_cmd==rm /target/osk2/$dest

#==================================================================================================
target==nut
description=="""Nut is an x86-based desktop computer, with:
Intel Celeron processor, running at 2 GHz.
The machine has 128 meg. of RAM and a 40G IDE hard drive."""

reset_cmd==nut-reset
console_cmd==minicom nut
login_cmd==telnet nut
ipaddr==192.168.1.14

TOOL_PATH==
ARCH==
CROSS_COMPILE==
INSTALL_PATH==/target/nut/boot
KERNEL_SRC==linux
KBUILD_OUTPUT==../build/nut

kimage==bzImage
kinstall_cmd==cp -v $KBUILD_OUTPUT/arch/i386/boot/bzImage /target/nut/boot/vmlinuz
#kinstall_cmd==make INSTALL_PATH==$INSTALL_PATH install
get_kernel_cmd=="""tar -xjf /home/rbatest/base/linux-2.6.10.tar.bz2
                mv linux-2.6.10 $KERNEL_SRC"""
get_config_cmd==cp /home/rbatest/base/config-nut-works-2.6.11-rc4 $KBUILD_OUTPUT/.config

copy_to_cmd==cp $src /target/nut/$dest
copy_from_cmd==cp /target/nut/$src $dest
rm_cmd==rm /target/nut/$dest

#=======================================================================================
target==ebony
description=="""Ebony (San Jose) is an IBM PowerPC development baord, with:
PowerPC 440GP processor, running at 400? GHz.
The machine has 128 meg. of RAM."""

ipaddr==192.168.1.54
reset_cmd==ebony-reset
console_cmd==minicom ebony
login_cmd==telnet ebony

TOOL_PATH==/usr/local/powerpc-sony-linux/devel/bin
ARCH==ppc
CROSS_COMPILE==powerpc-sony-linux-
TMPDIR==/tmp
KERNEL_SRC==linux
KBUILD_OUTPUT==../build/ebony
kimage==zImage
kinstall_cmd==cp -v $KBUILD_OUTPUT/arch/ppc/boot/images/zImage.ebony /target/ebony/boot

get_kernel_cmd==tla get -A alp@oak--trial-5 alp-linux--dev $KERNEL_SRC
get_config_cmd=="""export CVSRSH==/usr/bin/ssh ; cd $TMPDIR ; cvs -d :ext:oak.sm.sony.co.jp:/var/cvsroot co local-dev/team/configs/config-ebony-baseline ; cd -
        cp $TMPDIR/local-dev/team/configs/config-ebony-baseline $KBUILD_OUTPUT/.config"""

target_bin==/devel/usr/bin
copy_to_cmd==cp $src /target/ebony$dest
copy_from_cmd==cp /target/ebony$src $dest
rm_cmd==rm -f /target/ebony/$dest

Configuration attribute details

This section lists each configuration attribute, and what its value should be.

target
Short (one-word) name of the target
description
A description of the target board. Usually this is a multi-line value.
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)
get_config_cmd
Command(s) to put a default kernel configuration file (.config) in $KBUILD_OUTPUT
get_kernel_cmd
Command(s) to put the kernel source code in $KERNEL_SRC.
copy_to_cmd
Command(s) to copy files from host to target
copy_from_cmd
Command(s) to copy files from target to host
rm_cmd
Command(s) to remove files from target
ipaddr
Target IP address
reset_cmd
Command(s) to reset the target, from the host
console_cmd
Command(s) to start an interactive console for the target (usually minicom)
login_cmd
Command(s) to start an interactive login session with the target (usually telnet)
target_bin
Directory on target where binary files are located
fsinstall_cmd
Command(s) to install a root filesystem to the target