

===============================
VECTREX - DS2430A EEPROM Driver

Copyright Alex Herbert 2003

Web:   www.herbs64.com
Email: herbs64@yahoo.co.uk
===============================



                --- DRAFT ---




Introduction
------------


The DS2430A is a 32-byte EEPROM which uses the 1-Wire Serial protocol.
There are other types of 1-wire devices but this document concentrates on
the DS2430A.

All communication with the a 1-wire device is through a single data line,
which fits in very neatly with the single I/O line (PB6) available at the
Vectrex cartridge socket.

In fact, even the power is supplied to the device through this data line.
Since the DS2430A requires more current than the I/O line can deliver, a
resistor (3.3k, 1%, 0.25w) must be connected between the data line and +5v.

Mark Shaker's cartridge PCBs are ready wired for these components and are
available from www.vectrexcarts.com.  (Thanks Mark!)




Driver Overview
---------------


The following source files are included in this package:


        DS1W.I
        ------

        This contains the basic low-level I/O functions required to
        communicate with any single 1-Wire device.  (Multi-device networks
        are beyond the scope of this driver.)


        DS2430LS.I
        ----------

        Routines to Load/Save (read/write) a 32-byte block of memory from/to
        a DS2430A EEPROM.


        DS2430V.I
        ---------

        Expands on the above to include a Verify (compare memory to EEPROM)
        function.


        EXAMPLE.S
        ---------

        An example implementation of the driver (as used in Protector/YASI).




Driver Quick-Start
------------------


Ok, let's start with EXAMPLE.S since it provides a quick, easy and robust way
of adding EEPROM support to your project.


Variables defined:

        eeprom_buffer (32 bytes)
        -------------

        The first 31 bytes should contain the variables you want to
        save/restore.  The 32nd byte (eeprom_buffer+31) is used to store a
        checksum in order to validate the EEPROM contents.


Data required:

        eeprom_defaults (31 bytes)
        ---------------

        This should contain the default data used to initialize the EEPROM.


Routines:

        eeprom_save
        -----------

        This first creates a valid checksum and stores it in the last byte
        of eeprom_buffer.  It then compares the entire buffer with the
        contents of the EEPROM.  If they are different, the buffer will be
        written to the EEPROM.


        eeprom_format
        -------------

        Copies 31 bytes from eeprom_defualts to eeprom_buffer, then calls
        eeprom_save.


        eeprom_load
        -----------

        Loads the EEPROM contents to eeprom_buffer.  The checksum is then
        tested to determine if the data is valid.  If the checksum is not
        valid then eeprom_format is called.


Usage:

eeprom_load - Should be called once at boot.  eeprom_buffer will always
contain valid data after calling eeprom_load.  If valid data was found in
the EEPROM, then that will be used.  If no valid data was found (possibly
because the EEPROM is blank or there is no device connected) then
eeprom_defaults will be used.


eeprom_save - Call at any point where saving the data would be appropriate.
For example, YASI stores the display calibration settings, the top score and
unlocked game modes.  It makes sense in this instance to place a single call
to eeprom_save just before the title screen is displayed, as this always
occurs immediately after calibrating the display and the Game Over screen.


eeprom_format - It's best to provide the end user with some means to reset
the EEPROM to a known state.




The Driver in Detail
--------------------


I recommend that in addition to this text you refer to the DS2430A datasheet.
(Free to download from www.dalsemi.com or www.maxim-ic.com)


Low Level 1-Wire Communication:

The 6522 PIA I/O line PB6 is connected to the EEPROM data line and is tied
to +5v with a resistor, and will normally read logic 1.  Either device (PIA
or EEPROM) can exert a signal on this line by pulling it low, which reads
logic 0.  (It is advised that PB6 is never set to output 1.)

Pulling the data line low will deprive the EEPROM of a power source, but a
small capacitor built into the device will keep it going throughout normal
communication where the line only goes low for short periods of time.



Commands and data are transmitted to the device as a series of long/short
low pulses indicating binary 0/1.

Data is read from the device in a similar manner, but in this instance
each bit must be started by the Vectrex.  The data line is pulled low
momentarily then released.  The memory device will then either allow the
data line to go high immediately (indicating binary 1) or it will hold it
low for a moment (binary 0).

The transmit/receive order is predetermined and dependent on the command
issued.

Before each command sequence is issued, the device must be reset. This is
achieved by pulling the line low for a longer period of time (>480us). When
the line goes back high, the chip will restart in it's reset state. Shortly
after, the device will respond with a short pulse indicating that a 1-wire
device is present.

The timings for these pulses are set out in detail in the DS2430A datasheet.



