General Information
-------------------
 This is picptk 0.5.0.

 Picptk is a Microchip PIC programmer controller for Linux.  The core
 of picptk is written in C++, the GUI is written in itcl/itk, an
 enhanced version of Tcl/Tk.

Platform Requirements
---------------------

 Linux 2.0.x or later (that supports the real-time scheduler operations)

 Tcl/Tk 8.0

 itcl 3.0    (available from http://www.tcltk.com/itcl/index.html)


Picptk features
---------------

  * Can program any PIC chip (including FLASH, EPROM, and OTP memories)

    The picptk core is table driven for PIC timing and PIC memory map
    information, therefore picptk can be used to program any PIC
    type. Presently, picptk's tables are only populated with the PIC
    parts I use. These include the 16C76 (and EPROM part) and 16F84 (a
    FLASH part), but new parts are easily added. 

  * Supports parallel and serial programmers

    Programmer specifics are will isolated from the Picp core;
    parallel and serial programmers are supported.  (Note that serial
    programmers require a kernel patch.  Since I do not have a serial
    programmer, the serial driver is not fully debugged, but the code
    is included.)

  * Alternative GUIs are easily built

    The picp core is interface neutral.  I have included an incrTk
    interface (the preferred interface) and a vanilla Tk interface
    (deprecated).  Alternative interfaces (e.g., curses, GTK, Java)
    can be added easily.

  * "Fast" programming - doesn't program the "holes" in input data files

    When a data file is loaded, the picp core marks all used
    locations.  During a burn operation, unused locations are not
    programmed.  This offers a tremendous speedup when programming big
    devices (e.g., the 16C76) with small programs.

Installation
------------

 Picptk uses the GNU install.  Briefly, unpack it, then run "./configure",
 then "make all", and "make install".

 Two executables are installed, picptk (the user interface) and
 picpwish (the core).  At present, both executables must be in the
 search path.  (picptk is a Tk script that invokes picpwish).

 The only supported picptk Gui is built on incrTk, an object-oriented
 extension to Tcl/Tk.  You can get incrTk from
 http://www.tcltk.com/itcl/index.html.

 I have also included a now defunct prototype GUI written in pure
 Tcl/Tk; it's use is deprecated but, if you can't make incrTk work,
 this alternate GUI may provide a stopgap.  (Foolishly, I've made the
 build script automatically install the Tcl/Tk version if you don't
 have incrTk...  I suspect this is a mistake since most people will
 get the lame Tk interface and not install incrTk.)

 Please see the file INSTALL if you want more detail.

Bugs
----

 Please report bugs to me, mgb@mitre.org

 This version has been tested under Linux 2.0.35 and 2.1.132.

 These are the bugs I know about...

 * Picptk wants access to the I/O ports, so it can only be run as root.
   (Since picpwish is a tk shell, it's not safe to run it setuid.  Is
    there a way to allow the core run setuid without introducing a
    gaping security hole?)

 * The current binary release of incrTcl doesn't include itclInt.h, a
   file which is required to build an incrTk shell from source.  I've
   included a copy for incrTcl 3.0 with picptk; I'm hoping the inctTcl
   folks will fix this in the next release.

 * The itk3.0 menuconfig widget has a couple bugs.
	- the -indicator ambiguity
	- it doesn't highlight the selection

 * Compiler warnings from /usr/include/asm/io.h?
     "warning: volatile qualifier ignored on asm"

 These are some GUI shortcuts that I know about

 * The "Erase" button should change names to "blank check" if the part
   is not electrically erasable.

 * The Abort button (and perhaps others) should be disabled when they
   don't make sense.

 * There is no preferences editor.


Patches
-------
 I welcome any improvements (and particularly solicit them for the GUI).


Usage
-----
 
 The following test applies to the incrTk GUI.  The pure Tcl/Tk GUI is
 not supported and its use is deprecated---really!  This help text is
 available on-line; select "Help" on the "Main" menu.

 The picptk screen is divided into four segments,
    * Menu
    * Configuration
    * Status
    * Control

 The Menu section has one menu, "Main", with the following entries:
    Preferences...   - Invokes the (currently nonexistent) preferences editor
    About            - Shows some trivia about picptk
    Help             - Displays a portion of this file
    Save Prefs       - Writes the current preferences to ~/.picprc
    Exit             - ...

 The Configuration section has three entry widgets:
    DataFile        - A text entry box for selecting the programming data
		    - presently, only 8-bit IntelHex format is supported.
		    - New formats are easily added, look at IoIntel.C for
		    - details.
    Port	    - This is the port to which the programmer is
                    - connected. Parallel programmers will be
                    - connected to LPTx, serial programmers are
                    - expected to be connected to /dev/pipc.  (Make
                    - /dev/picp be a symbolic link to /dev/ttynn.)
   Pic Type	    - This is the type of PIC to be programmed.
                    - Selecting a PIC type chooses a memory map and
                    - sets programmer timing.  Programming one PIC
                    - type with another's settings is a bad idea.
                    - If your favorite pic isn't on this list, look at
                    - PicPersonality.C (or complain to me...)

 The Status section provides feedback on the execution of commands.
 During long operations it'll display progress (albeit in a rather
 unsophisticated way at present) including programming errors, etc.

 The Control section provides a collection of buttons which load
 data files, erase and burn PICs, show memory contents, etc.  At
 present, the control buttons are:

   Read   -  Reads the contents of a PIC into picptk's memory. A PIC
	     type must have been selected prior to reading.

   Load	  -  Loads the data from "data file" into picptk's memory.
	     This does not program the device, it only loads picptk.
	     A device type must have been selected prior to loading,
	     or picptk cannot tell how to map memory.

   Show	  -  Displays the contents of picptk's memory in the status
	     window.  (Of particular interest here is the device
	     status word.)

   Burn	  -  Programs the PIC with the contents of picptk's memory.
	     (Note that accidentally burning an empty programmer
	     socket will likely produce lots of errors and take a long
	     time.  This is what motivated the inclusion of an "Abort"
	     button.)

   Verify -  Compares the contents of the PICs memory with picptk's
	     memory.  Disagreements are displayed in the status window.

   Erase  -  Erases any electrically erasable segments of the PICs
             memory, and checks non-erasable segments for an
	     unprogrammed state.

   Abort  -  Aborts a long operation (e.g., program).
