--- a/www/header.html	Fri Aug 31 13:49:56 2007 -0500
+++ b/www/header.html	Sun Sep 02 05:05:52 2007 -0500
@@ -16,6 +16,7 @@
     <li><a href="index.html">News</a></li>
     <li><a href="about.html">What is it?</a></li>
     <li><a href="design.html">Design Docs</a></li>
+    <li><a href="new_platform.html>Porting</a></li>
     <li><a href="downloads/README">README</a></li>
   </ul>
   <b>Download</b>

--- a/www/index.html	Fri Aug 31 13:49:56 2007 -0500
+++ b/www/index.html	Sun Sep 02 05:05:52 2007 -0500
@@ -1,6 +1,12 @@
 <!--#include file="header.html" -->
 <b><h1>News</h1></b>
 
+<h2>September 02, 2007</h2>
+<p>Added <a href=new_platform.html>a porting guide</a>.  I'm working on
+m68k, ppc, big endian arm, and maybe blackfin targets for the next release,
+and thought other people might be interested in the process.  (The vast
+majority of it is fiddly debugging.  These are the other steps.)</p>
+
 <h2>June 27, 2007</h2>
 <p><a href=downloads/firmware-0.2.2.tar.bz2>Version 0.2.2</a> is out
 (changeset 185).  Using uClibc 0.9.29 release, several small bugfixes,

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/www/new_platform.html	Sun Sep 02 05:05:52 2007 -0500
@@ -0,0 +1,130 @@
+<!--#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>
+
+<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" -->