The include file "DS1W.I" contains the low-level routines to handle this
signalling:


        ds1w_open
        ---------

        Prepares the 6522 PIA for comminication with a 1-Wire device
        attached to PB6.  Bit 6 of the Port B Data register is cleared,
        ready for output.  Bit 7 is set in the PB Data register and cleared
        in the Aux Control register to prevent CRT deflection when Timer 1
        is used.

        This must be called before attempting communication with the
        device.


        ds1w_close
        ----------

        Bit 7 of Aux Control is set to return Timer 1 to it's normal state
        for performing timed vectors.

        For robustness it's recommended that no unrelated I/O operations
        are perfomed between calls to ds1w_open and ds1w_close


        ds1w_reset
        ----------

        Resets the 1-Wire device and checks for presence pulse.  The
        result code in A will be zero if a device was detected, or -1 if
        no device was detected.  (The Z and N flags are also set
        accoridngly.)


        ds1w_txbyte
        -----------

        Transmits the byte in A to the device.


        ds1w_rxbyte
        -----------

        Reads 1 byte from the device into A.


The 1-Wire protocol dictates a minimum command set which is common to all
1-Wire devices.  Constants for these are defined in the above file.  They
are:

        DS1W_READROM - this it to read the chip's ROM which contains its
        device code and unique serial number.  (Not normally used since we
        should know which type of device is connected.)

        DS1W_SKIPROM - this skips ROM reading and allows access to the device
        specific commands.

        DS1W_SEARCHROM and DS1W_MATCHROM are used to identify and select
        individual devices when more than one are connected to the same
        data line.  This is beyond the scope of this driver and are not
        used.



Ok, time to move onto the DS2430A specific stuff...

The DS2430A has an intermediate 32-byte RAM buffer, or Scratch Pad (SP) where
data can be freely read/written.  It is not possible to read/write individual
bytes directly from/to the actual EEPROM storeage, but instead we must copy
the entire EEPROM to the Scratch Pad first, or vice versa.

The include file "DS2430LS.I" contains constants for the DS2430A commands
and routines for loading the entire EEPROM to Vectrex RAM and saving RAM to
EEPROM, via the Scratch Pad.


        ds2430_load
        -----------

        This routine loads 32 bytes from the EEPROM to Vectrex RAM.
        On entry, X should hold the address of where the data is to be loaded.
        On exit, A will be 0 if the load was successful.

        How it works:

        The routine starts by calling ds1w_open followed by ds1w_reset.
        If no device is detected, ds1w_close is called and the routine exits.
        If a presence pulse is detected then a DS1W_SKIPROM command byte
        is sent (ds1w_txbyte) to access the device specific commands.

        Next a DS2430_READMEM command is sent which copies the entire EEPROM
        memory to the Scratch Pad.  This command also allows reading the SP,
        so next a zero byte is sent indicating the SP address of the first
        byte we want to read.

        Finally, ds1w_rxbyte is called 32 times to read the SP to Vectrex
        RAM.


        ds2430_save
        -----------

        This routine saves 32 bytes of Vectrex RAM (or ROM) to the EEPROM.
        On entry X should hold the start address of the data to be saved.
        On exit, A will be 0 if the save was successful.

        How it works:

        It starts exactly the same as ds2430_load up to and including the
        DS1W_SKIPROM command.

        Next a DS2430_WRITESP command followed by a zero is sent to
        initiate writing to the Scratch Pad from address 0.  Then
        ds1w_txbyte is called 32 times to write Vectrex RAM to the SP.

        The device is then reset and a DS1W_SKIPROM command issued. (To get
        back to the device specific commands.)

        Now a DS2430_COPYSP command is sent to instruct the device to copy
        the SP to EEPROM.  But before the SP is actually commited to EEPROM
        a validation byte (DS2430_VALKEY) must be sent.  (This feature helps
        prevent the EEPROM from being overwritten by spurious I/O.)

        Lastly, the routine waits for 10 milliseconds to prevent activity
        on the data line whilst the SP is actually copied to EEPROM.



Include file "DS2430V.I" has one more routine for EEPROM management:


        ds2430_verify
        -------------

        This is functionally very similar to ds2430_load, but rather than
        copy the EEPROM contents to Vectrex RAM, it just compares the two.
        On entry, X should hold the start address of the data to be compared.
        On exit, A will be 0 if the contents of the EEPROM match, non-0 if
        it doesn't.



The DS2430A has other device specific commands.  These are always issued after
sending a DS1W_SKIPROM command (or DS1W_MATCHROM for networked devices).
Constants for these commands are defined in "DS2430LS.I" but I haven't
provided routines for them in this driver pack.  Refer to the DS2430 datasheet
for more information.


