README
=========================

2003-12-28 Josef Wolf (jw@raven.inka.de)
2008-06-27 Matthew Riek (matthew.riek@ibiscomputer.com.au)

Flashlib is invoked using bdmctrl.  See the *.test script files in
bdm/m68k/utils as examples on how to bootstrap a board and invoke flashlib
for flashing.  See also bdm/m68k/utils/README.bdmctrl

Overview
=========================

Following is a rough overview of the flashlib architecture:

filter: 

	The filter is the main interface to the application. The application
	don't really need to know about the flash driver details. Filter's
	write_memory() function is the flashing aequivalent of the memcpy()
	function.  write_memory can write to flash or ram, depending on 
        the memory region of the write.

driver: 

	A driver is the implementation of a specific flashing algorithm.
        examples are flash29, flashcfm and flashintelc3.  If the algorithm
        or chip definition for your flash is not supported, you will need
        to either add a chip to the chip tables (flash29 and flashintelc3)
        or you will have to write a new driver.

chip description: 

	The chip description describes details of a flash chip. What
	information needs to be stored in the description is up to
	the driver. Most drivers will probably want to store at	least 
	chip-type and bus-interface.  Some flash drivers (such as flashcfm)
	don't need a chip description table.  Instead, you can configure
	the required bits such as flash register offsets using flash_set_var.

flash region: 

	A flash region describes specific flash chips (depending on the
	bus interface). The most important information herein is the
	base-address, the length, the driver and the chip description.

plugin: 

	A driver that can be downloaded and executed on the target.  

	Note that you don't _need_ plugins.  You can use host only mode,
	which is very slow, plugins just make flashing much much faster.

	A plugin is simply compiling just the driver '.c' file for your 
	target.  For example, If you have a 29 series flash chip on your
	board, you would compile flash29.c using your cross compiler
	toolchain.  Only a few header files are needed (the associated
	header file flash29.h, flash_filter.h and stdint.h.  note that
	when you compile the drivers as a plugin, you must define 
	HOST_FLASHING as 0. (-DHOST_FLASHING=0 for gcc).  You need to
	compile with -mpcrel such that the code is relocatable.  I have
	compiled all current drivers successfully using a m68k-elf gnu
	toolchain (version 4.3.0), and with the m68k-rtems4.9 toolchain.

	m68k-elf-gcc -DHOST_FLASHING=0 -O2 -Wall -fomit-frame-pointer \ 
	  -mpcrel -m<CPU> -Wcast-align -Wstrict-prototypes \
	  -Wmissing-prototypes -c -o <driver>.plugin <driver>.c

	where <driver> is one of flashcfm, flash29 or flashintelc3.
	and <CPU> is your 68k arch, such as 5200, 5307, 528x etc.

	There is a script provided which compiles the plugins which
	takes 2 args, your compiler and your target.  eg:
	>./compile_plugins m68k-elf-gcc 5200
        or
	>./compile_plugins m68k-rtems4.9-gcc 5200

	you will need to copy the plugins to the working folder you
	invoke the bdmctrl scripts from.

host-only mode: 

	All operations are piped through the BDM interface. This is
	extremely slow but very useful for bootstrapping/debugging. 
	Spend the time to compile plugins for your target

host-assisted mode: 

	Host downloads plugin. The actual flashing operation is executed
	by the plugin. This is the preferred operation mode for flashing
	under host-control.

target-only mode: 

	This mode is for operation without a host. compile filter and 
	drivers for the target with HOST_FLASHING = 0. This could be used
	for boot loaders etc.  This option has not been completed, there
	are a few FIXME's noted in the flash_filter.c where bit's for
	target-only mode remain unimplemented.  uses of malloc, free,
	strdup may need to be provided with hooks in this mode.

How to write a new driver
=========================

Best is to start with a copy of flash29.[ch]. You should rename the
init_flash29() function and add the new function to the algorithm[] array
in flash_filter.c. Next is to give a new value to the driver_magic string.
This name should be unique because it is used to identify the driver
that belongs to a loaded plugin. Change the download_struct() function to 
download the chip description structure of the new driver properly to the
target. Make sure byte orderings and alignment is not messed up while
downloading.