Preliminary sp89 version 0.6 manual page

NAME
     SP89: A serial programmer for working with Atmel AT89 uCs.
     Copyright (C) 2000 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
     SP89 -iNN -<options> [filename or address(:data)] -<options>...
      
EXAMPLES
     A command like this is suitable for rapidly writing a program and 
     some data into a series of devices:
          SP89 -i52 -M12 -wpfC prog.hex -wefC data.eep -L2 
          
     Communication timing is set to be correct for an AT89 uC
     running at 12MHz or higher clock speed. (When -M12 is not on
     the command line, the default set in _sp89rc is used.)
     Prog.hex is loaded into a write buffer sized for the AT89(L)S8252,
     padded with 0xff and written into the program area, and data.eep
     goes into the eeprom area. Checksums are provided for both.
     Finally the device is locked mode 2 (write-protected).
     Progress bars are shown while the area's are written.
     NOTE: Before each write, SP89 reads from the address to see
     whether the data is already present. This speeds things up
     when writing a small file into an empty area, and also saves
     erase cycles. As the progress bar is based on percentage of
     upload completed, you will see a large speed difference when
     data is already present.
     NOTE: After each write, SP89 immediately reads back from the
     same address and compares the response with the data that
     was written. If the response is not correct, SP89 tries to
     write to the same address two more times before returning an
     error, which is marked by a !! on the progress bar.

     Within a group, the order of options is not significant, so the
     above is equivalent to:
          SP89 -i52 -M12 -fwCp prog.hex -Cfew data.eep -L2

     However, the order of arguments on the command line *is*
     significant. The following is wrong:
          SP89 -i52 -M12 -wefC data.eep -L2 -wpfC prog.hex
          
     because the device will be locked before prog.hex can be written.
     You would have to erase the device again to correct this mistake,
     using an -E preceding other options as shown in the two examples
     below.

     When both LOGGING and QUERY in _sp89rc are set to 1, the results
     of a command like this are queried and logged. (See 
     _SP89RC SETTINGS below for details.)
          sp89 -i52 -M12 -E -wpf sxga.hex -wef diz-2.eep -L4

     This command outputs checksums for both area's:
          SP89 -i52 -M12 -Cp -Ce
          
     SPECIAL NOTE: When a device has been locked mode 3 or 4, the
     program and eeprom area checksums will be invalid.

     This one outputs checksums for both files, equal to what the
     checksums would be if they are read back from the respective
     area's:
          SP89 -i52 -Cpf prog.hex -Cef data.eep

     This command reads the program area and outputs to the screen
     (stdout):
          SP89 -i52 -rp

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

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

     This one does only a blank check:
          SP89 -i52 -B

     And this one locks the device against both writing and reading:
          SP89 -i52 -L3

COMPATIBILITY
     The 32-bit protected mode executable found in this version of
     SP89 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.
     SP89 is known to run in MS-DOS, in a Windows-3.X DosBox and in 
     a Windows-9X DosBox or DosMode. Windows NT does not provide
     the access to the parallel port required by SP89.

INSTALLATION
     SP89.exe should be put somewhere in your PATH. If you are using
     plain MS-DOS, Windows DosMode or something like it without a
     DPMI host, you must also put CWSDPMI.EXE (found in SP89\CSDPMI\BIN)
     in your PATH. This is not required when using a Windows DosBox.
     Finally, it is advisable to set the environment variable SP89 by
     adding a line like "Set SP89=C:\SP89\" to your autoexec.bat file.

     When you run SP89 for the first time, the runtime configuration
     file _sp89rc will be created in the directory as defined by the
     environment variable SP89, or in the current directory if this
     variable is not set. This will usually take a few seconds, as a
     timing loop must be calibrated.
     _sp89rc is in plain language and may be edited (with care), for
     instance to make SP89 use a different parallel port, or to
     activate the `logging' and/or `query' modes.
     NOTE: Be sure to erase any previous runtime conifiguration file
     (_sp89rc) and let this version make a new one.
     NOTE: When running SP89 in a Windows DosBox (rather than DosMode)
     you should let SP89 generate _sp89rc while your computer is
     lightly loaded. If heavy multitasking is going on, the
     autocalibration will produce time constants which are too small.
     When you are actually programming a uC, heavy background loads
     may slow down the job, but reliability won't suffer.

     SP89 expects the AT89 uC to be connected to the parallel port of
     your PC. The cable should include the Kanda-compatible `dongle'
     designed by Ken Huntington, which improves signal quality and 
     makes the connection high-Z except when SP89 is active.

DESCRIPTION
     The present version (0.6) is suitable for the following uCs
     And offers facilities as shown in the table:
     
                    chip    read/write   read/write    write
                    erase   flash        eeprom        lock
        AT89S8252   YES     YES          YES           YES
        AT89LS8252  YES     YES          YES           YES
        AT89S53     YES     YES                        YES
        AT89LS53    YES     YES                        YES

     `In circuit' programming procedure: 
     The PC is switched on. Run SP89 -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 SP89 for whatever you wish to
     do, then switch off and disconnect the target board.

