last modified: 2002-07-25

Content:
========
This document describes how to extend the zprommer for new chiptypes

Author:
=======
Martin Williges (Martin.Williges@zut.de)

General structure of zprommer
=============================
The source code of the program consists of 3 types of files:

-user interface (main.c)
-common functions for the prommer hardware (common.c, common.h)
-chip specific funtions (2764.[c|h] 28010.[c|h]....)

How to add a new type of chip
=============================

In short:
---------
1) Get the data sheet of your new chip. Especially the timing
   characteristics are important.

2) copy the chip specific files (.c/.h) of the chip who comes closest to your
   new type and name them after your new type.

3) modify the .c/.h files according to the data sheet.

4) modify those parts of main.c who parse command line input and those who
   call the chip specific functions.

5) add the new files to the Makefile and compile

6) check it out

7) check it again

8) check it even more

9) hunt bugs

10) MAIL ME A MESSAGE with your sources as attachement so I can put the
    program with your shiny new chiptype interface on my homepage.

Long version:
-------------
1) Get the data sheet. Probably a data sheet the new chiptype is available
via internet. Search google or other search engines for "TYPE DATA SHEET"
or "TYPE DATASHEET". What you need is
-the chip's pinout and pin names
-the timing characteristics for each access mode

2) see short version

3-4) Modify the source

Add the chiptype and the number of bytes in config.h

Copy .c and .h file of the chip which comes closest to your new chip and
name the copy like your new chip. Take care naming - some chips with nearly the
same name are different! E.g. CAT28F010P is not the same as M28010.

Now rename all functions that carry the chip's name in your new .c and .h
file. In the newly created files adjust those functions that set your
control pins (e.g. #OE, #PGM, #WE). Those functions are just other names for
the functions defined in common.c/common.h  This is done for readability of
the code. If for example your #PGM is needed by pin 29 (textool socket): Look
up in the eprommer's schematics which lpt-port pin switches pin29: It's X1-5.
So your remapping-functions is as follows:

-------------------------------------
inline void f_28010_pgm(int value)
{
        /* Set WE according to value WE is accessed by #INIT_PRINTER (X1-5)*/
        common_setpin_x1_5(value);
}
-------------------------------------

Be shure to use underscores (not minus) in the function's name. If your
specific common_setpin-function is not existent, you have to program it by
yourself in common.c. Caution with new setpin functions: The ones with
inverted logic (e.g. X1-17) are inverted in hardware so that setting the
port to 1 means 0V. Don't forget to list the function's prototype in
common.h.

Your adress counter has to be modified according to the number of adress
lines your new chiptype has. The adresscounter function is named "void
incadr_28010(unsigned int actual_adress)" or something like that, according
to the chip name. For adress lines A0...A15 there is a common function named
"common_inc16bitadr" which counts the first 16 adress lines. Higher lines have
to be set separately by common_setpin-functiones.

The reset for the adress counter has to be modified just like the increment
function to match the number of adress lines of your part.

Rewrite the write, read and evt. erase functions according to your timing
diagrams in the data sheet. Use the funtions

	f_chiptype_oe, f_chiptype_we or how you named them

to acces the devices control pins. Use 

	incadr_chiptype and resadr_chiptype

to set up the adresses. Use

	common_nanowait(xx)

to set delays. Use

	common_makesafe();

to bring the programmer into safe (for the chip) state.

So much for the chip specific files. You now have to extend main.c
to recognize your chip. Have a look. Extend the functions

	chip_read(), chip_write(), chip_erase() and help_types()

for your chip types. Somewhere in 

	parse_cmdline()

there is a part that looks for known chiptypes. Extend this section for your
new type. Finally, add the new header file to the ones already listed in the
beginning of main.c.

5) Add your file with the ".o" extension in the line which shows the object
files in the Makefile. Try a "make". If there are errors, you made something
wrong. Try to find out what.

6-9) Play with the new chiptype until you are shure others can use it
without problems.

10) Create a tar.gz archive and mail it to me. Describe your new chiptype
briefly.

That's it! I will be thankful for any extension of the program.

There might be another way for you to add a new chip type to the program, if
you are unable to program: Send 2 of the chips to me together with the data
sheet and I might extend the program by myself. But don't expect a fixed date
when this will happen!


FAQs
====

The name "zprommer"?
--------------------
The program is named "zprommer" because my nick is "zut". zprommer stands
for "zut's eprommer".
