 *********************************************************************************

 FlashStore File Format library for Z88 Flash Eprom card 
 (Development release, due to integration with FlashStore App V1.6.9)
 
 All routines are "Open Source" as designed by the GPL.

 This text describes a reference of all the basic routines to manipulate the
 Flash Eprom Card and their interface arguments. 
 For further information, please refer to the actual source file.

 The core data structure of the FlashStore Filing system is the Partition Header,
 located in the top bank of the partition. This header is not used when a 
 Std. Z88 File Eprom Area is located below an Application area. Please refer
 to the "flstore.def" file for definition of header and other interface
 mnemonics.
  
 All routines may be executed in slot 3 on a Flash Eprom.
 This is possible since they all indirect library routines which uses the
 Z80 stack for execution while the Flash Eprom is in non-read-array-mode.
 
 Design & programming by:
	Gunther Strube, InterLogic, April 1998

 *********************************************************************************

 Filename:			Library name:					Description:
 ---------------------------------------------------------------------------------
 Fstore				library project file to be used for compiling
 Fstore.lib			object file library

 FStPtId.asm			LIB FlashStore_CheckPartitionID	Check presence of FlashStore 
 												Partition Identifier.
 
 FStNxPid.asm			XLIB FlashStore_NextPartitionID	Get pointer to next 
 												Partition Identifier, or 
 												to Free space.

 FStFrmt.asm			XLIB FlashStoreFormat			Create,remove partitions
 
 FstFinfo.asm			XLIB FlashStoreFileEntryInfo		File Entry Management in
												FlashStore File Partition
												Outlined, but not implemented.

 FStFepr.asm			XLIB FlashStoreFileEpr			FlashStore File Eprom /
 												"oz" File Eprom.
 

; *********************************************************************************
;
;	XLIB FlashStoreDelSpace
;
; FlashStore File Eprom Format.
;
; Return amount of deleted file space on File Eprom, inserted in slot C.
;
; IN:
;	C = slot number containing File Eprom
;
; OUT:
;	Fc = 0, File Eprom available
;		DEBC = Amount of deleted file space used on File Eprom
;
;	Fc = 1, File Eprom was not found in slot C.
;
; Registers changed after return:
;	......HL/IXIY same
;	AFBCDE../.... different
;
; *********************************************************************************

 
; *********************************************************************************
;
;	XLIB FlashStoreFileEpr
;
; FlashStore File Eprom/"oz" File Eprom.
;
; Request for partition and "oz" File Eprom information on 
; Flash Eprom Application Card.
;
; In:
;	A = function reason codes
; 		FSFLE_SCPT 	SCan for first ParTition File Area
; 		FSFLE_NXPT	Get NeXt ParTition File Area
;
;	entry arguments depending on request code
;
; Out:
;	results depend on entry arguments
;
; -----------------------------------------------------------------------
;
; FSFLE_SCPT:
;
;	1) Check for a standard "oz" File Eprom, if that fails -
; 	2) Check that slot contains an Application ROM, then check for the 
; 	   Header Identifier in the first top block below reserved 
; 	   application banks on the card.
;	3) If a Rom Front Dor is located in a RAM Card, then this slot
;	   is regarded as a non-valid card as a File Eprom, ie. not present.
;
; 	On partial success, if a Header Identifier is not found, the
; 	returned pointer indicates that the card might hold a file area, 
; 	beginning at this location.
;
;	If the routine returns HL = @3FE0, it's a FS II partition (32 byte header)
;	If the routine returns HL = @3FC0, it's an "oz" partition (64 byte header)
;
; In:
;		C = slot number (1, 2 or 3)
;
; Out:
;	Success, first (top) partition (or potential) available:
;		Fc = 0,
;
;			BHL = pointer to top Partition ID for slot C (B = slot relative).
;				 (or pointer to free space in File Area).
;			Fz = 1, File Header found
;				A = Device Code of Flash Eprom (or "oz" File Eprom sub type)
;				C = size of card in 16K banks (0 - 64)
;				D = size of partition in 16K banks
;			Fz = 0, File Header not found
;				A undefined
;				C undefined
;				D undefined
;	Failure:
;		Fc = 1,
;			RC_ONF:
;				FlashStore File Area not available (possibly no ROM card)
;				nor any std. File Eprom "oz" header.
;			RC_ROOM, No room for File Area (all banks used for applications)
;
; Registers changed after return:
;	.....E../IXIY same
;	AFBCD.HL/.... different
;
; -----------------------------------------------------------------------
;
; FSFLE_NXPT:
;
; 	Check that BHL points to a real Partition ID, then return pointer
; 	to the next (lower) Partition ID on the Flash Eprom.
; 	If a Partition ID is not found, the returned pointer indicates the
; 	beginning of free Partition File Area that might be created.
;
; In:
;		C = slot number (1, 2 or 3)
;		BHL = pointer to existing Partition ID on card.
;
; Out:
;	Success, next partition (or potential) found:
;		Fc = 0,
;			Fz = 1, Partition ID found
;				BHL = pointer to Partition ID for slot C.
;				A = Device Code of Flash Eprom
;				C = size of card in 16K banks (0 - 64)
;				D = size of partition in 16K banks
;			Fz = 0, Partition ID not found, but free space
;				BHL = pointer to potential Partition ID for slot C.
;				A undefined
;				C undefined
;				D undefined
;	Failure:
;		Fc = 1,
;			RC_ONF, Current Partition ID not found or recognized
;			RC_ROOM, Current Partition ID was the last in File Area
;
; Registers changed after return:
;	.....E../IXIY same
;	AFBCD.HL/.... different
;
; *********************************************************************************


