forked from AreaScout/vice
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathvice.texi
More file actions
20860 lines (17770 loc) · 615 KB
/
vice.texi
File metadata and controls
20860 lines (17770 loc) · 615 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
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename vice.info
@settitle VICE Manual
@c %**end of header
@ifinfo
@format
START-INFO-DIR-ENTRY
* VICE: (vice). VICE, the Versatile Commodore Emulator.
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@c global options
@setchapternewpage on
@firstparagraphindent none
@paragraphindent 0
@exampleindent 0
@c @iftex
@c @set CHAPTER chapter
@c @end iftex
@c @ifinfo
@c @set CHAPTER node
@c @end ifinfo
@c Theoretically, this should not be needed. But my makeinfo does not
@c understand it.
@ifinfo
@macro uref{PARAM}
\PARAM\
@end macro
@end ifinfo
@ifinfo
VICE Manual
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
@end ifinfo
@c -----------------------------------------------------------------------------
@titlepage
@title VICE, the Versatile Commodore Emulator
@c page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2014 Dag Lem
Copyright @copyright{} 1999-2014 Andreas Matthies
Copyright @copyright{} 1999-2014 Martin Pottendorfer
Copyright @copyright{} 2005-2014 Marco van den Heuvel
Copyright @copyright{} 2006-2014 Christian Vogelgsang
Copyright @copyright{} 2007-2014 Fabrizio Gennari
Copyright @copyright{} 2007-2014 Daniel Kahlin
Copyright @copyright{} 2008-2014 Antti S. Lankila
Copyright @copyright{} 2009-2014 Groepaz
Copyright @copyright{} 2009-2014 Ingo Korb
Copyright @copyright{} 2009-2014 Errol Smith
Copyright @copyright{} 2010-2014 Olaf Seibert
Copyright @copyright{} 2011-2014 Marcus Sutton
Copyright @copyright{} 2011-2014 Ulrich Schulz
Copyright @copyright{} 2011-2014 Stefan Haubenthal
Copyright @copyright{} 2011-2014 Thomas Giesel
Copyright @copyright{} 2011-2014 Kajtar Zsolt
Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux
Copyright @copyright{} 2000-2011 Spiro Trikaliotis
Copyright @copyright{} 2007-2011 Hannu Nuotio
Copyright @copyright{} 1998-2010 Andreas Boose
Copyright @copyright{} 1998-2010 Tibor Biczo
Copyright @copyright{} 2007-2010 M. Kiesel
Copyright @copyright{} 1999-2007 Andreas Dehmel
Copyright @copyright{} 2003-2005 David Hansel
Copyright @copyright{} 2000-2004 Markus Brenner
Copyright @copyright{} 1999-2004 Thomas Bretz
Copyright @copyright{} 1997-2001 Daniel Sladic
Copyright @copyright{} 1996-2001 André Fachat
Copyright @copyright{} 1996-1999 Ettore Perazzoli
Copyright @copyright{} 1993-1994, 1997-1999 Teemu Rantanen
Copyright @copyright{} 1993-1996 Jouko Valta
Copyright @copyright{} 1993-1994 Jarkko Sonninen
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
@end titlepage
@c -----------------------------------------------------------------------------
@c @ifinfo
@node Top, License, (dir), (dir)
@c @top Version
@c Last updated @value{lastupdate}.
@c @end ifinfo
@ifinfo
This is the documentation for version 2.4 of VICE, the Versatile
Commodore Emulator.
@end ifinfo
@menu
* License:: The GNU General Public License gives you
permission to redistribute this program
on certain terms; and also explains that
there is no warranty.
* Preface:: Fundamental concepts.
* Usage:: Invoking the emulators.
* System files:: Files needed to emulate.
* Basics:: Simple things you can do.
* Settings and resources:: Emulator parameters you can change.
* Machine-specific features:: Peculiar characteristics of the emulators.
* Snapshots:: Save the emulator state in one file
* Monitor:: The VICE built-in monitor.
* c1541:: The disk-image maintenance utility.
* File formats:: Technical description of file formats.
* Acknowledgments:: People involved in VICE.
* Copyright:: Legal stuff.
* Contacts:: Official home page, email addresses@dots{}
* Concept Index::
* Resource Index::
@end menu
@node License, Preface, Top, Top
@chapter GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991
@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. 675
Mass Ave, Boston, MA 02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
@unnumberedsec Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and
modification follow.
@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo
@enumerate 0
@item
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License. The ``Program'', below,
refers to any such program or work, and a ``work based on the Program''
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language. (Hereinafter, translation is included without limitation in
the term ``modification''.) Each licensee is addressed as ``you''.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.
@item
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.
You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.
@item
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.
@item
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.
@item
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
@end enumerate
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.
In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
@item
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:
@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,
@item
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
@item
Accompany it with the information you received as to the offer
to distribute corresponding source code. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
@end enumerate
The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.
If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.
@item
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.
@item
You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Program or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.
@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
@item
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
@iftex
@vskip -@baselineskip
@vskip -@baselineskip
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo
@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
@end enumerate
@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo
@page
@unnumberedsec How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.
@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy} @var{name of author}
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.
@end smallexample
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'. This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
@end smallexample
The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License. Of course, the
commands you use may be called something other than @samp{show w} and
@samp{show c}; they could even be mouse-clicks or menu items---whatever
suits your program.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary. Here is a sample; alter the names:
@example
@group
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.
@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end group
@end example
This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.
@node Preface, Usage, License, Top
@chapter About VICE
VICE is the one and only @dfn{Versatile Commodore Emulator}. It provides
emulation of the Commodore C64, C64DTV, C128, VIC20, PET, PLUS4, SCPU64 and CBM-II computers
within a single package. The emulators run as separate programs, but have
the same user interface, share the same settings and support the same
file formats.
@strong{Important notice:} If you have no idea what a Commodore
8-bit computer is, or have questions about how these machines are used,
how the file formats work or anything else that is not strictly
related to VICE, you should read the appropriate FAQs @emph{first}, as
that kind of information is not available here. @xref{Contacts}. for
information about how to retrieve the FAQs.
All the emulators provide an accurate 6502/6510 emulator, with emulation
of all the opcodes (both documented and undocumented ones) and accurate
timing. Unlike other emulators, VICE aims to be cycle
accurate; it tries to emulate chip timings as precisely as possible and
does so @emph{efficiently}.
Please do @emph{not} expect the C64DTV, C128, PET, PLUS4, SCPU64 and CBM-II emulators to
be as good as the C64 or VIC20 one, as they are still under construction.
@emph{Notice:} This documentation is written for the Unix release of VICE.
@menu
* C64 emulator features::
* C64DTV emulator features::
* C128 emulator features::
* VIC20 emulator features::
* PET emulator features::
* CBM-II emulator features::
* SCPU64 emulator features::
* Keyboard emulation::
* Joystick emulation::
* Disk drive emulation::
* Supported file formats::
* Common problems::
@end menu
@node C64 emulator features, C64DTV emulator features, Preface, Preface
@section C64 emulator features
As of version 2.3, two C64 emulators are provided: @samp{x64} (fast)
and @samp{x64sc} (accurate).
The fast C64 emulator, called @samp{x64}, features a fairly complete
emulation of the VIC-II video chip: sprites, all registers and all video
modes are fully emulated. The emulation has been fully cycle-accurate
since version 0.13.0.
The accurate C64 emulator, called @samp{x64sc}, features a cycle-based
and pixel-accurate VIC-II emulation. This requires a much faster machine
than the old @samp{x64}.
A rather complete emulation of the SID sound chip is also provided. All
the basic features are implemented as well as most of the complex ones
including synchronisation, ring modulation and filters. There are three
emulators of the SID chip available: first is the ``standard'' VICE
emulator, available since VICE 0.12; the second is Dag Lem's reSID
engine. The reSID engine is a lot more accurate than the standard engine,
but it is also a lot slower, and only suitable for faster machines.
Naturally, also both CIAs (or VIAs, in some cases) are fully emulated
and cycle accurate.
@node C64DTV emulator features, C128 emulator features, C64 emulator features, Preface
@section C64DTV emulator features
The C64DTV emulator, called @samp{x64dtv}, features emulation of C64DTV
revisions 2 and 3. The emulator is under construction, but most of the
DTV specific features are already supported (with varying accuracy).
Video cache is disabled by default as it currently doesn't work with
some of C64DTV's new video modes. The new video modes have a simple
"fake" video cache implementation that may give incorrect results
and decreased performance.
@node C128 emulator features, VIC20 emulator features, C64DTV emulator features, Preface
@section C128 emulator features
The C128 emulator, called @samp{x128}, features a complete emulation of
the internal MMU (@dfn{Memory Management Unit}), 80 column VDC screen, fast
IEC bus emulation, 2 MHz mode, Z80 emulation plus all the features of the
C64 emulation.
@node VIC20 emulator features, PET emulator features, C128 emulator features, Preface
@section VIC20 emulator features
The VIC20 emulates all the internal hardware, including the VIA chips.
The VIC-I video chip is fully emulated except NTSC interlace mode, so most
graphical effects will work correctly.
Sound support is implemented, but is still at an experimental stage. If
you think it could be improved and know how to do so, feel
free to contact us (@pxref{Contacts}).
The VIC20 emulator now allows the use of the VIC1112 IEEE488
interface. You have to enable the hardware (by menu, resource, or
commandline option) and then load the IEEE488 ROM (see for
example @code{http://www.funet.fi/pub/cbm/schematics/cartridges/vic20/ieee-488/325329-04.bin}, but you have to double the size to 4k for now).
The IEEE-488 code is then started by @code{SYS45065}.
@node PET emulator features, CBM-II emulator features, VIC20 emulator features, Preface
@section PET emulator features
The PET emulator emulates the 2001, 3032, 4032, 8032, 8096, 8296 and
SuperPET (MicroMainFrame 9000) models, covering practically the whole series.
The hardware is pretty much the same in each and that is why one single
program is enough to emulate all of them. For more detailed information
about PET hardware please refer to the @file{PETdoc} file.
@c FIXME: add link to doc/html/plain/PETdoc.txt
Both the 40 column and 80 column CRTC video chips are emulated (from the
4032 onward), but a few of the features are not implemented yet (numbers
of rasterlines per char and lines per screen). Fortunately, they are
not very important for average applications.
Sound is available for the PET as well, but like the VIC20's it is still
under construction.
The PET 8096 is basically a PET 8032 with a 64k extension board which
allows remapping the upper 32k with RAM. You have to write to a special
register at @code{$fff0} to remap the memory. The PET 8296 is a
8096 but with a completely redesigned motherboard with 128k RAM in
total. Of the additional 32k RAM you can use only some in blocks of 4k,
but you have to set jumpers on the motherboard for it. VICE uses the
command line options @samp{-petram9} and @samp{-petramA}
instead. Also, the video controller can handle a larger address range.
The PET 8x96 model emulations run the Commodore LOS-96 operating system
- basically an improved BASIC 4 version with up to 32k for BASIC
text and 32k for variables. See @file{PETdoc} for more information.
@c FIXME: add link to doc/html/plain/PETdoc.txt
The SuperPET also is a PET 8032 with an expansion board. It can map 4k
at a time out of 64k into the @code{$9***} area. Also it has an ACIA
6551 for RS232 communication. The 6809 CPU that is built into the
SuperPET is now emulated, since release 2.4, including the 6702 dongle
chip.
The Super-OS/9 MMU expansion, developed by TPUG (Toronto PET Users
Group) is also emulated.
The PET computers came with three major ROM revisions, so-called BASIC
1, 2 and 4, all of which are provided. The PET 2001 uses the version 1,
the PET 3032 uses version 2, and the others use version 4. The 2001 ROM
is horribly broken with respect to IEEE488 (they shipped it before they
tested it with the floppy drive, so only tape worked. Therefore the
emulator patches the ROM to fix the IEEE488 routines.
As well as other low-level fixes the 2001 patch obtains the load address
for a program file from the first two bytes of the file. This allows
the loading of both PET2001-saved files (that have $0400 as their load
address) and other PET files (that have $0401). The PET2001 saves from
$0400 and not from $0401 as other PETs do.
Moreover, the secondary addresses used are now @code{0} and @code{1} for
load and save, respectively, and not arbitrary unused secondary
addresses.
To select which model to run, specify it on the
command line with the @code{-model MODEL} option, where
@code{MODEL} can be one of a list of PET model numbers, all
described in @pxref{PET model}
@c FIXME: add link to section
@node CBM-II emulator features, SCPU64 emulator features, PET emulator features, Preface
@section CBM-II emulator features
The CBM-II emulator emulates several types of CBM-II models. Those
models are known under different names in the USA and Europe. In the
States they have been sold as @code{B128} and @code{B256}, in Europe as
@code{CBM 610}, @code{CBM 620} (low-profile case) or @code{CBM 710} and
@code{CBM 720} (high-profile case with monitor). In addition to that
now an experimental C510 emulation is included. The C510 (also known as
P500) is the little brother of the C600/700 machines. It runs at roughly
1 MHz and, surprise, it has a VIC-II instead of the CRTC. Otherwise
the different line of computers are very similar.
These computers are prepared to take a coprocessor board with an 8088 or
Z80 CPU. Indeed there are models @code{CBM 630} and @code{CBM 730} that
supposedly had those processors. However these models are not emulated.
The basic difference is the amount of RAM these machines have been
supplied with. The @code{B128} and the @code{CBM *10} models had 128k
RAM, the others 256k. This implies some banking scheme, as the 6502 can
only address 64k. And indeed those machines use a 6509, that can
address 1 MByte of RAM. It has 2 registers at addresses 0 and 1. The
indirect bank register at address 1 determines the bank (0-15) where the
opcodes @code{LDA (zp),Y} and @code{STA (zp),Y} take the data from. The
exec bank register at address 0 determines the bank where all other read
and write addresses take place.
The business line machines (C6xx/7xx) have the RAM in banks 1-2, resp.
1-4. All available banks are used for BASIC, where program code is separated
from all variables, resp. from normal variables, strings and arrays that
are distributed over other banks. The C510 instead has RAM in banks 0 and 1,
and uses bank 1 for program and all variables. Bank 0, though, can be
accessed by the VIC-II to display graphics.
Many models have been expanded to more than the built-in memory. In fact
some machines have been expanded to the full 1M. Bank 15 is used as
system bank, with only little RAM, and lots of expansion cartridge ROM
area, the I/O and the kernal/basic ROMs. Some models have been modified
to map RAM into the expansion ROM area. Those modifications can be
emulated as well.
The different settings are described in @pxref{CBM-II model}.
@node SCPU64 emulator features, Keyboard emulation, CBM-II emulator features, Preface
@section SCPU64 emulator features
The XSCPU64 emulator is a simulation of a C64 equipped with a SuperCPU64 V2B. Features:
@itemize @bullet
@item 20 MHz asynchronous single cycle 65816 CPU core with proper dummy and invalid cycle handling.
@item 128 KiB static RAM, 0-16 MiB SIMM RAM, 64-512 KiB EPROM emulated and their respective timing details.
@item All RAM optimization configurations supported with write buffer.
@item I/O area access delays, write through to SRAM implemented.
@item Memory mappings including cartridge and boot memory map and kernal shadow.
@item Hardware registers and switches implemented.
@item Replacement SCPU64 ROM compatible with the original to avoid distribution problems
@item It's using the single cycle VICII core for accurate simulation
@end itemize
Still to do:
@itemize @bullet
@item Measure and verify VICII interrupt phase shift
@item Measure and verify BA phase shift
@item SIMM RAM extra 7.5 cycle refresh delay every 10us missing.
@item CPU NMI support for ``reset'' button
@end itemize
The emulation is quite accurate but not perfect. If you code something timing
intensive using this simulation please always check it on real hardware to avoid
bad surprises.
The hardware itself is asynchronous in nature, therefore caution must be taken
to not do long timing loops without synchronization in 20 MHz mode. Also don't
squeeze out the last remaining cycles without leaving a safety buffer.
Synchronization points can be created by doing I/O reads or writes and leaving
a few hundred cycles left each frame will not hurt.
Otherwise it can happen that the code is running on this version of VICE or my
SCPU64 V2+C128D perfectly but nowhere else due to manufacturing variations and
frequency drifts.
@node Keyboard emulation, Joystick emulation, SCPU64 emulator features, Preface
@section The keyboard emulation
There are two ways of emulating the keyboard in VICE.
The default way (@dfn{symbolic mapping}) is to map every key
combination to the corresponding key combination on the real machine:
for example, if you press @key{*}, which is bound to @kbd{Shift-8} on a
U.S. keyboard, in the C64 emulator, the emulated machine will have just
the @emph{unshifted} @key{*} key pressed (as @key{*} is unshifted on the
C64 keyboard). Likewise, pressing @key{'} on the same U.S. keyboard
without any shift key will cause the combination @kbd{Shift-7} to be
pressed in the emulated C64. This way, it becomes quite obvious what
keys should be typed to obtain all the symbols.
There is, however, one problem with symbolic mapping: some keys really
need to be mapped specially regardless. The most important examples
being, in the VIC20, C64 and C128 emulators, that @key{CTRL} is mapped
to @key{Tab} and that the @key{Commodore} key is mapped to the left
@key{Control}). The @key{RUN/STOP} key is mapped to the @key{ESC} key
on the PC keyboard. The PET emulator, lacking the @key{Commodore} key
but having an @key{ESC} key, uses the left @key{Control} key as
@key{RUN/STOP} and the @key{ESC} key as @key{ESC} of course.
@c FIXME: add a detailed list of all keys
The second way (@dfn{positional mapping}) is to map every key on the
``real'' keyboard to the key which has the same position on the keyboard
of the emulated machine. This way, no @key{Shift} key is forced by the
program (with the exception of the function keys @key{F2}, @key{F4},
@key{F6} and @key{F8}, which require @key{Shift} on the Commodore
keyboards), and the keyboard is more comfortable to use in those
programs (such as some games) that require the keys to be in the correct
positions.
@strong{Warning:} unlike the real C64, VICE ``presses'' the @key{Shift}
key @emph{together} with the key to shift when the @key{Shift} must be
forced. In most cases this should work fine, but some keyboard routines
are quite picky and tend not to recognize the shift key because of this.
For instance, @kbd{F6} (which on the real C64 is obtained with
@kbd{Shift + F5}) could be recognized as @kbd{F5}. In that case, use
the shift key manually (i.e., type @kbd{Shift + F5} in the example).
Yes, we know this is a bug.
The @kbd{RESTORE} key is mapped to @kbd{Page Up} (or @kbd{Prev}) by
default.
@node Joystick emulation, Disk drive emulation, Keyboard emulation, Preface
@section The joystick emulation
Joysticks can be emulated both via the keyboard and via a real joystick
connected to the host machine (the latter only works on GNU/Linux
systems).
There are two keyboard layouts for joystick use, known as @dfn{numpad}
and @dfn{custom}.
The @dfn{numpad} layout uses the numeric keypad keys, i.e., the numbers
@key{1}@dots{}@key{9} which emulate all the directions including the
diagonal ones; @key{0} emulates the fire button.
The @dfn{custom} layout uses the keys @key{w}, @key{e}, @key{r},
@key{s}, @key{d}, @key{f}, @key{x}, @key{c}, @key{v} for the directions
and @key{space} for the fire button instead.
@node Disk drive emulation, Supported file formats, Joystick emulation, Preface
@section The disk drive emulation
All the emulators support up to 4 external disk drives as
devices 8, 9, 10 and 11. Each of these devices can emulate virtual
Commodore 1541, 1541-II, 1571, 1581, 2031, 2040, 3040, 4040, 1001, 8050 and
8250 drives in one of four ways:
@itemize @bullet
@item
using disk images, i.e., files that contain a dump of all the blocks
contained in a real floppy disk (if you want more information about
what a disk image is, consult the
@code{comp.emulators.cbm} FAQ);
@item
accessing file system directories, thus giving you the use of files
without having to copy them to disk images; this also allows you to
read and write files in the @code{P00} format (again, consult the
@code{comp.emulators.cbm} FAQ for more info).
@item
accessing a real device connected to the host machine. As of VICE 1.11
it is possible to connect real drives like Commodore 1541 to the
printer port of the host using the XA1541 or XM1541 cable. Currently
this only works on Linux or Windows using the OpenCBM library. You can
get it from @uref{http://www.lb.shuttle.de/puffin/cbm4linux} (cbm4linux,
Linux version) or from @uref{http://cbm4win.sf.net/} (cbm4win, Windows
version).
@item
directly using the disk drive of the host. The 3.5" disk drive of the
host can be used to read or write Commodore 1581 formatted disks.
Currently this raw drive access feature is only available for Linux
hosts.
@end itemize
When using disk images there are two available types of drive
emulation. One of them the @dfn{virtual drive} emulation. It does
@emph{not} really emulate the serial line, but patches the kernal ROM
(with the so-called @dfn{kernal traps}) so that serial line operations
can be emulated via C language routines. This emulation is very fast,
but only allows use of standard DOS functions (and not even all of
them). For real device or raw drive access it is required to enable
this type of emulation.
The IEEE488 drives (2031, 2040, 3040, 4040, 1001, 8050 and 8250) do
not use kernal traps. Instead the IEEE488 interface lines are
monitored and the data is passed to the drive emulation. To use them
on the C64, you need to enable the IEEE488 interface emulation. Only
if the IEEE488 emulation is enabled, those drives can be selected.
The other alternative is a @dfn{true drive} emulation. The
Commodore disk drives are provided with their own CPU (a 6502 as the
VIC20 and the PETs) and their own RAM and ROM. So, in order to more
closely emulate its features, a complete emulation of this hardware
must be provided and that is what the @dfn{hardware level} emulation
does. When the @dfn{hardware level} emulation is used, the kernal
routines are remain unpatched and the serial line is fully emulated.
The problem with this emulation is that it needs a lot of processing
power, mainly because the emulator has to emulate two CPUs instead of
one.
The PETs do not use a serial IEC bus to communicate with the floppy
drive but instead use the parallel IEEE488 bus. This does
@emph{byte by byte} transfers, as opposed to the @emph{bit by bit}
transfers of the C64 and VIC20, so making it feasible to emulate the
parallel line completely while emulating the drive at DOS level only.
The IEEE488 line interpreter maps the drives 8-11 (as described
above) to the IEEE488 disk units, and no kernal traps are needed.
The same emulation of the Commodore IEEE488 bus interface is
available for the C64 and the VIC20. With IEEE488 drives you can have
true 2031 emulation at unit #8, and still have filesystem access at
units #10 or #11, because monitoring the IEEE488 lines does not
interfere with the true drive emulation.
The IEEE488 disk drives 2040, 3040, 4040, 8050 and 8250 are Dual Drive
Floppy Disks. This means that these drives handle two disks. To
accomplish the emulation, only two disks can be emulated, namely units
#8 and #10. The attached image, track display and LED display of unit
#9 and #11 are used for the second drive of the dual disk drives. On
unix the unit number display (8 or 9, 10 or 11) in the emulation
window changes to the drive number display (0 or 1).
The Commodore 2040, 3040, 4040, 1001, 8050 and 8250 disk drives are
so-called "old-style" disk drives. Their architecture includes not
one, but two processors of the 6502 type, namely a 6502 for the file
handling and communication with the PET (IP), and a 6504 (which is a
6502 with reduced address space) for the drive handling (FDC). Both
processors communicate over a shared memory area. The IP writes
commands to read/write blocks to this area and the FDC executes them.
To make the emulation feasible, the FDC processor is not emulated
cycle-exactly as a 6504, but simply by checking the commands and
executing them on the host. This provides a fast FDC emulation, but
disallows the sending the FDC processor commands to execute code.
Applications where this is necessary are believed to be rather
seldom. Only the format command uses this feature, but this is
checked for.
The dual disk drive 2040 emulates one of the very first CBM disk
drives. This drive has DOS version 1. DOS1 uses an own disk type,
that is closely related to the 1541 disk image. Only on tracks 18-24
DOS1 disks have a sector more than 1541 disks. DOS1 disk images have
the extension .d67.
The dual disk drives 3040 and 4040 use the same logical disk format
as the VC1541 and the 2031. In fact, the 4040 was the first disk with
DOS version 2. The 3040 emulated here originally was the same as
2040, only for the european 30xx PET series. As many of the original
DOS1 disk drives were upgraded (a simple ROM upgrade!) to DOS2, I use
the 3040 number for a DOS 2.0 disk drive, and 4040 for a revised DOS
2 disk drive. It is, however, not yet clear whether the disks here
are write compatible to the 1541, as rumors exist that the write gap
between sectors is different. But read compatible they are. As VICE
emulates the FDC processor in C and not as 6504 emulation, this does
not matter in VICE.
The drives 1001, 8050 and 8250 do actually have the very same DOS
ROM. Only the code in the FDC is different, which is taken care of by
VICE. So for all three of those disk drives, only @code{dos1001} is
needed. The DOS version used is 2.7.