
Board Overview
-----------------------------

The Worcester IQ80321 board is an evaluation platform for Intel's 80321 Xscale
CPU (sometimes called IOP321 chipset).

The 80321 contains a single PCI hose (called the ATUs), a PCI-to-PCI bridge,
two DMA channels, I2C, I2O messaging unit, XOR unit for RAID operations,
a bus performance monitoring unit, and a memory controller with ECC features.

For more information on the board, see http://developer.intel.com/iio

Port Status
-----------------------------

Supported:

- MTD/JFFS/JFFS2 root
- NFS root
- RAMDISK root
- Serial port (ttyS0)
- Cache/TLB locking on 80321 CPU
- Performance monitoring unit on 80321 CPU

TODO:

- DMA engines
- I2C
- 80321 Bus Performance Monitor
- Application Accelerator Unit (XOR engine for RAID)
- I2O Messaging Unit
- I2C unit
- SSP

Building the Kernel
-----------------------------
make iq80321_config
make oldconfig
make zImage

This will build an image setup for BOOTP/NFS root support.  To change this,
just run make menuconfig and disable nfs root or add a "root=" option.

Preparing the Hardware
-----------------------------

Make sure you do an 'fis init' command once you boot with the new
RedBoot image.

Downloading Linux
-----------------------------

Assuming you have your development system setup to act as a bootp/dhcp
server and running tftp:

NOTE: The 80321 board uses a different default memory map than the 80310.

   RedBoot> load -r -b 0x01008000 -m y

Once the download is completed:

   RedBoot> go 0x01008000

There is a version of RedBoot floating around that has DHCP support, but
I've never been able to cleanly transfer a kernel image and have it run.

Root Devices
-----------------------------

A kernel is not useful without a root filesystem, and you have several
choices with this board:  NFS root, RAMDISK, or JFFS/JFFS2.  For development
purposes, it is suggested that you use NFS root for easy access to various
tools.  Once you're ready to deploy, probably want to utilize JFFS/JFFS2 on
the flash device.

MTD on the IQ80321
-----------------------------

Linux on the IQ80321 supports RedBoot FIS paritioning if it is enabled.
Out of the box, once you've done 'fis init' on RedBoot, you will get
the following partitioning scheme:

   root@192.168.0.14:~# cat /proc/mtd
   dev:    size   erasesize  name
   mtd0: 00040000 00020000 "RedBoot"
   mtd1: 00040000 00020000 "RedBoot[backup]"
   mtd2: 0075f000 00020000 "unallocated space"
   mtd3: 00001000 00020000 "RedBoot config"
   mtd4: 00020000 00020000 "FIS directory"

To create an FIS directory, you need to use the fis command in RedBoot.
As an example, you can burn the kernel into the flash once it's downloaded:

   RedBoot> fis create -b 0x01008000 -l 0x8CBAC -r 0x01008000 -f 0x80000 kernel
   ... Erase from 0x00080000-0x00120000: .....
   ... Program from 0x01008000-0x01094bac at 0x00080000: .....
   ... Unlock from 0x007e0000-0x00800000: .
   ... Erase from 0x007e0000-0x00800000: .
   ... Program from 0x01fdf000-0x01fff000 at 0x007e0000: .
   ... Lock from 0x007e0000-0x00800000: .

   RedBoot> fis list
   Name              FLASH addr  Mem addr    Length      Entry point
   RedBoot           0x00000000  0x00000000  0x00040000  0x00000000
   RedBoot[backup]   0x00040000  0x00040000  0x00040000  0x00000000
   RedBoot config    0x007DF000  0x007DF000  0x00001000  0x00000000
   FIS directory     0x007E0000  0x007E0000  0x00020000  0x00000000
   kernel            0x00080000  0x01008000  0x000A0000  0x00000000

This leads to the following Linux MTD setup:

   mtroot@192.168.0.14:~# cat /proc/mtd
   dev:    size   erasesize  name
   mtd0: 00040000 00020000 "RedBoot"
   mtd1: 00040000 00020000 "RedBoot[backup]"
   mtd2: 000a0000 00020000 "kernel"
   mtd3: 006bf000 00020000 "unallocated space"
   mtd4: 00001000 00020000 "RedBoot config"
   mtd5: 00020000 00020000 "FIS directory"

