Mercurial > hg > aboriginal

annotate www/new_platform.html @ 346:8a71354d8ceb

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