114 lines
4.4 KiB
Plaintext
114 lines
4.4 KiB
Plaintext
|
|
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.
|