view www/new_platform.html @ 346:8a71354d8ceb

Added tag 0.4.0 for changeset 1a70dfe0a436
author Rob Landley <rob@landley.net>
date Fri, 06 Jun 2008 22:08:56 -0500
parents 185081cc4ea9
children
line wrap: on
line source

<!--#include file="header.html" -->

<h2>Setting up a new platform</h2>

<p>The differences between platforms are confined to a single file, which is
the platform configuration file in the <b>sources/configs</b> directory.  The
same scripts build the same packages for each platform, differing only in
which configuration file they read.</p>

<p>Each configuration file sets some environment variables, defines one
shell function, and writes two data files.  The name of the configuration file
is also significant.</p>

<p>Configuration files are read and processed by the script
<b>include.sh</b>.</p>

<h2>Naming your configuration file.</h2>

<p>The name of the platform configuration file is used to form a "tuple" for
gcc and binutils by appending "-unknown-linux" to the filename.  So the first
thing to do is find out what platform name gcc and binutils want for your
target platform, and name your config file appropriately.</p>

<p>(Note: if your platform really can't use an "${ARCH}-unknown-linux" style
tuple, and instead needs a tuple like "bfin-elf", you can set the variable
CROSS_TARGET in the config file to override the default value and feed
some other --target to gcc and binutils.  You really shouldn't have to do
this unless gcc doesn't yet fully support Linux on your platform.  Try the
default first, and fix it if necessary.)</p>

<p>The name of the configuration file is also used in the name of the various
directories generated during the build (temp-$NAME, cross-compiler-$NAME,
and mini-native-$NAME, all in the build/ directory), and as the prefix of the
cross compiler binaries ($NAME-gcc and friends).</p>

<h2>Setting environment variables.</h2>
<p>The following environment variables are usually set in a configuration
file:</p>
<ul>
<li><b>KARCH</b> - architecture value for the Linux kernel (ARCH=$KARCH).  The
Linux kernel uses different names for architectures than gcc or binutils
do.  To see all your options, list the "arch" directory of the linux kernel
source.</li>
<li><b>KERNEL_PATH</b> - Path in the linux kernel source tree where the bootable
kernel image is generated.  This is the file saved out of the kernel build, to
be fed to qemu's -kernel option.  Usually "arch/${KARCH}/boot/zImage", but
sometimes bzImage or image in that directory, sometimes vmlinux in the top
level directory...</li>
<li><b>GCC_FLAGS</b> - Any extra flags needed by gcc.  Usually blank, but
sometimes used to specify a floating point coprocessor or ABI.</li>
<li><b>BINUTILS_FLAGS</b> - Any extra flags needed by binutils.  Usually
blank.</li>
<li><b>QEMU_TEST</b> - At the end of the cross compiler build, a quick sanity
test builds static and dynamic "Hello world!" executables with the new cross
compiler.  Optionally, if QEMU_TEST isn't blank and a file qemu-$QEMU_TEST
exists in the $PATH, the cross compiler build script will then run qemu's
application emulation against the static version of "hello world" as an
additional sanity test, to make sure it runs on the target processor and
outputs "Hello world!".  Leave it blank to skip this test.</li>
</ul>

<h2>emulator_command</h2>

<p>The shell function <b>emulator_command()</b> is used to generate
the run-$ARCH.sh shell script in the build directory.  The function should
output an emulator command line to stdout (generally using "echo").  The
function receives three arguments: $1 is the name of the ext2 image containing
the root filesystem, $2 is the name of the kernel image, $3 is a set of
platform-independent kernel command line arguments (currently "rw
init=/tools/bin/sh panic=1 PATH=/tools/bin") to which emulator_command should
append at least root= and console= arguments.  This function is called from
include.sh.</p>

<a name="miniconfig"><h2>miniconfig-linux</h2>
<p>The Linux kernel needs a configuration file to build.  Firmware Linux
uses the "miniconfig" file format, which contains only the configuration
symbols a user would have to switch on in menuconfig if they started from
allnoconfig.</p>

<p>This file is written as a "here" document, ala:</p>
<blockquote>
<pre>
cat > "${WORK}"/miniconfig-linux << 'EOF'
[insert file contents here]
EOF
</pre>
</blockquote>

<p>To generate a miniconfig, first configure your kernel with menuconfig,
then copy the resulting .config file to a temporary filename (such as
"tempfile").  Then run the miniconfig.sh script in the sources/toys directory
with the temporary file name as your argument and with the environment variable
ARCH set to the $KARCH value in your new config file (and exported if
necessary).  This should produce a new file, "mini.config", which is your
.config file converted to miniconfig format.</p>

<p>For example, to produce a miniconfig for a given platform:</p>
<blockquote>
<pre>
make ARCH=$KARCH menuconfig
mv .config tempfile
ARCH=$KARCH miniconfig.sh tempfile
ls -l mini.config
</pre>
</blockquote>

<p>To expand a mini.config back into a full .config file (to build a kernel
by hand, or for further editing with menuconfig), you can go:</p>

<blockquote>
<pre>
make ARCH=$KARCH allnoconfig KCONFIG_ALLCONFIG=mini.config
</pre>
</blockquote>

<p>Remember to supply an actual value for $KARCH.</p>

<h2>miniconfig-uClibc</h2>

<p>Just like the Linux kernel, uClibc needs a .config file to build, and
so the Firmware Linux configuration file supplies a miniconfig.  Note that
uClibc doesn't require an ARCH= value, because all its architecture information
is stored in the config file.  Otherwise the procedure for creating and using
it is the same as for the Linux kernel, just with a different filename and
contents.</p>

<p>Note that Firmware Linux patches uClibc to work with miniconfig files,
the base uClibc 0.9.29 release doesn't support miniconfig files yet.</p>

<!--#include file="footer.html" -->