Z88 Developers' Notes
Contents   Contents of System Calls

OS_Fep, Flash Card Interface

RST 20H, DEFW $C806

IN:
     A = reason code:
          FEP_CDID = $00 - Identify Flash Memory Chip in slot
          FEP_CDDT = $03 - Get Flash Card Data
          FEP_SCER = $06 - Erase sector in Flash Memory
          FEP_CDER = $09 - Erase entire Flash Memory
          FEP_FFMT = $0C - Flash Memory File Area Formatting
          FEP_WRBT = $0F - Write byte to the Flash Memory
          FEP_WRBL = $12 - Write a block of bytes to Flash Memory
          FEP_CPFL = $15 - Copy file entry between two File Areas
          FEP_RDFA = $18 - Reduce an existing "oz" File Area

     BC, DE, HL, IX arguments.
OUT:
     Fc = 1, A = error code.
     Fc = 0, reason code action successfully ended.

The OS_Fep is a new operating system interface implemented to manage the new Flash Card hardware. Two chip generations were used to build the 1MB cards. During 1996 the first generation prototype 1Mb Flash Cards were built by Thierry Peycru, and driven using a BBC BASIC program with embedded driver software to manage the Intel 28F series chip soldered to an original 32K EPROM card PCB. The program was designed to be a simple file manager to format a file area and to save/backup files to the cards inserted in slot 3. Later, in 1997, Rakewell licensed the technology, and the software to drive the card was open sourced by Thierry Peycru. The FlashStore code base was re-written and separated as an end-user application which linked to a set of standard library routines to manage the chip hardware and to implement high level File Card routines using the File Eprom format. This enabled all Z88 applications to be able to use the Flash Cards through the standard library (which is still maintained and available today). Around 2001, Intel decided to stop the manufacturing of the 1Mb flash chip. Luckily, AMD 29F generation Flash chip technology was available that was pin compatible which enabled Rakewell to keep manufacturing costs down and continue production of the 1Mb Flash Cards for the Z88. Further, this 3rd generation flash technology only required 5V to erase and blow bytes to the memory which allows the card to be manipulated in all slots of the Z88 hardware (Intel flash chip required 12V and VPP pin only available in slot 3). Rakewell is still using this hardware today (2007). The new OS_Fep interface is based upon the code base of the standard flash library routines, and tightly integrated into OZ for compactness and speed efficiency. The complete reference documentation for the Intel I28F008S5 (1Mb) chip can be read in this PDF document. The complete reference documentation for the AMD AM29F080B (1Mb) chip can be read in this PDF document. The software to drive the Intel and Amd chips were implemented on the basis of these two documents.

All OS_Fep mnemonic defintions are found in the "flashepr.def" file. All OS_Fep routines are used in FlashStore popdown which is now integrated into OZ V4.2.



FEP_CDID ($00) - Identify Flash Memory Chip in slot C

In:
        C = slot number (0, 1, 2 or 3)
Out:
        Success:
             Fc = 0, Fz = 1
             A = FE_28F or FE_29F, defining the Flash Memory chip generation
             HL = Flash Memory ID
                  H = Manufacturer Code (FE_INTEL_MFCD, FE_AMD_MFCD)
                  L = Device Code (refer to flashepr.def)
             B = total of 16K banks on Flash Memory Chip.

        Failure:
             Fc = 1
             A = RC_NFE (not a recognized Flash Memory Chip)

Registers changed on return:
   ...CDE../IXIY af...... same
   AFB...HL/.... ..bcdehl different



FEP_CDDT ($03) - Get Flash Card Data

IN:
   HL = Polled from Flash Memory Chip (see FEP_CDID):
        Manufacturer & Device Code

OUT:
   Fc = 0
      ID was found (verified):
      A = chip generation (FE_28F or FE_29F)
      B = total of 16K banks on Flash Memory
      CDE = extended pointer to null-terminated string description of chip
   Fc = 1
     ID was not found

Registers changed on return:
  ......HL/IXIY same
  AFBCDE../.... different



FEP_SCER ($06) - Erase sector in Flash Memory

Erase sector defined in B (00h-0Fh), on Flash Memory Card inserted in slot C.

The routine will internally ask the Flash Memory for identification and intelligently use the correct erasing algorithm. All known Flash Memory chips from INTEL, AMD & STM (see flashepr.def) uses 64K sectors, except the AM29F010B/ST29F010B 128K chip, which uses 16K sectors.

