
GrLinux README file
-----------------------------------------------

Introduction
------------

GrLinux is a package to install a simple slackware linux version
(splack) on a leon3-based system.  The leon3 system needs to have
at least one hard disk or CF card with ~ 500 Mbyte of free space.
The leon3 processor must also be configured with the memory management 
unit (MMU) and the floating-point unit (FPU) enabled. Suitable FPGA
bitfiles are providedfor a few suitable development boards.

Concept of operation
--------------------

A GrLinux boots as follows: the linux-2.6 kernel is 
programmed into the boot PROM of the processor board, and configured
to mount a hard disk or CF card as root mount point. Once the
root is mounted, all start-up scripts are taken from the disk
as during a normal linux boot. No loader (Lilo or Grub) are used.
Suitable kernels to be programmed into the flash PROM are provided,
and can also be built from snapgear-1.0.25 for leon.

Package contents
----------------

alt-ep2c20/leon3mp.sof	LEON3 FPGA bitfile for Altera Cyclone EP1C20 board

ge-mini/leon3mini.bit	LEON3 FPGA bitfile for Hpe-mini-lattice board
ge-mini/image.flashbz	Linux kernel flash image for Hpe-mini-lattice

gr-xc3s/leon3mp.bit	LEON3 FPGA bitfile for GR-XC3S-1500 board
gr-xc3s/image.flashbz 	Linux kernel flash image for GR-XC3S-1500 board

image.dsu		Linux kernel DSU image (RAM image, no loader)
image-nomount.dsu	Linux kernel DSU image for disk preparation

splack-1.0.tar.gz	Tar-file with splack distribution (available separately)


Installation
------------

Running linux from a hard disk is made by using a linux
which is configured to mount the first partition of the 
hard disk as root file system. The kernel itself is 
programmed into the flash memory, and will boot 
automatically on power-on.

Perform the installation in the follwing steps:

1. Program the FPGA with the suitable FPGA bit file. Provided
   files contains a leon3mmu system with ATA controller, GRETH
   Ethernet MAC, and an SDRAM or DDR controller. The lattice
   board should have a 256 Mbyte DDR module installed in the 
   SODIMM socket.

2. Program the linux kernel (image.flashbz) in the board's boot
   flash using grmon. Use the following grmon commands:

   flash erase all
   flash load image.flashbz	

3. Install the splack-1.0.tar.gz file on the target CF disk.
   This is done by partitioning a hard drive such that the first
   partition (hda1) contains an ext2 file system, and then
   untaring the file on it using: tar xzpf splack-1.0.tar.gz.

Preparing the hard drive
------------------------

Partitioning the hard drive can be made using a laptop or
desktop computer, or by using the target hardware. For the
last option, do as follows:

1. Attach the hard drive to the target system, and load the
   image-nomount.dsu kernel via grmon (don't forget -nb).

2. Start the loaded kernel and partition the the disk using fdisk.
   Create the first partion as ext2 (type 83). Optionally,
   create the second partition as swap (type 82). The ext2
   partition must be about 500 Mbyte to hold the splack files.
   Exit fdisk with a 'w' to write the partition table.

3. Create an ext2 file system on partition 1:

   mke2fs /dev/hda1

4. If you have created a swap partion on hda2, initialize it:

   mkswap /dev/hda2

To untar the splack files on hda1 on a target system, it is
possible to mount a remote sever using NFS, and then access
the tar file over the network. The following commands can
serve as an example:

mount 192.168.0.32:/home/jiri /mnt/nfs
mount /dev/hda1 /mnt/hd
cd /mnt/hd
tar xzpf /mnt/nfs/splack-1.0.tar.gz
umount /mnt/hd

Booting from disk
-----------------

Connect the hard disk and power-on the board. Make sure
a terminal emulator is connected to the serial port at 38400 baud.
The first boot after power up will fail on the lattice board because
the DDR RAM needs to be manually reset. Push the reset and the
kernel should boot and mount this CF disk.

The root password is set to "qwerqwer".


ALWAYS terminate the system using the 'shutdown -h' command
before switching of the power. This will sync the file systems. 
Wait until you see the following message before switching of power
(or resetting the board):

Shutdown: hda                                                                   
Power down.      


Applications and networking
---------------------------

The most basic linux applications are provided on the disk,
including gcc and networking. The system's hostname is set
to leon3soc, and the network IP is set to 192.168.0.99.
It is possible to change this by running netconfig. Do NOT
connect multiple boards to the same network as they have
identical ethernet addresses ...


GRMON
-----

This package contains a modified version of grmon that is
able to display the attache disk drives through the 'ata'
command. Also note that the provided fpga bitfiles are both
configured with ethernet DSU. The IP number for the DSU
is 192.168.0.64 for the lattice board and 192.168.0.51 for
the Spartan3 board. The IP number is also listed in 'info sys'
and can be changed through the edcl command.

Send comments or suggestions to jiri@gaisler.com .

Jiri.