_SP89RC SETTINGS
     You can change the parallel port address; if SP89 found more than
     one parallel port, their addresses will be shown in _sp89rc.
     You can change the uC clock speed default. (A number in MHz, see
     -Mnn command line option below.)
     You can set LOGGING=1 (Default is 0.) When logging is set, every
     write operation will cause a single line to be appended to the
     file ``sp12log.txt'' in the current directory. 
     You can also set QUERY=1 (Default is 0). When both logging and
     query are set, then after writing a file content into the
     designated memory area, the flash or eeprom is read back and
     compared with the file, address by address. When all is well, a
     checksum is calculated and added to sp12log.txt; else "readback
     ERROR" is reported. For instance:

AT89(L)S8252 -wpf   diz_2.hex      readback ERROR  Sat Nov  4 13:56:08 2000
AT89(L)S8252 -wpa   000710:0x00ab  readback ERROR  Sat Nov  4 13:57:03 2000
AT89(L)S8252 -wea   000001:0xcd    verified        Sat Nov  4 13:57:21 2000
AT89(L)S8252 -wpf   sxga.hex       checksum ba57   Sat Nov  4 13:58:03 2000
AT89(L)S8252 -wef   diz_2.eep      checksum 0f37   Sat Nov  4 13:58:05 2000

     Lock operations are preceded by memory checksum calculations,
     and results are logged like this:
     
AT89(L)S8252 -L2    flash ba57     eeprom 0f37     Sat Nov  4 13:58:18 2000

     When logging is set but query is not, the address by address 
     comparison is not performed, and writes are logged like this:

AT89(L)S8252 -wpf   sxga.hex       not verified    Sat Nov  4 14:06:13 2000
AT89(L)S8252 -wef   diz_2.eep      not verified    Sat Nov  4 14:06:13 2000