Important:
INTEL I28Fxxxx series Flash chips require the 12V VPP pin in slot 3 to successfully erase a block/sector on the memory chip. If the Flash Eprom card is inserted in slot 1 or 2, this routine will automatically report a sector erase failure error.

It is the responsibility of the application (before using this call) to evaluate the Flash Memory (using the OS_Fep, FEP_CDID API) and warn the user that an INTEL Flash Memory Card requires the Z88 slot 3 hardware, so this type of unnecessary error can be avoided.

IN:
        B = block/sector number on chip to be erased (00h - 0Fh)
            (available sector size and count depend on chip type)
        C = slot number (0, 1, 2 or 3) of Flash Memory Card
OUT:
        Success:
             Fc = 0
        Failure:
             Fc = 1
             A = RC_NFE (not a recognized Flash Memory Chip)
             A = RC_BER (error occurred when erasing block/sector)
             A = RC_VPL (Vpp Low Error)

Registers changed on return:
   ..BCDEHL/IXIY ........ same
   AF....../.... afbcdehl different



FEP_CDER ($09) - Erase entire Flash Memory

The routine will internally ask the Flash Memory for identification and intelligently use the correct erasing algorithm.

Important:
INTEL I28Fxxxx series Flash chips require the 12V VPP pin in slot 3 to successfully erase the memory chip. If the Flash Memory card is inserted in slot 1 or 2, this routine will automatically report a sector erase failure error.

It is the responsibility of the application (before using this call) to evaluate the Flash Memory (using the FlashEprCardId routine) and warn the user that an INTEL Flash Memory Card requires the Z88 slot 3 hardware, so this type of unnecessary error can be avoided.

IN:
        C = slot number (0, 1, 2 or 3) of Flash Memory
OUT:
        Success:
             Fc = 0
        Failure:
             Fc = 1
             A = RC_NFE (not a recognized Flash Memory Chip)
             A = RC_BER (error occurred when erasing block/sector)
             A = RC_VPL (Vpp Low Error)

Registers changed on return:
   ..BCDEHL/IXIY ........ same
   AF....../.... afbcdehl different



FEP_FFMT ($0C) - Flash Memory File Area Formatting

Create/reformat an "oz" File Area below application Rom Area, or on empty Flash Cards to create a normal "oz" File Eprom that is also recognized by Filer popdown in slot 3. Also reformat file areas that are embedded as part of application cards, located at top of card above the application area (automatically preserving 'OZ' header during reformat of file area).

An 'oz' file card header or 'OZ' application card header with embedded 'oz' file area watermark is 64 bytes large, and is located at the top (last bank) of the file area at offset $3FC0.

Defining 8 banks in the ROM Front DOR for applications will leave 58 banks for file storage in a 1Mb Flash Card. 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 screen is turned off while the file area is being formatted if it is in the same slot as the OZ ROM. During formatting, no interference should happen from Blink, because the Blink reads the font bitmaps each 1/100 second:

If the screen were enabled while formatting a 64K sector that is part of the OZ ROM address space, the font bitmaps would suddenly be unavailable which would create violent screen flickering during chip command mode. Further, and most importantly, to avoid the Blink doing read-cycles while chip is in command mode.

By switching off the screen, the Blink doesn't read the font bit maps in OZ ROM, and the Flash chip can be in command mode without being disturbed by the Blink.

Important:
Third generation AMD Flash Memory chips may be erased/programmed in all available slots (0-3). Only INTEL I28Fxxxx series Flash chips require the 12V VPP pin in slot 3 to successfully erase or blow data on the memory chip. If the Intel Flash Eprom card is inserted in slot 1 or 2, this routine will report a programming failure.

It is the responsibility of the application (before using this call) to evaluate the Flash Memory (using the OS_Fep, FEP_CDID routine) and warn the user that an INTEL Flash Memory Card requires the Z88 slot 3 hardware, so this type of unnecessary error can be avoided.

Due to a strange side effect with Intel Flash Chips, a special "NULL" file is saved as the first file to the Card. These bytes occupies the first bytes that otherwise could be interpreted as a random boot command for the Intel chip - the behaviour is an Intel chip suddenly gone into command mode for no particular reason.

The NULL file prevents this behaviour by saving a file that avoids any kind of boot commands which sends the chip into command mode when the card
has been inserted into a Z88 slot.

IN:
   C = slot number (0, 1, 2 or 3) of Flash Memory Card

