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 - [filename or address(:data)] - [filename... OPTION SUMMARY i - 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' 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. 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. 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 [] [] 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 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. 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)