Kopenhagen, 9th March, 1998

<Introduction>

This document describes the standard Flash Eprom Library for the 1MB Flash
Eprom, used in conjunction with the Z80 Module Assembler for the Z88, or 
equivalent cross assembler versions on other platforms (MSDOS, etc.). 

The library enables you to write data to the new Rakewell/Zlab 1MB Intel 
Flash Eprom Card. Reading data from the card is done through the usual bank
binding and reading techniques as with other Z88 memory.

If you want further information about the chip hardware, please look at
Rakewell's Homepage, http://homepages.nildram.co.uk/~rakewell .


<The Library>

This library contains 7 main routines. They are as follows:

	FlashEprCardId          Obtain the Intel chip ID
	FlashEprBlockErase      Erase/format 64K memory blocks
	FlashEprVppOn           Enable VPP in slot 3, reset chip
	FlashEprVppOff          Disable VPP in slot 3, reset chip
	FlashEprWriteBlock      Write/blow a block of bytes (max 16K)
	FlashEprWriteByte       Write/blow a single byte
	CheckBattLow            Check for battery low condition

The library also contains some additional common (internal) support 
routines. These are not documented, and should be regarded as low level and
important to the application.


<Using the library>

The routines are easily interfaced into your source file by specifying
a LIB directive at the top (or before the actual reference of the routine).
For example:

	LIB FlashEprCardId
	...
	CALL FlashEprCardId

Then, when compiling your software, remember to specify the library at the
command line of the assembler, for example added with the standard library:

     Z80ASM -istdfep -istandard #yourproject


<Using the "flashepr.def" file>

The included definition file contains various constant mnemonic definitions
to better identify codes, applying a more readable form of the magic numbers.
Please include this file with the other OZ definition files in your
assembler workbench development setup. You will also see these definitions
in the library documentation below.


<Important>

To ensure 100% safe programming of data to the Flash Eprom, it is vital that
you check the battery low status before blowing data to the card. 

All the write/blow routines verify the data and return an error condition if
something went wrong. Still, it is better to ensure that sufficient battery 
power is available before starting the actual blowing process.

The <CheckBattLow> routine will return the hardware status of the batteries.


<Copyright notice>

These routines are freeware, and may be used in your application software 
as long as you make a notice in your software documentation or on-line 
help about the usage of these routines and the copyright holders:

	Standard Flash Eprom Library by:
		Copyright (C) Gunther Strube, InterLogic, Dec 1997-98
		Copyright (C) Thierry Peycru, Zlab, Dec 1997-98


<Contacting the authors>

You may reach either Gunther Strube or Thierry Peycru on the Internet:
	gbs@image.dk (Gunther Strube)
	tpeycru@club-internet.fr (Thierry Peycru)


; ***************************************************************************
; LIB FlashEprCardId
;
; Intel Flash Eprom Chip Identification.
;
; Warning:
; This routine cannot be executed on the Flash Eprom Card
; (in slot 3), since the Flash Eprom is not in Read Array Mode
; while the Chip Identification is being performed.
;
; ---------------------------------------------------------------
;
; Design & programming by
;	Gunther Strube, InterLogic, Dec 1997
;	Thierry Peycru, Zlab, Dec 1997
;
; ---------------------------------------------------------------
;
; In:
;		-
; Out:
;		Success:
;			Fc = 0
;			Fz = 1
;			A = Intel Device Code
;				FE_i016 ($AA), an INTEL 28F016S5 (2048K)
;				FE_i008 ($A2), an INTEL 28F008SA (1024K)
;				FE_i8s5 ($A6), an INTEL 28F008S5 (1024K)
;				FE_i004 ($A7), an INTEL 28F004S5 (512K)
;				FE_i020 ($BD), an INTEL 28F020 (256K)
;			B = total of 64K blocks on Flash Eprom.
;
;		Failure:
;			Fc = 1
;			A = RC_NFE (not a recognised Intel Flash Eprom)
;
; Registers changed on return:
;	...CDEHL/IXIY same
;	AFB...../.... different
;
; ***************************************************************************


; ***************************************************************************
; LIB FlashEprVppOn
;
; Set Flash Eprom chip in programming mode (in slot 3)
;
; 1) set Vpp (12V) on
; 2) clear the chip status register
;
; --------------------------------------------------------------------------
;
; Design & programming by
;	Gunther Strube, InterLogic, Dec 1997
;	Thierry Peycru, Zlab, Dec 1997
;
; --------------------------------------------------------------------------
;
; IN:
;		-
; OUT:
;		-
;
; Registers changed on return:
;	AFBCDEHL/IXIY same
;	......../.... different
;
; ***************************************************************************


; ***************************************************************************
; LIB FlashEprVppOff
;
; Disable VPP (in slot 3) and reset Flash Eprom chip in read array mode 
; (like a standard eprom chip)
;
; 1) Set Vpp (12V) off
; 2) Reset Flash Eprom Chip
;
; --------------------------------------------------------------------------
;
; Design & programming by
;	Gunther Strube, InterLogic, Dec 1997
;	Thierry Peycru, Zlab, Dec 1997
;
; --------------------------------------------------------------------------
;
; In:
;		-
; Out:
;		-
;
; Registers changed on return:
;	AFBCDEHL/IXIY same
;	......../.... different
;
; ***************************************************************************


