From fe8ecfe92e3648b7a0fd975620e7e1f1ee476c4c Mon Sep 17 00:00:00 2001 From: Tom Nisbet Date: Mon, 29 Jun 2020 14:44:14 -0400 Subject: [PATCH] Fix broken documentation links --- README.md | 2 +- docs/28C256-notes.md | 2 +- docs/_config.yml | 80 ++++++++++++++++++++++++++++++++++++++++- docs/extending.md | 43 +++++++++++++++++----- docs/hardware.md | 3 ++ docs/index.md | 21 ++++++----- docs/software.md | 19 +++++++--- docs/troubleshooting.md | 17 +++++---- 8 files changed, 155 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 3c177b2..be7147b 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Software Protection Algorithm. ![TommyPROM Nano Hardware](docs/images/TommyPROM-nano.jpg) -See the [project page](https://tomnisbet.github.io/TommyPROM/) for the full documentation +See the [documentation pages](https://tomnisbet.github.io/TommyPROM/) for the full documentation with hardware, software, and troubleshooting tips. ## Further Work diff --git a/docs/28C256-notes.md b/docs/28C256-notes.md index 00f4585..f7bc726 100644 --- a/docs/28C256-notes.md +++ b/docs/28C256-notes.md @@ -1,7 +1,7 @@ --- title: 28C256 Notes has_children: false -nav_order: 3 +nav_order: 5 --- # Notes on 28C EEPROMs diff --git a/docs/_config.yml b/docs/_config.yml index 5bb4f24..c796e80 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,9 +1,87 @@ +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.github_repo }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. title: "TommyPROM" +description: "A programmer for EEPROMs and EPROMs using Arduino hardware" +baseurl: "/TommyPROM" +url: "https://tomnisbet.github.io" + remote_theme: pmarsceill/just-the-docs -color_scheme: "light" + +permalink: pretty +#exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"] + +# Set a path/url to a logo that will be displayed instead of the title +#logo: "/docs/images/logo.png" + + +# Enable or disable the site search +# Supports true (default) or false search_enabled: true +search: + # Split pages into sections that can be searched individually + # Supports 1 - 6, default: 2 + heading_level: 2 + # Maximum amount of previews per search result + # Default: 3 + previews: 3 + # Maximum amount of words to display before a matched word in the preview + # Default: 5 + preview_words_before: 5 + # Maximum amount of words to display after a matched word in the preview + # Default: 10 + preview_words_after: 10 + # Set the search token separator + # Default: /[\s\-/]+/ + # Example: enable support for hyphenated search words + tokenizer_separator: /[\s/]+/ + # Display the relative url in search results + # Supports true (default) or false + rel_url: true + # Enable or disable the search button that appears in the bottom right corner of every page + # Supports true or false (default) + button: false + +# Enable or disable heading anchors +heading_anchors: true # Aux links for the upper right navigation aux_links: "Project Home": - "//github.com/TomNisbet/TommyPROM" + +# Makes Aux links open in a new tab. Default is false +aux_links_new_tab: false + + +# Sort order for navigation links +nav_sort: case_insensitive # default, equivalent to nil +# nav_sort: case_sensitive # Capital letters sorted before lowercase + +# Footer content +# appears at the bottom of every page's main content + +# Back to top link +back_to_top: true +back_to_top_text: "Back to top" + +#footer_content: "Copyright © 2017-2020 Patrick Marsceill. Distributed by an MIT license." + +# Footer last edited timestamp +#last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter +#last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Return to GitHub project" +gh_edit_repository: "https://github.com/tomnisbet/TommyPROM" +gh_edit_branch: "master" # the branch that your docs is served from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately + +# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define +color_scheme: nil + +plugins: + - jekyll-seo-tag diff --git a/docs/extending.md b/docs/extending.md index 9c3552a..61740ac 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -1,27 +1,52 @@ --- -title: Extension +title: Adding Chip Families has_children: false -nav_order: 3 +nav_order: 5 --- # 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 also 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. +There are currently two hardware flavors - one for 28C series EEPROMs and one specifically +for the Intel 8255A UV EPROM. There is also a work-in-progress version for 27C series +chips. -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. +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 +also 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 on for the +entire write and verify cycle. For those chips, it may be easier to simply switch the +programming voltage manually for these chips. + +The basic hardware design, used for the 28C EEPROMs, 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 for A0..A15 and wire Arduino pins D10..D12 to A16..A18 on the +target chip. # Software -The software design is modular, allowing easy extension for chips with different programming algorithms. 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 software design is modular, allowing easy extension for chips with different +programming algorithms. 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. +* 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. +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. diff --git a/docs/hardware.md b/docs/hardware.md index db6873a..da53bd0 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -45,3 +45,6 @@ assembled hardware design, a triple output bench supply was used to provide the 5.5V and 5V outputs. ![TommyPROM Nano Schematic](images/TommyPROM-8755A-sch.png) + +Eagle-format schematics can be downloaded from the +[hardware project page](https://github.com/TomNisbet/TommyPROM/tree/master/hardware). diff --git a/docs/index.md b/docs/index.md index 6da80b3..654a067 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,10 +12,14 @@ 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. +![TommyPROM Nano Hardware](images/TommyPROM-nano.jpg) + +## Design + 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 +the device. See the [Extending the design](extending.html) page 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. @@ -36,18 +40,17 @@ Features include: * 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 [hardware](hardware.html) page has descriptions of the hardware designs and links to schematics. The [software](software.html) page 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](images/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. +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 requirements for SDP @@ -77,7 +80,7 @@ in hex. Parameters are separated by a space. For example, either of the command d0000 01ff d0 1ff -dump memory from 0000H to 01ffH. Note that commands and parameters can be entered in +will 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 @@ -102,7 +105,7 @@ have different port mappings and definitely will not work without software chang 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](28C256-notes.html) for more information. +[28C256 Notes](28C256-notes.html) 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 diff --git a/docs/software.md b/docs/software.md index 02ff49f..4704930 100644 --- a/docs/software.md +++ b/docs/software.md @@ -6,7 +6,11 @@ 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](extending.md) for details on suggested hardware and software changes needed. +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 +[Adding Chip Families](extending.html) page for details on suggested hardware and software +changes needed. ## CommandStatus class @@ -18,15 +22,22 @@ has utility beyond XMODEM because it includes formatting that relieves each comm having to build parameterized 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. + +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. +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. + +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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 359527a..cc202a4 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -5,23 +5,26 @@ nav_order: 3 --- ## Hardware Verifier Tool -This tool allows access to individual control lines from the Arduino to verify that the +A [Hardware verification Arduino sketch](https://github.com/TomNisbet/TommyPROM/tree/master/HardwareVerify) +is provided to assist with troubleshooting. Loading this sketch onto the TommyPROM +hardware 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. +The verifier sketch 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 commands write to the individual 28C control lines with some exceptions to -protect the chip and the host arduino: +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 +* 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 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.