OPTIONS
     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 above). 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, octal or binary format. 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 0xff,
          eeprom addresses 0xff. 

     -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.hex
          calculates the checksum from the file foo.hex.
          During a read, you will see a progress bar like this:
          
          oooooooooooooooooooooooo.......................................

          NOTE:The combination -wpfC foo.hex writes foo.hex to the
          device, then reads the program area back into the buffer and
          calculates the checksum. So -wpfC foo.hex is equal to
          -wpf foo.hex -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. 
          SPECIAL NOTE: When a device has been locked mode 3 or 4, the
          program / eeprom area checksums will be invalid. 
          
     -E   chip erase
          Executes the AT89 command `chip erase', which erases both
          program and eeprom area's. It is not possible to erase just
          one of the area's.
          NOTE: When executing -wpf and -wef commands, sp89 always
          checks the entire flash or eeprom area, and writes new data
          into all addresses which differ from file content or 0xff
          buffer padding. So a file written into flash or eeprom will
          always fully replace the original content, whether the uC is
          first erased or not.
          
     -e   eprom area
          Targets the eeprom area when used in combination with -r, -w
          or -C
          
     -f   filename next
          The next argument on the command line must be a valid
          filename, or drive:path\filename. 
          Program files must be in Intel HEX format, as provided
          by the Atmel assembler. SP89 recognizes the file by
          content, so you don't need to use specific extensions; 
          but .hex seems logical.

     -iNN init
          This option must always be on the command line, and it must
          be the first option.
          As the Atmel serial mode programming algorithm provides no
          access to device codes, SP89 must be told which device is
          connected. 
          Here is a table of supported uCs and init numbers:
          
             AT90(L)S8252          -i52
             AT90(L)S53            -i53
          
          NOTE: init is the only valid option if no device is connected,
          though you might for instance check a file checksum using 
          -i52 -Cpf foo.hex, if foo.hex is intended for the 8252.
          
     -L   lock modes
          Mode 2 (-L2): MOVC instructions executed from external
          program memory are disabled from fetching code bytes from
          internal memory. EA is sampled and latched on reset and
          further writing to the flash area is disabled.
          Mode 3 (-L3): as mode 2, but read (verify) is also disabled.
          Mode 4 (-L4): as mode 3, but external execution is also
          disabled.
          The lock bits can be cleared only by completely erasing the
          device. The command  -iNN -EB  will erase a locked device
          and perform a blank check.
          
     -Mnn uC clock frequency
          NN is the uCs clock speed in MHz, not lower than 0.1. 
          _sp89rc contains timing data (delay caused by outportb(),
          loop count/s), from which a conservative Sck frequency is
          calculated, fitting the uC's clock speed as indicated by the
          user. There is also a default clock speed value in _sp89rc,
          originally set at 3MHz. In practice, the outportb() delay is
          likely to limit the shortest timing to about 2.4us for a
          complete Sck cycle. So while the programmer works correctly
          with very fast uCs, the time needed to execute a command
          line is not likely to decrease for Mnn settings above 16MHz.
          
          When sp89 starts, it first looks at the command line to find
          the first occurrence of -Mnn. Sck timing is calculated to
          fit either that or, if no -Mnn is found, the default value.
          So you can safely set -Mnn lower than the default.
          NOTE: When the Sck frequency is too high, the uC will
          misread commands and fill its memory with garbage.

     -o   optimization
          Default (-o1, or option not on command line): the Bytewrite
          timing value is dynamically adjusted, with the value in 
          _sp89rc as upper limit. Bytewrite determines how much time
          a flash or eeprom address gets to settle, after it has been
          written to.
          -o0: No optimization.
          NOTE: If used, this option must be the second option on the
          command line, directly after -iNN

     -p   program area
          Targets the program area when used in combination with -r, -w
          or -C
          
     -r   read
          To read from either program or eeprom area, a single address
          (-rpa address, or -rea address) or the whole area (-rp or -re).
          In the latter case output can be directed to a file using
          the -f option: -rpf foo.out reads the program area and
          writes an image into foo.out. Both flash and eeprom content
          are presented in this format:

000000  ff ff ff f6 fe ff 25 ff 55 ff 2a 00 87 8c 8d 8f   ......%.U.*.....
000010  74 41 40 37 35 0d 34 0c 05 04 14 07 33 13 31 30   tA@75.4.....3.10
000020  11 10 57 47 55 3d 0f 1d 1f 17 3f 15 1c 3c 03 01   ..WGU=....?..<..
000030  5f 75 77 7f 1f 3f 47 01 74 74 74 14 ff ff ff ff   _uw..?G.ttt.....
000040  ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff   ................
---8<---
Checksum: 0f37

          Or in this format when a single address is read to the screen
          (stdout):
               The byte 0x99 (153, 0231, B10011001) was read from 
               address 0x0001
          During a read, you will see a progress bar like this:
          
          oooooooooooooooooooooooo.......................................
             
     -w   write
          Writes 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.hex reads foo.hex and writes
          to the program area; -wef foo.eep reads foo.eep and writes
          to the eeprom area.
          During a write, you will see a progress bar like this:
          
          oooooooooooooooooooooooo.......................................

          NOTE: Before each write, SP89 reads from the address to see
          whether the data is already present. This speeds things up
          when writing a small file into an empty area, and also saves
          erase cycles. As the progress bar is based on percentage of
          upload completed, you will see a large speed difference when
          data is already present.
          NOTE: After each write, SP89 immediately reads back from the
          same address and compares the response with the data that
          was written. If the response is not correct, SP89 tries to
          write to the same address two more times before returning an
          error, which is marked by a !! on the progress bar.
 
          oooooooooooooooooooooooo!!.....................................
          
FILES
     SP89.exe       The executable.
     SP89.doc       This file
     _sp89rc        The runtime configuration file
     licence.txt    The GNU general public licence states the terms and
                    conditions for copying, distribution and modification
                    of this software
     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
     SP89 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.

BUGS & BOTHER
     Please report them to the authors.
     
     SP89 is known to run in MS-DOS, in a Windows 3.X Dosbox and in 
     a Windows 9X Dosbox. Windows NT does not provide the access to
     the parallel port required by SP89.

AUTHORS
     Software: Steven Bolt (sbolt@xs4all.nl)
     Hardware: Ken Huntington (kenh@compmore.net)