; ***************************************************************************
; LIB FlashEprBlockErase
;
; Erase Flash Eprom 64K Block number, defined in A (0 - xx)
; (16 blocks in total define the 1MB chip size, 32 = 2MB chip...)
;
; Warning:
; This routine cannot be executed on the Flash Eprom Card
; (in slot 3), since the Flash Eprom is not in Read Array Mode
; while a 64K block is being erased.
;
; ---------------------------------------------------------------
;
; Design & programming by:
;	Gunther Strube, InterLogic, Dec 1997-98
;	Thierry Peycru, Zlab, Dec 1997-98
;
; ---------------------------------------------------------------
;
; IN:
;		A = 64K Block number on chip to be erased (0 - xx)
;			(available block numbers depend on chip size)
;
; OUT:
;		Success:
;			Fc = 0
;			A = 0
;		Failure:
;			Fc = 1
;			A = RC_VPL (VPP was not set)
;			    RC_BER (block was not erased properly)
;
; Registers changed on return:
;	..BCDEHL/IXIY same
;	AF....../.... different
;
; ***************************************************************************


; ***************************************************************************
; LIB FlashEprWriteBlock
;
; Write a block of bytes to the Flash Eprom Card (in slot 3), from address
; DE to BHL of block size IX.
;
; This routine is primarily used for File Eprom management, but is well
; suited for other purposes.
;
; Use segment specifier C to blow the bytes in Flash Eprom Bank (MS_S0 - MS_S3)
;
; BHL pointer is assumed relative, ie. B = 00h - 3Fh, HL = 0000h - 3FFFh.
;
; This routine assumes that Vpp is enabled (CALL'ed FlashEprVppOn routine),
; and that local source buffer is available in Z80 address space.
;
; Further, the local buffer must be available in local address space and not
; part of the segment used for blowing bytes. 
;
; The routine writes across adjacent bank boundaries on the Flash Eprom, 
; ie. writing 16K at $3e, offset $2000 would blow the last byte at $3f, 
; offset $1FFF.
;
; On return, BHL points at the byte after the last written byte.
; (BHL returned relative to slot 3, B=00h-3Fh, HL=0000h-3FFFh)
;
; Warning:
; This routine cannot be executed on the Flash Eprom Card
; (in slot 3), since the Flash Eprom is not in Read Array Mode
; while the block of data is being blown.
;
; --------------------------------------------------------------------------
;
; Design & programming by
;	Gunther Strube, InterLogic, Dec 1997, Jan 1998
;	Thierry Peycru, Zlab, Dec 1997
;
; --------------------------------------------------------------------------
;
; In :
;		DE = local pointer to start of block (available in address space)
;		C = MS_Sx segment specifier (for bank on Flash Eprom)
;		BHL = extended address to start of Flash Eprom address
;		IX = size of block to blow, beginning at (DE)
; Out:
;		Success:
;			Fc = 0
;			BHL updated (relative pointer)
;		Failure:
;			Fc = 1
;			A = RC_VPL (VPP was not set)
;			    RC_BWR (write error)
;
; Registers changed on return:
;	A..CDE../IXIY same
;	.FB...HL/.... different
;
; ***************************************************************************


; ***************************************************************************
; LIB FlashEprWriteByte
;
; Write a byte to the Flash Eprom Card (in slot 3), at address BHL.
;
; BHL pointer is assumed relative, ie. B = 00h - 3Fh, HL = 0000h - 3FFFh.
;
; This routine also assumes that Vpp is enabled (CALL'ed FlashEprVppOn
; routine).
;
; Warning:
; This routine cannot be executed on the Flash Eprom Card
; (in slot 3), since the Flash Eprom is not in Read Array Mode
; while the byte is being blown.
;
; --------------------------------------------------------------------------
;
; Design & programming by
;	Gunther Strube, InterLogic, Dec 1997, Jan '98
;	Thierry Peycru, Zlab, Dec 1997, Jan '98
;
; --------------------------------------------------------------------------
;
; In:
;		A = byte
;		BHL = pointer to Flash Eprom address (B=00h-3Fh, HL=0000h-3FFFh)
; Out:
;		Success:
;			A = A(in)
;			Fc = 0
;		Failure:
;			Fc = 1
;			A = RC_VPL (VPP was not set)
;			    RC_BWR (write error)
;
; Registers changed on return:
;	A.BCDEHL/IXIY same
;	.F....../.... different
;
; ***************************************************************************


; ***************************************************************************
; LIB CheckBattLow
;
; Check Battery Low Status
;
; Design & Programming, InterLogic 1997, Gunther Strube
;
; In:
;		None
;
; Out:
;		Fc = 1, Battery condition is low
;		Fc = 0, Battery condition is OK.
;
; Design & programming by Gunther Strube, InterLogic, Dec 1997
;
; Registers changed after return:
;	A.BCDEHL/IXIY same
;	.F....../.... different
;
; ***************************************************************************