Building sh-linux

1. First retrieve the source code. All sources are managed using CVS, the central repository being stored here at ST. If you have access to this then the code can be checked out directly:
   1. First set the CVSROOT environment variable to point to the repository:

      export CVSROOT=/u/stuart/linux/sh/repository
      

      or for those of you still using C shell:

      setenv CVSROOT /u/stuart/linux/sh/repository
      

   2. Next checkout the sources:

      co src
      

   Unfortunately we cannot offer remote access to this repository.

   The alternative method of obtaining the sources is from the ftp.uk.linux.org FTP server. Most source code is provided as patches against easily available packages, however some are provided in full, especially where it is less common, or so small it is easier to provide the complete package.

   Name	Version	Form	Description
   binutils	2.9.1	Patch	The binutils package (as, ld, objdump, BFD, liberty etc.).
   example	-	Complete	Some simple examples which run on the SH3EVA, not using Linux.
   gcc	2.95.1	Patch	The GNU Compiler Collection. Note this is the full version, not just the 'core' package.
   genromfs	0.3	Complete	Tools to build a ROM filesystem
   glibc	2.1.1	Patch	The GNU C library. This has also had two optional packages installed; crypt version 2.0.11 and linuxthreads version 2.1.2.
   linux	2.2.9	Patch	The linux kernel
   misctools	-	Complete	Miscellaneous tools. Currently only genromdisk, used for generating ROM block device images.
   sash	2.1	Complete	A simple stand-alone shell
   sh3mon	-	Complete	Simple monitor for the SH3EVA board.

   For example, for binutils you will need the files:

   • binutils-2.9.1.tar.gz (available from the normal GNU archives).
   • binutils-2.9.1-shpatch-0.01.gz
   Then unpack the base sources and apply the patch:

   tar xvfz binutils-2.9.1.tar.gz
   zcat binutils-2.9.1-shpatch-0.01.gz | patch -p1 -d binutils-2.9.1
   

   Note if using the patch technique, some top level directory names will end up containing version numbers. This doesn't make any difference, but needs to be kept in mind.
2. Next you will need to start building things.
   1. Before you do anything else, decide where you would like the tools to be installed. The usual place is /usr/local/sh, however anywhere else can be used, and all the configure scripts take the target directory as a configuration option, so it is easy to change. As part of the build process tools installed in this directory will need to be called, you should add the bin sub-directory to your path, for example:

      export PATH=/usr/local/sh/bin:$PATH
      

   2. First build and install binutils:

      cd binutils
      ./configure --target=sh-linux --prefix=/usr/local/sh
      make
      make install
      cd ..
      

      /usr/local/sh is the directory where tools will normally be installed, but this is not mandatory.
   3. The next thing to build is gcc:

      cd gcc
      ./configure --target=sh-linux --prefix=/usr/local/sh
      make cross
      make install-cross
      cd ..
      

      The prefix should be the same as the one you used while building binutils. This may take some time, it takes around eight minutes on my machine at home (PII-400 running Linux), sixteen minutes at work (on a Sun Enterprise 450 running Solaris) and 50 minutes on slow Linux box (P166?). Most of this time is spent building the various versions of the libraries.
   4. If you want to use the SH3EVA board, you will need to build sh3mon. This simple program allows object files to be downloaded and run, and then acts as a simple terminal emulator to collect output from the target.

      cd sh3mon
      make
      make install
      cd ..
      

   5. Depending on how you are planning to configure the kernel, you may well need to build a root file system. There are lots of possible options here, but a few common ones are:
      • Don't do anything. Useful to make sure you can generate and boot a kernel successfully, but not much else.
      • Use a ROM file system and ROM block device. A simple starting point, which may have smaller memory footprint (because the code is simple and the image is stored run-length encoded), but after a while will need to be supplemented with a writable file system.
      • A normal (for example ext2) file system used to initialise a RAM disk. This is the most flexible option, but a little harder to set up.
      Here we will assume you have taken the first option, the other two are described later.
   6. Next build the Linux kernel.
      • First the kernel needs to be configured. Configure using your favorite configuration tool (I prefer menuconfig). There are not many SH specific options at the moment, and those that are there are mainly for selecting the target board. You will also need to configure the appropriate ROM and/or RAM disk support for your chosen filesystem. A good starting point should be the default configuration supplied, by using make oldconfig. Either way, this will generate a .config file which has virtually everything undefined.
      • Build the kernel:

        cd linux
        make dep
        make
        

        This should result in a kernel image: vmlinux

3. This image can now be booted. If you are using sh3mon:

   sh3mon vmlinux
   

   This should take around 1 minute to boot, and after going into terminal mode will print the usual Linux boot messages.

   Alternatively if you have access to the STMicroelectronics st40 toolchain and a JEI, you can use st40run. Depending on which version of this you are using, you may need to first alter the CPU identifier of the ELF file. The easiest way to determine if this is necessary it to try and run the vmlinux, and if you get the error message:

   ELF format file "vmlinux" is non-SH-series (expected 43 but got 42)
   

   then you know an ID change is required. A small tool idmunge is provided to to this:

   gcc idmunge.c -o idmunge
   ./idmunge vmlinux
   

   You can then simply run Linux like any other application:

   st40run -t sh4 vmlinux
   

   where sh4 is the name of your target. In this case you will have to have a terminal connected to the SCI.

