View source for Instructions for building and booting Linux

Some general notes on these instructions:

*  The following was tested on an x86 machine running Fedora Core 3 (FC3).
Other host distributions likely work but have not been tested.

*  Lines prefixed with "sudo" need to be executed as root.
The rest is best executed as a non-root user.
(It is possible to install subversion and git as a non-root user if
root access is an issue.  How to do this isn't shown here.)

*  Lines that set environment variables assume a Bourne compatible shell
(e.g. /bin/sh or bash), but are easily adapted to other shells.

*  Instructions are assumed executed all in order (e.g. commands assume
current directory and environment variables set earlier).



== Ensure you have all needed packages installed on your system ==

=== Install the 'subversion' source control tools ===

Download and install the 'subversion' source control tools if you
don't have it already installed:

   $ sudo yum install subversion

On an FC3 machine this picked up version 1.1.4, which works fine
even though the latest version is currently 1.4.5.
(On FC3, yum also installed dependent packages 'apr' and 'apr-util'.)


=== Download and install the 'git' source control tools ===

Download and install the 'git' source control tools if you
don't already have it installed.  On FC3, yum doesn't know about git,
so you have to do something like:

   $ cd /tmp
   $ lwp-download http://kernel.org/pub/software/scm/git/git-1.5.3.1.tar.bz2
   $ tar xfj git-1.5.3.1.tar.bz2
   $ cd git-1.5.3.1
   $ make prefix=/usr/local all
   $ sudo make prefix=/usr/local install

This doesn't install git documentation.  For that, you have
to build 'doc' and 'info' make targets, which require first
installing other packages such as 'asciidoc' and others.
However, for this example, documentation is not necessary.

On FC6, you can just do:

   $ sudo yum install git


== Download and build a toolchain and root filesystem using buildroot ==

   $ cd <workdir>

where <workdir> is the path to an empty directory on a disk with
at least 4 GB available space.
The following creates and populates the <workdir>/trunk directory:

   $ svn co svn://linux-xtensa.org/var/svn/repos/buildroot/trunk/


=== Change some default behavior ===

Edit  trunk/target/generic/target_skeleton/etc/inittab

Comment out the default getty's:

      # Set up a couple of getty's
      #tty1::respawn:/sbin/getty 38400 tty1
      #tty2::respawn:/sbin/getty 38400 tty2

Un-comment the serial port getty and modify the baud rate:

      # Put a getty on the serial port
      ttyS0::respawn:/sbin/getty -L ttyS0 38400 vt100


=== Prepare the overlay for gcc and binutils ===

   $ cd <workdir>
   $ mkdir overlay-DC232L
   $ cd overlay-DC232L
   $ lwp-download http://linux-xtensa.org/pub/processors/dc232l/dc232l-binutils.tar
   $ lwp-download http://linux-xtensa.org/pub/processors/dc232l/dc232l-gcc.tar
   $ lwp-download http://linux-xtensa.org/pub/processors/dc232l/dc232l-gdb.tar
   
   $ export XTENSA_CONFIG_DIR='<workdir>/overlay-DC-232L'
   $ export XTENSA_CONFIG_NAME='dc232l'

(As usual, replace <workdir> with the appropriate full path.)

=== Configure buildroot ===

Note:  You need the TERM environment variable properly set for curses
based tools to work.

   $ cd <workdir>/trunk
   $ make ARCH=xtensa menuconfig

You should get a curses interface for configuring buildroot.
Make the following changes:

* Change 'Target Architecture' from i386 to xtensa.
* Change 'Target Architecture Variant' from xtensa_generic to DC 232L
* Under 'Toolchain Options', change 'Binutils Version' from '2.17'
to '2.17.50.0.17'
* Under 'Target Options', enable 'cpio the root filesystem';
this creates a 'Compression method' submenu;
under this submenu, select 'gzip'
* Again under 'Target Options', enable 'initramfs for initial ramdisk
of linux kernel'.
* Exit and save the configuration.


=== Configure uClibc ===

   $ make ARCH=xtensa uclibc-config

Select '24' for 'xtensa' and accept all default settings (ENTER).


=== Build buildroot ===

   $ make ARCH=xtensa

Wait patiently for build to complete.  This builds an entire toolchain
as well as some basic packages, and constructs a root filesystem.


== Build a Linux kernel ==

=== Download the kernel ===

   $ cd <workdir>
   $ git clone git://git.linux-xtensa.org/kernel/xtensa-devel

This creates and populates the <workdir>/xtensa-devel directory.


=== Configure the kernel ===

The build is a two-step process:  configure the kernel, and build it.
First set your PATH to point to the toolchain built using buildroot.

   $ export PATH="<workdir>/trunk/build_xtensa/staging_dir/usr/bin:$PATH"

We usually like to have the build directory separate from
the source directory, so we use 'O=</destination/path>' in
kernel make commands.

   $ cd xtensa-devel
   $ mkdir build

You can use the default configuration for the LX60 as follows
(one long line if you omit the '\' continuator):

   $ make O=build ARCH=xtensa CROSS_COMPILE=xtensa-linux-uclibc-  \
         KBUILD_DEFCONFIG=lx60_defconfig defconfig

This configures the kernel using the default configuration found in
arch/xtensa/config/lx60_defconfig.

Edit  build/.config

Change the line:

      CONFIG_INITRAMFS_SOURCE=""

to:

      CONFIG_INITRAMFS_SOURCE="<workdir>/trunk/binaries/uclibc/rootfs.xtensa
.cpio.gz"
      CONFIG_INITRAMFS_ROOT_UID=0
      CONFIG_INITRAMFS_ROOT_GID=0

(Don't forget to replace <workdir> with the appropriate full path.)
Backup your configuration outside the build directory.  For example:

   $ cp build/.config config.saved

If you do a clean rebuild of the kernel (e.g. "rm -rf build")
you can now configure it with simply:
          mkdir build ; cp config.saved build/.config
Of course if you update the kernel, you'll probably have to do:
          make O=build ARCH=xtensa CROSS_COMPILE=xtensa-linux-uclibc-
menuconfig
and save a new copy of your configuration.


=== Build the kernel ===

   $ make O=build ARCH=xtensa CROSS_COMPILE=xtensa-linux-uclibc-

The build will issue a few warnings which are normal, such as
about RSR macro, elfcore.h, and section mismatches in MODPOST.
Once complete, the bootable image is in:
      <workdir>/xtensa-devel/build/arch/xtensa/boot/Image.elf
and the uncompressed ELF file containing kernel symbols is in:
      <workdir>/xtensa-devel/build/vmlinux
There is also a RedBoot bootable image (if you use RedBoot) in:
      <workdir>/xtensa-elf/build/arch/xtensa/boot/zImage.redboot


== Run the resulting kernel ==

=== Install Xtensa Tools with the 232L core ===

This can be done a a different machine than the one used so far,
as long as it has access to the <workdir> directory tree.

=== Install and setup the Xtensa OCD Daemon ===

Setup and connect your JTAG probe, etc.

=== Connect a terminal server ===

At 38400 bps 8N1 no flow control to the LX60 serial port.

=== Optionally, setup networking ===

This step is optional.

Setup the board's MAC address using dipswitches
(see LX60 docs) and connect the LX60 to a network that has a
DHCP server that will respond to that MAC address.
If you don't do this step, you'll simply not have network
access, and the boot process will take a minute or so longer
while the kernel times out waiting for a BOOTP response.
You can edit the kernel configuration and rebuild the kernel
to avoid using bootp (in particular, remove "ip=bootp" from
the kernel cmdline).

=== Download and run the kernel ===

Reset the LX60 board (see board documentation).

Using Xtensa Tools, invoke:

   $ xt-gdb <workdir>/xtensa-devel/build/arch/xtensa/boot/Image.elf

   (xt-gdb) target remote <ocdhost>:20000 0
   (xt-gdb) symbol-file <workdir>/xtensa-devel/build/vmlinux
   (xt-gdb) reset
   (xt-gdb) load
   (xt-gdb) set $pc = &_ResetVector
   (xt-gdb) c

where <ocdhost> is the IP address or DNS name of the machine
running the Xtensa OCD daemon.  The Linux kernel should
start booting as soon as 'c' (continue) is executed.

You should eventually get a login prompt.
Just login as root (no password).

Try various Linux commands.  Look at /bin, /sbin, /usr/bin,
etc to see what's available.  Not all guaranteed to work,
but basic things like 'ls' and 'ping' seem to work fine.

Note:  no need to setup an NFS or TFTP server.  The filesystem
is contained within the kernel image.  You may be able to mount
other filesystems over NFS though, if you wish, after booting.