NOTE: This is a preliminary note that has not undergone full peer
review. Use with some caution, but this should be somewhat helpful.


Table of Contents
-----------------
Introduction
Boot-block Sector Considerations
bbload Based System Partition Scheme Considerations
pmon Based System Partition Scheme Considerations
Multiple ROM Partition Scheme Considerations
Single FLASH, bbload Based System Partition Example
Two FLASH, pmon Based System Partition Example
Partition Calculations and Protections


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

This white paper is intended to provide quidelines on setting up jffs2
flash partitions for developers on BRECIS Linux systems. 

Setting new flash partitions is often a multi-pass process. The
process consists of the following steps:

develop partition scheme (identify purpose and size requirements for
        each partition),
build with these estimates,
adjust scheme if the binary sizes don't fit,
and finally, build again

The partition scheme is kept in the file:
uClinux/linux/drivers/mtd/maps/brecis_flashmap.c This file contains
definitions of the total address space used, and of the address space
of each defined partition.



Boot-block Sector Considerations
--------------------------------

Many flash devices (such as the Toshiba TC58FVT321 used on the BRECIS
MSP EVM boards) have a bank of sectors that require special circuitry
for write operations. The BRECIS EVM boards do not support programming
these sectors. Since these block sectors (sometimes called
boot-blocks) are not the same as the other flash sectors, they must be
put in a partition by themselves. In the parts used on the BRECIS EVM
boards, roughly 1.5% (64k/4M) of the total storage capability is lost
by ignoring these special sectors.



Partition Size Considerations
-----------------------------

Two items need to be considered for setting flash partition sizes. For
partitions which hold only one data block (such a load image), the
partition needs to have enough flash sectors to hold the data. Also,
if this data is expected to grow, sectors need to be reserved
to handle the additional data.

For partitions which hold many files, such as a general file storage
area, the jffs2 file structure reserves between 3 and 5 sectors for
overhead. Relatively small partitions (such as an 8 sector partition
described later) may lose half of the reserved space for overhead.



bbload Based System Partition Scheme Considerations
---------------------------------------------------

bbload, with BRECIS Linux on the BRECIS EVM platform, requires
a minimum of 5 partitions. These are defined for the bbload
binary, the bbload script, general storage, the BRECIS Linux load
image, and the reserved boot-block sectors. In the FLASH devices
used on the BRECIS MSP EVM boards, each sector is 64 kBytes, except
the top-boot block sectors which total 64 kBytes.

The bbload and bbload script partitions hold only one file each, and
both easily fit in one 64 kByte sector partition each. Physically, the
bbload partition must be stored at the bottom (zero offset) of the
FLASH device. The reserved top-boot block (as used on the BRECIS MSP
EVM boards) partition is physically at the top of the FLASH device.



pmon Based System Partition Scheme Considerations
-------------------------------------------------

pmon, on the BRECIS EVM platform, requires a minimum of 4 partitions.
These are defined for the pmon binary, the pmon script, general
storage and the reserved boot-block sectors. In the FLASH devices
used on the BRECIS MSP EVM boards, each sector is 64 kBytes, except
the top-boot block sectors which total 64 kBytes.

The pmon and pmon script partitions hold only only one file each, but
pmon needs at least 3 sectors. Physically, the pmon partition must be
stored at the bottom (zero offset) of the FLASH device. The reserved
top-boot block (as used on the BRECIS MSP EVM boards) partition is
physically at the top of the FLASH device.



Multiple ROM Considerations
---------------------------

The BRECIS MSP default settings for CS0 define an 8 mByte address
space, that starts at an address of 0xbf80,0000, and that boots at a 4
mByte offset within that space. Due to the use of a 4 mByte Flash
device, and address wrapping, effectively, the 4 mByte FLASH device
boots at offset zero. If one is defining a partitioning scheme for a
single 4 mByte FLASH device for CS0, the effective starting address
will be 0xbfc0,0000 and the effective ending address will be
0xbfff,ffff.

The BRECIS MSP default setting for CS1 define a 4 mByte address space,
that starts at an address of 0xbe00,0000. The starting address is
simply 0xbe00,0000 and the ending address is 0xbe3f,0000.

To design a partitioning scheme to use both of these address spaces,
reserve the address space from 0xbe00,0000 through 0xbfff,ffff (this
window size is 0x1ff,ffff). The space that is unused (0xbe79,000
through 0xbf3f,fff) and the space that is mirrored (0xbf80,0000
through 0xbfbf,ffff) can be lumped into a single partition which is
not used (similar to the partition defined for the reserved boot block
sectors).

So with two 4 mByte FLASH devices, a partition can be defined in the CS1
of maximum size 4 mByte (minus 64 kBytes of boot block sectors), and a
large general storage partition can be defined in the CS0 of a maximum
size of 4 mByte (minus 196 kBytes for bbload, bbload-scripts and
resevered boot block sectors)