Note that there is not a 1:1 mapping to the number of RedBoot paritions to
MTD partitions as unused space also gets allocated into MTD partitions.

As an aside, the -r option when creating the Kernel entry allows you to
simply do an 'fis load kernel' to copy the image from flash into memory.
You can then do an 'fis go 0x01008000' to start Linux.

If you choose to use static partitioning instead of the RedBoot partioning:

   /dev/mtd0  0x00000000 - 0x0007ffff: Boot Monitor     (512k)
   /dev/mtd1  0x00080000 - 0x0011ffff: Kernel Image     (640K)
   /dev/mtd2  0x00120000 - 0x0071ffff: File System      (6M)
   /dev/mtd3  0x00720000 - 0x00800000: RedBoot Reserved (896K)

To use a JFFS1/2 root FS, you need to donwload the JFFS image using either
tftp or ymodem, and then copy it to flash:

   RedBoot> load -r -b 0x01000000 /tftpboot/jffs.img
   Raw file loaded 0x01000000-0x01600000
   RedBoot> fis create -b 0x01000000 -l 0x600000 -f 0x120000 jffs
   ... Erase from 0x00120000-0x00720000: ..................................
   ... Program from 0x01000000-0x01600000 at 0x00120000: ..................
   ......................
   ... Unlock from 0x007e0000-0x00800000: .
   ... Erase from 0x007e0000-0x00800000: .
   ... Program from 0x01fdf000-0x01fff000 at 0x007e0000: .
   ... Lock from 0x007e0000-0x00800000: .
   RedBoot> fis list
   Name              FLASH addr  Mem addr    Length      Entry point
   RedBoot           0x00000000  0x00000000  0x00040000  0x00000000
   RedBoot[backup]   0x00040000  0x00040000  0x00040000  0x00000000
   RedBoot config    0x007DF000  0x007DF000  0x00001000  0x00000000
   FIS directory     0x007E0000  0x007E0000  0x00020000  0x00000000
   kernel            0x00080000  0x01008000  0x000A0000  0x01008000
   jffs              0x00120000  0x00120000  0x00600000  0x00000000

This looks like this in Linux:

   root@192.168.0.14:~# cat /proc/mtd
   dev:    size   erasesize  name
   mtd0: 00040000 00020000 "RedBoot"
   mtd1: 00040000 00020000 "RedBoot[backup]"
   mtd2: 000a0000 00020000 "kernel"
   mtd3: 00600000 00020000 "jffs"
   mtd4: 000bf000 00020000 "unallocated space"
   mtd5: 00001000 00020000 "RedBoot config"
   mtd6: 00020000 00020000 "FIS directory"

You need to boot the kernel once and watch the boot messages to see how the
JFFS RedBoot partition mapped into the MTD partition scheme.

You can grab a pre-built JFFS image to use as a root file system at:

   ftp://source.mvista.com/pub/xscale/iq80310/jffs.img

For detailed info on using MTD and creating a JFFS image go to:

   http://www.linux-mtd.infradead.org.

For details on using RedBoot's FIS commands, type 'fis help' or consult
your RedBoot manual.

BUGS and ISSUES
-----------------------------

* As shipped from Intel, pre-production boards have two issues:

- The on board ethernet is disabled S8E1-2 is off. You will need to turn it on.

- The PCIXCAPs are configured for a 100Mhz clock, but the clock selected is
  actually only 66Mhz. This causes the wrong PPL multiplier to be used and the
  board only runs at 400Mhz instead of 600Mhz. The way to observe this is to
  use a independent clock to time a "sleep 10" command from the prompt. If it
  takes 15 seconds instead of 10, you are running at 400Mhz.

- The experimental IOP310 drivers for the AAU, DMA, etc. are not supported yet.

Contributors
-----------------------------
The port to the IQ80321 was performed by:

Rory Bolt <rorybolt@pacbell.net> - Initial port, debugging.

This port was based on the IQ80310 port with the following contributors:

Nicolas Pitre <nico@cam.org> - Initial port, cleanup, debugging
Matt Porter <mporter@mvista.com> - PCI subsystem development, debugging
Tim Sanders <tsanders@sanders.org> - Initial PCI code
Deepak Saxena <dsaxena@mvista.com> - Cleanup, debug, cache lock, PMU

The port is currently maintained by Deepak Saxena <dsaxena@mvista.com>

-----------------------------
Enjoy.