• The first requirement is to build glibc, the GNU C library. For more information on glibc, have a look at the home pages at Cygnus or FSF, and FAQ for glibc 2 on Linux.

  To build it:

  cd glibc
  ./configure --build=i386-linux --host=sh-linux \
    --with-headers=/home/users/stuart/sh/src/linux/include \
    --prefix=/usr/local/sh \
    --disable-shared --disable-profile --enable-static-nss \
    --enable-add-ons=crypt,linuxthreads
  make
  make install
  cd ..
  

  Replace the -with-headers argument with the appropriate path to the include directory within your Linux sources. Note this can be quite time consuming (at takes 12 minutes on my PII-400).

  Note that this only works when crypt and linuxthreads have also been unpacked in the tree (which is recommended). If these are not added then remove the --enable-add-ons option and add --disable-sanity-checks:

  cd glibc
  ./configure --build=i386-linux --host=sh-linux \
    --with-headers=/home/users/stuart/sh/src/linux/include \
    --prefix=/usr/local/sh \
    --disable-shared --disable-profile --enable-static-nss \
    --disable-sanity-checks
  

  This installs the header files and libraries in /usr/local/sh/include and /usr/local/sh/lib respectively. To make these usable with Linux it is also necessary to place symbolic links to the kernel include and asm directories, for example:

  cd /usr/local/sh/include
  ln -s /home/users/stuart/sh/src/linux/include/asm-sh asm
  ln -s /home/users/stuart/sh/src/linux/include/linux .    
  

  or wherever the Linux kernel source is.
• Next build a program which can be used as /sbin/init. The simplest (useful) program for this is sash, a simple shell. Simply build this as normal:

  cd sash
  make
  

• The next step is to construct the desired root file system on the host computer. This process normally needs to be done while logged in as root, as it involves making special files and (if building a RAM disk) accessing file systems directly.

  In this example, the directory rootfs contains the root file system. As a minimum this needs to contain a /dev directory, with character special files for the console and serial device, and a init.

  mkdir rootfs
  mkdir rootfs/dev
  mknod rootfs/dev/console c 5 1
  mknod rootfs/dev/ttyS0 c 4 64
  mkdir rootfs/sbin
  cp sash/sash rootfs/sbin/init
  

• If you are going to use a ROM FS and ROM bock device, you next need to build the file system generation tools. These tools allow a ROM file system to be built into the Linux kernel image. The kernel can then mount this as the root file system without having any physical devices.

  There are two tools which need to be built first:

  cd genromfs
  make install
  cd ../misctools
  make install
  cd ..
  

  If you need to specify a different installation directory, this can be done using the INSTALL_DIR command line option, eg:

  make install INSTALL_DIR=/usr/bin
  

  This will build and install genromfs (which generates a ROM file system image from a specified directory) and genromdisk (which generates a C header file which is linked into the Linux image and used by the ROM block device).

  Having built the tools, the file system itself needs to be constructed. As described previously, if we assume that rootfs is the directory structure containing the files to be made into a file system image, then generate the root file system using:

  genromfs -f rootfs.fs -d rootfs 
  genromdisk < rootfs.fs > linux/drivers/block/romdisk.inc
  

  Finally configure the kernel with support for ROMFS and ROM disk, and re-build it.

  Note that these tools currently don't run under Solaris, so you'll need to build the root FS image on Linux.

• Alternatively, a RAM disk can be initialised to contain a file system image. This uses the INITRD kernel configuration. It is probably easiest to use the ext2 file system in this case (take care when using the minix file system, as this doesn't work when host and target are different endianness). In this case all the tools needed are normally part of a standard Linux installation.

  The easiest way to build a disk image is to make a new file system on a spare block device, mount it, copy the files to this device, and then unmount it and copy the special file. Usually the most convenient device is a RAM disk on the host, however a spare hard disk partition or floppy (if large enough) could also be used.

  dd if=/dev/zero of=/dev/ram bs=1k count=4096
  mke2fs -vm0 /dev/ram 4096
  mount /dev/ram /mnt/spare
  (cd ~stuart/sh/src/rootfs ; tar cf - .) | (cd /mnt/spare ; tar xvf -)
  umount /dev/ram
  cp /dev/ram ~stuart/sh/src/linux/arch/sh/kernel/initrd_data
  

  The final stage copies the image to the kernel build tree, where it can be linked into the kernel image. Note that at this point the image can be compressed using gzip if required.

  Finally configure the kernel with support for ramdisk and initrd, and re-build it.

Building on Solaris

• make must be GNU make.
• echo needs to support the -n option, for example /usr/ucb/echo.
• sh must be bash.

However don't even attempt to cross compile glibc.

sh3mon also builds and runs under Solaris, as long as SHDIR and CFLAGS are modified in the Makefile. You my also need to change the serial port device for your local setup.

So far I've not been able to build glibc under Solaris.