Mercurial > hg > aboriginal

comparison www/new_platform.html @ 208:6850e0aaddde

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add new_platform, note it in the header, mention it as news.
author Rob Landley <rob@landley.net>
date Sun, 02 Sep 2007 05:05:52 -0500
parents
children 185081cc4ea9
comparison
equal deleted inserted replaced
207:d922fe34cd5d 208:6850e0aaddde
1 <!--#include file="header.html" -->
2
3 <h2>Setting up a new platform</h2>
4
5 <p>The differences between platforms are confined to a single file, which is
6 the platform configuration file in the <b>sources/configs</b> directory. The
7 same scripts build the same packages for each platform, differing only in
8 which configuration file they read.</p>
9
10 <p>Each configuration file sets some environment variables, defines one
11 shell function, and writes two data files. The name of the configuration file
12 is also significant.</p>
13
14 <p>Configuration files are read and processed by the script
15 <b>include.sh</b>.</p>
16
17 <h2>Naming your configuration file.</h2>
18
19 <p>The name of the platform configuration file is used to form a "tuple" for
20 gcc and binutils by appending "-unknown-linux" to the filename. So the first
21 thing to do is find out what platform name gcc and binutils want for your
22 target platform, and name your config file appropriately.</p>
23
24 <p>(Note: if your platform really can't use an "${ARCH}-unknown-linux" style
25 tuple, and instead needs a tuple like "bfin-elf", you can set the variable
26 CROSS_TARGET in the config file to override the default value and feed
27 some other --target to gcc and binutils. You really shouldn't have to do
28 this unless gcc doesn't yet fully support Linux on your platform. Try the
29 default first, and fix it if necessary.)</p>
30
31 <p>The name of the configuration file is also used in the name of the various
32 directories generated during the build (temp-$NAME, cross-compiler-$NAME,
33 and mini-native-$NAME, all in the build/ directory), and as the prefix of the
34 cross compiler binaries ($NAME-gcc and friends).</p>
35
36 <h2>Setting environment variables.</h2>
37 <p>The following environment variables are usually set in a configuration
38 file:</p>
39 <ul>
40 <li><b>KARCH</b> - architecture value for the Linux kernel (ARCH=$KARCH). The
41 Linux kernel uses different names for architectures than gcc or binutils
42 do. To see all your options, list the "arch" directory of the linux kernel
43 source.</li>
44 <li><b>KERNEL_PATH</b> - Path in the linux kernel source tree where the bootable
45 kernel image is generated. This is the file saved out of the kernel build, to
46 be fed to qemu's -kernel option. Usually "arch/${KARCH}/boot/zImage", but
47 sometimes bzImage or image in that directory, sometimes vmlinux in the top
48 level directory...</li>
49 <li><b>GCC_FLAGS</b> - Any extra flags needed by gcc. Usually blank, but
50 sometimes used to specify a floating point coprocessor or ABI.</li>
51 <li><b>BINUTILS_FLAGS</b> - Any extra flags needed by binutils. Usually
52 blank.</li>
53 <li><b>QEMU_TEST</b> - At the end of the cross compiler build, a quick sanity
54 test builds static and dynamic "Hello world!" executables with the new cross
55 compiler. Optionally, if QEMU_TEST isn't blank and a file qemu-$QEMU_TEST
56 exists in the $PATH, the cross compiler build script will then run qemu's
57 application emulation against the static version of "hello world" as an
58 additional sanity test, to make sure it runs on the target processor and
59 outputs "Hello world!". Leave it blank to skip this test.</li>
60 </ul>
61
62 <h2>emulator_command</h2>
63
64 <p>The shell function <b>emulator_command()</b> is used to generate
65 the run-$ARCH.sh shell script in the build directory. The function should
66 output an emulator command line to stdout (generally using "echo"). The
67 function receives three arguments: $1 is the name of the ext2 image containing
68 the root filesystem, $2 is the name of the kernel image, $3 is a set of
69 platform-independent kernel command line arguments (currently "rw
70 init=/tools/bin/sh panic=1 PATH=/tools/bin") to which emulator_command should
71 append at least root= and console= arguments. This function is called from
72 include.sh.</p>
73
74 <h2>miniconfig-linux</h2>
75 <p>The Linux kernel needs a configuration file to build. Firmware Linux
76 uses the "miniconfig" file format, which contains only the configuration
77 symbols a user would have to switch on in menuconfig if they started from
78 allnoconfig.</p>
79
80 <p>This file is written as a "here" document, ala:</p>
81 <blockquote>
82 <pre>
83 cat > "${WORK}"/miniconfig-linux << 'EOF'
84 [insert file contents here]
85 EOF
86 </pre>
87 </blockquote>
88
89 <p>To generate a miniconfig, first configure your kernel with menuconfig,
90 then copy the resulting .config file to a temporary filename (such as
91 "tempfile"). Then run the miniconfig.sh script in the sources/toys directory
92 with the temporary file name as your argument and with the environment variable
93 ARCH set to the $KARCH value in your new config file (and exported if
94 necessary). This should produce a new file, "mini.config", which is your
95 .config file converted to miniconfig format.</p>
96
97 <p>For example, to produce a miniconfig for a given platform:</p>
98 <blockquote>
99 <pre>
100 make ARCH=$KARCH menuconfig
101 mv .config tempfile
102 ARCH=$KARCH miniconfig.sh tempfile
103 ls -l mini.config
104 </pre>
105 </blockquote>
106
107 <p>To expand a mini.config back into a full .config file (to build a kernel
108 by hand, or for further editing with menuconfig), you can go:</p>
109
110 <blockquote>
111 <pre>
112 make ARCH=$KARCH allnoconfig KCONFIG_ALLCONFIG=mini.config
113 </pre>
114 </blockquote>
115
116 <p>Remember to supply an actual value for $KARCH.</p>
117
118 <h2>miniconfig-uClibc</h2>
119
120 <p>Just like the Linux kernel, uClibc needs a .config file to build, and
121 so the Firmware Linux configuration file supplies a miniconfig. Note that
122 uClibc doesn't require an ARCH= value, because all its architecture information
123 is stored in the config file. Otherwise the procedure for creating and using
124 it is the same as for the Linux kernel, just with a different filename and
125 contents.</p>
126
127 <p>Note that Firmware Linux patches uClibc to work with miniconfig files,
128 the base uClibc 0.9.29 release doesn't support miniconfig files yet.</p>
129
130 <!--#include file="footer.html" -->