OUT:
   Success:
        Fc = 0,
             BHL = pointer to File Header for slot C (B = absolute bank of slot).
                   (or pointer to free space in potential new File Area).
               C = size of File Eprom Area in 16K banks
             Fz = 1, File Header available
                  A = "oz" File Eprom sub type
                  D = size of card in 16K banks (0 - 64)

        All sectors erased and a new header blown.

   Failure:
        Fc = 1
            A = RC_ONF (File Eprom Card / Area not available; possibly no card in slot)
            A = RC_ROOM (No room for File Area; all banks used for applications)
            A = RC_NFE (not a recognized Flash Memory Chip)
            A = RC_BER (error occurred when erasing block/sector)
            A = RC_BWR (couldn't write header to Flash Memory)
            A = RC_VPL (Vpp Low Error)

Registers changed after return:
   ......../IXIY same
   AFBCDEHL/.... different



FEP_WRBT ($0F) - Write byte to the Flash Memory

Write a byte (in C) to the Flash Memory Card in slot x, at address BHL. BHL points to a bank, offset (which is part of the slot that the Flash Memory Card have been inserted into).

The routine can be told which programming algorithm to use (by specifying the FE_28F or FE_29F mnemonic in E); these parameters can be fetched when
investigated which Flash Memory chip is available in the slot, using the OS_Fep, FEP_CDID routine that reports these constants back to the caller.

However, if neither of the constants are provided in E, the routine can be specified with E = 0 which internally polls the Flash Memory for identification and intelligently use the correct programming algorithm.

Important
:
Third generation AMD Flash Memory chips may be erased/programmed in all available slots (0-3). Only INTEL I28Fxxxx series Flash chips require the 12V VPP pin in slot 3 to successfully erase or blow data on the memory chip. If the Intel Flash Eprom card is inserted in slot 1 or 2, this routine will report a programming failure.

It is the responsibility of the application (before using this call) to evaluate the Flash Memory (using the OS_Fep, FEP_CDID routine) and warn the user that an INTEL Flash Memory Card requires the Z88 slot 3 hardware, so this type of unnecessary error can be avoided.

In:
        C = byte to blow at address
        E = FE_28F, FE_29F or 0 (poll card for blowing algorithm)
        BHL = pointer to Flash Memory address (B=00h-FFh, HL=0000h-3FFFh)
              (bits 7,6 of B is the slot mask)
Out:
        Success:
             Fc = 0
        Failure:
             Fc = 1
             A = RC_BWR (programming of byte failed)
             A = RC_NFE (not a recognized Flash Memory Chip)
             A = RC_UNK (chip type is unknown: use only FE_28F, FE_29F or 0)

Registers changed on return:
   ..BCDEHL/IXIY ........ same
   AF....../.... afbcdehl different



FEP_WRBL ($12) - Write a block of bytes to Flash Memory

Write a block of bytes to the Flash Eprom Card, from address DE to BHL of block size IX. If a block will cross a bank boundary, it is automatically continued on the next adjacent bank of the card. On return, BHL points at the byte after the last written byte.

The routine is used by the File Eprom Management libraries, but is well suited for other application purposes.

The routine can be told which programming algorithm to use (by specifying the FE_28F or FE_29F mnemonic in C); these parameters can be fetched when
investigating which Flash Memory chip is available in the slot, using the FlashEprCardId routine that reports these constants.

However, if neither of the constants are provided in A, the routine can be specified with C = 0 which internally polls the Flash Memory for identification and intelligently use the correct programming algorithm. The identified FE_28F or FE_29F constant is returned to the caller in C for future reference (when the block was successfully programmed to the card).

Uses the segment mask of HL (where BHL memory will be bound into the Z80 address space to blow the block of bytes (MM_S0 - MM_S3), which has to be in a different segment than DE is referring.

BHL points to an absolute bank (which is part of the slot that the Flash Memory Card have been inserted into). Further, the local buffer must be available in local address space and not part of the segment used for blowing bytes.

Important:
Third generation AMD Flash Memory chips may be programmed in all available slots (0-3). Only INTEL I28Fxxxx series Flash chips require the 12V VPP pin in slot 3 to successfully blow data on the memory chip. If the Intel Flash Eprom card is inserted in slot 1 or 2, this routine will report a programming failure.

It is the responsibility of the application (before using this call) to evaluate the Flash Memory (using the OS_Fep, FEP_CDID routine) and warn the user that an INTEL Flash Memory Card requires the Z88 slot 3 hardware, so this type of unnecessary error can be avoided.

In :
        C = FE_28F, FE_29F or 0 (poll card for blowing algorithm)
        DE = local pointer to start of block (located in current address space)
        BHL = extended address to start of destination (pointer into card)
             (bits 7,6 of B is the slot mask)
             (bits 7,6 of H = MM_Sx segment mask for BHL)
        IX = size of block (at DE) to blow
Out:
        Success:
             Fc = 0
             C = FE_28F or FE_29F (depending on found card)
             BHL updated
        Failure:
             Fc = 1
             A = RC_BWR (block not blown properly)
             A = RC_NFE (not a recognized Flash Memory Chip)
             A = RC_UNK (chip type is unknown: use only FE_28F, FE_29F or 0)

Registers changed on return:
   ....DE../IXIY ........ same
   AFBC..HL/.... afbcdehl different



FEP_CPFL ($15) - Copy file entry between two File Areas

Copy file entry from one file area to another file area in slot C (or to file area in same slot).

The routine does NOT handle automatical "deletion" of existing files that matches the filename (excl. device). This must be used by a call to OS_Epr, EP_Delete. Should the actual process of blowing the file image fail, the new File Entry will be marked as deleted, if possible.

The screen is turned off while the file entry is being copied to the file area of the same slot as the OZ ROM. During copying no interference should happen from Blink, because the Blink reads the font bitmaps each 1/100 second:

If the screen were enabled while copying a file entry to a file area being part of the OZ ROM address space, the font bitmaps would suddenly be unavailable which would create violent screen flickering during chip command mode. Further, and most importantly, to avoid the Blink doing read-cycles while chip is in command mode.

By switching off the screen, the Blink doesn't read the font bit maps in OZ ROM, and the Flash chip can be in command mode without being disturbed by the Blink.

Important:
Third generation AMD Flash Memory chips may be programmed in all available slots (0-3). Only INTEL I28Fxxxx series Flash chips require the 12V VPP pin in slot 3 to successfully blow data on the memory chip. If the Intel Flash Eprom card is inserted in slot 1 or 2, this routine will report a programming failure.

It is the responsibility of the application (before using this call) to evaluate the Flash Memory (using the OS_Fep, FEP_CDID routine) and warn the user that an INTEL Flash Memory Card requires the Z88 slot 3 hardware, so this type of unnecessary error can be avoided.

IN:
          C = slot number (0, 1, 2 or 3)
        BHL = pointer to file entry to be copied
OUT:
        Fc = 0,
             File successfully copied to File Area in slot C.
        Fc = 1,
             File (Flash) Eprom not available in slot C:
                  A = RC_Nfe (not a recognized Flash Memory Chip)
             File Entry at BHL was not found, or no file area in slot C:
                  A = RC_Onf
             No sufficient space to store file (and File Entry Header) in slot C:
                  A = RC_Room
             Flash Write Errors:
                  If possible, the new File Entry is marked as deleted.
                  A = RC_Vpl, RC_Bwr (see "flashepr.def" for details)

Registers changed on return:
   ..BCDEHL/IXIY ........ same
   AF....../.... afbcdehl different



FEP_RDFA ($18) - Reduce an existing "oz" File Area

Reduce an existing "oz" File Area below application/OZ Rom Area, or on sole Flash Card by one or several 64K sectors. Reduction is done on Flash sector size, ie. 64K.

This routine will signal failure ("file area not found") if an application wants to reduce a file area that is part of the OZ ROM in slot 0. A file area in slot is located above the OZ area and as a different layout structure which cannot be shrinked.

 IN:
    B = total sectors to reduce file area
    C = slot number (0, 1, 2 or 3) of Flash Memory Card

 OUT:
    Success:
         Fc = 0,
         BHL = absolute pointer to new "oz" header in card
         C = Number of 16K banks of File Eprom Area

         Current files in file area are intact.
         New header blown (for reduced file area) and old header sector erased.

    Failure:
         Fc = 1
             A = RC_ONF (File Eprom Card / Area not available; possibly no card in slot)
             A = RC_ROOM (File area cannot be reduced - files are located inside reducing sector)
             A = RC_NFE (not a recognized Flash Memory Chip)
             A = RC_BER (error occurred when erasing block/sector)
             A = RC_BWR (couldn't write header to Flash Memory)
             A = RC_VPL (Vpp Low Error)

 Registers changed after return:
    ....DE../IXIY same
    AFBC..HL/.... different