Initial documentation pages

This commit is contained in:
Tom Nisbet 2020-06-28 14:28:35 -04:00
parent 8961f7e3ff
commit 0243de7231
5 changed files with 246 additions and 0 deletions

38
docs/28C256-notes.md Normal file
View File

@ -0,0 +1,38 @@
---
title: 28C256 Notes
has_children: false
nav_order: 3
---
# Notes on 28C EEPROMs
The 28C series parallel EEPROMS, like the 28C256, support fast block writes and algorithms to implement Software Data Protection (SDP). The SDP feature seems to be a leading cause of problems for people trying to program these chips with Arduino or other homebrew hardware.
The first problem many people encounter is that new chips are often locked, even though the datasheet states that they should ship unlocked. It isn't clear if the manufacturing practices have changed or if this might be due to used or conterfeit chips. In any case, the chips may need to be unlocked before they can be programmed for the first time.
The unlock is accomplished by sending a sequence of bytes to specific addresses. Many people have reported problems with this step when using DIY programmers. Some programmers may not be writing the SDP sequences quickly enough to successfully unlock the chips and yet others will report that the same hardware works correctly. This may be due to variences in the behavior of chips from different manufacturers.
When writing SDP lock/unlock sequences, the datasheets note that the timing between bytes must follow the same restrictions as page writes. In particular, the bytes must be written within the tBLC (Byte Load Cycle time). On Atmel parts, this is specified as 150us max, so each write pulse must occur within 150us of the previous write. The tBLC value is even shorter on the Xicor and ON Semi datasheets, stating that the writes must occur within 100us of each other.
In practice, the Xicor chips seem very forgiving of the timing, doing successful SDP and page write operations even when the tBLC is close to 200us. Atmel chips, on the other hand, will refuse to unlock when the timing is outside the acceptable maximum.
# Solution
The TommyProm programmer uses direct port access on the Arduino to control the data bus and addressing shift register. This is much faster than doing individual DigitalWrite calls and allows the unlock and page write code to run comfortably within the tBLC constraints. It has been successfully tested with the following 28C256 chips:
* Atmel AT28C256-15PU
* Catalyst/ON Semi CSI CAT28C256P-12
* Xicor X28C256P-15
* Xicor X28C256P-25
The Atmel chips tested included a batch from eBay that may not have been genuine, but they were unlocked and burned successfully with the TommyProm code.
The capture below shows an unlock command sequence where the tBLC us within 80us for each byte.
![Unlock Timing](docs/Unlock-Timing.png)
# References
1. [Atmel AT28C256 Data Sheet, 0006MPEEPR12/09](http://ww1.microchip.com/downloads/en/DeviceDoc/doc0006.pdf)
1. [Xicor, Intersil, Renesas X28C256 Data Sheet, 3855-1.9 8/1/97 T1/C0/D8 EW](https://www.renesas.com/us/en/www/doc/datasheet/x28hc256.pdf)
1. [ON Semiconductor CAT28C256 Data Sheet, CAT28C256/D, December, 2009 Rev. 6](https://www.onsemi.com/pub/Collateral/CAT28C256-D.PDF)
1. [Parallel EEPROM Data Protection Application Note, Atmel, Rev. 0543C10/98](http://ww1.microchip.com/downloads/en/AppNotes/DOC0543.PDF)

27
docs/extending.md Normal file
View File

@ -0,0 +1,27 @@
---
title: Extension
has_children: false
nav_order: 3
---
# Extending the design to new chip families
## Hardware
There are currently two hardware flavors - one for 28C series EEPROMs and one specifically for the Intel 8255A UV EPROM. The 8755A chip uses a multiplexed set of address and data lines that are directly driven by the Arduino. Most other chips will not use this addressing method. The 8755A design aslso includes a circuit to switch the programming voltage under software control. This may be useful for other chips that use non-5V programming voltages, although many of these chips, like the 27 series EPROMS, have a programming voltage that remains for the entire write and verify cycle. For those chips, it may be easier to simply switch the programming voltage manually.
The basic hardware design, used for the 28C family. is much more adaptable to additional chip families. This design uses two shift registers to create 16 dedicated address lines from only 3 arduino pins. This design, plus manual switching of the program voltage, would be very adaptable to EPROMs like the 2716, 2764, 27040, and 272001. The hardware has already been used with these chips for read-only operations.
The current design can directly address chips as large as 512K bytes, like the 29C040. Use the shift registers to for A0..A15 and wire Arduino pins D10..D12 to A16..A18.
# Software
The software design is modular, allowing easy extenstion for chips with different programming algoritms. A new class can be added for each new chip family. This class will include code for byte reads, byte writes, and optional block writes, if the chip supports it. All of the chip-specific code will be in this single class.
The basic steps to support a new chip are as follows:
* Create or copy an existing PromDeviceXX class to create a new .cpp and .h file for the chip-specific code.
* Define the pin assignments and implement the chip-specific setAddress, readByte, and burnByte code in the new files. The setAddress code can call the PromAddressDriver code if the shift register address hardware is used.
* If supported, also add chip-specific burnBlock code.
* Be sure that the new files have unique #if defined code that matches the class name.
* Edit Configure.h to add the conditional code includes the new PromDevice subclass.
* Edit TommyPROM.ino to add the conditional code that declares the new device.
Note that after files are added or renamed in the TommyPROM directory, the project needs to be reopened in Arduino IDE to get the changes.

69
docs/index.md Normal file
View File

@ -0,0 +1,69 @@
---
title: Overview
has_children: false
nav_order: 1
---
# TommyPROM - An Arduino-based EEPROM programmer
This is a simple EEPROM programmer and reader that can be assembled using an Arduino and a few additional parts. It has been sucessfully built using the Arduino UNO, Nano and Boarduino models.
The original code was specific to the 28C256 32Kx8 EEPROM, but it has been extended to also support Intel 8755A EPROMS and some 29C010 Flash.
The 28C design can be used with other 5V EEPROMS as well. Many 5V chips, including UV EPROMs, such as the 2716, 2764, 27C2001 and 27C040, can be read, but not written, with the basic hardware. Some pin changes may be needed to get the signals to the correct pins on the device. See the [extension readme](README-extension.md) for details on suggested hardware and software changes needed to support new EPROM and EEPROM families.
The PROM-specific code is modular and can be easily adapted to support additional devices. There are currently drivers and hardware designs for 28C series EEPROMS and the Intel 8755A EPROM.
Some 29C series chips, like the 29C010 can be written with the 28C hardware. The 29C series only differs from the 28C in that the 29C chips erase and write an entire sector at a time. The 29C010 and some 29C020 chips use a 128 byte sector, which matches the XModem buffer in the current code. Other 29C020s and all 29C040s use a 256 byte sector and cannot be written without code changes to buffer up an entire 256 byte block of data before writing.
Features include:
* Simple hardware design that can be assembled on a breadboard.
* ROM images transfers using XMODEM - no special host client needed.
* Support for fast block EEPROM writes - a 32K EEPROM will program in just a few seconds.
* Optimized code that supports the timing requirements needed to unlock the 28C series Software Protection Algorithm.
* Modular software design to easily support other EEPROM and EPROM families.
The [hardware readme](hardware/README.md) has schematics and more information on the hardware design. The [software readme](TommyPROM/README.md) has class definitions and more information on the software design.
The project was inspired by the [MEEPROMMER programmer](http://www.ichbinzustaendig.de/dev/meeprommer-en).
![TommyPROM Nano Hardware](docs/TommyPROM-nano.jpg)
## Compiling
Open the TommyPROM.ino file in the Arduino IDE. It should automatically open the cpp and h files as well. The default code programs 28C series chips using Arduino Nano hardware. To use this version, just compile and upload it to the Arduino.
**Note well** that this code has been optimized for the Aduino UNO and Nano hardware so that it can run quickly enough to meet 28C series chip timing reqirements for SDP unlocking. To use different Arduino hardware, like the Micro, the board-specific code in PromDevice.cpp and PromAddressDriver.cpp must be change to match the port mappings between the ATmega chip and the Arduino I/O pins.
To use the 8755A version of the code and matching hardware, uncomment PROM_IS_8755A and comment out the other PROM_IS_xx choices in Configure.h.
## Operation
![TommyPROM Screenshot](docs/tp05.png)
To use the programmer, connect the Arduino USB to the host computer and run a terminal program, such as TeraTerm (Windows) or Minicom (Linux). The Arduino development Serial Monitor can also be used as a terminal initially, but it does not support XMODEM transfers, so the READ and WRITE commands can't be used.
Set the terminal's serial parameters to 115200 baud, 8 bits, no parity, 1 stop bit to match the Arduino. Press the Enter key. If the connection is successful, TommyPROM will display a menu of options.
Most of the commands take a start address parameter, always entered as 1 to 5 hex characters. Leading zeros are not required. If needed, the end address parameter is also in hex. Parameters are separated by a space. For example, either of the commands:
d0000 01ff
d0 1ff
dump memory from 0000H to 01ffH. Note that commands and parameters can be entered in uppercase or lowercase.
The R command is used to read from a PROM and save a binary image on the host. The W command receives a file from the host and writes (burns) it into the device. The R command needs a start and end address. The W command determines the end address from the received file size.
The READ and WRITE command both use XMODEM CRC to complete the file transfers. Many terminal programs default to XMODEM Checksum format, so be sure to select XMODEM CRC as the format. Once the READ or WRITE command is issued to the programmer, the transfer must be started on the host program.
The files used for READ and WRITE are simple binary images. This can be created directly by [asm85](http://github.com/TomNisbet/asm85) or can be converted from S-record or Intel HEX using an external utility.
## Troubleshooting
* Verify that the Arduino type you are using is a supported board or that its I/O port definitions match one of the supported boards. Some other Arduino boards, like the Duemilanove, appear to be compatible but have not been tested. Others, like the Micro, have different port mappings and definitely will not work without software changes.
* If the code doesn't appear to be working, concentrate on the read operations first to verify that the data and address paths are good.
* 28C series EEPROMS, like the X28C256, sometimes ship from the factory with Data Protection enabled. Use the UNLOCK command to disable this. See the [28C Readme](README-28C.md) for more information.
* Re-check all hardware connections and verify the the control pins are going to the Arduino pins that match the definitions in the code.
* This repo contains a standalone program called HardwareVerify that allows low-level access to the address, data, and control lines through a menu-driven interface. See the [readme](HardwareVerify/README.md) for that code for more tips.
## Further Work
* Add a new PromDevice class for 27 series EPROMS.
* Additional error checking in the CmdLine code.

42
docs/software.md Normal file
View File

@ -0,0 +1,42 @@
---
title: Software Design
has_children: false
nav_order: 3
---
# Software Design
The software is designed around several major blocks and classes. The code has been broken out into individual files to make it easy to extend the hardware support to additional EPROM and EEPROM families. See the [extension readme](../README-extension.md) for details on suggested hardware and software changes needed.
## CommandStatus class
The CommandStatus class stores the execution status of the previous command. It allows the status to be saved (and recalled using the / command) instead of just printing the status at the completion of the command. This was important for debugging XMODEM problems, because the error messages would get eaten as part of the transfer. The class has utility beyond XMODEM because it includes formatting that relieves each command from having to build paramterized error messages with multiple print calls.
## Xmodem class
The Xmodem class implements the communications protocols needed to do XMODEM CRC transmit and receive. It calls directly into the PROM read and write code, to the complete files are never stored during the transfer.
## CLI code and command implementation
This code parses input commands and parameters and executes the commands.
A compile-time switch in Configure.h enables additional debug commands that are not needed in normal operation, but are very useful to verify proper operation of the hardware.
## PromDevice class
The PromDevice class and its subclasses encapsulate all of the communication between the Arduino and the target PROM device.
To meet the timing requirements for block writes and 28C chip unlocking, the PromDevice class accesses the shift registers and data bus using direct port writes instead of 8 individual pin accesses. This greatly increases performance, but it makes the code dependent on the particular flavor of Arduino being used. The code supports the Uno, Nano, and Boarduino versions of Arduino hardware or any other variant that uses that same mapping of ATMega ports to I/O pins. To support a different Arduino board, either change the pins used to match the mapping in the software, or change the hardware-specific code in PromDevice.cpp and PromAddressDriver.cpp.
The PromDevice class contains common code used by all devices, including the block write code that will break a large write request into a set of properly-aligned smaller blocks for devices that support block writing, or a sequence of infividual byte writes for devices that do not.
Subclasses of the PromDevice class provide the device-specific code. To accomodate the limited memory footprint of the Arduino, only a single subclass will be compiled into the final code. This is controled via switches in the Configure.h file.
The device-specific subclasses are described below. Each class provides pin definitions, byte read, byte burn, and optional block burn code that is specific to the timing of the chip. They also supply a SetAddress method that either calls the built-in code for the shift register hardware or provices device-specific address code.
### PromDevice28C class
Although the existing code is specific to the 28C256, the constructor has parameters that easily support other chips. The current design has been used to read other chips, including 2764 and 29c040 EPROMs.
The 28C code supports fast block writes, allowing a 32K byte chip to be programmed in just a few seconds.
### PromDevice8755A class
The PromDevice8755A class provices the byte read and byte write code, as well as SetAddress code that accomodates the ALE used on this chip. The byte write code controls the Vdd switching hardware that toggles the Vdd pin between the normal 5V value and the 25V programming pulse.
### PromAddressDriver class
Although not actually a subclass of PromDevice, this contains the code to drive the shift registers that provide the address lines. If this hardware is used, the PromDeviceXX class can call this code to implement the SetAddress methods.

70
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,70 @@
---
title: Troubleshooting
has_children: false
nav_order: 3
---
## Hardware Verifier Tool
This tool allows access to individual control lines from the Arduino to verify that the hardware was assembled correctly.
It can be used without a chip installed to scope out address and data lines. It also offers low-level control when the chip is installed.
THIS TOOL USES DIRECT PORT ACCESS ON THE ARDUINO. CHECK TO MAKE SURE IT IS
COMPATIBLE WITH YOUR BOARD BEFORE USING. It will work correctly on the Unu, Nano, and Boarduino. It WILL NOT WORK on the Micro.
Note that the comamnds write access to the individual 28C control lines with some exceptions to protect the chip and the host arduino:
* When the O command is used to enable chip output, the arduino data bus is set to INPUT
* When the D command is used to write data from the arduino, the chip output is disabled
* The R command sets the output enable (OE) on the chip, but not the chip enable (CE)
* The L and U commands reset CE, OE, and WE back to disabled on completion and change the data and address
The session below shows how a write fails to a locked chip and then succeeds once the chip is unlocked.
```
Hardware Verifier - 28C series EEPROM
Valid commands are:
Axxxx - Set address bus to xxxx
Dxx - Set Data bus to xx
Cs - Set Chip enable to state (e=enable, d=disable)
Os - Set Output enable to state (e=enable, d=disable)
Ws - Set Write enable to state (e=enable, d=disable)
R - Read and print the value on the data bus
L - Send Lock sequence to enable device Software Data Protection
U - Send Unlock sequence to disable device Software Data Protection
#l
Writing the lock code to enable Software Write Protect mode.
#a0000
#ce
#r
22
#d55
#we
#wd
#r
22
#u
Writing the unlock code to disable Software Write Protect mode.
#d33
#we
#wd
#r
33
#cd
```