This is LinuxSH FAQ version 0.03bis. Last Modified Sunday, 14th of October, 2000

This article is a description and primer on the LinuxSH3 project.

You can always find the latest version of this FAQ at the following location: <http://LinuxSH.sourceforge.net/faq.php3>.


NOTES

1 GENERAL QUESTIONS

1.1 What is the LinuxSH3 project ?

The aim of the LinuxSH3 project is to port linux to the Hitachi SHx line of microprocessors. This includes, but is not limited to, the subset of Windows CE based PDA's running on these processors. The LinuxSH3 project is linked with of a more general project, LinuxCE, whose aim is to port Linux to Microsoft CE devices. Please refer to the FAQ <http://www.2gn.com/~jjorgens/linuxce_faq.html> and the official website <http://www.linuxce.org/>

1.2 Where can I find LinuxSH3 ?

Right now there is no distribution, for the project is still in its early developpment phase. But you can find kernel images and filesystem images that can be loaded on your hardware.

1.3 I have a SH-based board/PDA/Handheld. Where can I find more information on using LinuxSH3 on these ?

The official website is <http://linuxsh3.cjb.net/>. The development mailing list is linux-sh@m17n.org. The website has instructions on how to join the list. Below are a list of links with info related to LinuxSH3 project.

        John Hassey's LinuxCE page.     <http://home1.gte.net/hassey/linuxce/SH/index.html>
        Niibe Yutaka's SH3 efforts.     <http://www.m17n.org/linux-sh/>
        Kaz Kojima's Pages              <http://www.rr.iij4u.or.jp/~kkojima/linux-sh4.html>, <http://dodo.nurs.or.jp/~kkojima>
        Takasi Yoshii's Page            <http://www.ops.dti.ne.jp/~takasi-y/shlinux/>

