
NAME
     SP12: A serial programmer for working with Atmel AT90S uCs.
     Copyright (C) 1997, 1998 Ken Huntington, Pitronics
   
     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.
   
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
   
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston,
     MA  02111-1307, USA.
   
     Pitronics can be reached by email: sbolt@xs4all.nl
     Ken Huntington can be reached by email: kenh@compmore.net

SYNOPSIS 
     SP12 -<options> [filename or address(:data)] -<options> [filename...
      
COMPATIBILITY
     The 32-bit protected mode executable found in this version of
     SP12 relies on MS-DOS and BIOS for file I/O and other basic
     functions such as keyboard input, screen cursor position, etc.
     It uses "DPMI" (the DOS Protected Mode Interface) to allow
     DOS/BIOS calls from protected mode.
     SP12 is known to run in MS-DOS, in a Windows-3.X Dosbox and in 
     a Windows-9X Dosbox, on machines ranging from a slow 386 to a
     450MHz Pentium-II. Windows NT does not provide the access to the
     parallel port required by SP12.

INSTALLATION
     SP12.exe should be put somewhere in your PATH. If you are using
     plain MS-DOS or something like it without a DPMI host, you must
     also put CWSDPMI.EXE (found in SP12\CSDPMI\BIN) in your PATH.
     Finally, it is advisable to set the environment variable SP12 by 
     adding a line like "Set SP12=C:\SP12\" to your autoexec.bat file.
     When you run SP12 for the first time, use option -i. SP12 then
     creates the runtime configuration file _sp12rc, in the directory
     as defined by the environment variable SP12, or in the current
     directory if this variable is not set. Depending on your computer
     it may take half a minute or longer to calibrate the timing loop.
     _sp12rc is in plain language and may be edited (with care), for
     instance to make SP12 use a different parallel port (read _sp12rc
     for details). 

     SP12 expects the AT90S uC to be connected to the Centronics
     parallel port of your PC. Look at progrmmr.gif and icp_intr.gif
     for details.

     WARNING: The `VCC' connection should only be made if the pcb
     containing the microcontroller has to use the Centronics port as
     its power supply. This can be done safely if a supply current of
     less than 5 mA is sufficient, which is the case if you are using a
     `stand alone' programmer board with just a clock generator and a
     Zip socket for the microcontroller. SP12 will then automatically
     switch the supply current on and off as appropriate.
     Progrmmr.gif shows the layout and diagram of the programmer board
     Steve is using.
     
     NOTE: The connection between status 4 and CLK serves no purpose 
     for programming; it is used only for serial communications with
     a program running on the AT90S1200. Check subdirectory AVRCOM for
     software and details.
     
DESCRIPTION
     The present version (0.6) is suitable for the following uCs.
     On all of them, you have read and write access to the flash and
     eeprom memory (from/to file or single address), and you can set
     the lock bits. Some of them offer extra functions as shown in
     the table:
     
                  Read access to       set/clear   set/clear
                  lock & fuse bits     RCEN        FSTRT
     AT90S1200
     AT90S2313
     AT90S2323    YES
     AT90S2343    YES                  YES
     AT90S4414
     AT90S4434    YES                              YES
     AT90S8515
     AT90S8535    YES                              YES
     
     Note that on `YES' marked devices, you have access to the fuse
     bits even if the device is locked. For instance, you can switch
     the 2343 from internal to external clock oscillator and back
     even if you can't read the program inside.

     `stand alone' programming procedure:
     The PC is switched on. Run SP12 -i to ensure that all Centronics
     data bits are zero. Connect the programmer board to the Centronics
     port. Use SP12 for whatever you wish to do, then switch off and
     disconnect the programmer board.

     The software is just as suitable for `in circuit' programming. In
     that case, the target board must allow free access to MOSI (PB5),
     MISO (PB6), SCK (PB7) and Reset. SCK must be terminated on the
     target board using a 22pf capacitor and a 100 ohms resistor. On the
     reset pin, a 10K resistor and a 100N (100 nano-farad) capacitor may
     be used to make power-on reset more reliable. That combination
     allows SP12 sufficient access to Reset. Check icp_intr.gif for
     details.
     
     `In circuit' programming procedure: 
     The PC is switched on. Run SP12 -i to ensure that all Centronics
     data bits are zero. Power up the target board (to between 3 and 5
     volt). Connect it to the PC. Use SP12 for whatever you wish to
     do, then switch off and disconnect the target board.

OPTIONS
     If no options are used, SP12 will enter interactive mode. See
     INTERACTIVE USE below.

     Options must be used in meaningful groups, but you may use more
     than one group on a single command line. The command line is
     processed from left to right, and it is up to you to put the groups
     in a meaningful order (see EXAMPLES below). Within a group, the
     order of the options is not significant.

     -a   address(:data) next
          To specify a single address to read from, or an address:data
          combination for writing. Both address and data can be entered
          in hexadecimal, decimal or octal format. For eeprom data
          binary format is also allowed. So the addresses 0x1ff, 511 and
          0777 are identical, as are the address:data combinations
          0x3f:0xab, 0x3f:171, 63:171, 077:B10101011 and so on. 

     -B   blank check
          Checks both program and eeprom area's to see if every address
          has been erased. Program addresses should contain 0xffff,
          eeprom addresses 0xff. 
          NOTE: using options -w, -p and -f together (to write a file
          from disk to program area) cause an automatic erase, but no
          blank check. So -wpf foo.rom is equivalent to -Ewpf foo.rom.
          If you want a blank check to precede the actual programming,
          use -Bwpf foo.rom.

     -C   calculate checksum
          Takes the internal (program or eeprom) buffer and calculates a
          BSD-type 16-bit checksum. The buffer is an image of the
          corresponding area in the device, including empty addresses,
          but the content may be read from device or file. -Cp results
          in a checksum of the device program area, while -Cpf foo.rom
          gives you a checksum of the content of file foo.rom, as it
          would look like when written to the device. So after writing
          foo.rom to the device (-wpf foo.rom), -Cp and -Cpf foo.rom
          should result in the same checksum. Using files in Intel HEX
          format makes no difference to the checksum. If foo.rom is the
          same program as foo.hex, then -Cpf foo.rom and -Cpf foo.hex
          result in the same checksum.
          NOTE:The combination -wpfC foo.rom writes foo.rom to the
          device, then reads the program area back into the buffer and
          calculates the checksum. So -wpfC foo.rom is equal to
          -wpf foo.rom -Cp
          NOTE:-Ce and -Cef apply to the eeprom buffer. Of course these
          options make sense only if your program is not intended to
          write to eeprom addresses. 
          NOTE: The checksum value depends on what's in the buffer and
          also on the total size of the buffer. So if you move a file
          from an AT90S2313 to an AT90S8515, the checksum changes.
          -i12 -Cpf foo.rom and -i15 -Cpf foo.rom show different
          checksums for the same file, matching those calculated when
          doing -Cp with a 1200 or an 8515 connected.
          SPECIAL NOTE: When a device has been locked mode 3, and SP12
          is used with the option -iNN (no check of device code), the
          program / eeprom area checksums will be invalid.
          
     -E   chip erase
          Executes the AVR command `chip erase', which erases both
          program and eeprom area's. It is not possible to erase just
          one of the area's, but when writing to the eeprom area each
          address is automatically erased first. So you can write 0xff
          to an address containing 0x00. (You can write only 0's to the
          program area.)
          NOTE: Using options -w, -p and -f together (to write a file
          from disk to program area) cause an automatic erase, so -wpf
          foo.rom is equivalent to -Ewpf foo.rom.

     -e   eprom area
          Targets the eeprom area when used in combination with -r, -w
          or -C
          
     -F   Lock and fuse bits
          Use in combination with -r to make the command -rF, for
          reading the lock and fuse bits. Valid only if an AT90S2323,
          2343, 4434 or 8535 is connected.

     -f   filename next
          The next argument on the command line must be a valid
          filename, or drive:path\filename. 
          Program files must be either in the Atmel `generic' format or
          in Intel HEX format, both as provided by the Atmel assembler
          (w)avrasm.exe version 1.03 or higher. SP12 recognizes the file
          by content, so you don't need to use specific extensions; 
          but .rom and .hex do seem logical.
          The generic format contains only lines like 00000c:99e1 (both
          address and data in hexadecimal notation without prefix; six
          digits for the address, four for the data).
          Eeprom files must be either in SP12 `native' format, or Intel
          HEX format as provided by (w)avrasm.exe version 1.21 or
          higher. To conform to SP12 format, the file must contain only
          lines like 0x0d:0xcf (Address in hexadecimal, decimal or octal
          notation, data in hexadecimal, decimal, octal or binary
          notation, all with appropriate prefix. So the lines 0x0d:153,
          13:0231 and 015:B10011001 have the same meaning.)

  -i[NN]  init
          First initializes communication with the Centronics parallel
          port and some timing constants. SP12 looks for the runtime
          configuration file _sp12rc, in the directory as defined by
          the environment variable SP12, or in the current directory
          if this variable is not set. If _sp12rc is not found, a new
          one is created. Depending on your computer it may take half
          a minute or longer to calibrate the timing loop.
          _sp12rc is in plain language and may be edited (with care),
          for instance to make SP12 use a different parallel port
          (read _sp12rc for details). 
          Next the device code of your device (contained in the
          signature bytes) will be read to determine which member of
          the AVR family has been connected. This enables SP12 to use
          the correct programming command subset and to know the size
          of the flash and eeprom memory. When a device has been
          locked mode 3, the device code (signature bits) will be
          unreadable. To regain access, you must put a two-ddigit number
          behind the -i, thus forcing SP12 to assume that a certain
          device is connected. Here is a table of supported uCs and init
          numbers:
                       Force recognition 
                       with:
          AT90S1200           -i12
          AT90S2313           -i13
          AT90S2323           -i23
          AT90S2343           -i43
          AT90S4414           -i14
          AT90S4434           -i34
          AT90S8515           -i15
          AT90S8535           -i35

          -i0, -i or no use of this option (when there are others on
          the command line) results in automatic init and device check.
          NOTE: option -iNN must be the first on the command line.
          NOTE: init is the only valid option if no device is connected,
          though you might for instance check a file checksum using 
          -i15 -Cpf foo.hex, if foo.hex is intended for the 8515.
          
     -L   lock modes
          Mode 2 (-L2): further writing to both program and eeprom
          area's is disabled.
          Mode 3 (-L3): as mode 2, but read (verify) is also disabled.
          The lock bits can be reset only by erasing the device.
          NOTE: when a device has been locked mode 3, the device code
          (signature bits) will be unreadable, making sp12 refuse to
          do anything whatsoever with the device. If you need to
          regain access, You will have to erase the device using a
          command like -iNN -EB
          The use of option -iNN bypasses the device code check, see
          above. For example, -i12 makes sp12 assume an AT90S1200 is
          connected. Command -EB erases the device and performs a blank
          check.
          
     -p   program area
          Targets the program area when used in combination with -r, -w
          or -C
          NOTE: It is possible to write to a single address, by using
          the command -wpa address:data. In this case the device will
          *not* be automatically erased first. So unless the address was
          empty (0xffff), data are unlikely to be written correctly, as
          you can write only 0's to the program area.
          
     -R   RCEN fuse bit
          The command -R0 programs the RCEN bit on an AT90S2343, thus
          enabling the internal RC clock oscillator. Command -R1
          unprograms the bit, switching the internal clock off.
          While RCEN is available on other AT90S uCs, it can only be
          accessed by a serial programmer (like SP12) on the 2343.
          
     -r   read
          To read from either program or eeprom area, a single address
          (-rpa address, or -rea address) or the whole area. In the
          latter case output can be directed to a file using the -f
          option: -rpf foo.rom reads the program area and writes an
          image into foo.rom. Data read from the eeprom area is
          presented in this format when output is directed to a file:
               Address:  Data in hex,  dec, oct,  bin
                  0000:          0xc0  192  0300  11000000
                  0x01:          0x99  153  0231  10011001
          Or in this format when a single address is read to the screen
          (stdout):
               The byte 0x99 (153, 0231, B10011001) was read from 
               eeprom address 0x0001
             
     -S   FSTRT fuse bit
          The command -S0 programs the FSTRT bit on the AT90S4434 and
          8535, thus selecting the fast start-up time. Command -S1
          unprograms the bit, selecting the default (long) start-up
          time.

     -w   write 
          To write to either program or eeprom area, a single address
          (-wpa address:data, or -wea address:data) or the whole area.
          In the latter case, input has to be taken from a file, so the
          -f option is mandatory: -wpf foo.rom reads foo.rom and writes
          to the program area; the device is automatically erased first.
          -wef foo.epr reads foo.epr and writes to the eeprom area;
          there is *no* preceding erase, because when writing to the
          eeprom area the device takes care of erasing each address
          first.
          NOTE: All writes are automatically verified; SP12 immediately
          reads back from the current address and compares the response 
          with the data that was written. If the response is not
          correct, SP12 tries to write to the same address two more
          times before coming back with "ERROR: Verify has failed."
          
EXAMPLES
     A command like this is suitable for rapidly writing a program and 
     some data into a series of devices:
          SP12 -wpfC prog.rom -wefC data.epr -L2 
     This erases the device (this function is automatically included
     when you use the -wpf group). Then prog.rom is written into the
     program area, and data.epr into the eeprom area. Checksums are
     provided for both. Finally the device is locked mode 2
     (write-protected).

     Within a group, the order of options is not significant, so the
     above is equivalent to:
          SP12 -fwCp prog.rom -Cfew data.epr -L2

     However, the order of arguments on the command line *is*
     significant. The following is wrong:
          SP12 -wefC data.epr -wpfC prog.rom -L2 
     because it writes data.epr to the eeprom area, then erases it
     (erase being automatically included with the -wpf group), writes
     prog.rom to the program area and write-protects the device, so you
     would have to erase the device again to correct this mistake.

     This command outputs checksums for both area's:
          SP12 -Cp -Ce
     SPECIAL NOTE: When a device has been locked mode 3, and sp12
     is used with the switch DEVICE=12 in _sp12rc (no check of
     device code), the program / eeprom area checksums will be
     invalid. 

     While this one outputs checksums for both files, equal to what the
     checksums would be if they are read back from the respective
     area's:
          SP12 -Cpf prog.rom -Cef data.epr
     NOTE: The checksum value depends on what's in the buffer and
     also on the total size of the buffer. So if you move a file
     from an AT90S2313 to an AT90S8515, the checksum changes.

     This command reads the program area and ouputs to the screen
     (stdout):
          SP12 -rp

     While this one reads both area's into files:
          SP12 -rpf prog.out -ref eeprom.out

     This command erases the device and does a blank check:
          SP12 -EB

     This one does only a blank check:
          SP12 -B

     And this one locks the device against both writing and reading:
          SP12 -L3
     NOTE: when a device has been locked mode 3, the device code
     (signature bits) will be unreadable, making sp12 refuse to
     do anything whatsoever with the device. If you need to
     regain access, You will have to erase the device using a
     command like -i12 -E
     The use of option -iNN bypasses the device code check, see
     above. For example, -i12 makes sp12 assume an AT90S1200 is
     connected. Option -E erases the device and performs a blank
     check.

     When an AT90S2343 is connected, the command
         SP12 -rF
     Will result in something like:
         The following information was read from the
         lock and fuse bits:
            Internal RC clock enabled.
            Device is write-protected.
     But when an AT90S4434 or 8535 is connected, you might see:
         The following information was read from the
         lock and fuse bits:
            Short start-up time selected.
            Device is write-protected.    
 
     The command:
         SP12 -R0
     Will program the RCEN fuse bit on an AT90S2343, enabling the
     internal RC clock oscillator.
     On an AT90S4434 or 8535, the command:
         SP12 -S0
     programs the FSTRT fuse bit, to select the short start-up time. 
     
INTERACTIVE USE
     The interactive human interface is still on the `to do' list.
     It will probably appear in version 0.7.

FILES
     sp12.exe        The executable.
     sp12.doc        This file
     changes.doc     Describes the changes between versions.
     _sp12rc         The runtime configuration file
     licence.txt     The GNU general public licence states the terms and
                     conditions for copying, distribution and modification
                     of this software
     progrmmr.gif    Shows the layout and diagram of the programmer board
                     Steve is using.
     icp_intr.gif    Shows the connections between the Centronics parallel
                     port and a target board which uses external power,
                     and has an sp12-compatible time constant for providing
                     power-on reset.
     connect.gif     Shows the basic connections between the Centronics 
                     parallel port and the AT90S1200, including parallel
                     port pin numbers.
     SOURCE          This directory contains the source files and a
                     makefile for use with djgpp, see below.

ACKNOWLEDGEMENTS
     The 32-bit protected mode executable found in this version of
     SP12 was compiled with gcc 2.8.1, as found in the DJGPP packages. 
     You can obtain a copy of this excellent compiler from any
     SimTel.NET mirror in the pub/simtelnet/gnu/djgpp/ subdirectory, or
     from one of the CCT mirrors, world-wide. For instance:
     ftp://ftp.euro.net/d5/simtelnet/gnu/djgpp/ (in The Netherlands).
     
     This product includes software developed by the University of
     California, Berkeley and its contributors.

     The authors would like to thank Chris Jackson for pointing out
     the timing problems version 0.5 has on very fast machines, and 
     for testing this version on those same machines. He also pointed
     out the incompatibility with Windows-NT. (See also changes.doc.)

     Others who have contributed bug reports and/or suggested 
     improvements:
                       Arian van Dorsten
                       Robert Hyde
                       Zoran Kostic
                       Walter Waldner
     
BUGS & BOTHER
     Please report them to the authors.
     
     SP12 is known to run in MS-DOS, in a Windows 3.X Dosbox and in 
     a Windows 9X Dosbox, on machines ranging from a slow 386 to a
     450MHz Pentium-II. Windows NT does not provide the access to the
     parallel port required by SP12.
     
     As reported by Chris Jackson:
     "One of the machines that I tried it on had a Parallel Port
     PCMCIA adapter installed. Unless the machine was powered up with
     this device fully disconnected, the driver for it was loaded by
     Windows. This meant that whenever SP12 set the port lines high,
     the driver would kick in and set them back low again. Depending on
     the speed of the driver's response, the programmer would sometimes
     work, and sometimes not - which caused a bit of confusion at first."

     Note that sp12 has been tested on the AT90S1200, 2313, 2343 and
     8515. Since the -R and -S options work on the same fuse bit
     (the uCs just interpret the bit differently), we know they both
     function correctly. The AT90S2323, 4414, 4434 and 8535 don't
     require untested functionality, so you should have no trouble
     programming them :)

AUTHORS
     Basic functions and command line user interface: 
                       Steven Bolt (sbolt@xs4all.nl)
     Interactive user interface, hardware:
                       Ken Huntington (kenh@compmore.net)
