summaryrefslogtreecommitdiff
path: root/sp12.txt
diff options
context:
space:
mode:
authorDimitri Sokolyuk <demon@dim13.org>2010-01-06 17:55:16 +0000
committerDimitri Sokolyuk <demon@dim13.org>2010-01-06 17:55:16 +0000
commit09381c6097773b08622c810428a84840b5b08070 (patch)
treef62afce58620ebbffe6abcf1b8e1d8df6a09a5b8 /sp12.txt
AVR SP12 programmer
Diffstat (limited to 'sp12.txt')
-rw-r--r--sp12.txt1045
1 files changed, 1045 insertions, 0 deletions
diff --git a/sp12.txt b/sp12.txt
new file mode 100644
index 0000000..b5c3856
--- /dev/null
+++ b/sp12.txt
@@ -0,0 +1,1045 @@
+
+NAME
+
+ SP12: A serial programmer for working with Atmel AVR uCs.
+ Copyright (C) 1997-2001 Ken Huntington, Kevin Towers, 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 (Steve) can be reached by email: sbolt@xs4all.nl
+ Kevin Towers can be reached by email: ktowers@omnexcontrols.com
+ Ken Huntington can be reached by email: kenh@compmore.net
+
+URL
+ The home page for sp12 is
+ http://www.xs4all.nl/~sbolt/e-spider_prog.html
+
+SYNOPSIS
+
+ SP12 -<options> [filename or address(:data)] -<options> [filename...
+
+OPTION SUMMARY
+
+ i<nnn> - init E - chip erase
+ e - eprom area B - blank check
+ p - program area C - calculate checksum
+ w - write to L[n...n] - lock fuses
+ r - read from F[n...n] - fuses
+ a - address(:data) next H[n...n] - high fuses
+ f - filename next X[n...n] - extended fuses
+ I - create Intel Hex file c[nn] - calibration byte
+ h - hex dump with ascii M[n.n] - match Sck to uC clock
+ o0, o1 - optimization P[nnn] - parallel port control
+ s - show supported uCs t - timing check
+
+EXAMPLES
+
+ sp12 -rF -rH -rL -rc (reads fuses, locks and calibration if possible)
+ sp12 -wea 0x01:0x99 (Writes 0x99 into eeprom address 0x01)
+
+ A command like this is suitable for rapidly writing a program and
+ some data into a series of devices:
+
+ sp12 -M4 -wF10011 -wpfC prog.hex -wefC eep.hex -wL00
+
+ Timing is set to match a uC clock speed of 4MHz as close as
+ possible. Parallel port speed will probably limit the achieved
+ timing to a lower value, which doesn't matter; only timing which
+ is too fast can make communication impossible.
+ Then the fuses are programmed - note that the string 10011 must
+ exactly match the device's fuses block in length including gaps,
+ as defined in _sp12dev; this one would be appropriate for the
+ AT90S4433. For a Tiny15 it would be something like -wF01011101,
+ despite the fact that only four or at most six of those bits
+ can actually be altered. And since the _sp12dev in this package
+ blocks accidental change of a Tiny2313's high fuses bits
+ 7, 5 and 1, you'd use for instance -wH001110 to preserve its eeprom
+ through chip erase and set its brown-out detection to 1.8V.
+ (See also sp12dev.txt.)
+ Next, the device is erased (this function is automatically
+ included when you use the -wpf group). Prog.hex is written into
+ the program area, and data.hex into the eeprom. Checksums are
+ provided for both. Finally the device is locked against reading
+ and writing. The lock string must also be of the right length;
+ a Mega8 would require something like -wL111100
+ Note that setting the log and query options in _sp12rc may be
+ more useful than asking for checksums. (See sp12rc.txt)
+
+ Within a group, the order of options is not significant, so you
+ could also write -fwCp prog.hex -Cfew data.hex
+
+ However, the order of arguments on the command line *is*
+ significant. The following is wrong:
+
+ sp12 -wefC data.hex -wpfC prog.hex -wL00
+
+ because it writes data.hex to the eeprom area, then erases it
+ (erase being automatically included with the -wpf group), writes
+ prog.hex to the program area and write-protects the device, so you
+ would have to erase the device again to correct this mistake.
+
+ Of course you can use single commands like
+
+ sp12 -wpf prog.hex
+ sp12 -wef data.hex
+ sp12 -wL00
+
+ But the order in which they are given remains just as important.
+
+ Timing optimization is available when programming page mode
+ uCs (ATmega's). In previous versions, pages were allowed to
+ settle for 64ms, as demanded by the old Mega103. Optimization
+ allows you to fully program a Mega8 in about 3 seconds instead
+ of 11 seconds.
+ However, there are combinations of target and program cable
+ (without `dongle') which cause optimization to fail; a few
+ locations which have been programmed and verified may revert to
+ 0xff while programming another page. So it was decided to keep
+ `no optimization' as the default behaviour. To increase speed,
+ use -o1. For example:
+
+ sp12 -M4 -o1 -wpf foo.hex
+
+ To make sure that optimization is alright for your hardware,
+ it should be tested with QUERY=1 in _sp12rc, or a command like
+
+ sp12 -M4 -o1 -wpfC foo.hex -Cpf foo.hex
+
+ The checksums should be equal.
+ NOTE: The new Tiny2313 introduced the programming command
+ `poll rdy/bsy', which allows a different optimization method.
+ When this command is part of an _sp12dev entry (see sp12dev.txt),
+ the -o option is ignored. And for devices which obey this
+ new programming command, -o must be ignored, as -o1 would
+ cause programming errors.
+
+
+ This command outputs checksums for both area's:
+
+ SP12 -Cp -Ce
+
+ 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: When a device has been locked against reading, and sp12
+ is used with the option -innn on the command line (no check of
+ device code), the program / eeprom area checksums will be
+ invalid.
+
+ These output checksums for both files, equal to what the
+ checksums would be if they are read back from the respective
+ area's, even when no device is connected:
+
+ SP12 -iAT90LS4433 -Cpf prog.hex -Cef data.hex
+ SP12 -i392 -Cpf prog.hex -Cef data.hex
+
+ This command reads the program area and ouputs a hex dump with
+ ascii translation to the screen (stdout):
+
+ SP12 -rph
+
+ While this one reads both area's into files, using the Intel
+ hex format:
+
+ SP12 -rpIf prog.hex -reIf eeprom.hex
+
+ 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 devices with just two lock bits against both
+ writing and reading:
+
+ SP12 -wL00
+
+ NOTE: when a device has been locked againts reading, the device
+ code (signature bits) may 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
+
+ sp12 -iS2313 -E
+ or
+ sp12 -i191 -E
+
+ The use of option -innn bypasses the device code check, see
+ below. For example, -i191 or -iS2313 make sp12 assume an
+ AT90S2313 is connected. Option -E erases the device.
+
+ When an ATmega163 is connected, the command
+
+ SP12 -rF -rH
+
+ Will result in something like:
+
+ 11010010 are the fuse bits read from an ATmega163
+ 0x11xxxx - BODLEVEL 4V (default 2.7V)
+ x011xxxx - brownout detection enabled
+ xx11CKSE - clock and reset select, datasheet p5 p25
+
+ 111 are the high fuse bits read from an ATmega163
+ BZx - BootSZ, datasheet p134
+ xx0 - Boot reset at flash, default address zero
+
+ These messages are defined in _sp12dev and can easily be
+ customized. (See sp12dev.txt)
+
+ When given to an AT90S4433, The command:
+
+ sp12 -wF00100
+
+ Results in:
+
+ 00100 are the fuse bits written into an AT90S4433
+ 0xxxxx - serial programming enabled
+ x0xxxx - BODLEVEL 4V (default 2.7V)
+ xx0xxx - brownout detection enabled
+ xxxCKS - reset delay select (datasheet p20)
+ NOTE: (re)enabling brownout detection
+ often causes the 4433 to hang. In that
+ case power must be switched off and back
+ on again before programming can continue.
+
+ As the message shows (assuming you use a fixed pitch font to
+ get proper alignment), brownout detection is switched on, with
+ the detection level at 4V. A look at p20 of the datasheet tells
+ us that the start-up delay is set to 16K CK.
+
+ Atmel had the following comment on that bit about `hanging'
+ after (re)enabling brownout detection:
+
+ "This is a known problem with the current revision of the
+ AT90S4433. There is no other workaround than to program the
+ BODEN bit after you have programmed the flash and the EEPROM."
+ (Communication via Mark Korsloot of Alcom, the Dutch
+ distributor of Atmel products, on 27 Apr 2000.)
+
+ When this version of sp12 was prepared, the AT90(L)S2333 was
+ not available. (Re)enabling BOD may or may not cause this uC to
+ hang, but it seems best to make fuse programming the final
+ word on your command line. So if you want to write to eeprom
+ and flash, lock the device and program the fuses in one go,
+ this is the correct order of the command words:
+
+ SP12 -wpf prog.hex -wef data.epr -wL00 -wF00100
+
+ The flash must be written to first, because that command first
+ erases the device. The fuses can be programmed after locking
+ the device, because in serial programming mode, you have access
+ to the fuse bits even when this device is locked against reading
+ and writing.
+ Note that many other devices demand that the lock is applied after
+ programming the fuses.
+
+ The command:
+
+ SP12 -M4 -wpf foo.hex
+
+ Will attempt to set communication timing to match a device
+ clock speed of 4MHz. Hardware will usually limit the achievable
+ com speed, so while SP12 works correctly with very fast uCs, the
+ time needed to execute a command line is not likely to decrease
+ for Mnn settings above 1.5MHz. SP12 will report the speed
+ actually achieved. For instance:
+
+ Sck timing set for 1.5MHz or higher.
+
+ The command:
+
+ SP12 -Owpf foo.hex -Owef foo.hex
+
+ Will NOT erase the device before writing in the new data.
+ The files foo.hex and foo.hex are added to what is already in the
+ flash and eeprom area's. If there is a conflict, the flash
+ overlay will stop with an error report - it isn't possible to
+ write a 1 over a 0 in an AVR flash location. However, foo.hex is
+ always written, even if it (partially) replaces earlier data.
+
+ With suitable hardware, this command:
+
+ SP12 -P4 -wpf uC1.hex -P8 -wpf uC2.hex -P2
+
+ will program two uCs on a single target board, using a single
+ command line. The first -P would make parallel port data bit 3
+ high, making a set of analog switches route the programming lines
+ to the first uC. The second -P disconnects the first and connects
+ the second uC. Finally, the third -P leaves reset high when SP12
+ exits, allowing the new software to run. There is a 10ms delay
+ after each -P, to give analog switches on the target board some
+ time to do their job.
+
+ To force timing optimization for a 1200:
+
+ sp12 -o1 -wpfC foo.hex -Cpf foo.hex
+ Or
+ sp12 -i190 -o1 -wpfC foo.hex -Cpf foo.hex
+
+ Compare the two checksums to make sure that the upload was
+ correct.
+ To force a fixed byteWrite for other uCs, equal to the value in
+ _sp12rc (behaviour equal to early sp12 versions):
+
+ sp12 -o0 -wpf foo.hex
+
+ Each option is described in detail under `options' below.
+
+ERROR CODES RETURNED ON PROGRAM EXIT
+
+ 0 - accomplished writing/reading task - "life is wonderful :)"
+ 1 - no device present - "nothing to do"
+ 2 - bad command line options, corrupt _sp12rc, file not found,
+ unable to write to file - "don't know what to do"
+ 3 - verification or blank check error - "device doesn't respond
+ as expected"
+
+OPERATING SYSTEM COMPATIBILITY
+
+ The dynamically linked sp12 binary intended for Linux requires
+ libc.so.6 and ld-linux.so.2. See readme.linux for further information.
+ The 32-bit Dos 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, XP and W2000 do not provide the
+ access to the parallel port required by SP12.
+
+INSTALLATION
+
+ Have a look at either readme.dos (also for MS W9x and W3x) or
+ readme.linux as appropriate; also read hardware.txt.
+
+
+DESCRIPTION
+
+ The present version (2.0) should be suitable for all AVR uCs;
+ but _sp12dev only contains definitions for the ones mentioned in
+ the table below. You can easily add definitions for others - have
+ a look at sp12dev.txt.
+ On all of them, you have read and write access to the flash and
+ eeprom memory, and you can set the lock bits. Some of them offer
+ read and write access to various fuse bits, in serial programming
+ mode. This is also supported. Moreover, you can elect to block
+ write permission to fuses you don't want to change by mistake.
+ For instance, the _sp12dev supplied in this package doesn't allow
+ write access to the Tiny15's RSTDSBLE and SPIEN, because changing
+ either of them would put the uC out of action as far as serial
+ mode (in-circuit) programming is concerned. The table below
+ shows the devices for which there are entries in a recent
+ _sp12dev. Note that low voltage versions (AT90LS, mega_L) are
+ also supported.
+
+ device
+ code name
+
+ 0190 AT90S1200(A)
+ 0191 AT90S2313
+ 0193 AT90S8515
+ 0192 AT90S4414
+ 0291 AT90S2323
+ 0292 AT90S4434
+ 0393 AT90S8535
+ 0391 AT90S2343 or Tiny22 (*)
+ 0691 ATtiny22L
+ 0591 AT90S2333
+ 0392 AT90S4433
+ 0590 ATtiny12
+ 0690 ATtiny15L
+ 0991 ATtiny26
+ 0A91 ATtiny2313
+ 0197, 0101 ATmega103
+ 0196 ATmega603
+ 0194 ATmega161
+ 0294 ATmega163
+ 0693 ATmega8515
+ 0893 ATmega8535
+ 0793 ATmega8
+ 0394 ATmega16
+ 0295 ATmega32
+ 0297 ATmega128
+
+ (*) The 2343 is still treated as if it has an RCEN-bit, which
+ may not be true for the series now being sold - the 02/2000
+ errata sheet for the Tiny22 says "If external oscillator is
+ required, use the 100% pin- and code-compatible
+ AT90S/LS2343 which has external clock option only."
+ It appears that the RCEN fuse proved recalcitrant in some
+ cases, and Atmel felt this to be the quick and safe
+ solution.
+ The same errata sheet says that only the Tiny22L is now
+ available, with the internal RC oscillator as the single
+ clock option. However, I have several Tiny22s with a
+ switchable RCEN fuse, making them fully compatible with a
+ number of clock-switchable 2343s I have lying around.
+ Moreover, my Tiny22 (8PC) chips even have the same
+ signature bytes (device code) as my 2343s...
+ The key difference is that switching the Tiny22's RC clock
+ on or off causes some bits in flash to flip, so it has to be
+ done *before* programming the uC. The 2343s don't have this
+ slight disadvantage.
+ The supplied _sp12dev makes sp12 version 2.0 assume that
+ a uC with device code 0391 has a switchable RCEN fuse. It's
+ up to the user to determine or find out the use of of the
+ -R0/R1 option.
+
+ Note that on many devices, you have access to the fuse bits
+ even when 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.
+ But other devices require you to program the fuses before
+ setting a lock.
+
+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 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.hex is equivalent to -Ewpf foo.hex.
+ If you want a blank check to precede the actual programming,
+ use -Bwpf foo.hex.
+
+ -C calculate checksum
+ Reads 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.
+ During a device 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.
+ NOTE: When a device has been locked against reading, and sp12
+ is used with the option -innn on the command line (no check of
+ device code), the program / eeprom area checksums will be
+ invalid.
+
+ -c Calibration byte
+ Valid combinations: -rc to read the calibration for the internal
+ RC clock of uCs like the Tiny15, Mega163 and so on.
+ When there are more calibration bytes, like the four inside
+ the ATmega8 and ATmega128, add a binary address:
+
+ Byte 0: sp12 -rc or sp12 -rc00
+ Byte 1: sp12 -rc01
+ Byte 2: sp12 -rc10
+ Byte 3: sp12 -rc11
+
+ To set a different calibrated internal clock speed, the programmer
+ must read the relevant calibration byte and write it somewhere in
+ flash or eeprom, where your Mega8 software must find it and put it
+ in OSCCAL. To do the first part in one go, you need a script which
+ makes sp12 copy a calibration byte to flash. Here is one for Linux
+ systems:
+
+ #!/bin/sh
+ #
+ # First upload program.hex into the Mega8, and set the fuses:
+ # BODLEVEL 2.7V, brownout detection on, SUT 00, select internal
+ # RC clock 4MHz
+ #
+ sp12 -M4 -wpf program.hex -wF10000011
+ #
+ # Read the calibration byte for 4MHz (binary address 10),
+ # and feed it through the stream editor sed; it looks for
+ # the output line starting with `0x', replacing that with
+ # `000fff:00', resulting in for instance `000fff:0096'.
+ # Everything after that is cut away, and the other lines
+ # are not printed (the `-n and `p' take care of that). The
+ # line containing the highest flash address and the word
+ # `00<calibration byte>' are written into the file
+ # `overlay'.
+ #
+ sp12 -M4 -rc10 | sed -n -e s/^0x/000fff:00/ -e s/" is.*"//p - > overlay
+ #
+ # Finally, upload overlay (which is in the Atmel generic
+ # format) into the Mega8, without first doing an erase.
+ #
+ sp12 -M4 -Owpf overlay
+
+
+ -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.hex is equivalent to -Ewpf foo.hex.
+
+ -e eprom area
+ Targets the eeprom area when used in combination with -r, -w
+ or -C
+
+ -F Fuse bits
+ Valid combinations: -rF and -wF<n...n>. The latter command
+ writes all fuse bits in one go; you must supply the right
+ number of bits as defined in _sp12dev, or sp12 will barf.
+ Refer to your device's datasheet and _sp12dev to see
+ whether there are fuse bits to write, and if so, how many.
+ Note that the string must include any non-fuse or otherwise
+ fixed bits between the writable fuses, while excluding.
+ such fixed bits at either end of the string. For instance,
+ a Tiny15 needs a write command like -wF01011101, despite the
+ fact that only four or at most six of those bits can actually
+ be altered. (See also sp12dev.txt and _sp12dev.)
+ You can write the n...n in hex if you want, but in that case
+ sp12 can't check the number of bits; the command -wF0x3 will
+ write zeroes into the fuse bits 2, 3, 4 and so on, if they
+ happen to exist.
+ Note that there are separate options for `high fuses' (-H)
+ and `extended fuses' (-X).
+
+ -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.)
+
+ -H high fuse bits
+ Valid combinations: -rH and -wH<n...n>. The latter command
+ writes all high fuse bits in one go; you must supply the right
+ number of bits, or sp12 will barf. Refer to your device's
+ datasheet to see whether there are high fuse bits to write,
+ and if so, how many. Note that the string must include any
+ non-fuse or otherwise fixed bits between the writable fuses,
+ while excluding such fixed bits at either end of the string.
+ For instance, the _sp12dev in this package blocks accidental
+ change of a Tiny2313's high fuses bits 7, 5 and 1, you'd use
+ for instance -wH001110 to preserve its eeprom through chip
+ erase and set its brown-out detection to 1.8V, with sp12
+ reporting back:
+
+ 001110 are the high fuse bits written into an ATtiny2313
+ 0xxxxxxx - debugWire enabled
+ x0xxxxxx - EEPROM preserved in chip erase
+ xx0xxxxx - serial programming enabled
+ xxx0xxxx - WDT always on (page 41)
+ xxxxBODx - BODLEVEL (page 34)
+ xxxxxxx1 - reset-pin enabled (page 52)
+
+ (See also sp12dev.txt and _sp12dev.)
+ You can write the n...n in hex if you want, but in that case
+ sp12 can't check the number of bits; the command -wH0x3 will
+ write zeroes into the fuse bits 2, 3, 4 and so on, if they
+ happen to exist.
+ Note that there are separate options for `fuses' (-F)
+ and `extended fuses' (-X).
+
+ -h Hex dump with ascii translation modifier for the -r (read)
+ option, see below.
+
+ -I Intel Hex modifier for the -r (read) option, see below.
+
+ -i[nnn] init [<device code>] [<device name>]
+ First initializes communication with the parallel port and
+ some timing constants. SP12 looks for the runtime config
+ 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 and sp12rc.txt 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 against reading as well as writing, the device
+ code (signature bits) will often 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 -innn -EB
+ The use of option -innn bypasses the device code check,
+ nnn being equal to either the device code (with or without
+ leading zeroes) or the device name, which can be something
+ like AT90S1200, AT90LS1200, AT90LS1200A or abbreviations
+ like S1200, Mega128 and M8L. See sp12dev.txt for more
+ information about device names. For example, -i190 makes
+ sp12 assume an AT90S1200 is connected. Command -EB erases
+ the device and performs a blank check.
+ Here is a table of supported uCs and init numbers:
+
+ Force recognition
+ with:
+
+ AT90S1200(A) -i190
+ AT90S2313 -i191
+ AT90S8515 -i193
+ AT90S4414 -i192
+ AT90S2323 -i291
+ AT90S4434 -i292
+ AT90S8535 -i393
+ AT90S2343 or Tiny22 -i391
+ Tiny22L -i691
+ AT90S2333 -i591
+ AT90S4433 -i392
+ ATtiny15L -i690
+ ATmega103 -i197
+ ATmega603 -i196
+ ATmega161 -i194
+ ATmega163 -i294
+ ATmega8 -i793
+ ATmega128 -i297
+
+ -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 -innn must be the first on the command line.
+ NOTE: -i, -s and -t are the only valid options 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 bits
+ Valid combinations: -rL and -wL<n...n> The latter command
+ writes all lock bits in one go; you must supply the right
+ number of bits, or sp12 will barf. Refer to your device's
+ datasheet to see how many lock bits are supported. Also
+ have a look at sp12dev.txt and _sp12dev.
+ You can write the n...n in hex if you want, but in that case
+ sp12 can't check the number of bits; the command -wH0x3 will
+ write zeroes into the lock bits 2, 3, 4 and so on, if they
+ happen to exist.
+ Lock bits can be reset (to `1') only by erasing the device.
+
+ NOTE: Some AVR uC lock commands reverse the bit sequence
+ on readout, examples being the AT90S8535, 4434, 2323, 2343
+ and Tiny22. And these uCs have no `read locks' command;
+ the locks and fuses are separately programmed, but read
+ together. So you write-protect them with sp12 -wL10 while
+ the result can be read back with sp12 -rF resulting in:
+
+ 01011111 are the fuse bits read from an AT90S8535
+ 11xccccx - no lock
+ 01xccccx - write protected
+ 00xccccx - read/write protected
+ xx0ccccx - serial programming enabled
+ xxxcccc0 - FSTRT reset delay, datasheet p20
+
+ The more often used read and write protection is done with
+ a less confusing sp12 -wL00
+
+ NOTE: when a device has been locked against both writing
+ and reading, the device code (signature bits) will often 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 -innn -EB
+ The use of option -innn bypasses the device code check, see
+ above. For example, -i190 makes sp12 assume an AT90S1200 is
+ connected. Command -EB erases the device and performs a blank
+ check.
+
+ -M[n.n] uC clock frequency
+ n.n is the uCs clock speed in MHz, not lower than 0.1.
+ _sp12rc contains autocalibrated timing data (delay caused
+ by outportb(), loop count/s), from which an Sck frequency is
+ calculated, fitting the uC's clock speed as indicated by
+ -Mn.n. You can safely set -Mn.n lower than the default (also
+ in _sp12rc), but only if the command precedes all others
+ except -i[nnn]. For instance:
+
+ sp12 -M4 -wpf foo.hex
+ sp12 -imega128 -M4 -wpf foo.hex
+
+ When this option is not on the command line, the default
+ is used. Unless you change it (in _sp12rc), the default
+ makes sp12 version 1.0 behave like previous versions, which
+ means that the Sck frequency and wave form will be suitable
+ for uCs running on an internal RC clock, at fairly low Vcc.
+ WARNING: When -Mn.n is set too high, the uC will misread
+ commands and fill its memory with garbage.
+ NOTE: In practice, the outportb() function needs a certain
+ amount of time to actually change a parallel port data bit.
+ Depending on the hardware, this is likely to limit the
+ shortest timing to about 1.3us for an Sck half cycle. Most
+ AVR uCs need the Sck low and high phases to be at least two
+ clock cycles long; the AT89S1200 is an exception, needing an
+ Sck high phase of at least four clock cycles.
+ So while SP12 works correctly with very fast uCs, the time
+ needed to execute a command line is not likely to decrease
+ for Mnn settings above 3MHz for the 1200, and 1.5MHz for
+ the other family members. SP12 reports the timing achieved.
+
+ -O overlay
+ The commands -wpf and -wef cause SP12 to read files into
+ 0xFFFF or 0xFF padded buffers, and to make sure that the
+ flash or eeprom area contains the buffer image after
+ programming is done. -wpf is automatically preceded by a
+ `chip erase', and -wef writes 0xFF into all addresses which
+ don't have their content specified by the file (addresses
+ which already contain 0xFF are skipped). This guarantees
+ that programming is actually possible (new uploads to
+ flash could easily conflict with `leftovers' from previous
+ work). It also results in equal checksums for uC content
+ and file.
+ However, You may sometimes want to add calibration
+ constants, configuration data and/or serial numbers to
+ what's already in flash or eeprom. To overlay files on
+ data already in the uC's memory, you'd do:
+
+ sp12 -Owpf foo.hex -Owef foo.hex
+
+ In combination with -wpf, the -O precludes chip erase.
+ If there is a conflict, the flash overlay will stop with an
+ error report - it isn't possible to write a 1 over a 0 in an
+ AVR flash location. However, foo.hex is always written, even
+ if it (partially) replaces earlier data.
+ Both -Owpf and -Owef only upload the file (as opposed to
+ the buffer) and cause a query (performed when `logging' and
+ `query' are set in _sp12rc) to also be limited to the
+ file, or where the flash area is concerned, to addresses
+ which according to the file should contain something other
+ than 0xffff.
+ Checksums are always calculated for the entire area, as the
+ commands -Cp and -Ce refer to the entire uC areas. So
+ after an -Owpf or -Owef, the log will show a checksum
+ which only matches area content. The overlayed files each
+ have their own checksum.
+
+ -o optimization
+ Level 0 (-o0): No optimization for any uC.
+ Level 1 (-o1): forces optimization for all uCs, including
+ the 1200(A).
+ Default (option not on command line) for all `classic' uCs
+ like the AT90S2313 and the ATtiny's, except the AT90S1200:
+ the Bytewrite time constant - which determines how much
+ time a flash or eeprom address gets to settle, after it
+ has been written to - is dynamically adjusted, with the
+ value in _sp12rc as upper limit.
+ Default for the AT90S1200 and the ATmega's: No optimization.
+ Optimization makes sp12 1.0 program significantly faster
+ when conditions allow, and should cause less trouble at
+ low Vcc.
+ For the AT90S1200 and the Mega's, it turns out that there
+ are combinations of target and program cable (without
+ `dongle') which cause optimization to fail; the content of
+ a few locations which have been programmed and verified
+ may change while programming other locations or pages.
+ So it was decided to keep `no optimization' as the default
+ behaviour. To increase speed, use -o1. For example:
+
+ sp12 -M4 -o1 -wpf foo.hex
+
+ To make sure that optimization is alright for your
+ Mega or 1200 hardware, it should be tested with QUERY=1 in
+ _sp12rc, or a command like
+
+ sp12 -M4 -o1 -wpfC foo.hex -Cpf foo.hex
+
+ The checksums must be equal.
+ NOTE: If used, this option must be the first option on the
+ command line, or the first after -i[nnn]
+ NOTE: The new Tiny2313 introduced the programming command
+ `poll rdy/bsy', which allows a different optimization method.
+ When this command is part of an _sp12dev entry (see sp12dev.txt),
+ the -o option is ignored. And for devices which obey this
+ new programming command, -o must be ignored, as -o1 would
+ cause programming errors.
+
+ -P[nnn] Port control
+ When used as the final option on the command line, this
+ option leaves the parallel port data pins in the state
+ determined by NNN, which can be a decimal or hexadecimal
+ number: For instance, -P124 and -P0x7C both leave the
+ port in 01111100 state. When used like this:
+
+ SP12 -P4 -wpf uC1.hex -P8 -wpf uC2.hex -P2
+
+ The first two -P's are limited to controlling pins 2-6
+ (those not used for the programming interface itself).
+ Kevin invented this usage for programming two AVR uCs
+ on a single board, using a single connector and a single
+ command. There is a 10ms delay after each -P, to give
+ analog switches on the target board some time to do their
+ job.
+ NOTE: You can't use Ken Huntington's `dongle' together
+ with option -P, since buffers inside it are powered as well
+ as high-Z/enabled using the data 2-6 pins. So only the exit
+ state of the parallel port can be set, as with the old -T
+ option (see below).
+ NOTE: it is possible to set different communication speeds
+ for each uC, using the -Mn.n command, but you have to put
+ the -P first on the command line:
+
+ SP12 -P4 -M0.2 -wpf uC1.hex -P8 -M4 -wpf uC2.hex -P2
+
+ NOTE: -P has immediate control over data pins 2-6 only
+ when it's the first option on the command line. In this
+ case:
+ SP12 -innn -P4 -wpf ...
+
+ Pins 2-6 will all be high during init, which takes about a
+ quarter of a second, depending on settings in _sp12rc and
+ the possible need for resynchronization of the uC's
+ programming interface.
+
+ NOTE: When sp12 is used with the Kanda STK200 cable/dongle,
+ a -P which is not the final option on the command line will
+ control only data bits 0, 1 and 6. Bits 2 and 3 have to be
+ used to high-Z/enable buffers inside the Kanda dongle; bits
+ 4 and 7 are programming lines, and bit 7 handles reset.
+
+ -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 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. Use of the `I' modifier (-rpfI foo.hex)
+ changes the format from `native' avrasm to Intel Hex, while
+ use of `h' (-rph to screen or -rpfh foo.dmp to file)
+ results in a hex dump with ascii translation, ending with
+ a checksum:
+
+ 000078 95 08 24 ee 24 ff 27 cc 77 d7 ..$.$.'.w.......
+ 000080 bf 02 2f 4d 70 47 30 45 f0 10 ../MpG0E..=...h.
+ 000088 e0 00 16 e0 f0 89 16 f0 f0 79 .........y...i..
+ 000090 f4 18 16 fc f4 08 c0 04 14 fe ...........0...
+ Checksum: cb46
+
+ The above is just a sample of (shortened) lines taken from
+ actual output.
+ During a read, you will see a progress bar like this:
+
+ oooooooooooooooooooooooo.......................................
+
+ NOTE: 16-bit word addresses are used when displaying the
+ program space, and words are shown hi byte first.
+ By default, data read from the eeprom area is presented in
+ this format:
+
+ 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
+
+ But you can also use the commands -reH, -refH or -refI
+ with appropriate effect. Byte addressing is used for the
+ hex dump display.
+
+ -s Show supported devices
+ The command sp12 -s reads a list of supported uCs and
+ their device codes from _sp12dev, and shows them on screen.
+
+ -t Timing check
+ The command sp12 -t presents a progress bar which should
+ take about 10 seconds to complete, counting from the moment
+ when you hit the return on the command line. (There may a
+ brief pause before the bar appears, which nevertheless is
+ part of the ten seconds.) The "bugs & bother" section
+ of readme.linux or readme.dos tells you more about its use.
+
+ -T This option was retained to remain compatible with older
+ versions, but option -P offers much more control over the
+ parallel port.
+ By default, SP12 will leave the parallel port databits all
+ zero on exit. Command -T1 leaves the reset pin high, so a
+ connected device will start running immediately after SP12
+ has finished, assuming it uses an external power source.
+ Command -T2 also leaves the `powerbits' (2-6, as shown by
+ progrmmr.gif) high, to run a device without external
+ power.
+
+ -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.hex reads foo.hex and writes
+ to the program area; the device is automatically erased
+ first, unless the overlay option is used (as in -Owpf).
+ -wef foo.hex reads foo.hex and writes to the eeprom area;
+ there is *no* preceding erase, but SP12 will ensure that
+ all locations which are not specifically addressed by the
+ file contain 0xff - unless the overlay option is used.
+ During a write, you will see a progress bar like this:
+
+ oooooooooooooooooooooooo.......................................
+
+ 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."
+
+ -X Extended fuse bits
+ Valid combinations: -rX and -wX<n...n>. The latter command
+ writes all extended fuse bits in one go; you must supply
+ the right number of bits, or sp12 will barf. Refer to your
+ device's datasheet to see whether there are extended fuse
+ bits to write, and if so, how many. Note that the string
+ must include any non-fuse or otherwise fixed bits between
+ the writable fuses, while excluding such fixed bits at
+ either end of the string. (See also sp12dev.txt and
+ _sp12dev.)
+ You can write the n...n in hex if you want, but in that case
+ sp12 can't check the number of bits; the command -wX0x3 will
+ write zeroes into the fuse bits 2, 3, 4 and so on, if they
+ happen to exist.
+ Note that there are separate options for `fuses' (-F)
+ and `high fuses' (-H).
+
+
+FILES
+ sp12(.exe) The executable.
+ readme.linux,
+ readme.dos Describes software installation on Linux and Dos/MSW
+ sp12.txt This file
+ changes.txt Describes the changes between versions
+ hardware.txt About hardware connections
+ sp12dev.txt,
+ sp12rc.txt Ins and outs of the runtime configuration files
+ _sp12rc The runtime configuration file
+ _sp12dev The runtime device definitions file
+ COPYING.txt The GNU general public licence states the terms and
+ conditions for copying, distribution and modification
+ of this software
+ dongle.txt Describes Ken Huntington's `dongle'.
+ progrmmr.gif Shows the layout and diagram of the programmer board
+ Steve is using.
+ icp_intr.gif Shows the connections between the parallel port
+ and a target board which uses external power, and
+ has an sp12-compatible time constant for providing
+ power-on reset.
+ dongle.gif `Dongle' designed by Ken Huntington. Helps when
+ the parallel port signal is marginal. Avoids
+ the need for Sck termination as shown in the
+ above two .gifs. Makes the cable high-Z except
+ when sp12 is active. Perfectly transparent to
+ the software.
+ SOURCE This directory contains the source files and a
+ makefile for use with gcc or djgpp, see below.
+ CSDPMI This directory contains cwsdpmi. Read the
+ paragraph `installation' for details.
+
+ACKNOWLEDGEMENTS
+ SP12 binaries intended for Linux are compiled with gcc 3.2.
+ The 32-bit Dos 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. Have a look at
+ http://www.delorie.com/djgpp/getting.html for more information.
+
+ 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.
+
+ Kevin Towers improved the code for reading Intel HEX files, to be
+ compatible with flash data as generated by the IAR C compiler.
+ He contributed code to support the ATmega page modes, and conceived
+ the method for programming multiple uCs on a single target, using
+ a single command line.
+ He also noted further timing problems on a fast Celeron with
+ version 0.6; these are solved by the more accurate and faster
+ autocalibration routine in version 0.7 and higher.
+
+ Others who have contributed bug reports and/or suggested
+ improvements:
+ Arian van Dorsten
+ Robert Hyde
+ Zoran Kostic
+ Ludger Manten
+ Walter Waldner
+
+BUGS & BOTHER
+ Please report them to the authors.
+
+ SP12 is known to run in Linux, 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."
+
+AUTHORS
+ Software: Steven Bolt (sbolt@xs4all.nl)
+ Kevin Towers (ktowers@omnexcontrols.com)
+ Hardware: Ken Huntington (kenh@compmore.net)