1.4 What methods can be used to load the kernel ? (from LinuxCE's FAQ)

Current development is focusing on a Windows CE application to boot the kernel. The work is based on a NetBSD bootloader that is being developed in Japan. Some folks are working on replacing the ROMS but those projects tend to be very machine specific. Note on the ROMS replacement and self-advertising : I've written a piece of software that allow the use of certain features of the Windows CE bootloader, to actually download and flash the Flash ROMS in development CE devices. Please see <http://LinuxSH.free.fr/tools>

1.5 What is the development platform for the various pieces ? (from LinuxCE's FAQ)

The bootloader (and only the bootloader) is being written on the Microsoft Visual C++ platform. The rest of the project is done using GCC. Please have a look on the relevant section of the FAQ

1.6 What hardware will be required to run LinuxSH3 ?

It looks like on the sh3, it is reasonable to target a device with as low as 2 Meg of RAM. The following HITACHI processors are supported or reported to work :

1.7 How far along is the project ? (bits from LinuxCE's FAQ)

Bradley LaRonde and Steve Hill are working on a bootloader called CyaCE based in part on pbsdboot. In the words of Brad, "CyaCE is the coolest boot loader ever" :-) It is available for MIPS target, but I don't know if anybody ever tried to compile it for a SH target. In kernel developpment, the latest Linux developpement kernel boots, and can execute a simple user space program from ramdisk. In userland developpment, the port of Glibc to SH-4 has already started and many programs are running (bash, etc...)


2 KERNEL DEVELOPMENT

2.1 What are the tools needed to develop on kernel for LinuxSH3 project ?

You'll need to have the following :

Remark: In this FAQ, I use the target 'sh-linux', which resolves to 'sh-unknown-linux'. Kaz and NIIBE use the target 'sh-pc-linux'. You can choose to use 'sh-pc-linux' by replacing in the FAQ the targets and path.

2.2 How do I compile and setup binutils ?

We need : binutils-000314.tar.bz2, binutils-000314-sh.diff, binutils-cvs-000303.diff.gz

Unpack binutils.

        $ tar --use-compress-prog=bzip2 -xvf binutils-000314.tar.bz2
        $ cd binutils-000314

Due to a bug in BFD (Binary File Descriptor) in binutils, you'll have to make a few modifications if you intend to do ROM images. Two ways :

        $ patch -p1 < ../binutils-000314-sh.diff
        $

In each file look for the following test (search for BFD_ENDIAN_UNKNOWN):

        if ( ibdf->xvec->byteorder != obfd->xvec->byteorder
          && obfd->xvec->byteorder != BFD_ENDIAN_UNKNOWN )

and replace it with (add the last line)

        if ( ibdf->xvec->byteorder != obfd->xvec->byteorder &&
          && obfd->xvec->byteorder != BFD_ENDIAN_UNKNOWN
        ++        && ibfd->xvec->byteorder != BFD_ENDIAN_UNKNOWN )

Then you must apply Kaz's patches for PIC (Position Independent Code) for SH, that you can find here <http://dodo.nurs.or.jp/~kkojima/gnu-on-sh/binutils-000123-000131.diff.gz>

        $ zcat ../binutils-cvs-000303.diff.gz | patch -p1
        $

then you can issue the following command :

        $ ./configure --target=sh-linux
        $ make
        $ make install

2.3 How do I compile and setup GCC ?

We need : gcc-core-2.95.2.tar.bz2, gcc-2.95.2-000228.diff.gz, gcc-symbol-vis-000219.diff.gz

Unpack GCC-core v2.95.2

        $ tar --use-compress-prog=bzip2 -xvf gcc-core-2.95.2.tar.bz2
        $

You'll need the following patch <http://dodo.nurs.or.jp/~kkojima/gnu-on-sh/gcc-2.95.2-000228.diff.gz> (courtesy of kaz Kojima). This patch corrects some bugs with GCC, adds the ability to recognize the target 'sh*-*linux-gnu', and deals with PIC.

        $ cd gcc-2.95.2
        $ zcat ../gcc-2.95.2-000228.diff.gz | patch -p1

You'll also need the following patch <ftp://ftp.m17n.org/pub/linux-sh/gcc-symbol-vis-000219.diff.gz>

        $ zcat ../gcc-symbol-vis-000219.diff.gz | patch -p1
        $ cd ..

Then you can issue the following command : (Be careful : the directory in which you run make is NOT a subdirectory of gcc-2.91.2, but is on the same level. This is the recommended GCC configure/make process. It works.)

        $ mkdir sh-linux-gcc
        $ cd sh-linux-gcc
        $ ../gcc-2.95.2/configure --target=sh-linux
        $ make
        $ make install
        $ cd ..

NOTE
You should have no problem compiling GCC with these patches, it wasn't the case in the previous versions of the FAQ. You can thank Kaz and NIIBE for their wonderful job.

2.4 How do I compile and setup GDB ?

We need : gdb-4.18.tar.bz2

Unpack GDB.

        $ tar --use-compress-prog=bzip2 -xvf gdb-4.18.tar.bz2
        $ cd gdb-4.18

Optionnaly, if you have a CqREEK SH3 board, you can get Niibe's patch to support it. You should find it on his site.

Then you can issue the following commands : (you can use sh-elf if sh-linux doesn't work)

        $ ./configure --target=sh-linux
        $ make
        $ make install
        $ cd ..

2.5 How do I compile Linux Kernel ?

You need to have binutils and gcc compiled for SH. (You do not need glibc for the kernel).

First of all, get and unpack the desired kernel version somewhere. Then apply the necessary patches you can find at question 2.1. These patches add (or modify) the arch/sh subdirectory, which adds support for the SH line of processors. It also modifies a line in the main Makefile, where it forces the architecture to be sh (ARCH). Depending on the port, you can use 'make menuconfig' or you must copy a config file to set up the kernel.

With some patches, the main Makefile is not modified (concerning the architecture), so you'll need to type : 'make menuconfig ARCH=sh' or 'make config ARCH=sh' to specify you want to parameter a kernel on a SH machine. Also, the final build will have to use the line : 'make zImage ARCH=sh CROSS_COMPILE=sh-linux-'

But with other patches (NIIBE's for example) the architecture in the Makefile is modified, and you only have to type the 'make menuconfig' and 'make zImage' as usal.

2.6 How do I test the kernel ?

It depends on the target (board, PDA, etc...) and the boot process. - With CE devices (PDA, HPC, etc...) you have a bootloader (a Windows CE application) that looks for a specific file at a specific place. - With developpment boards, you either use a GDB stub then download the kernel to the board using a serial port, or you can directly program the board's ((E)EP)ROM with the kernel.

2.7 How do I use a Windows CE bootloader ?

Please refer to other FAQ's or web pages. (yet to be written)

2.8 How do I use GDB stub ?

( Quoting Mikhail )
If you are using Niibe version os kernel and load it by GDB, then you need to put the command line into kernel source. For it, in file arch/sh/kernel/setup.c put "#define COMMAND_LINE ..." (I couldn't use the normal way of setting it by GDB, having an error).

In the version that I used, this COMMAND_LINE was used nowhere. Maybe now Niibe fixed it. So to make it working you need to add the line again in setup.c: memcpy(command_line, COMMAND_LINE, COMMAND_LINE_SIZE);

Actually, there is "memcpy(saved_command_line, COMMAND_LINE, COMMAND_LINE_SIZE);" but the variable "command_line" is used for parsing and getting parameters.

(yet to be written)

2.9 How do I use a kernel directly from ROM ?

        $ make zImage
        $

It'll produce in 'arch/sh/boot' a ELF file 'vmlinux' which you can then convert to binary and put in ROM.

NOTE
This patch needs, in arch/sh/boot, a file 'root-fs-image', which must be an (uncompressed) initrd image. It bundles the kernel and the initrd image, and the bootloader will move the kernel to RAM, the initrd to another part of the RAM, and patch the kernel in RAM so that it uses the initrd. Only works with NIIBE's linux kernel, but can be easily adapted to work with others, or not to use the initrd image.

2.10 How do I flash a ROM with my kernel from question 2.9 ?

You'll need the tools I developped for this purpose : <http://LinuxSH.free.fr/tools/> You'll also need a CE target with a bootloader that understands the ESHELL protocol.

        $ sh-linux-objcopy -S -R .stack -R .bss -R .comment -O binary linux/arch/sh/boot/vmlinux vmlinux.bin
        $ bin2rom vmlinux.bin vmlinux.rom 0x84000000 0x84000000
        $ ethload <target_name> vmlinux.rom

Comments :

        $ ethload aaaa aaaa (Or any random values you like)
        $

And boot your CE device up.
ethload should come with a line :

                ethload comes with ABSOLUTELY NO WARRANTY; for details see COPYING.
                 This is free software, and you are welcome to redistribute it
                 under certain conditions; see COPYING for details.
                Waiting for aaaa to boot : 
                 Got BOOTME from device IP: 192.168.131.1 type DEVICE123 (DEVICE) : eboot v2.2 arch:Hitachi SH3

Your <target_name> to use shall be : DEVICE123. You can now issue to flash your kernel :

        $ ethload DEVICE123 vmlinux.rom
        $

2.11 How do I use linux XXXX driver for the (ISA) chipset YYYY ?

(I can only report here my experience with an ethernet chipset)

Depending on the driver, I think this can range from very easy to ... painful and difficult. The first thing to know is your peripheral 'IO' address : in PC world, ISA peripherals are accessible through IO space (from 0x000 to 0x400(?)) and memory space. They also use interrupts. In SH world, every thing is memory-mapped. Everything depends on your board design.

Pay attention to the fact that some drivers expect the peripheral to be in a known state (i.e. after reset) while it may be that the peripheral has already been initialized or is in a different state. So you may have to reinit the peripheral before it gets 'autodetected' by the driver.

(Quoting Mikhail)

2.12 How do I use linux XXXX driver for the (PCI) chipset YYYY ?

(yet to be written)

2.13 How do I NFS-mount my root partition ?

(Quoting Kaz)
To mount root file system via NFS, I turned on networking options CONFIG_IP_PNP (IP: kernel level autoconfiguration) CONFIG_IP_PNP_BOOTP (BOOTP support)
CONFIG_IP_PNP_RARP (RARP support)
which come from net/ipv4/Config.in and filesystems options CONFIG_NFS_FS NFS (filesystem support)
CONFIG_ROOT_NFS (Root file system on NFS). The last one will appear only if CONFIG_IP_PNP is turned on.
I set also the kernel command line like as static char cmdline[] = "root=/dev/nfs nfsroot=10.253.253.7:/tftpboot/sh ip=10.253.253.11:10.253.253.7:10.253.253.7:255.255.255.0:sh:eth0:rarp" which is used in init(), though this is specific to your kernel. Please see Documentation/nfsroot.txt also.


3 USERLAND DEVELOPMENT

3.1 What are the tools needed to develop userland applications for LinuxSH3 project ?

You use the same tools you use for kernel development (see 2.1), in addition to :

3.2 How do I compile and setup GLIBC ?

First of all, get glibc.
Optionnaly, get linuxthread and crypt add-ons for glibc. Unpack all this (all add-ons should be unpacked in the library source directory)

        $ tar --use-compress-prog=bzip2 -xvf glibc-2.1.3.tar.bz2
        $ cd glibc-2.1.3
        $ tar --use-compress-prog=bzip2 -xvf ../glibc-crypt-2.1.tar.bz2
        $ tar --use-compress-prog=bzip2 -xvf ../glibc-linuxthreads-2.1.3.tar.bz2

Apply the patches for LinuxSH :

        $ zcat ../glibc-2.1.2-000206.diff.gz | patch -p1
        $
        CFLAGS := -ml -m3 -O $(CFLAGS)
        ASFLAGS-.o := -ml
        build-programs=no
        LDFLAGS-relocatable := -ml
        crts-predefined=yes
        $ cd ..
        $ mkdir sh-linux-glibc
        $ cd sh-linux-glibc
        $ export CC='sh-linux-gcc -ml -m3'
        $ export RANLIB='sh-linux-ranlib'
        $ export AS='sh-linux-gcc -ml'
        $ export LD='sh-linux-ld -ml'
        $ export AR='sh-linux-ar'
        $ export BUILD_CC=gcc
        $ ../glibc-2.1.2/configure --enable-add-ons=crypt,linuxthreads --prefix=/usr --with-binutils=/usr/local/sh-linux/bin --disable-debug --disable-profile --host=sh3-linux --build=i686-linux --with-headers=/usr/local/src/linux/include/ --enable-static-nss
        $ make
        $ touch iconv/iconv_prog
        $ touch login/pt_chown
        $ make install_root=/usr/local/sh-linux/   prefix=    install
        $ cd ..
        $ vi /usr/local/sh-linux/lib/libc.so :

modify the file so that it reads (just remove the '/lib/' ) :

        ...
        GROUP( libc.so.6 libc_nonshared.a )
        ...

Note
- be sure, in the line 'make install_root=/usr/local/sh-linux/ prefix= install', not to forget the space between 'prefix=' and 'install'

Then you should be able to compile a simple hello world program for sh3 without any linking complaints. (You really should try 'sh-linux-gcc -ml -m3 hello.c -o hello' and 'sh-linux-gcc -ml -m3 -static hello.c -o hello.static', then 'file hello.*' to see if it looks good.)

3.3 How do I compile and setup Newlib ?

(to be written, any volunteer ? )

3.4 How do I compile and setup Ncurses ?

We need : ncurses-5.0.tar.gz, ncurses-5.0-sh.diff (or NIIBE's patch : ncurses-5.0-000205.diff.gz, not tested yet)

Extract ncurses-5.0.tar.gz (get it here : <ftp://ftp.gnu.org/pub/gnu> ) Apply the following patch : <http://LinuxSH.free.fr/faq/ncurses-5.0-sh.diff> (It modifies configure, config.sub for SH3 target, ncurses/tinfo/MKcaptab.c, misc/Makefile.in ) [Or apply NIIBE's patch instead, not tested yet]

        $ export CC='sh-linux-gcc -ml -m3'
        $ export RANLIB='sh-linux-ranlib'
        $ export AS='sh-linux-gcc -ml'
        $ export LD='sh-linux-ld -ml'
        $ export AR='sh-linux-ar'
        $ export BUILD_CC=gcc
        $ ./configure --prefix=/tftpboot/sh/local/ --host=sh3-linux --target=sh3-linux --without-cxx --without-ada --without-debug --without-progs
        $ make
        $ make install
        $ cd test
        $ mkdir /tftpboot/sh/local/tests
        $ cp blue bs cardfile ditto dots filter firework firstlast gdc hanoi hashtest keynames knight lrtest newdemo rain tclock testaddch testcurs testscanw tracemunch view worm xmas /tftpboot/sh/local/tests/

You should be able to try these programs on your target.

NOTE

3.5 How do I compile and setup bash ?

We need : bash-2.03.tar.gz, bash-2.03-sh.diff (or NIIBE's patch : bash-2.03-000205.diff.gz, not tested yet)

Extract bash-2.03.tar.gz (get it here : <ftp://ftp.gnu.org/pub/gnu> ) apply the following patch : <http://LinuxSH.free.fr/faq/bash-2.03-sh.diff> (It modifies configure, config.sub for SH3 target, and Makefile.in ) [Or apply NIIBE's patch instead, not tested yet]

        $ export CC='sh-linux-gcc -ml -m3'
        $ export RANLIB='sh-linux-ranlib'
        $ export AS='sh-linux-gcc -ml'
        $ export LD='sh-linux-ld -ml'
        $ export AR='sh-linux-ar'
        $ export BUILD_CC=gcc
        $ ./configure --prefix=/tftpboot/sh/local/ --host=sh3-linux --target=sh3-linux --with-curses --with-glibc-malloc
        $ make
        $ make install

SAD NOTE

3.6 How do I build a ramdisk filesystem for the kernel ?

        $ dd if=/dev/zero of=/dev/ram1 bs=1k count=2048
        $ mke2fs -vm0 /dev/ram1 2048
        $ mount /dev/ram1 /mnt/floppy

[Note : you can use anything you want instead of mount point /mnt/floppy] copy everything you want on /mnt/floppy, for example a raw system may be :

        $ mkdir -p /mnt/floppy/bin /mnt/floppy/dev /mnt/floppy/sbin /mnt/floppy/tmp /mnt/floppy/etc
        $ mkdir -p /mnt/floppy/var /mnt/floppy/var/run /mnt/floppy/var/tmp
        $ mkdir -p /mnt/floppy/usr /mnt/floppy/usr/share /mnt/floppy/usr/share/terminfo
        $ mkdir -p /mnt/floppy/usr/share/terminfo/l /mnt/floppy/usr/share/terminfo/v
        $ cp -p ~/minimum-termcap-000205 /mnt/floppy/etc/termcap
        $ cp -p /tftpboot/sh/local/bin/bash /mnt/floppy/bin
        $ (cd /mnt/bin; ln -s bash sh)
        $ mknod /mnt/floppy/dev/ttyS0 c 4 64
        $ mknod /mnt/floppy/dev/null c 1 3
        $ mknod /mnt/floppy/dev/tty c 5 0
        $ (cd /mnt/floppy/dev; ln -s ttyS0 console)
        $ echo '#\!/bin/sh' > /mnt/floppy/sbin/init
        $ chmod +x /mnt/floppy/sbin/init

Then make a file of it :

        $ umount /dev/ram1
        $ dd if=/dev/ram1 bs=1k count=2048 of=fs.img

If one day you want to remount it, for example to add programs, all you have to do is :

        $ mount fs.img /mnt/floppy -o loop
        $ ...
        $ umount /mnt/floppy

You can now compress it :

        $ gzip fs.img
        $

And prepare it for loading in memory (at 0x8c360000) for GDB :

        $ sh-linux-objcopy -I binary -O elf32-shl fs.img.gz --adjust-vma=0x8c360000 sh3-fs.img
        $

Copyright (C) 1999: Ludovic LANGE. Linux SH at free dot fr. The contents of this article reflect my opinions only and not necessarily those of my employer.

This article is provided as is without any express or implied warranties. While every effort has been taken to ensure the accuracy of the information contained in this article, the author, maintainer and contributors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

Windows is a trademark of Microsoft Corporation.

HTML conversion using txt2html