summaryrefslogtreecommitdiff
path: root/sp12.txt
blob: b5c3856aecf01969aaef2999d447b427abae0ef0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
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)