However, the definitions of the size of the MSP ELB Chip Selects can
be adjusted. Note, that it is difficult to modify the boot Chip Select
(CS0) since this holds the boot code itself. The CS1 Chip Select can
be modified in bbload and pmon, allowing for a smaller FLASH device
for general storage, and/or a larger FLASH device for larger load
images.

To change the chip select settings when using pmon, one modifies the
file, pmon/pmon/a5000rom.s   Please see the code following "Program
External Local Bus CS"

To change the chip select settings when using bbload, one modifies the
file, bbload/mips/a5000.s   Please see the code following "Program
External Local Bus CS"




Single FLASH, bbload Based System Partition Example
---------------------------------------------------

Using a single 4 mByte FLASH device, five partitions are used. The
following is the physical layout:

Block          # of sectors   Address Space
-----          ------------   -------------
bbload               1            64k
bbload-script        1            64k
general              8           512k (256k? usable)
load image          53           3.4m
reserved             1            64k

The following are the definitions used to create this scheme (from the
file uClinux/linux/drivers/mtd/maps/brecis_flashmap.c):

static const struct b_flash_info b_flash_board_desc[PHYSMAP_NUMBER] = 
{
	{   // Brecis EVM configuration
		"flash",         // name
		0xbfc00000,      // window_addr (note: could have been 0xbf800000)
		0x00400000,      // window_size
		1,               // buswidth
		5,               // num_partitions
	}

};

static struct mtd_partition b_flash_partitions[PHYSMAP_NUMBER][MAX_PHYSMAP_PARTITIONS] = {
	{   // Brecis EVM configuration
		{
			name: "general storage",
			size: 0x80000, 
			offset: 0x20000,
		},
		{
			name: "bbload",
			size: 0x10000, 
			offset: 0,
		},
		{
			name: "bbload start script",
			size: 0x10000, 
			offset: 0x10000,
		},
		{
			name: "load image",
			size: 0x350000, 
			offset: 0xA0000,
		},
		{
			name: "region with copyprotected blocks",
			size: 0x10000,
			offset: 0x3f0000,
		},
	},
};



Two FLASH, pmon Based System Partition Example
----------------------------------------------

Using a two FLASH devices and a pmon based system, 6 partitions are
used. This example will assume an 8 mByte FLASH device is used for CS1
to hold the load image and a 4 mByte FLASH device is used for CS0 for
pmon and general storage. The following is the physical layout:

Block          # of sectors   Address Space
-----          ------------   -------------
load image(CS1)    121           7.9m
reserved(CS1+gap)  327          21.4m
pmon                 3           196k
pmon-script          1            64k
general             59           3.8m
reserved(CS0)        1            64k

The following are the definitions used to create this scheme (from the
file uClinux/drivers/mtd/maps/brecis_flashmap.c):

static const struct b_flash_info b_flash_board_desc[PHYSMAP_NUMBER] = 
{
	{   // Brecis EVM configuration
		"flash",         // name
		0xbe000000,      // window_addr start
		0x02000000,      // window_size
		1,               // buswidth
		5,               // num_partitions
	}

};

static struct mtd_partition b_flash_partitions[PHYSMAP_NUMBER][MAX_PHYSMAP_PARTITIONS] = {
	{   // Brecis EVM configuration
		{
			name: "general partition",
			size:   0x003b0000, 
			offset: 0x01c40000,         // end of CS0
		},
		{
			name: "pmon",
			size:   0x00030000, 
			offset: 0x01c00000,         // beginning of CS0
		},
		{
			name: "pmon script",
			size:   0x00010000, 
			offset: 0x01c30000,         // after pmon (CS0)
		},
		{
			name: "load image",
			size:   0x00790000, 
			offset: 0x00000000,         // beginning of CS1
		},
		{
			name: "middle gap region - reserved",
			size:   0x01470000,
			offset: 0x00790000,         // end of CS1 through mirror of CS0
		},
		{
			name: "reserved top-boot region",
			size:   0x00010000,
			offset: 0x01ff0000,         // end of CS0
		},
	},
};


Partition Calculations and Protections
--------------------------------------

Explaining the built-in protections against overlapping is easy. There
aren't any! If the partitions overlap and are filled, the overlapped
partition will be overwritten and corrupted.

There is a small spreadsheet,
uClinux/documentation/partition_sizer.xls, that can help build
consistant tables. Simply enter the hex sizes desired for the physical
partitions, and the spreadsheet calculates the hex offset for each
partition. 

Note, while the spreadsheet works with the Linux tool "gnumeric", when
using Microsoft Excel, the Analysis Tool-Pak needs to be installed for
the hex<->decimal conversions.