; *********************************************************************************
;
;	XLIB FlashStoreFormat
;
; 1MB Flash Eprom File Area Formatting/partitioning of free banks that are 
; not used on the Flash Eprom, where the ROM Front DOR only defines space 
; for application code.
;
; Defining 8 banks in the ROM Front DOR for applications will leave 58
; banks for file storage. This scheme is however always performed with
; only formatting the Flash Eprom in free modulus 64K blocks, ie.
; having defined 5 banks for ROM would "waste" three banks for 
; applications.
;
; Hence, ROM Front DOR definitions should always define bank reserved 
; for applications in modulus 64K, eg. 4 banks, 8, 12, etc...
;
; The first Partition Identifier on the Flash Eprom is blown at the top 
; bank of the availabe File Area. Then, the next partition follows in
; a number of lower adjacent 64K blocks.
;
; This routine also handles the creation of the sub File Eprom below
; an application area.
;
; IN:
;	A = reason code:
;		FSFMT_CRPT 	CReate ParTition
;		FSFMT_EXPT	EXtend ParTition with next (lower) Partition
;		FSFMT_ERPT	ERase ParTition
;		FSFMT_RMPT	ReMove ParTitions/erase whole File Area
;		FSFMT_FRPT	Get FRee void space for PaRtition
;
; -----------------------------------------------------------------------
;
; FSFMT_ERPT:
;
; Format existing Partition in Flash Eprom File Area.
; All 64K blocks in partition will be erased, and the Partition Identifier
; will be updated with new format time/date stamp and format counter.
; All other Identifier information will remain identical.
;
; IN:
;	BHL = pointer to Partition ID location on Flash Eprom (slot relative)
;
; OUT:
;	Success:
;		Fc = 0, erased successfully, Partion Identifier updated at (BHL)
;		A = size of partition in 64K blocks
;	Failure:
;		Fc = 1
;		A = Error code
;
; Registers changed after return:
;	..BCDEHL/IXIY same
;	AF....../.... different
;	
; -----------------------------------------------------------------------
;
; FSFMT_CRPT:
;
; Create FS II Partition or "oz" File Area in Flash Eprom (in slot 3).
;
; When creating an "oz" File Eprom, ALL remaining space is ALWAYS used 
; in File Area (B parameter is ignored).
;
; IN:
;	B = Total of 64K Blocks for FS II partition, or 0 (use remaining void space).
;	DE = ptr. to label, null-terminated string, for partition
;
;	DE = 0, create "oz" File Eprom (use remaining free space of Eprom)
;
; OUT:
;	Success:
;		Fc = 0
;		A = number of allocated blocks for partition/"oz" area
;		BHL = pointer to Partition Identifier/"oz" header (slot relative)
;
;	Failure:
;		Fc = 1
;		A = Error code
;
; Registers changed after return:
;	...CDE../IXIY same
;	AFB...HL/.... different
;
; -----------------------------------------------------------------------
;
; FSFMT_EXPT:
;
; Extend Partition in Flash Eprom File Area (in slot 3) with Partition
; below the specified or with the void space available.
;
; IN:
;	BHL = pointer to Partition Identifier (slot relative)
;
; OUT:
;	Success:
;		Fc = 0
;		A = number of re-allocated 64K blocks for partition
;
;	Failure:
;		Fc = 1
;		A = Error code
;
; Registers changed after return:
;	..BCDEHL/IXIY same
;	AF....../.... different
;	
; -----------------------------------------------------------------------
;
; FSFMT_RMPT:
;
; Remove Partitions in Flash Eprom File Area.
; All 64K blocks in the File Area will be erased. All Partitions with 
; file contents will be lost.
;
; IN:
;	-
;
; OUT:
;	Success:
;		Fc = 0, File Area on Flash Eprom erased successfully.
;		(Complete File Area contains $FF bytes)
;
;	Failure:
;		Fc = 1
;		(Blocks could not be formatted or Flash Eprom not available)
;		A = Error code
;
; Registers changed after return:
;	..BCDEHL/IXIY same
;	AF....../.... different
;	
; -----------------------------------------------------------------------
;
; FSFMT_FRPT:
;
; Get Free Partition Space in File Area, returned in modulus 64K blocks,
; of slot specified in C register.
;
; IN:
;	C = slot number (1, 2 or 3)
;
; OUT:
;	Success:
;		Fc = 0, Free Partition Space in File Area
;		A = Total of Free 64K blocks
;		BHL = (slot relative) pointer to potential Partition Identifier
;
;	Failure:
;		Fc = 1
;		A = Error code
;
; Registers changed after return:
;	...CDE../IXIY same
;	AFB...HL/.... different
;	
; *********************************************************************************

 
; *********************************************************************************
;
;	XLIB FlashStore_NextPartitionID
;
; Internal support library routine.
; Get pointer to next Partition Identifier, or to Free space.
; 
; IN:
;	BHL = (absolute) pointer to current (valid) Partition Identifier
;		 (or "oz" File Eprom section)
;	D = size of current Partition in 16K banks
;
; OUT:
;	Fc = 0, 
;		Next Partition ID found, or pointer to free space
;		Fz = 1, Partition Identifier found at BHL.
;			A = Intel Chip Device Code
;			C = size of physical Card in 16K banks (defined by Device Code)
;			D = Size of Partition in 16K banks
;		Fz = 0, Partition Identifier not found (potential free space)
;			A undefined
;			C undefined
;			D undefined
;	Fc = 1,
;		No next partition ID or free space.
;		The entry Partition ID was the last on the card.
;
; Registers changed after return:
;	.....EHL/IXIY same
;	AFBCD.../.... different
;
; *********************************************************************************


; *********************************************************************************
;
;	XLIB FlashStore_CheckPartitionID
;
; Check presence of FlashStore Partition Identifier.
; This is an internal, low level routine used by high level library
; routines for validation of a Partition Identifier in the specified bank B.
;
; IN:
;	BHL = absolute pointer to potential Partition Identifier, $xFE0 or $xF00
;	(B = must be defined for specific bank in specific slot, 
;	 HL = must be masked to specific segment that is free for bank binding)
;
; OUT:
;	Fc = 0 always.
;
;	Fz = 1, Partition Identifier found at BHL.
;		A = Intel Chip Device Code
;		C = size of physical Card in 16K banks (defined by Device Code)
;		D = Size of Partition in 16K banks
;	Fz = 0, Partition Identifier not found.
;		A undefined
;		C undefined
;		D undefined
;
; Registers changed after return:
;	..B..EHL/IXIY same
;	AF.CD.../.... different
;
; *********************************************************************************

