-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathWOZ Disk Image Reference 2.0.html
More file actions
1255 lines (1201 loc) · 72.1 KB
/
WOZ Disk Image Reference 2.0.html
File metadata and controls
1255 lines (1201 loc) · 72.1 KB
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
<!doctype html>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="profile" href="http://gmpg.org/xfn/11">
<title>WOZ Disk Image Reference 2.0 – applesauce</title>
<link rel='dns-prefetch' href='//www.google.com' />
<link rel='dns-prefetch' href='//s.w.org' />
<link rel="alternate" type="application/rss+xml" title="applesauce » Feed" href="https://applesaucefdc.com/feed/" />
<link rel="alternate" type="application/rss+xml" title="applesauce » Comments Feed" href="https://applesaucefdc.com/comments/feed/" />
<script type="text/javascript">
window._wpemojiSettings = {"baseUrl":"https:\/\/s.w.org\/images\/core\/emoji\/12.0.0-1\/72x72\/","ext":".png","svgUrl":"https:\/\/s.w.org\/images\/core\/emoji\/12.0.0-1\/svg\/","svgExt":".svg","source":{"concatemoji":"https:\/\/applesaucefdc.com\/wp-includes\/js\/wp-emoji-release.min.js?ver=5.2.2"}};
!function(a,b,c){function d(a,b){var c=String.fromCharCode;l.clearRect(0,0,k.width,k.height),l.fillText(c.apply(this,a),0,0);var d=k.toDataURL();l.clearRect(0,0,k.width,k.height),l.fillText(c.apply(this,b),0,0);var e=k.toDataURL();return d===e}function e(a){var b;if(!l||!l.fillText)return!1;switch(l.textBaseline="top",l.font="600 32px Arial",a){case"flag":return!(b=d([55356,56826,55356,56819],[55356,56826,8203,55356,56819]))&&(b=d([55356,57332,56128,56423,56128,56418,56128,56421,56128,56430,56128,56423,56128,56447],[55356,57332,8203,56128,56423,8203,56128,56418,8203,56128,56421,8203,56128,56430,8203,56128,56423,8203,56128,56447]),!b);case"emoji":return b=d([55357,56424,55356,57342,8205,55358,56605,8205,55357,56424,55356,57340],[55357,56424,55356,57342,8203,55358,56605,8203,55357,56424,55356,57340]),!b}return!1}function f(a){var c=b.createElement("script");c.src=a,c.defer=c.type="text/javascript",b.getElementsByTagName("head")[0].appendChild(c)}var g,h,i,j,k=b.createElement("canvas"),l=k.getContext&&k.getContext("2d");for(j=Array("flag","emoji"),c.supports={everything:!0,everythingExceptFlag:!0},i=0;i<j.length;i++)c.supports[j[i]]=e(j[i]),c.supports.everything=c.supports.everything&&c.supports[j[i]],"flag"!==j[i]&&(c.supports.everythingExceptFlag=c.supports.everythingExceptFlag&&c.supports[j[i]]);c.supports.everythingExceptFlag=c.supports.everythingExceptFlag&&!c.supports.flag,c.DOMReady=!1,c.readyCallback=function(){c.DOMReady=!0},c.supports.everything||(h=function(){c.readyCallback()},b.addEventListener?(b.addEventListener("DOMContentLoaded",h,!1),a.addEventListener("load",h,!1)):(a.attachEvent("onload",h),b.attachEvent("onreadystatechange",function(){"complete"===b.readyState&&c.readyCallback()})),g=c.source||{},g.concatemoji?f(g.concatemoji):g.wpemoji&&g.twemoji&&(f(g.twemoji),f(g.wpemoji)))}(window,document,window._wpemojiSettings);
</script>
<style type="text/css">
img.wp-smiley,
img.emoji {
display: inline !important;
border: none !important;
box-shadow: none !important;
height: 1em !important;
width: 1em !important;
margin: 0 .07em !important;
vertical-align: -0.1em !important;
background: none !important;
padding: 0 !important;
}
</style>
<link rel='stylesheet' id='wp-block-library-css' href='https://applesaucefdc.com/wp-includes/css/dist/block-library/style.min.css?ver=5.2.2' type='text/css' media='all' />
<link rel='stylesheet' id='contact-form-7-css' href='https://applesaucefdc.com/wp-content/plugins/contact-form-7/includes/css/styles.css?ver=5.1.3' type='text/css' media='all' />
<link rel='stylesheet' id='miniva-style-css' href='https://applesaucefdc.com/wp-content/themes/miniva/style.css?ver=5.2.2' type='text/css' media='all' />
<script type='text/javascript' src='https://applesaucefdc.com/wp-includes/js/jquery/jquery.js?ver=1.12.4-wp'></script>
<script type='text/javascript' src='https://applesaucefdc.com/wp-includes/js/jquery/jquery-migrate.min.js?ver=1.4.1'></script>
<link rel='https://api.w.org/' href='https://applesaucefdc.com/wp-json/' />
<link rel="EditURI" type="application/rsd+xml" title="RSD" href="https://applesaucefdc.com/xmlrpc.php?rsd" />
<link rel="wlwmanifest" type="application/wlwmanifest+xml" href="https://applesaucefdc.com/wp-includes/wlwmanifest.xml" />
<meta name="generator" content="WordPress 5.2.2" />
<link rel="canonical" href="https://applesaucefdc.com/woz/reference2/" />
<link rel='shortlink' href='https://applesaucefdc.com/?p=350' />
<link rel="alternate" type="application/json+oembed" href="https://applesaucefdc.com/wp-json/oembed/1.0/embed?url=https%3A%2F%2Fapplesaucefdc.com%2Fwoz%2Freference2%2F" />
<link rel="alternate" type="text/xml+oembed" href="https://applesaucefdc.com/wp-json/oembed/1.0/embed?url=https%3A%2F%2Fapplesaucefdc.com%2Fwoz%2Freference2%2F&format=xml" />
<style type="text/css">
.site-title,
.site-description {
position: absolute;
clip: rect(1px, 1px, 1px, 1px);
}
.site-header { background-image: url(https://applesaucefdc.com/wp-content/uploads/2018/06/header-1.png); }
</style>
<style type="text/css" id="custom-background-css">
body.custom-background { background-color: #ede2cf; }
</style>
<style type="text/css" id="wp-custom-css">
hr {
margin-top: 48px;
margin-bottom: 8px;
border: 5;
border-top: 2px solid #d44;
} </style>
</head>
<body class="page-template page-template-template-fullwidth page-template-template-fullwidth-php page page-id-350 page-child parent-pageid-59 custom-background posts-large logo-top menu-centered logo-default">
<svg viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" style="display:none;">
<symbol viewBox="0 0 16 16" id="search"><title>search</title> <path d="M14.7,13.3L11,9.6c0.6-0.9,1-2,1-3.1C12,3.5,9.5,1,6.5,1S1,3.5,1,6.5S3.5,12,6.5,12c1.2,0,2.2-0.4,3.1-1l3.7,3.7L14.7,13.3z
M2.5,6.5c0-2.2,1.8-4,4-4s4,1.8,4,4s-1.8,4-4,4S2.5,8.7,2.5,6.5z"/> </symbol>
</svg>
<div id="page" class="site">
<a class="skip-link screen-reader-text" href="#content">Skip to content</a>
<header id="masthead" class="site-header" role="banner">
<div class="container">
<div class="site-branding">
<div class="site-branding-text">
<p class="site-title"><a href="https://applesaucefdc.com/" rel="home">applesauce</a></p>
<p class="site-description">Apple II Floppy Drive Controller</p>
</div>
</div><!-- .site-branding -->
<nav id="site-navigation" class="main-navigation" role="navigation" aria-label="Primary">
<button class="menu-toggle" aria-controls="primary-menu" aria-expanded="false">Menu</button>
<ul id="primary-menu" class="primary-menu"><li id="menu-item-66" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-66"><a href="https://applesaucefdc.com/hardware/">Hardware</a></li>
<li id="menu-item-65" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-65"><a href="https://applesaucefdc.com/software/">Software</a></li>
<li id="menu-item-251" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-251"><a href="https://applesaucefdc.com/documentation/">Documentation</a></li>
<li id="menu-item-63" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-63"><a href="https://applesaucefdc.com/a2r/">A2R</a></li>
<li id="menu-item-64" class="menu-item menu-item-type-post_type menu-item-object-page current-page-ancestor menu-item-64"><a href="https://applesaucefdc.com/woz/">WOZ</a></li>
<li id="menu-item-420" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-420"><a href="https://applesaucefdc.com/order/">Order</a></li>
<li id="menu-item-34" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-34"><a href="https://applesaucefdc.com/contact/">Contact</a></li>
</ul> </nav><!-- #site-navigation -->
</div>
</header><!-- #masthead -->
<div id="content" class="site-content container">
<div id="primary" class="content-area">
<main id="main" class="site-main" role="main">
<article id="post-350" class="post-350 page type-page status-publish hentry post-single">
<header class="entry-header">
<h1 class="entry-title">WOZ Disk Image Reference 2.0</h1> </header><!-- .entry-header -->
<div class="entry-content">
<p>Created by John K. Morris<br />
jmorris@evolutioninteractive.com</p>
<p>Version 2.0 – December 16, 2018</p>
<p>Version 1.0 of the WOZ Disk Image Reference can be found <a href="https://applesaucefdc.com/woz/reference1/">here</a>.</p>
<p>Many thanks to the people who helped me prepare this document for release:<br />
John Brooks, David Brown, Bill Martens, Sean McNamara, Antoine Vignau, Olivier Galibert and 4am</p>
<hr />
<h2>Why yet another Apple II disk image format?</h2>
<p>This is probably the question many of you reading this document are asking. It basically comes down to the simple fact that none of the currently existing formats accurately represent the way data is encoded on an Apple II floppy disk. There is a place for a format that is an accurate representation of a bitstream that is also the exact length of a track so that it can be looped correctly. And since we are creating a format, it is also a great time to ensure that we organize the data in the image file in a way that allows for easy unpacking with as little memory and processing overhead as possible – this provides more performant usage in hardware and software emulators.</p>
<hr />
<h2>What benefits come with using the WOZ format?</h2>
<p>We seem to be doing just fine with the current file formats, why would we want to support the WOZ format? The big benefit is being able to successfully run copy protected software if you follow the emulation guidelines presented in this document. The second benefit is that the WOZ format is actually much simpler to implement than many of the other disk image formats. WOZ files also contain metadata about the disk image – such as disk name, product name, publisher, system requirements and language – that you can use to display additional information in your emulator.</p>
<hr />
<h2>What has changed in the WOZ specification for the 2.0 release?</h2>
<p>After releasing Applesauce, the flood of software began that has enabled a lot of validation of the WOZ format. Unfortunately, a few short comings were uncovered with the initial format. There were also some requests made to improve the format. This document details the 2.x specification. The 2.0 format is intended to be a replacement of the 1.0 format.</p>
<h3>File Header Changes</h3>
<p>The file identifier (bytes 0-3 of the file) was changed from WOZ1 to WOZ2. This was done since there are a couple of fundamental changes made to the format and we need to make sure that new WOZ 2.0 files are only consumed by hardware and software that is explicitly compatible with these changes.</p>
<h3>INFO Chunk Changes</h3>
<p>New INFO fields are indicated by the “2” in the Vers field in the INFO Chunk section of this document.</p>
<p>There are now flags for indicating whether track 0 contains boot sectors for 16 and/or 13 sector hardware. The Apple disk controller card contains a ROM (P5) that performs the task of bootstrap loading track $00 sector $0 from the disk and running it. This is what happens when you reboot your machine or use PR#6. The code contained within that boot sector is then responsible for loading up the rest of the disk. When Apple originally came out with the Disk II, it only dealt with 13-sector disks and 5&3 nibble encoding. When you booted the computer, the P5 ROM would look for the boot sector by identifying an address prolog with the nibble values D5 AA B5. Later on, with DOS 3.3, Apple introduced the 16-sector format along with 6&2 nibble encoding. This new format also needed a revised P5 ROM, known as the P5A. Since the two formats aren’t compatible with each other, they chose to change the default address prolog nibbles to D5 AA 96. The problem with this is that disks in one format are basically invisible to disks and hardware using the other format since they aren’t looking for the correct address prolog. The WOZ format now contains a Boot Sector Format indicating whether a boot sector exists for 13 and/or 16 sector ROMs. This can help emulators detect which ROM is needed when booting a disk.</p>
<p>The Optimal Bit Timing is now provided. This value dictates the rate at which bits should be provided to the disk controller card. There are a several disks that use slightly non-standard bit timings. Most of these work just fine under emulation, but many of these disks load faster if the bits are provided at the correct speed. This value is in 125 nanosecond increments, so 8 is equal to 1 microsecond. And a standard bit rate for a 5.25 disk would be 32 (4µs), and a 3.5 would be 16 (2µs).</p>
<p>Another feature requested by emulator developers was to hoist some of the compatible hardware values from the META chunk and place it into the INFO chunk in an easier to parse format. So, there is now a Compatible Hardware bit field as well as a Required RAM one.</p>
<p>A Largest Track field was added in order to help emulators allocate a properly sized buffer for storing track data.</p>
<h3>TMAP Chunk Changes</h3>
<p>The order of the TMAP data for 3.5 disks has changed to make it more efficient to find the proper offset ((track << 1) + side). The TMAP chunk is unchanged for 5.25 disks.</p>
<h3>TRKS Chunk Changes</h3>
<p>It turns out that there was a trick that was more effective than I thought possible. Most 5.25 disks end up using about 6300-6500 bytes of data per track, but this all depends on the speed of the drive when writing the disk. I allocated 6646 bytes to each track to make sure there was a good pad in there for disks that were purposely written at a slower speed to pack more data on a track. It seems like some disks (I’m looking at you Datasoft) had things turned down even more and were able to fit an amazing 6680 bytes of data on a track. This broke the WOZ track size limit by 34 bytes.</p>
<p>The TRKS chunk was modified in order to allow a variable number of 512-byte blocks to be allocated for each track. This will allow the WOZ format to remain as small as possible for “normal” 5.25 disks, but also be able to accommodate ones with larger track data requirements. This also allows for more optimal storage for 3.5 disks as each speed zone can have the track size tuned for it.</p>
<p>The write hints have also been removed from the TRKS chunk and moved to their own WRIT chunk.</p>
<h3>WRIT Chunk Addition</h3>
<p>A new WRIT chunk has been added to the WOZ specification in order to provide detailed instructions for programs wanting to write WOZ files back to a real floppy disk. Inclusion of this chunk in a WOZ file is optional.</p>
<h3>Freaking Out Like a MC3470 Changes</h3>
<p>Due to some new findings in the analysis of MC3470, there is a new recommended implementation that should more accurately model the proper behavior.</p>
<hr />
<h2>Implementation Details</h2>
<p>Integrating WOZ support with your product is more than just loading data from a new type of container. It is also about how that data is used. Yes, it is possible to just shovel bits from the WOZ right into your bitstream, and many disk images will work just fine like that. But, by taking the following guidelines into account, your implementation will enable disk functionality that is also compatible with all copy protection schemes. <i>Yes, this means you can run copy protected software in system and disk drive emulators without the need to crack it first!</i></p>
<h3>Cross-Track Synchronization</h3>
<p>When Steve Wozniak was hacking up Shugart drives to make the Disk II, one of the parts that he threw away was the sync sensor. The sync sensor involved a light source on one side of the disk with a sensor on the other. This sensor would allow the drive to know when it made a full revolution, as the disk media itself had a hole that would let the light pass though as it passed the sensor. It really wasn’t a necessary part for Wozniak’s soft-sectored design that was going to be used for storing data on the disk.</p>
<p><img class=" wp-image-115 aligncenter" src="https://applesaucefdc.com/wp-content/uploads/2018/06/unsynced_and_synced-300x140.png" alt="" width="669" height="312" srcset="https://applesaucefdc.com/wp-content/uploads/2018/06/unsynced_and_synced-300x140.png 300w, https://applesaucefdc.com/wp-content/uploads/2018/06/unsynced_and_synced-768x357.png 768w, https://applesaucefdc.com/wp-content/uploads/2018/06/unsynced_and_synced-1024x477.png 1024w, https://applesaucefdc.com/wp-content/uploads/2018/06/unsynced_and_synced.png 1100w" sizes="(max-width: 669px) 100vw, 669px" /></p>
<h5 style="text-align: center;">A NORMAL UNSYNCHRONIZED DISK VS A SYNCHRONIZED ONE.</h5>
<p>When it came to businesses designing copy protection schemes, this was something that they could use to their advantage. The professional disk copiers could easily write out all tracks synchronized with each other, something that your average Apple II floppy drive couldn’t do. Then, the software would read a known sector on a specific track and, when it jumped to a neighboring track, it could make sure that the first sector it encountered there was the one it expected. Later protection schemes even made track widths which were almost 2 standard tracks wide and were accurate to within 1 bit. As much as the disk copy programs tried, they could only sync up tracks by sheer luck.</p>
<p>To circumvent these kind of copy protection checks, the WOZ format uses a Track Map (see the “TMAP Chunk” section below). This allows us to assign a track image to any number of quarter tracks on a disk. An entire disk could even be a single track if we wanted.</p>
<p>There are a couple of rules to follow with regards to changing tracks within the emulator:</p>
<p>Firstly, if the tracks you are changing between have matching values in the TMAP, then don’t change the track data. This will prevent any hiccups in the bitstream and can be a good performance gain to boot.</p>
<p>The second rule is that you need to maintain a bit pointer into your bitstream. You always need to know which bit you are on. When you do change tracks, you need to start the new bitstream at the same relative bitstream position – you cannot simply start the pointer at the beginning of the stream. You need to maintain the illusion of the head being over the same area of the disk, just shifted to a new track.</p>
<p>Also be sure to account for the fact that track lengths are inconsistent on a disk due to fluctuations in drive speed. Something like this works well to maintain the relative position if your environment can work with 32-bit or greater values:</p>
<pre>new_position = current_position * new_track_length / current_track_length</pre>
<p>Remember to maintain the bit position even when on an empty track (TMAP value of 0xFF). Since the empty track has no data, and therefore no length, using a fake length of 51,200 bits (6400 bytes) works very well.</p>
<h3>Freaking Out Like a MC3470</h3>
<p>On the Apple II, floppy disk data is written to the disk based on a 4µs clock. Whenever there is a 1 bit to write, the polarity of the magnetic flux under the drive head is transitioned from its current state to the opposite. If a zero needs to be written out, the 4µs clock is skipped (no transition occurs).</p>
<p>The MC3470 chip is the heart of the Apple II floppy drive. It reads the magnetic flux pattern off the disk and sends out a pulse for every flux transition it sees. This gives us back our 1 bits and our 0 bits come from the 4µs clock going by with no pulse.</p>
<p>One of the nice features of the MC3470 is that it has an internal amplification system to adapt to the varying magnetic strengths of each disk. If it has a hard time reading the disk, it can turn up its amp until it finds the signal. It allows the drive to read a wide assortment of disks. The Apple II uses GCR encoding to store bits on the disk. It is a very efficient system that was used widely on many platforms, because it doesn’t use clock bits to frame up your data bits, giving you more room to write data. This technique also has a drawback though, which is never being able to record more than two 0 bits in a row. It is why data on an Apple II is stored as nibbles instead of plain binary bytes.</p>
<p>One very popular copy protection is referred to as “fake bits” or “weak bits” – this technique is actually an exploit against the MC3470. It comes from the idea of what happens when we make it read more than two 0 bits in a row. What happens is that our poor MC3470 thinks that it is doing a bad job reading the disk and keeps trying to turn up its amp to find the flux signal. It does this until it gets to the point that it amplifies background electrical noise so much that it <i>thinks</i> that it sees a transition and sends out a false pulse, which the computer happily records as a 1 bit.</p>
<p>So, how can this failure be used as copy protection? The software developers simply put these blank fake bit areas on the disk where the software knows where to find them. It then reads some good nibbles followed by the fake bits area. This gives us some good nibbles followed by some random valued nibble. This in itself is not particularly useful until you do it multiple times and see that the random nibble changes every time you read it! If the value keeps changing, then you know that it isn’t a copy of the disk. How does it know that? Because programs like Copy II+ and Locksmith will read those same good nibbles followed by the random nibble, and then they will promptly write out all of the nibble values that they captured, thinking that they are all good. The random nibble is no longer random, it will never change from the value that has been captured, and now the copy protected software will know that it is actually a copy.</p>
<p>So how does the WOZ format deal with this? Well, the first part of the problem isn’t taken care of within the WOZ format itself. The WOZ format is an offshoot of the Applesauce Floppy Drive Controller project. The Applesauce has a way to determine when it is seeing these fake bits and changes the fake bits back to the 0 bits that existed on the original disk.</p>
<p>Now that we are back to having long runs of 0s in the bitstream, we now need to emulate the MC3470 freaking out about them. There are a couple factors that come into play with making an accurate representation of this behavior. For those of you familiar with the WOZ 1.0 specification, this recommended implementation behavior has changed.</p>
<p>The first factor is that there is a latency of up to 5µs from when the head sees a <strong>real</strong> transition to when it passes through the MC3470 filter, differentiator, pulse generator and finally sent out as a pulse. But it appears that <strong>fake</strong> transitions have a much shorter latency. Due to this, fake bits are introduced earlier into the pulse stream than you would expect. The second factor is to remember that the read head is an analog device and isn’t reading a single point on the disk surface, but actually one that has a radius of about 7.5µs. As long as it has a flux within its window, either coming or going, it remains happy. It is when there is nothing in this windows that it starts freaking out. This means that we are definitely in our happy place with two 0 bits as the interval between them is 12µs (vs the window diameter of 15µs). Even three 0 bits is fairly safe with an interval of 16µs (only needs to deal with 1µs of starting to freak out), but this will sometimes throw a fake bit.</p>
<p>So, knowing these things, the recommended way to implement this behavior is to maintain an 4-bit wide buffer for the bits coming out of the WOZ file. Every time a new bit needs to be outputted, shift the buffer left 1 bit and put the next bit from the WOZ into bit 0 of the buffer. Then send the value in bit 1 of the buffer. This will give us our desired latency. So, how do we know when to send in the random fake bits? If the value of our buffer is 0, then we randomly output a bit instead of sending bit 1.</p>
<pre>uint8_t head_window = 0;
uint8_t nextDiskBit() {
head_window <<= 1;
head_window |= getNextWozBit();
if ((head_window & 0x0f) != 0x00) {
return (head_window & 0x02) >> 1;
} else {
return fakeBit();
}
}</pre>
<p>Of course, coming up with random values like this can be a bit processor intensive, so it is adequate to create a randomly-filled circular buffer of 32 bytes. We then just pull bits from this whenever we are in “fake bit mode”. This buffer should also be used for empty tracks as designated with an 0xFF value in the TMAP Chunk (see below). You will want to have roughly 30% of the buffer be 1 bits.</p>
<h3>When Off Isn’t Really Off</h3>
<p>Turning on the floppy drive motor and getting the disk up to its 300 RPM speed isn’t a particularly fast operation. When it came to DOS, it used a simple mechanism to read a file: turn disk on, read data, turn disk off. This turned out to be a fairly slow process as it kept needing to spin up the disk when you were accessing multiple files. So, a simple hardware optimization was created that would use a timing circuit to delay the turning off of the motor for a period of 1 second. This way if you were reading a bunch of files in a row, the motor wouldn’t actually turn off between them and you could access the files much quicker. Pretty clever!</p>
<p>When it came to the copy protection arms race, a mechanism as clever as this would of course end up being weaponized. In order to discourage people from boot tracing their software, several protections took to the idea of turning off the floppy drive motor <i>before</i> trying to read some sectors. The developers knew that the disk would still have almost 5 full revolutions before actually turning off, so it wasn’t a problem. But, if the crackers stopped program execution in this area, then they would lose access to the next sectors being read since the drive would turn off automatically after 1 second.</p>
<p>Therefore, a 1 second delay after accessing the “drive motor off” soft-switch at $C088,X needs to be implemented to allow software to continue reading sectors.</p>
<h3>Abusing Disk Controller Soft Switches for Fun and Profit</h3>
<p>The floppy drive is accessed by using the soft switches associated with the floppy disk controller card. These are in the range $C0x0-C0xF, with the value of x being $8 + the slot number. All of these switches have a specific function like turning the motor on/off, reading/writing data, or controlling the head stepper motor phases. But due to the way the circuit was laid out on the disk controller card, they also have some unexpected behaviors. Many copy protection schemes relied on these undocumented side effects.</p>
<p>As referenced in the previous section, when you access $C088,X it begins the timer to turn off the drive motor. But, it also returns the value of the data latch! Why would it do that?!? It does this for one simple reason, the low bit of the address line (A0) is connected through a NOT gate to the Output Enable line of the data latch. Therefore every soft switch on an even address should actually return the value of the data latch.</p>
<p>Another nuance that needs to be implemented is that reading $C08D,X will reset the sequencer and clear the contents of the data latch. This is used to great effect in the E7 protection scheme to resynchronize the nibble stream to make timing bits become valid data bits.</p>
<hr />
<h2>WOZ File Format Specification</h2>
<p>A WOZ file uses a chunk-based file binary format that provides future-proof expandability in a way that is safe for older software which may not recognize newer data chunks.</p>
<p><b>All data is stored little-endian.</b></p>
<p>WOZ files begin with the following 12-byte header in order to identify the file type as well as detect any corruption that may have occurred. The easiest way to detect that a file is indeed a WOZ file is to check the first 8 bytes of the file for the signature. The remaining 4 bytes are a CRC of all remaining data in the file. This is only provided to allow you to ensure file integrity and is not necessary to process the file. If the CRC is 0x00000000, then no CRC has been calculated for the file and should be ignored. The exact CRC routine used is shown in Appendix A, and you should be passing in 0x00000000 as the initial crc value.</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 8%;">Byte</th>
<th style="width: 17%;">Value</th>
<th style="width: 60%;">Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;">0</td>
<td><span style="color: #000000; font-family: 'Courier New'; font-size: medium;">57 4F 5A 32</span></td>
<td><span style="color: #000000; font-family: Helvetica; font-size: small;">The ASCII string ‘WOZ2’. </span><span style="color: #000000; font-family: 'Courier New'; font-size: medium;">0x325A4F57</span></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;">4</td>
<td><span style="color: #000000; font-family: 'Courier New'; font-size: medium;">FF</span></td>
<td><span style="color: #000000; font-family: Helvetica; font-size: small;">Make sure that high bits are valid (no 7-bit data transmission)</span></td>
</tr>
<tr>
<td style="background-color: #ddd;">5</td>
<td><span style="color: #000000; font-family: 'Courier New'; font-size: medium;">0A 0D 0A</span></td>
<td><span style="color: #000000; font-family: Helvetica; font-size: small;">LF CR LF – File translators will often try to convert these.</span></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;">8</td>
<td><span style="color: #000000; font-family: 'Courier New'; font-size: medium;">xx xx xx xx</span></td>
<td><span style="color: #000000; font-family: Helvetica; font-size: small;">CRC32 of all remaining data in the file. The method used to generate the CRC is described in Appendix A.</span></td>
</tr>
</tbody>
</table>
<p>After the header comes a sequence of chunks which each contain information about the disk image. Using chunks allows for the WOZ disk format to provide forward compatibility as chunks can be added to the specification and will just be safely ignored by applications that do not care (or know) about the information. For lower-performance emulation platforms, the primary data chunks are all located in fixed positions so that direct access to data is possible using just offsets from the start of the file.</p>
<p>All chunks have the following structure:</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Size</th>
<th style="width: 20%;">Name</th>
<th style="width: 55%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;"><b>+0</b></td>
<td>4 bytes</td>
<td>Chunk ID</td>
<td>4 ASCII characters that make up the ID of the chunk</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;"><b>+4</b></td>
<td>uint32</td>
<td>Chunk Size</td>
<td>The size of the chunk data in bytes.</td>
</tr>
<tr>
<td style="background-color: #ddd;"><b>+8</b></td>
<td>…</td>
<td>Chunk Data</td>
<td>The chunk data.</td>
</tr>
</tbody>
</table>
<p>To process the file, you start at the first Chunk ID which will be located at byte 12 of the file, immediately following the header. You read the Chunk ID and the Chunk Size following it. If you want to process this chunk, then your file pointer will be at the start of the data. If you don’t care about this chunk, then skip the number of bytes as Chunk Size indicates and you will now be at the next Chunk ID.</p>
<pre>while(data_stream.availableToRead() > 8) {
uint32_t chunk_id = data_stream.readU32();
uint32_t chunk_size = data_stream.readU32();
switch(chunk_id) {
case INFO_CHUNK_ID:
// read the INFO chunk
break;
case TMAP_CHUNK_ID:
// read the TMAP chunk
break;
case TRKS_CHUNK_ID:
// read the TRKS chunk
break;
case META_CHUNK_ID:
// read the META chunk
break;
default:
// no idea what this chunk is, so skip it
data_stream.skip(chunk_size);
}
}
</pre>
<hr />
<h3>INFO Chunk</h3>
<p>The first chunk in an Applesauce file is always an ‘INFO’ chunk. This contains some fundamental information about the contained image. The data of the ‘INFO’ chunk begins at byte 20 of the file and is 60 bytes long (pad chunk with zeros to full length).</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Byte</th>
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Type</th>
<th style="width: 10%;">Vers</th>
<th style="width: 20%;">Name</th>
<th style="width: 35%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>12</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top"></td>
<td valign="top">‘INFO’ Chunk ID</td>
<td valign="top">0x4F464E49</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>16</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top"></td>
<td valign="top">Chunk Size</td>
<td valign="top">Size is always 60.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>20</b></td>
<td style="background-color: #ddd;" valign="top"><b>+0</b></td>
<td valign="top">uint8</td>
<td valign="top">1</td>
<td valign="top">INFO Version</td>
<td valign="top">Version number of the INFO chunk.<br />
Current version is 2.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>21</b></td>
<td style="background-color: #ddd;" valign="top"><b>+1</b></td>
<td valign="top">uint8</td>
<td valign="top">1</td>
<td valign="top">Disk Type</td>
<td valign="top">1 = 5.25, 2 = 3.5</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>22</b></td>
<td style="background-color: #ddd;" valign="top"><b>+2</b></td>
<td valign="top">uint8</td>
<td valign="top">1</td>
<td valign="top">Write Protected</td>
<td valign="top">1 = Floppy is write protected</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>23</b></td>
<td style="background-color: #ddd;" valign="top"><b>+3</b></td>
<td valign="top">uint8</td>
<td valign="top">1</td>
<td valign="top">Synchronized</td>
<td valign="top">1 = Cross track sync was used during imaging</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>24</b></td>
<td style="background-color: #ddd;" valign="top"><b>+4</b></td>
<td valign="top">uint8</td>
<td valign="top">1</td>
<td valign="top">Cleaned</td>
<td valign="top">1 = MC3470 fake bits have been removed</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>25</b></td>
<td style="background-color: #ddd;" valign="top"><b>+5</b></td>
<td valign="top">UTF-8<br />
32 bytes</td>
<td valign="top">1</td>
<td valign="top">Creator</td>
<td valign="top">Name of software that created the WOZ file. String in UTF-8. No BOM. Padded to 32 bytes using space character (0x20).<br />
ex: “Applesauce v1.0 <span class="Apple-converted-space"> </span>”</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>57</b></td>
<td style="background-color: #ddd;" valign="top"><b>+37</b></td>
<td valign="top">uint8</td>
<td valign="top">2</td>
<td valign="top">Disk Sides</td>
<td valign="top">The number of disk sides contained within this image. A 5.25 disk will always be 1. A 3.5 disk can be 1 or 2.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>58</b></td>
<td style="background-color: #ddd;" valign="top"><b>+38</b></td>
<td valign="top">uint8</td>
<td valign="top">2</td>
<td valign="top">Boot Sector Format</td>
<td valign="top">The type of boot sector found on this disk. This is only for 5.25 disks. 3.5 disks should just set this to 0.<br />
0 = Unknown<br />
1 = Contains boot sector for 16-sector<br />
2 = Contains boot sector for 13-sector<br />
3 = Contains boot sectors for both</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>59</b></td>
<td style="background-color: #ddd;" valign="top"><b>+39</b></td>
<td valign="top">uint8</td>
<td valign="top">2</td>
<td valign="top">Optimal Bit Timing</td>
<td valign="top">The ideal rate that bits should be delivered to the disk controller card. This value is in 125 nanosecond increments, so 8 is equal to 1 microsecond. And a standard bit rate for a 5.25 disk would be 32 (4µs).</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>60</b></td>
<td style="background-color: #ddd;" valign="top"><b>+40</b></td>
<td valign="top">uint16</td>
<td valign="top">2</td>
<td valign="top">Compatible Hardware</td>
<td valign="top">Bit field with a 1 indicating known compatibility. Multiple compatibility flags are possible. A 0 value represents that the compatible hardware list is unknown.<br />
0x0001 = Apple ][<br />
0x0002 = Apple ][ Plus<br />
0x0004 = Apple //e (unenhanced)<br />
0x0008 = Apple //c<br />
0x0010 = Apple //e Enhanced<br />
0x0020 = Apple IIgs<br />
0x0040 = Apple //c Plus<br />
0x0080 = Apple ///<br />
0x0100 = Apple /// Plus</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>62</b></td>
<td style="background-color: #ddd;" valign="top"><b>+42</b></td>
<td valign="top">uint16</td>
<td valign="top">2</td>
<td valign="top">Required RAM</td>
<td valign="top">Minimum RAM size needed for this software. This value is in K (1024 bytes). If the minimum size is unknown, this value should be set to 0. So, a requirement of 64K would be indicated by the value 64 here.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>64</b></td>
<td style="background-color: #ddd;" valign="top"><b>+44</b></td>
<td valign="top">uint16</td>
<td valign="top">2</td>
<td valign="top">Largest Track</td>
<td valign="top">The number of blocks (512 bytes) used by the largest track. Can be used to allocate a buffer with a size safe for all tracks.</td>
</tr>
</tbody>
</table>
<p>The chunk is versioned to allow for adding additional info in the future. The “Vers” column in the table above indicates at which version the data field became available. When reading data from the chunk, make sure that value you are looking for actually exists within the version of the chunk you are reading.</p>
<hr />
<h3>TMAP Chunk</h3>
<p>The ‘TMAP’ chunk contains a track map. This allows you to map physical drive tracks with the track data contained within the image file ‘TRKS’ chunk. This system is used because, on a 5.25 drive, the physical drive head is larger than the width of the written track and so the track is also visible from neighboring quarter tracks. For example, the data of track 1.00 is actually visible while reading from track 0.75 or 1.25. Instead of storing copies of track data for every possible quarter track, we use the map to point multiple quarter tracks to a single track image.</p>
<table class="aligncenter" style="width: 95%;" border="2">
<tbody>
<tr>
<td valign="top"><b>Track</b></td>
<td valign="top">0.00</td>
<td valign="top">0.25</td>
<td valign="top">0.50</td>
<td valign="top">0.75</td>
<td valign="top">1.00</td>
<td valign="top">1.25</td>
<td valign="top">1.50</td>
<td valign="top">1.75</td>
<td valign="top">2.00</td>
<td valign="top">2.25</td>
<td valign="top">2.50</td>
<td valign="top">2.75</td>
<td valign="top">3.00</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><b>Maps</b></td>
<td valign="top">00</td>
<td valign="top">00</td>
<td valign="top">FF</td>
<td valign="top">01</td>
<td valign="top">01</td>
<td valign="top">01</td>
<td valign="top">FF</td>
<td valign="top">02</td>
<td valign="top">02</td>
<td valign="top">02</td>
<td valign="top">FF</td>
<td valign="top">03</td>
<td valign="top">03</td>
</tr>
</tbody>
</table>
<p>The data of the ‘TMAP’ chunk begins at byte 88 of the file and is 160 bytes long.</p>
<p>Each map entry contains an index number for the track data contained within the ‘TRKS’ chunk. If the map entry is 0, then the correct track data to be using is the first entry in the ‘TRKS’ chunk. Any blank tracks are given a value of 255 (0xFF) in the map and the emulator should be outputting random bits in this case.</p>
<p>The mapping changes slightly between 5.25 and 3.5 disks. This is the format for the table for the layout of a 5.25 disk. The table only shows to track 35, but can also accommodate 40 track disks. All unused map entries should have a 255 (0xFF) value.</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Byte</th>
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Type</th>
<th style="width: 23%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>80</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">‘TMAP’ Chunk ID</td>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">0x50414D54</span></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>84</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">Chunk Size</td>
<td valign="top">Size is always 160.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>88</b></td>
<td style="background-color: #ddd;" valign="top"><b>+0</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 0.00</td>
<td valign="top">Index of TRKS entry to use for Track 0.00.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>89</b></td>
<td style="background-color: #ddd;" valign="top"><b>+1</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 0.25</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>90</b></td>
<td style="background-color: #ddd;" valign="top"><b>+2</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 0.50</td>
<td valign="top"></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>91</b></td>
<td style="background-color: #ddd;" valign="top"><b>+3</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 0.75</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>92</b></td>
<td style="background-color: #ddd;" valign="top"><b>+4</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 1.00</td>
<td valign="top"></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>…</b></td>
<td style="background-color: #ddd;" valign="top"><b>…</b></td>
<td valign="top"></td>
<td valign="top">…</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>228</b></td>
<td style="background-color: #ddd;" valign="top"><b>+140</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 35.00</td>
<td valign="top"></td>
</tr>
</tbody>
</table>
<p>This is the mapping for 3.5 disks:</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Byte</th>
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Type</th>
<th style="width: 23%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>80</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">‘TMAP’ Chunk ID</td>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">0x50414D54</span></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>84</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">Chunk Size</td>
<td valign="top">Size is always 160.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>88</b></td>
<td style="background-color: #ddd;" valign="top"><b>+0</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 0, Side 0</td>
<td valign="top">Index of TRKS entry to use for Track 0, Side 0.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>89</b></td>
<td style="background-color: #ddd;" valign="top"><b>+1</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 0, Side 1</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>90</b></td>
<td style="background-color: #ddd;" valign="top"><b>+2</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 1, Side 0</td>
<td valign="top"></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>…</b></td>
<td style="background-color: #ddd;" valign="top"><b>…</b></td>
<td valign="top"></td>
<td valign="top">…</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>246</b></td>
<td style="background-color: #ddd;" valign="top"><b>+158</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 79, Side 0</td>
<td valign="top"></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>247</b></td>
<td style="background-color: #ddd;" valign="top"><b>+159</b></td>
<td valign="top">uint8</td>
<td valign="top">Track 79, Side 1</td>
<td valign="top"></td>
</tr>
</tbody>
</table>
<hr />
<h3>TRKS Chunk</h3>
<p>The ‘TRKS’ chunk contains the data for all of the unique tracks. The data of the ‘TRKS’ chunk begins at byte 256. For more efficient track data copying from SD cards and other block devices, all track data is stored in 512-byte blocks and the blocks are 512 byte aligned relative to the start of the WOZ file. The start of the TRKS chunk has an array of TRK structures to locate all of the actual bit data within the file. The actual bit data begins at byte 1536 (block 3) of the WOZ file. While every track can be a different size, this is rarely the case. Just about all 5.25 floppy disk tracks will tend to each be 13 blocks long. The track sizes for a 3.5 floppy disk will be different for each speed zone. If needed, the ‘INFO’ chunk contains a Largest Track value that you can use to safely allocate a storage buffer for any tracks in this WOZ file.</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Byte</th>
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Type</th>
<th style="width: 23%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>248</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">‘TRKS’ Chunk ID</td>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">0x534B5254</span></td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>252</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">Chunk Size</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>256</b></td>
<td style="background-color: #ddd;" valign="top"><b>+0</b></td>
<td valign="top">TRK</td>
<td valign="top">Track 00</td>
<td valign="top">First track in track array. TMAP value of 0.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>264</b></td>
<td style="background-color: #ddd;" valign="top"><b>+8</b></td>
<td valign="top">TRK</td>
<td valign="top">Track 01</td>
<td valign="top">Second track in track array. TMAP value of 1.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>272</b></td>
<td style="background-color: #ddd;" valign="top"><b>+16</b></td>
<td valign="top">TRK</td>
<td valign="top">Track 02</td>
<td valign="top">Third track in track array. TMAP value of 2.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>…</b></td>
<td style="background-color: #ddd;" valign="top"><b>…</b></td>
<td valign="top"></td>
<td valign="top">…</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>1528</b></td>
<td style="background-color: #ddd;" valign="top"><b>+1272</b></td>
<td valign="top">TRK</td>
<td valign="top">Track 159</td>
<td valign="top">Last track in track array. TMAP value of 159.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>1536</b></td>
<td style="background-color: #ddd;" valign="top"><b>+1280</b></td>
<td valign="top">BITS</td>
<td valign="top">Beginning of Track Data Blocks</td>
<td valign="top">Start of the actual track bits.</td>
</tr>
</tbody>
</table>
<p>The structure of the TRK type in the previous table is as follows:</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Byte</th>
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Type</th>
<th style="width: 23%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"><strong>+0</strong></td>
<td valign="top">uint16</td>
<td valign="top">Starting Block</td>
<td valign="top">First block of BITS data. This value is relative to the start of the file, so the first possible starting block is 3. Multiply this value by 512 (x << 9) to get the starting byte of the BITS data.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"><strong>+2</strong></td>
<td valign="top">uint16</td>
<td valign="top">Block Count</td>
<td valign="top">Number of blocks for this BITS data.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"><strong>+4</strong></td>
<td valign="top">uint32</td>
<td valign="top">Bit Count</td>
<td valign="top">The number of bits in the bitstream.</td>
</tr>
</tbody>
</table>
<p>The TRKS chunk always contains 160 TRK entires, but most disks will not use them all. All unused TRK structures should be filled out with zeros for all values.</p>
<p>The bitstream data is the series of bits recorded from the floppy drive and normalized to 4µs intervals for 5.25 disks and 2µs for 3.5 disks. The bits are packed into bytes, but the bytes will not necessarily be representative of nibble values as timing bits are also represented within the bitstream. When processing the bitstream, the order of bits within each byte is high to low, meaning the high bit goes first and the low bit is last. Since this bitstream is the flow of data directly from the floppy drive, it will need to pass through a Logic State Sequencer as found on the Disk II Interface Card, Apple 5.25 Drive Controller Card or IWM chip to create nibbles. But, due to the fact that the bitstream timing has already been normalized, you can use a very lightweight implementation of one. The Logic State Sequencer performs the function of converting the bitstream to a nibble stream as well as enforcing the proper nibble timing that many copy protection schemes will check.</p>
<p>If you are creating a floppy drive emulator for use with a real Apple II, then you will simply be stepping to the next bit in the bitstream at the rate specified by the Optimal Bit Timing in the INFO chunk. If the bit has a 1 value, then you send a 1µs pulse on the RDDATA line. For a 3.5 drive, the pulse width would be 0.5µs.</p>
<p>If the Cleaned value of the ‘INFO’ chunk is 1, then any fake bits generated by the MC3470 during the imaging process will have been removed and replaced with 0 bit values (see the Implementation Details section for proper handling of these).</p>
<hr />
<h3>WRIT Chunk (optional)</h3>
<p>The ‘WRIT’ chunk contains the information necessary to be able to write the WOZ file to a physical floppy.</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Byte</th>
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Type</th>
<th style="width: 23%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">‘WRIT’ Chunk ID</td>
<td valign="top">0x54495257</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">Chunk Size</td>
<td valign="top"></td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top">+0</td>
<td valign="top">WTRK</td>
<td valign="top">Array of Track Writes</td>
<td valign="top"></td>
</tr>
</tbody>
</table>
<p>The WTRK structure provides all of the information for writing a single track to disk. Within each write there is the ability to insert multiple write commands. Each write command specifies which bits should be written to which area of the disk. For many simple disk layouts, there will just be a single write command for the entire track. But more complex writes, like if you needed to have data interleaved on neighboring half or even quarter tracks, can be done using multiple write command. The primary difference between using a single write command vs multiple is that the drive head is in write mode for the entire duration of a write command. Between write commands, the drive head is in read mode. This allows you to ensure that data on neighboring tracks is not overwritten.</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Offset</th>
<th style="width: 18%;">Size</th>
<th style="width: 25%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>+0</b></td>
<td valign="top">uint8</td>
<td valign="top">Track Number</td>
<td valign="top">The track number at which to write this data. For 5.25 disks, this value is in half-phases or quarter tracks (0 = 0.00, 4 = 1.00, 5 = 1.25). For 3.5 disks, this value indicates track number as well as side. The formula ((track << 1) + side) can be used (0 = Track 0, Side 0, 1 = Track 0, Side 1, 2 = Track 1, Side 0).</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>+1</b></td>
<td valign="top">uint8</td>
<td valign="top">Command Count</td>
<td valign="top">The number of commands in the write array.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>+2</b></td>
<td valign="top">uint8</td>
<td valign="top">Additional Write Functions Bit Field</td>
<td valign="top">Bit field with a 1 indicating to perform the action:<br />
0x01 = Wipe the track before writing.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>+3</b></td>
<td valign="top">uint8</td>
<td valign="top">–</td>
<td valign="top">Reserved and must be zero.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>+4</b></td>
<td valign="top">uint32</td>
<td valign="top">BITS checksum</td>
<td valign="top">Checksum of the entire used BITS data of this TRK. The proper data length can be calculated by (TRK.bitCount + 7) / 8. Used to determine if the BITS has changed since the WRIT chunk was written.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>+8</b></td>
<td valign="top">WCMD</td>
<td valign="top">Array of Write Commands</td>
<td valign="top"></td>
</tr>
</tbody>
</table>
<p>The structure of the WCMD type is as follows:</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Offset</th>
<th style="width: 18%;">Size</th>
<th style="width: 25%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>+0</b></td>
<td valign="top">uint32</td>
<td valign="top">Index of starting bit</td>
<td valign="top">The index of the first bit of this write.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>+4</b></td>
<td valign="top">uint32</td>
<td valign="top">Bit Count</td>
<td valign="top">The number of bits to write.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>+8</b></td>
<td valign="top">uint8</td>
<td valign="top">Leader Nibble</td>
<td valign="top">If this write requires leader nibbles, then this is the value for it. Typical value for this is 0xFF. If no leader is needed, then set value to 0x00.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>+9</b></td>
<td valign="top">uint8</td>
<td valign="top">Leader Nibble Bit Count</td>
<td valign="top">The number of bits that leader nibbles have. Typical value for DOS 3.3 and ProDOS would be 10.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>+10</b></td>
<td valign="top">uint8</td>
<td valign="top">Leader Count</td>
<td valign="top">The number of Leader Nibbles that should be written before the bit data.</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>+11</b></td>
<td valign="top">uint8</td>
<td valign="top">–</td>
<td valign="top">Reserved and currently used to pad each WCMD to 4 byte boundaries. Must be zero.</td>
</tr>
</tbody>
</table>
<p>The Leader Nibble information in the WCMD structure is used to ensure a clean gap 1, it contains a nibble value and bit count for the nibbles that should be written before the data bits. For a normal DOS 3.3 or ProDOS disk, the leader would be 128 FF/10 nibbles.</p>
<hr />
<h3>META Chunk (optional)</h3>
<p>The ‘META’ chunk contains metadata for the disk image and its existence is optional in the WOZ file. The metadata is stored as a tab-delimited UTF-8 list of keys and values. Columns are by separated by a tab character (‘\t’ 0x09). All rows end with a linefeed character (‘\n’ 0x0A)</p>
<table class="aligncenter" style="width: 95%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 10%;">Byte</th>
<th style="width: 10%;">Offset</th>
<th style="width: 10%;">Type</th>
<th style="width: 23%;">Name</th>
<th style="width: 42%;">Usage</th>
</tr>
</thead>
<tbody>
<tr>
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">‘META’ Chunk ID</td>
<td valign="top">0x4154454D</td>
</tr>
<tr style="background-color: #eee;">
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"></td>
<td valign="top">uint32</td>
<td valign="top">Chunk Size</td>
<td valign="top">Length of the metadata string in bytes.</td>
</tr>
<tr>
<td style="background-color: #ddd;" valign="top"><b>–</b></td>
<td style="background-color: #ddd;" valign="top"><b>+0</b></td>
<td valign="top">String</td>
<td valign="top">Metadata</td>
<td valign="top">Metadata string in UTF-8. No BOM.</td>
</tr>
</tbody>
</table>
<p>This is the list of standard metadata keys. Multiple values are pipe-separated.</p>
<table class="aligncenter" style="width: 96%;" border="2">
<thead>
<tr style="background-color: #bbb;">
<th style="width: 32%;">Key</th>
<th style="width: 32%;">Purpose</th>
<th style="width: 32%;">Example Value</th>
</tr>
</thead>
<tbody>
<tr>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">title</span></td>
<td valign="top">Name/Title of the product.</td>
<td valign="top">Prince of Persia</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">subtitle</span></td>
<td valign="top">Subtitle of the product.</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">publisher</span></td>
<td valign="top">Publisher of the software.</td>
<td valign="top">Brøderbund Software, Inc.</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">developer</span></td>
<td valign="top">Developer of the software. Pipe-delimited list if needed.</td>
<td valign="top">Jordan Mechner</td>
</tr>
<tr>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">copyright</span></td>
<td valign="top">Copyright date. Free form text allowed.</td>
<td valign="top">1989<br />
1987 Muse Software</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">version</span></td>
<td valign="top">Version number of the software. Free form text allowed.</td>
<td valign="top">1.0<br />
19870115P</td>
</tr>
<tr>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">language</span></td>
<td valign="top">Language (see table A)</td>
<td valign="top">English</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">requires_ram</span></td>
<td valign="top">RAM requirements (see table B)</td>
<td valign="top">64K</td>
</tr>
<tr>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">requires_machine</span></td>
<td valign="top">Which computers does this run on? Pipe-delimited list. (see table C)</td>
<td valign="top">2+|2e|2c|2gs</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">notes</span></td>
<td valign="top">Additional notes.</td>
<td valign="top"></td>
</tr>
<tr>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">side</span></td>
<td valign="top">Physical disk side formatted as:<br />
“Disk #, Side [A|B]”</td>
<td valign="top">Disk 1, Side A</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">side_name</span></td>
<td valign="top">Name of the disk side. If the disk side is named on the label like Player, Town, Dungeon, etc then it goes here.</td>
<td valign="top">Front</td>
</tr>
<tr>
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">contributor</span></td>
<td valign="top">Name of the person who imaged the disk.</td>
<td valign="top">Mr. Pirate</td>
</tr>
<tr style="background-color: #eee;">
<td valign="top"><span style="color: #000000; font-family: Courier New; font-size: medium;">image_date</span></td>
<td valign="top">RFC3339 date of the imaging.</td>
<td valign="top">2018-01-07T05:00:02.511Z</td>
</tr>
</tbody>
</table>
<p>If a standard key has no value, then the value will be an empty string. Key names are case-sensitive. Values cannot contain pipe, linefeed or tab characters. It would also be a good idea to keep all values as ASCII-friendly as possible to ensure compatibility with the widest range of devices that will consume these files. No duplicate keys are allowed and key order does not matter. Standard keys that have values laid out in the tables below cannot have values other that those shown below. Implementors are free to add additional keys to the metadata as long as they follow the same rules laid out here.</p>
<h5 style="text-align: center;">TABLE A- LANGUAGES</h5>
<table class="aligncenter" style="width: 80%;" border="2">
<tbody>
<tr>
<td style="width: 20%;">English</td>
<td style="width: 20%;">Spanish</td>
<td style="width: 20%;">French</td>