1\input texinfo @c -*- texinfo -*- 2@c %**start of header 3@setfilename vice.info 4@settitle VICE Manual 5@documentencoding ISO-8859-15 6@c %**end of header 7 8@ifinfo 9@format 10START-INFO-DIR-ENTRY 11* VICE: (vice). VICE, the Versatile Commodore Emulator. 12END-INFO-DIR-ENTRY 13@end format 14@end ifinfo 15 16@c global options 17@setchapternewpage on 18@ifset txicommandconditionals 19@ifcommanddefined firstparagraphindent 20@firstparagraphindent none 21@end ifcommanddefined 22@end ifset 23@paragraphindent 0 24@exampleindent 0 25 26@c define platformall as the default 27@ifclear platformall 28@set platformall 29@end ifclear 30 31@c @iftex 32@c @set CHAPTER chapter 33@c @end iftex 34 35@c @ifinfo 36@c @set CHAPTER node 37@c @end ifinfo 38 39@c define platformunix if any of the following are set: 40@c platformgtk3 41@ifset platformgtk3 42@set platformunix 43@end ifset 44 45@c define platformsdl if any of the following are set: 46 47@c undef platformall if any of the following are set: 48@c platformos2 platformsdl platformgtk3 platformunix platformosx 49@ifset platformos2 50@clear platformall 51@end ifset 52@ifset platformsdl 53@clear platformall 54@end ifset 55@ifset platformgtk3 56@clear platformall 57@end ifset 58@ifset platformunix 59@clear platformall 60@end ifset 61@ifset platformosx 62@clear platformall 63@end ifset 64 65@c set all platform defines if platformall is still defined 66@ifset platformall 67@set platformgtk3 68@set platformos2 69@set platformosx 70@set platformsdl 71@set platformunix 72@end ifset 73 74@ifset txicommandconditionals 75@ifcommanddefined uref 76@set urefdefined 77@end ifcommanddefined 78@end ifset 79 80@c Theoretically, this should not be needed. But my makeinfo does not 81@c understand it. 82@ifinfo 83@ifclear urefdefined 84@macro uref{PARAM} 85\PARAM\ 86@end macro 87@end ifclear 88@end ifinfo 89 90@c ----------------------------------------------------------------------------- 91@c this disables the ugly black boxes at the end of each line on overfull hboxes 92@finalout 93 94@c ----------------------------------------------------------------------------- 95@ifinfo 96VICE Manual 97 98Permission is granted to make and distribute verbatim copies of 99this manual provided the copyright notice and this permission notice 100are preserved on all copies. 101 102@ignore 103Permission is granted to process this file through TeX and print the 104results, provided the printed document carries copying permission 105notice identical to this one except for the removal of this paragraph 106(this paragraph not being relevant to the printed manual). 107@end ignore 108 109Permission is granted to copy and distribute modified versions of this 110manual under the conditions for verbatim copying, provided that the entire 111resulting derived work is distributed under the terms of a permission 112notice identical to this one. 113 114@end ifinfo 115 116@c ----------------------------------------------------------------------------- 117 118@titlepage 119 120@title VICE, the Versatile Commodore Emulator 121 122@c page 123@vskip 0pt plus 1filll 124@c section used in file generation, keep to the format used. 125@c ---vice-core-team--- 126Copyright @copyright{} 1999-2020 Martin Pottendorfer 127Copyright @copyright{} 2005-2020 Marco van den Heuvel 128Copyright @copyright{} 2007-2020 Fabrizio Gennari 129Copyright @copyright{} 2009-2020 Groepaz 130Copyright @copyright{} 2009-2020 Errol Smith 131Copyright @copyright{} 2009-2020 Ingo Korb 132Copyright @copyright{} 2010-2020 Olaf Seibert 133Copyright @copyright{} 2011-2020 Marcus Sutton 134Copyright @copyright{} 2011-2020 Kajtar Zsolt 135Copyright @copyright{} 2016-2020 AreaScout 136Copyright @copyright{} 2016-2020 Bas Wassink 137Copyright @copyright{} 2017-2020 Michael C. Martin 138Copyright @copyright{} 2018-2020 Christopher Phillips 139Copyright @copyright{} 2019-2020 David Hogan 140Copyright @copyright{} 2020 Empathic Qubit 141Copyright @copyright{} 2020 Roberto Muscedere 142@c ---vice-core-team-end--- 143 144@c ---ex-team--- 145Copyright @copyright{} 2011-2016 Stefan Haubenthal 146Copyright @copyright{} 2015-2016 BSzili 147Copyright @copyright{} 1999-2016 Andreas Matthies 148Copyright @copyright{} 2007-2015 Daniel Kahlin 149Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux 150Copyright @copyright{} 2011-2014 Ulrich Schulz 151Copyright @copyright{} 2011-2014 Thomas Giesel 152Copyright @copyright{} 2008-2014 Antti S. Lankila 153Copyright @copyright{} 2006-2014 Christian Vogelgsang 154Copyright @copyright{} 1998-2014 Dag Lem 155Copyright @copyright{} 2000-2011 Spiro Trikaliotis 156Copyright @copyright{} 2007-2011 Hannu Nuotio 157Copyright @copyright{} 1998-2010 Andreas Boose 158Copyright @copyright{} 1998-2010 Tibor Biczo 159Copyright @copyright{} 2007-2010 M. Kiesel 160Copyright @copyright{} 1999-2007 Andreas Dehmel 161Copyright @copyright{} 2003-2005 David Hansel 162Copyright @copyright{} 2000-2004 Markus Brenner 163Copyright @copyright{} 1999-2004 Thomas Bretz 164Copyright @copyright{} 1997-2001 Daniel Sladic 165Copyright @copyright{} 1996-2001 Andr� Fachat 166Copyright @copyright{} 1996-1999 Ettore Perazzoli 167Copyright @copyright{} 1993-1994, 1997-1999 Teemu Rantanen 168Copyright @copyright{} 1993-1996 Jouko Valta 169Copyright @copyright{} 1993-1994 Jarkko Sonninen 170@c ---ex-team-end--- 171@c end of file generation section. 172 173Permission is granted to make and distribute verbatim copies of 174this manual provided the copyright notice and this permission notice 175are preserved on all copies. 176 177Permission is granted to copy and distribute modified versions of this 178manual under the conditions for verbatim copying, provided that the entire 179resulting derived work is distributed under the terms of a permission 180notice identical to this one. 181 182@end titlepage 183 184@c ----------------------------------------------------------------------------- 185 186@c @ifinfo 187@node Top, License, (dir), (dir) 188@top 189 190@c Last updated @value{lastupdate}. 191@c @end ifinfo 192 193@ifinfo 194 195This is the documentation for version 3.3 of VICE, the Versatile 196Commodore Emulator. 197 198@end ifinfo 199 200@menu 201* License:: The GNU General Public License gives you 202 permission to redistribute this program 203 on certain terms; and also explains that 204 there is no warranty. 205 206* Preface:: Fundamental concepts. 207 208* Usage:: Invoking the emulators. 209* System files:: Files needed to emulate. 210 211* Basics:: Simple things you can do. 212 213* Settings and resources:: Emulator parameters you can change. 214 215* Machine-specific features:: Peculiar characteristics of the emulators. 216 217* Platform-specific features:: Host platform specific features. 218 219* Snapshots:: Save the emulator state in one file. 220* Media images:: Saving audio and/or video. 221* Event history:: Recording and replaying a session. 222* Monitor:: The VICE built-in monitor. 223* Binary monitor:: For remote control. 224* c1541:: The disk-image maintenance utility. 225* Cartconv:: Cartridge conversion utility. 226* Petcat:: Text conversion utility. 227 228* File formats:: Technical description of file formats. 229 230* Acknowledgments:: People involved in VICE. 231* Copyright:: Legal stuff. 232* Contacts:: Official home page, email addresses@dots{} 233 234* Concept Index:: 235* Resource Index:: 236* Command-line Index:: 237@end menu 238 239@node License, Preface, Top, Top 240@chapter GNU GENERAL PUBLIC LICENSE 241 242@center Version 2, June 1991 243 244@display 245Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. 246675 Mass Ave, Boston, MA 02111-1307, USA 247 248Everyone is permitted to copy and distribute verbatim copies 249of this license document, but changing it is not allowed. 250@end display 251 252@unnumberedsec Preamble 253 254 The licenses for most software are designed to take away your 255freedom to share and change it. By contrast, the GNU General Public 256License is intended to guarantee your freedom to share and change free 257software---to make sure the software is free for all its users. This 258General Public License applies to most of the Free Software 259Foundation's software and to any other program whose authors commit to 260using it. (Some other Free Software Foundation software is covered by 261the GNU Library General Public License instead.) You can apply it to 262your programs, too. 263 264 When we speak of free software, we are referring to freedom, not 265price. Our General Public Licenses are designed to make sure that you 266have the freedom to distribute copies of free software (and charge for 267this service if you wish), that you receive source code or can get it 268if you want it, that you can change the software or use pieces of it 269in new free programs; and that you know you can do these things. 270 271 To protect your rights, we need to make restrictions that forbid 272anyone to deny you these rights or to ask you to surrender the rights. 273These restrictions translate to certain responsibilities for you if you 274distribute copies of the software, or if you modify it. 275 276 For example, if you distribute copies of such a program, whether 277gratis or for a fee, you must give the recipients all the rights that 278you have. You must make sure that they, too, receive or can get the 279source code. And you must show them these terms so they know their 280rights. 281 282 We protect your rights with two steps: (1) copyright the software, and 283(2) offer you this license which gives you legal permission to copy, 284distribute and/or modify the software. 285 286 Also, for each author's protection and ours, we want to make certain 287that everyone understands that there is no warranty for this free 288software. If the software is modified by someone else and passed on, we 289want its recipients to know that what they have is not the original, so 290that any problems introduced by others will not reflect on the original 291authors' reputations. 292 293 Finally, any free program is threatened constantly by software 294patents. We wish to avoid the danger that redistributors of a free 295program will individually obtain patent licenses, in effect making the 296program proprietary. To prevent this, we have made it clear that any 297patent must be licensed for everyone's free use or not licensed at all. 298 299 The precise terms and conditions for copying, distribution and 300modification follow. 301 302@iftex 303@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 304@end iftex 305@ifinfo 306@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 307@end ifinfo 308 309@enumerate 0 310@item 311This License applies to any program or other work which contains 312a notice placed by the copyright holder saying it may be distributed 313under the terms of this General Public License. The ``Program'', below, 314refers to any such program or work, and a ``work based on the Program'' 315means either the Program or any derivative work under copyright law: 316that is to say, a work containing the Program or a portion of it, 317either verbatim or with modifications and/or translated into another 318language. (Hereinafter, translation is included without limitation in 319the term ``modification''.) Each licensee is addressed as ``you''. 320 321Activities other than copying, distribution and modification are not 322covered by this License; they are outside its scope. The act of 323running the Program is not restricted, and the output from the Program 324is covered only if its contents constitute a work based on the 325Program (independent of having been made by running the Program). 326Whether that is true depends on what the Program does. 327 328@item 329You may copy and distribute verbatim copies of the Program's 330source code as you receive it, in any medium, provided that you 331conspicuously and appropriately publish on each copy an appropriate 332copyright notice and disclaimer of warranty; keep intact all the 333notices that refer to this License and to the absence of any warranty; 334and give any other recipients of the Program a copy of this License 335along with the Program. 336 337You may charge a fee for the physical act of transferring a copy, and 338you may at your option offer warranty protection in exchange for a fee. 339 340@item 341You may modify your copy or copies of the Program or any portion 342of it, thus forming a work based on the Program, and copy and 343distribute such modifications or work under the terms of Section 1 344above, provided that you also meet all of these conditions: 345 346@enumerate a 347@item 348You must cause the modified files to carry prominent notices 349stating that you changed the files and the date of any change. 350 351@item 352You must cause any work that you distribute or publish, that in 353whole or in part contains or is derived from the Program or any 354part thereof, to be licensed as a whole at no charge to all third 355parties under the terms of this License. 356 357@item 358If the modified program normally reads commands interactively 359when run, you must cause it, when started running for such 360interactive use in the most ordinary way, to print or display an 361announcement including an appropriate copyright notice and a 362notice that there is no warranty (or else, saying that you provide 363a warranty) and that users may redistribute the program under 364these conditions, and telling the user how to view a copy of this 365License. (Exception: if the Program itself is interactive but 366does not normally print such an announcement, your work based on 367the Program is not required to print an announcement.) 368@end enumerate 369 370These requirements apply to the modified work as a whole. If 371identifiable sections of that work are not derived from the Program, 372and can be reasonably considered independent and separate works in 373themselves, then this License, and its terms, do not apply to those 374sections when you distribute them as separate works. But when you 375distribute the same sections as part of a whole which is a work based 376on the Program, the distribution of the whole must be on the terms of 377this License, whose permissions for other licensees extend to the 378entire whole, and thus to each and every part regardless of who wrote it. 379 380Thus, it is not the intent of this section to claim rights or contest 381your rights to work written entirely by you; rather, the intent is to 382exercise the right to control the distribution of derivative or 383collective works based on the Program. 384 385In addition, mere aggregation of another work not based on the Program 386with the Program (or with a work based on the Program) on a volume of 387a storage or distribution medium does not bring the other work under 388the scope of this License. 389 390@item 391You may copy and distribute the Program (or a work based on it, 392under Section 2) in object code or executable form under the terms of 393Sections 1 and 2 above provided that you also do one of the following: 394 395@enumerate a 396@item 397Accompany it with the complete corresponding machine-readable 398source code, which must be distributed under the terms of Sections 3991 and 2 above on a medium customarily used for software interchange; or, 400 401@item 402Accompany it with a written offer, valid for at least three 403years, to give any third party, for a charge no more than your 404cost of physically performing source distribution, a complete 405machine-readable copy of the corresponding source code, to be 406distributed under the terms of Sections 1 and 2 above on a medium 407customarily used for software interchange; or, 408 409@item 410Accompany it with the information you received as to the offer 411to distribute corresponding source code. (This alternative is 412allowed only for noncommercial distribution and only if you 413received the program in object code or executable form with such 414an offer, in accord with Subsection b above.) 415@end enumerate 416 417The source code for a work means the preferred form of the work for 418making modifications to it. For an executable work, complete source 419code means all the source code for all modules it contains, plus any 420associated interface definition files, plus the scripts used to 421control compilation and installation of the executable. However, as a 422special exception, the source code distributed need not include 423anything that is normally distributed (in either source or binary 424form) with the major components (compiler, kernel, and so on) of the 425operating system on which the executable runs, unless that component 426itself accompanies the executable. 427 428If distribution of executable or object code is made by offering 429access to copy from a designated place, then offering equivalent 430access to copy the source code from the same place counts as 431distribution of the source code, even though third parties are not 432compelled to copy the source along with the object code. 433 434@item 435You may not copy, modify, sublicense, or distribute the Program 436except as expressly provided under this License. Any attempt 437otherwise to copy, modify, sublicense or distribute the Program is 438void, and will automatically terminate your rights under this License. 439However, parties who have received copies, or rights, from you under 440this License will not have their licenses terminated so long as such 441parties remain in full compliance. 442 443@item 444You are not required to accept this License, since you have not 445signed it. However, nothing else grants you permission to modify or 446distribute the Program or its derivative works. These actions are 447prohibited by law if you do not accept this License. Therefore, by 448modifying or distributing the Program (or any work based on the 449Program), you indicate your acceptance of this License to do so, and 450all its terms and conditions for copying, distributing or modifying 451the Program or works based on it. 452 453@item 454Each time you redistribute the Program (or any work based on the 455Program), the recipient automatically receives a license from the 456original licensor to copy, distribute or modify the Program subject to 457these terms and conditions. You may not impose any further 458restrictions on the recipients' exercise of the rights granted herein. 459You are not responsible for enforcing compliance by third parties to 460this License. 461 462@item 463If, as a consequence of a court judgment or allegation of patent 464infringement or for any other reason (not limited to patent issues), 465conditions are imposed on you (whether by court order, agreement or 466otherwise) that contradict the conditions of this License, they do not 467excuse you from the conditions of this License. If you cannot 468distribute so as to satisfy simultaneously your obligations under this 469License and any other pertinent obligations, then as a consequence you 470may not distribute the Program at all. For example, if a patent 471license would not permit royalty-free redistribution of the Program by 472all those who receive copies directly or indirectly through you, then 473the only way you could satisfy both it and this License would be to 474refrain entirely from distribution of the Program. 475 476If any portion of this section is held invalid or unenforceable under 477any particular circumstance, the balance of the section is intended to 478apply and the section as a whole is intended to apply in other 479circumstances. 480 481It is not the purpose of this section to induce you to infringe any 482patents or other property right claims or to contest validity of any 483such claims; this section has the sole purpose of protecting the 484integrity of the free software distribution system, which is 485implemented by public license practices. Many people have made 486generous contributions to the wide range of software distributed 487through that system in reliance on consistent application of that 488system; it is up to the author/donor to decide if he or she is willing 489to distribute software through any other system and a licensee cannot 490impose that choice. 491 492This section is intended to make thoroughly clear what is believed to 493be a consequence of the rest of this License. 494 495@item 496If the distribution and/or use of the Program is restricted in 497certain countries either by patents or by copyrighted interfaces, the 498original copyright holder who places the Program under this License 499may add an explicit geographical distribution limitation excluding 500those countries, so that distribution is permitted only in or among 501countries not thus excluded. In such case, this License incorporates 502the limitation as if written in the body of this License. 503 504@item 505The Free Software Foundation may publish revised and/or new versions 506of the General Public License from time to time. Such new versions will 507be similar in spirit to the present version, but may differ in detail to 508address new problems or concerns. 509 510Each version is given a distinguishing version number. If the Program 511specifies a version number of this License which applies to it and ``any 512later version'', you have the option of following the terms and conditions 513either of that version or of any later version published by the Free 514Software Foundation. If the Program does not specify a version number of 515this License, you may choose any version ever published by the Free Software 516Foundation. 517 518@item 519If you wish to incorporate parts of the Program into other free 520programs whose distribution conditions are different, write to the author 521to ask for permission. For software which is copyrighted by the Free 522Software Foundation, write to the Free Software Foundation; we sometimes 523make exceptions for this. Our decision will be guided by the two goals 524of preserving the free status of all derivatives of our free software and 525of promoting the sharing and reuse of software generally. 526@end enumerate 527 528@iftex 529@heading NO WARRANTY 530@end iftex 531@ifinfo 532@center NO WARRANTY 533@end ifinfo 534 535@enumerate 11 536@item 537BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY 538FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN 539OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 540PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED 541OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 542MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS 543TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE 544PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, 545REPAIR OR CORRECTION. 546 547@item 548IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 549WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 550REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, 551INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING 552OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED 553TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY 554YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 555PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE 556POSSIBILITY OF SUCH DAMAGES. 557@end enumerate 558 559@iftex 560@heading END OF TERMS AND CONDITIONS 561@end iftex 562@ifinfo 563@center END OF TERMS AND CONDITIONS 564@end ifinfo 565 566@page 567@unnumberedsec How to Apply These Terms to Your New Programs 568 569 If you develop a new program, and you want it to be of the greatest 570possible use to the public, the best way to achieve this is to make it 571free software which everyone can redistribute and change under these terms. 572 573 To do so, attach the following notices to the program. It is safest 574to attach them to the start of each source file to most effectively 575convey the exclusion of warranty; and each file should have at least 576the ``copyright'' line and a pointer to where the full notice is found. 577 578@smallexample 579@var{one line to give the program's name and an idea of what it does.} 580Copyright (C) 19@var{yy} @var{name of author} 581 582This program is free software; you can redistribute it and/or 583modify it under the terms of the GNU General Public License 584as published by the Free Software Foundation; either version 2 585of the License, or (at your option) any later version. 586 587This program is distributed in the hope that it will be useful, 588but WITHOUT ANY WARRANTY; without even the implied warranty of 589MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 590GNU General Public License for more details. 591 592You should have received a copy of the GNU General Public License 593along with this program; if not, write to the Free Software 594Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 595@end smallexample 596 597Also add information on how to contact you by electronic and paper mail. 598 599If the program is interactive, make it output a short notice like this 600when it starts in an interactive mode: 601 602@smallexample 603Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} 604Gnomovision comes with ABSOLUTELY NO WARRANTY; for details 605type `show w'. This is free software, and you are welcome 606to redistribute it under certain conditions; type `show c' 607for details. 608@end smallexample 609 610The hypothetical commands @samp{show w} and @samp{show c} should show 611the appropriate parts of the General Public License. Of course, the 612commands you use may be called something other than @samp{show w} and 613@samp{show c}; they could even be mouse-clicks or menu items---whatever 614suits your program. 615 616You should also get your employer (if you work as a programmer) or your 617school, if any, to sign a ``copyright disclaimer'' for the program, if 618necessary. Here is a sample; alter the names: 619 620@example 621@group 622Yoyodyne, Inc., hereby disclaims all copyright 623interest in the program `Gnomovision' 624(which makes passes at compilers) written 625by James Hacker. 626 627@var{signature of Ty Coon}, 1 April 1989 628Ty Coon, President of Vice 629@end group 630@end example 631 632This General Public License does not permit incorporating your program into 633proprietary programs. If your program is a subroutine library, you may 634consider it more useful to permit linking proprietary applications with the 635library. If this is what you want to do, use the GNU Library General 636Public License instead of this License. 637 638@node Preface, Usage, License, Top 639@chapter About VICE 640 641VICE is the one and only @dfn{Versatile Commodore Emulator}. It provides 642emulation of the Commodore C64, C64DTV, C128, VIC20, PET, PLUS4, SCPU64 and CBM-II computers 643within a single package. The emulators run as separate programs, but have 644the same user interface, share the same settings and support the same 645file formats. 646 647@strong{Important notice:} If you have no idea what a Commodore 6488-bit computer is, or have questions about how these machines are used, 649how the file formats work or anything else that is not strictly 650related to VICE, you should read the appropriate FAQs @emph{first}, as 651that kind of information is not available here. @xref{Contacts}. for 652information about how to retrieve the FAQs. 653 654All the emulators provide an accurate 6502/6510 emulator, with emulation 655of all the opcodes (both documented and undocumented ones) and accurate 656timing. Unlike other emulators, VICE aims to be cycle 657accurate; it tries to emulate chip timings as precisely as possible and 658does so @emph{efficiently}. 659 660Please do @emph{not} expect the C64DTV, C128, PET, PLUS4, SCPU64 and CBM-II emulators to 661be as good as the C64 or VIC20 one, as they are still under construction. 662 663@emph{Notice:} This documentation is written for the Unix release of VICE, but is slowly being made universal. 664 665@menu 666* C64 emulator features:: 667* C64DTV emulator features:: 668* C128 emulator features:: 669* VIC20 emulator features:: 670* PET emulator features:: 671* CBM-II emulator features:: 672* SCPU64 emulator features:: 673* Keyboard emulation:: 674* Joystick emulation:: 675* Disk drive emulation:: 676* Supported file formats:: 677* Common problems:: 678@end menu 679 680 681@node C64 emulator features, C64DTV emulator features, Preface, Preface 682@section C64 emulator features 683 684As of version 2.3, two C64 emulators are provided: @samp{x64} (fast) 685and @samp{x64sc} (accurate). As of version 3.4 @samp{x64} will no more get 686built by default and is not contained in the default binary packages. 687 688The fast C64 emulator, called @samp{x64}, features a fairly complete 689emulation of the VIC-II video chip: sprites, all registers and all video 690modes are fully emulated. The emulation has been fully cycle-accurate 691since version 0.13.0. 692 693The accurate C64 emulator, called @samp{x64sc}, features a cycle-based 694and pixel-accurate VIC-II emulation. This requires a much faster machine 695than the old @samp{x64}. 696 697A rather complete emulation of the SID sound chip is also provided. All 698the basic features are implemented as well as most of the complex ones 699including synchronisation, ring modulation and filters. There are two 700emulators of the SID chip available: first is the ``standard'' VICE 701emulator, available since VICE 0.12; the second is Dag Lem's reSID 702engine. The reSID engine is a lot more accurate than the standard engine, 703but it is also a lot slower, and only suitable for faster machines. 704 705Naturally, also both CIAs (or VIAs, in some cases) are fully emulated 706and cycle accurate. 707 708 709@node C64DTV emulator features, C128 emulator features, C64 emulator features, Preface 710@section C64DTV emulator features 711 712The C64DTV emulator, called @samp{x64dtv}, features emulation of C64DTV 713revisions 2 and 3. The emulator is under construction, but most of the 714DTV specific features are already supported (with varying accuracy). 715 716Video cache is disabled by default as it currently doesn't work with 717some of C64DTV's new video modes. The new video modes have a simple 718"fake" video cache implementation that may give incorrect results 719and decreased performance. 720 721 722@node C128 emulator features, VIC20 emulator features, C64DTV emulator features, Preface 723@section C128 emulator features 724 725The C128 emulator, called @samp{x128}, features a complete emulation of 726the internal MMU (@dfn{Memory Management Unit}), 80 column VDC screen, fast 727IEC bus emulation, 2 MHz mode, Z80 emulation plus all the features of the 728C64 emulation. 729 730 731@node VIC20 emulator features, PET emulator features, C128 emulator features, Preface 732@section VIC20 emulator features 733 734The VIC20 emulates all the internal hardware, including the VIA chips. 735The VIC-I video chip is fully emulated except NTSC interlace mode, so most 736graphical effects will work correctly. 737 738The VIC20 emulator allows the use of the VIC1112 IEEE488 739interface. You have to enable the hardware (by menu, resource, or 740commandline option) and then load the IEEE488 ROM (see for 741example @uref{http://www.funet.fi/pub/cbm/schematics/cartridges/vic20/ieee-488/325329-04.bin}, 742but you have to double the size to 4KiB for now). 743The IEEE-488 code is then started by @code{SYS45065}. 744 745 746@node PET emulator features, CBM-II emulator features, VIC20 emulator features, Preface 747@section PET emulator features 748 749The PET emulator emulates the 2001, 3032, 4032, 8032, 8096, 8296 and 750SuperPET (MicroMainFrame 9000) models, covering the whole series. 751The hardware is pretty much the same in each and that is why one single 752program is enough to emulate all of them. For more detailed information 753about PET hardware please refer to the @uref{https://sourceforge.net/p/vice-emu/code/HEAD/tree/techdocs/PET/PETdoc.txt?format=raw, PETDoc} file. 754 755Both the 40 column and 80 column CRTC video chips are emulated (from the 7564032 onward), but a few of the features are not implemented yet (numbers 757of rasterlines per char and lines per screen). Fortunately, they are 758not very important for average applications. 759 760The PET 8096 is basically a PET 8032 with a 64KiB extension board which 761allows remapping the upper 32KiB with RAM. You have to write to a special 762register at @code{$fff0} to remap the memory. The PET 8296 is a 7638096 but with a completely redesigned motherboard with 128KiB RAM in 764total. Of the additional 32KiB RAM you can use only some in blocks of 4KiB, 765but you have to set jumpers on the motherboard for it. VICE uses the 766command line options @samp{-petram9} and @samp{-petramA} 767instead. Also, the video controller can handle a larger address range. 768The PET 8x96 model emulations run the Commodore LOS-96 operating system 769- basically an improved BASIC 4 version with up to 32KiB for BASIC 770text and 32KiB for variables. See @uref{https://sourceforge.net/p/vice-emu/code/HEAD/tree/techdocs/PET/PETdoc.txt?format=raw, PETDoc} for more information. 771 772The PET 8296D is an 8296 with built-in 8250 low-profile dual disk drive. 773 774The PET 8296GD is an 8296D with additionally a "HiRes Emulator" (HRE). 775This is a cheaper version of a "HRG" hi-res board which was based on 776Thomson chips. This version instead uses no additional hardware support 777apart from some memory mapping tricks. It has supporting software in the 778hre-*.bin rom files. 779 780The SuperPET also is a PET 8032 with an expansion board. It can map 4KiB 781at a time out of 64KiB into the @code{$9***} area. Also it has an ACIA 7826551 for RS232 communication. The 6809 CPU that is built into the 783SuperPET is now emulated, since release 2.4, including the 6702 dongle 784chip. 785 786The Super-OS-9 MMU expansion, developed by TPUG (Toronto PET Users 787Group) is also emulated. 788 789The PET computers came with three major ROM revisions, so-called BASIC 7901, 2 and 4, all of which are provided. The PET 2001 uses the version 1, 791the PET 3032 uses version 2, and the others use version 4. The 2001 ROM 792is horribly broken with respect to IEEE488 (they shipped it before they 793tested it with the floppy drive, so only tape worked. Therefore the 794emulator patches the ROM to fix the IEEE488 routines. 795 796As well as other low-level fixes the 2001 patch obtains the load address 797for a program file from the first two bytes of the file. This allows 798the loading of both PET2001-saved files (that have $0400 as their load 799address) and other PET files (that have $0401). The PET2001 saves from 800$0400 and not from $0401 as other PETs do. 801 802Moreover, the secondary addresses used are now @code{0} and @code{1} for 803load and save, respectively, and not arbitrary unused secondary 804addresses. 805 806To select which model to run, specify it on the 807command line with the @code{-model MODEL} option, where 808@code{MODEL} can be one of a list of PET model numbers, all 809described in @pxref{PET model} 810@c FIXME: add link to section 811 812 813@node CBM-II emulator features, SCPU64 emulator features, PET emulator features, Preface 814@section CBM-II emulator features 815 816The CBM-II emulator emulates several types of CBM-II models. Those 817models are known under different names in the USA and Europe. In the 818States they have been sold as @code{B128} and @code{B256}, in Europe as 819@code{CBM 610}, @code{CBM 620} (low-profile case) or @code{CBM 710} and 820@code{CBM 720} (high-profile case with monitor). In addition to that 821now an experimental C510 emulation is included. The C510 (also known as 822P500) is the little brother of the C600/700 machines. It runs at roughly 8231 MHz and, surprise, it has a VIC-II instead of the CRTC. Otherwise 824the different line of computers are very similar. 825 826These computers are prepared to take a coprocessor board with an 8088 or 827Z80 CPU. Indeed there are models @code{CBM 630} and @code{CBM 730} that 828supposedly had those processors. However these models are not emulated. 829 830The basic difference is the amount of RAM these machines have been 831supplied with. The @code{B128} and the @code{CBM *10} models had 128KiB 832RAM, the others 256KiB. This implies some banking scheme, as the 6502 can 833only address 64KiB. And indeed those machines use a 6509, that can 834address 1 MiB of RAM. It has 2 registers at addresses 0 and 1. The 835indirect bank register at address 1 determines the bank (0-15) where the 836opcodes @code{LDA (zp),Y} and @code{STA (zp),Y} take the data from. The 837exec bank register at address 0 determines the bank where all other read 838and write addresses take place. 839 840The business line machines (C6xx/7xx) have the RAM in banks 1-2, resp. 8411-4. All available banks are used for BASIC, where program code is separated 842from all variables, resp. from normal variables, strings and arrays that 843are distributed over other banks. The C510 instead has RAM in banks 0 and 1, 844and uses bank 1 for program and all variables. Bank 0, though, can be 845accessed by the VIC-II to display graphics. 846 847Many models have been expanded to more than the built-in memory. In fact 848some machines have been expanded to the full 1MiB. Bank 15 is used as 849system bank, with only little RAM, and lots of expansion cartridge ROM 850area, the I/O and the kernal/basic ROMs. Some models have been modified 851to map RAM into the expansion ROM area. Those modifications can be 852emulated as well. 853 854The different settings are described in @pxref{CBM-II model}. 855 856@node SCPU64 emulator features, Keyboard emulation, CBM-II emulator features, Preface 857@section SCPU64 emulator features 858 859The XSCPU64 emulator is a simulation of a C64 equipped with a SuperCPU64 V2B. Features: 860 861@itemize @bullet 862@item 20 MHz asynchronous single cycle 65816 CPU core with proper dummy and invalid cycle handling. 863@item 128 KiB static RAM, 0-16 MiB SIMM RAM, 64-512 KiB EPROM emulated and their respective timing details. 864@item All RAM optimization configurations supported with write buffer. 865@item I/O area access delays, write through to SRAM implemented. 866@item Memory mappings including cartridge and boot memory map and kernal shadow. 867@item Hardware registers and switches implemented. 868@item Replacement SCPU64 ROM compatible with the original to avoid distribution problems 869@item It's using the single cycle VICII core for accurate simulation 870@end itemize 871 872Still to do: 873 874@itemize @bullet 875@item Measure and verify VICII interrupt phase shift 876@item Measure and verify BA phase shift 877@item SIMM RAM extra 7.5 cycle refresh delay every 10us missing. 878@item CPU NMI support for ``reset'' button 879@end itemize 880 881The emulation is quite accurate but not perfect. If you code something timing 882intensive using this simulation please always check it on real hardware to avoid 883bad surprises. 884 885The hardware itself is asynchronous in nature, therefore caution must be taken 886to not do long timing loops without synchronization in 20 MHz mode. Also don't 887squeeze out the last remaining cycles without leaving a safety buffer. 888Synchronization points can be created by doing I/O reads or writes and leaving 889a few hundred cycles left each frame will not hurt. 890 891Otherwise it can happen that the code is running on this version of VICE or my 892SCPU64 V2+C128D perfectly but nowhere else due to manufacturing variations and 893frequency drifts. 894 895@node Keyboard emulation, Joystick emulation, SCPU64 emulator features, Preface 896@section The keyboard emulation 897 898There are two ways of emulating the keyboard in VICE. 899 900The default way (@dfn{symbolic mapping}) is to map every key 901combination to the corresponding key combination on the real machine: 902for example, if you press @key{*}, which is bound to @kbd{Shift-8} on a 903U.S. keyboard, in the C64 emulator, the emulated machine will have just 904the @emph{unshifted} @key{*} key pressed (as @key{*} is unshifted on the 905C64 keyboard). Likewise, pressing @key{'} on the same U.S. keyboard 906without any shift key will cause the combination @kbd{Shift-7} to be 907pressed in the emulated C64. This way, it becomes quite obvious what 908keys should be typed to obtain all the symbols. @dfn{The key printed on the 909host keyboard will be pressed in the emulator}. 910 911There is, however, one problem with symbolic mapping: some keys really 912need to be mapped specially regardless (those that do not exist on a PC 913keyboard). Some examples are the @key{Commodore} key, @key{RUN/STOP}, 914@key{Clear/Home}. The exact mapping depends on your host layout, but should 915be easy to find out by try and error :) If in doubt, you can read the keyboard 916mapping files. 917 918The second way (@dfn{positional mapping}) is to map every key on the 919host keyboard to the key which has the same position on the keyboard 920of the emulated machine. This way the keyboard is more comfortable to use 921in those programs (such as some games) that require the keys to be in the 922correct positions. On the other hand it can be quite confusing if you are not 923very familiar with the original emulated keyboards. Also not all keys can be 924mapped exactly this way either, which means some of them still need to be 925mapped to other keys (see above). 926 927@strong{Warning:} unlike the real C64, VICE ``presses'' the @key{Shift} 928key @emph{together} with the key to shift when the @key{Shift} must be 929forced. In most cases this should work fine, but some keyboard routines 930are quite picky and tend not to recognize the shift key because of this. 931For instance, @kbd{F6} (which on the real C64 is obtained with 932@kbd{Shift + F5}) could be recognized as @kbd{F5}. In that case, use 933the shift key manually (i.e., type @kbd{Shift + F5} in the example). 934Yes, we know this is a bug. 935 936We depend a lot on your support to improve the keyboard maps, as we can not 937test all emulators in all possible configurations and using all host keyboard 938mappings. Please report any problems to us so we can fix them! 939 940If you experience problems with 'accent' keys such as acute, grave, tilde, 941circumflex, diaresis (and possibly more/other, depending on your host keyboard 942layout) try switching to a "no deadkeys" layout in your OS. In any case, please 943also report these problems so we can fix them! 944 945To find out the keycodes to use, incase you want to edit the keymaps yourself, 946you can enable showing the keycodes in the status bar in the settings. 947 948@node Joystick emulation, Disk drive emulation, Keyboard emulation, Preface 949@section The joystick emulation 950 951Joysticks can be emulated both via the keyboard and via a real joystick 952connected to the host machine. 953 954There are two keyboard layouts for joystick use, known as @dfn{numpad} 955and @dfn{custom}. 956 957The @dfn{numpad} layout uses the numeric keypad keys, i.e., the numbers 958@key{1}@dots{}@key{9} which emulate all the directions including the 959diagonal ones; @key{0} emulates the fire button. 960 961The @dfn{custom} layout is configurable to your liking. 962 963@node Disk drive emulation, Supported file formats, Joystick emulation, Preface 964@section The disk drive emulation 965 966All the emulators support up to 4 external disk drives as 967devices 8, 9, 10 and 11. Each of these devices can emulate virtual 968Commodore 1541, 1541-II, 1571, 1581, 2031, 2040, 3040, 4040, 1001, 8050, 8250, 969and D9090/60 drives in one of the following ways: 970 971@itemize @bullet 972@item 973using disk images, i.e., files that contain a dump of all the blocks 974contained in a real floppy disk; 975@item 976accessing file system directories, thus giving you the use of files 977without having to copy them to disk images; this also allows you to 978read and write files in the @code{P00} format. 979@item 980accessing a real device connected to the host machine. This works using the 981OpenCBM library. You can get it from @uref{https://spiro.trikaliotis.net/opencbm}. 982 983@end itemize 984 985When using disk images there are two available types of drive 986emulation. One of them the @dfn{virtual drive} emulation. It does 987@emph{not} really emulate the serial line, but patches the kernal ROM 988(with the so-called @dfn{kernal traps}) so that serial line operations 989can be emulated via C language routines. This emulation is very fast, 990but only allows use of standard DOS functions (and not even all of 991them). For real device access it is required to enable 992this type of emulation. 993 994The IEEE488 drives (2031, 2040, 3040, 4040, 1001, 8050, 8250, and D9090/60) 995do not use kernal traps. Instead the IEEE488 interface lines are 996monitored and the data is passed to the drive emulation. To use them 997on the C64, you need to enable the IEEE488 interface emulation. Only 998if the IEEE488 emulation is enabled, those drives can be selected. 999 1000The other alternative is a @dfn{true drive} emulation. The 1001Commodore disk drives are provided with their own CPU (a 6502 as the 1002VIC20 and the PETs) and their own RAM and ROM. So, in order to more 1003closely emulate its features, a complete emulation of this hardware 1004must be provided and that is what the @dfn{hardware level} emulation 1005does. When the @dfn{hardware level} emulation is used, the kernal 1006routines remain unpatched and the serial line is fully emulated. 1007The problem with this emulation is that it needs a lot of processing 1008power, mainly because the emulator has to emulate two CPUs instead of 1009one. 1010 1011The PETs do not use a serial IEC bus to communicate with the floppy 1012drive but instead use the parallel IEEE488 bus. This does 1013@emph{byte by byte} transfers, as opposed to the @emph{bit by bit} 1014transfers of the C64 and VIC20, so making it feasible to emulate the 1015parallel line completely while emulating the drive at DOS level only. 1016The IEEE488 line interpreter maps the drives 8-11 (as described 1017above) to the IEEE488 disk units, and no kernal traps are needed. 1018The same emulation of the Commodore IEEE488 bus interface is 1019available for the C64 and the VIC20. With IEEE488 drives you can have 1020true 2031 emulation at unit #8, and still have filesystem access at 1021units #10 or #11, because monitoring the IEEE488 lines does not 1022interfere with the true drive emulation. 1023 1024The IEEE488 disk drives 2040, 3040, 4040, 8050 and 8250 are Dual Drive 1025Floppy Disks. This means that these drives handle two disks. To 1026accomplish the emulation, only two disks can be emulated, namely units 1027#8 and #10. The attached image, track display and LED display of unit 1028#9 and #11 are used for the second drive of the dual disk drives. On 1029unix the unit number display (8 or 9, 10 or 11) in the emulation 1030window changes to the drive number display (0 or 1). 1031 1032The Commodore 2040, 3040, 4040, 1001, 8050, 8250, and D9090/60 drives are 1033so-called "old-style" disk drives. Their architecture includes not 1034one, but two processors of the 6502 type, namely a 6502 for the file 1035handling and communication with the PET (IP), and a 6504 (which is a 10366502 with reduced address space) for the drive handling (FDC). Both 1037processors communicate over a shared memory area. The IP writes 1038commands to read/write blocks to this area and the FDC executes them. 1039To make the emulation feasible, the FDC processor is not emulated 1040cycle-exactly as a 6504, but simply by checking the commands and 1041executing them on the host. This provides a fast FDC emulation, but 1042disallows the sending the FDC processor commands to execute code. 1043Applications where this is necessary are believed to be rather 1044seldom. Only the format command uses this feature, but this is 1045checked for. 1046 1047The dual disk drive 2040 emulates one of the very first CBM disk 1048drives. This drive has DOS version 1. DOS1 uses an own disk type, 1049that is closely related to the 1541 disk image. Only on tracks 18-24 1050DOS1 disks have a sector more than 1541 disks. DOS1 disk images have 1051the extension .d67. 1052 1053The dual disk drives 3040 and 4040 use the same logical disk format 1054as the VC1541 and the 2031. In fact, the 4040 was the first disk with 1055DOS version 2. The 3040 emulated here originally was the same as 10562040, only for the european 30xx PET series. As many of the original 1057DOS1 disk drives were upgraded (a simple ROM upgrade!) to DOS2, I use 1058the 3040 number for a DOS 2.0 disk drive, and 4040 for a revised DOS 10592 disk drive. It is, however, not yet clear whether the disks here 1060are write compatible to the 1541, as rumors exist that the write gap 1061between sectors is different. But read compatible they are. As VICE 1062emulates the FDC processor in C and not as 6504 emulation, this does 1063not matter in VICE. 1064 1065The drives 1001, 8050 and 8250 do actually have the very same DOS 1066ROM. Only the code in the FDC is different, which is taken care of by 1067VICE. So for all three of those disk drives, only @code{dos1001} is 1068needed. The DOS version used is 2.7. 1069 1070The D9090/60 is the only Commodore branded hard drive produced for 1071the PET series computers, and were often used by C64 and C128 users for 1072their significant storage capacity (29162/19441 free blocks). 1073Just like the other IEEE drives before it, it uses a separate 1074CPU as the FDC which in turn communicates with the SASI-to-ST506 bridge 1075(which is controlled by an AM2910). The hardware design is very similar 1076to the 8050/8250 drive. 1077 1078Creative Micro Designs (CMD) produced the last drives for the 1079Commodore 8-bit systems. They first released the hard drive (HD) line, 1080and later the floppy drive (FD) line. The CMD HD series can support up 1081to 4 GiB HDs with 255 separate partitions, while the CMD FD series can 1082support up to 3.3 MB extended density floppy disks with 31 separate 1083partitions. The FD series are also backwards compatible with 1581 1084media. The DOS for the FD series is stored on a ROM (@code{dos2000} 1085and @code{dos4000}, the latest versions being 1.40). 1086 1087The CMD HD uses a small boot ROM (@code{dosCMDHD}, the latest version 1088is 2.80) which loads the primary DOS (latest is 1.92) off the HD 1089itself. This allows for easy upgrades and expandability. This is also 1090the only drive to use the front panel buttons to control the mode of 1091the drive on reset. There are three modes of operation: normal, 1092configuration, and installation. VICE supports placing the drive in 1093either of these modes through the "Reset" sub-menu on the status bar 1094for the GTK3 interface, and the "Reset" menu in the SDL interface. 1095When creating a new DHD image, simply create an EMPTY file and VICE 1096will automatically place the drive in installation mode. Once the DOS 1097is installed, the CMD "hd-tools" program can be used to configure 1098various settings and partition the drive; this is done in 1099configuration mode for safety. When in either configuration or 1100installation mode, the device number is set to 30. Therefore, it is 1101not suggested to place two or more CMD HDs in either of these modes on 1102the same bus at the same time. 1103When migrating from real CMD hardware, use any HDD imaging software ("dd" 1104or GNU "ddrescue" on Linux) to copy the raw contents of a device to a file. 1105The destination file should have a "DHD" extension. 1106For those users with multiple disks, SCSI ID 0 should have the extension 1107"DHD", but any other drives should have ".S<ID>0" where <ID> is the SCSI ID. 1108Place all the files in the same folder when attaching to the "DHD" file. 1109The other files will automatically be scanned for and connected as well. 1110The CMD HD boot ROM is used for partition management, and ALL versions have 1111a known bug which corrupts data when deleting paritions across multiple 1112SCSI drives. 1113To avoid this scenario, it is highly suggested that another full DHD 1114image be created in VICE (on another unit) and all the files be copied 1115over from multi-disk configurations, using CMD "fcopy" for example, to 1116the new unit. 1117This will allow the user to take advantage of all the CMD HD features 1118without the potential for data loss. 1119 1120@node Supported file formats, Common problems, Disk drive emulation, Preface 1121@section Supported file formats 1122 1123VICE supports the most popular Commodore file formats: 1124 1125@itemize @bullet 1126 1127@item 1128@code{X64} or @code{D64} disk image files; Used by the 1541, 2031, 3040, 4040 drives. 1129 1130@item 1131@code{G64} GCR-encoded 1541 disk image files 1132 1133@item 1134@code{P64} lowlevel NRZI flux pulse disk image files 1135 1136@item 1137@code{D67} CBM2040 (DOS1) disk image format 1138 1139@item 1140@code{D71} VC1571 disk image format 1141 1142@item 1143@code{D81} VC1581 disk image format 1144 1145@item 1146@code{D80} CBM8050 disk image format 1147 1148@item 1149@code{D82} CBM8250/1001 disk image format 1150 1151@item 1152@code{D90} CBM D9090/60 disk image format 1153 1154@item 1155@code{D1M} FD2000/FD4000 DD disk image format 1156 1157@item 1158@code{D2M} FD2000/FD4000 HD disk image format 1159 1160@item 1161@code{D4M} FD4000 ED disk image format 1162 1163@item 1164@code{DHD} CMD HD disk image format 1165 1166@item 1167@code{T64} tape container files (read-only) 1168 1169@item 1170@code{TAP} lowlevel tape image files 1171 1172@item 1173@code{P00} program files 1174 1175@item 1176@code{CRT} C64 cartridge image files 1177 1178@item 1179@code{TCRT} tapecart image files 1180 1181@end itemize 1182 1183A utility (@code{c1541}, @pxref{c1541}) is provided to allow transfers 1184and conversions between these formats. 1185 1186Notice that the use of the @code{X64} file format is deprecated now. 1187 1188@cindex Converting X64 files into D64 1189You can convert an @code{X64} file back into a @code{D64} file with the 1190UNIX @code{dd} command: 1191 1192@example 1193dd bs=64 skip=1 if=IMAGE.X64 of=IMAGE.D64 1194@end example 1195 1196@xref{File formats}. for a technical description of the supported file 1197formats. 1198 1199@node Common problems, , Supported file formats, Preface 1200@section Common problems 1201 1202This section tries to describe the most common known problems with VICE, 1203and how to resolve them. 1204 1205@menu 1206* Sound problems:: 1207* Video problems:: 1208* Printer problems:: 1209* PET keyboard problems:: 1210@end menu 1211 1212@node Sound problems, Video problems, Common problems, Common problems 1213@subsection Sound problems 1214 1215VICE should compile and run without major problems on many systems, 1216but there are some known issues related to the sound driver. 1217 1218If you are having sound problems, such as skipping, first monitor how much CPU 1219time the respective emulator is taking on your system. To run smoothly, on a 1220modern system, it should really never go over 50% or so, except for very short 1221peaks that should also stay well beyond 90%. If you see it takes more, try 1222disabling some of the most CPU intense features (disable CRT emulation, use 1223fastsid instead of reSID, disable true drive emulation). 1224 1225If the CPU usage is ok, try using a different sound driver. You may also try 1226increasing the sound buffer size (although the default should be ok for modern 1227systems). 1228 1229All platforms that can run the SDL port (like Amiga, BeOS, etc) should be able 1230to play sound via SDL. 1231 1232@node Video problems, Printer problems , Sound problems, Common problems 1233@subsection Video problems 1234 1235Due to the way VICE currently handles its main loop, a common problem with 1236video sync occurs when the real (the monitors) frame rate is very close to, 1237equal, or lower than the framerate of the emulated machine. We recommend to 1238use a framerate which is slightly higher than that (eg 51Hz for the C64). 1239 1240@node Printer problems, PET keyboard problems ,Video problems, Common problems 1241@subsection Printer problems 1242 1243VICE supports the emulation of a printer either on the userport or as 1244IEC device 4. Unfortunately the Commodore IEC routines do not 1245send all commands to the IEC bus. For example an @code{OPEN 1,4} 1246is not seen on the IEC bus. Also a @code{CLOSE 1} after that 1247is not seen. VICE can see from printing that there was an @code{OPEN}, 1248but it cannot see when the close was. Also a "finish print job" 1249cannot be seen on the userport device. 1250To flush the printer buffer (write to @code{print.dump} or to the 1251printer) now a menu entry can be used. Disabling and re-enabling the printer 1252should work as well. 1253 1254The printing services have not been extensively tested but apart 1255from the problem mentioned above it should work fine now. 1256 1257@node PET keyboard problems, ,Printer problems, Common problems 1258@subsection PET keyboard problems 1259 1260If you find that the German keyboard mapping (plus German charset) 1261does not print uppercase umlauts, then you are right. 1262The umlauts replace the [,\ and ] characters in the charset. The keys 1263that make these characters do not have a different entry in the 1264PET editor ROM tables when shifted. 1265Thus it is not possible to get the uppercase umlauts in the editor. 1266Nevertheless other programs are reported to change the keyboard 1267mapping table and thus allow the use of the shifted (uppercase) umlauts. 1268 1269Anyway, the VICE keyboard mappings are far from being perfect and we are open 1270to any suggestions. 1271 1272@node Usage, System files, Preface, Top 1273@chapter Invoking the emulators 1274 1275The names of the available emulators are: 1276 1277@itemize @bullet 1278 1279@item 1280@code{vsid}, the SID player 1281 1282@item 1283@code{x64}, the fast C64 emulator 1284 1285@item 1286@code{x64sc}, the accurate C64 emulator 1287 1288@item 1289@code{x64dtv}, the C64DTV emulator 1290 1291@item 1292@code{x128}, the C128 emulator 1293 1294@item 1295@code{xvic}, the VIC20 emulator 1296 1297@item 1298@code{xpet}, the PET emulator 1299 1300@item 1301@code{xplus4}, the PLUS4 emulator 1302 1303@item 1304@code{xcbm2}, the CBM-II emulator (CRTC models) 1305 1306@item 1307@code{xcbm5x0}, the CBM-II emulator (VIC-II models) 1308 1309@item 1310@code{xscpu64}, the SCPU64 emulator 1311 1312@end itemize 1313 1314You can run each of them by simply typing the name from a shell or by configuring 1315your window manager for example to use them to open disk images. 1316 1317If you want to look at the log output run them from a terminal window such as 1318@code{xterm} or @code{rxvt}. For example, you could do 1319 1320@example 1321xterm -e x64sc 1322@end example 1323 1324 1325@menu 1326* Command-line initialization:: 1327* Command-line autostart:: 1328@end menu 1329 1330@node Command-line initialization, Command-line autostart, Usage, Usage 1331@section Command-line options used during initialization 1332 1333There are several options you can specify on the command line. Some of 1334them are used to specify emulation settings and will be described in 1335detail later (@pxref{Settings and resources} for a complete list). The 1336remaining options are used only to give usage information or to 1337initialize the emulator in some way: 1338 1339@table @code 1340@findex -help 1341@item -help 1342@findex -? 1343@itemx -? 1344List all the available command-line options and their meaning. 1345 1346@findex -features 1347@item -features 1348List all compile time features 1349 1350@findex -default 1351@item -default 1352Set default resources (@pxref{Settings and resources}). This will 1353override all the settings specified before, but not the settings 1354specified afterwards on the command line. 1355 1356@findex -config 1357@item -config <filename> 1358Specify config file 1359 1360@findex -addconfig 1361@item -addconfig <filename> 1362Specify extra config file for loading additional resources. This can be used to 1363add "patch sets" for various configurations. 1364 1365@findex -dumpconfig 1366@item -dumpconfig <filename> 1367Write the complete config into file. Normally only resources that have been 1368changed from their default value would be written to the config file, however 1369with this option you can see all resources and their current values. 1370 1371@findex -logfile 1372@item -logfile <name> 1373Specify log file name 1374(@code{LogFileName}). 1375 1376@findex -verbose 1377@item -verbose 1378Enable verbose log output. 1379 1380@findex -silent 1381@item -silent 1382Disable all log output (except errors). 1383 1384@findex -keybuf 1385@item -keybuf <string> 1386Put the specified string into the keyboard buffer. 1387 1388@findex -console 1389@item -console 1390Console mode (for music playback, or for running the emulator test programs) 1391 1392@findex -limitcycles 1393@item -limitcycles <cycles> 1394Automatically exit the emulator after a given number of cycles. 1395 1396@findex -chdir 1397@item -chdir <directory> 1398Change the working directory. 1399 1400@findex -autostart 1401@item -autostart <name> 1402Autostart <name> (@pxref{Command-line autostart}). 1403 1404@findex -autoload 1405@item -autoload <name> 1406Attach and autoload tape/disk image <name> 1407 1408@findex -1 1409@item -1 <Name> 1410Attach <Name> as a tape image file. 1411 1412@findex -8 1413@item -8 <Name> 1414@findex -9 1415@itemx -9 <Name> 1416@findex -10 1417@itemx -10 <Name> 1418@findex -11 1419@itemx -11 <Name> 1420Attach <Name> as a disk image to device 8, 9, 10 or 11. 1421 1422@findex -8d1 1423@item -8d1 <Name> 1424@findex -9d1 1425@itemx -9d1 <Name> 1426@findex -10d1 1427@itemx -10d1 <Name> 1428@findex -11d1 1429@itemx -11d1 <Name> 1430Attach <Name> as a disk image to the second drive of a dual-drive device 8, 9, 10 or 11. 1431 1432@findex -attach8ro 1433@findex -attach9ro 1434@findex -attach10ro 1435@findex -attach11ro 1436@item -attach8ro 1437@itemx -attach9ro 1438@itemx -attach10ro 1439@itemx -attach11ro 1440Attach disk image for drive #8-11 read only 1441(@code{AttachDevice8Readonly=1}, @code{AttachDevice9Readonly=1}, @code{AttachDevice10Readonly=1}, @code{AttachDevice11Readonly=1}) 1442(all emulators except vsid). 1443 1444@findex -attach8d1ro 1445@findex -attach9d1ro 1446@findex -attach10d1ro 1447@findex -attach11d1ro 1448@item -attach8d1ro 1449@itemx -attach9d1ro 1450@itemx -attach10d1ro 1451@itemx -attach11d1ro 1452Attach disk image for second drive of a dual-drive #8-11 read only 1453(@code{AttachDevice8d1Readonly=1}, @code{AttachDevice9d1Readonly=1}, @code{AttachDevice10d1Readonly=1}, @code{AttachDevice11d1Readonly=1}) 1454(all emulators except vsid). 1455 1456@findex -attach8rw 1457@findex -attach9rw 1458@findex -attach10rw 1459@findex -attach11rw 1460@item -attach8rw 1461@itemx -attach9rw 1462@itemx -attach10rw 1463@itemx -attach11rw 1464Attach disk image for drive #8-11 read write (if possible) 1465(@code{AttachDevice8Readonly=0}, @code{AttachDevice9Readonly=0}, @code{AttachDevice10Readonly=0}, @code{AttachDevice11Readonly=0}) 1466(all emulators except vsid). 1467 1468@findex -attach8d1rw 1469@findex -attach9d1rw 1470@findex -attach10d1rw 1471@findex -attach11d1rw 1472@item -attach8d1rw 1473@itemx -attach9d1rw 1474@itemx -attach10d1rw 1475@itemx -attach11d1rw 1476Attach disk image for second drive of a dual-drive #8-11 read write (if possible) 1477(@code{AttachDevice8d1Readonly=0}, @code{AttachDevice9d1Readonly=0}, @code{AttachDevice10d1Readonly=0}, @code{AttachDevice11d1Readonly=0}) 1478(all emulators except vsid). 1479 1480@findex -exitscreenshot 1481@item -exitscreenshot <name> 1482Specify name of a screenshot file that will be written when the emulator exits. 1483(@code{ExitScreenshotName}). 1484 1485@findex -exitscreenshotvicii 1486@item -exitscreenshotvicii <name> 1487Specify name of a screenshot file that will be written when the emulator exits. 1488(@code{ExitScreenshotName1}). (x128) 1489 1490@end table 1491 1492 1493@node Command-line autostart, , Command-line initialization, Usage 1494@section Autostarting programs from the command-line 1495 1496It is possible to let the emulator @dfn{autostart} a disk or tape image 1497file, by simply specifying its name as the @emph{last} argument on the 1498command line, for example 1499 1500@example 1501x64sc lovelygame.d64 1502@end example 1503 1504will start the C64 emulator, attaching @file{lovelygame.d64} as a 1505disk image and running the first program on it. You can also specify 1506the name of the program on the fisk image by appending a colon 1507(@samp{:}) the name itself to the argument; for example 1508 1509@example 1510x64sc "lovelygame.d64:run me" 1511@end example 1512 1513will run the program named @file{run me} on @file{lovelygame.d64} 1514instead of the first one. 1515 1516@findex -autostart 1517Using the command-line option @code{-autostart} is equivalent; so the same 1518result can be obtained with 1519 1520@example 1521x64sc -autostart "lovelygame.d64:run me" 1522@end example 1523 1524If you specify a raw CBM or P00 file, the emulator will setup the file 1525system based drive emulation so that it is enabled and accesses the 1526directory containing the file first. This is a very convenient way to 1527start multi-file programs stored in file system directories and not 1528requiring ``true'' drive emulation. 1529 1530@xref{Disk and tape images}. for more information about images and 1531autostart. 1532 1533 1534@node System files, Basics, Usage, Top 1535@chapter System files 1536 1537In order to work properly, the emulators need to load a few system 1538files: 1539 1540@itemize @bullet 1541 1542@item 1543the @dfn{system ROMs}, raw binary files containing copies of the original ROMs 1544of the machine you are emulating; 1545 1546@item 1547the @dfn{keyboard maps}, text files describing the keyboard layout; 1548 1549@item 1550the @dfn{palette files}, text files describing the colors of the machine you 1551are emulating. 1552 1553@item 1554the @dfn{romset files}, text files describing the different ROMs to load. 1555 1556@end itemize 1557 1558The place where they will be searched for depends on the value of the 1559@code{Directory} resource, which is a colon (@code{:})-separated search 1560path list, like the @sc{unix} @code{PATH} environment variable. The 1561default value is 1562 1563@example 1564$HOME/.local/share/vice/EMU:PREFIX/lib/vice/EMU:BOOTPATH/EMU 1565@end example 1566 1567Where @code{PREFIX} is the installation prefix (usually 1568@file{/usr/local}), @code{EMU} is the name of the emulated machine 1569(@code{C64}, @code{C64DTV}, @code{C128}, @code{PET}, @code{PLUS4}, @code{CBM-II}, @code{SCPU64} 1570or @code{VIC20}) and @code{BOOTPATH} is the directory where the executable resides. 1571The disk drive ROMs are looked for in a directory with @code{EMU} set to 1572@code{DRIVES}. @code{$HOME} is the user's home directory. 1573 1574For example, if you have the C64 emulator installed in 1575 1576@example 1577/usr/local/bin/x64 1578@end example 1579 1580then the value will be 1581 1582@example 1583$HOME/.local/share/vice/C64:/usr/local/lib/vice/C64:/usr/local/bin/C64 1584@end example 1585 1586And system files will be searched for under the following directories, 1587in the specified order: 1588 1589@enumerate 1 1590@item 1591@code{$HOME/.local/share/vice/C64} 1592@item 1593@code{/usr/local/lib/VICE/C64} 1594@item 1595@code{/usr/local/bin/C64} 1596@end enumerate 1597 1598System files can still be installed in a different directory if you 1599specify a complete path instead of just a file name. For example, if 1600you specify @file{./kernal} as the kernal image name, the kernal image 1601will be loaded from the current directory. This can be done by using 1602command-line options or by modifying 1603resource values (@pxref{Resource files}). 1604 1605@menu 1606* ROM files:: Files containing dumps of the original ROMs. 1607* Keymap files:: Files describing the keyboard layout. 1608* Palette files:: Files defining the machine's colors. 1609* Romset files:: Files defining the machine's ROM set. 1610@end menu 1611 1612@node ROM files, Keymap files, System files, System files 1613@section ROM files 1614 1615Every emulator requires its own ROM set. For the VIC20 and the C64, the 1616ROM set consists of the following files: 1617 1618@itemize @bullet 1619 1620@item 1621@file{kernal}, the Kernal ROM (8 KiB) 1622 1623@item 1624@file{basic}, the Basic ROM (8 KiB) 1625 1626@item 1627@file{chargen}, the character generator ROM (4 KiB) 1628 1629@end itemize 1630 1631The C128 needs the following files: 1632 1633@itemize @bullet 1634 1635@item 1636@file{kernal}, the Kernal ROM (8 KiB) 1637 1638@item 1639@file{basic}, the Basic + Editor ROM (32 KiB) 1640 1641@item 1642@file{chargen}, the character generator ROM (4 KiB) 1643 1644@end itemize 1645 1646The C128, VIC20, SCPU64 and C64 emulators also need the following DOS ROMs for 1647the hardware-level emulation of the 1540, 1541, 1571, 1581, 2000, and 4000 disk 1648drives, as well as the CMD hard drive: 1649 1650@itemize @bullet 1651 1652@item 1653@file{dos1540}, the 1540 drive ROM (16 KiB) 1654 1655@item 1656@file{dos1541}, the 1541 drive ROM (16 KiB) 1657 1658@item 1659@file{dos1541II}, the 1541-II drive ROM (16 KiB) 1660 1661@item 1662@file{dos1571}, the 1571 drive ROM (32 KiB) 1663 1664@item 1665@file{dos1581}, the 1581 drive ROM (32 KiB) 1666 1667@item 1668@file{dos2000}, the 2000 drive ROM (32 KiB) 1669 1670@item 1671@file{dos4000}, the 4000 drive ROM (32 KiB) 1672 1673@item 1674@file{dosCMDHD}, the CMD HD boot ROM (16 KiB) 1675 1676@end itemize 1677 1678In addition to those all emulators can handle 1679a parallel IEEE488 interface (the C64 and C128 via @code{$df**} extension, 1680the VIC20 via VIC1112 emulation) 1681so they also need the DOS ROM for the IEEE disk drives: 1682 1683@itemize @bullet 1684 1685@item 1686@file{dos2031}, the 2031 drive ROM (16 KiB) 1687(DOS 2.6, Commodore ROM images 901484-03 and 901484-05) 1688 1689@item 1690@file{dos2040}, the 2040 drive ROM (8 KiB) 1691(DOS 1, Commodore ROM images 901468-06, 901468-07) 1692 1693@item 1694@file{dos3040}, the 3040 drive ROM (12 KiB) 1695(DOS 2, Commodore ROM images 901468-11, 901468-12 and 901468-13) 1696 1697@item 1698@file{dos4040}, the 4040 drive ROM (12 KiB) 1699(DOS 2, Commodore ROM images 901468-14, 901468-15 and 901468-16) 1700 1701@item 1702@file{dos1001}, the 1001/8050/8250 drive ROM (16 KiB) 1703(DOS 2.7, Commodore ROM images 901887-01 and 901888-01) 1704 1705@item 1706@file{dos9000}, the D9090/60 drive ROM (16 KiB) 1707(DOS 3.0, Commodore ROM images 300516-RevC and 300517-RevC) 1708 1709@end itemize 1710 1711Note that there are other DOS images on the internet. The DOS 2.5 images 1712might be used with the 8050, but it cannot handle the double sided drives 1713of the 1001 and 8250 and it is not supported by VICE. 1714 1715The PET emulator uses an expanded setup, because there are three major 1716versions of the Basic and the Kernal, and many versions of the 1717Editor ROM. In addition there are cartridge ROM sockets. 1718 1719The Kernal files contain the memory from range $F000-$FFFF, the Basic 1720ROMs either the range $C000-$DFFF or $B000-$DFFF. 1721To handle the different screen 1722sizes and keyboards, different so-called ``editor-ROMs'' for the memory 1723range $E000-$E800 are provided. 1724The PET ROMs have the following names: 1725 1726@itemize @bullet 1727 1728@item 1729@file{kernal-1.901439-04-07.bin}, the PET2001 Kernal ROM (4 KiB) 1730(Commodore ROM images 901447-06 and 901447-07, same as 901439-04 and 901439-07) 1731@item 1732@file{kernal-2.901465-03.bin}, the PET3032 Kernal ROM (4 KiB) 1733(Commodore ROM image 901465-03) 1734@item 1735@file{kernal-4.901465-22.bin}, the PET4032/8032 Kernal ROM (4 KiB) 1736(Commodore ROM image 901465-22) 1737 1738@item 1739@file{basic-1.901439-09-05-02-06.bin}, the PET2001 Basic 1 ROM (8 KiB) 1740(Commodore ROM images 901447-09, 901447-02, 901447-03, 901447-04.bin. 1741The -09 ROM is the revised -01 ROM. 1742Same as images 901439-09, 901439-05, 901439-02, 901439-06. 1743The -09 ROM is the revised -01 ROM) 1744@item 1745@file{basic-2.901465-01-02.bin}, the PET3032 Basic 2 ROM (8 KiB) 1746(Commodore ROM images 901465-01 and 901465-01) 1747@item 1748@file{basic-4.901465-23-20-21.bin}, the PET4032/8032 Basic 4 ROM (12 KiB) 1749(Commodore ROM images 901465-23, 901465-20 and 901465-21. 1750The -23 ROM is a revised -19 ROM) 1751 1752@item 1753@file{edit-1-n.901439-03.bin}, the PET2001 editor for graphics keyboards (2 KiB) 1754(Commodore ROM image 901447-05, same as 901439-03) 1755@item 1756@file{edit-2-b.901474-01.bin}, the PET3032 editor for business keyboards (2 KiB) 1757(Commodore ROM image 901474-01) 1758@item 1759@file{edit-2-n.901447-24.bin}, the PET3032 editor for graphics keyboards (2 KiB) 1760(Commodore ROM image 901447-24) 1761@item 1762@file{edit-4-40-n-50Hz.901498-01.bi}, the PET4032 editor for graphics keyboards (2 KiB) 1763(Commodore ROM image 901498-01) 1764@item 1765@file{edit-4-40-b-50Hz.ts.bin}, the PET4032 editor for business keyboards (2 KiB) 1766(Said to be "901498-01 modified to use a business keyboard on a 50Hz 4032") 1767 1768@item 1769@file{edit-4-80-b-50Hz.901474-04_.bin}, the PET8032 editor for business keyboards (2 KiB) 1770(Commodore ROM image 901474-04-?) 1771 1772@item 1773@file{characters-2.901447-10.bin}, the character generator ROM (2KiB). 1774It has two sets 1775with 128 chars each. The second (inverted) half of each set is computed from 1776the first half by inverting it. This is a PET hardware feature. 1777(Commodore ROM image 901447-10) 1778@item 1779@file{chargen.de}, the character generator ROM (2KiB). This version is a 1780patched German charset, with the characters [, \ and ] replaced by umlauts. 1781It has been provided by U. Guettich and he reports that it is supported 1782by some programs. 1783 1784@item 1785@file{characters.901640-01.bin}, the SuperPET character generator ROM (4KiB). 1786The first half is the same as @file{characters-2.901447-10.bin}, the second half contains, 1787instead of an upper and lower case set, an ASCII character set and an 1788APL character set. For these sets, the screen code is equal to the 1789ASCII/APL code. 1790@item 1791@file{waterloo-[abcdf]000.901898-0[1-5].bin}, 1792@file{waterloo-e000.901897-01.bin}. 1793The Waterloo system ROMs for the 6809 CPU in the SuperPET. 1794 1795@item 1796@file{hre-9000.324992-02.bin} HiRes Emulator (at $9000) and 1797@file{hre-a000.324993-02.bin} HiRes BASIC (at $A000). 1798These are the two roms for supporting the HRE on the 8296. 1799The ROMs are initialized by the command @code{SYS 36864}. 1800@end itemize 1801 1802The PETs also have sockets for extension ROMs for the addresses 1803$9000-$9FFF, $A000-$AFFF and $B000-$BFFF (the last one for PET2001 and 1804PET3032 only). You can specify ROM image files for those extensions 1805command line options @code{-petrom9}, @code{-petromA} and 1806@code{-petromB} resp. 1807 1808An alternative would be to specify a long kernal ROM with the 1809@code{-kernal} option that includes the extension ROM areas. 1810 1811Also, you can specify replacements for the basic ROM at $B000-$DFFF 1812with the @code{-petromBasic} option and for the editor ROM 1813at $E000-$E7FF with the @code{-petromEditor} option. 1814 1815The CBM-II emulator again uses another setup. For those models the 1816kernal used is the same for all. However, for different amounts of 1817memory exist different versions of the BASIC ROMs. The 128KiB RAM version 1818(C610, C710, B128) uses one bank of 64KiB for the BASIC text and another 1819one for all the variables. The 256KiB RAM version uses one bank for text, 1820one for variables, one for arrays and one for strings. 1821 1822Also the character generator ROMs have a format different from the 1823above. The other character ROMs have 8 bytes of pixel data per 1824character. Those ROMs have 16 bytes per character instead. The C6x0 1825only uses the first 8 of it, but the C7x0 uses 14 lines per character 1826and needs those larger ROMs. Both ROMs hold, like the PET, two 1827character sets with 128 characters each. Again the second half of the 1828full (256 char) character set is computed by inverting. 1829 1830@itemize @bullet 1831 1832@item 1833@file{kernal}, the KERNAL (8KiB) for the business machines (6xx/7xx) 1834 1835@item 1836@file{kernal.500}, the KERNAL (8KiB) for the personal machine (510) (901234-02) 1837 1838@item 1839@file{basic.128}, the CBM-II 128KiB BASIC (16KiB) 1840 1841@item 1842@file{basic.256}, CBM-II 256KiB BASIC (16KiB) 1843 1844@item 1845@file{basic.500}, C510 BASIC (16KiB) (901236-02 + 901235-02) 1846 1847@item 1848@file{chargen.500}, character generator ROM for the C5x0 (4KiB) (901225-01) 1849 1850@item 1851@file{chargen.600}, character generator ROM for the C6x0 (4KiB) 1852 1853@item 1854@file{chargen.700}, character generator ROM for the C7x0 (4KiB) 1855 1856@end itemize 1857 1858The SCPU64 needs the following files: 1859 1860@itemize @bullet 1861 1862@item 1863@file{scpu64}, the SCPU64 ROM (128 KiB) 1864 1865@item 1866@file{chargen}, the character generator ROM (4 KiB) 1867 1868@end itemize 1869 1870@node Keymap files, Palette files, ROM files, System files 1871@section Keymap files 1872 1873@dfn{Keymap files} are used to define the keyboard layout, defining which 1874key (or combination of keys) must be mapped to each keysym. 1875 1876In other words, the keyboard emulation works like this: whenever the 1877user presses or releases a key while the emulation window has the input 1878focus, the emulator receives an event with a value that 1879identifies that key. That value is called a @dfn{keysym} and is unique 1880to that key. The emulator then looks up that keysym in an internal 1881table that tells it which key(s) to press or release on the emulated 1882keyboard. 1883 1884This table is described by the keymap file, which is made up of lines 1885like the following: 1886 1887@example 1888KEYSYM ROW COLUMN SHIFTFLAG 1889@end example 1890 1891Where: 1892 1893@itemize @bullet 1894 1895@item 1896@code{KEYSYM} is a string (GTK) or number (SDL) identifying the keysym: you can 1897use the "show keycodes in statusbar" feature to see what keysym 1898is bound to any key; 1899 1900@item 1901@code{ROW} and @code{COLUMN} identify the key on the emulated keyboard; 1902 1903@item 1904@code{SHIFTFLAG} can have one of the following values: 1905 1906@itemize @bullet 1907 1908@item 1909@code{0}: the key is never shifted; 1910 1911@item 1912@code{1}: the key is shifted; 1913 1914@item 1915@code{2}: the key is the left shift; 1916 1917@item 1918@code{4}: the key is the right shift; 1919 1920@item 1921@code{8}: the key can be (optionally) shifted by the user. 1922 1923@item 1924@code{16}: deshift key for this keysym/scancode 1925 1926@item 1927@code{32}: another definition for this keysym/scancode follows 1928 1929@item 1930@code{64}: key is shift-lock on emulated machine 1931 1932@item 1933@code{128}: shift modifier required on host 1934 1935@item 1936@code{256}: key is used for an alternative keyboard mapping 1937 1938@item 1939@code{512}: alt-r (alt-gr) modifier required on host 1940 1941@item 1942@code{1024}: ctrl modifier required on host 1943 1944@item 1945@code{2048}: key is combined with cbm for this keysym/scancode 1946 1947@item 1948@code{4096}: key is combined with ctrl for this keysym/scancode 1949 1950@item 1951@code{8192}: key is (left) cbm on emulated machine 1952 1953@item 1954@code{16384}: key is (left) ctrl on emulated machine 1955 1956@end itemize 1957 1958@end itemize 1959 1960The @code{SHIFTFLAG} is useful if you want certain keys to be 1961``artificially'' shifted by the emulator, and not by the user. For 1962example, @key{F2} is shifted on the C64 keyboard, but you might want it 1963to be mapped to the unshifted @key{F2} key on the PC keyboard. To do 1964so, you just have to use a line like the following: 1965 1966@example 1967F2 0 4 1 1968@end example 1969 1970where @code{0} and @code{4} identify the key (row 0, column 4 on the 1971keyboard matrix), and @code{1} specifies that every time the user presses 1972@key{F2} the shift key on the C64 keyboard must be pressed. 1973 1974There are also some special commands you can put into the keyboard file; 1975they are recognized because they start with an exclamation mark: 1976 1977@itemize @bullet 1978 1979@item 1980@code{!CLEAR} clears the currently loaded keyboard map; it is 1981necessary to put this at the beginning of the file if you want the 1982keymap file to override all of the current internal settings; 1983 1984@item 1985@code{!INCLUDE} followed by "filename" reads (inserts) file as mapping file. This is useful 1986when adding local mappings to an otherwise generic file (so you dont have to 1987copy the while file, but just add/modify a few keys). 1988 1989@item 1990@code{!UNDEF} keysym' remove keysym from table 1991 1992@item 1993@code{!LSHIFT}, @code{!RSHIFT}, followed by a row and a column 1994value, specify where the left and right shift keys are located on the 1995emulated keyboard; for example, C64 default keymaps will specify 1996 1997@example 1998!LSHIFT 1 7 1999!RSHIFT 6 4 2000@end example 2001 2002@item 2003@code{!LCTRL}, followed by a row and a column value, specifiy where the left 2004control key is located on the emulated keyboard. 2005 2006@item 2007@code{!LCBM}, followed by a row and a column value, specifiy where the left 2008CBM key is located on the emulated keyboard. 2009 2010@item 2011@code{!VSHIFT}, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will 2012be used as a virtual shift key when the shift flag is set. 2013 2014@item 2015@code{!SHIFTL}, followed by a shiftkey (RSHIFT or LSHIFT), specify what key will 2016be used as a virtual shift-lock key. 2017 2018@item 2019@code{!VCTRL}, followed by a ctrlkey (LCTRL), specify what key will 2020be used as a virtual control key. 2021 2022@item 2023@code{!VCBM}, followed by a cbmkey (LCBM), specify what key will 2024be used as a virtual CBM key. 2025 2026@end itemize 2027 2028Any line starting with the @code{#} sign, instead, is completely 2029ignored. This is useful for adding comments within the keymap file. 2030 2031VICE keymap files have the @file{.vkm} default extension, and every 2032emulator comes with a default positional mapping and a default symbolic 2033mapping. 2034 2035 2036@node Palette files, Romset files, Keymap files, System files 2037@section Palette files 2038 2039@dfn{Palette files} are used to specify the colors used in the 2040emulators. They are made up of lines like the following: 2041 2042@example 2043RED GREEN BLUE DITHER 2044@end example 2045 2046where @code{RED}, @code{GREEN} and @code{BLUE} are hexadecimal values 2047ranging from 0 to FF and specifying the amount of red, green and blue 2048you want for each color and @code{DITHER} is a 4-bit hexadecimal number 2049specifying the pattern you want when rendering on a B/W display. 2050 2051You have to include as many lines as the number of colors the emulated 2052machine has, and the order of the lines must respect the one used in the 2053machine (so the N'th line must contain the specifications for color N - 20541 in the emulated machine). 2055 2056Lines starting with the @code{#} sign are completely ignored. This is 2057useful for adding comments (such as color names) within the palette 2058file. 2059 2060For example, the default PET palette file (which has only two colors, 0 for 2061background and 1 for foreground), looks like the following: 2062 2063@example 2064# 2065# VICE Palette file 2066# 2067# Syntax: 2068# Red Green Blue Dither 2069# 2070 2071# Background 207200 00 00 0 2073 2074# Foreground 207500 FF 00 F 2076@end example 2077 2078@node Romset files, , Palette files, System files 2079@section Romset files 2080 2081The Romset files are not used by default on all emulators. 2082You might have recognized that the names of the ROM images are 2083saved in resources. Loading a Romset file now just means a `shortcut' 2084to changing all the resources with ROM image names and reloading 2085the ROMs. 2086 2087The PET and CBM-II emulators use this feature to change between the 2088different ROM versions available for those machines. E.g. the 2089Romset file for the PET 2001 is 2090 2091@example 2092KernalName="pet2001" 2093EditorName= 2094ChargenName="chargen" 2095RomModule9Name= 2096RomModuleAName= 2097RomModuleBName= 2098@end example 2099 2100As you can see, the file even uses the same syntax as the 2101resource file, it is just a bit stripped down. 2102 2103While a Romset file is processed, the directory where the Romset file 2104was found is temporarily prepended to the search path (@code{Directory} 2105resource). This also means that if you have a setting for 2106@code{Directory} in it, its effect is limited to the Romset file itself. 2107 2108@c FIXME @node 2109@subsection Romset command line options 2110 2111@table @code 2112 2113@findex -romsetfile 2114@item -romsetfile <File> 2115load the given romset file 2116 2117@findex -romsetarchive 2118@item -romsetarchive <File> 2119load the given romset archive 2120 2121@findex -romsetarchiveselect 2122@item -romsetarchiveselect <Item number> 2123select the given item from the current romset archive 2124 2125@end table 2126 2127@node Basics, Settings and resources, System files, Top 2128@chapter Basic operation 2129 2130This section describes the basic things you can do once the emulator 2131has been fired up. 2132 2133 2134@menu 2135* Emulation window:: The window the emulator runs in. 2136* Menus:: Using emulator menus. 2137* Help:: Getting help if you are stuck. 2138* File Selector:: Selecting files interactively. 2139* Disk and tape images:: Using virtual disks and tapes. 2140* Reset:: Resetting the virtual machines. 2141@end menu 2142 2143@node Emulation window, Menus, Basics, Basics 2144@section The emulation window 2145 2146When the emulator is run, the screen of the emulated machine is 2147displayed in a window which we will call the @dfn{emulation 2148window}. This window will be updated in real time, displaying the same 2149contents that a real monitor or TV set would. 2150 2151Below the emulation window there is an area which is used to display 2152information about the state of the emulator; we will call this area the 2153@dfn{status bar}. 2154 2155On the extreme left of the status bar, there is a @dfn{performance 2156meter}. This displays the current relative speed of the emulator (as a 2157percentage) and the update frequency (in frames per second). All the 2158machines emulated are PAL, so the update frequency will be 50 frames 2159per second if your system is fast enough to allow emulation at 2160the speed of the real machine. 2161 2162On the extreme right of the status bar, there is a @dfn{drive status 2163indicator}. This is only visible if the hardware-level (``True'') 1541 2164emulation is turned on. In that case, the drive status indicator will 2165contain a rectangle emulating the drive LED and will display the current 2166track position of the drive's read/write head. 2167 2168@node Menus, Help, Emulation window, Basics 2169@section Using the menus 2170 2171It is possible to execute some commands and change emulation parameters 2172while the emulator is running: most emulation settings can be changed in 2173the @dfn{options menu}. Additionally clicking on the various widgets in the 2174status bar gives access to related settings. 2175Settings can be saved and later used with the ``Save settings'' and ``Load settings'' 2176menu items, respectively. Also by default, settings will get saved when exiting 2177the emulator. ``Restore default settings'' restores the factory defaults. 2178See @xref{Settings and resources} for more information about how settings 2179work in VICE. 2180 2181A lot of settings and actions can be reached via @dfn{shortcuts} or @dfn{hotkeys}, 2182i.e., it is possible to execute them by pressing a sequence of keys 2183instead of going through the menu with the mouse. Where shortcuts 2184exist, they are displayed in parentheses at the right edge of the menu 2185item. In VICE, all shortcuts must begin with the @key{Meta} or 2186@key{Alt} key. So, for example, to attach a disk image to drive #8 (the 2187corresponding menu item displays ``M-8''), you have to press the 2188@key{Meta} (or @key{Alt}) and then @key{8}. 2189 2190Note that no other key presses are passed on to the emulated machine 2191while either @key{Meta} or @key{Alt} are held down. 2192 2193@node Help, File Selector, Menus, Basics 2194@section Getting help 2195 2196At any time, if you get stuck or do not remember how to perform a 2197certain action, you can use the ``Browse manuals'' command (from the help 2198menu). This will open either the PDF or popup a browser and open the HTML 2199version of the documentation. 2200 2201Notice that on Linux this requires VICE to be properly (and fully) installed, 2202eg with a @samp{make install}. 2203 2204@node File Selector, Disk and tape images, Help, Basics 2205@section Using the file selector 2206 2207In those situations where it is necessary to specify a file name, all 2208of the VICE emulators will pop up a file selector window allowing 2209you to select or specify a file interactively. 2210 2211To the left of the file selector, there is a list of ancestor 2212directories: by clicking on them, you can ascend the directory tree. To 2213the right, there is a list of the files in the current directory; files 2214can be selected by clicking on them. If you click on a directory, that 2215directory becomes the current one; if you click on an ordinary file, it 2216becomes the active selection. 2217 2218At the top, there is a @dfn{directory box}, with the complete path of 2219the current directory, and a @dfn{file name box}, with the name of the 2220currently selected file. At the bottom there are two buttons: ``OK'' 2221confirms the selected file and ``Cancel'' abandons the file selector 2222without cancelling the operation. 2223 2224It is also possible to specify what files you want to show in the file 2225selector by writing an appropriate shell-like pattern in the directory 2226box; e.g., @samp{~/*.[dx]64} will only show files in the home directory whose 2227name ends with either @file{.d64} or with @file{.x64}. 2228 2229 2230@node Disk and tape images, Reset, File Selector, Basics 2231@section Using disk and tape images 2232 2233The emulator is able to emulate disk drives and tape 2234recorders if provided with suitable @dfn{disk images} or @dfn{tape 2235images}. An @dfn{image} is a raw dump of the contents of the media, and 2236must be @dfn{attached} before the emulator can use it. ``Attaching'' a 2237disk or tape image is like ``virtually'' inserting a diskette or a 2238cassette into the disk drive or the tape recorder: once an image is 2239attached, the emulator is able to use it as a storage media. 2240 2241There are five commands that deal with disk and tape images: 2242 2243@itemize @bullet 2244 2245@item 2246Attach Disk Image 2247@item 2248Detach Disk Image 2249@item 2250Attach Tape Image 2251@item 2252Detach Tape Image 2253@item 2254Smart-attach a file 2255 2256@end itemize 2257 2258The first four commands are used to insert and remove the virtual disks 2259and cassettes from the respective units. On the other hand, the 2260last commands tries to guess the type of the image you are attaching 2261from its name and size, and attaches it to the most reasonable device. 2262 2263Supported formats are @code{D64}, @code{G64}, @code{P64} for disk images 2264(devices 8, 9 and 10) and @code{T64} and @code{TAP} for tape images. 2265 2266The ancient @code{X64} format is deprecated and subject for removal. 2267 2268Notice that @code{T64} support is @emph{read-only}, and that the cassette is 2269automatically rewound when you reach its end. For actually emulating tape, the 2270@code{TAP} format is highly recommended. 2271 2272Another important feature is that raw Commodore BASIC binary files and 2273.P00 files can be attached as tapes. As you can autostart a 2274tape image when it is attached (@pxref{Autostart}), this allows you to 2275autostart these particular files as well. 2276 2277You can attach a disk for which you do not have write permissions: when this 2278happens, the 1541 emulator will emulate a write-protected disk. This is 2279also useful if you want to prevent certain disk images from being 2280written to; in the latter case, just remove the write permission for 2281that file, e.g., by doing a @code{chmod a-w}. 2282 2283@menu 2284* Autostart:: Starting a program automagically. 2285* Compressed files:: Dealing with compressed files. 2286* Zipcode and Lynx:: Using Zipcoded ([1-4]!*) and Lynx files. 2287@end menu 2288 2289@node Autostart, Compressed files, Disk and tape images, Disk and tape images 2290@subsection ``Autostarting'' an image 2291 2292If you want to reset the machine and run the first program on a certain 2293image without typing any commands at the Commodore BASIC prompt, you can 2294use the ``Autostart'' button in the file selector window after selecting 2295a proper disk or tape image file. 2296 2297If true drive emulation is turned on, and the @dfn{Handle TDE at Autostart} 2298setting is enabled, true drive emulation will be turned off before running 2299the program and then turned on again after it has been 2300loaded. This way, you get the maximum possible speed while loading the 2301file, but you do not lose compatibility once the program itself is 2302running. This method is not completely safe, because some autostarting methods 2303might cause the true drive emulation not to be turned on again, which is why 2304it is disabled by default. 2305 2306@node Compressed files, Zipcode and Lynx, Autostart, Disk and tape images 2307@subsection Using compressed files 2308 2309It is also possible to attach disk or tape images that have been 2310compressed through various algorithms; compression formats are 2311identified from the file extension. The following formats are supported 2312(the expected file name extension is in parenthesis): 2313 2314@itemize @bullet 2315@item 2316GNU Zip (@code{.gz} or @code{.z}); 2317@item 2318BZip version 2 (@code{.bz2}); 2319@item 2320PkZip (@code{.zip}); 2321@item 2322GNU Zipped TAR archives (@code{.tar.gz}, @code{.tgz}); 2323@item 2324Zoo (@code{.zoo}). 2325@end itemize 2326 2327PkZip, @code{tar.gz}, @code{lha} and @code{zoo} support is 2328@emph{read-only} and always uses the @emph{first} @code{T64} or 2329@code{D64} file in the archive. So archives containing multiple files 2330will always be handled as if they contain only a single file. 2331 2332Windows and DOS don't contain the needful programs to handle 2333compressed archives. Get gzip and unzip for Windows and for DOS at 2334@uref{http://infozip.sourceforge.net}. Don't use pkunzip 2335for DOS, it doesn't work. The programs to use BZip2 archives may be 2336found at @uref{https://sourceware.org/bzip2/}. 2337Just put the programs (unzip.exe, gzip.exe, bzip2.exe) into a directory 2338of your search path (e.g. C:\DOS or C:\WINDOWS\COMMAND; have a look at 2339the PATH variable). 2340 2341@node Zipcode and Lynx, , Compressed files, Disk and tape images 2342@subsection Using Zipcode and Lynx images 2343 2344Since version 0.15, the VICE emulators have been able to attach disks 2345packed with Zipcode or Lynx directly, removing the need to manually 2346convert them into @code{D64} files with @code{c1541}. 2347This is achieved by automatically invoking @code{c1541}, letting it 2348decode the file into a temporary image and attaching the resulting 2349temporary image read-only. For this to work, the directory containing 2350@code{c1541} must be in your @code{PATH}. 2351 2352This uses the @code{-unlynx} and @code{-unzip} options of @code{c1541} 2353(@pxref{c1541 commands and options}); these commands are not very 2354reliable yet, and could fail with certain kinds of Lynx and Zipcode 2355images (for example, they cannot deal with @code{DEL} files properly). 2356So please use them with caution. 2357 2358Lynx files usually come as @file{.lnx} files which are unpacked into 2359single disk images. On the other hand, Zipcode files do not have a 2360particular extension (although @file{.z64} is sometimes used), and 2361represent a disk by means of component files, named as follows: 2362 2363@itemize @bullet 2364@item 2365@file{1!NAME} 2366@item 2367@file{2!NAME} 2368@item 2369@file{3!NAME} 2370@item 2371@file{4!NAME} 2372@end itemize 2373 2374If you attach as a disk image (or smart-attach) any one of these files, 2375the emulator will simply pick up the other three (by examining 2376the name) and then build a disk image using all four. 2377 2378 2379@node Reset, , Disk and tape images, Basics 2380@section Resetting the machine 2381 2382You can reset the emulated machine at any time by using the ``Reset'' 2383command from the file menu. There are two types of reset: 2384 2385@itemize @bullet 2386@item 2387@dfn{soft reset}, which simply resets the CPU and all the other chips; 2388@item 2389@dfn{hard reset}, which also clears up the contents of RAM. 2390@end itemize 2391 2392A @dfn{soft reset} is the same as a hardware reset achieved by pulling 2393the @sc{reset} line down; a @dfn{hard reset} is more like a power 2394on/power off sequence in that it makes sure the whole RAM is cleared. 2395 2396It is possible that a soft reset may not be enough to take the machine 2397to the OS initialization sequence: in such cases, you will have to do a 2398hard reset instead. 2399 2400This is especially the case for the CBM-II emulators. Those machines 2401examine a memory location and if they find a certain "magic" value they 2402only do what you know from the C64 as @code{Run/Stop-Restore}. 2403Therefore, to really reset a CBM-II use hard reset. 2404 2405@node Settings and resources, Machine-specific features, Basics, Top 2406@chapter Settings and resources 2407 2408In the VICE emulators, all the settings are stored in entities known as 2409called @dfn{resources}. Each resource has a name and a value which may 2410be either an integer or a string. Integer values are often used as 2411boolean values with the usual convention of using zero for ``false'' 2412and any other value for ``true''. 2413 2414Resource values can be changed via the the 2415@dfn{options} menu, via command-line options, using monitor commands, or via 2416the @dfn{resource file}. 2417 2418The @dfn{resource file} is a human-readable file containing resource 2419values: On windows systems it is called @file{vice.ini} and is usually stored 2420in the users roaming profile directory (something like 2421@file{C:\Users\}<username>@file{\AppData\Roaming\vice}). Additionally the emulators 2422will look in the program directory at startup, and use @file{vice.ini} if it 2423exists there. On unix systems the resource file is called @file{vicerc} and is 2424stored in the users config directory according to the XDG specification (usually 2425@file{/home/}<username>@file{/.config/vice/}). Additionally the emulators will look 2426if @file{.vicerc} exists in the users home directory, and use that if so. 2427 2428It is possible to dump the current values of the resources 2429into that file or load the values stored into that file as the current 2430values, at any time. This is achieved with the ``Save settings'' and 2431``Load settings'' right menu items. A third menu item, ``Restore 2432Default Settings'', can be used to reset all the values to the factory 2433defaults. 2434 2435A special resource, @code{SaveResourcesOnExit}, if set to a non zero 2436value, causes the emulator to save the current 2437(changed) settings before exiting, and can be toggled with the ``Save 2438settings on exit'' item from the options menu. 2439 2440 2441@menu 2442* Resource files:: Format of resource files. 2443* Resources and command-line:: Specifying settings from the 2444 command-line 2445 2446* Performance settings:: Settings that affect speed of execution. 2447* Video settings:: Settings dealing with the video output. 2448* Keyboard settings:: Settings relative to the keyboard emulation. 2449* Control port settings:: Settings that control what device is emulated on available control ports. 2450* Sound settings:: Settings that control audio playback 2451* Drive settings:: Settings that control disk-drive emulation. 2452* Peripheral settings:: Settings for emulated external devices. 2453* RS232 settings:: Settings for the RS232 emulation. 2454* Monitor settings:: Settings for the built-in monitor. 2455* Misc settings:: Other settings. 2456@end menu 2457 2458@node Resource files, Resources and command-line, Settings and resources, Settings and resources 2459@section Format of resource files 2460 2461A resource file is made up of several sections; sections have the 2462purpose of separating the resources of a certain emulator from the ones 2463of the other emulators. A section starts with the name of an 2464emulator in brackets (e.g., @samp{[C64]}) and ends when another section 2465starts or when the file ends. 2466 2467Every line in a section has the following format: 2468 2469@example 2470RESOURCE=VALUE 2471@end example 2472 2473where @code{RESOURCE} is the name of a resource and @code{VALUE} is its 2474assigned value. Resource names are case-sensitive and resource values 2475are either strings or integers. Strings must start and end with a 2476double quote character (@code{"}), while integers must be given in 2477decimal notation. 2478 2479Here is an example of a stripped-down @file{.vice/vicerc} file: 2480 2481@example 2482[VIC20] 2483SaveResourcesOnExit=0 2484FileSystemDevice8=1 2485FSDevice8ConvertP00=1 2486FSDevice8Dir="/home/ettore/cbm/stuff/vic20p00" 2487FSDevice8SaveP00=1 2488FSDevice8HideCBMFiles=1 2489[C64] 2490SaveResourcesOnExit=1 2491FileSystemDevice8=1 2492FSDevice8ConvertP00=1 2493FSDevice8Dir="/home/ettore/cbm/stuff/c64p00" 2494FSDevice8SaveP00=1 2495FSDevice8HideCBMFiles=1 2496@end example 2497 2498Notice that, when resource values are saved with ``Save settings'', the 2499emulator only modifies its own section, leaving the others unchanged. 2500 2501@node Resources and command-line, Performance settings, Resource files, Settings and resources 2502@section Using command-line options to change resources 2503 2504Resources can also be changed via command-line options. 2505 2506Command-line options always override the defaults from @code{.vice/vicerc}, 2507and their assignments last for the whole session. So, if you specify a 2508certain command-line option that changes a certain resource from its 2509default value and then use ``Save Settings'', the value specified with 2510the command-line option will be saved back to the resource file. 2511 2512Command-line options can begin with with a minus sign (@samp{-}) or 2513with a plus sign (@samp{+}). Options beginning with a minus sign 2514may require an additional parameter, while the ones beginning with the 2515plus sign never require one. 2516 2517Moreover, options beginning with a plus sign always have a counterpart 2518with the same name, but with a minus sign; in that case, the option 2519beginning with a minus sign is used to @emph{enable} a certain 2520feature, while the one beginning with a plus sign is used to 2521@emph{disable} the same feature (this is an X11 convention). For 2522example, @code{-warp} enables warp mode, while @code{+warp} 2523disables it. 2524 2525@c @node FIXME 2526@section Autostart settings 2527 2528@c @node FIXME 2529@subsection Autostart resources 2530 2531@b{All these resources are available for all emulators except vsid.} 2532 2533@table @code 2534 2535@vindex AutostartPrgDiskImage 2536@item AutostartPrgDiskImage 2537String specifying the filename of the disk image used when autostarting a prg file and "copy to D64" is enabled 2538(all emulators except vsid). 2539 2540@vindex AutostartBasicLoad 2541@item AutostartBasicLoad 2542Boolean, if true load to basic start using ,8 when autostarting from disk, else 2543use ,8,1 to load absolute. 2544(all emulators except vsid). 2545 2546@vindex AutostartTapeBasicLoad 2547@item AutostartTapeBasicLoad 2548Boolean, if true load to basic start using ,1 when autostarting from tape, else 2549use ,1,1 to load absolute. 2550(all emulators except vsid). 2551 2552@vindex AutostartRunWithColon 2553@item AutostartRunWithColon 2554Boolean, if true put a colon after the load command when autostarting 2555(all emulators except vsid). 2556 2557@vindex AutostartHandleTrueDriveEmulation 2558@item AutostartHandleTrueDriveEmulation 2559Boolean, if true handle (enable/disable) True Drive Emulation on autostart 2560(all emulators except vsid). This is disabled by default to ensure maximum 2561compatibility. 2562 2563@vindex AutostartWarp 2564@item AutostartWarp 2565Boolean, if true temporarily enable warp mode when autostarting 2566(all emulators except vsid). 2567 2568@vindex AutostartPrgMode 2569@item AutostartPrgMode 2570Integer specifying the autostart mode for prg files 2571(all emulators except vsid). 2572(0: virtual filesystem, 1: inject to RAM, 2: copy to D64) 2573 2574@vindex AutostartDelayRandom 2575@item AutostartDelayRandom 2576Boolean, enables a short (0-10 frames) random delay on autostart. This is added 2577to the @code{AutostartDelay} 2578(all emulators except vsid). 2579 2580@vindex AutostartDelay 2581@item AutostartDelay 2582Integer specifying the delay in seconds required to wait for the kernal reset 2583routine before autostart. (0: use builtin value for standard kernal) 2584When tweaking this value start with 'large' values and then lower it, a value 2585that is too small results in autostart not happening. 2586(all emulators except vsid). 2587(0..1000) 2588 2589@end table 2590 2591@c @node FIXME 2592@subsection Autostart command-line options 2593 2594@b{All these command-line options are available for all emulators except vsid.} 2595 2596@table @code 2597 2598@findex -autostartprgdiskimage 2599@item -autostartprgdiskimage <Name> 2600Set disk image for autostart of PRG files 2601(@code{AutostartPrgDiskImage}) 2602(all emulators except vsid). 2603 2604@findex -basicload, +basicload 2605@item -basicload 2606On autostart from disk, load to BASIC start (without ',1') 2607(@code{AutostartBasicLoad=1}) 2608(all emulators except vsid). 2609@item +basicload 2610On autostart from disk, load with ',1' 2611(@code{AutostartBasicLoad=0}) 2612(all emulators except vsid). 2613 2614@findex -tapebasicload, +tapebasicload 2615@item -tapebasicload 2616On autostart from tape, load to BASIC start (without ',1') 2617(@code{AutostartTapeBasicLoad=1}) 2618(all emulators except vsid). 2619@item +tapebasicload 2620On autostart from tape, load with ',1' 2621(@code{AutostartTapeBasicLoad=0}) 2622(all emulators except vsid). 2623 2624@findex -autostartwithcolon, +autostartwithcolon 2625@item -autostartwithcolon 2626On autostart, use the 'RUN' command with a colon, i.e., 'RUN:' 2627(@code{AutostartRunWithColon=1}). 2628(all emulators except vsid) 2629@item +autostartwithcolon 2630On autostart, do not use the 'RUN' command with a colon; i.e., 'RUN' 2631(@code{AutostartRunWithColon=0}) 2632(all emulators except vsid). 2633 2634@findex -autostart-handle-tde, +autostart-handle-tde 2635@item -autostart-handle-tde 2636@itemx +autostart-handle-tde 2637Handle/Do not handle True Drive Emulation on autostart 2638(@code{AutostartHandleTrueDriveEmulation=1}, @code{AutostartHandleTrueDriveEmulation=0}) 2639(all emulators except vsid). 2640 2641@findex -autostart-warp, +autostart-warp 2642@item -autostart-warp 2643@itemx +autostart-warp 2644Enable/disable warp mode during autostart 2645(@code{AutostartWarp=1}, @code{AutostartWarp=0}) 2646(all emulators except vsid). 2647 2648@findex -autostartprgmode 2649@item -autostartprgmode <Mode> 2650Set autostart mode for PRG files 2651(@code{AutostartPrgMode}) 2652(all emulators except vsid). 2653(0: virtual filesystem, 1: inject to RAM, 2: copy to D64) 2654 2655@findex -autostart-delay-random, +autostart-delay-random 2656@item -autostart-delay-random 2657@itemx +autostart-delay-random 2658Enable/disable random delay on autostart 2659(@code{AutostartDelayRandom}) 2660(all emulators except vsid). 2661 2662@findex -autostart-delay 2663@item -autostart-delay <seconds> 2664Set initial autostart delay in seconds for the kernal reset 2665routine before autostart. (0: use builtin value for standard kernal). 2666When tweaking this value start with 'large' values and then lower it, a value 2667that is too small results in autostart not happening. 2668(@code{AutostartDelay}) 2669(all emulators except vsid). 2670(0..1000) 2671 2672@end table 2673 2674@node Performance settings, Video settings, Resources and command-line, Settings and resources 2675@section Performance settings 2676 2677@cindex Limiting emulation speed 2678It is possible to control the emulation speed by using the ``Maximum 2679speed'' item in the speed setting. The default setting is 2680@code{100}, which causes the emulation to never run faster than the real 2681machine. A higher value allows the emulator to run faster, a lower one 2682may force it to run slower. A specific FPS may also be targeted. 2683 2684@cindex Warp speed mode 2685Moreover, a special @dfn{warp speed} mode is provided and can be toggled 2686with the ``Enable Warp Mode'' menu item. If this mode is enabled, it 2687will cause the emulator to disable any speed limit, turn sound emulation 2688off and use a 1/10 refresh rate, so that it will run at the maximum 2689possible speed. 2690 2691@menu 2692* Performance resources:: 2693* Performance options:: 2694@end menu 2695 2696@node Performance resources, Performance options, Performance settings, Performance settings 2697@subsection Performance resources 2698 2699@table @code 2700 2701@vindex Speed 2702@item Speed 2703Integer specifying the maximum relative speed, as a percentage. @code{0} 2704stands for ``no limit''. 2705 2706@vindex WarpMode 2707@item WarpMode 2708Booolean specifying whether ``warp mode'' is turned on or not. 2709 2710@end table 2711 2712 2713@node Performance options, , Performance resources, Performance settings 2714@subsection Performance command-line options 2715 2716@table @code 2717 2718@findex -speed 2719@item -speed <value> 2720A positive <value> specifies the maximum speed as a percentage. A negative 2721<value> results in a target FPS of 0 - <value> 2722(@code{Speed}). 2723 2724@findex -warp, +warp 2725@item -warp 2726@itemx +warp 2727Enable/Disable warp mode 2728(@code{WarpMode=1}, @code{WarpMode=0}). 2729 2730@end table 2731 2732 2733@node Video settings, Keyboard settings, Performance settings, Settings and resources 2734@section Video settings 2735 2736The following right-button menu items control the video output. 2737On emulators that include two video chips (like @code{x128}) 2738all options exist twice, once for each chip. 2739 2740@itemize @bullet 2741 2742@cindex Video cache 2743@item 2744``Video Cache'' enables a video cache that can speed up the emulation 2745when little graphics activity is going on; it is especially useful when 2746you run the emulator on a networked X terminal as it can reduce the 2747network bandwidth required. However, this setting can actually make the 2748emulator slower when there is little graphics activity and the amount of 2749work needed to maintain the cache is greater than the amount of work that 2750would be wasted by not using it (if any). 2751 2752@cindex Double-size mode 2753@item 2754``Double Size'' toggles @dfn{double-size mode}, which makes the 2755emulation window twice as big. It also selects a more accurate CRT emulation 2756renderer with scanlines. 2757 2758@cindex Double-scan mode. 2759@item 2760``Double Scan'' toggles @dfn{double-scan mode}, which causes the 2761emulator to draw only odd lines when running in double-size mode (this 2762saves some CPU time and also makes the emulation window look more like 2763an old monitor). 2764 2765@end itemize 2766 2767 2768@menu 2769* Video resources:: 2770@end menu 2771 2772@node Video resources, , Video settings, Video settings 2773@subsection Video resources 2774 2775The following resources affect the screen emulation. 2776 2777@table @code 2778 2779@vindex HwScalePossible 2780@item HwScalePossible 2781Boolean that indicates whether hardware scaling is possible or not. 2782 2783@vindex Speed 2784@item Speed 2785Integer specifying the maximum relative speed, as a percentage. @code{0} 2786stands for ``no limit''. 2787 2788@vindex WarpMode 2789@item WarpMode 2790Boolean specifying whether ``warp mode'' is turned on or not. 2791 2792@vindex FullscreenEnable 2793@item FullscreenEnable 2794Boolean specifying whether ``fullscreen'' is turned on at startup or not. 2795 2796@end table 2797 2798@c FIXME: @node 2799@subsection Video command line options 2800 2801@table @code 2802 2803@findex -hwscalepossible, +hwscalepossible 2804@item -hwscalepossible 2805@itemx +hwscalepossible 2806Enable/Disable the possibility of hardware scaling 2807@code{HwScalePossible=1} or @code{HwScalePossible=1}). 2808 2809@end table 2810 2811@node Keyboard settings, Control port settings, Video settings, Settings and resources 2812@section Keyboard settings 2813 2814It is possible to specify whether the ``positional'' or ``symbolic'' 2815keyboard mapping should be used with the ``Keyboard mapping type'' 2816submenu (@pxref{Keyboard emulation} for an explanation of positional 2817and symbolic mappings). 2818 2819The keyboard settings also allows you to: 2820 2821@itemize @bullet 2822@item 2823Load custom-made positional and symbolic keymap files 2824(``Set symbolic keymap file'' and ``Set positional keymap file''). 2825@item 2826Dump the current keymap to a user-defined keymap file (``Dump to keymap 2827file''). 2828@end itemize 2829 2830 2831@menu 2832* Keyboard resources:: 2833* Keyboard options:: 2834@end menu 2835 2836@node Keyboard resources, Keyboard options, Keyboard settings, Keyboard settings 2837@subsection Keyboard resources 2838 2839@table @code 2840 2841@vindex KeymapIndex 2842@item KeymapIndex 2843Integer identifying which keymap is being used. 2844(0: symbolic, 1: positional, 2: symbolic (user), 3: positional (user)). 2845 2846@vindex KeymapSymFile 2847@item KeymapSymFile 2848String specifying the name of the keymap file for the symbolic mapping 2849(@pxref{Keyboard emulation} 2850(this will be set indirectly by changing @code{KeymapIndex}, 2851@code{KeyboardMapping} or @code{KeyboardType}). 2852 2853@vindex KeymapPosFile 2854@item KeymapPosFile 2855String specifying the name of the keymap file for the positional mapping 2856(@pxref{Keyboard emulation} 2857(this will be set indirectly by changing @code{KeymapIndex}, 2858@code{KeyboardMapping} or @code{KeyboardType}). 2859 2860@vindex KeymapUserSymFile 2861@item KeymapUserSymFile 2862String specifying the name of the user keymap file for symbolic mapping 2863(@pxref{Keyboard emulation} 2864 2865@vindex KeymapUserPosFile 2866@item KeymapUserPosFile 2867String specifying the name of the user keymap file for positional mapping 2868(@pxref{Keyboard emulation} 2869 2870@vindex KeyboardMapping 2871@item KeyboardMapping 2872Integer specifying the keyboard layout of the host. 2873(0: American 1: British 2: German 3: Danish 4: Norwegian 5: Finnish 6: Italian). 2874 2875@vindex KeyboardType 2876@item KeyboardType 2877Integer specifying the emulated type of keyboard. 2878(machine specific, currently always 0 except for xpet: 0: Business (us) 28791: Business (uk) 2: Business (de) 3: Business (jp) 4: Graphics (us)). 2880 2881@end table 2882 2883 2884@node Keyboard options, , Keyboard resources, Keyboard settings 2885@subsection Keyboard command-line options 2886 2887@table @code 2888 2889@findex -keymap 2890@item -keymap <number> 2891Specifies which keymap is being used 2892(@code{KeymapIndex} 28930: symbolic, 1: positional, 2: symbolic (user), 3: positional (user)). 2894 2895@findex -symkeymap 2896@item -symkeymap <Name> 2897Specify filename of the symbolic user keymap file 2898(@code{KeymapUserSymFile}). 2899 2900@findex -poskeymap 2901@item -poskeymap <Name> 2902Specify filename of the positional user keymap file 2903(@code{KeymapUserPosFile}). 2904 2905@findex -keyboardmapping 2906@item -keyboardmapping <number> 2907Specifies the keyboard layout of the host 2908(@code{KeyboardMapping} 29090: American 1: British 2: German 3: Danish 4: Norwegian 5: Finnish 6: Italian). 2910 2911@findex -keyboardtype 2912@item -keyboardtype <number> 2913Specifies the emulated type of keyboard 2914(@code{KeyboardType} 2915machine specific, currently always 0 except for xpet: 0: Business (us) 29161: Business (uk) 2: Business (de) 3: Business (jp) 4: Graphics (us)). 2917 2918 2919@end table 2920 2921@node Control port settings, Sound settings, Keyboard settings, Settings and resources 2922 2923The control port settings submenu allows you to select which control 2924port device is connected to a control port. 2925 2926@menu 2927* Control port resources:: 2928* Control port options:: 2929@end menu 2930 2931@node Control port resources, Control port options, Control port settings, Control port settings 2932@subsection Control port resources 2933 2934@table @code 2935 2936@vindex JoyPort1Device 2937@item JoyPort1Device 2938Set the device attached to: 2939control port 1 (x64, x64sc, x64dtv, xscpu64, x128, xcbm5x0, xplus4) 2940control port (xvic). 2941(x64, x64sc, xscpu, x128, xcbm5x0, xvic: 0: None, 1: Joystick, 2: Paddles, 3: Mouse (1351), 4: Mouse (NEOS), 5: Mouse (Amiga), 6: Mouse (CX-22), 7: Mouse (Atari ST), 8: Mouse (SmartMouse), 9: Mouse (Micromys), 10: KoalaPad, 11: Light Pen (up trigger), 12: Light Pen (left trigger), 13: Datel Light Pen, 14: Magnum Light Phaser, 15: Stack Light Rifle, 16: Inkwell Light Pen, 17: Sampler (2bit)) 2942(x64dtv, xplus4: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 2943 2944@vindex JoyPort2Device 2945@item JoyPort2Device 2946Set the device attached to: 2947control port 2 (x64, x64sc, x64dtv, xscpu64, x128, xcbm5x0, xplus4) 2948(x64, x64sc, xscpu, x128, xcbm5x0: 0: None, 1: Joystick, 2: Paddles, 3: Mouse (1351), 4: Mouse (NEOS), 5: Mouse (Amiga), 6: Mouse (CX-22), 7: Mouse (Atari ST), 8: Mouse (SmartMouse), 9: Mouse (Micromys), 10: KoalaPad, 17: Sampler (2bit)) 2949(x64dtv, xplus4: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 2950 2951@vindex JoyPort3Device 2952@item JoyPort3Device 2953Set the device attached to: 2954userport joystick adapter port 1 (x64, x64sc, xscpu64, x128, xcbm2, xpet, xvic) 2955userport joystick adapter port (x64dtv) 2956sidcart control port (xplus4). 2957(x64, x64sc, x64dtv, xscpu, x128, xcbm2, xpet, xvic: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 2958(xplus4: 0: None, 1: Joystick, 2: Paddles, 3: Mouse (1351), 4: Mouse (NEOS), 5: Mouse (Amiga), 6: Mouse (CX-22), 7: Mouse (Atari ST), 8: Mouse (SmartMouse), 9: Mouse (Micromys), 10: KoalaPad, 17: Sampler (2bit)) 2959 2960@vindex JoyPort4Device 2961@item JoyPort4Device 2962Set the device attached to: 2963userport joystick adapter port 2 (x64, x64sc, xscpu64, x128, xcbm2, xpet, xvic) 2964(x64, x64sc, xscpu, x128, xcbm2, xpet, xvic: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 2965 2966@vindex JoyPort5Device 2967@item JoyPort5Device 2968Set the device attached to: 2969SidCart on the Plus4 (xplus4) 2970 2971@vindex BBRTCSave 2972@item BBRTCSave 2973Enable saving of the battery-backed real time clock data. 2974 2975@end table 2976 2977 2978@node Control port options, , Control port resources, Control port settings 2979@subsection Control port command-line options 2980 2981@table @code 2982 2983@findex -controlport1device 2984@item -controlport1device <device> 2985Set the device attached to: 2986control port 1 (x64, x64sc, x64dtv, xscpu, x128, xcbm5x0, xplus4) 2987control port (xvic) 2988(@code{JoyPort1Device}). 2989(x64, x64sc, xscpu, x128, xcbm5x0, xvic: 0: None, 1: Joystick, 2: Paddles, 3: Mouse (1351), 4: Mouse (NEOS), 5: Mouse (Amiga), 6: Mouse (CX-22), 7: Mouse (Atari ST), 8: Mouse (SmartMouse), 9: Mouse (Micromys), 10: KoalaPad, 11: Light Pen (up trigger), 12: Light Pen (left trigger), 13: Datel Light Pen, 14: Magnum Light Phaser, 15: Stack Light Rifle, 16: Inkwell Light Pen, 17: Sampler (2bit)) 2990(x64dtv, xplus4: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 2991 2992@findex -controlport2device 2993@item -controlport2device <device> 2994Set the device attached to: 2995control port 2 (x64, x64sc, x64dtv, xscpu, x128, xcbm5x0, xplus4) 2996(@code{JoyPort2Device}). 2997(x64, x64sc, xscpu, x128, xcbm5x0: 0: None, 1: Joystick, 2: Paddles, 3: Mouse (1351), 4: Mouse (NEOS), 5: Mouse (Amiga), 6: Mouse (CX-22), 7: Mouse (Atari ST), 8: Mouse (SmartMouse), 9: Mouse (Micromys), 10: KoalaPad, 17: Sampler (2bit)) 2998(x64dtv, xplus4: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 2999 3000@findex -controlport3device 3001@item -controlport3device <device> 3002Set the device attached to: 3003userport joystick adapter port 1 (x64, x64sc, xscpu, x128, xcbm2, xpet, xvic) 3004userport joystick adapter port (x64dtv) 3005sidcart control port (xplus4) 3006(@code{JoyPort3Device}). 3007(x64, x64sc, x64dtv, xscpu, x128, xcbm2, xpet, xvic: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 3008(xplus4: 0: None, 1: Joystick, 2: Paddles, 3: Mouse (1351), 4: Mouse (NEOS), 5: Mouse (Amiga), 6: Mouse (CX-22), 7: Mouse (Atari ST), 8: Mouse (SmartMouse), 9: Mouse (Micromys), 10: KoalaPad, 17: Sampler (2bit)) 3009 3010@findex -controlport4device 3011@item -controlport4device <device> 3012Set the device attached to: 3013userport joystick adapter port 2 (x64, x64sc, xscpu, x128, xcbm2, xpet, xvic) 3014(@code{JoyPort4Device}). 3015(x64, x64sc, xscpu, x128, xcbm2, xpet, xvic: 0: None, 1: Joystick, 6: Mouse (CX-22), 17: Sampler (2bit)) 3016 3017@findex -controlport5device 3018@item -controlport5device <device> 3019Set the device attached to: 3020SID cart joystick port (xplus4) 3021(@code{JoyPort5Device}). 3022(xplus4: 0: None, 1: Joystick, 2: Paddles, 3: Mouse (1351), 4: Mouse (NEOS), 5: Mouse (Amiga), 6: Mouse (CX-22), 7: Mouse (Atari ST), 8: Mouse (SmartMouse), 9: Mouse (Micromys), 10: KoalaPad, 17: Sampler (2bit), 18: Sampler (4bit), 19: BBRTC, 20: Paperclip64 dongle, 21: Coplin Keypad, 22: Cardco Cardkey 1 keypad, 23: Atari CX85 keypad, 24: RushWare Keypad, 25: Atari CX21 keypad) 3023 3024@findex -bbrtcsave, +bbrtcsave 3025@item -bbrtcsave 3026@itemx +bbrtcsave 3027Enable/Disable saving of the battery-backed real time clock data 3028(@code{BBRTCSave}). 3029 3030@end table 3031 3032@c @node FIXME 3033@section Joystick settings 3034 3035@c @node FIXME 3036@subsection Joystick resources 3037 3038@table @code 3039 3040@vindex JoyDevice1 3041@vindex JoyDevice2 3042@vindex JoyDevice3 3043@vindex JoyDevice4 3044@vindex JoyDevice5 3045@item JoyDevice1 3046@itemx JoyDevice2 3047@itemx JoyDevice3 3048@itemx JoyDevice4 3049@itemx JoyDevice5 3050Integer specifying which joystick device the emulator should use for 3051joystick emulation for ports 1 - 5, respectively. 3052(0=None, 1=Joystick 1, 2=Joystick 2, 4=Numpad, 8=Keyset 1, 16=Keyset 2 on OS/2) 3053(0=None, 1=Numpad, 2=Keyset 1, 3=Keyset 2, 4=HID joystick 0, 5=HID joystick 1 on Mac OS X) 3054The available joysticks might differ depending on operating system and 3055joystick support in the OS (Linux joystick module must be 3056available for example). 3057 3058@vindex JoyOpposite 3059@item JoyOpposite 3060Boolean, if true allow (usually impossible) bitcombinations for opposite directions. 3061(all emulators except vsid) 3062 3063@vindex UserportJoy 3064@item UserportJoy 3065Boolean to enable/disable extra joysticks 3066(all emulators except xcbm5x0 and vsid). 3067 3068@vindex UserportJoyType 3069@item UserportJoyType 3070Integer specifying the type of adapter used for the extra joysticks 3071(all emulators except xcbm5x0 and vsid). 3072(0: Classical Games/Protovision, 1: PET, 2: Hummer, 3: OEM, 4: Digital Excess/Hitmen, 5: Kingsoft, 6: Starbyte) 30734, 5 and 6 are x64, x64sc, xscpu64 and x128 only. 3074 3075@vindex Mouse 3076@item Mouse 3077Boolean, enables mouse emulation 3078 3079@vindex SmartMouseRTCSave 3080@item SmartMouseRTCSave 3081Boolean, specified whether to save real time clock data for the SmartMouse 3082 3083 3084@vindex KeySet1NorthWest 3085@vindex KeySet1North 3086@vindex KeySet1NorthEast 3087@vindex KeySet1East 3088@vindex KeySet1SouthEast 3089@vindex KeySet1South 3090@vindex KeySet1SouthWest 3091@vindex KeySet1West 3092@vindex KeySet1Fire 3093@vindex KeySet1Fire2 3094@vindex KeySet1Fire3 3095@item KeySet1NorthWest 3096@itemx KeySet1North 3097@itemx KeySet1NorthEast 3098@itemx KeySet1East 3099@itemx KeySet1SouthEast 3100@itemx KeySet1South 3101@itemx KeySet1SouthWest 3102@itemx KeySet1West 3103@itemx KeySet1Fire 3104@itemx KeySet1Fire2 3105@itemx KeySet1Fire3 3106Integers specifying the keycodes for keyset 1 3107(all emulators except vsid). 3108 3109@vindex KeySet2NorthWest 3110@vindex KeySet2North 3111@vindex KeySet2NorthEast 3112@vindex KeySet2East 3113@vindex KeySet2SouthEast 3114@vindex KeySet2South 3115@vindex KeySet2SouthWest 3116@vindex KeySet2West 3117@vindex KeySet2Fire 3118@vindex KeySet2Fire2 3119@vindex KeySet2Fire3 3120@item KeySet2NorthWest 3121@itemx KeySet2North 3122@itemx KeySet2NorthEast 3123@itemx KeySet2East 3124@itemx KeySet2SouthEast 3125@itemx KeySet2South 3126@itemx KeySet2SouthWest 3127@itemx KeySet2West 3128@itemx KeySet2Fire 3129@itemx KeySet2Fire2 3130@itemx KeySet2Fire3 3131Integers specifying the keycodes for keyset 2 3132(all emulators except vsid). 3133 3134@vindex KeySetEnable 3135@item KeySetEnable 3136Boolean that specifies whether user defined keysets are enabled 3137(all emulators except vsid). 3138 3139@vindex KbdbufDelay 3140@item KbdbufDelay 3141Integer specifying the additional keyboard delay. 3142(0: use default) 3143 3144@end table 3145 3146@c @node FIXME 3147@subsection Joystick command-line options 3148 3149@table @code 3150 3151@findex -joydev1 3152@findex -joydev2 3153@item -joydev1 <range> 3154@itemx -joydev2 <range> 3155Set the device for joystick emulation of port 1 and 2, respectively. 3156(@code{JoyDevice1}, @code{JoyDevice2}). 3157The range for OS/2 is, valid numbers in the range are 0, 1, 2, 4, 8 and 16. 3158@findex -extrajoydev1 3159@findex -extrajoydev2 3160@findex -extrajoydev3 3161@item -extrajoydev1 <0-8> 3162@itemx -extrajoydev2 <0-8> 3163@itemx -extrajoydev3 <0-8> 3164Set device for extra joystick port 1, 2 and 3. 3165 3166@findex -joyopposite, +joyopposite 3167@item -joyopposite 3168@itemx +joyopposite 3169Enable/disable opposite joystick directions 3170(@code{JoyOpposite=1}, @code{JoyOpposite=0}). 3171(all emulators except vsid) 3172 3173@findex -userportjoy, +userportjoy 3174@item -userportjoy 3175@itemx +userportjoy 3176Enable/disable extra joystick(s) 3177(@code{UserportJoy=1}, @code{UserportJoy=0}). 3178(all emulators except xcbm5x0 and vsid). 3179 3180@findex -userportjoytype 3181@item -userportjoytype <Type> 3182Set extra joystick type 3183(@code{UserportJoyType}) 3184(all emulators except xcbm5x0 and vsid). 3185(0: Classical Games/Protovision, 1: PET, 2: Hummer, 3: OEM, 4: Digital Excess/Hitmen, 5: Kingsoft, 6: Starbyte) 31864, 5 and 6 are x64, x64sc, xscpu64 and x128 only. 3187 3188@findex -mouse, +mouse 3189@item -mouse 3190@itemx +mouse 3191Enable/Disable mouse grab 3192 3193@findex -smartmousertcsave, +smartmousertcsave 3194@item -smartmousertcsave 3195@itemx +smartmousertcsave 3196Enable/Disable saving of the real time clock data for the SmartMouse 3197 3198@findex -keyset, +keyset 3199@item -keyset 3200@itemx +keyset 3201Enable/disable user defined keyset 3202(@code{KeySetEnable=1}, @code{KeySetEnable=0}) 3203(all emulators except vsid). 3204 3205@findex -keybuf-delay 3206@item -keybuf-delay <value> 3207Set additional keyboard buffer delay 3208(@code{KbdbufDelay}). 3209(0: use default) 3210 3211@end table 3212 3213@node Sound settings, Drive settings, Control port settings, Settings and resources 3214@section Sound settings 3215 3216The following menu items control sound output: 3217 3218@itemize @bullet 3219 3220@cindex Turning sound playback on/off 3221@item 3222``Enable sound playback'' turns sound emulation on and off. 3223 3224@cindex Sound syncronization 3225@cindex Sound speed adjustment 3226@item 3227``Sound synchronization'' specifies the method for syncronizing the 3228sound playback. Possible settings are: 3229@itemize @bullet 3230@item 3231``Flexible'', i.e., the audio renderer flexibly adds/removes samples to 3232the output to smoothly adapt the playback to slight changes in the speed 3233of the emulator. 3234@item 3235``Adjusting'' works like ``flexible'', but supports bigger differences 3236in speed. For example, if the emulation speed drops down from from 100% 3237to 50%, audio slows down by the same amount too. 3238@item 3239``Exact'', instead, makes the audio renderer output always the same 3240sounds you would hear from the real thing, without trying to adapt the 3241ratio; to compensate the tolerances in speed, some extra frames will be 3242skipped or added. 3243@end itemize 3244 3245@cindex Sample rate 3246@item 3247``Sample rate'' specifies the sampling frequency, ranging from 8000 to 324848000 Hz (not all the sound cards and/or sound drivers can support all 3249the frequencies, so actually the nearest candidate will be chosen). 3250 3251@cindex Audio buffer size 3252@cindex Sound buffer size 3253@item 3254``Buffer size'' specifies the size of the audio buffer; the bigger the 3255buffer, the longer the delay with which sounds are played. You should 3256pick the smallest value your machine can handle without problems. 3257 3258@cindex Sound suspend time 3259@item 3260``Sound suspend time'', will cause the audio playback to pause for the 3261specified number of seconds whenever some clicking happens. If ``Keep 3262going'' is selected, no pausing is done. 3263 3264The following menu items control sound input: 3265 3266@cindex Sampler Device 3267@item 3268``Sampler Device'' specifies the host device/method used for sampling/sound input, 3269currently portaudio (if linked in) and file methods are supported. 3270 3271@cindex Sampler Gain 3272@item 3273``Sampler Gain'' specifies the amount of gain (increase the input volume if above 100 3274or decrease the input volume if below 100) for the input of the sampler device. 3275 3276@cindex Sampler File 3277@item 3278``Sampler File'' specifies the name of the file to be uses as an input source for 3279the 'file' method/device. 3280 3281@end itemize 3282 3283@menu 3284* Sound resources:: 3285* Sound options:: 3286@end menu 3287 3288@node Sound resources, Sound options, Sound settings, Sound settings 3289@subsection Sound resources 3290 3291@table @code 3292 3293@vindex Sound 3294@item Sound 3295Boolean specifying whether audio emulation is turned on. 3296 3297@vindex SoundSpeedAdjustment 3298@item SoundSpeedAdjustment 3299Integer specifying what speed adjustment method the audio renderer should use. 3300(0: flexible, 1: adjusting, 2: exact) 3301 3302@vindex SoundSampleRate 3303@item SoundSampleRate 3304Integer specifying the sampling frequency in Hz 3305(not all the sound cards and/or sound drivers can support all the 3306frequencies, so actually the nearest candidate will be chosen). 3307(8000..48000) 3308 3309@vindex SoundBufferSize 3310@item SoundBufferSize 3311Integer specifying the size of the audio buffer, in milliseconds. 3312 3313@vindex SoundSuspendTime 3314@item SoundSuspendTime 3315Integer specifying the pause interval when audio underflows (``clicks'') 3316happen. @code{0} means no pause is done. 3317 3318@vindex SoundDeviceName 3319@item SoundDeviceName 3320String specifying the audio driver. 3321 3322Implemented drivers are: 3323 3324@itemize @bullet 3325@item 3326@code{ahi}, for the Amiga/Morphos/Aros sound driver. 3327@item 3328@code{aix}, for the IBM AIX sound driver. 3329@item 3330@code{allegro}, for the DOS Allegro sound driver. 3331@item 3332@code{alsa}, for the linux ALSA sound driver. 3333@item 3334@code{arts}, for the *nix ARTS sound driver. 3335@item 3336@code{beos}, for the BeOS/Zeta/Haiku sound driver. 3337@item 3338@code{bsp}, for the BeOS/Zeta/Haiku BeOS Media Kit sound driver. 3339@item 3340@code{coreaudio}, for the Mac OS X sound driver (@code{SoundDeviceArg} 3341specifies the audio device, default system output by default). 3342@item 3343@code{dart}, for the OS/2 sound driver. 3344@item 3345@code{dummy}, fully emulating the sound output chip(s), but not actually playing samples. 3346@item 3347@code{dx}, for the Windows Direct-X sound driver. 3348@item 3349@code{hpux}, for the HP-UX audio device (unfinished; 3350@code{SoundDeviceArg} specifies the audio device, @file{/dev/audio} by 3351default). 3352@item 3353@code{midas}, for the DOS Midas sound driver. 3354@item 3355@code{pulse}, for the Pulseaudio sound driver. 3356@item 3357@code{sdl}, for the Simple DirectMedia Layer audio driver. 3358@item 3359@code{sgi}, for the Silicon Graphics audio device (@code{SoundDeviceArg} 3360specifies the audio device, @file{/dev/audio} by default); 3361@item 3362@code{speed}, like @code{dummy} but also calculating samples (mainly 3363used to evaluate the speed of the sample generator); 3364@item 3365@code{sun}, for the Solaris and NetBDS audio device (unfinished; 3366@code{SoundDeviceArg} specifies the audio device, @file{/dev/audio} by 3367default). 3368@item 3369@code{uss}, for the Linux/FreeBSD Universal Sound System driver 3370(@code{SoundDeviceArg} specifies the audio device, @file{/dev/dsp} by 3371default); 3372@item 3373@code{wmm}, for the Windows Multimedia Waveout sound device. 3374@end itemize 3375 3376These drivers will actually be present only if the VICE configuration 3377script detected the corresponding development support at the time of compilation. 3378 3379@vindex SoundDeviceArg 3380@item SoundDeviceArg 3381String specifying an additional parameter for the audio driver (see 3382@code{SoundDeviceName}). 3383 3384@vindex SoundRecordDeviceName 3385@item SoundRecordDeviceName 3386String specifying the driver used for sound recording. 3387 3388Implemented drivers are: 3389 3390@itemize @bullet 3391@item 3392@code{aiff}, for the Apple Interchange File Format 16bit sound recorder driver. 3393@item 3394@code{dump}, writing all the write accesses to the registers to a file 3395(specified by @code{SoundDeviceArg}, default value is 3396@code{vicesnd.sid}); 3397@item 3398@code{fs}, writing samples to a file (specified by 3399@code{SoundDeviceArg}; default is @file{vicesnd.raw}); 3400@code{iff}, for the Amiga Interchange File Format (8SVX) 8bit sound recorder driver. 3401@item 3402@code{mp3}, for the MP3 sound recorder driver. 3403@item 3404@code{flac}, for the FLAC sound recorder driver. 3405@item 3406@code{ogg}, for the ogg/vorbis sound recorder driver. 3407@item 3408@code{voc}, for the Creative Voice (VOC) sound recorder driver. 3409@item 3410@code{wav}, for the RIFF/WAV sound recorder driver. 3411@end itemize 3412 3413These drivers will actually be present only if the VICE configuration 3414script detected the corresponding development support at the time of compilation. 3415 3416@vindex SoundRecordDeviceArg 3417@item SoundRecordDeviceArg 3418String specifying additional arguments for sound recording. 3419 3420@vindex SoundFragmentSize 3421@item SoundFragmentSize 3422Integer specifying the fragment size. 3423(0: very small, 1: small, 2: medium, 3: large, 4: very large) 3424 3425@vindex SoundVolume 3426@item SoundVolume 3427Integer specifying the master volume in percent. 3428(0..100) 3429 3430@vindex SoundOutput 3431@item SoundOutput 3432Integer specifying the type of sound output. Output is selectable between 'system' 3433(system decides to use mono or stereo output based on the presence of a stereo sid), 3434'always mono' (output is always mono, stereo streams are mixed into a mono stream) 3435or 'always stereo' (output is always stereo, mono streams are multiplexed to a stereo 3436stream). 3437(0: system, 1: mono, 2: stereo) 3438 3439@vindex SamplerDevice 3440@item SamplerDevice 3441Integer specifying the device/method to be used for sound input. 3442(0: sample file device, 1: PortAudio device) 3443 3444@vindex SamplerGain 3445@item SamplerGain 3446Integer specifying the gain to be used for sound input. 3447(>100 increase input volume, <100: decrease input volume) 3448 3449@vindex SampleName 3450@item SampleName 3451String specifying the name of the file/sample to be used as the input 3452source for the 'file' sampler device. 3453 3454@end table 3455 3456@node Sound options, , Sound resources, Sound settings 3457@subsection Sound command-line options 3458 3459@table @code 3460 3461@findex -sound, +sound 3462@item -sound 3463@itemx +sound 3464Enable/disable sound emulation 3465(@code{Sound=1}, @code{Sound=0}). 3466 3467@findex -soundrate 3468@item -soundrate <value> 3469Specify the sound playback sample rate 3470(@code{SoundSampleRate}). 3471(8000..48000) 3472 3473@findex -soundoutput 3474@item -soundoutput <output mode> 3475Sound output mode 3476(@code{SoundOutput}). 3477(0: system decides mono/stereo, 1: always mono, 2: always stereo) 3478 3479@findex -soundbufsize 3480@item -soundbufsize <value> 3481Specify the size of the audio buffer in milliseconds 3482(@code{SoundBufferSize}). 3483 3484@findex -soundfragsize 3485@item -soundfragsize <value> 3486Set sound fragment size 3487(@code{SoundFragmentSize}). 3488(0: very small, 1: small, 2: medium, 3: large, 4: very large) 3489 3490@findex -sounddev 3491@item -sounddev <Name> 3492Specifies the name of the audio device 3493(@code{SoundDeviceName}). 3494(ahi, aix, allegro, alsa, arts, beos, bsp, coreaudio, dart, dummy, dx, hpux, midas, pulse, sdl, sgi, sun, uss, wmm) 3495 3496@findex -soundarg 3497@item -soundarg <args> 3498Specifies an additional parameter for the audio device 3499(@code{SoundDeviceArg}). 3500 3501@findex -soundrecdev 3502@item -soundrecdev <name> 3503Specify recording sound driver 3504(@code{SoundRecordDeviceName}). 3505(aiff, dump, fs, iff, mp3, flac, ogg, speed, voc, wav) 3506 3507@findex -soundrecarg 3508@item -soundrecarg <args> 3509Specify initialization parameters for recording sound driver 3510(@code{SoundRecordDeviceArg}). 3511 3512@findex -soundsuspend 3513@item -soundsuspend <seconds> 3514Specify the pause interval when audio underflows (clicks) happen. 0 means no pause is done 3515(@code{SoundSuspendTime}). 3516 3517@findex -soundvolume 3518@item -soundvolume <volume> 3519Specify the sound volume 3520(@code{SoundVolume}). 3521(0..100) 3522 3523@findex -samplerdev 3524@item -samplerdev <device number> 3525Specify the device to use for audio input 3526(@code{SamplerDevice}). 3527(0: file device, 1: portaudio device) 3528 3529@findex -samplergain 3530@item -samplergain <percent> 3531Specify the amount of gain (volume increase/decrease) for the audio input device 3532(@code{SamplerGain}). 3533(0..200) 3534 3535@findex -samplename 3536@item -samplename <name> 3537Specify the name of the file to use for the 'file' audio input device 3538(@code{SampleFile}). 3539 3540@end table 3541 3542@c @node FIXME 3543@section Tape settings 3544 3545These settings are used to control the hardware-level emulation of the Tape 3546drive. 3547 3548@c @node FIXME 3549@subsection Tape resources 3550 3551@table @code 3552 3553@vindex Datasette 3554@item Datasette 3555Boolean specifying whether to emulate the datasette. 3556 3557@vindex DatasetteResetWithCPU 3558@item DatasetteResetWithCPU 3559Boolean specifying whether to reset (rewind) the tape when resetting the CPU. 3560 3561@vindex DatasetteZeroGapDelay 3562@item DatasetteZeroGapDelay 3563Integer specifying the delay in cycles for a zero in the tap. 3564 3565@vindex DatasetteSpeedTuning 3566@item DatasetteSpeedTuning 3567Integer specifying the number of cycles added to each gap in the tap. 3568 3569@vindex DatasetteTapeWobble 3570@item DatasetteTapeWobble 3571Integer specifying the maximum random number of cycles added to each gap in the tap. 3572 3573@vindex DatasetteSound 3574@item DatasetteSound 3575Boolean specifying whether to produce audible sound when playing a tape on the datasette 3576 3577@vindex DatasetteSoundVolume 3578@item DatasetteSoundVolume 3579Integer specifying the volume of the tape sound. Meaningful values are in the range 1-32767 3580@end table 3581 3582@subsection Tape command-line options 3583 3584@table @code 3585 3586@findex -datasette, +datasette 3587@item -datasette 3588@itemx +datasette 3589Enable/disable datasette emulation 3590(@code{Datasette=1}, @code{Datasette=0}). 3591 3592@findex -dsresetwithcpu, +dsresetwithcpu 3593@item -dsresetwithcpu 3594@itemx +dsresetwithcpu 3595Enable/disable automatic Datasette-Reset 3596(@code{DatasetteResetWithCPU=1}, @code{DatasetteResetWithCPU=0}). 3597 3598@findex -dszerogapdelay 3599@item -dszerogapdelay <value> 3600Set delay in cycles for a zero in the tap 3601(@code{DatasetteZeroGapDelay}). 3602 3603@findex -dsspeedtuning 3604@item -dsspeedtuning <value> 3605Set number of cycles added to each gap in the tap 3606(@code{DatasetteSpeedTuning}). 3607 3608@findex -dstapewobble 3609@item -dstapewobble <value> 3610Set maximum random number of cycles added to each gap in the tap 3611(@code{DatasetteTapeWobble}). 3612 3613@findex -datasettesound, +datasettesound 3614@item -datasettesound 3615@itemx +datasettesound 3616Enable/disable Datasette sound emulation 3617(@code{DatasetteSound=1}, @code{DatasetteSound=0}). 3618 3619@findex -dssoundvolume 3620@item -dssoundvolume <value> 3621Set the volume of the Datasette sound 3622(@code{DatasetteSoundVolume}). 3623 3624@end table 3625 3626@node Drive settings, Peripheral settings, Sound settings, Settings and resources 3627@section Drive settings 3628 3629These settings are used to control the hardware-level emulation of the Disk 3630drives. When hardware-level emulation is turned on, only drives 8 and 9 3631are being emulated. 3632 3633The following settings affect both drives: 3634 3635@itemize @bullet 3636 3637@item 3638``Enable true drive emulation'' enables the (slow) hardware-level 3639emulation of the drives for maximum compatibility. This must be turned 3640on for any of the following settings to have effect. 3641 3642@item 3643``Drive sync factor'' specifies the speed of the drive's CPU. This can 3644be used to help loading certain programs that have trouble with the 3645default PAL setting (for example, programs designed for NTSC machines). 3646The ratio is calculated as follows: 3647 3648@example 3649sync_factor = 65536 * clk_drive / clk_machine 3650@end example 3651 3652where @code{clk_drive} and @code{clk_machine} are clock speeds in MHz. 3653The menu lets you choose between the PAL and NTSC values, and also lets 3654you specify whatever value you want. Be careful when changing it, 3655though, because a wrong value can break things and even corrupt disk 3656images. 3657 3658@end itemize 3659 3660The following settings, instead, are specific of each drive: 3661 3662@itemize @bullet 3663 3664@item 3665``Drive model'' specifies the model of the drive being emulated. 3666@strong{Warning:} This will reset the drive. 3667 3668@item 3669``Enable parallel cable'' enables emulation of a SpeedDOS parallel 3670cable; if you switch this option on and replace the original Commodore 3671ROMs with SpeedDOS-compatible ones, you can speed up loading/saving times. 3672 3673@item 3674``Idle method'' specifies which method the drive emulation should use to 3675save CPU cycles in the host CPU. There are three methods: 3676 3677@itemize @bullet 3678@item 3679@dfn{Skip cycles}: Each time the serial line is accessed by the C64, the 3680drive executes all the cycles since the last time it ran. If 3681the number of elapsed cycles is larger than a certain value, the drive 3682discards part of them. 3683@item 3684@dfn{Trap idle}: The disk drive is still emulated upon serial line 3685accesses as with the previous option, but it is also always emulated at 3686the end of each screen frame. If the drive gets into the DOS idle loop, 3687only pending interrupts are emulated to save time. 3688@item 3689@dfn{No traps}: Like ``Trap idle'', but without any traps at all. So 3690basically the drive works exactly as with the real thing, and nothing is 3691done to reduce the power needs of the drive emulation. 3692@end itemize 3693 3694The first option (``Skip cycles'') is usually best for performance, as 3695the drive is emulated as little as possible; on the other hand, you may 3696notice sudden slowdowns (when the drive executes several cycles at once) 3697and the LED status is never updated (because it would not be possible to 3698do correctly so). Moreover, if the drive tries to get in sync with the 3699computer in some weird way and the computer does not access the serial 3700line for a long time, it is possible that some cycles are discarded and 3701the sync is lost. Notice that this hack will have no effect on 3702performance if a program continuously reads from the IEC port, as the 3703drive will have to be fully emulated in any case (some stupid programs 3704do this, even when they don't actually need to use the drive). 3705 3706@c without this, texi2html strips our end-of-paragraph away. 3707@c maybe we should patch it? 3708@ifhtml 3709<P> 3710@end ifhtml 3711 3712The second option (``Trap idle'') is usually a bit slower, as at least 3713interrupts are always emulated, but ensures the LED state is always 3714updated correctly and always keeps the drive and the computer in sync. 3715On the other hand, if a program installs a non-standard idle loop in the 3716drive, the drive CPU has to be emulated even when not necessary and the 3717global emulation speed is then @emph{much} slower. 3718 3719@item 3720``40-track image support'' specifies how 40-track (``extended'') disk 3721images should be supported. There are three possible ways: 3722 3723@itemize @bullet 3724@item 3725``Never extend'' never extends disk images at all (so if a program tries 3726to write tracks beyond the 35th, it is not allowed to do so); 3727@item 3728``Ask on extend'' prompts the user as soon as a program tries to write 3729tracks beyond the 35th, and the user can then choose whether he wants 3730the disk image to be extended or not; 3731@item 3732``Extend on access'' simply extends the disk image as soon the program 3733needs it, without prompting the user. 3734@end itemize 3735 3736@end itemize 3737 3738 3739@menu 3740* Drive resources:: 3741* Drive options:: 3742@end menu 3743 3744@node Drive resources, Drive options, Drive settings, Drive settings 3745@subsection Drive resources 3746 3747@table @code 3748 3749@vindex DriveTrueEmulation 3750@item DriveTrueEmulation 3751Boolean controlling whether the ``true'' drive emulation is turned on. 3752 3753@vindex DriveSoundEmulation 3754@item DriveSoundEmulation 3755Boolean controlling whether the drive noise emulation is turned on 3756(all emulators except vsid). 3757 3758@vindex DriveSoundEmulationVolume 3759@item DriveSoundEmulationVolume 3760Integer specifying the volume of the drive noise emulation 3761(all emulators except vsid). 3762(0..4000) 3763 3764@vindex Drive8Type 3765@vindex Drive9Type 3766@vindex Drive10Type 3767@vindex Drive11Type 3768@item Drive8Type 3769@itemx Drive9Type 3770@itemx Drive10Type 3771@itemx Drive11Type 3772Integers specifying the model number for drives 8 to 11. Possible 3773values are @code{1541} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3774@code{1542} (1541-II) [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3775@code{1570} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3776@code{1571} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3777@code{1573} (1571CR) [x128 only], 3778@code{1551} [xplus4 only], 3779@code{1581} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3780@code{1001} [all emulators except x64dtv, xplus4 and vsid], 3781@code{2000} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3782@code{2031} [all emulators except x64dtv, xplus4 and vsid], 3783@code{2040} [all emulators except x64dtv, xplus4 and vsid], 3784@code{3040} [all emulators except x64dtv, xplus4 and vsid], 3785@code{4000} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3786@code{4040} [all emulators except x64dtv, xplus4 and vsid], 3787@code{4844} (CMD HD) [all emulators except xcbm2, xcbm5x0, xpet and vsid], 3788@code{8050} [all emulators except x64dtv, xplus4 and vsid], 3789@code{8250} [all emulators except x64dtv, xplus4 and vsid]. 3790@code{9000} [all emulators except x64dtv, xplus4 and vsid]. 3791 3792@vindex Drive8RTCSave 3793@item Drive8RTCSave 3794Integer specifying whether the RTC data of drive 8 should be saved when changed or not (drive type 2000/4000 only). 3795 3796@vindex Drive9RTCSave 3797@item Drive9RTCSave 3798Integer specifying whether the RTC data of drive 9 should be saved when changed or not (drive type 2000/4000 only). 3799 3800@vindex Drive10RTCSave 3801@item Drive10RTCSave 3802Integer specifying whether the RTC data of drive 10 should be saved when changed or not (drive type 2000/4000 only). 3803 3804@vindex Drive11RTCSave 3805@item Drive11RTCSave 3806Integer specifying whether the RTC data of drive 11 should be saved when changed or not (drive type 2000/4000 only). 3807 3808@vindex Drive8ParallelCable 3809@vindex Drive9ParallelCable 3810@vindex Drive10ParallelCable 3811@vindex Drive11ParallelCable 3812@item Drive8ParallelCable 3813@itemx Drive9ParallelCable 3814@itemx Drive10ParallelCable 3815@itemx Drive11ParallelCable 3816integers controlling what type of parallel cable is emulated for drives 8 to 11 3817(x64, x64sc, xscpu64, x128 and xplus4 only). 3818x64, x64sc, xscpu64, x128: (0: None, 1: Standard, 2: Dolphin DOS 3, 3: Formel64) 3819xplus4: (0: None, 1: Standard) 3820 3821@vindex Drive8ProfDOS 3822@vindex Drive9ProfDOS 3823@vindex Drive10ProfDOS 3824@vindex Drive11ProfDOS 3825@item Drive8ProfDOS 3826@itemx Drive9ProfDOS 3827@itemx Drive10ProfDOS 3828@itemx Drive11ProfDOS 3829Booleans controlling whether Professional DOS is emulated or not for drives 8 to 11 3830(x64, x64sc, xscpu64 and x128 only). 3831 3832@vindex Drive8SuperCard 3833@vindex Drive9SuperCard 3834@vindex Drive10SuperCard 3835@vindex Drive11SuperCard 3836@item Drive8SuperCard 3837@itemx Drive9SuperCard 3838@itemx Drive10SuperCard 3839@itemx Drive11SuperCard 3840Booleans controlling whether Supercard is emulated or not for drives 8 to 11 3841(x64, x64sc, xscpu64 and x128 only). 3842 3843@vindex Drive8StarDos 3844@vindex Drive9StarDos 3845@vindex Drive10StarDos 3846@vindex Drive11StarDos 3847@item Drive8StarDos 3848@itemx Drive9StarDos 3849@itemx Drive10StarDos 3850@itemx Drive11StarDos 3851Booleans controlling whether StarDOS is emulated or not for drives 8 to 11 3852(x64, x64sc, xscpu64 and x128 only). 3853 3854@vindex Drive8RAM2000 3855@vindex Drive8RAM4000 3856@vindex Drive8RAM6000 3857@vindex Drive8RAM8000 3858@vindex Drive8RAMA000 3859@vindex Drive9RAM2000 3860@vindex Drive9RAM4000 3861@vindex Drive9RAM6000 3862@vindex Drive9RAM8000 3863@vindex Drive9RAMA000 3864@vindex Drive10RAM2000 3865@vindex Drive10RAM4000 3866@vindex Drive10RAM6000 3867@vindex Drive10RAM8000 3868@vindex Drive10RAMA000 3869@vindex Drive11RAM2000 3870@vindex Drive11RAM4000 3871@vindex Drive11RAM6000 3872@vindex Drive11RAM8000 3873@vindex Drive11RAMA000 3874@item Drive8RAM2000 3875@itemx Drive8RAM4000 3876@itemx Drive8RAM6000 3877@itemx Drive8RAM8000 3878@itemx Drive8RAMA000 3879@itemx Drive9RAM2000 3880@itemx Drive9RAM4000 3881@itemx Drive9RAM6000 3882@itemx Drive9RAM8000 3883@itemx Drive9RAMA000 3884@itemx Drive10RAM2000 3885@itemx Drive10RAM4000 3886@itemx Drive10RAM6000 3887@itemx Drive10RAM8000 3888@itemx Drive10RAMA000 3889@itemx Drive11RAM2000 3890@itemx Drive11RAM4000 3891@itemx Drive11RAM6000 3892@itemx Drive11RAM8000 3893@itemx Drive11RAMA000 3894Booleans controlling whether a RAM block is emulated at the respective block or 3895not for drives 8 to 11 respectively. 3896 3897@vindex Drive8ExtendImagePolicy 3898@vindex Drive9ExtendImagePolicy 3899@vindex Drive10ExtendImagePolicy 3900@vindex Drive11ExtendImagePolicy 3901@item Drive8ExtendImagePolicy 3902@itemx Drive9ExtendImagePolicy 3903@itemx Drive10ExtendImagePolicy 3904@itemx Drive11ExtendImagePolicy 3905Integer specifying the policy for 40-track support for drives 8 to 11. 3906(0: never extend, 1: ask on extend, 2: extend on access) 3907 3908@vindex Drive8IdleMethod 3909@vindex Drive9IdleMethod 3910@vindex Drive10IdleMethod 3911@vindex Drive11IdleMethod 3912@item Drive8IdleMethod 3913@itemx Drive9IdleMethod 3914@itemx Drive10IdleMethod 3915@itemx Drive11IdleMethod 3916Integers specifying the idling method for the drive CPU. 3917@xref{Drive settings}. 3918(0: none, 1: skip cycles, 2: trap idle) 3919 3920@vindex Drive8RPM 3921@vindex Drive9RPM 3922@vindex Drive10RPM 3923@vindex Drive11RPM 3924@item Drive8RPM 3925@itemx Drive9RPM 3926@itemx Drive10RPM 3927@itemx Drive11RPM 3928Integers specifying the rotation speed of the drive, multiplied by 100, so 3929300rpm equals 30000. 3930 3931@vindex Drive8WobbleFrequency 3932@vindex Drive9WobbleFrequency 3933@vindex Drive10WobbleFrequency 3934@vindex Drive11WobbleFrequency 3935@item Drive8WobbleFrequency 3936@itemx Drive9WobbleFrequency 3937@itemx Drive10WobbleFrequency 3938@itemx Drive11WobbleFrequency 3939Integers specifying the drive wobble frequency 3940 3941@vindex Drive8WobbleAmplitude 3942@vindex Drive9WobbleAmplitude 3943@vindex Drive10WobbleAmplitude 3944@vindex Drive11WobbleAmplitude 3945@item Drive8WobbleAmplitude 3946@itemx Drive9WobbleAmplitude 3947@itemx Drive10WobbleAmplitude 3948@itemx Drive11WobbleAmplitude 3949Integers specifying the drive wobble amplitude 3950 3951@vindex DosName1540 3952@vindex DosName1541 3953@vindex DosName1541ii 3954@vindex DosName1570 3955@vindex DosName1571 3956@vindex DosName1581 3957@vindex DosName2000 3958@vindex DosName4000 3959@vindex DosNameCMDHD 3960@item DosName1540 3961@itemx DosName1541 3962@itemx DosName1541ii 3963@itemx DosName1570 3964@itemx DosName1571 3965@itemx DosName1581 3966@itemx DosName2000 3967@itemx DosName4000 3968@itemx DosNameCMDHD 3969Strings specifying the names of the ROM images for the drive emulation. 3970(all emulators except xcbm2, xcbm5x0, xpet and vsid) 3971 3972@vindex DosName1551 3973@item DosName1551 3974String specifying the name of the ROM image for the drive emulation. 3975(xplus4 only) 3976 3977@vindex DosName1571cr 3978@item DosName1571cr 3979String specifying the name of the ROM image for the drive emulation. 3980(x128 only) 3981 3982@vindex DosName2031 3983@vindex DosName2040 3984@vindex DosName3040 3985@vindex DosName4040 3986@vindex DosName1001 3987@vindex DosName9000 3988@item DosName2031 3989@itemx DosName2040 3990@itemx DosName3040 3991@itemx DosName4040 3992@itemx DosName1001 3993@itemx DosName9000 3994Strings specifying the names of the ROM images for the drive emulation. 3995(all emulators except x64dtv, xplus4 and vsid) 3996 3997@vindex DriveProfDOS1571Name 3998@item DriveProfDOS1571Name 3999String specifying the filename of the 1571 professional DOS ROM image 4000(x64, x64sc, xscpu64 and x128 only). 4001 4002@vindex DriveSuperCardName 4003@item DriveSuperCardName 4004String specifying the filename of the Supercard ROM image 4005(x64, x64sc, xscpu64 and x128 only). 4006 4007@vindex DriveStarDosName 4008@item DriveStarDosName 4009String specifying the filename of the image of the lower half of the StarDOS ROM 4010(x64, x64sc, xscpu64 and x128 only). 4011 4012@end table 4013 4014@node Drive options, , Drive resources, Drive settings 4015@subsection Drive command-line options 4016 4017@table @code 4018 4019@findex -truedrive, +truedrive 4020@item -truedrive 4021@itemx +truedrive 4022Enable/disable true drive emulation 4023(@code{DriveTrueEmulation=1}, @code{DriveTrueEmulation=0}). 4024 4025@findex -drivesound, +drivesound 4026@item -drivesound 4027@itemx +drivesound 4028Enable/disable drive sound emulation 4029(@code{DriveSoundEmulation=1}, @code{DriveSoundEmulation=0}) 4030(all emulators except vsid). 4031 4032@findex -drivesoundvolume 4033@item -drivesoundvolume <Volume> 4034Set the volume of the drive sound emulation 4035(@code{DriveSoundEmulationVolume=1}, @code{DriveSoundEmulationVolume=0}) 4036(all emulators except vsid). 4037 4038@findex -drive8type 4039@findex -drive9type 4040@findex -drive10type 4041@findex -drive11type 4042@item -drive8type <Type> 4043@itemx -drive9type <Type> 4044@itemx -drive10type <Type> 4045@itemx -drive11type <Type> 4046Specifies the drive types for drives 8-11, respectively. 4047Possible values for @code{TYPE} are 4048@code{1541} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4049@code{1542} (meaning 1541-II) [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4050@code{1551} [xplus4 only], 4051@code{1570} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4052@code{1571} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4053@code{1573} (meaning 1571cr) [x128 only], 4054@code{1581} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4055@code{2000} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4056@code{4000} [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4057@code{4844} (meaning CMD HD) [all emulators except xcbm2, xcbm5x0, xpet and vsid], 4058@code{2031} [all emulators except x64dtv, xplus4 and vsid], 4059@code{2040} [all emulators except x64dtv, xplus4 and vsid], 4060@code{3040} [all emulators except x64dtv, xplus4 and vsid], 4061@code{4040} [all emulators except x64dtv, xplus4 and vsid], 4062@code{1001} [all emulators except x64dtv, xplus4 and vsid], 4063@code{8050} [all emulators except x64dtv, xplus4 and vsid] 4064@code{8250} [all emulators except x64dtv, xplus4 and vsid]. 4065and @code{9000} [all emulators except x64dtv, xplus4 and vsid]. 4066 4067@findex -drive8rtcsave, +drive8rtcsave 4068@item -drive8rtcsave 4069@itemx -drive8rtcsave 4070Enable/disable the saving of the RTC data for drive 8 when changed (drive type 2000/4000/4844 only) 4071(@code{Drive8RTCSave=1}, @code{Drive8RTCSave=0}). 4072 4073@findex -drive9rtcsave, +drive9rtcsave 4074@item -drive9rtcsave 4075@itemx -drive9rtcsave 4076Enable/disable the saving of the RTC data for drive 9 when changed (drive type 2000/4000/4844 only) 4077(@code{Drive9RTCSave=1}, @code{Drive9RTCSave=0}). 4078 4079@findex -drive10rtcsave, +drive10rtcsave 4080@item -drive10rtcsave 4081@itemx -drive10rtcsave 4082Enable/disable the saving of the RTC data for drive 10 when changed (drive type 2000/4000/4844 only) 4083(@code{Drive10RTCSave=1}, @code{Drive10RTCSave=0}). 4084 4085@findex -drive11rtcsave, +drive11rtcsave 4086@item -drive11rtcsave 4087@itemx -drive11rtcsave 4088Enable/disable the saving of the RTC data for drive 11 when changed (drive type 2000/4000/4844 only) 4089(@code{Drive11RTCSave=1}, @code{Drive11RTCSave=0}). 4090 4091@findex -parallel8 4092@findex -parallel9 4093@findex -parallel10 4094@findex -parallel11 4095@item -parallel8 <type> 4096@itemx -parallel9 <type> 4097@itemx -parallel10 <type> 4098@itemx -parallel11 <type> 4099Set parallel cable type for drives 8-11 respectively 4100(@code{Drive8ParallelCable}, @code{Drive9ParallelCable}, 4101@code{Drive10ParallelCable}, @code{Drive11ParallelCable}) 4102(x64, x64sc, xscpu64, x128 and xplus4 only). 4103x64, x64sc, xscpu64, x128: (0: None, 1: Standard, 2: Professional DOS, 3: Formel64) 4104xplus4: (0: None, 1: Standard) 4105 4106@findex -drive8idle 4107@findex -drive9idle 4108@findex -drive10idle 4109@findex -drive11idle 4110@item -drive8idle <method> 4111@itemx -drive9idle <method> 4112@itemx -drive10idle <method> 4113@itemx -drive11idle <method> 4114Specifies <method> as the idling method for drives 8-11 respectively 4115(@code{Drive8IdleMethod}, @code{Drive9IdleMethod}, 4116@code{Drive10IdleMethod}), @code{Drive11IdleMethod}). 4117(0: none, 1: skip cycles, 2: trap idle) 4118 4119@findex -drive8extend 4120@findex -drive9extend 4121@findex -drive10extend 4122@findex -drive11extend 4123@item -drive8extend <method> 4124@itemx -drive9extend <method> 4125@itemx -drive10extend <method> 4126@itemx -drive11extend <method> 4127Specifies <method> as the track 40 extend policy in drives 8-11 respectively 4128(@code{Drive8ExtendImagePolicy}, @code{Drive9ExtendImagePolicy}, 4129@code{Drive10ExtendImagePolicy}, @code{Drive11ExtendImagePolicy}). 4130(0: never extend, 1: ask on extend, 2: extend on access) 4131 4132@findex -drive8rpm 4133@findex -drive9rpm 4134@findex -drive10rpm 4135@findex -drive11rpm 4136@item -drive8rpm <rpm> 4137@itemx -drive9rpm <rpm> 4138@itemx -drive10rpm <rpm> 4139@itemx -drive11rpm <rpm> 4140Specifies the rotation speed of the drive, multiplied by 100 so 300rpm 4141equal 30000. 4142 4143@findex -drive8wobblefrequency 4144@findex -drive9wobblefrequency 4145@findex -drive10wobblefrequency 4146@findex -drive11wobblefrequency 4147@item -drive8wobblefrequency <frequency> 4148@itemx -drive9wobblefrequency <frequency> 4149@itemx -drive10wobblefrequency <frequency> 4150@itemx -drive11wobblefrequency <frequency> 4151Specifies frequency of the drive wobble 4152 4153@findex -drive8wobbleamplitude 4154@findex -drive9wobbleamplitude 4155@findex -drive10wobbleamplitude 4156@findex -drive11wobbleamplitude 4157@item -drive8wobbleamplitude <amplitude> 4158@itemx -drive9wobbleamplitude <amplitude> 4159@itemx -drive10wobbleamplitude <amplitude> 4160@itemx -drive11wobbleamplitude <amplitude> 4161Specifies amplitude of the drive wobble 4162 4163@findex -dos1540 4164@item -dos1540 <name> 4165Specify the ROM name for the 1540 emulation 4166(@code{DosName1540}). 4167(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4168 4169@findex -dos1541 4170@item -dos1541 <name> 4171Specify the ROM name for the 1541 emulation 4172(@code{DosName1541}). 4173(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4174 4175@findex -dos1541II 4176@item -dos1541II <name> 4177Specify the ROM name for the 1541-II emulation 4178(@code{DosName1541ii}). 4179(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4180 4181@findex -dos1551 4182@item -dos1551 <name> 4183Specify the ROM name for the 1551 emulation 4184(@code{DosName1551}). 4185(xplus4 only) 4186 4187@findex -dos1570 4188@item -dos1570 <name> 4189Specify the ROM name for the 1570 emulation 4190(@code{DosName1570}). 4191(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4192 4193@findex -dos1571 4194@item -dos1571 <name> 4195Specify the ROM name for the 1571 emulation 4196(@code{DosName1571}). 4197(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4198 4199@findex -dos1571cr 4200@item -dos1571cr <name> 4201Specify the ROM name for the 1571 emulation 4202(@code{DosName1571CR}). 4203(x128 only) 4204 4205@findex -dos1581 4206@item -dos1581 <name> 4207Specify the ROM name for the 1581 emulation 4208(@code{DosName1581}). 4209(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4210 4211@findex -dos2000 4212@item -dos2000 <name> 4213Specify the ROM name for the FD2000 emulation 4214(@code{DosName2000}). 4215(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4216 4217@findex -dos4000 4218@item -dos4000 <name> 4219Specify the ROM name for the FD4000 emulation 4220(@code{DosName4000}). 4221(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4222 4223@findex -dosCMDHD 4224@item -dosCMDHD <name> 4225Specify the boot ROM name for the CMD HD emulation 4226(@code{DosNameCMDHD}). 4227(all emulators except xcbm2, xcbm5x0, xpet and vsid) 4228 4229@findex -dos2031 4230@item -dos2031 <name> 4231Specify the ROM name for the 2031 emulation 4232(@code{DosName2031}). 4233(all emulators except x64dtv, xplus4 and vsid) 4234 4235@findex -dos2040 4236@item -dos2040 <name> 4237Specify the ROM name for the 2040 emulation 4238(@code{DosName2040}). 4239(all emulators except x64dtv, xplus4 and vsid) 4240 4241@findex -dos3040 4242@item -dos3040 <name> 4243Specify the ROM name for the 3040 emulation 4244(@code{DosName3040}). 4245(all emulators except x64dtv, xplus4 and vsid) 4246 4247@findex -dos4040 4248@item -dos4040 <name> 4249Specify the ROM name for the 4040 emulation 4250(@code{DosName4040}). 4251(all emulators except x64dtv, xplus4 and vsid) 4252 4253@findex -dos1001 4254@item -dos1001 <name> 4255Specify the ROM name for the 1001, 8050 and 8250 emulations 4256(@code{DosName1001}). 4257(all emulators except x64dtv, xplus4 and vsid) 4258 4259@findex -dos9000 4260@item -dos9000 <name> 4261Specify the ROM name for the D9090/60 emulations 4262(@code{DosName9000}). 4263(all emulators except x64dtv, xplus4 and vsid) 4264 4265@findex -drive8ram2000, +drive8ram2000 4266@item -drive8ram2000, +drive8ram2000 4267Enable/disable 8KiB RAM expansion at $2000-$3FFF for drive 8 4268(@code{Drive8RAM2000=1}, @code{Drive8RAM2000=0}). 4269 4270@findex -drive9ram2000, +drive9ram2000 4271@item -drive9ram2000, +drive9ram2000 4272Enable/disable 8KiB RAM expansion at $2000-$3FFF for drive 9 4273(@code{Drive9RAM2000=1}, @code{Drive9RAM2000=0}). 4274 4275@findex -drive10ram2000, +drive10ram2000 4276@item -drive10ram2000, +drive10ram2000 4277Enable/disable 8KiB RAM expansion at $2000-$3FFF for drive 10 4278(@code{Drive10RAM2000=1}, @code{Drive10RAM2000=0}). 4279 4280@findex -drive11ram2000, +drive11ram2000 4281@item -drive11ram2000, +drive11ram2000 4282Enable/disable 8KiB RAM expansion at $2000-$3FFF for drive 11 4283(@code{Drive11RAM2000=1}, @code{Drive11RAM2000=0}). 4284 4285@findex -drive8ram4000, +drive8ram4000 4286@item -drive8ram4000, +drive8ram4000 4287Enable/disable 8KiB RAM expansion at $4000-$5FFF for drive 8 4288(@code{Drive8RAM4000=1}, @code{Drive8RAM4000=0}). 4289 4290@findex -drive9ram4000, +drive9ram4000 4291@item -drive9ram4000, +drive9ram4000 4292Enable/disable 8KiB RAM expansion at $4000-$5FFF for drive 9 4293(@code{Drive9RAM4000=1}, @code{Drive9RAM4000=0}). 4294 4295@findex -drive10ram4000, +drive10ram4000 4296@item -drive10ram4000, +drive10ram4000 4297Enable/disable 8KiB RAM expansion at $4000-$5FFF for drive 10 4298(@code{Drive10RAM4000=1}, @code{Drive10RAM4000=0}). 4299 4300@findex -drive11ram4000, +drive11ram4000 4301@item -drive11ram4000, +drive11ram4000 4302Enable/disable 8KiB RAM expansion at $4000-$5FFF for drive 11 4303(@code{Drive11RAM4000=1}, @code{Drive11RAM4000=0}). 4304 4305@findex -drive8ram6000, +drive8ram6000 4306@item -drive8ram6000, +drive8ram6000 4307Enable/disable 8KiB RAM expansion at $6000-$7FFF for drive 8 4308(@code{Drive8RAM6000=1}, @code{Drive8RAM6000=0}). 4309 4310@findex -drive9ram6000, +drive9ram6000 4311@item -drive9ram6000, +drive9ram6000 4312Enable/disable 8KiB RAM expansion at $6000-$7FFF for drive 9 4313(@code{Drive9RAM6000=1}, @code{Drive9RAM6000=0}). 4314 4315@findex -drive10ram6000, +drive10ram6000 4316@item -drive10ram6000, +drive10ram6000 4317Enable/disable 8KiB RAM expansion at $6000-$7FFF for drive 10 4318(@code{Drive10RAM6000=1}, @code{Drive10RAM6000=0}). 4319 4320@findex -drive11ram6000, +drive11ram6000 4321@item -drive11ram6000, +drive11ram6000 4322Enable/disable 8KiB RAM expansion at $6000-$7FFF for drive 11 4323(@code{Drive11RAM6000=1}, @code{Drive11RAM6000=0}). 4324 4325@findex -drive8ram8000, +drive8ram8000 4326@item -drive8ram8000, +drive8ram8000 4327Enable/disable 8KiB RAM expansion at $8000-$9FFF for drive 8 4328(@code{Drive8RAM8000=1}, @code{Drive8RAM8000=0}). 4329 4330@findex -drive9ram8000, +drive9ram8000 4331@item -drive9ram8000, +drive9ram8000 4332Enable/disable 8KiB RAM expansion at $8000-$9FFF for drive 9 4333(@code{Drive9RAM8000=1}, @code{Drive9RAM8000=0}). 4334 4335@findex -drive10ram8000, +drive10ram8000 4336@item -drive10ram8000, +drive10ram8000 4337Enable/disable 8KiB RAM expansion at $8000-$9FFF for drive 10 4338(@code{Drive10RAM8000=1}, @code{Drive10RAM8000=0}). 4339 4340@findex -drive11ram8000, +drive11ram8000 4341@item -drive11ram8000, +drive11ram8000 4342Enable/disable 8KiB RAM expansion at $8000-$9FFF for drive 11 4343(@code{Drive11RAM8000=1}, @code{Drive11RAM8000=0}). 4344 4345@findex -drive8rama000, +drive8rama000 4346@item -drive8rama000, +drive8rama000 4347Enable/disable 8KiB RAM expansion at $A000-$BFFF for drive 8 4348(@code{Drive8RAMA000=1}, @code{Drive8RAMA000=0}). 4349 4350@findex -drive9rama000, +drive9rama000 4351@item -drive9rama000, +drive9rama000 4352Enable/disable 8KiB RAM expansion at $A000-$BFFF for drive 9 4353(@code{Drive9RAMA000=1}, @code{Drive9RAMA000=0}). 4354 4355@findex -drive10rama000, +drive10rama000 4356@item -drive10rama000, +drive10rama000 4357Enable/disable 8KiB RAM expansion at $A000-$BFFF for drive 10 4358(@code{Drive10RAMA000=1}, @code{Drive10RAMA000=0}). 4359 4360@findex -drive11rama000, +drive11rama000 4361@item -drive11rama000, +drive11rama000 4362Enable/disable 8KiB RAM expansion at $A000-$BFFF for drive 11 4363(@code{Drive11RAMA000=1}, @code{Drive11RAMA000=0}). 4364 4365@findex -drive8profdos, +drive8profdos 4366@item -drive8profdos 4367@itemx +drive8profdos 4368Enable/disable Professional DOS for drive 8 4369(@code{Drive8ProfDOS=1}, @code{Drive8ProfDOS=0}) 4370(x64, x64sc, xscpu64 and x128 only). 4371 4372@findex -drive9profdos, +drive9profdos 4373@item -drive9profdos 4374@itemx +drive9profdos 4375Enable/disable Professional DOS for drive 9 4376(@code{Drive9ProfDOS=1}, @code{Drive9ProfDOS=0}) 4377(x64, x64sc, xscpu64 and x128 only). 4378 4379@findex -drive10profdos, +drive10profdos 4380@item -drive10profdos 4381@itemx +drive10profdos 4382Enable/disable Professional DOS for drive 10 4383(@code{Drive10ProfDOS=1}, @code{Drive10ProfDOS=0}) 4384(x64, x64sc, xscpu64 and x128 only). 4385 4386@findex -drive11profdos, +drive11profdos 4387@item -drive11profdos 4388@itemx +drive11profdos 4389Enable/disable Professional DOS for drive 11 4390(@code{Drive11ProfDOS=1}, @code{Drive11ProfDOS=0}) 4391(x64, x64sc, xscpu64 and x128 only). 4392 4393@findex -profdos1571 4394@item -profdos1571 <name> 4395Specify name of Professional DOS 1571 ROM image 4396(@code{DriveProfDOS1571Name}) 4397(x64, x64sc, xscpu64 and x128). 4398 4399@findex -drive8supercard, +drive8supercard 4400@item -drive8supercard 4401@itemx +drive8supercard 4402Enable/disable Supercard for drive 8 4403(@code{Drive8SuperCard=1}, @code{Drive8SuperCard=0}) 4404(x64, x64sc, xscpu64 and x128 only). 4405 4406@findex -drive9supercard, +drive9supercard 4407@item -drive9supercard 4408@itemx +drive9supercard 4409Enable/disable Supercard for drive 9 4410(@code{Drive9SuperCard=1}, @code{Drive9SuperCard=0}) 4411(x64, x64sc, xscpu64 and x128 only). 4412 4413@findex -drive10supercard, +drive10supercard 4414@item -drive10supercard 4415@itemx +drive10supercard 4416Enable/disable Supercard for drive 10 4417(@code{Drive10SuperCard=1}, @code{Drive10SuperCard=0}) 4418(x64, x64sc, xscpu64 and x128 only). 4419 4420@findex -drive11supercard, +drive11supercard 4421@item -drive11supercard 4422@itemx +drive11supercard 4423Enable/disable Supercard for drive 11 4424(@code{Drive11SuperCard=1}, @code{Drive11SuperCard=0}) 4425(x64, x64sc, xscpu64 and x128 only). 4426 4427@findex -supercard 4428@item -supercard <name> 4429Specify name of Supercard ROM image 4430(@code{DriveSuperCardName}) 4431(x64, x64sc, xscpu64 and x128 only). 4432 4433@findex -drive8stardos, +drive8stardos 4434@item -drive8stardos 4435@itemx +drive8stardos 4436Enable/disable StarDOS for drive 8 4437(@code{Drive8StarDos=1}, @code{Drive8StarDos=0}) 4438(x64, x64sc, xscpu64 and x128 only). 4439 4440@findex -drive9stardos, +drive9stardos 4441@item -drive9stardos 4442@itemx +drive9stardos 4443Enable/disable StarDOS for drive 9 4444(@code{Drive9StarDos=1}, @code{Drive9StarDos=0}) 4445(x64, x64sc, xscpu64 and x128 only). 4446 4447@findex -drive10stardos, +drive10stardos 4448@item -drive10stardos 4449@itemx +drive10stardos 4450Enable/disable StarDOS for drive 10 4451(@code{Drive10StarDos=1}, @code{Drive10StarDos=0}) 4452(x64, x64sc, xscpu64 and x128 only). 4453 4454@findex -drive11stardos, +drive11stardos 4455@item -drive11stardos 4456@itemx +drive11stardos 4457Enable/disable StarDOS for drive 11 4458(@code{Drive11StarDos=1}, @code{Drive11StarDos=0}) 4459(x64, x64sc, xscpu64 and x128 only). 4460 4461@findex -stardos 4462@item -stardos <name> 4463Specify name of the image of the lower half of the StarDOS ROM. (Attach the upper 4464half using the -dos1541 option.) 4465(@code{DriveStarDosName}) 4466(x64, x64sc, xscpu64 and x128 only). 4467 4468@end table 4469 4470 4471@node Peripheral settings, RS232 settings, Drive settings, Settings and resources 4472@section Peripheral settings 4473 4474VICE is able to support some special peripherals: 4475 4476@itemize @bullet 4477@item 4478@dfn{file system devices}, pseudo-drives accessing the Unix file system; 4479@item 4480printers. 4481@end itemize 4482 4483These features depend on some @dfn{kernal traps} that replace the 4484existing routines in the original Commodore operating system with 4485custom-made C routines. 4486 4487@menu 4488* File system device settings:: Settings for file system devices. 4489* Printer settings:: Settings for emulating a printer. 4490* No kernal traps:: Disabling kernal traps completely. 4491@end menu 4492 4493@node File system device settings, Printer settings, Peripheral settings, Peripheral settings 4494@subsection Settings for file system devices 4495 4496These settings deal with the drive-like peripherals connected to the bus 4497of the emulated machine. 4498The first setting relates to the parallel IEEE488 interface. With 4499this interface a special engine is used to listen to the bus lines 4500to translates them to the filesystem code. Thus the PET will always 4501detect a drive for example, but it can also use drives 10 and 11 even 4502together with true disk drive emulation. 4503 4504@itemize @bullet 4505@item 4506``Enable virtual devices'', enables the peripheral access via 4507the fast disk emulation (either kernal traps or IEEE488 interface). 4508Both, filesystem and disk image access via fast 4509drive emulation, are affected. 4510@end itemize 4511 4512Four peripherals, numbered from 8 to 11, are 4513accessible; each of them provides the following settings: 4514 4515@itemize @bullet 4516@item 4517``File system access'', if enabled, allows the device to emulate a drive 4518accessing a file system directory; note that when a disk image is 4519attached to the same drive, the directory is no longer visible and the 4520attached disk is used instead. 4521@item 4522``File system directory'' specifies the directory to be accessed by the 4523drive. 4524@item 4525``Convert P00 file names'', if enabled, allows access to P00 files using 4526their built-in name instead of the Unix one. 4527@item 4528``Create P00 files on save'', if enabled, creates P00 files (instead of 4529raw CBM files) whenever a program creates a file. 4530@end itemize 4531 4532Note that, by default, all drives create P00 files on save. 4533 4534@menu 4535* File system device resources:: 4536* File system device options:: 4537@end menu 4538 4539 4540@node File system device resources, File system device options, File system device settings, File system device settings 4541@subsubsection Resources for file system devices 4542 4543 4544@table @code 4545 4546@vindex IECDevice8 4547@vindex IECDevice9 4548@vindex IECDevice10 4549@vindex IECDevice11 4550@item IECDevice8 4551@itemx IECDevice9 4552@itemx IECDevice10 4553@itemx IECDevice11 4554Booleans that specify whether IEC device emulation for device #8 to #11 is enabled. 4555 4556@vindex FileSystemDevice8 4557@vindex FileSystemDevice9 4558@vindex FileSystemDevice10 4559@vindex FileSystemDevice11 4560@item FileSystemDevice8 4561@itemx FileSystemDevice9 4562@itemx FileSystemDevice10 4563@itemx FileSystemDevice11 4564Integers specifying the device type for device 8-11 respectively 4565(all emulators except vsid). 4566(0: None, 1: Filesystem, 2: OpenCBM (Real)) 4567 4568@vindex FSDevice8ConvertP00 4569@vindex FSDevice9ConvertP00 4570@vindex FSDevice10ConvertP00 4571@vindex FSDevice11ConvertP00 4572@item FSDevice8ConvertP00 4573@itemx FSDevice9ConvertP00 4574@itemx FSDevice10ConvertP00 4575@itemx FSDevice11ConvertP00 4576Booleans specifying whether on-read support for P00 files is enabled on drives 8, 9, 10 and 11 respectively 4577(all emulators except vsid). 4578 4579@vindex FSDevice8SaveP00 4580@vindex FSDevice9SaveP00 4581@vindex FSDevice10SaveP00 4582@vindex FSDevice11SaveP00 4583@item FSDevice8SaveP00 4584@itemx FSDevice9SaveP00 4585@itemx FSDevice10SaveP00 4586@itemx FSDevice11SaveP00 4587Booleans specifying whether the drives should create P00 files instead of plain CBM ones for drives 8, 9, 10 and 11 respectively 4588(all emulators except vsid). 4589 4590@vindex FSDevice8HideCBMFiles 4591@vindex FSDevice9HideCBMFiles 4592@vindex FSDevice10HideCBMFiles 4593@vindex FSDevice11HideCBMFiles 4594@item FSDevice8HideCBMFiles 4595@itemx FSDevice9HideCBMFiles 4596@itemx FSDevice10HideCBMFiles 4597@itemx FSDevice11HideCBMFiles 4598Booleans specifying whether non-P00 files should be invisible for drives 8, 9, 10 and 11 respectively 4599(all emulators except vsid). 4600 4601@vindex FSDevice8Dir 4602@vindex FSDevice9Dir 4603@vindex FSDevice10Dir 4604@vindex FSDevice11Dir 4605@item FSDevice8Dir 4606@itemx FSDevice9Dir 4607@itemx FSDevice10Dir 4608@itemx FSDevice11Dir 4609Strings specifying the directories to which drives 8, 9, 10 and 11 have access 4610(all emulators except vsid). 4611 4612@vindex FSDeviceLongNames 4613@item FSDeviceLongNames 4614Boolean specifying whether filenames will get converted to 16 character long short names 4615or not. Disabled by default. 4616 4617@vindex FSDeviceOverwrite 4618@item FSDeviceOverwrite 4619Boolean specifying whether files in the file system can be overwritten without 4620using @code{"@@:name"}, or not. 4621Disabled by default. 4622 4623@end table 4624 4625 4626@node File system device options, , File system device resources, File system device settings 4627@subsubsection Command-line options for file system devices 4628 4629@table @code 4630 4631@findex -iecdevice8, +iecdevice8 4632@item -iecdevice8 4633@itemx +iecdevice8 4634Enable/disable IEC device emulation for device #8 4635(@code{IECDevice8=1}, @code{IECDevice8=0}). 4636 4637@findex -iecdevice9, +iecdevice9 4638@item -iecdevice9 4639@itemx +iecdevice9 4640Enable/disable IEC device emulation for device #9 4641(@code{IECDevice9=1}, @code{IECDevice9=0}). 4642 4643@findex -iecdevice10, +iecdevice10 4644@item -iecdevice10 4645@itemx +iecdevice10 4646Enable/disable IEC device emulation for device #10 4647(@code{IECDevice10=1}, @code{IECDevice10=0}). 4648 4649@findex -iecdevice11, +iecdevice11 4650@item -iecdevice11 4651@itemx +iecdevice11 4652Enable/disable IEC device emulation for device #11 4653(@code{IECDevice11=1}, @code{IECDevice11=0}). 4654 4655@findex -device8 4656@findex -device9 4657@findex -device10 4658@findex -device11 4659@item -device8 <type> 4660@itemx -device9 <type> 4661@itemx -device10 <type> 4662@itemx -device11 <type> 4663Set device type for device 8-11 respectively 4664(@code{FileSystemDevice8}, @code{FileSystemDevice9}, @code{FileSystemDevice10}, @code{FileSystemDevice11}) 4665(all emulators except vsid). 4666(0: None, 1: Filesystem, 2: OpenCBM (Real)) 4667 4668@findex -fs8 4669@findex -fs9 4670@findex -fs10 4671@findex -fs11 4672@item -fs8 <Name> 4673@itemx -fs9 <Name> 4674@itemx -fs10 <Name> 4675@itemx -fs11 <Name> 4676Specify the paths for the file system access on drives 8, 9, 10 and 11, respectively 4677(@code{FSDevice8Dir}, @code{FSDevice9Dir}, 4678@code{FSDevice10Dir} and @code{FSDevice11Dir}) 4679(all emulators except vsid). 4680 4681@findex -fs8convertp00,+fs8convertp00 4682@item -fs8convertp00 4683@itemx +fs8convertp00 4684Enable/disable on-read support for P00 files on drive 8 4685(@code{FSDevice8ConvertP00=1}, @code{FSDevice8ConvertP00=0}) 4686(all emulators except vsid). 4687 4688@findex -fs9convertp00, +fs9convertp00 4689@item -fs9convertp00 4690@itemx +fs9convertp00 4691Enable/disable on-read support for P00 files on drive 9 4692(@code{FSDevice9ConvertP00=1}, @code{FSDevice9ConvertP00=0}) 4693(all emulators except vsid). 4694 4695@findex -fs10convertp00, +fs10convertp00 4696@item -fs10convertp00 4697@itemx +fs10convertp00 4698Enable/disable on-read support for P00 files on drive 10 4699(@code{FSDevice10ConvertP00=1}, @code{FSDevice10ConvertP00=0}) 4700(all emulators except vsid). 4701 4702@findex -fs11convertp00, +fs11convertp00 4703@item -fs11convertp00 4704@itemx +fs11convertp00 4705Enable/disable on-read support for P00 files on drive 11 4706(@code{FSDevice11ConvertP00=1}, @code{FSDevice11ConvertP00=0}) 4707(all emulators except vsid). 4708 4709@findex -fs8savep00, +fs8savep00 4710@item -fs8savep00 4711@itemx +fs8savep00 4712Enable/disable saving P00 files on drive 8 4713(@code{FSDevice8SaveP00=1}, @code{FSDevice8SaveP00=0}) 4714(all emulators except vsid). 4715 4716@findex -fs9savep00, +fs9savep00 4717@item -fs9savep00 4718@itemx +fs9savep00 4719Enable/disable saving P00 files on drive 9 4720(@code{FSDevice9SaveP00=1}, @code{FSDevice9SaveP00=0}) 4721(all emulators except vsid). 4722 4723@findex -fs10savep00, +fs10savep00 4724@item -fs10savep00 4725@itemx +fs10savep00 4726Enable/disable saving P00 files on drive 10 4727(@code{FSDevice10SaveP00=1}, @code{FSDevice10SaveP00=0}) 4728(all emulators except vsid). 4729 4730@findex -fs11savep00, +fs11savep00 4731@item -fs11savep00 4732@itemx +fs11savep00 4733Enable/disable saving P00 files on drive 11 4734(@code{FSDevice11SaveP00=1}, @code{FSDevice11SaveP00=0}) 4735(all emulators except vsid). 4736 4737@findex -fs8hidecbm, +fs8hidecbm 4738@item -fs8hidecbm 4739@itemx +fs8hidecbm 4740Enable/disable hiding of CBM files for drive 8 4741(@code{FSDevice8HideCBMFiles=1}, @code{FSDevice8HideCBMFiles=0}) 4742(all emulators except vsid). 4743 4744@findex -fs9hidecbm, +fs9hidecbm 4745@item -fs9hidecbm 4746@itemx +fs9hidecbm 4747Enable/disable hiding of CBM files for drive 9 4748(@code{FSDevice9HideCBMFiles=1}, @code{FSDevice9HideCBMFiles=0}) 4749(all emulators except vsid). 4750 4751@findex -fs10hidecbm, +fs10hidecbm 4752@item -fs10hidecbm 4753@itemx +fs10hidecbm 4754Enable/disable hiding of CBM files for drive 10 4755(@code{FSDevice10HideCBMFiles=1}, @code{FSDevice10HideCBMFiles=0}) 4756(all emulators except vsid). 4757 4758@findex -fs11hidecbm, +fs11hidecbm 4759@item -fs11hidecbm 4760@itemx +fs11hidecbm 4761Enable/disable hiding of CBM files for drive 11 4762(@code{FSDevice11HideCBMFiles=1}, @code{FSDevice11HideCBMFiles=0}) 4763(all emulators except vsid). 4764 4765@findex -fslongnames, +fslongnames 4766@item -fslongnames 4767@itemx +fslongnames 4768Enable/disable whether filenames will get converted to 16 character long short names 4769(@code{FSDeviceLongNames=1}, @code{FSDeviceLongNames=0}) 4770(all emulators except vsid). 4771 4772@findex -fsoverwrite, +fsoverwrite 4773@item -fsoverwrite 4774@itemx +fsoverwrite 4775Enable/disable whether existing files in the file system can be overwritten 4776by default. Using @code{OPEN} or @code{SAVE"@@:name"} this is always possible. 4777(@code{FSDeviceOverwrite=1}, @code{FSDeviceOverwrite=0}) 4778(all emulators except vsid). 4779 4780@findex -flipname 4781@item -flipname <name> 4782Specify name of the flip list file image 4783(@code{FliplistName}) 4784(all emulators except vsid). 4785 4786@end table 4787 4788 4789@node Printer settings, No kernal traps, File system device settings, Peripheral settings 4790@subsection Printer settings 4791 4792The VICE emulators can emulate printers connected to either the IEC 4793buffer or the user port. Emulation can be achieved by redirecting the 4794printer output to a file or by piping it through an external process. 4795This is defined by so-called @dfn{printer device file names}; a printer 4796device file name can be either a simple path, or a command name 4797preceeded by a pipe symbol @samp{|}. 4798 4799For example, printer device @samp{filename} will cause the output to be 4800appended to the file @file{filename}, while printer device @samp{|lpr} 4801will cause the @code{lpr} command to be executed and be fed the printer 4802output. The printer output will not be converted but saved as printed 4803by the emulated machine. 4804 4805Up to three printer devices may be specified through the following 4806resources: 4807 4808@itemize @bullet 4809@item 4810device 1, whose default value is @code{print.dump}; 4811@item 4812device 2, whose default value is @code{|lpr}. 4813@item 4814device 3, whose default value is @code{|petlp -F PS|lpr}; 4815@end itemize 4816 4817So, basically, by default printer device 1 will dump printer 4818output to @file{print.dump}; printer device 2 will print it via 4819@code{lpr} directly to the printer and device 3 will print it via 4820@code{petlp} (a not-yet-complete utility that will produce Postscript 4821output from the Commodore printer code) and then to the printer via 4822@code{lpr}. 4823 4824 4825@menu 4826* Printer resources:: 4827* Printer options:: 4828@end menu 4829 4830@node Printer resources, Printer options, Printer settings, Printer settings 4831@subsubsection Printer resources 4832 4833@table @code 4834 4835@vindex IECDevice4 4836@vindex IECDevice5 4837@vindex IECDevice6 4838@vindex IECDevice7 4839@item IECDevice4 4840@itemx IECDevice5 4841@itemx IECDevice6 4842@itemx IECDevice7 4843Booleans that specify whether IEC device emulation for device #4, #5, #6 and #7 is enabled. 4844 4845@vindex PrinterTextDevice1 4846@vindex PrinterTextDevice2 4847@vindex PrinterTextDevice3 4848@item PrinterTextDevice1 4849@itemx PrinterTextDevice2 4850@itemx PrinterTextDevice3 4851Strings specifying the printer devices (@pxref{Printer settings}). 4852 4853@vindex Printer4TextDevice 4854@vindex Printer5TextDevice 4855@vindex Printer6TextDevice 4856@item Printer4TextDevice 4857@itemx Printer5TextDevice 4858@itemx Printer6TextDevice 4859Integer (ranging from 0 to 2, for device 1-3) specifying what printer device 4860(@pxref{Printer settings}) the IEC printer is using. 4861 4862@vindex Printer4 4863@vindex Printer5 4864@vindex Printer6 4865@item Printer4 4866@itemx Printer5 4867@itemx Printer6 4868Integer specifying how the printer (device 4-6) is being emulated. 4869(0: None, 1: Filesystem, 2: Real) 4870 4871@vindex Printer7 4872@item Printer7 4873Integer specifying how printer 7 is being emulated. 4874(0: None, 2: Real) 4875 4876@vindex Printer4Driver 4877@item Printer4Driver 4878String specifying the printer output driver. 4879(raw, ascii, mps803, nl10) 4880 4881@vindex Printer5Driver 4882@item Printer5Driver 4883String specifying the printer output driver. 4884(raw, ascii, mps803, nl10) 4885 4886@vindex Printer6Driver 4887@item Printer6Driver 4888String specifying the printer output driver. 4889(raw, 1520) 4890 4891@vindex Printer4Output 4892@vindex Printer5Output 4893@vindex Printer6Output 4894@item Printer4Output 4895@itemx Printer5Output 4896@itemx Printer6Output 4897Strings specifying the IEC printer output device. 4898(text, graphics) 4899 4900@vindex PrinterUserport 4901@item PrinterUserport 4902Boolean specifying if the user-port printer is being emulated. 4903 4904@vindex PrinterUserportTextDevice 4905@item PrinterUserportTextDevice 4906Integer (ranging from 0 to 2, for device 1-3) specifying what printer 4907device the user-port printer is using. 4908 4909@vindex PrinterUserportDriver 4910@item PrinterUserportDriver 4911String specifying the user-port printer output driver. 4912(ascii/nl10/raw) 4913 4914@vindex PrinterUserportOutput 4915@item PrinterUserportOutput 4916String specifying the user-port printer output device. 4917(text, graphics) 4918 4919@end table 4920 4921@node Printer options, , Printer resources, Printer settings 4922@subsubsection Printer command-line options 4923 4924@table @code 4925 4926@findex -iecdevice4, +iecdevice4 4927@item -iecdevice4 4928@itemx +iecdevice4 4929Enable/disable IEC device emulation for device #4 4930(@code{IECDevice4=1}, @code{IECDevice4=0}). 4931 4932@findex -iecdevice5, +iecdevice5 4933@item -iecdevice5 4934@itemx +iecdevice5 4935Enable/disable IEC device emulation for device #5 4936(@code{IECDevice5=1}, @code{IECDevice5=0}). 4937 4938@findex -iecdevice6, +iecdevice6 4939@item -iecdevice6 4940@itemx +iecdevice6 4941Enable/disable IEC device emulation for device #6 4942(@code{IECDevice6=1}, @code{IECDevice6=0}). 4943 4944@findex -iecdevice7, +iecdevice7 4945@item -iecdevice7 4946@itemx +iecdevice7 4947Enable/disable IEC device emulation for device #7 4948(@code{IECDevice7=1}, @code{IECDevice7=0}). 4949 4950@findex -device4 4951@item -device4 <type> 4952Set device type for device 4 4953(@code{Printer4}). 4954(0: None, 1: Filesystem, 2: Real) 4955 4956@findex -device5 4957@item -device5 <type> 4958Set device type for device 5 4959(@code{Printer5}). 4960(0: None, 1: Filesystem, 2: Real) 4961 4962@findex -device6 4963@item -device6 <type> 4964Set device type for device 6 4965(@code{Printer6}). 4966(0: None, 1: Filesystem, 2: Real) 4967 4968@findex -device7 4969@item -device7 <type> 4970Set device type for device 7 4971(@code{Printer7}). 4972(0: None, 2: Real) 4973 4974@findex -prtxtdev1 4975@findex -prtxtdev2 4976@findex -prtxtdev3 4977@item -prtxtdev1 <name> 4978@itemx -prtxtdev2 <name> 4979@itemx -prtxtdev3 <name> 4980Specify name of printer text device or dump file 4981(@code{PrinterTextDevice1}, @code{PrinterTextDevice2}, @code{PrinterTextDevice3}). 4982 4983@findex -pr4txtdev 4984@findex -pr5txtdev 4985@findex -pr6txtdev 4986@item -pr4txtdev <0-2> 4987@itemx -pr5txtdev <0-2> 4988@itemx -pr6txtdev <0-2> 4989Specify printer text output device for IEC printer #4-6 4990(@code{Printer4TextDevice}, @code{Printer5TextDevice}, @code{Printer6TextDevice}). 4991 4992@findex -pr4output 4993@item -pr4output <name> 4994Specify name of output device for device #4 4995(@code{Printer4Output}). 4996(text, graphics) 4997 4998@findex -pr5output 4999@item -pr5output <name> 5000Specify name of output device for device #5 5001(@code{Printer5Output}). 5002(text, graphics) 5003 5004@findex -pr6output 5005@item -pr6output <name> 5006Specify name of output device for device #6 5007(@code{Printer6Output}). 5008(text, graphics) 5009 5010@findex -pr4drv 5011@item -pr4drv <name> 5012Specify name of printer driver for device #4 5013(@code{Printer4Driver}). 5014(raw, ascii, mps803, nl10) 5015 5016@findex -pr5drv 5017@item -pr5drv <name> 5018Specify name of printer driver for device #5 5019(@code{Printer5Driver}). 5020(raw, ascii, mps803, nl10) 5021 5022@findex -pr6drv 5023@item -pr6drv <name> 5024Specify name of printer driver for device #6 5025(@code{Printer6Driver}). 5026(raw, 1520) 5027 5028@findex -pruser, +pruser 5029@item -pruser 5030@itemx +pruser 5031Enable/disable emulation of the userport printer emulation 5032(@code{PrUser=1}, @code{PrUser=0}). 5033 5034@findex -prusertxtdev 5035@item -prusertxtdev <0-2> 5036Specify printer text output device for userport printer 5037(@code{PrinterUserportTextDevice}). 5038 5039@findex -pruseroutput 5040@item -pruseroutput <name> 5041Specify name of output device for the userport printer 5042(@code{PrinterUserportOutput}). 5043(text, graphics) 5044 5045@findex -pruserdrv 5046@item -pruserdrv <name> 5047Specify name of printer driver for the userport printer 5048(@code{PrinterUserportDriver}). 5049 5050@end table 5051 5052 5053@node No kernal traps, , Printer settings, Peripheral settings 5054@subsection Disabling kernal traps 5055 5056If you have compatibility problems, you can completely disable Kernal 5057traps with the ``Disable kernal traps'' option. This will of course 5058disable all the features that depend on it, such as the fast 1541 5059emulation (so you will have to turn true 1541 emulation on if you want 5060to be able to read or write disk images) and tape (t64) support. 5061 5062Since the 3.0 release kernal traps have been disabled by default to ensure 5063maximum compatibility. 5064 5065@menu 5066* No traps resources:: 5067* No traps options:: 5068@end menu 5069 5070@node No traps resources, No traps options, No kernal traps, No kernal traps 5071@subsubsection Resources to control Kernal traps 5072 5073@table @code 5074 5075@vindex VirtualDevices 5076@item VirtualDevices 5077Boolean specifying whether all the mechanisms for virtual device 5078emulation should be enabled. Serial IEC devices use kernal traps, 5079parallel IEEE488 devices use an own IEEE488 engine. Both are switched 5080on and off with this resource. 5081 5082@end table 5083 5084 5085@node No traps options, , No traps resources, No kernal traps 5086@subsubsection Command-line options to control Kernal traps 5087 5088@table @code 5089 5090@findex -virtualdev, +virtualdev 5091@item -virtualdev 5092@itemx +virtualdev 5093Enable/disable virtual devices 5094(@code{VirtualDevices=1}, @code{VirtualDevices=0}). 5095 5096@end table 5097 5098@c ---------------------------------------------------------------- 5099 5100@node RS232 settings, Monitor settings, Peripheral settings, Settings and resources 5101@section RS232 settings 5102 5103The VICE emulators can emulate the RS232 device most of the machines 5104have. The C64, C128 and VIC20 emulators emulate the userport RS232 5105interface at 300, 1200 and 2400 baud. The C64 and C128 can also use the 9600 5106baud interface by Daniel Dallmann, using the shift registers of the two 5107CIA 6526 chips. The PET can have a 6551 ACIA RS232 interface when 5108running as a SuperPET, and the CBM-II has such an ACIA by default. The 5109C64 and C128 emulators can emulate an ACIA 6551 (also known as Swithlink, Datapump 5110or Turbo232 for example) as extension at @code{$de**}. 5111 5112Emulation can be achieved by either: 5113 5114@itemize @bullet 5115@item 5116connecting a real UNIX serial device; 5117@item 5118dumping to a file; 5119@item 5120piping through a process. 5121@item 5122connect through a network socket. 5123@end itemize 5124 5125It is possible to define up to four UNIX serial devices, and then decide 5126which interface should be connected to which device. This is done by 5127so-called @dfn{rs232 device file names}; an rs232 device file name can 5128be either a simple path, a network address, or a command name preceeded 5129by a pipe symbol @samp{|}. 5130If the path specifies a special device (e.g. @file{/dev/ttyS0}) it 5131is recognized by VICE and the emulator can set the baudrate. 5132 5133For example, rs232 device @samp{filename} will cause the output to be 5134written (not appended) to the file @file{filename}, while printer device 5135@samp{|lpr} will cause the @code{lpr} command to be executed and be fed 5136the rs232 output. The rs232 output will not be converted but saved as 5137sent by the emulated machine. The same holds true for the rs232 input. 5138If the command writes data to the standard output it will be caught by VICE 5139and sent back to the emulator. Also the data sent by the pseudo device will 5140be sent back to VICE. 5141 5142For example you can setup a null-modem cable between two serial ports 5143of your PC, setup one port for login and use the other in VICE. Then you 5144can login from your emulator via the RS232 emulation and the null-modem 5145cable to your machine again. 5146 5147Up to four RS232 devices may be specified through the following 5148resources: 5149 5150@itemize @bullet 5151@item 5152device 1, whose default value is @code{/dev/ttyS0}; 5153@item 5154device 2, whose default value is @code{/dev/ttyS1}; 5155@item 5156device 3, whose default value is @code{127.0.0.1:25232}; 5157@item 5158device 4, whose default value is @code{|nc 127.0.0.1:25232}. 5159@end itemize 5160 5161You can change the baudrate the tty device is set to by specifying it on the 5162commandline or in the menu. 5163 5164@menu 5165* RS232 resources:: 5166* RS232 options:: 5167* RS232 usage:: 5168@end menu 5169 5170@node RS232 resources, RS232 options, RS232 settings, RS232 settings 5171@subsection RS232 resources 5172 5173@table @code 5174 5175@vindex RsDevice1 5176@vindex RsDevice2 5177@vindex RsDevice3 5178@vindex RsDevice4 5179@item RsDevice1 5180@itemx RsDevice2 5181@itemx RsDevice3 5182@itemx RsDevice4 5183Strings specifying the RS232 devices (@pxref{RS232 settings}). 5184 5185@end table 5186 5187@table @code 5188 5189@vindex RsDevice1ip232 5190@vindex RsDevice2ip232 5191@vindex RsDevice3ip232 5192@vindex RsDevice4ip232 5193@item RsDevice1ip232 5194@itemx RsDevice2ip232 5195@itemx RsDevice3ip232 5196@itemx RsDevice4ip232 5197Boolean specifying whether the respective RS232 devices (@pxref{RS232 settings}) 5198use the IP232 protocol supported by tcpser. 5199This only works with Socket connections. 5200 5201@end table 5202 5203@table @code 5204 5205@vindex Acia1Enable 5206@item Acia1Enable 5207Boolean specifying whether the ACIA (Swiftlink, Turbo232) cartridge should be emulated or not 5208(x64, x64sc, xscpu64, x128 and xvic only, and only if RS232 support is enabled and supported at compile time). 5209 5210@vindex Acia1Dev 5211@item Acia1Dev 5212Integer specifying what RS232 device (@pxref{RS232 settings}) the ACIA is using 5213(all emulators except x64dtv and vsid, and only if RS232 support is enabled and supported at compile time). 5214 5215@vindex Acia1Base 5216@item Acia1Base 5217Integer specifying the base address for the emulated ACIA chip (x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time). 5218(xvic: $9800/$9C00, x128: $D700/$DE00/$DF00, x64, x64sc, xscpu64: $DE00/$DF00) 5219 5220@vindex Acia1Mode 5221@item Acia1Mode 5222Integer specifying the type of emulated RS232 interface (x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time). 5223(0: normal, 1: Swiftlink, 2: Turbo232) 5224 5225@vindex Acia1Irq 5226@item Acia1Irq 5227Integer specifying which interrupt to use (x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time). 5228(0 = none, 1 = NMI, 2 = IRQ) 5229 5230@end table 5231 5232@table @code 5233 5234@vindex RsUserEnable 5235@item RsUserEnable 5236Boolean specifying if the user-port RS232 interface is being emulated 5237(C64, C128 and VIC20). 5238 5239@vindex RsUserBaud 5240@item RsUserBaud 5241Integer specifying the baudrate of the user-port RS232 interface 5242(C64, C128 and VIC20). 5243 5244@vindex RsUserDev 5245@item RsUserDev 5246Integer (ranging from 0 to 3, for device 1-4) specifying what RS232 device 5247the user-port interface is using (C64, C128 and VIC20). 5248 5249@end table 5250 5251@b{The following resources are only available if RS232 device support or RS232 network support is available at compile time.} 5252 5253@table @code 5254 5255@vindex RsDevice1Baud 5256@vindex RsDevice2Baud 5257@vindex RsDevice3Baud 5258@vindex RsDevice4Baud 5259@item RsDevice1Baud 5260@itemx RsDevice2Baud 5261@itemx RsDevice3Baud 5262@itemx RsDevice4Baud 5263Integers specifying the RS232 baudrate devices if the device file points 5264to a special device (like @file{/dev/ttyS0}; @pxref{RS232 settings}) 5265(all emulators except vsid). 5266 5267@end table 5268 5269@node RS232 options, RS232 usage, RS232 resources, RS232 settings 5270@subsection RS232 command-line options 5271 5272@table @code 5273 5274@findex -rsdev1 5275@item -rsdev1 <Name> 5276@findex -rsdev2 5277@itemx -rsdev2 <Name> 5278@findex -rsdev3 5279@itemx -rsdev3 <Name> 5280@findex -rsdev4 5281@itemx -rsdev4 <Name> 5282Specify <Name> as RS232 devices 1, 2, 3 and 4, respectively 5283(@code{RsDevice1}, @code{RsDevice2} @code{RsDevice3} and @code{RsDevice4}). 5284 5285@end table 5286 5287@table @code 5288 5289@findex -rsdev1ip232, +rsdev1ip232 5290@item -rsdev1ip232 5291@itemx +rsdev1ip232 5292@findex -rsdev2ip232, +rsdev2ip232 5293@item -rsdev2ip232 5294@itemx +rsdev2ip232 5295@findex -rsdev3ip232, +rsdev3ip232 5296@item -rsdev3ip232 5297@itemx +rsdev3ip232 5298@findex -rsdev4ip232, +rsdev4ip232 5299@item -rsdev4ip232 5300@itemx +rsdev4ip232 5301Enable/Disable whether the respective RS232 devices (@pxref{RS232 settings}) 5302use the IP232 protocol supported by tcpser. 5303This only works with Socket connections. 5304 5305@end table 5306 5307@table @code 5308 5309@findex -acia1, +acia1 5310@item -acia1 5311@itemx +acia1 5312Enable/Disable the $DE** ACIA RS232 interface emulation 5313(@code{Acia1Enable=1}, @code{Acia1Enable=0}) 5314(x64, x64sc, xscpu64, x128 and xvic only, and only if RS232 support is enabled and supported at compile time). 5315 5316@findex -myaciadev 5317@item -myaciadev <0-3> 5318Specify RS232 device the ACIA should work on 5319(all emulators except x64dtv and vsid, and only if RS232 support is enabled and supported at compile time) 5320 5321@findex -acia1base 5322@item -acia1base <Base address> 5323Set the base address of the ACIA cartridge 5324(@code{Acia1Base}) 5325(x64, x64sc, xscpu, x128 and xvic only, and only if RS232 support is enabled and supported at compile time). 5326(xvic: $9800/$9C00, x128: $D700/$DE00/$DF00, x64, x64sc, xscpu: $DE00/$DF00) 5327 5328@findex -acia1mode 5329@item -acia1mode <mode> 5330Set the ACIA mode 5331(@code{Acia1Mode}) 5332(x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time). 5333(0: Normal, 1: Swiftlink, 2: Turbo232) 5334 5335@findex -acia1irq 5336@item -acia1irq <interrupt> 5337Set the ACIA interrupt 5338(@code{Acia1Irq}) 5339(x64, x64sc, xscpu64, xvic and x128 only, and only if RS232 support is enabled and supported at compile time). 5340(0: None, 1: NMI, 2: IRQ) 5341 5342@end table 5343 5344@table @code 5345 5346@findex -rsuser, +rsuser 5347@item -rsuser 5348@itemx +rsuser 5349Enable or disable emulation of the 5350userport RS232 emulation (@code{RsUser}; C64, C128 and VIC20) 5351 5352@findex -rsuserbaud 5353@item -rsuserbaud <baud> 5354Set the baud rate of the RS232 userport emulation. 5355 5356@findex -rsuserdev 5357@item -rsuserdev <0-3> 5358Specify device for the userport RS232 emulation (@code{RsUserDev}; 5359C64, C128 and VIC20). 5360 5361@end table 5362 5363@b{The following command-line options are only available if RS232 device support or RS232 network support is available at compile time.} 5364 5365@table @code 5366 5367@findex -rsdev1baud 5368@item -rsdev1baud <baudrate> 5369@findex -rsdev2baud 5370@itemx -rsdev2baud <baudrate> 5371@findex -rsdev3baud 5372@itemx -rsdev3baud <baudrate> 5373@findex -rsdev4baud 5374@itemx -rsdev4baud <baudrate> 5375Specify <baudrate> as baudrate for the RS232 devices if the device name 5376specifies a special device (like @file{/dev/ttyS0} for example, 5377@pxref{RS232 settings}; 5378@code{RsDevice1Baud}, @code{RsDevice2Baud} @code{RsDevice3Baud} and 5379@code{RsDevice4Baud}) 5380(all emulators except vsid). 5381 5382@end table 5383 5384@node RS232 usage, , RS232 options, RS232 settings 5385@subsection RS232 usage example 5386 5387Here we give you a simple example how to set up an emulated C64 using 5388the modem connected to your PC. The following list shows each step. 5389 5390@table @code 5391@item Attach your modem to your PC at a serial port. 5392Normally you should set it up to use the modem as "/dev/modem". 5393@item start VICE 5394 5395@item Setup VICE to use your modem as "serial device 1" 5396Go to the RS232 settings menu and change "Serial 1 device" to "/dev/modem" 5397(or the device where you attached your modem to) 5398Then go to the RS232 settings menu and change "Serial 1 baudrate" to the 5399baudrate your modem should run at. 5400 Watch out, e.g. on Linux there is an additional multiplier 5401 to multiply with the baudrate (so e.g. 19200 gives 115200 or so baud) 5402 See the "setserial" manpage on Linux for example. 5403 However, most modems should be able to autodetect the speed to 5404 the computer as well. 5405 5406@item Select the RS232 emulation your programs use 5407If you want to use the Userport emulation, go to the RS232 settings and 5408 change "Userport RS232 Device" to 5409 "Serial 1". If you want ACIA emulation (swiftlink or what's it called?) 5410 then change "ACIA $DE** device" to "Serial 1". 5411 5412@item Enable the emulation 5413 Go to the RS232 settings and select either "ACIA $DE** emulation" 5414 or Userport 300/1200 baud or CIA 9600 baud emulation. 5415 5416@item Load your program and start it. 5417If it is able to detect an 5418 RS232 cartridge like swiftlink or so, try to detect the ACIA emulation 5419 if enabled. 5420 Otherwise just set the baudrate to either 300, 1200, 2400 or 9600 according 5421 to what you enabled in the VICE menu for the userport. 5422 5423@end table 5424 5425@c ----------------------------------------------------------------------------- 5426 5427@c @node FIXME 5428@section Tape port devices 5429 5430@c @node FIXME 5431@subsection Tape port resources 5432 5433@table @code 5434 5435@vindex CPClockF83 5436@item CPClockF83 5437Boolean specifying whether the CP Clock F83 (PCF8583 RTC) is enabled. 5438 5439@vindex CPClockF83Save 5440@item CPClockF83Save 5441Boolean specifying whether the CP Clock F83 (PCF8583 RTC) data is saved when changed. 5442 5443@vindex TapeSenseDongle 5444@item TapeSenseDongle 5445Boolean specifying whether the tape sense dongle is enabled. 5446 5447@vindex DTLBasicDongle 5448@item DTLBasicDongle 5449Boolean specifying whether the DTL Basic dongle is enabled. 5450 5451@vindex TapecartEnabled 5452@item TapecartEnabled 5453Boolean that specifies if a tapecart is attached. 5454 5455@vindex TapecartUpdateTCRT 5456@item TapecartUpdateTCRT 5457Boolean, if true write back the tapecart memory contents back to the 5458.tcrt file when detaching the image or quitting the emulator. 5459 5460@vindex TapecartOptimizeTCRT 5461@item TapecartOptimizeTCRT 5462Boolean, when set to true the .tcrt image will be optimized by leaving 5463out blank space at the end when saving. 5464 5465@vindex TapecartLogLevel 5466@item TapecartLogLevel 5467Integer that specifies the tapecart emulation log level. At the default 5468level of 0, only errors are logged. Level 1 additionally logs mode 5469changes and command bytes and level 2 adds details of command 5470parameters. 5471 5472@vindex TapecartTCRTFilename 5473@item TapecartTCRTFilename 5474String specifying the file name of the current tapecart image. 5475 5476@end table 5477 5478@c @node FIXME 5479@subsection Tape port command line options 5480 5481@table @code 5482 5483@findex -cpclockf83, +cpclockf83 5484@item -cpclockf83 5485@itemx +cpclockf83 5486Enable/Disable CP Clock F83 (PCF8583 RTC) 5487(@code{CPClockF83=1}, @code{CPClockF83=0}). 5488 5489@findex -cpclockf83save, +cpclockf83save 5490@item -cpclockf83save 5491@itemx +cpclockf83save 5492Enable/Disable saving of the CP Clock F83 (PCF8583 RTC) data when changed 5493 (@code{CPClockF83Save=1}, @code{CPClockF83Save=0}). 5494 5495@findex -tapesensedongle, +tapesensedongle 5496@item -tapesensedongle 5497@itemx +tapesensedongle 5498Enable/Disable tape sense dongle 5499 (@code{TapeSenseDongle=1}, @code{TapeSenseDongle=0}). 5500 5501@findex -dtlbasicdongle, +dtlbasicdongle 5502@item -dtlbasicdongle 5503@itemx +dtlbasicdongle 5504Enable/Disable DTL Basic dongle 5505 (@code{DTLBasicDongle=1}, @code{DTLBasicDongle=0}). 5506 5507@findex -tapecart, +tapecart 5508@item -tapecart 5509@itemx +tapecart 5510Enable/disable tapecart emulation 5511(@code{TapecartEnabled=1}, @code{TapecartEnabled=0}) 5512 5513@findex -tcrt 5514@item -tcrt <name> 5515Specify tapecart .tcrt image filename 5516(@code{TapecartTCRTFilename}) 5517 5518@findex -tapecartupdatetcrt, +tapecartupdatetcrt 5519@item -tapecartupdatetcrt 5520@itemx +tapecartupdatetcrt 5521Specify if the attached .tcrt image should be updated when the emulated 5522tapecart is written to. 5523(@code{TapecartUpdateTCRT=1}, @code{TapecartUpdateTCRT=0}) 5524 5525@findex -tapecartoptimizetcrt, +tapecartoptimizetcrt 5526@item -tapecartoptimizetcrt 5527@itemx +tapecartoptimizetcrt 5528Specify if writing to a .tcrt file should optimize its size by leaving 5529out blank space at the end. 5530(@code{TapecartOptimizeTCRT=1}, @code{TapecartOptimizeTCRT=0}) 5531 5532@findex -tapecartloglevel 5533@item -tapecartloglevel <number> 5534Specify the tapecart log level. The default level of 0 only logs 5535errors. Level 1 additionally logs mode changes and command bytes and 5536level 2 adds details of command parameters. 5537 5538@end table 5539 5540@c ----------------------------------------------------------------------------- 5541 5542@c @node FIXME 5543@section Userport devices 5544 5545@c @node FIXME 5546@subsection Userport resources 5547 5548@table @code 5549 5550@vindex UserportCollisionHandling 5551@item UserportCollisionHandling 5552Boolean specifying the way the Userport collisions should be handled, (0: error message and 5553 detach all involved devices, 1: error message and detach last attached involved 5554 device, 2: warning in log and 'AND' the valid return values) 5555 5556@vindex UserportDIGIMAX 5557@item UserportDIGIMAX 5558Boolean specifying whether the userport DigiMAX device is enabled. 5559 5560@vindex Userport4bitSampler 5561@item Userport4bitSampler 5562Boolean specifying whether the Userport 4bit sampler is enabled. 5563 5564@vindex Userport8BSS 5565@item Userport8BSS 5566Boolean specifying whether the Userport 8bit stereo sampler is enabled. 5567 5568@vindex UserportRTC58321a 5569@item UserportRTC58321a 5570Boolean specifying whether the userport RTC is emulated or not 5571(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5572 5573@vindex UserportRTC58321aSave 5574@item UserportRTC58321aSave 5575Boolean specifying whether the userport RTC data is saved when changed or not 5576(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5577 5578@vindex UserportRTCDS1307 5579@item UserportRTCDS1307 5580Boolean specifying whether the userport RTC is emulated or not 5581(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5582 5583@vindex UserportRTCDS1307Save 5584@item UserportRTCDS1307Save 5585Boolean specifying whether the userport RTC data is saved when changed or not 5586(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5587 5588@end table 5589 5590@c @node FIXME 5591@subsection Userport command line options 5592 5593@table @code 5594 5595@findex -userportcollision 5596@item -userportcollision 5597Select the way the Userport collisions should be handled, (0: error message and 5598 detach all involved devices, 1: error message and detach last attached involved 5599 device, 2: warning in log and 'AND' the valid return values) 5600(@code{UserportCollisionHandling}) 5601 5602 @findex -userportdigimax, +userportdigimax 5603@item -userportdigimax 5604@itemx +userportdigimax 5605Enable/Disable the userport DigiMAX device 5606(@code{UserportDIGIMAX=1}, @code{UserportDIGIMAX=0}) 5607 5608@findex -userport4bitsampler, +userport4bitsampler 5609@item -userport4bitsampler 5610@itemx +userport4bitsampler 5611Enable/Disable Userport 4bit sampler 5612(@code{Userport4bitSampler=1}, @code{Userport4bitSampler=0}) 5613 5614@findex -userport8bss, +userport8bss 5615@item -userport8bss 5616@itemx +userport8bss 5617Enable/Disable Userport 8bit stereo sampler 5618(@code{Userport8BSS=1}, @code{Userport8BSS=0}) 5619 5620@findex -userportrtc58321a, +userportrtc58321a 5621@item -userportrtc58321a 5622@itemx +userportrtc58321a 5623Enable/disable the userport RTC emulation 5624(@code{UserportRTC58321a=1}, @code{UserportRTC58321a=0}) 5625(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5626 5627@findex -userportrtc58321asave, +userportrtc58321asave 5628@item -userportrtc58321asave 5629@itemx +userportrtc58321asave 5630Disable/enable saving of the userport RTC data when changed 5631(@code{UserportRTC58321aSave=1}, @code{UserportRTC58321aSave=0}) 5632(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5633 5634@findex -userportrtcds1307, +userportrtcds1307 5635@item -userportrtcds1307 5636@itemx +userportrtcds1307 5637Enable/disable the userport RTC emulation 5638(@code{UserportRTCDS1307=1}, @code{UserportRTCDS1307=0}) 5639(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5640 5641@findex -userportrtcds1307save, +userportrtcds1307save 5642@item -userportrtcds1307save 5643@itemx +userportrtcds1307save 5644Disable/enable saving of the userport RTC data when changed 5645(@code{UserportRTCDS1307Save=1}, @code{UserportRTCDS1307Save=0}) 5646(xpet, cbm2, x64, x64sc, xscpu64 and x128 only). 5647 5648@end table 5649 5650@c ----------------------------------------------------------------------------- 5651 5652@node Monitor settings, Misc settings, RS232 settings, Settings and resources 5653@section Monitor settings 5654 5655This section lists command-line options specific to the built-in monitor. 5656 5657@menu 5658* Monitor options:: 5659@end menu 5660 5661@node Monitor options, , , Monitor settings 5662 5663@c @node FIXME 5664@subsection Monitor resources 5665 5666@table @code 5667 5668@vindex KeepMonitorOpen 5669@item KeepMonitorOpen 5670Boolean, if true the monitor window may stay open when the emulation is running, 5671eg to look at trace-point output. (Not all ports/UIs support this, in that case 5672this setting has no effect.) 5673 5674@vindex RefreshOnBreak 5675@item RefreshOnBreak 5676Boolean, if true, the emulated display(s) will update as the monitor is entered 5677and also after each command executed via the monitor. Not entirely accurate yet, 5678as updates become visible one scanline at a time. In addtion, the image can be not 5679quite right around the raster line being updated. 5680 5681@vindex MonitorServer 5682@item MonitorServer 5683Boolean specifying whether the remote monitor server is enabled. 5684 5685@vindex MonitorServerAddress 5686@item MonitorServerAddress 5687String specifying the address the remote monitor server listens to (ip4://127.0.0.1:6510) 5688 5689@vindex BinaryMonitorServer 5690@item BinaryMonitorServer 5691Boolean specifying whether the binary monitor server is enabled. 5692 5693@vindex BinaryMonitorServerAddress 5694@item BinaryMonitorServerAddress 5695String specifying the address the binary monitor server listens to (ip4://127.0.0.1:6502) 5696 5697@vindex NativeMonitor 5698@item NativeMonitor 5699Boolean specifying whether the native monitor is enabled. When enabled, the monitor 5700 will not run in the interface of the emulator, but instead work in the spawning 5701 terminal. 5702 5703@vindex MonitorLogEnabled 5704@item MonitorLogEnabled 5705Boolean specifying whether the output of the monitor will be logged to a file. 5706 5707@vindex MonitorLogFileName 5708@item MonitorLogFileName 5709String specifying the logfile name for the monitor. 5710 5711@vindex MonitorChisLines 5712@item MonitorChisLines 5713Integer specifying the number of lines to keep in the cpu history. (only when enabled in configure) 5714 5715@vindex MonitorScrollbackLines 5716@item MonitorScrollbackLines 5717Integer specifying the number of lines to keep in the monitor scrollback buffer (-1 for no limit). 5718 5719@vindex MonitorFont 5720@item MonitorFont 5721String specifying the font to use in the Gtk3 UI's VTE monitor window. Should be in the form accepted by Pango, for example "Liberation Mono 11". 5722 5723@end table 5724 5725@subsection Monitor command-line options 5726 5727@table @code 5728@findex -moncommands 5729@item -moncommands <Name> 5730Execute the commands from the file <Name> in the monitor after starting up. All 5731monitor commands are supported, including playback of other command files via 5732@code{pb}. By default, the monitor opens and starts executing the commands just 5733before the kernal reset routine starts. The kernal starup sequence may interfere 5734with what you are trying to achieve, for example by clearing any basic listing 5735you may have loaded. In this case, use the @code{-initbreak} option to control 5736when the monitor will open and execute your script. You can choose an address, 5737or use @code{-initbreak ready} to attempt to detect when the kernel is ready 5738and execute the script then. 5739 5740@findex -initbreak 5741@item -initbreak <address> 5742@item -initbreak reset 5743@item -initbreak ready 5744Set an initial breakpoint for the monitor. Addresses with prefix "0x" are hexadecimal. 5745@code{-initbreak reset} will break just before the reset routine starts. 5746@code{-initbreak ready} will attempt to break when the kernal is 'ready'. 5747 5748@findex -keepmonopen, +keepmonopen 5749@item -keepmonopen 5750@itemx +keepmonopen 5751Enable/disable keeping the monitor window open 5752(@code{KeepMonitorOpen=1}, @code{KeepMonitorOpen=0}). 5753 5754@findex -refreshonbreak, +refreshonbreak 5755@item -refreshonbreak 5756@itemx +refreshonbreak 5757Enable/Disable refresh display when entering monitor and after each monitor command. 5758(@code{RefreshOnBreak=1}, @code{RefreshOnBreak=0}). 5759 5760@findex -remotemonitor, +remotemonitor 5761@item -remotemonitor 5762@itemx +remotemonitor 5763Enable/Disable remote monitor 5764 5765@findex -remotemonitoraddress 5766@item -remotemonitoraddress <name> 5767The local address the remote monitor should bind to 5768 5769@findex -binarymonitor, +binarymonitor 5770@item -binarymonitor 5771@itemx +binarymonitor 5772Enable/Disable binary monitor 5773 5774@findex -binarymonitoraddress 5775@item -binarymonitoraddress <name> 5776The local address the binary monitor should bind to 5777 5778@findex -nativemonitor, +nativemonitor 5779@item -nativemonitor 5780@itemx +nativemonitor 5781Enable/Disable native monitor. 5782(@code{NativeMonitor=1}, @code{NativeMonitor=0}). 5783 5784@findex -monlog, +monlog 5785@item -monlog 5786@itemx +monlog 5787Enable/Disable logging monitor output to a file. 5788(@code{MonitorLogEnabled=1}, @code{MonitorLogEnabled=0}). 5789 5790@findex -monlogname 5791@item -monlogname <name> 5792Specify logfile name for the monitor. 5793(@code{MonitorLogFileName}). 5794 5795@findex -monchislines 5796@item -monchislines <value> 5797Set number of lines to keep in the cpu history. (only when enabled in configure) 5798(@code{MonitorChisLines}). 5799 5800@findex -monscrollbacklines 5801@item -monscrollbacklines <value> 5802Set number of lines to keep in the monitor scrollback buffer (-1 for no limit). 5803(@code{MonitorScrollbackLines}). 5804 5805@findex -monitorfont 5806@item -monitorfont <font-description> 5807Set the monitor font for the Gtk3 UI's VTE-monitor. 5808(@code{MonitorFont}). 5809 5810@end table 5811 5812@c ---------------------------------------------------------------- 5813 5814@c @node FIXME 5815@section RAM init pattern settings 5816 5817The initial content of uninitialized RAM depends on many factors, the inner 5818workings of the RAM chip, the motherboard, etc. Generally, many RAM chips are 5819build in a way that - however - at powerup about half the bits turn out 1, and 5820about the other half turns out 0. As a consequence, and depending on what kind 5821of RAM chips have been used in what kind of way, the typical patterns can be 5822"seen" by the CPU right after powerup. 5823 5824VICE tries to model (some of) the real patterns accurately. Please be aware of 5825the fact that there is - technically buggy - software out there that will only 5826work with a certain RAM init pattern. 5827 5828How generating the pattern works is easily described in three simple steps: 5829 58301. A base pattern is created using blocks of @code{RAMInitStartValue}, which 5831 is inverted every @code{RAMInitValueInvert} bytes. This pattern can be offset 5832 ("rotated") by @code{RAMInitValueOffset} bytes. This step creates the typical 5833 00 00 ff ff ff ff 00 00 etc patterns. 5834 58352. Every @code{RAMInitPatternInvert} bytes the base pattern is inverted 5836 ("xored") by @code{RAMInitPatternInvertValue}. This step creates the inverted 5837 pattern every $4000 or so bytes that is typical for some boards/ICs. It may 5838 also create the 0x99, 0x66 based patterns that show up on other setups. 5839 58403. Every @code{RAMInitRepeatRandom} bytes @code{RAMInitStartRandom} bytes are 5841 randomly inverted ("xored"). Additionally every bit is randomly inverted with 5842 a @code{RAMInitRandomChance} : 4096 chance. This step creates the typical 5843 random bytes that have been observed with some boards/ICs. 5844 5845@c @node FIXME 5846@subsection RAM init pattern resources 5847 5848@table @code 5849 5850@vindex RAMInitStartValue 5851@item RAMInitStartValue 5852Integer specifying the first value of the base pattern 5853(all emulators except vsid). 5854(0..255) 5855 5856@vindex RAMInitValueInvert 5857@item RAMInitValueInvert 5858Integer specifying the number of bytes until the base pattern is inverted 5859(all emulators except vsid). 5860 5861@vindex RAMInitValueOffset 5862@item RAMInitValueOffset 5863Integer specifying the number of bytes to offset the base pattern 5864(all emulators except vsid). 5865 5866@vindex RAMInitPatternInvert 5867@item RAMInitPatternInvert 5868Integer specifying the length of the memory block when inverting the base pattern 5869(all emulators except vsid). 5870 5871@vindex RAMInitPatternInvertValue 5872@item RAMInitPatternInvertValue 5873Integer specifying the value to use for inverting the base pattern with 5874(all emulators except vsid). 5875 5876@vindex RAMInitStartRandom 5877@item RAMInitStartRandom 5878Integer specifying the number of random bytes in the random pattern 5879(all emulators except vsid). 5880 5881@vindex RAMInitRepeatRandom 5882@item RAMInitRepeatRandom 5883Integer specifying the number of bytes after which to repeat the random pattern 5884(all emulators except vsid). 5885 5886@vindex RAMInitRandomChance 5887@item RAMInitRandomChance 5888Integer specifying the chance of any bit to randomly toggle (0-4096) 5889(all emulators except vsid). 5890 5891@end table 5892 5893@c @node FIXME 5894@subsection RAM init pattern command-line options 5895 5896@table @code 5897 5898@findex -raminitstartvalue 5899@item -raminitstartvalue <value> 5900Set the first value of the base pattern 5901(@code{RAMInitStartValue}) 5902(all emulators except vsid). 5903(0..255) 5904 5905@findex -raminitvalueinvert 5906@item -raminitvalueinvert <num of bytes> 5907Set the number of bytes until the base pattern is inverted 5908(@code{RAMInitValueInvert}) 5909(all emulators except vsid). 5910 5911@findex -raminitvalueoffset 5912@item -raminitvalueoffset <num of bytes> 5913Offset the first pattern by <num> of bytes 5914(@code{RAMInitValueOffset}) 5915(all emulators except vsid). 5916 5917@findex -raminitpatterninvert 5918@item -raminitpatterninvert <num of bytes> 5919Set the length of the memory block when inverting the base pattern 5920(@code{RAMInitPatternInvert}) 5921(all emulators except vsid). 5922 5923@findex -raminitpatterninvertvalue 5924@item -raminitpatterninvertvalue <value> 5925Set the length of the memory block when inverting the base pattern 5926(@code{RAMInitPatternInvertValue}) 5927(all emulators except vsid). 5928 5929@findex -raminitstartrandom 5930@item -raminitstartrandom <num of bytes> 5931Set the number of random bytes in the random pattern 5932(@code{RAMInitStartRandom}) 5933(all emulators except vsid). 5934 5935@findex -raminitrepeatrandom 5936@item -raminitrepeatrandom <num of bytes> 5937Set the number of bytes after which to repeat the random pattern 5938(@code{RAMInitRepeatRandom}) 5939(all emulators except vsid). 5940 5941@findex -raminitrandomchance 5942@item -raminitrandomchance <value> 5943Set the chance of any bit to randomly toggle (0-4096) 5944(@code{RAMInitRandomChance}) 5945(all emulators except vsid). 5946 5947@end table 5948 5949@c ---------------------------------------------------------------- 5950 5951@c @node FIXME 5952@section Debug settings 5953 5954@c @node FIXME 5955@subsection Debug resources 5956 5957@table @code 5958 5959@vindex TapeLog 5960@item TapeLog 5961Boolean specifying whether the tape log device is enabled. 5962 5963@vindex TapeLogDestination 5964@item TapeLogDestination 5965Integer specifying where the tape log goes to (0=Enable logging to the emulator log file 1=Enable logging to a file). 5966 5967@vindex TapeLogfilename 5968@item TapeLogfilename 5969String that specifies the tape log file name 5970 5971@vindex DebugCartEnable 5972@item DebugCartEnable 5973Boolean specifying whether the debug "cartridge" used for the test suite is enabled. 5974 5975@b{The following are only available when the emulators were compiled in DEBUG mode:} 5976 5977@vindex TraceMode 5978@item TraceMode 5979Integer specifying the trace mode (0=normal 1=small 2=history) 5980 5981@vindex AutoPlaybackFrames 5982@item AutoPlaybackFrames 5983Amount of automatic playback frames 5984 5985@vindex MainCPU_TRACE 5986@item MainCPU_TRACE 5987Trace the main CPU / Do not trace the main CPU 5988@vindex Drive0CPU_TRACE 5989@item Drive0CPU_TRACE 5990Trace the drive 0 CPU / Do not trace the drive 0 CPU 5991@vindex Drive1CPU_TRACE 5992@item Drive1CPU_TRACE 5993Trace the drive 1 CPU / Do not trace the drive 1 CPU 5994@vindex Drive2CPU_TRACE 5995@item Drive2CPU_TRACE 5996Trace the drive 2 CPU / Do not trace the drive 2 CPU 5997@vindex Drive3CPU_TRACE 5998@item Drive3CPU_TRACE 5999Trace the drive 3 CPU / Do not trace the drive 3 CPU 6000 6001@vindex IEC_TRACE 6002@item IEC_TRACE 6003Trace IEC bus activity / Do not trace IEC bus activity 6004 6005@end table 6006 6007@c @node FIXME 6008@subsection Debug command-line options 6009 6010@table @code 6011 6012@findex -core, +core 6013@item -core 6014@itemx +core 6015Enable/disable generation of core dumps 6016(@code{DoCoreDump=1}, @code{DoCoreDump=0}) 6017(all emulators except vsid). 6018 6019@findex -debug, +debug 6020@item -debug 6021@itemx +debug 6022Disable/enable calling of the exception handler 6023(@code{DoCoreDump=1}, @code{DoCoreDump=0}) 6024(all emulators except vsid). 6025 6026@findex -debugcart, +debugcart 6027@item -debugcart 6028@itemx +debugcart 6029Enable/disable the debug "cartridge" used for the test suite. 6030 6031@findex -tapelog, +tapelog 6032@item -tapelog 6033@itemx +tapelog 6034Enable/Disable the tape log device. (@code{TapeLog=1}, @code{TapeLog=0}). 6035 6036@findex -tapelogtofile 6037@item -tapelogtofile 6038Enable logging to a file (@code{TapeLogDestination=1}). 6039 6040@findex -tapelogtolog 6041@item -tapelogtolog 6042Enable logging to the emulator log file (@code{TapeLogDestination=0}). 6043 6044@findex -tapelogimage 6045@item -tapelogimage <name> 6046Specify tape log file name (@code{TapeLogfilename}). 6047 6048@b{The following are only available when the emulators were compiled in DEBUG mode:} 6049 6050@findex -trace_maincpu, +trace_maincpu 6051@item -trace_maincpu 6052@itemx +trace_maincpu 6053Trace the main CPU / Do not trace the main CPU (@code{MainCPU_TRACE=1}, @code{MainCPU_TRACE=0}) 6054 6055@findex -trace_drive0, +trace_drive0 6056@item -trace_drive0 6057@itemx +trace_drive0 6058Trace the drive 0 CPU / Do not trace the drive 0 CPU (@code{Drive0CPU_TRACE=1}, @code{Drive0CPU_TRACE=0}) 6059 6060@findex -trace_drive1, +trace_drive1 6061@item -trace_drive1 6062@itemx +trace_drive1 6063Trace the drive 1 CPU / Do not trace the drive 1 CPU (@code{Drive1CPU_TRACE=1}, @code{Drive1CPU_TRACE=0}) 6064 6065@findex -trace_drive2, +trace_drive2 6066@item -trace_drive2 6067@itemx +trace_drive2 6068Trace the drive 2 CPU / Do not trace the drive 2 CPU (@code{Drive2CPU_TRACE=1}, @code{Drive2CPU_TRACE=0}) 6069 6070@findex -trace_drive3, +trace_drive3 6071@item -trace_drive3 6072@itemx +trace_drive3 6073Trace the drive 3 CPU / Do not trace the drive 3 CPU (@code{Drive3CPU_TRACE=1}, @code{Drive3CPU_TRACE=0}) 6074 6075@findex -trace_iec, +trace_iec 6076@item -trace_iec 6077@itemx +trace_iec 6078Trace IEC bus activity / Do not trace IEC bus activity (@code{IEC_TRACE=1}, @code{IEC_TRACE=0}) 6079 6080@findex -trace_mode 6081@item -trace_mode <value> 6082Trace mode (0=normal 1=small 2=history) 6083 6084@findex -autoplaybackframes 6085@item -autoplaybackframes <frames> 6086Set the amount of automatic playback frames 6087 6088@end table 6089 6090@c ---------------------------------------------------------------- 6091 6092@c @node FIXME 6093@section Network Play settings 6094 6095@c @node FIXME 6096@subsection Network Play resources 6097 6098@table @code 6099 6100@vindex NetworkServerName 6101@item NetworkServerName 6102String specifying the name of the remote server. 6103 6104@vindex NetworkServerBindAddress 6105@item NetworkServerBindAddress 6106String specifying the IP of the remote server. 6107 6108@vindex NetworkServerPort 6109@item NetworkServerPort 6110Integer specifying the port used for network play. 6111@c FIXME: is this correct? 6112 6113@vindex NetworkControl 6114@item NetworkControl 6115Integer specifying whether the emulator is running as server or client (0: client, 61161: server) 6117 6118@end table 6119 6120@c @node FIXME 6121@subsection Network Play command-line options 6122 6123@table @code 6124 6125@findex -netplayserver 6126@item -netplayserver <name> 6127Set the name of the remote server. 6128 6129@findex -netplaybind 6130@item -netplaybind <ip> 6131Set the IP of the remote server. 6132 6133@findex -netplayport 6134@item -netplayport <port> 6135Set the port used for network play. 6136 6137@findex -netplayctrl 6138@item -netplayctrl <flag> 6139Specify whether the emulator is running as server or client (0: client, 1: server) 6140 6141@end table 6142 6143@c ---------------------------------------------------------------- 6144 6145@node Misc settings, , Monitor settings, Settings and resources 6146@section Miscellaneous settings 6147 6148This section lists generic resources that do not fit in the other 6149categories. 6150 6151@menu 6152* Misc resources:: 6153* Misc options:: 6154@end menu 6155 6156@node Misc resources, Misc options, Misc settings, Misc settings 6157@subsection Miscellaneous resources 6158 6159@table @code 6160@vindex JAMAction 6161@item JAMAction 6162Integer specifying the action to take when the CPU encounters a 'JAM' opcode. 6163(0: show dialog, 1: continue emulation, 2: start monitor, 3: soft reset, 4: hard reset, 5: quit emulator) 6164 6165@vindex Directory 6166@item Directory 6167String specifying the search path for system files. It is defined as a 6168sequence of directory names, separated by colons (@samp{:}), just like 6169the @code{PATH} variable in the shell. The special string @samp{$$} 6170stands for the default search path. 6171 6172@c FIXME: add the following section to archdep stuff: 6173@ifset dummy 6174, which is initialized at startup to 6175the following value: 6176 6177@example 6178LIBDIR/EMUID:$HOME/.vice/EMUID:BOOTPATH/EMUID:LIBDIR/DRIVES:$HOME/.vice/DRIVES:BOOTPATH/DRIVES 6179@end example 6180 6181where: 6182 6183@itemize @bullet 6184@item 6185@code{LIBDIR} is the VICE installation directory (usually 6186@file{/usr/local/lib/vice}, @file{/usr/lib/vice} or 6187@file{/opt/vice/lib}); 6188@item 6189@code{EMUID} is the emulation identification 6190string (@code{C64}, @code{C128}, @code{VIC20} or @code{PET}); 6191@item 6192@code{BOOTPATH} is the directory where the binary lies (usually 6193@file{/usr/local/bin}, @file{/usr/bin} or @code{/opt/vice/bin}). 6194@item 6195@code{DRIVES} is the directory called "DRIVES", where the disk drive ROMs are. 6196(The disk drive ROMs are used by all emulators, so there is an extra 6197directory for them.) 6198@end itemize 6199 6200Notice that the middle entry points to a default location in 6201the user's home directory. Here private ROM versions (e.g. 6202speeddos or JiffyDos) can be stored for example. 6203 6204@xref{System files}. for a description of the method used to load the 6205emulator's system files. 6206 6207@end ifset 6208 6209@vindex DoCoreDump 6210@item DoCoreDump 6211Boolean specifying whether the emulator should dump core when it gets a signal 6212(all emulators except vsid). 6213 6214@vindex LogFileName 6215@item LogFileName 6216String specifying the filename of the current log file. 6217 6218@vindex ExitScreenshotName 6219@item ExitScreenshotName 6220String specifying the filename of a screenshot file that will be written when the emulator exits. 6221 6222@vindex ExitScreenshotName1 6223@item ExitScreenshotName1 6224String specifying the filename of a screenshot file that will be written when the emulator exits. (x128) 6225 6226@vindex FliplistName 6227@item FliplistName 6228String specifying the filename of the current flip list. (Drive 8 only) 6229(all emulators except vsid). 6230 6231@vindex AttachDevice8Readonly 6232@vindex AttachDevice9Readonly 6233@vindex AttachDevice10Readonly 6234@vindex AttachDevice11Readonly 6235@item AttachDevice8Readonly 6236@itemx AttachDevice9Readonly 6237@itemx AttachDevice10Readonly 6238@itemx AttachDevice11Readonly 6239Booleans that specify whether to attach images on drives 8 to 11 read-only or not 6240(all emulators except vsid). 6241 6242@vindex AttachDevice8d1Readonly 6243@vindex AttachDevice9d1Readonly 6244@vindex AttachDevice10d1Readonly 6245@vindex AttachDevice11d1Readonly 6246@item AttachDevice8d1Readonly 6247@itemx AttachDevice9d1Readonly 6248@itemx AttachDevice10d1Readonly 6249@itemx AttachDevice11d1Readonly 6250Booleans that specify whether to attach images on the second drive of dual-drives 8 to 11 read-only or not 6251(all emulators except vsid). 6252 6253@end table 6254 6255@node Misc options, , Misc resources, Misc settings 6256@subsection Miscellaneous command-line options 6257 6258@table @code 6259@findex -jamaction 6260@item -jamaction <Type> 6261Specify the action to take when the CPU encounters a 'JAM' opcode 6262(@code{JAMAction}) 6263(0: Show dialog, 1: continue emulation, 2: start monitor, 3: soft reset, 4: hard reset, 5: quit emulator). 6264 6265@findex -directory 6266@item -directory <Path> 6267Specify the system file search path 6268(@code{Directory}). 6269 6270@end table 6271 6272 6273@node Machine-specific features, Platform-specific features, Settings and resources, Top 6274@chapter Machine-specific features 6275 6276@menu 6277* C64/128-specific:: Commands and settings specific to the 6278 C64/128 emulators 6279* C128-specific:: Commands and settings specific to the 6280 C128 emulator 6281* C64DTV-specific:: Commands and settings specific to the 6282 C64DTV emulator 6283* SCPU64-specific:: Commands and settings specific to the 6284 SCPU64 emulator 6285* VIC20-specific:: Commands and settings specific to the 6286 VIC20 emulator 6287* PLUS4-specific:: Commands and settings specific to the 6288 PLUS4 emulator 6289* PET-specific:: Commands and settings specific to the 6290 PET emulator 6291* CBM-II-specific:: Commands and settings specific to the 6292 CBM-II emulator 6293* VSID-specific:: Commands and settings specific to the 6294 VSID music player 6295@end menu 6296 6297@c ----------------------------------------------------------------------------- 6298 6299@node C64/128-specific, C128-specific, Machine-specific features, Machine-specific features 6300@section C64/128-specific commands and settings 6301 6302@c FIXME: clean up "c64/128" vs "c64" 6303 6304This section lists the settings and commands that are C64/128 specific 6305and thus are not present in the other emulators. 6306 6307@menu 6308* C64 cartridges:: Using cartridges with the C64 emulator. 6309* VIC-II settings:: Settings that control the video chip. 6310* SID settings:: Settings that control the audio chip. 6311* C64 I/O extension settings:: Settings that enable special extensions. 6312* C64 system ROM settings:: Settings to control the C64 system ROMs. 6313@end menu 6314 6315@node C64 cartridges, VIC-II settings, C64/128-specific, C64/128-specific 6316 6317@subsection Using cartridges 6318 6319The cartridge system is organized in "Slots" to allow more than one cartridge 6320connected at a time, like it can be done using an expansion port expander on 6321a real C64 (see below). 6322 6323Generally a cartridge can be enabled by attaching its respective cartridge 6324image, or using the respective menu option for cartridges that do not 6325require an image. 6326 6327x64, x64sc and x128 allow you to attach the following kinds of images: 6328 6329@itemize @bullet 6330@item 6331@file{.crt} images, as used by the CCS64 emulator by Per H�kan Sundell 6332@item 6333raw @file{.bin} images, with or without load address 6334@end itemize 6335 6336@dfn{Cartridge images} are like disk images, but contain the contents of 6337cartridge ROM and/or RAM images instead of disk images. 6338 6339To attach cartridges, use the ``Attach a cartridge image'' submenu. When using 6340@file{.crt} images, this will work for every cartridge which is supported. For 6341raw @file{.bin} images you might have to use command line options. 6342 6343When you have successfully attached a cartridge image, 6344you should then reset the machine to make sure the cartridge initializes 6345itself. (Or enable the "reset on cartridge change" option). 6346 6347Of course, it is also possible to detach a currently attached 6348cartridge image (``Detach cartridge image''). 6349 6350If you are using a freezer cart like an Action Replay cartridge, you can 6351emulate the cartridge's freeze button with the ``Cartridge freeze'' 6352command. 6353 6354The imaginary expansion port expander is organized in 4 slots, the 6355cartridges are associated with them like this: 6356 6357@c @node FIXME 6358@subsubsection Slot 0 6359 6360All carts that have a passthrough connector go here. Once a "Slot 0" 6361cartridge is enabled all further cartridges are connected to its respective 6362passthrough port. 6363 6364Only one cartridge of this type can be active at a time. 6365 6366"Slot 0" carts have individual "enable" switches, enabling means enabling permanently. 6367 6368The following cartridges are emulated in this slot: 6369 6370@itemize @bullet 6371@item 6372IEEE-488 Interface 6373(@uref{http://www.funet.fi/pub/cbm/schematics/cartridges/c64/ieee-488/eprom.bin}) 6374@item 6375Magic Voice 6376@item 6377MMC64 6378@end itemize 6379 6380@c @node FIXME 6381@subsubsection Slot 1 6382 6383Mostly RAM based cartridges which for one reason or the other might make sense 6384to be enabled together with one of the "Main Slot" cartridges go here. 6385 6386Only one cartridge of this type can be active at a time. 6387 6388"Slot 1" carts have individual "enable" switches, enabling means enabling permanently 6389 6390The following cartridges are emulated in this slot: 6391 6392@itemize @bullet 6393@item 6394Double Quick Brown Box (DQBB) 6395@item 6396Expert Cartridge 6397@item 6398ISEPIC 6399@item 6400RamCart 6401@end itemize 6402 6403@c @node FIXME 6404@subsubsection Main Slot 6405 6406All other cartridges which are not pure i/o extensions go here. 6407 6408Only one cartridge of this type can be active at a time. 6409 6410Cartridges in the "Main Slot" must be explicitly set as default to enable them permanently. 6411 6412The following cartridges are emulated in this slot: 6413 6414@itemize @bullet 6415@item 6416generic 4KiB, 8KiB and 16KiB game- and ultimax cartridges 6417@item 6418Action Replay V5 6419@item 6420Action Replay MK2 6421@item 6422Action Replay MK3 6423@item 6424Action Replay MK4 6425@item 6426Atomic Power 6427@item 6428BIS-Plus 6429@item 6430Blackbox V3 6431@item 6432Blackbox V4 6433@item 6434Blackbox V8 6435@item 6436Blackbox V9 6437@item 6438C64 Games System 6439@item 6440Capture 6441@item 6442Comal 80 6443@item 6444Dela EP64 6445@item 6446Dela EP7x8 6447@item 6448Dela EP256 6449@item 6450Diashow-Maker 6451@item 6452Dinamic 6453@item 6454Easy Calc 6455@item 6456EasyFlash 6457@item 6458Epyx FastLoad 6459@item 6460EXOS 6461@item 6462The Final Cartridge 6463@item 6464The Final Cartridge III 6465@item 6466Final Cartridge Plus 6467@item 6468Formel 64 6469@item 6470Freeze Frame 6471@item 6472Freeze Machine 6473@item 6474Fun Play / Powerplay 6475@item 6476Game Killer 6477@item 6478GMod2 6479@item 6480GMod3 6481@item 6482H.E.R.O. bootleg 6483@item 6484IDE64 (@uref{http://www.ide64.org}) 6485@item 6486KCS Power Cartridge 6487@item 6488Kingsoft 6489@item 6490Lt. Kernal Host Adaptor 6491@item 6492MACH 5 6493@item 6494Magic Desk 6495@item 6496Magic Formel 6497@item 6498MAX Basic 6499@item 6500Mikro Assembler 6501@item 6502MMC Replay 6503@item 6504Ocean 6505@item 6506Pagefox 6507@item 6508Prophet64 6509@item 6510RAMLink 6511@item 6512REX 256KiB EPROM Cart 6513@item 6514REX RAM-Floppy 6515@item 6516REX Utility 6517@item 6518Retro Replay 6519@item 6520RGCD 6521@item 6522RR-Net MK3 6523@item 6524ROSS 6525@item 6526SD-BOX 6527@item 6528Silverrock 128 6529@item 6530Simons' BASIC 6531@item 6532Snapshot 64 6533@item 6534Stardos 6535@item 6536Structured BASIC 6537@item 6538Super Explode V5.0 6539@item 6540Super Games 6541@item 6542Super Snapshot V4 6543@item 6544Super Snapshot V5 6545@item 6546Warp Speed 6547@item 6548Westermann Learning 6549@item 6550Zaxxon 6551@item 6552ZIPP-CODE 48 6553@end itemize 6554 6555@c @node FIXME 6556@subsubsection I/O Slot 6557 6558All carts that are pure I/O extensions go here. 6559 6560Any number of "I/O Slot" Carts may be active at a time. 6561 6562"I/O Slot" carts have individual "enable" switches, enabling means enabling permanently. 6563 6564The following cartridges are emulated in this slot: 6565 6566@itemize @bullet 6567@item 6568ACIA (Swiftlink, Turbo232) 6569@item 6570DigiMAX 6571@item 6572DS12C887 RTC 6573@item 6574Ethernet (The Final Ethernet, RR-Net) 6575@item 6576GEO-RAM 6577@item 6578MIDI (Passport/Syntech, Datel/Siel/JMS/C-Lab, Maplin, Namesoft, Sequential) 6579@item 6580RAM Expansion Module (REU) 6581@item 6582SFX Sound Expander 6583@item 6584SFX Sound Sampler 6585@end itemize 6586 6587@c @node FIXME 6588@subsubsection Expected behaviour 6589 6590When the emulator is run without arguments, all settings from the config file 6591should be applied and arguments override settings from the config file. 6592 6593When saving the settings to the config file it is expected that on the next run 6594of the emulator all settings will be in the same state as they were when saved. 6595 6596There is an exception to this rule: the cartridge in the "Main Slot" must be 6597explicitly set as default before it gets saved to the config file. 6598 6599@code{+cart} should disable ALL cartridges, including eventually activated REU, 6600Swithlink and all similar expansionport devices. 6601 6602@code{-cartXYZ} options should generally attach AND activate a cart of type XYZ. 6603As a consequence, attaching carts this way which are NOT in the "Main Slot" will 6604also enable the cart permanently. 6605 6606@c @node FIXME 6607@subsubsection Common problems 6608 6609If attaching a cartridge does not work as expected, this may be because of various 6610reasons: 6611 6612@itemize @bullet 6613 6614@item Not seldomly the CRT type is incorrectly set in @code{.crt} files found "in the wild". 6615Make sure this is not the case (if in doubt use @code{cartconv} to verify and/or fix). 6616 6617@item You may have unintentionally enabled more than one cartridge at once, for 6618example by saving the settings with REU enabled, and then later attaching a game 6619cartridge from the command-line. The cartridge system will allow certain combinations, 6620but (as on the real thing) not all do (can) actually work. To make sure this is 6621not the case, either detach all cartridges from the menus, or use @code{+cart} 6622on the command-line. 6623 6624@item The cartridge image might be broken. Try one from a different source. If you 6625are sure the dump is ok (for example because you dumped it yourself) then make sure 6626it is in proper linear order (on some cartridges, for example "capture", address and/or 6627data lines at the eprom are shuffled around so a dump made with an eprom burner can not 6628be used as is). 6629 6630@item Last not least you might have encountered a bug in the emulation. If you 6631suspect this is the case, and you can still reproduce the bug after checking the 6632things above, please file a bug report including the following information: 6633 6634@itemize @bullet 6635@item attach your vicerc and a reference to the cartridge binaries 6636@item if you can, comment in the respective DEBUGXYZ macros prominently defined at the 6637top of these files: src/c64/cart/c64cart.c src/c64/cart/c64cartmem.c src/c64/c64io.c 6638src/c64/c64export.c and then recompile. this will add debug output that might make 6639it much easier to locate certain problems. 6640@end itemize 6641 6642@end itemize 6643 6644@c @node FIXME 6645@subsubsection IEEE-488 interface 6646 6647To be able to use an IEEE drive, you need to enable IEEE emulation for the 6648emulator. To do this, follow the following steps: 6649 6650Download the IEEE 488 ROM image from the CBM archives (formerly known as FUNET) 6651Attach that image with File/Attach cartridge image/IEEE488 interface image. 6652 6653Make sure you have a one-drive system only (that is, go to Settings/Peripheral 6654Setting, uncheck "use IEC device" for all devices, go to Settings/Drive Settings 6655and select "Floppy type" as "none" for all drives other than drive 8. 6656 6657After this, all drives can be selected in x64 and x128. 6658 6659@c @node FIXME 6660@subsubsection The Final Cartridge 3 6661The Final Cartridge 3 detects whether a mouse is connected when it starts and 6662disables mouse support if it doesnt detect one. So to make mouse emulation 6663work you must either enable it on the command line, or reset the cartridge 6664after enabling it from the user interface. 6665 6666@c @node FIXME 6667@subsubsection CMD RAMLink 6668The CMD RAMLink can operate standalone using its own RAMCard or with an REU, 6669GEORAM, or RAMDrive (only one) which is inserted into the RAM port. 6670The RAMLink is essentially a builtin high capacity RAMDOS with battery backup 6671support. 6672This "backup" support can be emulated through the use of images. 6673Initially it will "format" the memory so each has their own native parition 6674on drive 16. 6675Paritions and the device number can be changed with the CMD "RAM-tools". 6676The latest RAMLink firmware (2.01) can not handle REU sizes other than 128 6677and 512 KiB, or GEORAM sizes beyond 2 MiB in VICE, as the firmware will hang 6678on size detection. 6679 6680The RAMLink also features a parallel port (similar to IEEE-488 interface) 6681which allows faster transfers to the CMD HD series drives. 6682The "cabling" is automatically performed by VICE and the RAMLink firmware will 6683detect the cable presence and use it automatically. 6684However, some programs may have compatibility issues (notably the CMD HD-tools 6685with older HD boot roms). 6686To disable this, issue the JiffyDOS command "@@P0" to disable, or "@@P1" to 6687enable parallel transfers. 6688 6689The RAMLink features an "Enable/Disable" switch that can be changed at 6690anytime using the GUI options. 6691Prior to disabling, the JiffyDOS "@@Q" command should be issued to remove the 6692JiffyDOS system vectors. See the manual for how to reactivate JiffyDOS. 6693It is not recommended to change the REU, GEORAM, or RAMCard size as the 6694CMD RAMDOS was not designed to detect this. Any changes should be followed 6695by a machine reset. 6696 6697The RAMLink also has a "Normal/Disable" switch which can also be changed at 6698anytime. 6699Normal, the default, only allows RAMLink access to the RAM port (REU, GEORAM, 6700and RAMDrive); their registers are hidden otherwise. 6701Direct exposes their registers all the time. This can lead to potential 6702data corruption of the data on the RAM expansion devices as RAMLink can not 6703guarantee its access is exclusive. 6704 6705RAMLink is also compatible with the CMD SuperCPU 64, however it requires the 6706official SuperCPU ROM (2.04) along with the RAMLink ROM to properly detect and 6707utilize all the RAMLink features. 6708 6709@c @node FIXME 6710@subsection C64 cartridge settings 6711 6712@c @node FIXME 6713@subsubsection C64 cartridge resources 6714 6715@table @code 6716 6717@vindex IOCollisionHandling 6718@item IOCollisionHandling 6719Integer specifying the way the I/O collisions should be handled. 6720(0: error message and detach all involved carts, 1: error message and detach last attached involved 6721carts, 2: warning in log and 'AND' the valid return values) 6722 6723@vindex CartridgeReset 6724@item CartridgeReset 6725Boolean specifying whether the machine should be reset when a cartridge is changed. 6726 6727@vindex CartridgeType 6728@item CartridgeType 6729Integer specifying the type of cartridge emulated in the "main" slot. 6730 6731The following cartridge types are valid: 6732 6733@itemize @bullet 6734@item 6735- 6: Ultimax 6736@item 6737- 3: Generic 8KiB 6738@item 6739- 2: Generic 16KiB 6740@item 6741- 1: None 6742@item 6743 0: CRT 6744@item 6745 1: Action Replay V5 6746@item 6747 2: KCS Power Cartridge 6748@item 6749 3: The Final Cartridge III 6750@item 6751 4: Simons' BASIC 6752@item 6753 5: Ocean 6754@item 6755 6: Expert Cartridge 6756@item 6757 7: Fun Play 6758@item 6759 8: Super Games 6760@item 6761 9: Atomic Power / Nordic Power 6762@item 676310: Epyx FastLoad 6764@item 676511: Westermann Learning 6766@item 676712: REX Utility 6768@item 676913: The Final Cartridge 6770@item 677114: Magic Formel 6772@item 677315: C64 Games System 6774@item 677516: Warp Speed 6776@item 677717: Dinamic 6778@item 677918: Zaxxon 6780@item 678119: Magic Desk 6782@item 678320: Super Snapshot V5 6784@item 678521: Comal 80 6786@item 678722: Structured BASIC 6788@item 678923: ROSS 6790@item 679124: Dela EP64 6792@item 679325: Dela EP7x8 6794@item 679526: Dela EP256 6796@item 679727: REX 256KiB EPROM Cart 6798@item 679928: Mikro Assembler 6800@item 680129: Final Cartridge Plus 6802@item 680330: Action Replay MK4 6804@item 680531: Stardos 6806@item 680732: EasyFlash 6808@item 680933: EasyFlash Xbank 6810@item 681134: Capture 6812@item 681335: Action Replay MK3 6814@item 681536: Retro Replay 6816@item 681737: MMC64 6818@item 681938: MMC Replay 6820@item 682139: IDE64 6822@item 682340: Super Snapshot V4 6824@item 682541: IEEE-488 Interface 6826@item 682742: Game Killer 6828@item 682943: Prophet64 6830@item 683144: EXOS 6832@item 683345: Freeze Frame 6834@item 683546: Freeze Machine 6836@item 683747: Snapshot 64 6838@item 683948: Super Explode V5.0 6840@item 684149: Magic Voice 6842@item 684350: Action Replay MK2 6844@item 684551: MACH 5 6846@item 684752: Diashow-Maker 6848@item 684953: Pagefox 6850@item 685154: Kingsoft 6852@item 685355: Silverrock 128KiB Cartridge 6854@item 685556: Formel 64 6856@item 685757: RGCD 6858@item 685958: RR-Net MK3 6860@item 686159: EasyCalc 6862@item 686360: GMod2 6864@item 686561: MAX Basic 6866@item 686762: GMod3 6868@item 686963: ZIPP-CODE 48 6870@item 687164: Blackbox V8 6872@item 687365: Blackbox V3 6874@item 687566: Blackbox V4 6876@item 687767: REX RAM-Floppy 6878@item 687968: BIS-Plus 6880@item 688169: SD-BOX 6882@item 688370: MultiMAX 6884@item 688571: Blackbox V9 6886@item 688772: Lt. Kernal Host Adaptor 6888@item 688973: RAMLink 6890@item 689174: H.E.R.O. bootleg 6892@end itemize 6893 6894@vindex CartridgeFile 6895@item CartridgeFile 6896String specifying the filename of the image for the cartridge emulated in the "main" slot. 6897 6898@vindex DQBB 6899@item DQBB 6900Boolean specifying whether the Double Quick Brown Box should be emulated or not. 6901 6902@vindex DQBBfilename 6903@item DQBBfilename 6904String specifying the filename of the DQBB RAM image. 6905 6906@vindex DQBBImageWrite 6907@item DQBBImageWrite 6908Boolean, if true write back the DQBB image file automatically, incase the RAM 6909contents changed, when detaching or quitting the emulator. 6910 6911@vindex EasyFlashJumper 6912@item EasyFlashJumper 6913Boolean specifying whether the Easy Flash jumper is set. 6914 6915@vindex EasyFlashWriteCRT 6916@item EasyFlashWriteCRT 6917Boolean, if true write back the Easy Flash image file automatically, incase the 6918contents changed, when detaching or quitting the emulator. 6919 6920@vindex EasyFlashOptimizeCRT 6921@item EasyFlashOptimizeCRT 6922Boolean, if true omit empty (filled with $ff) banks from the .crt image when writing. 6923 6924@vindex ExpertCartridgeEnabled 6925@item ExpertCartridgeEnabled 6926Boolean specifying whether the Expert Cartridge should be emulated or not. 6927 6928@vindex Expertfilename 6929@item Expertfilename 6930String specifying the filename of the Expert Cartridge RAM image. 6931 6932@vindex ExpertImageWrite 6933@item ExpertImageWrite 6934Boolean, if true write back the Expert Cartridge image file automatically, incase the RAM 6935contents changed, when detaching or quitting the emulator. 6936 6937@vindex ExpertCartridgeMode 6938@item ExpertCartridgeMode 6939Integer specifying the state of the expert cartridge switch. 6940(0: off, 1: prg, 2: on) 6941 6942@vindex GMod2EEPROMImage 6943@item GMod2EEPROMImage 6944String that specifies the name of the raw GMod2 EEPROM image. 6945 6946@vindex GMod2FlashWrite 6947@item GMod2FlashWrite 6948Boolean that specifies wether writes to GMod2 EEPROM image are enabled. 6949 6950@vindex GMod2EEPROMRW 6951@item GMod2EEPROMRW 6952Boolean that specifies wether the GMod2 ROM is saved at exit 6953 6954@vindex GMod3FlashWrite 6955@item GMod3FlashWrite 6956Boolean that specifies wether changes to GMod3 EEPROM image are written back to the cartridge image. 6957 6958@vindex IDE64version 6959@item IDE64version 6960Integer specifying whether the emulated card version is V3.4, V4.1 or V4.2. This is automatically 6961detected most of the time for .crt cartridge images. 6962 6963@vindex IDE64Image1 6964@vindex IDE64Image2 6965@vindex IDE64Image3 6966@vindex IDE64Image4 6967@item IDE64Image1 6968@itemx IDE64Image2 6969@itemx IDE64Image3 6970@itemx IDE64Image4 6971Strings specifying the full path to the four harddisk images. If a file is non-existing the drive is not emulated. 6972Some older IDEDOS versions only support the first two harddisks. 6973 6974@vindex IDE64Cylinders1 6975@vindex IDE64Cylinders2 6976@vindex IDE64Cylinders3 6977@vindex IDE64Cylinders4 6978@item IDE64Cylinders1 6979@itemx IDE64Cylinders2 6980@itemx IDE64Cylinders3 6981@itemx IDE64Cylinders4 6982Integers specifying the number of cylinders for the four harddisk images. 6983(1..65535) 6984 6985@vindex IDE64Heads1 6986@vindex IDE64Heads2 6987@vindex IDE64Heads3 6988@vindex IDE64Heads4 6989@item IDE64Heads1 6990@itemx IDE64Heads2 6991@itemx IDE64Heads3 6992@itemx IDE64Heads4 6993Integers specifying the number of heads for the four harddisk images. 6994(1..16) 6995 6996@vindex IDE64Sectors1 6997@vindex IDE64Sectors2 6998@vindex IDE64Sectors3 6999@vindex IDE64Sectors4 7000@item IDE64Sectors1 7001@itemx IDE64Sectors2 7002@itemx IDE64Sectors3 7003@itemx IDE64Sectors4 7004Integers specifying the number of sectors for the four harddisk images. 7005(1..63) 7006 7007@vindex IDE64AutodetectSize1 7008@vindex IDE64AutodetectSize2 7009@vindex IDE64AutodetectSize3 7010@vindex IDE64AutodetectSize4 7011@item IDE64AutodetectSize1 7012@itemx IDE64AutodetectSize2 7013@itemx IDE64AutodetectSize3 7014@itemx IDE64AutodetectSize4 7015Booleans specifying whether the disk geometry should be auto detected based 7016on the disk image for the respective harddisk, or the cylinder/head/sector resources above should be used. 7017 7018@vindex IDE64USBServerAddress 7019@item IDE64USBServerAddress 7020String specifying the address the IDE64 USB server listens to (ip4://127.0.0.1:64245) 7021@vindex IDE64USBServer 7022@item IDE64USBServer 7023Boolean specifying whether the IDE64 USB server is enabled. 7024 7025@vindex IDE64RTCSave 7026@item IDE64RTCSave 7027Boolean specifying whether the IDE64 RTC data should be saved when changed or not. 7028 7029@vindex IDE64ClockPort 7030@item IDE64ClockPort 7031Integer that specifies the enabled IDE64 Clockport device. (0: None, 2: RRNet, 4: MP3@@64) 7032 7033@vindex SBDIGIMAX 7034@item SBDIGIMAX 7035Boolean that specifies whether the Short Bus DigiMAX expansion is enabled. 7036 7037@vindex SBDIGIMAXbase 7038@item SBDIGIMAXbase 7039Integer specifying the Base address of the Short Bus DigiMAX expansion. (0xDE40/0xDE48) 7040 7041@vindex SBETFE 7042@item SBETFE 7043Boolean specifying whether the Short Bus ETFE expansion is enabled 7044 7045@vindex SBETFEbase 7046@item SBETFEbase 7047Integer specifying the Base address of the Short Bus ETFE expansion. ($de00, $de10, $df00) 7048 7049@vindex IEEE488 7050@item IEEE488 7051Boolean specifying whether the IEEE488 interface should be emulated or not. 7052 7053@vindex IEEE488Image 7054@item IEEE488Image 7055String specifying the filename of the IEEE488 ROM image. 7056 7057@vindex IsepicCartridgeEnabled 7058@item IsepicCartridgeEnabled 7059Boolean specifying whether ISEPIC should be emulated or not. 7060 7061@vindex Isepicfilename 7062@item Isepicfilename 7063String specifying the filename of the ISEPIC RAM image. 7064 7065@vindex IsepicSwitch 7066@item IsepicSwitch 7067Boolean specifying the status of the ISEPIC switch. 7068(0: off, 1: on) 7069 7070@vindex IsepicImageWrite 7071@item IsepicImageWrite 7072Boolean, if true write back the ISEPIC image file automatically, incase the RAM 7073contents changed, when detaching or quitting the emulator. 7074 7075@vindex LTKimage0 7076@vindex LTKimage1 7077@vindex LTKimage2 7078@vindex LTKimage3 7079@vindex LTKimage4 7080@vindex LTKimage5 7081@vindex LTKimage6 7082@item LTKimage0 7083@itemx LTKimage1 7084@itemx LTKimage2 7085@itemx LTKimage3 7086@itemx LTKimage4 7087@itemx LTKimage5 7088@itemx LTKimage6 7089Strings specifying the full path to up to seven harddisk images. If a file is 7090non-existing the drive is not emulated. The first drive is necessary. 7091 7092@vindex LTKio 7093@item LTKio 7094Integer specifying the Base address of the I/O interface. (1: $de00, 2: $df00) 7095Default is $df00. 7096 7097@vindex LTKport 7098@item LTKport 7099Integer specifying the port number in multiplexed multi-computer/single-disk 7100configurations. (0 to 15) Default is 0, the master. 7101 7102@vindex LTKserial 7103@item LTKserial 7104String specifying the serial number. It must be in the form "00000000" with all 7105numeric digits. Default is 87000000. LTK DOS install disks are locked to their 7106respective LTK host adapor boot ROM. This setting will override the boot ROM 7107value. The floppy disk serial number can be changed with a sector editor on 7108track 18, sector 18. 7109 7110@vindex MagicVoiceCartridgeEnabled 7111@item MagicVoiceCartridgeEnabled 7112Boolean specifying whether the Magic Voice should be emulated or not. 7113 7114@vindex MagicVoiceImage 7115@item MagicVoiceImage 7116String specifying the filename of the Magic Voice ROM image. 7117 7118@vindex MMC64 7119@item MMC64 7120Boolean specifying whether the MMC64 should be emulated or not. 7121 7122@vindex MMC64BIOSfilename 7123@item MMC64BIOSfilename 7124String specifying the filename of the MMC64 Flash ROM image. 7125 7126@vindex MMC64_bios_write 7127@item MMC64_bios_write 7128Boolean, if true write back the MMC64 Flash ROM image file automatically, incase the 7129contents changed, when detaching or quitting the emulator. 7130 7131@vindex MMC64_flashjumper 7132@item MMC64_flashjumper 7133Boolean that specifies whether the MMC64 flash jumper is set. 7134 7135@vindex MMC64_revision 7136@item MMC64_revision 7137Integer specifying the MMC64 hardware revision. 7138(0: Revision A, 1: Revision B) 7139 7140@vindex MMC64imagefilename 7141@item MMC64imagefilename 7142String specifying the filename of the SD-Card image used by the MMC64 emulation. 7143 7144@vindex MMC64_RO 7145@item MMC64_RO 7146Boolean, if true the SD-Card image is mounted read-only. 7147 7148@vindex MMC64_sd_type 7149@item MMC64_sd_type 7150Integer that specifies the reported type for the emulated SD-Card. 7151(0: Auto, 1: MMC, 2: SD, 3: SDHC) 7152 7153@vindex MMC64ClockPort 7154@item MMC64ClockPort 7155Integer that specifies the clockport device used. 7156(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID) 7157 7158@vindex MMCRCardImage 7159@item MMCRCardImage 7160String specifying the filename of the SD-Card image used by the MMCR emulation. 7161 7162@vindex MMCREEPROMImage 7163@item MMCREEPROMImage 7164String specifying the filename of the MMCR EEPROM image. 7165 7166@vindex MMCRRescueMode 7167@item MMCRRescueMode 7168Boolean specifying if the rescue mode (both buttons pressed during powerup) 7169of the MMCR is active. 7170 7171@vindex MMCRImageWrite 7172@item MMCRImageWrite 7173Boolean, if true write back the MMCR Flash ROM image file automatically, incase the 7174contents changed, when detaching or quitting the emulator. 7175 7176@vindex MMCRCardRW 7177@item MMCRCardRW 7178Boolean specifying if the SD-Card image used by the MMCR emulation is writeable. 7179 7180@vindex MMCRSDType 7181@item MMCRSDType 7182Integer that specifies the reported type for the emulated SD-Card. 7183(0: Auto, 1: MMC, 2: SD, 3: SDHC) 7184 7185@vindex MMCREEPROMRW 7186@item MMCREEPROMRW 7187Boolean specifying if the MMCR EEPROM image is writeable. 7188 7189@vindex MMCRClockPort 7190@item MMCRClockPort 7191Integer that specifies the clockport device. 7192(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID) 7193 7194@vindex RAMCART 7195@item RAMCART 7196Boolean specifying whether the RAMCart should be emulated or not. 7197 7198@vindex RAMCARTfilename 7199@item RAMCARTfilename 7200String specifying the filename of the RAMCart RAM image. 7201 7202@vindex RAMCARTImageWrite 7203@item RAMCARTImageWrite 7204Boolean, if true write back the RAMCart image file automatically, incase the RAM 7205contents changed, when detaching or quitting the emulator. 7206 7207@vindex RAMCART_RO 7208@item RAMCART_RO 7209Boolean, if true the RAMCart contents are read only. 7210 7211@vindex RAMCARTsize 7212@item RAMCARTsize 7213Integer specifying the size of the RAMCart in KiB. 7214(64, 128) 7215 7216@vindex RAMLINK 7217@item RAMLINK 7218Boolean specifying whether the RAMLink module should be emulated or not. 7219This option emulates the behavior of the enable/disable switch on the unit. 7220 7221@vindex RAMLINKfilename 7222@item RAMLINKfilename 7223String specifying the filename of the RAMCard image. 7224 7225@vindex RAMLINKImageWrite 7226@item RAMLINKImageWrite 7227Boolean, if true write back the RAMCard image file automatically, in case the 7228RAM contents changed, when detaching or quitting the emulator. 7229 7230@vindex RAMLINKsize 7231@item RAMLINKsize 7232Integer specifying the size of the RAMCard in MiB. (0..16; default is 0) 7233 7234@vindex RAMLINKmode 7235@item RAMLINKmode 7236Integer specifying the mode of the RAMLink. "1", the default, (Normal) only 7237allows RAMLink access to the RAM port (REU, GEORAM, and RAMDrive); their 7238registers are hidden otherwise. "0" (Direct) exposes their registers all the 7239time. This option emulates the behavior of the Normal/Direct switch on the unit. 7240 7241@vindex RAMLINKRTCSave 7242@item RAMLINKRTCSave 7243Boolean specifying whether the RTC data should be saved when changed or not. 7244 7245@vindex RRrevision 7246@item RRrevision 7247Integer specifying the RR hardware revision. 7248(0: Retro Replay, 1: Nordic Replay) 7249 7250@vindex RRFlashJumper 7251@item RRFlashJumper 7252Boolean specifying whether the RR flash jumper is set or not. 7253 7254@vindex RRBankJumper 7255@item RRBankJumper 7256Boolean specifying whether the RR bank jumper is set or not. 7257 7258@vindex RRBiosWrite 7259@item RRBiosWrite 7260Boolean, if true write back the RR Flash ROM image file automatically, incase the 7261contents changed, when detaching or quitting the emulator. 7262 7263@vindex RRClockPort 7264@item RRClockPort 7265Integer that specifies the clockport device. 7266(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID) 7267 7268@vindex RRNETMK3_flashjumper 7269@item RRNETMK3_flashjumper 7270Boolean specifying whether the RRNETMK3 Flash Jumper is set. 7271 7272@vindex RRNETMK3_bios_write 7273@item RRNETMK3_bios_write 7274Boolean specifying whether to save the RRNETMK3 bios when changed. 7275 7276@vindex SSRamExpansion 7277@item SSRamExpansion 7278Boolean, if true enable the 32KiB addon RAM of the Supersnapshot V5 7279 7280@end table 7281 7282@c @node FIXME 7283@subsubsection C64 cartridge command-line options 7284 7285@table @code 7286 7287@findex -iocollision 7288@item -iocollision <method> 7289Select the way the I/O collisions should be handled 7290(@code{IOCollisionHandling}). 7291(0: error message and detach all involved carts, 1: error message and detach last attached involved 7292carts, 2: warning in log and 'AND' the valid return values 7293 7294@findex +cart 7295@item +cart 7296Disable all cartridges (which would eventually be enabled in the config file). 7297 7298@findex -cartreset, +cartreset 7299@item -cartreset 7300@itemx +cartreset 7301Reset/Do not reset machine if a cartridge is attached or detached 7302(@code{CartridgeReset=1}, @code{CartridgeReset=0}). 7303 7304@findex -cart8 7305@item -cart8 <name> 7306Attach generic 8KiB cartridge image. 7307 7308@findex -cart16 7309@item -cart16 <name> 7310Attach generic 16KiB cartridge image. 7311 7312@findex -cartultimax 7313@item -cartultimax <name> 7314Attach generic 16KiB Ultimax cartridge image. 7315 7316@findex -cartcrt 7317@item -cartcrt <name> 7318Attach CRT cartridge image. 7319 7320@findex -cartap 7321@item -cartap <name> 7322Attach raw 32KiB Atomic Power cartridge image. 7323 7324@findex -cartar2 7325@item -cartar2 <name> 7326Attach raw 16KiB Action Replay MK2 cartridge image. 7327 7328@findex -cartar3 7329@item -cartar3 <name> 7330Attach raw 16KiB Action Replay MK3 cartridge image. 7331 7332@findex -cartar4 7333@item -cartar4 <name> 7334Attach raw 32KiB Action Replay MK4 cartridge image. 7335 7336@findex -cartar5 7337@item -cartar5 <name> 7338Attach raw 32KiB Action Replay cartridge image. 7339 7340@findex -cartbis 7341@item -cartbis <name> 7342Attach raw 8KiB BIS-Plus cartridge image. 7343 7344@findex -cartbb3 7345@item -cartbb3 <name> 7346Attach raw 8KiB Blackbox V3 cartridge image. 7347 7348@findex -cartbb4 7349@item -cartbb4 <name> 7350Attach raw 16KiB Blackbox V4 cartridge image. 7351 7352@findex -cartbb8 7353@item -cartbb8 <name> 7354Attach raw 32/64KiB Blackbox V8 cartridge image. 7355 7356@findex -cartbb9 7357@item -cartbb9 <name> 7358Attach raw 32KiB Blackbox V9 cartridge image. 7359 7360@findex -cartcap 7361@item -cartcap <name> 7362Attach raw 8KiB Capture cartridge image. 7363 7364@findex -cartcomal 7365@item -cartcomal <name> 7366Attach raw 64KiB Comal 80 cartridge image. 7367 7368@findex -cartdep256 7369@item -cartdep256 <name> 7370Attach raw Dela EP256 cartridge image. 7371 7372@findex -cartdep64 7373@item -cartdep64 <name> 7374Attach raw Dela EP64 cartridge image. 7375 7376@findex -cartdep7x8 7377@item -cartdep7x8 <name> 7378Attach raw Dela EP7x8 cartridge image. 7379 7380@findex -cartdin 7381@item -cartdin <name> 7382Attach raw 128KiB Dinamic cartridge image. 7383 7384@findex -cartdsm 7385@item -cartdsm <name> 7386Attach raw 8KiB Diashow-Maker cartridge image. 7387 7388@findex -cartdqbb 7389@item -cartdqbb <name> 7390Attach raw 16KiB Double Quick Brown Box cartridge image. 7391 7392@findex -dqbb, +dqbb 7393@item -dqbb 7394@itemx +dqbb 7395Enable/disable Double Quick Brown Box 7396(@code{DQBB=1}, @code{DQBB=0}). 7397 7398@findex -dqbbimage 7399@item -dqbbimage <name> 7400Specify Double Quick Brown Box filename 7401(@code{DQBBfilename}). 7402 7403@findex -dqbbimagerw, +dqbbimagerw 7404@item -dqbbimagerw 7405@itemx +dqbbimagerw 7406Allow/disallow writing to DQBB image 7407(@code{DQBBImageWrite=1}, @code{DQBBImageWrite=0}). 7408 7409@findex -carteasy 7410@item -carteasy <name> 7411Attach raw EasyFlash cartridge image. 7412 7413@findex -carteasycalc 7414@item -carteasycalc <name> 7415Attach raw 24KiB Easy Calc Result cartridge image 7416 7417@findex -easyflashjumper, +easyflashjumper 7418@item -easyflashjumper 7419@itemx +easyflashjumper 7420Enable/disable EasyFlash jumper 7421(@code{EasyFlashJumper=1}, @code{EasyFlashJumper=0}). 7422 7423@findex -easyflashcrtwrite, +easyflashcrtwrite 7424@item -easyflashcrtwrite 7425@itemx +easyflashcrtwrite 7426Allow/Disallow writing to EasyFlash .crt image 7427(@code{EasyFlashWriteCRT=1}, @code{EasyFlashWriteCRT=0}). 7428 7429@findex -easyflashcrtoptimize, +easyflashcrtoptimize 7430@item -easyflashcrtoptimize 7431@itemx +easyflashcrtoptimize 7432Allow/Disallow EasyFlash .crt image optimizing (omitting of empty banks) on write 7433(@code{EasyFlashOptimizeCRT=1}, @code{EasyFlashOptimizeCRT=0}). 7434 7435@findex -cartepyx 7436@item -cartepyx <name> 7437Attach raw 8KiB Epyx FastLoad cartridge image. 7438 7439@findex -cartexos 7440@item -cartexos <name> 7441Attach raw 8KiB EXOS cartridge image. 7442 7443@findex -cartexpert 7444@item -cartexpert <name> 7445Attach raw 8KiB Expert Cartridge image. 7446 7447@findex -expert, +expert 7448@item -expert 7449@itemx +expert 7450Enable/Disable the Expert Cartridge 7451(@code{ExpertCartridgeEnabled=1}, @code{ExpertCartridgeEnabled=0}). 7452 7453@findex -expertimagename 7454@item -expertimagename <name> 7455Set Expert Cartridge image name 7456(@code{Expertfilename}). 7457 7458@findex -expertimagerw, +expertimagerw 7459@item -expertimagerw 7460@itemx +expertimagerw 7461Allow/Disallow writing to Expert Cartridge image 7462(@code{ExpertImageWrite=1}, @code{ExpertImageWrite=0}). 7463 7464@findex -expertmode 7465@item -expertmode <mode> 7466Set Expert Cartridge mode 7467(@code{ExpertCartridgeMode}). 7468(0: off, 1: prg, 2: on) 7469 7470@findex -cartf64 7471@item -cartf64 <Name> 7472Attach raw 32KiB Formel 64 image. 7473 7474@findex -cartfc1 7475@item -cartfc1 <name> 7476Attach raw 16KiB Final Cartridge image. 7477 7478@findex -cartfc3 7479@item -cartfc3 <name> 7480Attach raw 64KiB Final Cartridge III image. 7481 7482@findex -cartfcplus 7483@item -cartfcplus <name> 7484Attach raw 32KiB Final Cartridge Plus image. 7485 7486@findex -cartff 7487@item -cartff <name> 7488Attach raw 8KiB Freeze Frame image. 7489 7490@findex -cartfm 7491@item -cartfm <name> 7492Attach raw 32KiB Freeze Machine image. 7493 7494@findex -cartfp 7495@item -cartfp <name> 7496Attach raw 128KiB Fun Play/Power Play cartridge image. 7497 7498@findex -cartgmod2 7499@item -cartgmod2 <name> 7500Attach raw GMod2 cartridge image. 7501 7502@findex -gmod2eepromimage 7503@item -gmod2eepromimage <name> 7504Attach raw GMod2 EEPROM image (@code{GMod2EEPROMImage}). 7505 7506@findex -gmod2eepromrw, +gmod2eepromrw 7507@item -gmod2eepromrw 7508@itemx +gmod2eepromrw 7509Enable/Disable writes to GMod2 EEPROM image (@code{GMod2EEPROMRW=1}, @code{GMod2EEPROMRW=0}). 7510 7511@findex -gmod2flashwrite, +gmod2flashwrite 7512@item -gmod2flashwrite 7513@itemx +gmod2flashwrite 7514Enable/Disable saving of the GMod2 ROM at exit (@code{GMod2FlashWrite=1}, @code{GMod2FlashWrite=0}). 7515 7516@findex -cartgmod3 7517@item -cartgmod3 <name> 7518Attach raw GMod3 cartridge image. 7519 7520@findex -gmod3flashwrite, +gmod3flashwrite 7521@item -gmod3flashwrite 7522@itemx +gmod3flashwrite 7523Enable/Disable saving of the GMod3 ROM at exit (@code{GMod3FlashWrite=1}, @code{GMod3FlashWrite=0}). 7524 7525@findex -cartgk 7526@item -cartgk <name> 7527Attach raw 8KiB Game Killer cartridge image. 7528 7529@findex -cartgs 7530@item -cartgs <name> 7531Attach raw 512KiB Game System cartridge image. 7532 7533@findex -carthero 7534@item -carthero <name> 7535Attach raw 32KiB H.E.R.O. bootleg cartridge image 7536 7537@findex -cartide64 7538@item -cartide64 <name> 7539Attach raw 64KiB or 128KiB IDE64 cartridge image. 7540 7541@findex -IDE64image1 7542@item -IDE64image1 <name> 7543@findex -IDE64image2 7544@item -IDE64image2 <name> 7545@findex -IDE64image3 7546@item -IDE64image3 <name> 7547@findex -IDE64image4 7548@item -IDE64image4 <name> 7549Specify path to the image files for IDE64 harddisks 7550(@code{IDE64Image1}, @code{IDE64Image2}, @code{IDE64Image3}, @code{IDE64Image4}). 7551 7552@findex -IDE64cyl1 7553@item -IDE64cyl1 <value> 7554@findex -IDE64cyl2 7555@item -IDE64cyl2 <value> 7556@findex -IDE64cyl3 7557@item -IDE64cyl3 <value> 7558@findex -IDE64cyl4 7559@item -IDE64cyl4 <value> 7560Set number of cylinders for the IDE64 harddisk emulation 7561(@code{IDE64Cylinders1}, @code{IDE64Cylinders2}, @code{IDE64Cylinders3}, @code{IDE64Cylinders1}). 7562(1..65535) 7563 7564@findex -IDE64hds1 7565@item -IDE64hds1 <value> 7566@findex -IDE64hds2 7567@item -IDE64hds2 <value> 7568@findex -IDE64hds3 7569@item -IDE64hds3 <value> 7570@findex -IDE64hds4 7571@item -IDE64hds4 <value> 7572Set number of heads for the IDE64 harddisk emulation 7573(@code{IDE64Heads1}, @code{IDE64Heads2}, @code{IDE64Heads3}, @code{IDE64Heads4}). 7574(1..16) 7575 7576@findex -IDE64sec1 7577@item -IDE64sec1 <value> 7578@findex -IDE64sec2 7579@item -IDE64sec2 <value> 7580@findex -IDE64sec3 7581@item -IDE64sec3 <value> 7582@findex -IDE64sec4 7583@item -IDE64sec4 <value> 7584Set number of sectors for the IDE64 harddisk emulation 7585(@code{IDE64Sectors1}, @code{IDE64Sectors2}, @code{IDE64Sectors3}, @code{IDE64Sectors4}). 7586(1..63) 7587 7588@findex -IDE64autosize1, +IDE64autosize1 7589@item -IDE64autosize1 7590@itemx +IDE64autosize1 7591Autodetect geometry of formatted image or do not autodetect and use specified geometry 7592(@code{IDE64AutodetectSize1=1}, @code{IDE64AutodetectSize1=0}). 7593 7594@findex -IDE64autosize2, +IDE64autosize2 7595@item -IDE64autosize2 7596@itemx +IDE64autosize2 7597Autodetect geometry of formatted image or do not autodetect and use specified geometry 7598(@code{IDE64AutodetectSize2=1}, @code{IDE64AutodetectSize2=0}). 7599 7600@findex -IDE64autosize3, +IDE64autosize3 7601@item -IDE64autosize3 7602@itemx +IDE64autosize3 7603Autodetect geometry of formatted image or do not autodetect and use specified geometry 7604(@code{IDE64AutodetectSize3=1}, @code{IDE64AutodetectSize3=0}). 7605 7606@findex -IDE64autosize4, +IDE64autosize4 7607@item -IDE64autosize4 7608@itemx +IDE64autosize4 7609Autodetect geometry of formatted image or do not autodetect and use specified geometry 7610(@code{IDE64AutodetectSize4=1}, @code{IDE64AutodetectSize4=0}). 7611 7612@findex -IDE64version 7613@item -IDE64version <value> 7614Select IDE64 version V3 (0), V4.1 (1) or V4.2 (2). 7615(@code{IDE64version}). 7616(0..2) 7617 7618@findex -IDE64USB, +IDE64USB 7619@item -IDE64USB 7620@itemx +IDE64USB 7621Enable/Disable IDE64 USB server 7622@findex -IDE64USBAddress 7623@item -IDE64USBAddress <name> 7624The local address the IDE64 USB server should bind to 7625 7626@findex -IDE64rtcsave, +IDE64rtcsave 7627@item -IDE64rtcsave 7628@itemx +IDE64rtcsave 7629Enable/disable saving of IDE64 RTC data when changed 7630(@code{IDE64RTCSave=1}, @code{IDE64RTCSave=0}). 7631 7632@findex -ide64clockportdevice 7633@item -ide64clockportdevice 7634Enable IDE64 Clockport device (0: None, 2: RRNet, 4: MP3@@64) 7635(@code{IDE64ClockPort}). 7636 7637@findex -sbdigimax, +sbdigimax 7638@item -sbdigimax 7639@itemx +sbdigimax 7640Enable/Disable the Short Bus DigiMAX expansion (@code{SBDIGIMAX}). 7641 7642@findex -sbdigimaxbase 7643@item -sbdigimaxbase 7644Set Base address of the Short Bus DigiMAX expansion (0xDE40/0xDE48) (@code{SBDIGIMAXbase}). 7645 7646@findex -sbetfe, +sbetfe 7647@item -sbetfe 7648@itemx +sbetfe 7649Enable/Disable the Short Bus ETFE expansion (@code{SBETFE}). 7650 7651@findex -sbetfebase 7652@item -sbetfebase 7653Set Base address of the Short Bus ETFE expansion (56832: $de00, 56848: $de10, 57088: $df00) (@code{SBETFEbase}). 7654 7655@findex -cartieee 7656@item -cartieee <name> 7657Attach CBM IEEE-488 cartridge image. 7658 7659@findex -ieee488, +ieee488 7660@item -ieee488 7661@itemx +ieee488 7662Enable/disable emulation of the IEEE488 interface 7663(@code{IEEE488=1}, @code{IEEE488=0}). 7664 7665@findex -ieee488image 7666@item -ieee488image <name> 7667Set IEEE488 interface image name 7668(@code{IEEE488Image}). 7669 7670@findex -isepic, +isepic 7671@item -isepic 7672@itemx +isepic 7673Enable/disable the ISEPIC cart 7674(@code{IsepicCartridgeEnabled=1}, @code{IsepicCartridgeEnabled=0}). 7675 7676@findex -isepicswitch, +isepicswitch 7677@item -isepicswitch 7678@itemx +isepicswitch 7679Enable/disable the ISEPIC switch 7680(@code{IsepicSwitch=1}, @code{IsepicSwitch=0}). 7681 7682@findex -cartisepic 7683@item -cartisepic <name> 7684Attach raw 2KiB ISEPIC cartridge image. 7685 7686@findex -isepicimagename 7687@item -isepicimagename <name> 7688Set ISEPIC image name 7689(@code{Isepicfilename}). 7690 7691@findex -isepicimagerw, +isepicimagerw 7692@item -isepicimagerw 7693@itemx +isepicimagerw 7694Allow/disallow writing to ISEPIC image 7695(@code{IsepicImageWrite=1}, @code{IsepicImageWrite=0}). 7696 7697@findex -cartkcs 7698@item -cartkcs <name> 7699Attach raw 16KiB KCS Power cartridge image. 7700 7701@findex -cartks 7702@item -cartks <name> 7703Attach raw 24KiB Kingsoft cartridge image. 7704 7705@findex -cartltk 7706@item -cartltk <name> 7707Attach raw Lt. Kernal Host Adaptor cartridge image. 7708 7709@findex -ltkimage0 7710@item -ltkimage0 <name> 7711@findex -ltkimage1 7712@item -ltkimage1 <name> 7713@findex -ltkimage2 7714@item -ltkimage2 <name> 7715@findex -ltkimage3 7716@item -ltkimage3 <name> 7717@findex -ltkimage4 7718@item -ltkimage4 <name> 7719@findex -ltkimage5 7720@item -ltkimage5 <name> 7721@findex -ltkimage6 7722@item -ltkimage6 <name> 7723Strings specifying the full path to up to seven harddisk images. If a file is 7724non-existing the drive is not emulated. The first drive is necessary. 7725(@code{ltkimage0}, @code{ltkimage1}, @code{ltkimage2}, @code{ltkimage3}, 7726@code{ltkimage4}, @code{ltkimage5}, @code{ltkimage6}). 7727 7728@findex -ltkio 7729@item -ltkio <value> 7730Integer specifying the Base address of the I/O interface. (1: $de00, 2: $df00) 7731Default is $df00. 7732 7733@findex -ltkport 7734@item -ltkport <value> 7735Integer specifying the port number in multiplexed multi-computer/single-disk 7736configurations. (0..15) Default is 0, the master. 7737 7738@findex -ltkserial 7739@item -ltkserial <name> 7740String specifying the serial number. It must be in the form "00000000" with all 7741numeric digits. Default is 87000000. LTK DOS install disks are locked to their 7742respective LTK host adapor boot ROM. This setting will override the boot ROM 7743value. The floppy disk serial number can be changed with a sector editor on 7744track 18, sector 18. 7745 7746@findex -cartmach5 7747@item -cartmach5 <name> 7748Attach raw 8KiB MACH 5 cartridge image. 7749 7750@findex -cartmd 7751@item -cartmd <name> 7752Attach raw 32/64/128KiB Magic Desk cartridge image. 7753 7754@findex -cartmf 7755@item -cartmf <name> 7756Attach raw Magic Formel cartridge image. 7757 7758@findex -cartmax 7759@item -cartmax <name> 7760Attach raw MAX Basic cartridge image. 7761 7762@findex -cartmm 7763@item -cartmm <name> 7764Attach raw MultiMAX cartridge image. 7765 7766@findex -cartmikro 7767@item -cartmikro <name> 7768Attach raw 8KiB Mikro Assembler cartridge image. 7769 7770@findex -mmc64, +mmc64 7771@item -mmc64 7772@itemx +mmc64 7773Enable/disable the MMC64 expansion 7774(@code{MMC64=1}, @code{MMC64=0}). 7775 7776@findex -cartmmc64 7777@item -cartmmc64 <name> 7778Attach raw 8KiB MMC64 cartridge image. 7779 7780@findex -mmc64bios 7781@item -mmc64bios <name> 7782Specify name of MMC64 BIOS image 7783(@code{MMC64BIOSfilename}). 7784 7785@findex -mmc64image 7786@item -mmc64image <name> 7787Specify name of MMC64 image 7788(@code{MMC64imagefilename}). 7789 7790@findex -mmc64readonly 7791@item -mmc64readonly 7792Set the MMC64 card to read-only 7793(@code{MMC64_RO=1}). 7794 7795@findex -mmc64readwrite 7796@item -mmc64readwrite 7797Set the MMC64 card to read/write 7798(@code{MMC64_RO=0}). 7799 7800@findex -mmc64flash, +mmc64flash 7801@item -mmc64flash 7802@itemx +mmc64flash 7803Enable/Disable the MMC64 flash jumper 7804(@code{MMC64_flashjumper=1}, @code{MMC64_flashjumper=0}). 7805 7806@findex -mmc64bioswrite 7807@item -mmc64bioswrite 7808Save the MMC64 bios when changed 7809(@code{MMC64_bios_write}=1). 7810 7811@findex -mmc64biosreadonly 7812@item -mmc64biosreadonly 7813Do not save the MMC64 bios when changed 7814(@code{MMC64_bios_write}=0). 7815 7816@findex -mmc64rev 7817@item -mmc64rev <revision> 7818Specify MMC64 revision 7819(@code{MMC64_revision}). 7820(0: Revision A, 1: Revision B) 7821 7822@findex -mmc64sdtype 7823@item -mmc64sdtype <type> 7824Specify MMC64 SD type 7825(@code{MMC64_sd_type}). 7826(0: Auto, 1: MMC, 2: SD, 3: SDHC) 7827 7828@findex -mmc64clockportdevice 7829@item -mmc64clockportdevice <device> 7830Set MMC64 clockport device 7831(@code{MMC64ClockPort}) 7832(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID) 7833 7834@findex -cartmmcr 7835@item -cartmmcr <name> 7836Attach raw 512KiB MMC Replay cartridge image. 7837 7838@findex -mmcrrescue, +mmcrrescue 7839@item -mmcrrescue 7840@itemx +mmcrrescue 7841Enable/disable MMC Replay rescue mode 7842(@code{MMCRRescueMode=1}, @code{MMCRRescueMode=0}). 7843 7844@findex -mmcrimagerw, +mmcrimagerw 7845@item -mmcrimagerw 7846@itemx +mmcrimagerw 7847Allow/disallow writing to MMC Replay image 7848(@code{MMCRImageWrite=1}, @code{MMCRImageWrite=0}). 7849 7850@findex -mmcrsdtype 7851@item -mmcrsdtype <type> 7852Specify MMC Replay SD type 7853(@code{MMCRSDType}). 7854(0: Auto, 1: MMC, 2: SD, 3: SDHC) 7855 7856@findex -mmcrcardimage 7857@item -mmcrcardimage <filename> 7858Specify MMC Replay card image filename 7859(@code{MMCRCardImage}). 7860 7861@findex -mmcrcardrw, +mmcrcardrw 7862@item -mmcrcardrw 7863@itemx +mmcrcardrw 7864Allow/disallow writes to MMC Replay card image 7865(@code{MMCRCardRW=1}, @code{MMCRCardRW=0}). 7866 7867@findex -mmcreepromimage 7868@item -mmcreepromimage <filename> 7869Specify MMC Replay EEPROM image filename 7870(@code{MMCREEPROMImage}). 7871 7872@findex -mmcreepromrw, +mmcreepromrw 7873@item -mmcreepromrw 7874@itemx +mmcreepromrw 7875Allow/disallow writes to MMC Replay EEPROM image 7876(@code{MMCREEPROMRW=1}, @code{MMCREEPROMRW=0}). 7877 7878@findex -mmcrclockportdevice 7879@item -mmcrclockportdevice <id> 7880Set MMC Replay clockport device 7881(@code{MMCRClockPort}). 7882(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID) 7883 7884@findex -cartmv 7885@item -cartmv <name> 7886Attach raw 16KiB Magic Voice cartridge image. 7887 7888@findex -magicvoiceimage 7889@item -magicvoiceimage <name> 7890Specify Magic Voice cartridge ROM image filename 7891(@code{MagicVoiceImage}). 7892 7893@findex -magicvoice, +magicvoice 7894@item -magicvoice 7895@itemx +magicvoice 7896Enable/disable Magic Voice cartridge 7897(@code{MagicVoiceCartridgeEnabled=1}, @code{MagicVoiceCartridgeEnabled=0}). 7898 7899@findex -cartocean 7900@item -cartocean <name> 7901Attach raw Ocean cartridge image. 7902 7903@findex -cartp64 7904@item -cartp64 <name> 7905Attach raw 256KiB Prophet 64 cartridge image. 7906 7907@findex -cartpf 7908@item -cartpf <name> 7909Attach raw 64KiB Pagefox cartridge image. 7910 7911@findex -cartramcart 7912@item -cartramcart <name> 7913Attach raw RamCart cartridge image. 7914 7915@findex -ramcart, +ramcart 7916@item -ramcart 7917@itemx +ramcart 7918Enable/disable the RAMCART expansion 7919(@code{RAMCART=1}, @code{RAMCART=0}). 7920 7921@findex -ramcartsize 7922@item -ramcartsize <size in KiB> 7923Size of the RAMCART expansion 7924(@code{RAMCARTsize}). 7925(64, 128) 7926 7927@findex -ramcartimage 7928@item -ramcartimage <name> 7929Specify name of RAMCART image 7930(@code{RAMCARTfilename}). 7931 7932@findex -ramcartimagerw, +ramcartimagerw 7933@item -ramcartimagerw 7934@itemx +ramcartimagerw 7935Allow/disallow writing to RAMCart image 7936(@code{RAMCARTImageWrite=1}, @code{RAMCARTImageWrite=0}). 7937 7938@findex -ramcartro 7939@item -ramcartro 7940Set the RamCart switch to read-only 7941(@code{RAMCART_RO=1}). 7942 7943@findex -ramcartrw 7944@item -ramcartrw 7945Set the RamCart switch to read-only 7946(@code{RAMCART_RO=0}). 7947 7948@findex -ramlink, +ramlink 7949@item -ramlink 7950@itemx +ramlink 7951Enable/disable emulation of the RAMLink module. This option emulates the 7952behavior of the enable/disable switch on the unit 7953(@code{RAMLINK=1}, @code{RAMLINK=0}). 7954 7955@findex -cartramlink 7956@item -cartramlink <name> 7957Attach the raw 64 KiB ROM image. 7958 7959@findex -ramlinkimage 7960@item -ramlinkimage <name> 7961Specify name of RAMLink RAMCard image 7962(@code{RAMLINKfilename}). 7963 7964@findex -ramlinkimagerw, +ramlinkimagerw 7965@item -ramlinkimagerw 7966@itemx +ramlinkimagerw 7967Allow/disallow writing to RAMCard image on detach 7968(@code{RAMLINKImageWrite=1}, @code{RAMLINKImageWrite=0}). 7969 7970@findex -ramlinksize 7971@item -ramlinksize <size in MiB> 7972Size of the RAMCard unit 7973(@code{RAMLINKsize}). 7974(0..16; default is 0) 7975 7976@findex -ramlinkmode 7977@item -ramlinkmode <value> 7978Sets the RAM port mode of the unit. "1", the default, (Normal) only 7979allows RAMLink access to the RAM port (REU, GEORAM, and RAMDrive); their 7980registers are hidden otherwise. "0" (Direct) exposes their registers all the 7981time. This option emulates the behavior of the Normal/Direct switch on the unit. 7982(@code{RAMLINKmode}). 7983(1:normal (default), 0:direct) 7984 7985@findex -ramlinkrtcsave, +ramlinkrtcsave 7986@item -ramlinkrtcsave 7987@itemx +ramlinkrtcsave 7988Enable/disable saving of the RTC data when changed 7989(@code{RAMLINKRTCSave=1}, @code{RAMLINKRTCSave=0}). 7990 7991@findex -cartrep256 7992@item -cartrep256 <name> 7993Attach raw REX EP256 cartridge image. 7994 7995@findex -cartrgcd 7996@item -cartrgcd <Name> 7997Attach raw 64KiB RGCD cartridge image. 7998 7999@findex -cartross 8000@item -cartross <name> 8001Attach raw 16/32KiB ROSS cartridge image. 8002 8003@findex -cartrrnet 8004@item -cartrrnet <name> 8005Attach raw 8KiB RR-Net MK3 cartridge image. 8006 8007@findex -cartrr 8008@item -cartrr <name> 8009Attach raw 64KiB Retro Replay cartridge image. 8010 8011@findex -rrbioswrite, +rrbioswrite 8012@item -rrbioswrite 8013@itemx +rrbioswrite 8014Enable/disable saving of the RR ROM at exit 8015(@code{RRBiosWrite=1}, @code{RRBiosWrite=0}). 8016 8017@findex -rrbankjumper, +rrbankjumper 8018@item -rrbankjumper 8019@itemx +rrbankjumper 8020Set/unset RR Bank Jumper 8021(@code{RRBankJumper=1}, @code{RRBankJumper=0}). 8022 8023@findex -rrflashjumper, +rrflashjumper 8024@item -rrflashjumper 8025@itemx +rrflashjumper 8026Set/unset RR Flash Jumper 8027(@code{RRFlashJumper=1}, @code{RRFlashJumper=0}). 8028 8029@findex -rrrev 8030@item -rrrev <Revision> 8031Set the RR revision 8032(@code{RRrevision}). 8033(0: Retro Replay, 1: Nordic Replay) 8034 8035@findex -rrclockportdevice 8036@item -rrclockportdevice <device> 8037Set the RR clockport device 8038(@code{RRClockPort}) 8039(0: None, 1: ETH64-II, 2: RRNet, 3: Silver Surfer, 4: MP3@@64, 5: Catweasel MkIII SID) 8040 8041@findex -rrnetmk3flash,+rrnetmk3flash 8042@item -rrnetmk3flash 8043@itemx +rrnetmk3flash 8044SetRemove the RRNETMK3 Flash Jumper 8045(@code{RRNETMK3_flashjumper=1}, @code{RRNETMK3_flashjumper=0}). 8046 8047@findex -rrnetmk3bioswrite, +rrnetmk3bioswrite 8048@item -rrnetmk3bioswrite 8049@itemx +rrnetmk3bioswrite 8050Save/Do not save the RRNETMK3 bios when changed 8051(@code{RRNETMK3_bios_write=1}, @code{RRNETMK3_bios_write=0}). 8052 8053@findex -cartrrf 8054@item -cartrrf <name> 8055Attach raw 8KiB REX RAM-Floppy cartridge image. 8056 8057@findex -cartru 8058@item -cartru <name> 8059Attach raw 8KiB REX Utility cartridge image. 8060 8061@findex -cartsdbox 8062@item -cartsdbox <name> 8063Attach raw 128KiB SD-BOX cartridge image. 8064 8065@findex -carts64 8066@item -carts64 <name> 8067Attach raw 4KiB Snapshot 64 cartridge image. 8068 8069@findex -cartsb 8070@item -cartsb <name> 8071Attach raw Structured Basic cartridge image. 8072 8073@findex -cartse5 8074@item -cartse5 <name> 8075Attach raw 16KiB Super Explode V5 cartridge image. 8076 8077@findex -cartsg 8078@item -cartsg <name> 8079Attach raw 64KiB Super Games cartridge image. 8080 8081@findex -cartsilver 8082@item -cartsilver <Name> 8083Attach raw Silverrock 128 cartridge image. 8084 8085@findex -cartsimon 8086@item -cartsimon <name> 8087Attach raw 16KiB Simons' Basic cartridge image. 8088 8089@findex -cartss4 8090@item -cartss4 <name> 8091Attach raw 32KiB Super Snapshot V4 cartridge image. 8092 8093@findex -cartss5 8094@item -cartss5 <name> 8095Attach raw 64KiB Super Snapshot V5 cartridge image. 8096 8097@findex -ssramexpansion, +ssramexpansion 8098@item -ssramexpansion 8099@itemx +ssramexpansion 8100Enable/disable 32KiB addon RAM. 8101(@code{SSRamExpansion=1}, @code{SSRamExpansion=0}). 8102 8103@findex -cartstar 8104@item -cartstar <name> 8105Attach raw 16KiB Stardos cartridge image. 8106 8107@findex -cartwl 8108@item -cartwl <name> 8109Attach raw 16KiB Westermann Learning cartridge image. 8110 8111@findex -cartws 8112@item -cartws <name> 8113Attach raw 8KiB Warp Speed cartridge image. 8114 8115@findex -cartzaxxon 8116@item -cartzaxxon <name> 8117Attach raw 16KiB Zaxxon cartridge image. 8118 8119@findex -cartzipp 8120@item -cartzipp <name> 8121Attach raw 8KiB ZIPP-CODE 48 cartridge image. 8122@end table 8123 8124@c @node FIXME 8125@subsection CIA settings 8126 8127@c @node FIXME 8128@subsubsection CIA resources 8129 8130@table @code 8131 8132@vindex CIA1Model 8133@item CIA1Model 8134@c the exceptions will be corrected as the resource list is implemented 8135Integer specifying CIA1 model (all emulators except x64dtv, xpet, xplus4, xvic). 8136(0: old 6526, 1: new 6526A) 8137 8138@vindex CIA2Model 8139@item CIA2Model 8140@c the exceptions will be corrected as the resource list is implemented 8141Integer specifying CIA2 model (all emulators except x64dtv, xcbm2, xcbm5x0, xpet, xplus4, xvic). 8142(0: old 6526, 1: new 6526A) 8143 8144@end table 8145 8146@c @node FIXME 8147@subsubsection CIA command-line options 8148 8149@table @code 8150 8151@findex -ciamodel 8152@item -ciamodel <model> 8153Set both CIA models 8154(@code{CIA1Model}, @code{CIA2Model}) 8155@c the exceptions will be corrected as the resource list is implemented 8156(all emulators except x64dtv, xcbm2, xcbm5x0, xpet, xplus4, xvic). 8157(0: old 6526, 1: new 6526A) 8158 8159@findex -cia1model 8160@item -cia1model <model> 8161Set CIA1 model 8162(@code{CIA1Model}) 8163@c the exceptions will be corrected as the resource list is implemented 8164(all emulators except x64dtv, xpet, xplus4, xvic). 8165(0: old 6526, 1: new 6526A) 8166 8167@findex -cia2model 8168@item -cia2model <model> 8169Set CIA2 model 8170(@code{CIA2Model}) 8171@c the exceptions will be corrected as the resource list is implemented 8172(all emulators except x64dtv, xcbm2, xcbm5x0, xpet, xplus4, xvic). 8173(0: old 6526, 1: new 6526A) 8174 8175@end table 8176 8177@node VIC-II settings, SID settings, C64 cartridges, C64/128-specific 8178@subsection VIC-II settings 8179 8180These settings control the emulation of the VIC-II (MOS6569) video chip 8181used in both the C64 and the C128. 8182 8183@itemize @bullet 8184 8185@cindex Sprite collision detection 8186@item 8187``Sprite-sprite collisions'' and ``Sprite-background collisions'', if 8188enabled, cause the hardware detection of sprite-to-sprite and 8189sprite-to-background collisions of the VIC-II to be emulated. This 8190feature is used by many games, and disabling either of the two detection 8191systems can sometimes make you invincible (although there is also a 8192chance that also enemies become invincible then). 8193 8194@cindex VIC-II color sets 8195@item 8196``Color set'' can be used to dynamically change the palette file being used by 8197choosing one of the available predefined color sets, for example: 8198 8199@itemize @bullet 8200@item 8201@file{pepto-pal.vpl} (``Pepto PAL''), a Palette calculated by Philip "Pepto" Timmermann 8202(@uref{http://www.pepto.de/projects/colorvic/}). (This is the default) 8203@item 8204@file{vice.vpl} (``VICE''), the old default VICE palette. 8205@item 8206@file{c64s.vpl} (``C64S''), palette taken from the shareware C64S emulator by Miha Peternel. 8207@item 8208@file{ccs64.vpl} (``CCS64''), palette taken from the shareware CCS64 emulator by Per H�kan Sundell. 8209@item 8210@file{frodo.vpl} (``Frodo''), palette taken from the free Frodo emulator by Christian Bauer 8211(@uref{https://frodo.cebix.net/}). 8212@item 8213@file{pc64.vpl} (``PC64''), palette taken from the free PC64 emulator by Wolfgang Lorenz. 8214@item 8215@file{godot.vpl} (``GoDot''), palette as suggested by the authors of the C64 graphics package GoDot 8216(@uref{https://www.godot64.de}). 8217@end itemize 8218 8219@end itemize 8220 8221@menu 8222* VIC-II resources:: 8223* VIC-II options:: 8224@end menu 8225 8226@node VIC-II resources, VIC-II options, VIC-II settings, VIC-II settings 8227@subsubsection VIC-II resources 8228 8229@table @code 8230 8231@vindex VICIIModel 8232@item VICIIModel 8233Integer that specifies VIC-II model 8234(x64sc, xscpu64 only). 8235(6569, 6569r1, 8565, 6567, 8562, 6567r56a, 6572) 8236 8237@vindex VICIICheckSsColl 8238@item VICIICheckSsColl 8239Boolean specifying whether the sprite-sprite hardware collision 8240detection must be emulated. 8241 8242@vindex VICIICheckSbColl 8243@item VICIICheckSbColl 8244Boolean specifying whether the sprite-background hardware collision 8245detection must be emulated. 8246 8247@vindex VICIIVSPBug 8248@item VICIIVSPBug 8249Boolean specifying whether the "VSP Bug" must be emulated 8250(x64sc, xscpu64 only). 8251 8252@vindex VICIIVideoCache 8253@item VICIIVideoCache 8254Boolean specifying whether the video cache is turned on. 8255 8256@vindex VICIIDoubleSize 8257@item VICIIDoubleSize 8258Boolean specifying whether double-size mode is turned on. 8259 8260@vindex VICIIDoubleScan 8261@item VICIIDoubleScan 8262Boolean specifying whether double-scan mode is turned on. 8263 8264@vindex VICIINewLuminances 8265@item VICIINewLuminances 8266Boolean specifying whether to use new (9 steps) luminances. 8267 8268@vindex VICIIPaletteFile 8269@item VICIIPaletteFile 8270String specifying the name of the palette file being used. The 8271@file{.vpl} extension is optional. 8272 8273@vindex VICIIExternalPalette 8274@item VICIIExternalPalette 8275Boolean specifying whether to use external palette file or not. 8276 8277@vindex VICIIColorSaturation 8278@item VICIIColorSaturation 8279Integer specifying saturation of internal calculated palette. 8280(0..2000) 8281 8282@vindex VICIIColorContrast 8283@item VICIIColorContrast 8284Integer specifying contrast of internal calculated palette. 8285(0..2000) 8286 8287@vindex VICIIColorBrightness 8288@item VICIIColorBrightness 8289Integer specifying brightness of internal calculated palette. 8290(0..2000) 8291 8292@vindex VICIIColorGamma 8293@item VICIIColorGamma 8294Integer specifying gamma of internal calculated palette. 8295(0..4000) 8296 8297@vindex VICIIColorTint 8298@item VICIIColorTint 8299Integer specifying tint of internal calculated palette. 8300(0..2000) 8301 8302@vindex VICIIPALScanLineShade 8303@item VICIIPALScanLineShade 8304Integer specifying amount of scan line shading for the CRT emulation. 8305(0..1000) 8306 8307@vindex VICIIPALBlur 8308@item VICIIPALBlur 8309Integer specifying amount of horizontal blur for the CRT emulation. 8310(0..1000) 8311 8312@vindex VICIIPALOddLinePhase 8313@item VICIIPALOddLinePhase 8314Integer specifying phase for color carrier in odd lines. 8315(0..2000) 8316 8317@vindex VICIIPALOddLineOffset 8318@item VICIIPALOddLineOffset 8319Integer specifying phase offset for color carrier in odd lines. 8320(0..2000) 8321 8322@vindex VICIIAudioLeak 8323@item VICIIAudioLeak 8324Boolean specifying whether to enable/disable video to audio leak emulation. 8325 8326@vindex VICIIFilter 8327@item VICIIFilter 8328Integer specifying rendering filter. 8329(0: None, 1: CRT emulation, 2: Scale2x) 8330 8331@vindex VICIIBorderMode 8332@item VICIIBorderMode 8333Integer specifying border display mode. 8334(0: normal, 1: full, 2: debug, 3: none) 8335 8336@end table 8337 8338 8339@node VIC-II options, , VIC-II resources, VIC-II settings 8340@subsubsection VIC-II command-line options 8341 8342@table @code 8343 8344@findex -VICIIcheckss, +VICIIcheckss 8345@item -VICIIcheckss 8346@itemx +VICIIcheckss 8347Enable/disable emulation of hardware sprite-sprite collision detection 8348(@code{VICIICheckSsColl=1}, @code{VICIICheckSsColl=0}). 8349 8350@findex -VICIIchecksb, +VICIIchecksb 8351@item -VICIIchecksb 8352@itemx +VICIIchecksb 8353Enable/disable emulation of hardware sprite-background collision detection 8354(@code{VICIICheckSbColl=1}, @code{VICIICheckSbColl=0}). 8355 8356@findex -VICIIvspbug, +VICIIvspbug 8357@item -VICIIvspbug 8358@itemx +VICIIvspbug 8359Enable/disable emulation of the "VSP bug" 8360(@code{VICIIVSPBug=1}, @code{VICIIVSPBug=0}) 8361(x64sc, xscpu64 only). 8362 8363@findex -VICIIvcache, +VICIIvcache 8364@item -VICIIvcache 8365@itemx +VICIIvcache 8366Enable/disable the video cache 8367(@code{VICIIVideoCache=1}, @code{VICIIVideoCache=0}). 8368 8369@findex -VICIIdsize, +VICIIdsize 8370@item -VICIIdsize 8371@itemx +VICIIdsize 8372Enable/disable the double size mode 8373(@code{VICIIDoubleSize=1}, @code{VICIIDoubleSize=0}). 8374 8375@findex -VICIIdscan, +VICIIdscan 8376@item -VICIIdscan 8377@itemx +VICIIdscan 8378Enable/disable the double scan mode 8379(@code{VICIIDoubleScan=1}, @code{VICIIDoubleScan=0}). 8380 8381@findex -VICIIfilter 8382@item -VICIIfilter <Mode> 8383Select rendering filter 8384(@code{VICIIFilter}). 8385(0: None, 1: CRT emulation, 2: Scale2x) 8386 8387@findex -VICIIintpal 8388@item -VICIIintpal 8389Use an internal calculated palette 8390(@code{VICIIExternalPalette=0}). 8391 8392@findex -VICIIextpal 8393@item -VICIIextpal 8394Use an external palette (file) 8395(@code{VICIIExternalPalette=1}). 8396 8397@findex -VICIIpalette 8398@item -VICIIpalette <Name> 8399Specify the name of the palette file 8400(@code{VICIIPaletteFile}). 8401 8402@findex -VICIIborders 8403@item -VICIIborders <mode> 8404Set VIC-II border display mode 8405(@code{VICIIBorderMode}). 8406(0: normal, 1: full, 2: debug, 3: none) 8407 8408@findex -VICIImodel 8409@item -VICIImodel <model> 8410Set VIC-II model 8411(@code{VICIIModel}) 8412(x64sc and xscpu64 only). 8413(6569, 6569r1, 8565, 6567, 8562, 6567r56a, 6572) 8414 8415@findex -VICIInewluminance, +VICIInewluminance 8416@item -VICIInewluminance 8417@item +VICIInewluminance 8418Enable/disable new luminances 8419(@code{VICIINewLuminances=1}, @code{VICIINewLuminances=0}). 8420 8421@findex -VICIIsaturation 8422@item -VICIIsaturation <0-2000> 8423Set saturation of internal calculated palette 8424(@code{VICIIColorSaturation}). 8425 8426@findex -VICIIcontrast 8427@item -VICIIcontrast <0-2000> 8428Set contrast of internal calculated palette 8429(@code{VICIIColorContrast}). 8430 8431@findex -VICIIbrightness 8432@item -VICIIbrightness <0-2000> 8433Set brightness of internal calculated palette 8434(@code{VICIIColorBrightness}). 8435 8436@findex -VICIIgamma 8437@item -VICIIgamma <0-4000> 8438Set gamma of internal calculated palette 8439(@code{VICIIColorGamma}). 8440 8441@findex -VICIItint 8442@item -VICIItint <0-2000> 8443Set tint of internal calculated palette 8444(@code{VICIIColorTint}). 8445 8446@findex -VICIIoddlinesphase 8447@item -VICIIoddlinesphase <0-2000> 8448Set phase for color carrier in odd lines 8449(@code{VICIIPALOddLinePhase}). 8450 8451@findex -VICIIoddlinesoffset 8452@item -VICIIoddlinesoffset <0-2000> 8453Set phase offset for color carrier in odd lines 8454(@code{VICIIPALOddLineOffset}). 8455 8456@findex -VICIIcrtblur 8457@item -VICIIcrtblur <0-1000> 8458Amount of horizontal blur for the CRT emulation 8459(@code{VICIIPALBlur}). 8460 8461@findex -VICIIcrtscanlineshade 8462@item -VICIIcrtscanlineshade <0-1000> 8463Amount of scan line shading for the CRT emulation 8464(@code{VICIIPALScanLineShade}). 8465 8466@findex -VICIIaudioleak, +VICIIaudioleak 8467@item -VICIIaudioleak 8468@item +VICIIaudioleak 8469Enable/disable video to audio leak emulation 8470(@code{VICIIAudioLeak=1}, @code{VICIIAudioLeak=0}). 8471 8472@end table 8473 8474 8475@node SID settings, C64 I/O extension settings, VIC-II settings, C64/128-specific 8476@subsection SID settings 8477 8478These settings control the emulation of the SID (MOS6581 or MOS8580) 8479audio chip. 8480 8481@itemize @bullet 8482 8483@cindex Second SID 8484@item 8485``Second SID'' maps a second SID chip into the address space for stereo 8486sound. This emulates e.g. the ``SID Symphony Stereo Cartridge'' from 8487Dr. Evil Laboratories. The second SID can be used with software such as 8488``Stereo SID Player'' by Mark Dickenson or ``The Enhanced Sidplayer'' by 8489Craig Chamberlain. 8490 8491@cindex Second SID base address 8492@item 8493``Second SID base address'' sets the start address for the second SID 8494chip. Software normally uses $DE00 or $DF00, since $DE00-$DEFF and 8495$DF00-$DFFF can be mapped through the cartridge port of the C64. The 8496default start address is $DE00. 8497 8498@cindex SID filters 8499@item 8500``Emulate filters'' causes the built-in programmable filters of the SID 8501chip to be emulated. A lot of C64 music requires them to be emulated 8502properly, but their emulation requires some additional processor power. 8503 8504@cindex SID models 8505@item 8506``ChipModel'' specifies the model of the SID chip being emulated: there 8507are two slightly different generations of SID chips: MOS6581 ones and 8508MOS8580 ones. Additionally there is "8580D", which refers to MOS8580 with added 8509"Digifix" modification, which adds a DC offset to audio-in, which makes classic 8510samples audible also on the 8580. 8511 8512@cindex Toggling reSID emulation 8513@item 8514``Use reSID emulation'' specifies whether the more accurate (and 8515resource hungry) reSID emulation is turned on or off. 8516 8517@cindex reSID samping method 8518@item 8519``reSID sampling method'' selects the method for conversion of the SID 8520output signal to a sampling rate appropriate for playback by standard 8521digital sound equipment. Possible settings are: 8522@itemize @bullet 8523@item 8524``Fast'' simply clocks the SID chip at the output sampling frequency, 8525picking the nearest sample. This yields acceptable sound quality, but 8526sampling noise is noticeable in some cases, especially with SID combined 8527waveforms. The sound emulation is still cycle exact. 8528@item 8529``Interpolating'' clocks the SID chip each cycle, and calculates each 8530sample with linear interpolation. The sampling noise is now strongly 8531attenuated by the SID external filter (as long as ``Emulate filters'' is 8532selected), and the linear interpolation further improves the sound 8533quality. 8534@item 8535``Resampling'' clocks the SID chip each cycle, and uses the 8536theoretically correct method for sample generation. This delivers CD 8537quality sound, but is extremely CPU intensive, and is thus most useful 8538for non-interactive sound generation. Unless you have a very fast 8539machine, that is. 8540@end itemize 8541 8542@cindex reSID resampling passband 8543@item ``reSID resampling passband'' specifies the percentage of the 8544total bandwidth allocated to the resampling filter passband. The work 8545rate of the resampling filter is inversely proportional to the remaining 8546transition band percentage. This implies that e.g. with the transition 8547band starting at ~ 20kHz, it is faster to generate 48kHz than 44.1kHz 8548samples. For CD quality sound generation at 44.1kHz the passband 8549percentage should be set to 90 (i.e. the transition band starting at 8550almost 20kHz). 8551 8552@end itemize 8553 8554@menu 8555* SID resources:: 8556* SID options:: 8557@end menu 8558 8559@node SID resources, SID options, SID settings, SID settings 8560@subsubsection SID resources 8561 8562@table @code 8563 8564@vindex SidStereo 8565@item SidStereo 8566Integer specifying the amount of emulated extra SIDs. 8567(0: off, 1: 1 extra sid, 2: 2 extra sids, 3: three extra sids, 4: four extra sids, 5: five extra sids, 6: six extra sids, 7: seven extra sids) 8568 8569@vindex Sid2AddressStart 8570@item Sid2AddressStart 8571Integer specifying the base address of the second SID 8572(x64, x64sc, xscpu64, x128 and vsid only). 8573(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 85740xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 85750xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 85760xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8577(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 85780xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 85790xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 85800xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 85810xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 85820xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 85830xDFC0, 0xDFE0) 8584 8585@vindex Sid3AddressStart 8586@item Sid3AddressStart 8587Integer specifying the base address of the third SID 8588(x64, x64sc, xscpu64, x128 and vsid only). 8589(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 85900xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 85910xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 85920xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8593(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 85940xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 85950xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 85960xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 85970xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 85980xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 85990xDFC0, 0xDFE0) 8600 8601@vindex Sid4AddressStart 8602@item Sid4AddressStart 8603Integer specifying the base address of the fourth SID 8604(x64, x64sc, xscpu64, x128 and vsid only). 8605(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 86060xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 86070xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 86080xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8609(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 86100xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 86110xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 86120xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 86130xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 86140xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 86150xDFC0, 0xDFE0) 8616 8617@vindex Sid5AddressStart 8618@item Sid5AddressStart 8619Integer specifying the base address of the fifth SID 8620(x64, x64sc, xscpu64, x128 and vsid only). 8621(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 86220xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 86230xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 86240xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8625(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 86260xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 86270xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 86280xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 86290xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 86300xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 86310xDFC0, 0xDFE0) 8632 8633@vindex Sid6AddressStart 8634@item Sid6AddressStart 8635Integer specifying the base address of the sixth SID 8636(x64, x64sc, xscpu64, x128 and vsid only). 8637(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 86380xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 86390xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 86400xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8641(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 86420xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 86430xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 86440xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 86450xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 86460xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 86470xDFC0, 0xDFE0) 8648 8649@vindex Sid7AddressStart 8650@item Sid7AddressStart 8651Integer specifying the base address of the seventh SID 8652(x64, x64sc, xscpu64, x128 and vsid only). 8653(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 86540xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 86550xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 86560xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8657(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 86580xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 86590xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 86600xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 86610xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 86620xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 86630xDFC0, 0xDFE0) 8664 8665@vindex Sid8AddressStart 8666@item Sid8AddressStart 8667Integer specifying the base address of the eigth SID 8668(x64, x64sc, xscpu64, x128 and vsid only). 8669(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 86700xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 86710xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 86720xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8673(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 86740xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 86750xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 86760xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 86770xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 86780xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 86790xDFC0, 0xDFE0) 8680 8681 8682@vindex SidFilters 8683@item SidFilters 8684Boolean specifying whether the built-in SID filters must be emulated. 8685 8686@vindex SidModel 8687@item SidModel 8688Integer specifying what model of the SID must be emulated. 8689(0: 6581, 1: 8580, 2: 8580D, 3: DTVSID) 8690 8691@vindex SidEngine 8692@item SidEngine 8693Integer specifying what SID engine will be used. 8694(0: FastSID, 1: ReSID, 2: Catweasel MKIII, 3: HardSID, 4: ParSID Port 1, 5: ParSID Port 2, 6: ParSID Port 3) 8695 8696@vindex SidResidSampling 8697@item SidResidSampling 8698Integer specifying the sampling method (@code{0}: Fast, @code{1}: 8699Interpolation, @code{2}: Resampling, @code{3}: Fast Resampling) 8700 8701@vindex SidResidPassband 8702@item SidResidPassband 8703Integer specifying the resampling filter passband in percentage of the 8704total bandwidth (@code{0 - 90}) for 6581. 8705 8706@vindex SidResidGain 8707@item SidResidGain 8708Integer that specifies reSID gain in percent [97] (90..100) for 6581. 8709 8710@vindex SidResidFilterBias 8711@item SidResidFilterBias 8712Integer that specifies reSID filter bias for 6581, which can be used to adjust DAC bias 8713in millivolts. [0] (-5000..5000) 8714 8715@vindex SidResid8580Passband 8716@item SidResid8580Passband 8717Integer specifying the resampling filter passband in percentage of the 8718total bandwidth (@code{0 - 90}) for 8580. 8719 8720@vindex SidResid8580Gain 8721@item SidResid8580Gain 8722Integer that specifies reSID gain in percent [97] (90..100) for 8580. 8723 8724@vindex SidResid8580FilterBias 8725@item SidResid8580FilterBias 8726Integer that specifies reSID filter bias for 8580, which can be used to adjust DAC bias 8727in millivolts. [0] (-5000..5000) 8728 8729@end table 8730 8731 8732@node SID options, , SID resources, SID settings 8733@subsubsection SID command-line options 8734 8735@table @code 8736 8737@findex -sidextra 8738@item -sidextra 8739Specify the amount of extra SID chips to emulate 8740(@code{SidStereo}). 8741(0: off, 1: 1 extra sid, 2: 2 extra sids, 3: 3 extra sids, 4: 4 extra sids, 5: 5 extra sids, 6: 6 extra sids, 7: 7 extra sids) 8742 8743@findex -sid2address 8744@item -sid2address <Base address> 8745Specifies the start address for the second SID chip 8746(@code{Sid2AddressStart}) 8747(x64, x64sc, xscpu64, x128 and vsid only). 8748(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 87490xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 87500xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 87510xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8752(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 87530xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 87540xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 87550xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 87560xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 87570xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 87580xDFC0, 0xDFE0) 8759 8760@findex -sid3address 8761@item -sid3address @code{ADDRESS} 8762Specifies the start address for the third SID chip 8763(@code{Sid3AddressStart}) 8764(x64, x64sc, xscpu64, x128 and vsid only). 8765(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 87660xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 87670xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 87680xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8769(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 87700xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 87710xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 87720xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 87730xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 87740xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 87750xDFC0, 0xDFE0) 8776 8777@findex -sid4address 8778@item -sid4address @code{ADDRESS} 8779Specifies the start address for the fourth SID chip 8780(@code{Sid4AddressStart}) 8781(x64, x64sc, xscpu64, x128 and vsid only). 8782(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 87830xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 87840xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 87850xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8786(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 87870xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 87880xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 87890xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 87900xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 87910xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 87920xDFC0, 0xDFE0) 8793 8794@findex -sid5address 8795@item -sid5address @code{ADDRESS} 8796Specifies the start address for the fifth SID chip 8797(@code{Sid5AddressStart}) 8798(x64, x64sc, xscpu64, x128 and vsid only). 8799(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 88000xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 88010xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 88020xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8803(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 88040xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 88050xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 88060xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 88070xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 88080xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 88090xDFC0, 0xDFE0) 8810 8811@findex -sid6address 8812@item -sid6address @code{ADDRESS} 8813Specifies the start address for the sixth SID chip 8814(@code{Sid6AddressStart}) 8815(x64, x64sc, xscpu64, x128 and vsid only). 8816(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 88170xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 88180xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 88190xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8820(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 88210xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 88220xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 88230xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 88240xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 88250xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 88260xDFC0, 0xDFE0) 8827 8828@findex -sid7address 8829@item -sid7address @code{ADDRESS} 8830Specifies the start address for the seventh SID chip 8831(@code{Sid7AddressStart}) 8832(x64, x64sc, xscpu64, x128 and vsid only). 8833(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 88340xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 88350xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 88360xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8837(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 88380xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 88390xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 88400xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 88410xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 88420xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 88430xDFC0, 0xDFE0) 8844 8845@findex -sid8address 8846@item -sid8address @code{ADDRESS} 8847Specifies the start address for the eight SID chip 8848(@code{Sid8AddressStart}) 8849(x64, x64sc, xscpu64, x128 and vsid only). 8850(x128: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 0xD4C0, 0xD4E0, 88510xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 0xD7C0, 0xD7E0, 88520xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 88530xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8854(x64, x64sc, xscpu64, vsid: 0xD420, 0xD440, 0xD460, 0xD480, 0xD4A0, 88550xD4C0, 0xD4E0, 0xD500, 0xD520, 0xD540, 0xD560, 0xD580, 0xD5A0, 88560xD5C0, 0xD5E0, 0xD600, 0xD620, 0xD640, 0xD660, 0xD680, 0xD6A0, 88570xD6C0, 0xD6E0, 0xD700, 0xD720, 0xD740, 0xD760, 0xD780, 0xD7A0, 88580xD7C0, 0xD7E0, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 88590xDEC0, 0xDEE0, 0xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 88600xDFC0, 0xDFE0) 8861 8862@findex -sidenginemodel 8863@item -sidenginemodel <engine and model> 8864Specify engine and model for the emulated SID chip 8865(@code{SidEngine}, @code{SidModel}). 8866(FastSID 6581: 0/fast/fastold/fast6581, 8867FastSID 8580: 1/fastnew/fast8580, 8868ReSID 6581: 256/resid/residold/resid6581, 8869ReSID 8580: 257/residnew/resid8580, 8870ReSID 8580 + digiboost: 258/residdigital/residd/residnewd/resid8580d, 8871DTVSID: 260/dtv/c64dtv/dtvsid, 8872Catweasel MKIII: 512/catweaselmkiii/catweasel3/catweasel/cwmkiii/cw3/cw, 8873HardSID: 768/hardsid/hard/hs, 8874ParSID Port 1: 1024/parsid/parsid1/par1/lpt1, 8875ParSID Port 2: 1280/parsid2/par2/lpt2 8876ParSID Port 3: 1536/parsid3/par3/lpt3) 8877 8878@findex -sidfilters, +sidfilters 8879@item -sidfilters 8880@itemx +sidfilters 8881Enable/disable emulation of the built-in SID filters 8882(@code{SidFilters=1}, @code{SidFilters=0}). 8883 8884@findex -residsamp 8885@item -residsamp @code{METHOD} 8886Specifies the sampling method; fast (@code{SidResidSampling=0}), 8887interpolating (@code{SidResidSampling=1}), resampling 8888(@code{SidResidSampling=2}), fast resampling (@code{SidResidSampling=3}). 8889 8890@findex -residpass 8891@item -residpass @code{PERCENTAGE} 8892Specifies the resampling filter passband in percentage of the total 8893bandwidth (@code{SidResidPassband=0-90}) for 6581. 8894 8895@findex -residgain 8896@item -residgain @code{PERCENTAGE} 8897Specifies reSID gain in percent (90 - 100) for 6581. 8898 8899@findex -residfilterbias 8900@item -residfilterbias <number> 8901reSID filter bias setting for 6581, which can be used to adjust DAC bias in millivolts. 8902 8903@findex -resid8580pass 8904@item -residpass @code{PERCENTAGE} 8905Specifies the resampling filter passband in percentage of the total 8906bandwidth (@code{SidResid8580Passband=0-90}) for 8580. 8907 8908@findex -resid8580gain 8909@item -residgain @code{PERCENTAGE} 8910Specifies reSID gain in percent (90 - 100) for 8580. 8911 8912@findex -resid8580filterbias 8913@item -residfilterbias <number> 8914reSID filter bias setting for 8580, which can be used to adjust DAC bias in millivolts. 8915 8916@end table 8917 8918 8919@node C64 I/O extension settings, C64 system ROM settings, SID settings, C64/128-specific 8920@subsection C64 I/O extension settings 8921 8922I/O extensions are (usually) cartridges which do not map into ROM space, 8923but use only the I/O space at address range $DE00 @dots{} $DEFF and/or 8924$DF00 @dots{} $DFFF. 8925 8926Please use these extensions only when needed, as they might cause 8927compatibility problems. 8928 8929The following I/O extensions are available: 8930 8931@itemize @bullet 8932 8933@cindex ACIA (Swiftlink, Turbo232) 8934@item ACIA (Swiftlink, Turbo232) 8935 8936@cindex DigiMAX 8937@item DigiMAX 8938 8939@cindex DS12C887 RTC 8940@item DS12C887 RTC 8941 8942@cindex Ethernet (The Final Ethernet, RR-Net) 8943@item Ethernet (The Final Ethernet, RR-Net) 8944 8945@cindex GEO-RAM 8946@item GEO-RAM 8947 8948@cindex MIDI (Passport, Datel, Maplin, Namesoft, Sequential) 8949@item MIDI (Passport, Datel, Maplin, Namesoft, Sequential) 8950 8951@cindex REU 8952@item REU - 8953The ``RAM Expansion Module'' extension emulates a standard 8954Commodore RAM Expansion Unit; this can be used with GEOS and other 8955programs that are designed to take advantage of it. This currently 8956works only in the C64 emulator. 8957 8958@cindex SFX Sound Expander 8959@item SFX Sound Expander 8960 8961@cindex SFX Sound Sampler 8962@item SFX Sound Sampler 8963 8964@end itemize 8965 8966@menu 8967* C64 I/O extension resources:: 8968* C64 I/O extension options:: 8969@end menu 8970 8971@node C64 I/O extension resources, C64 I/O extension options, C64 I/O extension settings, C64 I/O extension settings 8972@subsubsection C64 I/O extension resources 8973 8974@table @code 8975 8976@vindex DIGIMAX 8977@item DIGIMAX 8978Boolean specifying whether the DigiMAX cartridge should be emulated or not. 8979 8980@vindex DIGIMAXbase 8981@item DIGIMAXbase 8982Integer specifying the DigiMAX base address. 8983(0xDD00: useport, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 89840xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 8985 8986@vindex DS12C887RTC 8987@item DS12C887RTC 8988Boolean specifying whether the DS12C887 RTC cartridge should be emulated or not. 8989 8990@vindex DS12C887RTCbase 8991@item DS12C887RTCbase 8992Integer specifying the DS12C887 RTC base address. 8993x128: (0xD700, 0xDE00, 0xDF00) 8994x64, x64sc, xscpu64: (0xD500, 0xD600, 0xD700, 0xDE00, 0xDF00) 8995 8996@vindex DS12C887RTCRunMode 8997@item DS12C887RTCRunMode 8998Boolean specifying whether the DS12C887 RTC cartridge starts out running or halted. 8999(0: halted, 1: running) 9000 9001@vindex DS12C887RTCSave 9002@item DS12C887RTCSave 9003Boolean specifying whether the DS12C887 RTC data should be saved when changed or not. 9004 9005@vindex ETHERNETCART_ACTIVE 9006@item ETHERNETCART_ACTIVE 9007Boolean that specifies whether the CS8900 ethernet interface emulation is active. 9008@vindex ETHERNET_INTERFACE 9009@item ETHERNET_INTERFACE 9010String specifying the device name of the ethernet device to use for the emulation. 9011@vindex ETHERNET_DISABLED 9012@item ETHERNET_DISABLED 9013Boolean that specified whether ethernet emulation has been disabled because it is 9014not available in the current configuration. 9015@vindex ETHERNETCARTMode 9016@item ETHERNETCARTMode 9017Boolean that specifies whether RR-Net compatible mapping is enabled. 9018@vindex ETHERNETCARTBase 9019@item ETHERNETCARTBase 9020Integer specifying the I/O base address of the emulated ethernet cartridge, 9021 9022 9023@vindex GEORAM 9024@item GEORAM 9025Boolean specifying whether the GEO-RAM cartridge should be emulated or not. 9026(x64, x64sc, x128). 9027 9028@vindex GEORAMfilename 9029@item GEORAMfilename 9030String specifying the filename of the GEORAM image. 9031(x64, x64sc, x128). 9032 9033@vindex GEORAMImageWrite 9034@item GEORAMImageWrite 9035Boolean, if true write back the GEO-RAM image file automatically, incase the RAM 9036contents changed, when detaching or quitting the emulator. 9037(x64, x64sc, x128). 9038 9039@vindex GEORAMsize 9040@item GEORAMsize 9041Integer specifying the size of the emulated GEO-RAM in KiB. 9042(64, 128, 256, 512, 1024, 2048, 4096). 9043(x64, x64sc, x128). 9044 9045@vindex MIDIEnable 9046@item MIDIEnable 9047Boolean specifying whether the MIDI cartridge should be emulated or not 9048(x64, x64sc, xscpu64, x128 only, and only if MIDI support is enabled and available at compile time). 9049 9050@vindex MIDIMode 9051@item MIDIMode 9052Integer specifying the type of emulated MIDI interface 9053(x64, x64sc, xscpu64 and x128 only, and only if MIDI support is enabled and available at compile time). 9054(0: Sequential, 1: Passport/Syntech, 2: DATEL/Siel/JMS, 3: Namesoft, 4: Maplin) 9055 9056@vindex REU 9057@item REU 9058Boolean specifying whether the RAM Expansion Module should be emulated or not. 9059 9060@vindex REUfilename 9061@item REUfilename 9062String specifying the filename of the REU image. 9063 9064@vindex REUImageWrite 9065@item REUImageWrite 9066Boolean, if true write back the REU image file automatically, in case the RAM 9067contents changed, when detaching or quitting the emulator. 9068 9069@vindex REUsize 9070@item REUsize 9071Integer specifying the size of the emulated REU in KiB. 9072(128, 256, 512, 1024, 2048, 4096, 8192, 16384) 9073 9074@vindex SFXSoundExpander 9075@item SFXSoundExpander 9076Boolean specifying whether the SFX Sound Expander should be emulated or not. 9077 9078@vindex SFXSoundExpanderChip 9079@item SFXSoundExpanderChip 9080Integer specifying which YM chip is emulated. 9081(3526, 3812) 9082 9083@vindex SFXSoundSampler 9084@item SFXSoundSampler 9085Boolean specifying whether the SFX Sound Sampler should be emulated or not. 9086 9087@end table 9088 9089 9090@node C64 I/O extension options, , C64 I/O extension resources, C64 I/O extension settings 9091@subsubsection C64 I/O extension command-line options 9092 9093@table @code 9094 9095@findex -digimax, +digimax 9096@item -digimax 9097@itemx +digimax 9098Enable/disable the DigiMAX cartridge 9099(@code{DIGIMAX=1}, @code{DIGIMAX=0}). 9100 9101@findex -digimaxbase 9102@item -digimaxbase <base address> 9103Base address of the DigiMAX cartridge 9104(@code{DIGIMAXbase}). 9105(0xDD00: userport, 0xDE00, 0xDE20, 0xDE40, 0xDE60, 0xDE80, 0xDEA0, 0xDEC0, 0xDEE0, 91060xDF00, 0xDF20, 0xDF40, 0xDF60, 0xDF80, 0xDFA0, 0xDFC0, 0xDFE0) 9107 9108@findex -ds12c887rtc, +ds12c887rtc 9109@item -ds12c887rtc 9110@itemx +ds12c887rtc 9111Enable/disable the DS12C887 RTC cartridge 9112(@code{DS12C887RTC=1}, @code{DS12C887RTC=0}). 9113 9114@findex -ds12c887rtcbase 9115@item -ds12c887rtcbase <base address> 9116Base address of the DS12C887 RTC cartridge 9117(@code{DS12C887RTCbase}). 9118x128: (0xD700, 0xDE00, 0xDF00) 9119x64, x64sc, xscpu64: (0xD500, 0xD600, 0xD700, 0xDE00, 0xDF00) 9120 9121@findex -ds12c887rtchalted, -ds12c887rtcrunning 9122@item -ds12c887rtchalted 9123Set the DS12C887 RTC oscillator to 'halted' 9124(@code{DS12C887RTCRunMode=0}). 9125@item -ds12c887rtcrunning 9126Set the DS12C887 RTC oscillator to 'running' 9127(@code{DS12C887RTCRunMode=1}). 9128 9129@findex -ds12c887rtcsave, +ds12c887rtcsave 9130@item -ds12c887rtcsave 9131@itemx +ds12c887rtcsave 9132Enable/disable saving of the DS12C887 RTC data when changed 9133(@code{DS12C887RTCSave=1}, @code{DS12C887RTCSave=0}). 9134 9135@findex -miditype 9136@item -miditype <0-4> 9137Set MIDI interface type 9138(@code{MIDIMode}) 9139(x64, x64sc, xscpu64 and x128 only, and only if MIDI support is enabled and available at compile time). 9140(0: Sequential, 1: Passport/Syntech, 2: DATEL/Siel/JMS, 3: Namesoft, 4: Maplin) 9141 9142@findex -midi, +midi 9143@item -midi 9144@itemx +midi 9145Enable/disable MIDI emulation 9146(@code{MIDIEnable=1}, @code{MIDIEnable=0}) 9147(x64, x64sc, xscpu64 and x128 only, and only if MIDI support is enabled and available at compile time). 9148(0: Sequential, 1: Passport/Syntech, 2: DATEL/Siel/JMS, 3: Namesoft, 4: Maplin) 9149 9150@findex -georam, +georam 9151@item -georam 9152@itemx +georam 9153Enable/disable the GEORAM expansion unit 9154(@code{GEORAM=1}, @code{GEORAM=0}). 9155 9156@findex -cartgeoram 9157@item -cartgeoram <name> 9158Attach raw GEO-RAM cartridge image. 9159 9160@findex -georamimage 9161@item -georamimage <name> 9162Specify name of GEORAM image 9163(@code{GEORAMfilename}). 9164 9165@findex -georamimagerw, +georamimagerw 9166@item -georamimagerw 9167@itemx +georamimagerw 9168Allow/disallow writing to GEORAM image 9169(@code{GEORAMImageWrite=1}, @code{GEORAMImageWrite=0}). 9170 9171@findex -georamsize 9172@item -georamsize <size in KiB> 9173Size of the GEORAM expansion unit 9174(@code{GEORAMsize}). 9175(64, 128, 256, 512, 1024, 2048, 4096) 9176 9177@findex -reu, +reu 9178@item -reu 9179@itemx +reu 9180Enable/disable emulation of the RAM Expansion Module 9181(@code{REU=1}, @code{REU=0}). 9182 9183@findex -cartreu 9184@item -cartreu <name> 9185Attach raw REU cartridge image. 9186 9187@findex -reuimage 9188@item -reuimage <name> 9189Specify name of REU image 9190(@code{REUfilename}). 9191 9192@findex -reuimagerw, +reuimagerw 9193@item -reuimagerw 9194@itemx +reuimagerw 9195Allow/disallow writing to REU image 9196(@code{REUImageWrite=1}, @code{REUImageWrite=0}). 9197 9198@findex -reusize 9199@item -reusize <size in KiB> 9200Size of the RAM expansion unit 9201(@code{REUsize}). 9202(128, 256, 512, 1024, 2048, 4096, 8192, 16384) 9203 9204@findex -sfxse, +sfxse 9205@item -sfxse 9206@itemx +sfxse 9207Enable/disable the SFX soundexpander cartridge 9208(@code{SFXSoundExpander=1}, @code{SFXSoundExpander=0}). 9209 9210@findex -sfxsetype 9211@item -sfxsetype <type> 9212Set YM chip type 9213(@code{SFXSoundExpanderChip}). 9214(3526, 3812) 9215 9216@findex -sfxss, +sfxss 9217@item -sfxss 9218@itemx +sfxss 9219Enable/disable the SFX Sound Sampler cartridge 9220(@code{SFXSoundSampler=1}, @code{SFXSoundSampler=0}). 9221 9222@findex -cs8900ioif 9223@item -cs8900ioif <name> 9224Set the system ethernet interface for Ethernet Cartridge emulation 9225 9226@findex -ethernetcart, +ethernetcart 9227@item -ethernetcart 9228@itemx +ethernetcart 9229Disable/Enable the Ethernet Cartridge (TFE/RR-Net/64NIC/FB-NET) 9230 9231@findex -ethernetcartmode 9232@item -ethernetcartmode <Mode> 9233Mode of Ethernet Cartridge (0: TFE, 1: RR-Net) 9234 9235@findex -ethernetcartbase 9236@item -ethernetcartbase <Base address> 9237Base address of the Ethernet Cartridge. (0xDE00, 0xDE10, 0xDE20, 0xDE30, 0xDE40, 92380xDE50, 0xDE60, 0xDE70, 0xDE80, 0xDE90, 0xDEA0, 0xDEB0, 0xDEC0, 0xDED0, 0xDEE0, 92390xDEF0, 0xDF00, 0xDF10, 0xDF20, 0xDF30, 0xDF40, 0xDF50, 0xDF60, 0xDF70, 0xDF80, 92400xDF90, 0xDFA0, 0xDFB0, 0xDFC0, 0xDFD0, 0xDFE0, 0xDFF0) 9241 9242@findex -tfe 9243@item -tfe 9244Enable the Ethernet Cartridge in TFE ("The Final Ethernet") compatible mode and set default I/O address 9245 9246@findex -rrnet 9247@item -rrnet 9248Enable the Ethernet Cartridge in RR-Net compatible mode and set default I/O address 9249 9250@findex -burstmod 9251@item -burstmod <value> 9252Set the kind of burst modification. This emulates the fast serial bus connection 9253as described at @uref{https://a1bert.kapsi.fi/Dev/burst/}, with the wire to 9254the tape port cut 9255(@code{BurstMod}). 9256(0: None, 1: CIA-1, 2: CIA-2) 9257 9258@end table 9259 9260@node C64 system ROM settings, , C64 I/O extension settings, C64/128-specific 9261@subsection C64 system ROM settings 9262 9263These settings can be used to control what system ROMs are loaded in the 9264C64 emulator at startup. They cannot be changed from the menus. 9265 9266@menu 9267* C64 system ROM resources:: 9268* C64 system ROM options:: 9269@end menu 9270 9271@node C64 system ROM resources, C64 system ROM options, C64 system ROM settings, C64 system ROM settings 9272@subsubsection C64 system ROM resources 9273 9274@table @code 9275 9276@vindex BasicName 9277@item BasicName 9278String specifying the name of the Basic ROM (default @file{basic}). 9279 9280@vindex ChargenName 9281@item ChargenName 9282String specifying the name of the character generator ROM (default @file{chargen}). 9283 9284@vindex KernalName 9285@item KernalName 9286String specifying the name of the Kernal ROM (default @file{kernal}). 9287 9288@vindex KernalRev 9289@item KernalRev 9290String specifying the Kernal revision. This resource can be used to 9291control what revision of the C64 kernal is being used; it cannot be 9292changed at runtime. VICE is able to automatically convert one ROM 9293revision into another, by manually patching the loaded image. This way, 9294it is possible to use any of the ROM revisions without changing the ROM 9295set. Valid values are: 9296 9297@table @code 9298@item 0 9299Kernal revision 0; 9300@item 3 9301Kernal revision 3; 9302@item sx 9303@itemx 67 9304Commodore SX-64 ROM; 9305@item 100 9306@item 4064 9307Commodore 4064 (also known as ``PET64'' or ``Educator 64'') ROM. 9308@end table 9309 9310@end table 9311 9312@node C64 system ROM options, , C64 system ROM resources, C64 system ROM settings 9313@subsubsection C64 system ROM command-line options 9314 9315@table @code 9316 9317@findex -basic 9318@item -basic <name> 9319Specify filename of the Basic ROM file 9320(@code{BasicName}). 9321 9322@findex -chargen 9323@item -chargen <name> 9324Specify filename of the character generator ROM file 9325(@code{ChargenName}). 9326 9327@findex -kernal 9328@item -kernal <name> 9329Specify filename of the Kernal ROM file 9330(@code{KernalName}). 9331 9332@findex -kernalrev 9333@item -kernalrev <revision> 9334Specify Kernal revision 9335(@code{KernalRev}). 9336(1/2/3, 67/sx, 100/4064) 9337@end table 9338 9339@c @node FIXME 9340@subsection C64 settings 9341 9342@c @node FIXME 9343@subsubsection C64 resources 9344 9345@table @code 9346 9347@vindex GlueLogic 9348@item GlueLogic 9349Integer specifying the type of emulated glue-logic. 9350(0: discrete, 1: custom IC) 9351 9352@vindex BurstMod 9353@item BurstMod 9354Integer specifying the kind of Burst-Mode modification. 9355(0: None, 1: CIA-1, 2: CIA-2) 9356 9357@vindex BoardType 9358@item BoardType 9359Integer specifying the type of emulated board (not available in xscpu64). 9360(0: C64, 1: MAX) 9361 9362@vindex IECReset 9363@item IECReset 9364Integer specifying if the IEC bus resets when the CPU resets. 9365(0: No, 1: Yes) 9366 9367@vindex MemoryHack 9368@item MemoryHack 9369Integer specifying what memory expansion hack is active. 9370(0: None, 1: C64 256K, 2: PLUS60K, 3: PLUS256K) 9371 9372@vindex PLUS60Kfilename 9373@item PLUS60Kfilename 9374String specifying the filename of the PLUS60K RAM image. 9375 9376@vindex PLUS60Kbase 9377@item PLUS60Kbase 9378Integer that specifies the base address of the PLUS60K RAM expansion. 9379(0xD040, 0xD100) 9380 9381@vindex PLUS256Kfilename 9382@item PLUS256Kfilename 9383String specifying the filename of the PLUS256K RAM image. 9384 9385@vindex C64_256Kfilename 9386@item C64_256Kfilename 9387String specifying the filename of the 256KiB RAM image. 9388 9389@vindex C64_256Kbase 9390@item C64_256Kbase 9391Integer that specifies the base address of the 256KiB RAM expansion. 9392(0xDE00/0xDE80/0xDF00/0xDF80) 9393 9394@vindex MachineVideoStandard 9395@item MachineVideoStandard 9396Integer that specifies the video standard of the emulated machine 9397(0: PAL, 1: Old PAL, 2: NTSC, 3: Old NTSC, 4: PAL-N). 9398 9399@vindex CPMCart 9400@item CPMCart 9401Boolean that specifies if a CP/M cartridge is attached. 9402 9403@end table 9404 9405@c @node FIXME 9406@subsubsection C64 command-line options 9407 9408@table @code 9409 9410@findex -gluelogictype 9411@item -gluelogictype <type> 9412Set glue logic type 9413(@code{GlueLogic}). 9414(0: discrete, 1: 252535-01) 9415 9416@findex -iecreset 9417@item -iecreset <value> 9418Set IEC reset bahaviour 9419(@code{IECReset}). 9420(0: Do not reset with CPU reset, 1: Reset with CPU reset) 9421 9422@findex -memoryexphack 9423@item -memoryexphack <device> 9424Set active memory expansion hack 9425(@code{MemoryHack}). 9426(0: None, 1: C64 256K, 2: PLUS60K, 3: PLUS256K) 9427 9428@findex -plus60kimage 9429@item -plus60kimage <name> 9430Specify name of PLUS60K image 9431(@code{PLUS60Kfilename}). 9432 9433@findex -plus60kbase 9434@item -plus60kbase <base address> 9435Base address of the PLUS60K expansion 9436(@code{PLUS60Kbase}). 9437(0xD040/0xD100) 9438 9439 9440@findex -plus256kimage 9441@item -plus256kimage <name> 9442Specify name of PLUS256K image 9443(@code{PLUS256Kfilename}). 9444 9445@findex -256kimage 9446@item -256kimage <name> 9447Specify name of 256K image 9448(@code{C64_256Kfilename}). 9449 9450@findex -256kbase 9451@item -256kbase <base address> 9452Base address of the 256KiB expansion 9453(@code{C64_256Kbase}). 9454(0xDE00, 0xDE80, 0xDF00, 0xDF80) 9455 9456@findex -pal 9457@item -pal 9458Use PAL sync factor 9459(@code{MachineVideoStandard=1}). 9460 9461@findex -ntsc 9462@item -ntsc 9463Use NTSC sync factor 9464(@code{MachineVideoStandard=2}). 9465 9466@findex -ntscold 9467@item -ntscold 9468Use old NTSC sync factor 9469(@code{MachineVideoStandard=3}). 9470 9471@findex -paln 9472@item -paln 9473Use PAL-N sync factor 9474(@code{MachineVideoStandard=4}). 9475 9476@findex -model 9477@item -model <Model> 9478Set the C64 model 9479(@code{VICIIModel}, @code{CIA1Model}, @code{CIA2Model}, @code{GlueLogic}, @code{BoardType}, @code{IECReset}, @code{KernalName}, 9480@code{ChargenName}, @code{SidEngine}, @code{SidModel}) 9481(x64 and x64sc only). 9482(c64/c64c/c64old, ntsc/newntsc/oldntsc, drean, jap, c64gs, pet64, ultimax) 9483 9484@findex -cpmcart, +cpmcart 9485@item -cpmcart 9486@itemx +cpmcart 9487Enable/disable the CP/M cartridge 9488(@code{CPMCart=1}, @code{CPMCart=0}) 9489 9490@end table 9491 9492@c ----------------------------------------------------------------------------- 9493 9494@node C128-specific, C64DTV-specific, C64/128-specific, Machine-specific features 9495@section C128-specific commands and settings 9496 9497@c @node FIXME 9498@subsection VDC settings 9499 9500@c @node FIXME 9501@subsubsection VDC resources 9502 9503@table @code 9504 9505@vindex VDC64KB 9506@item VDC64KB 9507Boolean to enabled/disable full 64KiB video ram. 9508 9509@vindex VDCRevision 9510@item VDCRevision 9511Integer specifying the VDC hardware revision 9512(0: Rev 0, 1: Rev 1, 2: Rev 2). 9513 9514@vindex VDCVideoCache 9515@item VDCVideoCache 9516Boolean specifying whether the video cache is turned on. 9517 9518@vindex VDCDoubleSize 9519@item VDCDoubleSize 9520Boolean specifying whether double-size mode is turned on. 9521 9522@vindex VDCDoubleScan 9523@item VDCDoubleScan 9524Boolean specifying whether double-scan mode is turned on. 9525 9526@vindex VDCStretchVertical 9527@item VDCStretchVertical 9528Boolean specifying whether vertical stretching is turned on. 9529 9530@vindex VDCPaletteFile 9531@item VDCPaletteFile 9532String specifying the name of the palette file being used. The 9533@file{.vpl} extension is optional. 9534 9535@vindex VDCExternalPalette 9536@item VDCExternalPalette 9537Boolean specifying whether to use external palette file or not. 9538 9539@vindex VDCColorSaturation 9540@item VDCColorSaturation 9541Integer specifying saturation of internal calculated palette. 9542(0..2000) 9543 9544@vindex VDCColorContrast 9545@item VDCColorContrast 9546Integer specifying contrast of internal calculated palette. 9547(0..2000) 9548 9549@vindex VDCColorBrightness 9550@item VDCColorBrightness 9551Integer specifying brightness of internal calculated palette. 9552(0..2000) 9553 9554@vindex VDCColorGamma 9555@item VDCColorGamma 9556Integer specifying gamma of internal calculated palette. 9557(0..4000) 9558 9559@vindex VDCColorTint 9560@item VDCColorTint 9561Integer specifying tint of internal calculated palette. 9562(0..2000) 9563 9564@vindex VDCPALScanLineShade 9565@item VDCPALScanLineShade 9566Integer specifying amount of scan line shading for the CRT emulation. 9567(0..1000) 9568 9569@vindex VDCPALBlur 9570@item VDCPALBlur 9571Integer specifying amount of horizontal blur for the CRT emulation. 9572(0..1000) 9573 9574@vindex VDCPALOddLinePhase 9575@item VDCPALOddLinePhase 9576Integer specifying phase for color carrier in odd lines. 9577(0..2000) 9578 9579@vindex VDCPALOddLineOffset 9580@item VDCPALOddLineOffset 9581Integer specifying phase offset for color carrier in odd lines. 9582(0..2000) 9583 9584@vindex VDCAudioLeak 9585@item VDCAudioLeak 9586Boolean specifying whether to enable/disable video to audio leak emulation. 9587 9588@vindex VDCFilter 9589@item VDCFilter 9590Integer specifying rendering filter 9591(0: None, 1: CRT emulation, 2: Scale2x) 9592@end table 9593 9594@c @node FIXME 9595@subsubsection VDC command-line options 9596 9597@table @code 9598@findex -VDCvcache, +VDCvcache 9599@item -VDCvcache 9600@itemx +VDCvcache 9601Enable/disable the video cache 9602(@code{VDCVideoCache=1}, @code{VDCVideoCache=0}). 9603 9604@findex -VDCdsize, +VDCdsize 9605@item -VDCdsize 9606@itemx +VDCdsize 9607Enable/disable double size 9608(@code{VDCDoubleSize=1}, @code{VDCDoubleSize=0}). 9609 9610@findex -VDCstretchvertical, +VDCstretchvertical 9611@item -VDCstretchvertical 9612@itemx +VDCstretchvertical 9613Enable/Disable vertical stretching 9614(@code{VDCStretchVertical=1}, @code{VDCStretchVertical=0}). 9615 9616@findex -VDCdscan, +VDCdscan 9617@item -VDCdscan 9618@itemx +VDCdscan 9619Enable/disable double scan 9620(@code{VDCDoubleScan=1}, @code{VDCDoubleScan=0}). 9621 9622@findex -VDCintpal 9623@item -VDCintpal 9624Use an internal calculated palette 9625(@code{VDCExternalPalette=0}). 9626 9627@findex -VDCextpal 9628@item -VDCextpal 9629Use an external palette (file) 9630(@code{VDCExternalPalette=1}). 9631 9632@findex -VDCpalette 9633@item -VDCpalette <name> 9634Specify name of file of external palette 9635(@code{VDCPaletteFile}). 9636 9637@findex -VDC16KB 9638@item -VDC16KB 9639Set the VDC memory size to 16KiB 9640(@code{VDC64KB=0}). 9641 9642@findex -VDC64KB 9643@item -VDC64KB 9644Set the VDC memory size to 64KiB 9645(@code{VDC64KB=1}). 9646 9647@findex -VDCRevision 9648@item -VDCRevision <number> 9649Set VDC revision 9650(@code{VDCRevision}). 9651(0..2) 9652 9653@findex -VDCsaturation 9654@item -VDCsaturation <0-2000> 9655Set saturation of internal calculated palette 9656(@code{VDCColorSaturation}). 9657 9658@findex -VDCcontrast 9659@item -VDCcontrast <0-2000> 9660Set contrast of internal calculated palette 9661(@code{VDCColorContrast}). 9662 9663@findex -VDCbrightness 9664@item -VDCbrightness <0-2000> 9665Set brightness of internal calculated palette 9666(@code{VDCColorBrightness}). 9667 9668@findex -VDCgamma 9669@item -VDCgamma <0-4000> 9670Set gamma of internal calculated palette 9671(@code{VDCColorGamma}). 9672 9673@findex -VDCtint 9674@item -VDCtint <0-2000> 9675Set tint of internal calculated palette 9676(@code{VDCColorTint}). 9677 9678@findex -VDCoddlinesphase 9679@item -VDCoddlinesphase <0-2000> 9680Set phase for color carrier in odd lines 9681(@code{VDCPALOddLinePhase}). 9682 9683@findex -VDCoddlinesoffset 9684@item -VDCoddlinesoffset <0-2000> 9685Set phase offset for color carrier in odd lines 9686(@code{VDCPALOddLineOffset}). 9687 9688@findex -VDCcrtblur 9689@item -VDCcrtblur <0-1000> 9690Amount of horizontal blur for the CRT emulation 9691(@code{VDCPALBlur}). 9692 9693@findex -VDCcrtscanlineshade 9694@item -VDCcrtscanlineshade <0-1000> 9695Amount of scan line shading for the CRT emulation 9696(@code{VDCPALScanLineShade}). 9697 9698@findex -VDCaudioleak, +VDCaudioleak 9699@item -VDCaudioleak 9700@item +VDCaudioleak 9701Enable/disable video to audio leak emulation 9702(@code{VDCAudioLeak=1}, @code{VDCAudioLeak=0}). 9703 9704@findex -VDCfilter 9705@item -VDCfilter <Mode> 9706Select rendering filter 9707(@code{VDCFilter}). 9708(0: None, 1: CRT emulation, 2: Scale2x) 9709 9710@end table 9711 9712@c @node FIXME 9713@subsection C128 system ROM settings 9714 9715@c @node FIXME 9716@subsubsection C128 system ROM resources 9717 9718@table @code 9719 9720@vindex ChargenIntName 9721@item ChargenIntName 9722String specifying the filename of the international character generator ROM image. 9723 9724@vindex ChargenDEName 9725@item ChargenDEName 9726String specifying the filename of the German character generator ROM image. 9727 9728@vindex ChargenFRName 9729@item ChargenFRName 9730String specifying the filename of the French character generator ROM image. 9731 9732@vindex ChargenSEName 9733@item ChargenSEName 9734String specifying the filename of the Swedish character generator ROM image. 9735 9736@vindex ChargenCHName 9737@item ChargenCHName 9738String specifying the filename of the Swiss character generator ROM image. 9739 9740@vindex ChargenNOName 9741@item ChargenNOName 9742String specifying the filename of the Norwegian character generator ROM image. 9743 9744@vindex KernalIntName 9745@item KernalIntName 9746String specifying the filename of the international Kernal ROM image. 9747 9748@vindex KernalDEName 9749@item KernalDEName 9750String specifying the filename of the German Kernal ROM image. 9751 9752@vindex KernalFIName 9753@item KernalFIName 9754String specifying the filename of the Finnish Kernal ROM image. 9755 9756@vindex KernalFRName 9757@item KernalFRName 9758String specifying the filename of the French Kernal ROM image. 9759 9760@vindex KernalITName 9761@item KernalITName 9762String specifying the filename of the Italian Kernal ROM image. 9763 9764@vindex KernalNOName 9765@item KernalNOName 9766String specifying the filename of the Norwegian Kernal ROM image. 9767 9768@vindex KernalSEName 9769@item KernalSEName 9770String specifying the filename of the Swedish Kernal ROM image. 9771 9772@vindex KernalCHName 9773@item KernalCHName 9774String specifying the filename of the Swiss Kernal ROM image. 9775 9776@vindex BasicLoName 9777@vindex BasicHiName 9778@item BasicLoName 9779@itemx BasicHiName 9780Strings specifying the filename of the Basic ROM images. 9781 9782@vindex Kernal64Name 9783@item Kernal64Name 9784String specifying the filename of the C64 Kernal ROM image. 9785 9786@vindex Basic64Name 9787@item Basic64Name 9788String specifying the filename of the C64 Basic ROM image. 9789 9790@vindex InternalFunctionROM 9791@item InternalFunctionROM 9792Integer specifying the internal function ROM type 9793(0: None, 1: ROM, 2: RAM, 3: RTC). 9794 9795@vindex InternalFunctionName 9796@item InternalFunctionName 9797String specifying the filename of the ROM image for the internal function ROM. 9798 9799@vindex InternalFunctionROMRTCSave 9800@item InternalFunctionROMRTCSave 9801Boolean to enable/disable the saving of the Internal Function RTC data when changed. 9802 9803@vindex ExternalFunctionROM 9804@item ExternalFunctionROM 9805Integer specifying the external function ROM type 9806(0: None, 1: ROM, 2: RAM, 3: RTC) 9807 9808@vindex ExternalFunctionName 9809@item ExternalFunctionName 9810String specifying the filename of the ROM image for the external function ROM. 9811 9812@vindex ExternalFunctionROMRTCSave 9813@item ExternalFunctionROMRTCSave 9814Boolean to enable/disable the saving of the External Function RTC data when changed. 9815 9816@end table 9817 9818@c @node FIXME 9819@subsubsection C128 system ROM command-line options 9820 9821@table @code 9822 9823@findex -basic64 9824@item -basic64 <name> 9825Specify name of C64 mode BASIC ROM image 9826(@code{Basic64Name}). 9827 9828@findex -kernal64 9829@item -kernal64 <name> 9830Specify name of C64 mode Kernal ROM image 9831(@code{Kernal64Name}). 9832 9833@findex -basiclo 9834@item -basiclo <name> 9835Specify name of BASIC ROM image (lower part) 9836(@code{BasicLoName}). 9837 9838@findex -basichi 9839@item -basichi <name> 9840Specify name of BASIC ROM image (higher part) 9841(@code{BasicHiName}). 9842 9843@findex -kernal 9844@item -kernal <name> 9845Specify name of international Kernal ROM image 9846(@code{KernalIntName}). 9847 9848@findex -kernalde 9849@item -kernalde <name> 9850Specify name of German Kernal ROM image 9851(@code{KernalDEName}). 9852 9853@findex -kernalfi 9854@item -kernalfi <name> 9855Specify name of Finnish Kernal ROM image 9856(@code{KernalFIName}). 9857 9858@findex -kernalfr 9859@item -kernalfr <name> 9860Specify name of French Kernal ROM image 9861(@code{KernalFRName}). 9862 9863@findex -kernalit 9864@item -kernalit <name> 9865Specify name of Italian Kernal ROM image 9866(@code{KernalITName}). 9867 9868@findex -kernalno 9869@item -kernalno <name> 9870Specify name of Norwegian Kernal ROM image 9871(@code{KernalNOName}). 9872 9873@findex -kernalse 9874@item -kernalse <name> 9875Specify name of Swedish Kernal ROM image 9876(@code{KernalSEName}). 9877 9878@findex -kernalch 9879@item -kernalch <name> 9880Specify name of Swiss Kernal ROM image 9881(@code{KernalCHName}). 9882 9883@findex -chargen 9884@item -chargen <name> 9885Specify name of international character generator ROM image 9886(@code{ChargenIntName}). 9887 9888@findex -chargde 9889@item -chargde <name> 9890Specify name of German character generator ROM image 9891(@code{ChargenDEName}). 9892 9893@findex -chargfr 9894@item -chargfr <name> 9895Specify name of French character generator ROM image 9896(@code{ChargenFRName}). 9897 9898@findex -chargse 9899@item -chargse <name> 9900Specify name of Swedish character generator ROM image 9901(@code{ChargenSEName}). 9902 9903@findex -chargch 9904@item -chargch <name> 9905Specify name of Swiss character generator ROM image 9906(@code{ChargenCHName}). 9907 9908@findex -chargno 9909@item -chargno <name> 9910Specify name of Norwegian character generator ROM image 9911(@code{ChargenNOName}). 9912 9913@findex -intfunc 9914@item -intfunc <type> 9915Set the internal Function ROM type 9916(@code{InternalFunctionROM}). 9917(0: None, 1: ROM, 2: RAM, 3: RTC) 9918 9919@findex -intfrom 9920@item -intfrom <name> 9921Specify name of internal Function ROM image 9922(@code{InternalFunctionName}). 9923 9924@findex -intfuncrtcsave, +intfuncrtcsave 9925@item -intfuncrtcsave 9926@itemx +intfuncrtcsave 9927Enable/disable the saving of the Internal Function RTC data when changed 9928(@code{InternalFunctionROMRTCSave=1}, @code{InternalFunctionROMRTCSave=0}). 9929 9930@findex -extfunc 9931@item -extfunc <type> 9932Set the external Function ROM type 9933(@code{ExternalFunctionROM}). 9934(0: None, 1: ROM, 2: RAM, 3: RTC) 9935 9936@findex -extfrom 9937@item -extfrom <name> 9938Specify name of external Function ROM image 9939(@code{ExternalFunctionName}). 9940 9941@findex -extfuncrtcsave, +extfuncrtcsave 9942@item -extfuncrtcsave 9943@itemx +extfuncrtcsave 9944Enable/disable the saving of the External Function RTC data when changed 9945(@code{ExternalFunctionROMRTCSave=1}, @code{ExternalFunctionROMRTCSave=0}). 9946 9947@end table 9948 9949@c @node FIXME 9950@subsection C128 settings 9951 9952@c @node FIXME 9953@subsubsection C128 resources 9954 9955@table @code 9956 9957@c Rename to C128ColumnSwitch or so 9958@vindex C128ColumnKey 9959@item C128ColumnKey 9960Boolean specifying the status of the 40/80 columns key. 9961(0: Not pressed, 1: Pressed) 9962 9963@vindex Go64Mode 9964@item Go64Mode 9965Boolean, if true enter C64 mode on reset. 9966 9967@vindex C128FullBanks 9968@item C128FullBanks 9969Boolean to enable/disable RAM banks 2 and 3. 9970 9971@vindex MachineType 9972@item MachineType 9973Integer specifying the C128 machine type. 9974(0: International, 1: Finnish, 2: French, 3: German, 4: Italian, 5: Norwegian, 6: Swedish) 9975 9976@vindex MachineVideoStandard 9977@item MachineVideoStandard 9978Integer that specifies the video standard of the emulated machine 9979(1: PAL, 2: NTSC). 9980 9981@vindex C128HideVDC 9982@item C128HideVDC 9983Boolean to enable/disable the VDC display window. 9984 9985@end table 9986 9987@c @node FIXME 9988@subsubsection C128 command-line options 9989 9990@table @code 9991 9992@findex -40col 9993@item -40col 9994Activate 40 column mode 9995(@code{C128ColumnKey=1}). 9996 9997@findex -80col 9998@item -80col 9999Activate 80 column mode 10000(@code{C128ColumnKey=0}). 10001 10002@findex -go64, +go64 10003@item -go64 10004Always switch to C64 mode on reset 10005(@code{Go64Mode=1}. 10006@item +go64 10007Always switch to C128 mode on reset 10008(@code{Go64Mode=0}. 10009 10010@findex -pal 10011@item -pal 10012Use PAL sync factor 10013(@code{MachineVideoStandard=1}). 10014 10015@findex -ntsc 10016@item -ntsc 10017Use NTSC sync factor 10018(@code{MachineVideoStandard=2}). 10019 10020@findex -model 10021@item -model <Model> 10022Set the C128 model 10023(@code{MachineVideoStandard}, @code{CIA1Model}, @code{CIA2Model}, @code{VICIINewLuminances}, @code{VDCRevision}, 10024@code{VDC64KB}, @code{SidEngine}, @code{SidModel}). 10025(c128/c128dcr, pal/ntsc) 10026 10027@findex -c128fullbanks, +c128fullbanks 10028@item -c128fullbanks 10029@itemx +c128fullbanks 10030Enable/disable RAM banks 2 and 3 10031(@code{C128FullBanks=1}, @code{C128FullBanks=0}). 10032 10033@findex -machinetype 10034@item -machinetype <Type> 10035Set the C128 machine type 10036(@code{MachineType}). 10037(0: International, 1: Finnish, 2: French, 3: German, 4: Italian, 5: Norwegian, 6: Swedish) 10038 10039@findex -hidevdcwindow, +hidevdcwindow 10040@item -hidevdcwindow 10041@itemx +hidevdcwindow 10042Hide/show the VDC display window 10043(@code{C128HideVDC=1}, @code{C128HideVDC=0}). 10044 10045@end table 10046 10047@c ----------------------------------------------------------------------------- 10048 10049@node C64DTV-specific, SCPU64-specific, C128-specific, Machine-specific features 10050@section C64DTV-specific commands and settings 10051 10052This section lists the settings and commands that are C64DTV specific 10053and thus are not present in the other emulators. 10054 10055@menu 10056* C64DTV ROM image:: 10057* DTV revision:: 10058* LumaFix:: 10059* Userport:: 10060* Debug:: 10061* Monitor DTV features:: 10062@end menu 10063 10064 10065@node C64DTV ROM image, DTV revision, C64DTV-specific, C64DTV-specific 10066@subsection C64DTV ROM image 10067 10068The DTV has a 2MiB Flash chip which contains the kernal, basic and 10069character set ROMs along with other data, such as games in the case of 10070the original C64DTV ROM. 10071 10072The image file is a dump of the flash chip. It is exactly 2MiB (2097152 bytes). 10073 10074If you do not have a suitable image file, an image using the C64 kernal, 10075basic and charset is automatically created. 10076 10077If writing to the C64DTV ROM is enabled, the image file is rewritten with 10078the current data when exiting x64dtv. 10079 10080Note that x64dtv tries to load the image file from the C64DTV 10081directory first, and if it isn't found there, x64dtv tries to 10082load it from the current directory. If you do not have @file{dtvrom.bin} 10083in your C64DTV directory and writing to DTV ROM is enabled, 10084the @file{dtvrom.bin} file is created to the current directory. 10085 10086NOTE: The original C64DTV ROM has somewhat distorted colors, 10087normally you should use a patched rom. 10088 10089@table @code 10090 10091@findex -c64dtvromimage 10092@item -c64dtvromimage <name> 10093Specify filename of the C64DTV ROM image 10094(@code{c64dtvromfilename}). 10095 10096@findex -c64dtvromrw, +c64dtvromrw 10097@item -c64dtvromrw 10098@itemx +c64dtvromrw 10099Enable/disable writing to C64DTV ROM image 10100(@code{c64dtvromrw=1}, @code{c64dtvromrw=0}). 10101 10102@end table 10103 10104The trueflashfs option is analogous to True drive emulation. If disabled, 10105any file access to the flash filesystem (device 1) will go to the local 10106file system instead. 10107 10108@table @code 10109 10110@findex -trueflashfs, +trueflashfs 10111@item -trueflashfs 10112@itemx +trueflashfs 10113Enable/disable true hardware flash file system 10114(@code{FlashTrueFS=1}, @code{FlashTrueFS=0}). 10115 10116@findex -fsflash 10117@item -fsflash <name> 10118Specify the directory for the flash file system device 10119(@code{FSFlashDir}). 10120 10121@end table 10122 10123 10124@node DTV revision, LumaFix, C64DTV ROM image, C64DTV-specific 10125@subsection DTV revision 10126 10127The DTV revision 2 has a bug in the Blitter. Using revision 3 10128is recommended. Emulation of DTV revision 2 including Blitter 10129bug is intended for testing DTV software. 10130 10131@table @code 10132 10133@findex -dtvrev 10134@item -dtvrev <revision> 10135Specify DTV revision 10136(@code{DtvRevision}). 10137(2: DTV2, 3: DTV3) 10138 10139@end table 10140 10141 10142@node LumaFix, Userport, DTV revision, C64DTV-specific 10143@subsection LumaFix 10144 10145The PAL C64DTVs have wrong resistors in the video output circuit, 10146which causes incorrect luminances. Several hardware solutions 10147("LumaFixes") have been developed to fix this flaw. 10148 10149The fixed video output is emulated by selecting "New Luminances". 10150The unmodified C64DTV video output can be emulated with "Old Luminances". 10151 10152The default setting is "New Luminances". 10153 10154 10155@node Userport, Debug, LumaFix, C64DTV-specific 10156@subsection Userport 10157 10158The C64DTV userport emulation currently supports three devices: 10159Hummer ADC, userport joystick and PS/2 mouse. 10160 10161The joystick that controls either the Hummer ADC or userport joystick 10162can be selected using the same parameter or menu option. 10163 10164While using the Hummer ADC, joystick UP and DOWN are mapped to 10165the Hummer buttons A and B respectively. LEFT and RIGHT set the ADCs 10166output to 0 and 255. Centering the joystick results in the ADC value of 128. 10167 10168Currently the Hummer ADC and userport joystick are mutually exclusive. 10169This means that enabling one disables the other. PS/2 mouse emulation 10170can be used simultaneously with either Hummer ADC or userport joystick. 10171 10172@table @code 10173 10174@findex -hummeradc, +hummeradc 10175@item -hummeradc 10176@itemx +hummeradc 10177Enable/Disable Hummer ADC 10178(@code{HummerADC=1}, @code{HummerADC=0}). 10179 10180@findex -ps2mouse, +ps2mouse 10181@item -ps2mouse 10182@itemx +ps2mouse 10183Enable/disable PS/2 mouse on userport 10184(@code{ps2mouse=1}, @code{ps2mouse=0}). 10185 10186@end table 10187 10188 10189@node Debug, Monitor DTV features, Userport, C64DTV-specific 10190@subsection Debug 10191 10192Debugging information on Blitter, DMA and Flash can be enabled with command 10193line parameters. This can be useful for DTV software development. 10194 10195@table @code 10196 10197@findex -dtvblitterlog, +dtvblitterlog 10198@item -dtvblitterlog 10199@itemx +dtvblitterlog 10200Enable or disable DTV Blitter log 10201 10202@findex -dtvdmalog, +dtvdmalog 10203@item -dtvdmalog 10204@itemx +dtvdmalog 10205Enable or disable DTV DMA log 10206 10207@findex -dtvflashlog, +dtvflashlog 10208@item -dtvflashlog 10209@itemx +dtvflashlog 10210Enable or disable DTV Flash log 10211 10212@end table 10213 10214 10215@node Monitor DTV features, , Debug, C64DTV-specific 10216@subsection Monitor DTV features 10217 10218Currently the registers A, Y and X are registers R0, R1 and R2 regardless of 10219the mapping, which can be seen and modified via the registers ACM and XYM. 10220 10221The monitor can access all 2MiB of RAM and 2MiB of Flash, but only 64 KiB at a time. 10222The 64KiB bank can be selected with "bank ram00".."ram1f" for RAM and 10223"bank rom00".."rom1f" for Flash. 10224 10225The "load" command can load large files (>64KiB) correctly if the bank is set 10226to "ramXX", where XX is the starting bank (usually "bank00"). 10227 10228@c @node FIXME 10229@subsection DTV resources 10230 10231@table @code 10232 10233@vindex DtvRevision 10234@item DtvRevision 10235Integer specifying the emulated DTV revision. 10236(2: DTV2, 3: DTV3) 10237 10238@vindex ChargenName 10239@item ChargenName 10240String specifying the name of the character generator ROM (default @file{chargen}). 10241 10242@vindex KernalName 10243@item KernalName 10244String specifying the name of the Kernal ROM (default @file{kernal}). 10245 10246@vindex BasicName 10247@item BasicName 10248String specifying the name of the Basic ROM (default @file{basic}). 10249 10250@vindex c64dtvromfilename 10251@item c64dtvromfilename 10252String specifying the filename of the DTV Flash ROM image. 10253 10254@vindex c64dtvromrw 10255@item c64dtvromrw 10256Boolean that specifies whether the emulated Flash ROM is writeable. 10257 10258@vindex FSFlashDir 10259@item FSFlashDir 10260String specifying the working directory for the flash file system. 10261 10262@vindex FlashTrueFS 10263@item FlashTrueFS 10264Boolean, enables true hardware flash file system. 10265 10266@vindex HummerADC 10267@item HummerADC 10268Boolean to enable/disable the Hummer ADC emulation. 10269 10270@vindex ps2mouse 10271@item ps2mouse 10272Boolean to enable/disable PS/2 Mouse emulation. 10273 10274@vindex DtvBlitterLog 10275@item DtvBlitterLog 10276Boolean, enables Blitter logging. 10277@vindex DtvDMALog 10278@item DtvDMALog 10279Boolean, enables DMA logging. 10280@vindex DtvFlashLog 10281@item DtvFlashLog 10282Boolean, enables Flash ROM logging. 10283 10284@vindex MachineVideoStandard 10285@item MachineVideoStandard 10286Integer that specifies the video standard of the emulated machine. 10287(1: PAL, 2: NTSC) 10288 10289@end table 10290 10291@c @node FIXME 10292@subsection DTV command-line options 10293 10294@table @code 10295 10296@findex -model 10297@item -model <Model> 10298Set the DTV model 10299(@code{MachineVideoStandard}, @code{DtvRevision}, @code{HummerADC}). 10300(v2/v2pal/v2ntsc, v3/v3pal/v3ntsc, hummer) 10301 10302@findex -pal 10303@item -pal 10304Use PAL sync factor 10305(@code{MachineVideoStandard=1}). 10306 10307@findex -ntsc 10308@item -ntsc 10309Use NTSC sync factor 10310(@code{MachineVideoStandard=2}). 10311 10312@findex -chargen 10313@item -chargen <name> 10314Specify filename of the character generator ROM file 10315(@code{ChargenName}). 10316 10317@findex -kernal 10318@item -kernal <name> 10319Specify filename of the Kernal ROM file 10320(@code{KernalName}). 10321 10322@findex -basic 10323@item -basic <name> 10324Specify the filename of the Basic ROM file 10325(@code{BasicName}). 10326 10327@end table 10328 10329@c ----------------------------------------------------------------------------- 10330 10331@node SCPU64-specific, VIC20-specific, C64DTV-specific, Machine-specific features 10332 10333@section SCPU64-specific commands and settings 10334 10335@c @node FIXME 10336@subsection SCPU64 resources 10337 10338@table @code 10339 10340@vindex ChargenName 10341@item ChargenName 10342String specifying the name of the character generator ROM (default @file{chargen}). 10343 10344@vindex SCPU64Name 10345@item SCPU64Name 10346String specifying the name of the SCPU64 ROM (default @file{scpu64}). 10347 10348@vindex MachineVideoStandard 10349@item MachineVideoStandard 10350Integer that specifies the video standard of the emulated machine 10351(4: PAL-N, 3: Old NTSC, 1: PAL, 2: NTSC). 10352 10353@vindex IECReset 10354@item IECReset 10355Integer specifying if the IEC bus resets when the CPU resets. 10356(0: No, 1: Yes) 10357 10358@vindex BurstMod 10359@item BurstMod 10360Integer specifying the kind of Burst-Mode modification. 10361(0: None, 1: CIA-1, 2: CIA-2) 10362 10363@vindex SIMMSize 10364@item SIMMSize 10365Integer specifying the size of the SIMM RAM. 10366(0, 1, 4, 8, 16) 10367 10368@vindex JiffySwitch 10369@item JiffySwitch 10370Boolean to enable/disable the jiffy switch. 10371 10372@vindex SpeedSwitch 10373@item SpeedSwitch 10374Boolean to enable/disable the speed switch. 10375 10376@vindex GlueLogic 10377@item GlueLogic 10378Integer specifying the type of emulated glue-logic. 10379(0: discrete, 1: custom IC) 10380 10381@end table 10382 10383@c @node FIXME 10384@subsection SCPU64 command-line options 10385 10386@table @code 10387 10388@findex -chargen 10389@item -chargen <name> 10390Specify filename of the character generator ROM file 10391(@code{ChargenName}). 10392 10393@findex -scpu64 10394@item -scpu64 <Name> 10395Specify filename of the SCPU64 ROM file 10396(@code{SCPU64Name}). 10397 10398@findex -model 10399@item -model <Model> 10400Set the C64 model 10401(@code{MachineVideoStandard}, @code{CIA1Model}, @code{CIA2Model}, 10402@code{VICIINewLuminances}, @code{IECReset}, @code{ChargenName}, 10403@code{SidEngine}, @code{SidModel}). 10404(c64/c64c/c64old, ntsc/newntsc/oldntsc, drean, jap, c64gs) 10405 10406@findex -pal 10407@item -pal 10408Use PAL sync factor 10409(@code{MachineVideoStandard=1}). 10410 10411@findex -ntsc 10412@item -ntsc 10413Use NTSC sync factor 10414(@code{MachineVideoStandard=2}). 10415 10416@findex -ntscold 10417@item -ntscold 10418Use old NTSC sync factor 10419(@code{MachineVideoStandard=3}). 10420 10421@findex -paln 10422@item -paln 10423Use PAL-N sync factor 10424(@code{MachineVideoStandard=4}). 10425 10426@findex -iecreset 10427@item -iecreset <value> 10428Set IEC reset bahaviour 10429(@code{IECReset}). 10430(0: Do not reset with CPU reset, 1: Reset with CPU reset) 10431 10432@findex -burstmod 10433@item -burstmod <value> 10434Set the kind of burst modification. This emulates the fast serial bus connection 10435as described at @uref{https://a1bert.kapsi.fi/Dev/burst/}, with the wire to 10436the tape port cut 10437(@code{BurstMod}). 10438(0: None, 1: CIA-1, 2: CIA-2) 10439 10440@findex -simmsize 10441@item -simmsize <number> 10442Set the size of the SIMM RAM 10443(@code{SIMMSize}). 10444(0, 1, 4, 8, 16) 10445 10446@findex -jiffyswitch, +jiffyswitch 10447@item -jiffyswitch 10448@itemx +jiffyswitch 10449Enable/disable the jiffy switch 10450(@code{JiffySwitch=1}, @code{JiffySwitch=0}). 10451 10452@findex -speedswitch, +speedswitch 10453@item -speedswitch 10454@itemx +speedswitch 10455Enable/disable the speed switch 10456(@code{SpeedSwitch=1}, @code{SpeedSwitch=0}). 10457 10458@findex -gluelogictype 10459@item -gluelogictype <type> 10460Set glue logic type 10461(@code{GlueLogic}). 10462(0: discrete, 1: 252535-01) 10463 10464@end table 10465 10466@c ----------------------------------------------------------------------------- 10467 10468@node VIC20-specific, PLUS4-specific, SCPU64-specific, Machine-specific features 10469@section VIC20-specific commands and settings 10470 10471This section lists the settings and commands that are VIC20-specific and 10472thus are not present in the other emulators. 10473 10474@menu 10475* VIC20 cartridges:: 10476* VIC20 memory expansions:: 10477* VIC20 system ROM settings:: 10478@end menu 10479 10480 10481@node VIC20 cartridges, VIC20 memory expansions, VIC20-specific, VIC20-specific 10482@subsection Using cartridge images 10483 10484As with the C64 (@pxref{C64 cartridges}), it is possible to attach 10485several types of cartridge images: 10486 10487@itemize @bullet 10488@item 104894 or 8 KiB cartridges located at $2000; 10490@item 104914 or 8 KiB cartridges located at $4000; 10492@item 104934 or 8 KiB cartridges located at $6000; 10494@item 104954 or 8 KiB cartridges located at $A000; 10496@item 104974 KiB cartridges located at $B000. 10498@end itemize 10499 10500This can all be done via the ``Attach cartridge image@dots{}'' command in 10501the menu. It is also possible to let xvic ``guess'' the 10502type of cartridge using ``Smart-attach cartridge image@dots{}''. 10503 10504Notice that several cartridges are actually made up of two pieces (and 10505two files), that need to be loaded separately at different addresses. 10506In that case, you have to know the addresses (which are usually 10507specified in the file name) and use the ``attach'' command twice. 10508 10509A special kind of cartridge file is where the two files mentioned 10510above are concatenated (with removing the two byte load address of 10511the second image) into one 16KiB image. Vice can attach such concatenated files 10512at the start address $2000, $4000, and $6000. The second half of such an image is 10513moved to the memory block following the first block. It is also possible to 10514concatenate four 8KiB files, the resulting file will load into all 4 cartridge blocks. 10515 10516If you encounter 16KiB images that have the second half at eg $A000 you can split 10517the image into two halfs (i.e. one 8194 byte and one 8192 byte, because the first 10518has the load address) and attach both files separately. Alternatively you can 10519create a 32KiB file with padding blocks in between. 10520 10521One cartridge that is currently only partially supported here is 10522the VIC1112 IEEE488 interface. You have to load the ROM as a cartridge, 10523but you also have to enable the IEEE488 hardware by menu. 10524 10525@c @node FIXME 10526@subsection VIC20 cartridge settings 10527 10528@c @node FIXME 10529@subsubsection VIC20 cartridge resources 10530 10531@table @code 10532 10533@vindex CartridgeReset 10534@item CartridgeReset 10535Boolean specifying whether the machine should be reset when a cartridge is 10536changed. 10537 10538@vindex CartridgeType 10539@item CartridgeType 10540Integer specifying the type of cartridge emulated. 10541 10542The following cartridge types are valid: 10543 10544@itemize @bullet 10545@item 10546 - 1: None 10547@item 10548 1: Generic 10549@item 10550 2: Megacart 10551@item 10552 3: Final Expansion 10553@item 10554 4: Vic Flash Plugin 10555@item 10556 5: IEEE-4888 10557@item 10558 6: SIDCart 10559@item 10560 7: Ultimem 10561@item 10562 8: IO ram cart (IO2) 10563@item 10564 9: IO ram cart (IO3) 10565@item 10566 10: BehrBonz 10567@item 105680x8000: Auto Detect 10569@item 105700x8002: 4KiB at $2000-$2FFF 10571@item 105720x8003: 8KiB at $2000-$3FFF 10573@item 105740x8004: 4KiB at $6000-$6FFF 10575@item 105760x8005: 8KiB at $6000-$7FFF 10577@item 105780x8006: 4KiB at $A000-$AFFF 10579@item 105800x8007: 8KiB at $A000-$BFFF 10581@item 105820x8008: 4KiB at $B000-$BFFF 10583@item 105840x8009: 8KiB at $4000-$5FFF 10585@item 105860x800A: 4KiB at $4000-$4FFF 10587@item 105880x8013: 16KiB at $2000-$5FFF 10589@item 105900x8015: 16KiB at $6000-$9FFF 10591@item 105920x8019: 16KiB at $4000-$7FFF 10593@end itemize 10594 10595@vindex CartridgeFile 10596@item CartridgeFile 10597String specifying the filename of the image for the current cartridge. 10598 10599@vindex IOCollisionHandling 10600@item IOCollisionHandling 10601Integer specifying the way the I/O collisions should be handled. 10602(0: error message and detach all involved carts, 106031: error message and detach last attached involved carts, 106042: warning in log and 'AND' the valid return values) 10605 10606@vindex GenericCartridgeFile2000 10607@vindex GenericCartridgeFile4000 10608@vindex GenericCartridgeFile6000 10609@vindex GenericCartridgeFileA000 10610@vindex GenericCartridgeFileB000 10611@item GenericCartridgeFile2000 10612@itemx GenericCartridgeFile4000 10613@itemx GenericCartridgeFile6000 10614@itemx GenericCartridgeFileA000 10615@itemx GenericCartridgeFileB000 10616Strings specifying the name of the respective cartridge ROM images. 10617 10618@vindex FinalExpansionWriteBack 10619@item FinalExpansionWriteBack 10620Boolean, if true write back the Flash ROM image file automatically, incase the 10621contents changed, when detaching or quitting the emulator. 10622 10623@vindex VicFlashPluginWriteBack 10624@item VicFlashPluginWriteBack 10625Boolean, if true write back the Flash ROM image file automatically, incase the 10626contents changed, when detaching or quitting the emulator. 10627 10628@vindex MegaCartNvRAMfilename 10629@item MegaCartNvRAMfilename 10630String specifying the filename of the MegaCart NvRAM image. 10631 10632@vindex MegaCartNvRAMWriteBack 10633@item MegaCartNvRAMWriteBack 10634Boolean, if true write back the NvRAM image file automatically, incase the RAM 10635contents changed, when detaching or quitting the emulator. 10636 10637@vindex UltiMemWriteBack 10638@item UltiMemWriteBack 10639Boolean, if true write back the Flash ROM image file automatically, incase the 10640contents changed, when detaching or quitting the emulator. 10641 10642@vindex IO2RAM 10643@item IO2RAM 10644Boolean specifying whether the I/O-2 ($9800-$9BFF) RAM cartridge should be emulated or not. 10645 10646@vindex IO3RAM 10647@item IO3RAM 10648Boolean specifying whether the I/O-3 ($9C00-$9FFF) RAM cartridge should be emulated or not. 10649 10650@vindex VFLImod 10651@item VFLImod 10652Boolean specifying whether the VFLI modification should be enabled. 10653 10654@vindex SFXSoundExpander 10655@item SFXSoundExpander 10656Boolean specifying whether the SFX Sound Expander should be emulated or not. 10657 10658@vindex SFXSoundExpanderChip 10659@item SFXSoundExpanderChip 10660Integer specifying which YM chip is emulated. 10661(3526, 3812) 10662 10663@vindex SFXSoundExpanderIOSwap 10664@item SFXSoundExpanderIOSwap 10665Boolean, swap io mapping (map cart I/O to VIC20 I/O-2) or don't swap io mapping (map cart I/O to VIC20 I/O-3). 10666 10667@vindex SFXSoundSampler 10668@item SFXSoundSampler 10669Boolean specifying whether the SFX Sound Sampler should be emulated or not. 10670 10671@vindex SFXSoundSamplerIOSwap 10672@item SFXSoundSamplerIOSwap 10673Boolean, swap io mapping (map cart I/O to VIC20 I/O-2) or don't swap io mapping (map cart I/O to VIC20 I/O-3). 10674 10675@vindex GEORAMfilename 10676@item GEORAMfilename 10677String specifying the filename of the GEORAM image. 10678 10679@vindex GEORAM 10680@item GEORAM 10681Boolean specifying whether the GEO-RAM cartridge (using the MasC=uerade cartridge adapter) should be emulated or not. 10682 10683@vindex GEORAMsize 10684@item GEORAMsize 10685Integer specifying the size of the emulated GEO-RAM in KiB. 10686(64, 128, 256, 512, 1024, 2048, 4096). 10687 10688@vindex GEORAMImageWrite 10689@item GEORAMImageWrite 10690Boolean, if true write back the GEO-RAM image file automatically, incase the RAM 10691contents changed, when detaching or quitting the emulator. 10692 10693@vindex GEORAMIOSwap 10694@item GEORAMIOSwap 10695Boolean specifying whether the io mapping should be swapped 10696(map cart I/O-1 to VIC20 I/O-3 and cart I/O-2 to VIC20 I/O-2) 10697or not 10698(map cart I/O-2 to VIC20 I/O-2 and cart I/O-2 to VIC20 I/O-3). 10699 10700@vindex SidCart 10701@item SidCart 10702Boolean specifying whether SID-Cart emulation is enabled or not. 10703 10704@vindex SidAddress 10705@item SidAddress 10706Integer that specifies the base address of the emulated SID chip. 10707(0x9800, 0x9C00) 10708 10709@vindex SidClock 10710@item SidClock 10711Integer specifying the clock rate used for the emulated SID chip 10712(0: C64, 1: VIC20) 10713 10714@vindex DIGIMAX 10715@item DIGIMAX 10716Boolean specifying whether the DigiMAX cartridge (using the MasC=uerade cartridge adapter) should be emulated or not. 10717 10718@vindex DIGIMAXbase 10719@item DIGIMAXbase 10720Integer specifying the DigiMAX base address. 10721(0x9800, 0x9820, 0x9840, 0x9860, 0x9880, 0x98A0, 0x98C0, 0x98E0, 107220x9C00, 0x9C20, 0x9C40, 0x9C60, 0x9C80, 0x9CA0, 0x9CC0, 0x9CE0) 10723 10724@vindex DS12C887RTC 10725@item DS12C887RTC 10726Boolean specifying whether the DS12C887 RTC cartridge (using the MasC=uerade cartridge adapter) should be emulated or not. 10727 10728@vindex DS12C887RTCbase 10729@item DS12C887RTCbase 10730Integer specifying the DS12C887 RTC base address. 10731(0x9800, 0x9C00) 10732 10733@vindex DS12C887RTCRunMode 10734@item DS12C887RTCRunMode 10735Boolean specifying whether the DS12C887 RTC cartridge starts out running or halted. 10736(0: halted, 1: running) 10737 10738@vindex DS12C887RTCSave 10739@item DS12C887RTCSave 10740Boolean specifying whether the DS12C887 RTC data should be saved when changed or not. 10741 10742@vindex IEEE488 10743@item IEEE488 10744Boolean specifying whether the IEEE488 interface should be emulated or not. 10745 10746@vindex MachineVideoStandard 10747@item MachineVideoStandard 10748Integer that specifies the video standard of the emulated machine 10749(1: PAL, 2: NTSC). 10750 10751@end table 10752 10753@c @node FIXME 10754@subsubsection VIC20 cartridge command-line options 10755 10756@table @code 10757 10758@findex -iocollision 10759@item -iocollision <method> 10760Select the way the I/O collisions should be handled 10761(@code{IOCollisionHandling}). 10762(0: error message and detach all involved carts, 107631: error message and detach last attached involved carts, 107642: warning in log and 'AND' the valid return values 10765 10766@findex -cartreset, +cartreset 10767@item -cartreset 10768@itemx +cartreset 10769Do/don't reset machine if a cartridge is attached or detached 10770(@code{CartridgeReset=1}, @code{CartridgeReset}). 10771 10772@findex -cart2 10773@item -cart2 <name> 10774Specify 4/8/16KiB extension ROM name at $2000 10775@findex -cart4 10776@item -cart4 <name> 10777Specify 4/8/16KiB extension ROM name at $4000 10778@findex -cart6 10779@item -cart6 <name> 10780Specify 4/8/16KiB extension ROM name at $6000 10781@findex -cartA 10782@item -cartA <name> 10783Specify 4/8KiB extension ROM name at $A000 10784@findex -cartB 10785@item -cartB <name> 10786Specify 4KiB extension ROM name at $B000 10787@findex -cartgeneric 10788@item -cartgeneric <name> 10789Specify generic extension ROM name 10790 10791@findex -cartbb 10792@item -cartbb <name> 10793Specify Behr-Bonz extension ROM name 10794 10795@findex -cartmega 10796@item -cartmega <name> 10797Specify Mega-Cart extension ROM name 10798 10799@findex -mcnvramfile 10800@item -mcnvramfile <name> 10801Set Mega-Cart NvRAM filename 10802(@code{MegaCartNvRAMfilename}). 10803 10804@findex -mcnvramwriteback, +mcnvramwriteback 10805@item -mcnvramwriteback 10806@itemx +mcnvramwriteback 10807Enable/Disable Mega-Cart NvRAM writeback 10808(@code{MegaCartNvRAMWriteBack=1}, @code{MegaCartNvRAMWriteBack=0}). 10809 10810@findex -cartfe 10811@item -cartfe <name> 10812Specify Final Expansion extension ROM name 10813 10814@findex -fewriteback, +fewriteback 10815@item -fewriteback 10816@itemx +fewriteback 10817Enable/disable Final Expansion write back to ROM file 10818(@code{FinalExpansionWriteBack=1}, @code{FinalExpansionWriteBack=0}). 10819 10820@findex -cartfp 10821@item -cartfp <name> 10822Specify Vic Flash Plugin extension ROM name 10823 10824@findex -fpwriteback, +fpwriteback 10825@item -fpwriteback 10826@itemx +fpwriteback 10827Enable/Disable Vic Flash Plugin write back to ROM file 10828(@code{VicFlashPluginWriteBack=1}, @code{VicFlashPluginWriteBack=0}). 10829 10830@findex -ultimem 10831@item -ultimem <name> 10832Specify Ultimem extension ROM name 10833 10834@findex -umwriteback, +umwriteback 10835@item -umwriteback 10836@itemx +umwriteback 10837Enable/disable UltiMem write back to ROM file 10838(@code{UltiMemWriteBack=1}, @code{UltiMemWriteBack=0}). 10839 10840@findex -io2ram, +io2ram 10841@item -io2ram 10842@itemx +io2ram 10843Enable/disable the I/O-2 ($9800-$9BFF) RAM cartridge 10844(@code{IO2RAM=1}, @code{IO2RAM=0}). 10845 10846@findex -io3ram, +io3ram 10847@item -io3ram 10848@itemx +io3ram 10849Enable/disable the I/O-3 ($9C00-$9FFF) RAM cartridge 10850(@code{IO3RAM=1}, @code{IO3RAM=0}). 10851 10852@findex -ieee488, +ieee488 10853@item -ieee488 10854@itemx +ieee488 10855Enable/disable VIC-1112 IEEE488 interface 10856(@code{IEEE488=1}, @code{IEEE488=0}). 10857 10858@findex -vflimod, +vflimod 10859@item -vflimod 10860@itemx +vflimod 10861Enable/disable VIC-20 VFLI modification 10862(@code{VFLImod=1}, @code{VFLImod=0}) 10863 10864@findex -sidcart, +sidcart 10865@item -sidcart 10866@item +sidcart 10867Enable/disable SID Cartridge 10868(@code{SidCart=1}, @code{SidCart=0}). 10869 10870@findex -sidcartaddress 10871@item -sidcartaddress <address> 10872Specify address of the SID Cartridge 10873(@code{SidAddress}). 10874(0x9800, 0x9C00) 10875 10876@findex -sidcartclock 10877@item -sidcartclock <clock> 10878Specify clock of the SID Cartridge 10879(@code{SidClock}). 10880(0: C64, 1: VIC20) 10881 10882@findex -cs8900ioif 10883@item -cs8900ioif <name> 10884Set the system ethernet interface for Ethernet Cartridge emulation 10885 10886@findex -ethernetcart, +ethernetcart 10887@item -ethernetcart 10888@itemx +ethernetcart 10889Disable/Enable the Ethernet Cartridge (TFE/RR-Net/64NIC/FB-NET) 10890 10891@findex -ethernetcartmode 10892@item -ethernetcartmode <Mode> 10893Mode of Ethernet Cartridge (0: TFE, 1: RR-Net) 10894 10895@findex -ethernetcartbase 10896@item -ethernetcartbase <Base address> 10897Base address of the Ethernet Cartridge. (0x9800, 0x9810, 0x9820, 0x9830, 0x9840, 108980x9850, 0x9860, 0x9870, 0x9880, 0x9890, 0x98A0, 0x98B0, 0x98C0, 0x98D0, 0x98E0, 108990x98F0, 0x9C00, 0x9C10, 0x9C20, 0x9C30, 0x9C40, 0x9C50, 0x9C60, 0x9C70, 0x9C80, 109000x9C90, 0x9CA0, 0x9CB0, 0x9CC0, 0x9CD0, 0x9CE0, 0x9CF0) 10901 10902@findex -tfe 10903@item -tfe 10904Enable the Ethernet Cartridge in TFE ("The Final Ethernet") compatible mode and set default I/O address 10905 10906@findex -rrnet 10907@item -rrnet 10908Enable the Ethernet Cartridge in RR-Net compatible mode and set default I/O address 10909 10910@findex -digimax, +digimax 10911@item -digimax 10912@itemx +digimax 10913Enable/disable the DigiMAX cartridge (using the MasC=uerade cartridge adapter) 10914(@code{DIGIMAX=1}, @code{DIGIMAX=0}). 10915 10916@findex -digimaxbase 10917@item -digimaxbase <base address> 10918Base address of the DigiMAX cartridge 10919(@code{DIGIMAXbase}). 10920(0x9800, 0x9820, 0x9840, 0x9860, 0x9880, 0x98A0, 0x98C0, 0x98E0, 109210x9C00, 0x9C20, 0x9C40, 0x9C60, 0x9C80, 0x9CA0, 0x9CC0, 0x9CE0) 10922 10923@findex -ds12c887rtc, +ds12c887rtc 10924@item -ds12c887rtc 10925@itemx +ds12c887rtc 10926Enable/disable the DS12C887 RTC cartridge (using the MasC=uerade cartridge adapter) 10927(@code{DS12C887RTC=1}, @code{DS12C887RTC=0}). 10928 10929@findex -ds12c887rtcbase 10930@item -ds12c887rtcbase <base address> 10931Base address of the DS12C887 RTC cartridge 10932(@code{DS12C887RTCbase}). 10933(0x9800, 0x9C00) 10934 10935@findex -ds12c887rtchalted, -ds12c887rtcrunning 10936@item -ds12c887rtchalted 10937Set the DS12C887 RTC oscillator to 'halted' 10938(@code{DS12C887RTCRunMode=0}). 10939@item -ds12c887rtcrunning 10940Set the DS12C887 RTC oscillator to 'running' 10941(@code{DS12C887RTCRunMode=1}). 10942 10943@findex -ds12c887rtcsave, +ds12c887rtcsave 10944@item -ds12c887rtcsave 10945@itemx +ds12c887rtcsave 10946Enable/disable saving of the DS12C887 RTC data when changed 10947(@code{DS12C887RTCSave=1}, @code{DS12C887RTCSave=0}). 10948 10949@findex -sfxse, +sfxse 10950@item -sfxse 10951@itemx +sfxse 10952Enable/disable the SFX soundexpander cartridge (using the MasC=uerade cartridge adapter) 10953(@code{SFXSoundExpander=1}, @code{SFXSoundExpander=0}). 10954 10955@findex -sfxsetype 10956@item -sfxsetype <type> 10957Set YM chip type 10958(@code{SFXSoundExpanderChip}). 10959(3526, 3812) 10960 10961@findex -sfxseioswap, +sfxseioswap 10962@item -sfxseioswap 10963Swap io mapping (map cart I/O to VIC20 I/O-2) 10964(@code{SFXSoundExpanderIOSwap=1}). 10965@item +sfxseioswap 10966Swap io mapping (map cart I/O to VIC20 I/O-3) 10967(@code{SFXSoundExpanderIOSwap=0}). 10968 10969@findex -sfxssioswap, +sfxssioswap 10970@item -sfxssioswap 10971Swap io mapping (map cart I/O to VIC20 I/O-2) 10972(@code{SFXSoundSamplerIOSwap=1}). 10973@item +sfxssioswap 10974Don't swap io mapping (map cart I/O to VIC20 I/O-3) 10975(@code{SFXSoundSamplerIOSwap=0}). 10976 10977@findex -sfxss, +sfxss 10978@item -sfxss 10979@itemx +sfxss 10980Enable/disable the SFX Sound Sampler cartridge 10981(@code{SFXSoundSampler=1}, @code{SFXSoundSampler=0}). 10982 10983@findex -georamioswap, +georamioswap 10984@item -georamioswap 10985Swap the io mapping (map cart I/O-1 to VIC20 I/O-3 and cart I/O-2 to VIC20 I/O-2) 10986(@code{GEORAMIOSwap=1}). 10987@item +georamioswap 10988Do not swap the io mapping (map cart I/O-2 to VIC20 I/O-2 and cart I/O-2 to VIC20 I/O-3) 10989(@code{GEORAMIOSwap=0}). 10990 10991@findex -georam, +georam 10992@item -georam 10993@itemx +georam 10994Enable/disable the GEORAM expansion unit (using the MasC=uerade cartridge adapter) 10995(@code{GEORAM=1}, @code{GEORAM=0}). 10996 10997@findex -georamimage 10998@item -georamimage <name> 10999Specify name of GEORAM image 11000(@code{GEORAMfilename}). 11001 11002@findex -georamimagerw, +georamimagerw 11003@item -georamimagerw 11004@itemx +georamimagerw 11005Allow/disallow writing to GEORAM image 11006(@code{GEORAMImageWrite=1}, @code{GEORAMImageWrite=0}). 11007 11008@findex -georamsize 11009@item -georamsize <size in KiB> 11010Size of the GEORAM expansion unit 11011(@code{GEORAMsize}). 11012(64, 128, 256, 512, 1024, 2048, 4096) 11013 11014@findex -model 11015@item -model <model> 11016Specify the VIC20 model you want to emulate 11017(@code{MachineVideoStandard}, @code{RamBlock0}, @code{RamBlock1}, @code{RamBlock2}, @code{RamBlock3} and @code{RamBlock5}). 11018(vic20/vic20pal/vic20ntsc, vic21) 11019 11020@findex -pal 11021@item -pal 11022Use PAL sync factor 11023(@code{MachineVideoStandard=1}). 11024 11025@findex -ntsc 11026@item -ntsc 11027Use NTSC sync factor 11028(@code{MachineVideoStandard=2}). 11029 11030@end table 11031 11032@c @node FIXME 11033@subsection VIC settings 11034 11035@c @node FIXME 11036@subsubsection VIC resources 11037 11038@table @code 11039 11040@vindex VICVideoCache 11041@item VICVideoCache 11042Boolean specifying whether the video cache is turned on. 11043 11044@vindex VICDoubleSize 11045@item VICDoubleSize 11046Boolean specifying whether double-size mode is turned on. 11047 11048@vindex VICDoubleScan 11049@item VICDoubleScan 11050Boolean specifying whether double-scan mode is turned on. 11051 11052@vindex VICPaletteFile 11053@item VICPaletteFile 11054String specifying the name of the palette file being used. The 11055@file{.vpl} extension is optional. 11056 11057@vindex VICExternalPalette 11058@item VICExternalPalette 11059Boolean specifying whether to use external palette file or not. 11060 11061@vindex VICColorSaturation 11062@item VICColorSaturation 11063Integer specifying saturation of internal calculated palette. 11064(0..2000) 11065 11066@vindex VICColorContrast 11067@item VICColorContrast 11068Integer specifying contrast of internal calculated palette, 11069(0..2000) 11070 11071@vindex VICColorBrightness 11072@item VICColorBrightness 11073Integer specifying brightness of internal calculated palette. 11074(0..2000) 11075 11076@vindex VICColorGamma 11077@item VICColorGamma 11078Integer specifying gamma of internal calculated palette. 11079(0..4000) 11080 11081@vindex VICColorTint 11082@item VICColorTint 11083Integer specifying tint of internal calculated palette. 11084(0..2000) 11085 11086@vindex VICPALScanLineShade 11087@item VICPALScanLineShade 11088Integer specifying amount of scan line shading for the CRT emulation. 11089(0..1000) 11090 11091@vindex VICPALBlur 11092@item VICPALBlur 11093Integer specifying amount of horizontal blur for the CRT emulation. 11094(0..1000) 11095 11096@vindex VICPALOddLinePhase 11097@item VICPALOddLinePhase 11098Integer specifying phase for color carrier in odd lines. 11099(0..2000) 11100 11101@vindex VICPALOddLineOffset 11102@item VICPALOddLineOffset 11103Integer specifying phase offset for color carrier in odd lines. 11104(0..2000) 11105 11106@vindex VICAudioLeak 11107@item VICAudioLeak 11108Boolean specifying whether to enable/disable video to audio leak emulation. 11109 11110@vindex VICFilter 11111@item VICFilter 11112Integer specifying the rendering filter. 11113(0: None, 1: CRT emulation, 2: Scale2x) 11114 11115@vindex VICBorderMode 11116@item VICBorderMode 11117Integer specifying border display mode 11118(0: normal, 1: full, 2: debug, 3: none) 11119 11120@end table 11121 11122@c @node FIXME 11123@subsubsection VIC command-line options 11124 11125@table @code 11126 11127@findex -VICvcache, +VICvcache 11128@item -VICvcache 11129@itemx +VICvcache 11130Enable/disable the video cache 11131(@code{VICVideoCache=1}, @code{VICVideoCache=0}). 11132 11133@findex -VICdsize, +VICdsize 11134@item -VICdsize 11135@itemx +VICdsize 11136Enable/disable the double size mode 11137(@code{VICDoubleSize=1}, @code{VICDoubleSize=0}). 11138 11139@findex -VICdscan, +VICdscan 11140@item -VICdscan 11141@itemx +VICdscan 11142Enable/disable the double scan mode 11143(@code{VICDoubleScan=1}, @code{VICDoubleScan=0}). 11144 11145@findex -VICfilter 11146@item -VICfilter <Mode> 11147Select rendering filter 11148(@code{VICFilter}). 11149(0: None, 1: CRT emulation, 2: Scale2x) 11150 11151@findex -VICpalette 11152@item -VICpalette NAME 11153Specify the name of the palette file 11154(@code{VICPaletteFile}). 11155 11156@findex -VICintpal 11157@item -VICintpal 11158Use an internal calculated palette 11159(@code{VICExternalPalette=0}). 11160 11161@findex -VICextpal 11162@item -VICextpal 11163Use an external palette (file) 11164(@code{VICExternalPalette=1}). 11165 11166@findex -VICborders 11167@item -VICborders <mode> 11168Set VIC border display mode 11169(@code{VICBorderMode}). 11170(0: normal, 1: full, 2: debug, 3: none) 11171 11172@findex -VICsaturation 11173@item -VICsaturation <0-2000> 11174Set saturation of internal calculated palette 11175(@code{VICColorSaturation}). 11176 11177@findex -VICcontrast 11178@item -VICcontrast <0-2000> 11179Set contrast of internal calculated palette 11180(@code{VICColorContrast}). 11181 11182@findex -VICbrightness 11183@item -VICbrightness <0-2000> 11184Set brightness of internal calculated palette 11185(@code{VICColorBrightness}). 11186 11187@findex -VICgamma 11188@item -VICgamma <0-4000> 11189Set gamma of internal calculated palette 11190(@code{VICColorGamma}). 11191 11192@findex -VICtint 11193@item -VICtint <0-2000> 11194Set tint of internal calculated palette 11195(@code{VICColorTint}). 11196 11197@findex -VICoddlinesphase 11198@item -VICoddlinesphase <0-2000> 11199Set phase for color carrier in odd lines 11200(@code{VICPALOddLinePhase}). 11201 11202@findex -VICoddlinesoffset 11203@item -VICoddlinesoffset <0-2000> 11204Set phase offset for color carrier in odd lines. 11205(@code{VICPALOddLineOffset}). 11206 11207@findex -VICcrtblur 11208@item -VICcrtblur <0-1000> 11209Amount of horizontal blur for the CRT emulation 11210(@code{VICPALBlur}). 11211 11212@findex -VICcrtscanlineshade 11213@item -VICcrtscanlineshade <0-1000> 11214Amount of scan line shading for the CRT emulation 11215(@code{VICPALScanLineShade}). 11216 11217@findex -VICaudioleak, +VICaudioleak 11218@item -VICaudioleak 11219@item +VICaudioleak 11220Enable/disable video to audio leak emulation 11221(@code{VICAudioLeak=1}, @code{VICAudioLeak=0}). 11222 11223@end table 11224 11225 11226@node VIC20 memory expansions, VIC20 system ROM settings, VIC20 cartridges, VIC20-specific 11227@subsection Changing memory configuration 11228 11229It is possible to change the VIC20 memory configuration in two ways: by 11230enabling and/or disabling certain individual memory blocks, or by 11231choosing one among a few typical memory configurations. The former can 11232be done by modifying resource values directly or from the right-button 11233menu; the latter can only be done from the menu. 11234 11235There are 5 RAM expansion blocks in the VIC20, numbered 0, 1, 2, 3 and 112365: 11237 11238@itemize @bullet 11239@item 11240block 0 (3 KiB at $0400-$0FFF); 11241@item 11242block 1 (8 KiB at $2000-$3FFF); 11243@item 11244block 2 (8 KiB at $4000-$5FFF); 11245@item 11246block 3 (8 KiB at $6000-$7FFF); 11247@item 11248block 5 (8 KiB at $A000-$BFFF). 11249@end itemize 11250 11251These blocks are called @dfn{expansion blocks} because they are not 11252present a stock (``unexpanded'') machine. Each of them is associated to 11253a boolean @code{RamBlockX} resource (where @code{X} is the block number) 11254that specifies whether the block is enabled or not. 11255 11256There are also some common memory configurations you can select: 11257 11258@itemize @bullet 11259@item 11260no RAM expansion blocks at all; 11261@item 11262all RAM expansion blocks enabled; 11263@item 112643KiB expansion (only block 0 is enabled); 11265@item 112668KiB expansion (only block 1 is enabled); 11267@item 1126816KiB expansion (only blocks 1 and 2 are enabled); 11269@item 1127024KiB expansion (only blocks 1, 2 and 3 are enabled). 11271@end itemize 11272 11273@menu 11274* VIC20 memconf resources:: 11275* VIC20 memconf options:: 11276@end menu 11277 11278@node VIC20 memconf resources, VIC20 memconf options, VIC20 memory expansions, VIC20 memory expansions 11279@subsubsection VIC20 memory configuration resources 11280 11281@table @code 11282 11283@vindex RAMBlock0 11284@vindex RAMBlock1 11285@vindex RAMBlock2 11286@vindex RAMBlock3 11287@vindex RAMBlock5 11288@item RAMBlock0 11289@itemx RAMBlock1 11290@itemx RAMBlock2 11291@itemx RAMBlock3 11292@itemx RAMBlock5 11293Booleans specifying whether RAM blocks 0, 1, 2, 3 and 5 must be enabled. 11294 11295@end table 11296 11297@node VIC20 memconf options, , VIC20 memconf resources, VIC20 memory expansions 11298@subsubsection VIC20 memory configuration command-line options 11299 11300@table @code 11301 11302@findex -memory 11303@item -memory <config> 11304Specify memory configuration. It must be a comma-separated list of 11305options, each of which can be one the following: 11306 11307@itemize @bullet 11308@item 11309@code{none} (no extension); 11310@item 11311@code{all} (all blocks); 11312@item 11313@code{3k} (3KiB space in block 0); 11314@item 11315@code{8k} (first 8KiB extension block); 11316@item 11317@code{16k} (first and second 8KiB extension blocks); 11318@item 11319@code{24k} (first, second and 3rd extension blocks); 11320@item 11321@code{0}, @code{1}, @code{2}, @code{3}, @code{5} (memory in respective 11322blocks); 11323@item 11324@code{04}, @code{20}, @code{40}, @code{60}, @code{A0} (memory at respective address. 11325@end itemize 11326 11327For example, 11328 11329@example 11330xvic -memory none 11331@end example 11332 11333gives an unexpanded VIC20. While 11334 11335@example 11336xvic -memory 60,a0 11337@end example 11338 11339or 11340 11341@example 11342xvic -memory 3,5 11343@end example 11344 11345enables memory in blocks 3 and 5, which is the usual configuration for 1134616KiB ROM modules. 11347 11348@end table 11349 11350 11351@node VIC20 system ROM settings, , VIC20 memory expansions, VIC20-specific 11352@subsection VIC20 system ROM settings 11353 11354These settings can be used to control what system ROMs are loaded in the 11355VIC20 emulator at startup. 11356 11357@menu 11358* VIC20 system ROM resources:: 11359* VIC20 system ROM options:: 11360@end menu 11361 11362@node VIC20 system ROM resources, VIC20 system ROM options, VIC20 system ROM settings, VIC20 system ROM settings 11363@subsubsection VIC20 system ROM resources 11364 11365@table @code 11366 11367@vindex KernalName 11368@item KernalName 11369String specifying the name of the Kernal ROM (default @file{kernal}). 11370 11371@vindex BasicName 11372@item BasicName 11373String specifying the name of the Basic ROM (default @file{basic}). 11374 11375@vindex ChargenName 11376@item ChargenName 11377String specifying the name of the character generator ROM (default @file{chargen}). 11378 11379@end table 11380 11381@node VIC20 system ROM options, , VIC20 system ROM resources, VIC20 system ROM settings 11382@subsubsection VIC20 system ROM command-line options 11383 11384@table @code 11385 11386@findex -kernal 11387@item -kernal <name> 11388Specify the filename of the Kernal ROM file 11389(@code{KernalName}). 11390 11391@findex -basic 11392@item -basic <name> 11393Specify the filename of the Basic ROM file 11394(@code{BasicName}). 11395 11396@findex -chargen 11397@item -chargen <name> 11398Specify the filename of the character generator ROM file 11399(@code{ChargenName}). 11400 11401@findex -cart2 11402@findex -cart4 11403@findex -cart6 11404@findex -cartA 11405@findex -cartB 11406@item -cart2 NAME 11407@itemx -cart4 NAME 11408@itemx -cart6 NAME 11409@itemx -cartA NAME 11410@itemx -cartB NAME 11411Specify @file{NAME} as the cartridge image to attach. 11412(@code{CartridgeFile2000}, @dots{}, @code{CartridgeFileB000}). 11413 11414@end table 11415 11416@c @node FIXME 11417@subsection VIC20 settings 11418 11419@c @node FIXME 11420@subsubsection VIC20 command-line options 11421 11422@table @code 11423@end table 11424 11425@c ----------------------------------------------------------------------------- 11426 11427@node PLUS4-specific, PET-specific, VIC20-specific, Machine-specific features 11428@section PLUS4-specific commands and settings 11429 11430@c @node FIXME 11431@subsection TED settings 11432 11433@c @node FIXME 11434@subsubsection TED resources 11435 11436@table @code 11437@vindex TEDVideoCache 11438@item TEDVideoCache 11439Boolean specifying whether the video cache is turned on. 11440 11441@vindex TEDDoubleSize 11442@item TEDDoubleSize 11443Boolean specifying whether double-size mode is turned on. 11444 11445@vindex TEDDoubleScan 11446@item TEDDoubleScan 11447Boolean specifying whether double-scan mode is turned on. 11448 11449@vindex TEDPaletteFile 11450@item TEDPaletteFile 11451String specifying the name of the palette file being used. The 11452@file{.vpl} extension is optional. 11453 11454@vindex TEDExternalPalette 11455@item TEDExternalPalette 11456Boolean specifying whether to use external palette file or not. 11457 11458@vindex TEDColorSaturation 11459@item TEDColorSaturation 11460Integer specifying saturation of internal calculated palette. 11461(0..2000) 11462 11463@vindex TEDColorContrast 11464@item TEDColorContrast 11465Integer specifying contrast of internal calculated palette. 11466(0..2000) 11467 11468@vindex TEDColorBrightness 11469@item TEDColorBrightness 11470Integer specifying brightness of internal calculated palette. 11471(0..2000) 11472 11473@vindex TEDColorGamma 11474@item TEDColorGamma 11475Integer specifying gamma of internal calculated palette. 11476(0..4000) 11477 11478@vindex TEDColorTint 11479@item TEDColorTint 11480Integer specifying tint of internal calculated palette. 11481(0..2000) 11482 11483@vindex TEDPALScanLineShade 11484@item TEDPALScanLineShade 11485Integer specifying amount of scan line shading for the CRT emulation. 11486(0..1000) 11487 11488@vindex TEDPALBlur 11489@item TEDPALBlur 11490Integer specifying amount of horizontal blur for the CRT emulation. 11491(0..1000) 11492 11493@vindex TEDPALOddLinePhase 11494@item TEDPALOddLinePhase 11495Integer specifying phase for color carrier in odd lines. 11496(0..2000) 11497 11498@vindex TEDPALOddLineOffset 11499@item TEDPALOddLineOffset 11500Integer specifying phase offset for color carrier in odd lines. 11501(0..2000) 11502 11503@vindex TEDAudioLeak 11504@item TEDAudioLeak 11505Boolean specifying whether to enable/disable video to audio leak emulation. 11506 11507@vindex TEDFilter 11508@item TEDFilter 11509Integer specifying rendering filter. 11510(0: None, 1: CRT emulation, 2: Scale2x) 11511 11512@vindex TEDBorderMode 11513@item TEDBorderMode 11514Integer specifying border display mode. 11515(0: normal, 1: full, 2: debug, 3: none) 11516 11517@end table 11518 11519@c @node FIXME 11520@subsubsection TED command-line options 11521 11522@table @code 11523@findex -TEDvcache, +TEDvcache 11524@item -TEDvcache 11525@itemx +TEDvcache 11526Enable/disable the video cache 11527(@code{TEDVideoCache=1}, @code{TEDVideoCache=0}). 11528 11529@findex -TEDdsize, +TEDdsize 11530@item -TEDdsize 11531@itemx +TEDdsize 11532Enable/disable double size 11533(@code{TEDDoubleSize=1}, @code{TEDDoubleSize=0}). 11534 11535@findex -TEDdscan, +TEDdscan 11536@item -TEDdscan 11537@itemx +TEDdscan 11538Enable/disable double scan 11539(@code{TEDDoubleScan=1}, @code{TEDDoubleScan=0}). 11540 11541@findex -TEDfilter 11542@item -TEDfilter <Mode> 11543Select rendering filter 11544(@code{TEDFilter}). 11545(0: None, 1: CRT emulation, 2: Scale2x) 11546 11547@findex -TEDintpal 11548@item -TEDintpal 11549Use an internal calculated palette 11550(@code{TEDExternalPalette=0}). 11551 11552@findex -TEDextpal 11553@item -TEDextpal 11554Use an external palette (file) 11555(@code{TEDExternalPalette=1}). 11556 11557@findex -TEDpalette 11558@item -TEDpalette <name> 11559Specify name of the external palette file 11560(@code{TEDPaletteFile}). 11561 11562@findex -TEDborders 11563@item -TEDborders <mode> 11564Set TED border display mode 11565(@code{TEDBorderMode}). 11566(0: normal, 1: full, 2: debug, 3: none) 11567 11568@findex -TEDsaturation 11569@item -TEDsaturation <0-2000> 11570Set saturation of internal calculated palette 11571(@code{TEDColorSaturation}). 11572 11573@findex -TEDcontrast 11574@item -TEDcontrast <0-2000> 11575Set contrast of internal calculated palette 11576(@code{TEDColorContrast}). 11577 11578@findex -TEDbrightness 11579@item -TEDbrightness <0-2000> 11580Set brightness of internal calculated palette 11581(@code{TEDColorBrightness}). 11582 11583@findex -TEDgamma 11584@item -TEDgamma <0-4000> 11585Set gamma of internal calculated palette 11586(@code{TEDColorGamma}). 11587 11588@findex -TEDtint 11589@item -TEDtint <0-2000> 11590Set tint of internal calculated palette 11591(@code{TEDColorTint}). 11592 11593@findex -TEDoddlinesphase 11594@item -TEDoddlinesphase <0-2000> 11595Set phase for color carrier in odd lines 11596(@code{TEDPALOddLinePhase}). 11597 11598@findex -TEDoddlinesoffset 11599@item -TEDoddlinesoffset <0-2000> 11600Set phase offset for color carrier in odd lines 11601(@code{TEDPALOddLineOffset}). 11602 11603@findex -TEDcrtblur 11604@item -TEDcrtblur <0-1000> 11605Amount of horizontal blur for the CRT emulation 11606(@code{TEDPALBlur}). 11607 11608@findex -TEDcrtscanlineshade 11609@item -TEDcrtscanlineshade <0-1000> 11610Amount of scan line shading for the CRT emulation 11611(@code{TEDPALScanLineShade}). 11612 11613@findex -TEDaudioleak, +TEDaudioleak 11614@item -TEDaudioleak 11615@item +TEDaudioleak 11616Enable/disable video to audio leak emulation 11617(@code{TEDAudioLeak=1}, @code{TEDAudioLeak=0}). 11618 11619@end table 11620 11621@c @node FIXME 11622@subsection PLUS4 I/O extension settings 11623 11624@c @node FIXME 11625@subsubsection PLUS4 I/O extension resources 11626 11627@table @code 11628 11629@vindex CartridgeReset 11630@item CartridgeReset 11631Boolean specifying whether the machine should be reset when a cartridge is changed. 11632 11633@vindex DIGIBLASTER 11634@item DIGIBLASTER 11635Boolean to enable/disable the Digiblaster emulation. 11636 11637@vindex SpeechEnabled 11638@item SpeechEnabled 11639Boolean to enable/disable the emulation of the V364 speech chip. 11640 11641@vindex SidCart 11642@item SidCart 11643Boolean specifying whether SID-Cart emulation is enabled or not. 11644 11645@vindex SidAddress 11646@item SidAddress 11647Integer that specifies the base address of the emulated SID chip. 11648(0xFD40, 0xFE80) 11649 11650@vindex SidClock 11651@item SidClock 11652Integer specifying the clock rate used for the emulated SID chip 11653(0: C64, 1: Plus4) 11654 11655@vindex SIDCartJoy 11656@item SIDCartJoy 11657Boolean to enable/disable the emulation of the SID-Cart control port. 11658 11659@end table 11660 11661@c @node FIXME 11662@subsubsection PLUS4 I/O extension command-line options 11663 11664@table @code 11665 11666@findex -cartreset, +cartreset 11667@item -cartreset 11668@itemx +cartreset 11669Do/don't reset machine if a cartridge is attached or detached 11670(@code{CartridgeReset=1}, @code{CartridgeReset}). 11671 11672@findex -cart, +cart 11673@item -cart <Name> 11674@itemx +cart 11675Smart-attach cartridge image / Start without cartridge 11676 11677@findex -digiblaster, +digiblaster 11678@item -digiblaster 11679@itemx +digiblaster 11680Enable/disable the digiblaster add-on 11681(@code{DIGIBLASTER=1}, @code{DIGIBLASTER=0}). 11682 11683@findex -sidcart, +sidcart 11684@item -sidcart 11685@item +sidcart 11686Enable/disable SID Cartridge 11687(@code{SidCart=1}, @code{SidCart=0}). 11688 11689@findex -sidcartjoy, +sidcartjoy 11690@item -sidcartjoy 11691@item +sidcartjoy 11692Enable/disable SID cartridge control port 11693(@code{SIDCartJoy=1}, @code{SIDCartJoy=0}). 11694 11695@findex -sidcartaddress 11696@item -sidcartaddress <address> 11697Specify address of the SID Cartridge 11698(@code{SidAddress}). 11699(0xFD40, 0xFE80) 11700 11701@findex -sidcartclock 11702@item -sidcartclock <clock> 11703Specify clock of the SID Cartridge 11704(@code{SidClock}). 11705(0: C64, 1: Plus4) 11706 11707@findex -speech, +speech 11708@item -speech 11709@itemx +speech 11710Enable/Disable the v364 speech add-on 11711(@code{SpeechEnabled=1}, @code{SpeechEnabled=0}). 11712 11713@end table 11714 11715@c @node FIXME 11716@subsection PLUS4 system ROM settings 11717 11718@c @node FIXME 11719@subsubsection PLUS4 system ROM resources 11720 11721@table @code 11722 11723@vindex KernalName 11724@item KernalName 11725String specifying the name of the Kernal ROM (default @file{kernal}). 11726 11727@vindex BasicName 11728@item BasicName 11729String specifying the name of the Basic ROM (default @file{basic}). 11730 11731@vindex FunctionLowName 11732@item FunctionLowName 11733String specifying the filename of the Lo Function ROM. 11734 11735@vindex FunctionHighName 11736@item FunctionHighName 11737String specifying the filename of the High Function ROM. 11738 11739@vindex c1loName 11740@item c1loName 11741String specifying the filename of cartridge 1 Lo ROM. 11742 11743@vindex c1hiName 11744@item c1hiName 11745String specifying the filename of cartridge 1 High ROM. 11746 11747@vindex c2loName 11748@item c2loName 11749String specifying the filename of cartridge 2 Lo ROM. 11750 11751@vindex c2hiName 11752@item c2hiName 11753String specifying the filename of cartridge 2 High ROM. 11754 11755@end table 11756 11757@c @node FIXME 11758@subsubsection PLUS4 system ROM command-line options 11759 11760@table @code 11761 11762@findex -kernal <Name> 11763@item -kernal <Name> 11764Specify name of the Kernal ROM image 11765(@code{KernalName}). 11766 11767@findex -basic <Name> 11768@item -basic <Name> 11769Specify name of the BASIC ROM image 11770(@code{BasicName}). 11771 11772@findex -functionlo 11773@item -functionlo <name> 11774Specify name of Function low ROM image 11775(@code{FunctionLowName}). 11776 11777@findex -functionhi 11778@item -functionhi <name> 11779Specify name of Function high ROM image 11780(@code{FunctionHighName}). 11781 11782@findex -c1lo 11783@item -c1lo <name> 11784Specify name of Cartridge 1 low ROM image 11785(@code{c1loName}). 11786 11787@findex -c1hi 11788@item -c1hi <name> 11789Specify name of Cartridge 1 high ROM image 11790(@code{c1HiName}). 11791 11792@findex -c2lo 11793@item -c2lo <name> 11794Specify name of Cartridge 2 low ROM image 11795(@code{c2loName}). 11796 11797@findex -c2hi 11798@item -c2hi <name> 11799Specify name of Cartridge 2 high ROM image 11800(@code{c2HiName}). 11801 11802@end table 11803 11804@c @node FIXME 11805@subsection PLUS4 settings 11806 11807@c @node FIXME 11808@subsubsection PLUS4 resources 11809 11810@table @code 11811 11812@vindex MachineVideoStandard 11813@item MachineVideoStandard 11814Integer that specifies the video standard of the emulated machine 11815(1: PAL, 2: NTSC). 11816 11817@vindex RamSize 11818@item RamSize 11819Integer specifying the size of the memory in KiB. 11820(16, 32, 64) 11821 11822@vindex MemoryHack 11823@item MemoryHack 11824Integer specifying what memory expansion hack is active. 11825(0: None, 1: C256K, 2: H256K, 3: H1024K, 4: H4096K) 11826 11827@vindex Acia1Enable 11828@item Acia1Enable 11829Boolean specifying whether the ACIA should be emulated or not. 11830 11831@end table 11832 11833@c @node FIXME 11834@subsubsection PLUS4 command-line options 11835 11836@table @code 11837 11838@findex -model 11839@item -model <model> 11840Specify the PLUS4 model you want to emulate 11841(@code{MachineVideoStandard}, @code{RamSize}, @code{KernalName}, 11842@code{BasicName}, @code{FunctionLowName}, @code{FunctionHighName}, @code{c2loName}, 11843@code{Acia1Enable}, @code{SpeechEnabled}). 11844(c16/c16pal/c16ntsc, plus4/plus4pal/plus4ntsc, v364/cv364, c232) 11845 11846@findex -pal 11847@item -pal 11848Use PAL sync factor 11849(@code{MachineVideoStandard=1}). 11850 11851@findex -ntsc 11852@item -ntsc 11853Use NTSC sync factor 11854(@code{MachineVideoStandard=2}). 11855 11856@findex -ramsize 11857@item -ramsize <ramsize> 11858Specify size of RAM installed in KiB 11859(@code{RamSize}). 11860(16, 32, 64) 11861 11862@findex -memoryexphack 11863@item -memoryexphack <device> 11864Set active memory expansion hack 11865(@code{MemoryHack}). 11866(0: None, 1: C256K, 2: H256K, 3: H1024K, 4: H4096K) 11867 11868@findex -acia, +acia 11869@item -acia 11870@itemx +acia 11871Enable/Disable the ACIA emulation 11872 11873@findex -userportdac, +userportdac 11874@item -userportdac 11875@itemx +userportdac 11876Enable/disable the userport DAC 11877(@code{UserportDAC=1}, @code{UserportDAC=0}). 11878 11879 11880@end table 11881 11882@c ----------------------------------------------------------------------------- 11883 11884@node PET-specific, CBM-II-specific, PLUS4-specific, Machine-specific features 11885@section PET-specific commands and settings 11886 11887This section lists the settings and commands that are PET-specific and 11888thus are not present in the other emulators. 11889 11890@menu 11891* PET model:: 11892* CRTC Settings:: 11893* PET I/O extensions:: 11894* PET system ROM:: 11895* PET diagnostic pin:: 11896* PET settings:: 11897* Colour PET:: 11898* PET colors:: 11899* PET DWW high resolution graphics:: 11900* PET HRE (HiRes Emulator) high resolution graphics:: 11901@end menu 11902 11903@node PET model 11904@subsection Changing PET model settings 11905 11906With @code{xpet}, it is possible to change at runtime the 11907characteristics of the emulated PET so that it matches (or not) the ones 11908of a certain PET model, and it is also possible to select from a common 11909set of PET models so that all the features are selected accordingly. 11910 11911The former is done by changing the following resources (via resource 11912file, command line options or right-menu items): 11913 11914@table @code 11915 11916@vindex RamSize 11917@item RamSize 11918Integer specifying the size of the memory in KiB. 96KiB denotes an 8096, 128KiB an 8296. 11919(4, 8, 16, 32, 96, 128) 11920 11921@vindex IOSize 11922@item IOSize 11923Integer specifying the size of the I/O area in Bytes for the 8296 model. 11924(256, 2048) 11925 11926@vindex VideoSize 11927@item VideoSize 11928Integer specifying the number of columns on the screen. 11929(0: Automatic from ROM, 40: 40 columns, 80: 80 columns) 11930 11931@vindex Ram9 11932@item Ram9 11933Boolean specifying if the 8296 can map RAM into the address range $9*** or not. 11934 11935@vindex RamA 11936@item RamA 11937Boolean specifying if the 8296 can map RAM into the address range $A*** or not. 11938 11939@vindex SuperPET 11940@item SuperPET 11941Boolean that enables/disables the SuperPET (MicroMainFrame 9000) I/O and 6809 CPU, 11942and disables/enables the 8x96 mappings. 11943 11944@vindex Basic1 11945@item Basic1 11946Boolean to enable/disable the patching of a version 1 kernal ROM to make the IEEE488 interface work. 11947 11948@vindex Basic1Chars 11949@item Basic1Chars 11950Boolean to enable/disable the exchanges of some characters in the character ROM 11951that have changed between the first PET 2001 and all newer versions. 11952 11953@vindex EoiBlank 11954@item EoiBlank 11955Boolean to enable/disable the "blank screen on EOI" feature of the oldest PET 2001. 11956 11957@vindex DiagPin 11958@item DiagPin 11959Boolean to enable/disable the diagnostic pin on the PET userport (see below). 11960 11961@vindex ChargenName 11962@item ChargenName 11963String specifying the name of the character generator ROM (default @file{chargen}). 11964 11965@vindex KernalName 11966@item KernalName 11967String specifying the name of the Kernal ROM (default @file{kernal4}). 11968 11969@vindex BasicName 11970@item BasicName 11971String specifying the name of the Basic ROM (default @file{basic4}). 11972 11973@vindex EditorName 11974@item EditorName 11975String specifying the filename of the editor ROM file. This file contains 11976an overlay for the editor ROM at $E000-$E7FF if necessary. 11977 11978@vindex RomModule9Name 11979@item RomModule9Name 11980String specifying the filename for the $9*** Expansion ROM file. This file contains 11981an expansion ROM image of 4KiB. 11982 11983@vindex RomModuleAName 11984@item RomModuleAName 11985String specifying the filename for the $A*** Expansion ROM file. This file contains 11986an expansion ROM image of 4KiB. 11987 11988@vindex RomModuleBName 11989@item RomModuleBName 11990String specifying the filename for the $B*** Expansion ROM file. This file contains 11991an expansion ROM image of 4KiB. This file overlays the lowest 4KiB of a BASIC 4 ROM. 11992 11993@end table 11994 11995Choosing a common PET model is done from the setting dialog, 11996by choosing an item from the ``Model'' selection. Available 11997models are: 11998 11999@itemize @bullet 12000@item 12001PET 2001-8N 12002@item 12003PET 3008 12004@item 12005PET 3016 12006@item 12007PET 3032 12008@item 12009PET 3032B 12010@item 12011PET 4016 12012@item 12013PET 4032 12014@item 12015PET 4032B 12016@item 12017PET 8032 12018@item 12019PET 8096 12020@item 12021PET 8296 12022@item 12023SuperPET 12024@end itemize 12025 12026Notice that this will @strong{reset the emulated machine}. 12027 12028It is also possible to select the PET model at startup, with the 12029@code{-model} command-line option: for example, @samp{xpet -model 3032} 12030will emulate a PET 3032 while @samp{xpet -model 8296} will emulate a PET 120318296. 12032 12033@node CRTC Settings 12034@subsection CRTC Settings 12035 12036@c @node FIXME 12037@subsubsection CRTC resources 12038 12039@table @code 12040 12041@vindex Crtc 12042@item Crtc 12043Boolean specifying whether to enable/disable CRTC 6545 emulation (all models from 40xx and above). 12044 12045@vindex CrtcVideoCache 12046@item CrtcVideoCache 12047Boolean specifying whether the video cache is turned on. 12048 12049@vindex CrtcDoubleSize 12050@item CrtcDoubleSize 12051Boolean specifying whether double-size mode is turned on. 12052 12053@vindex CrtcDoubleScan 12054@item CrtcDoubleScan 12055Boolean specifying whether double-scan mode is turned on. 12056 12057@vindex CrtcStretchVertical 12058@item CrtcStretchVertical 12059Boolean specifying whether vertical stretching is turned on. 12060 12061@vindex CrtcPaletteFile 12062@item CrtcPaletteFile 12063String specifying the name of the palette file being used. The 12064@file{.vpl} extension is optional. 12065 12066@vindex CrtcExternalPalette 12067@item CrtcExternalPalette 12068Boolean specifying whether to use external palette file or not. 12069 12070@vindex CrtcColorSaturation 12071@item CrtcColorSaturation 12072Integer specifying saturation of internal calculated palette. 12073(0..2000) 12074 12075@vindex CrtcColorContrast 12076@item CrtcColorContrast 12077Integer specifying contrast of internal calculated palette. 12078(0..2000) 12079 12080@vindex CrtcColorBrightness 12081@item CrtcColorBrightness 12082Integer specifying brightness of internal calculated palette. 12083(0..2000) 12084 12085@vindex CrtcColorGamma 12086@item CrtcColorGamma 12087Integer specifying gamma of internal calculated palette. 12088(0..4000) 12089 12090@vindex CrtcColorTint 12091@item CrtcColorTint 12092Integer specifying tint of internal calculated palette. 12093(0..2000) 12094 12095@vindex CrtcPALScanLineShade 12096@item CrtcPALScanLineShade 12097Integer specifying amount of scan line shading for the CRT emulation. 12098(0..1000) 12099 12100@vindex CrtcPALBlur 12101@item CrtcPALBlur 12102Integer specifying amount of horizontal blur for the CRT emulation. 12103(0..1000) 12104 12105@vindex CrtcPALOddLinePhase 12106@item CrtcPALOddLinePhase 12107Integer specifying phase for color carrier in odd lines. 12108(0..2000) 12109 12110@vindex CrtcPALOddLineOffset 12111@item CrtcPALOddLineOffset 12112Integer specifying phase offset for color carrier in odd lines. 12113(0..2000) 12114 12115@vindex CrtcAudioLeak 12116@item CrtcAudioLeak 12117Boolean specifying whether to enable/disable video to audio leak emulation. 12118 12119@vindex CrtcFilter 12120@item CrtcFilter 12121Integer specifying rendering filter. 12122(0: None, 1: CRT emulation, 2: Scale2x) 12123 12124@end table 12125 12126@c @node FIXME 12127@subsubsection CRTC command-line options 12128 12129@table @code 12130 12131@findex -crtc, +crtc 12132@item -crtc 12133@itemx +crtc 12134Enable/disable the 6545 CRTC emulation 12135(@code{Crtc=1}, @code{Crtc=0}). 12136 12137@findex -Crtcvcache, +Crtcvcache 12138@item -Crtcvcache 12139@itemx +Crtcvcache 12140Enable/disable the video cache 12141(@code{CrtcVideoCache=1}, @code{CrtcVideoCache=0}). 12142 12143@findex -Crtcdsize, +Crtcdsize 12144@item -Crtcdsize 12145@itemx +Crtcdsize 12146Enable/disable double size 12147(@code{CrtcDoubleSize=1}, @code{CrtcDoubleSize=0}). 12148 12149@findex -CRTCstretchvertical, +CRTCstretchvertical 12150@item -CRTCstretchvertical 12151@itemx +CRTCstretchvertical 12152Enable/disable vertical stretching 12153(@code{CrtcStretchVertical=1}, @code{CrtcStretchVertical=0}). 12154 12155@findex -Crtcdscan, +Crtcdscan 12156@item -Crtcdscan 12157@itemx +Crtcdscan 12158Enable/disable double scan 12159(@code{CrtcDoubleScan=1}, @code{CrtcDoubleScan=0}). 12160 12161@findex -Crtcfilter 12162@item -Crtcfilter <Mode> 12163Select rendering filter 12164(@code{CrtcFilter}). 12165(0: None, 2: CRT emulation, 3: Scale2x) 12166 12167@findex -Crtcintpal 12168@item -Crtcintpal 12169Use an internal calculated palette 12170(@code{CrtcExternalPalette=0}). 12171 12172@findex -Crtcextpal 12173@item -Crtcextpal 12174Use an external palette (file) 12175(@code{CrtcExternalPalette=1}). 12176 12177@findex -Crtcpalette 12178@item -Crtcpalette <name> 12179Specify the name of the palette file 12180(@code{CrtcPaletteFile}). 12181 12182@findex -Crtcsaturation 12183@item -Crtcsaturation <0-2000> 12184Set saturation of internal calculated palette 12185(@code{CrtcColorSaturation}). 12186 12187@findex -Crtccontrast 12188@item -Crtccontrast <0-2000> 12189Set contrast of internal calculated palette 12190(@code{CrtcColorContrast}). 12191 12192@findex -Crtcbrightness 12193@item -Crtcbrightness <0-2000> 12194Set brightness of internal calculated palette 12195(@code{CrtcColorBrightness}). 12196 12197@findex -Crtcgamma 12198@item -Crtcgamma <0-4000> 12199Set gamma of internal calculated palette 12200(@code{CrtcColorGamma}). 12201 12202@findex -Crtctint 12203@item -Crtctint <0-2000> 12204Set tint of internal calculated palette 12205(@code{CrtcColorTint}). 12206 12207@findex -Crtcoddlinesphase 12208@item -Crtcoddlinesphase <0-2000> 12209Set phase for color carrier in odd lines 12210(@code{CrtcPALOddLinePhase}). 12211 12212@findex -Crtcoddlinesoffset 12213@item -Crtcoddlinesoffset <0-2000> 12214Set phase offset for color carrier in odd lines 12215(@code{CrtcPALOddLineOffset}). 12216 12217@findex -Crtccrtblur 12218@item -Crtccrtblur <0-1000> 12219Amount of horizontal blur for the CRT emulation 12220(@code{CrtcPALBlur}). 12221 12222@findex -Crtccrtscanlineshade 12223@item -Crtccrtscanlineshade <0-1000> 12224Amount of scan line shading for the CRT emulation 12225(@code{CrtcPALScanLineShade}). 12226 12227@findex -Crtcaudioleak, +Crtcaudioleak 12228@item -Crtcaudioleak 12229@item +Crtcaudioleak 12230Enable/disable video to audio leak emulation 12231(@code{CrtcAudioLeak=1}, @code{CrtcAudioLeak=0}). 12232 12233@end table 12234 12235@node PET I/O extensions 12236@subsection PET I/O extension settings 12237 12238@c @node FIXME 12239@subsubsection PET I/O extension resources 12240 12241@table @code 12242 12243@vindex PETREU 12244@item PETREU 12245Boolean specifying whether PET REU emulation is enabled or not. 12246 12247@vindex PETREUfilename 12248@item PETREUfilename 12249String specifying the filename of the PET REU image. 12250 12251@vindex PETREUsize 12252@item PETREUsize 12253Integer specifying the size of the emulated PET REU in KiB. 12254(128, 512, 1024, 2048) 12255 12256@vindex PETDWW 12257@item PETDWW 12258Boolean specifying whether DWW emulation is enabled or not. 12259 12260@vindex PETDWWfilename 12261@item PETDWWfilename 12262String specifying the filename of the DWW image RAM image. 12263 12264@vindex PETHRE 12265@item PETHRE 12266Boolean specifying whether HRE emulation is enabled or not. 12267 12268@vindex PETColour 12269@item PETColour 12270Integer selecting the colour extension. 12271(0: off, 1: RGBI, 2: Analog) 12272 12273@vindex PETColourBG 12274@item PETColourBG 12275Iteger specifying the analog colour background on PET 4032. 12276(0..255) 12277 12278@vindex UserportDAC 12279@item UserportDAC 12280Boolean specifying whether userport DAC emulation is enabled. 12281 12282@vindex SidCart 12283@item SidCart 12284Boolean specifying whether SID Cart emulation is enabled or not. 12285 12286@vindex SidAddress 12287@item SidAddress 12288Integer that specifies the base address of the emulated SID chip. 12289(0x8F00, 0xE900) 12290 12291@vindex SidClock 12292@item SidClock 12293Integer specifying the clock rate used for the emulated SID chip. 12294(0: C64, 1: PET) 12295 12296@end table 12297 12298@c @node FIXME 12299@subsubsection PET I/O extension command-line options 12300 12301@table @code 12302 12303@findex -petreu, +petreu 12304@item -petreu 12305@itemx +petreu 12306Enable/disable the PET Memory Expansion Unit 12307(@code{PETREU=1}, @code{PETREU=0}). 12308 12309@findex -petreuimage 12310@item -petreuimage <name> 12311Specify name of PET Ram and Expansion Unit image 12312(@code{PETREUfilename}). 12313 12314@findex -petreuramsize 12315@item -petreuramsize <size in KiB> 12316Size of the PET Ram and Expansion Unit 12317(@code{PETREUsize}). 12318(128, 512, 1024, 2048) 12319 12320@findex -userportdac, +userportdac 12321@item -userportdac 12322@itemx +userportdac 12323Enable/disable the userport DAC 12324(@code{UserportDAC=1}, @code{UserportDAC=0}). 12325 12326@findex -petdww, +petdww 12327@item -petdww 12328@itemx +petdww 12329Enable/disable the PET DWW hi-res board (30xx models only) 12330(@code{PETDWW=1}, @code{PETDWW=0}). 12331 12332@findex -petdwwimage 12333@item -petdwwimage <name> 12334Specify name of PET DWW RAM image 12335(@code{PETDWWfilename}). 12336 12337@findex -pethre, +pethre 12338@item -pethre 12339@itemx +pethre 12340Enable/disable the PET HRE extension (model 8296 only) 12341(@code{PETHRE=1}, @code{PETHRE=0}). 12342 12343@findex -colour-rgbi 12344@item -colour-rgbi 12345Enable the RGBI colour extension to PET 4032 12346(@code{PETColour=1}). 12347 12348@findex -colour-analog 12349@item -colour-analog 12350Enable the analog colour extension to PET 4032 12351(@code{PETColour=2}). 12352 12353@findex -colour-analog-bg 12354@item -colour-analog-bg <Colour 0-255> 12355Select the analog colour background on PET 4032 12356(@code{PETColourBG}). 12357 12358@findex -sidcart, +sidcart 12359@item -sidcart 12360@itemx +sidcart 12361Enable/disable the SID Cartridge 12362(@code{SidCart=1}, @code{SidCart=0}). 12363 12364@findex -sidcartaddress 12365@item -sidcartaddress <address> 12366Specify address of the SID Cartridge 12367(@code{SidAddress}). 12368(0x8F00, 0xE900) 12369 12370@findex -sidcartclock 12371@item -sidcartclock <clock> 12372Specify clock of the SID Cartridge 12373(@code{SidClock}). 12374(0: C64, 1: PET) 12375 12376@end table 12377 12378@node PET system ROM 12379@subsection PET system ROM settings 12380 12381@c @node FIXME 12382@subsubsection PET system ROM resources 12383 12384@table @code 12385 12386@vindex H6809RomAName 12387@vindex H6809RomBName 12388@vindex H6809RomCName 12389@vindex H6809RomDName 12390@vindex H6809RomEName 12391@vindex H6809RomFName 12392@item H6809RomAName 12393@itemx H6809RomBName 12394@itemx H6809RomCName 12395@itemx H6809RomDName 12396@itemx H6809RomEName 12397@itemx H6809RomFName 12398Strings specifying the filenames of the respective H6809 ROM images, 12399relevant for the SuperPET. 12400 12401@end table 12402 12403@c @node FIXME 12404@subsubsection PET system ROM command-line options 12405 12406@table @code 12407 12408@findex -kernal 12409@item -kernal <name> 12410Specify filename of the Kernal ROM file 12411(@code{KernalName}). 12412 12413@findex -basic 12414@item -basic <name> 12415Specify filename of the BASIC ROM file 12416(@code{BasicName}). 12417 12418@findex -editor 12419@item -editor NAME 12420Specify the filename for the editor ROM file 12421(@code{EditorName}). 12422 12423@findex -chargen 12424@item -chargen <name> 12425Specify filename of the character generator ROM file 12426(@code{ChargenName}). 12427 12428@findex -rom9 12429@item -rom9 <name> 12430Specify the filename for the ROM image file for the $9*** 12431cartridge area (@code{RomModule9Name}). 12432 12433@findex -romA 12434@item -romA <name> 12435Specify the filename for the ROM image file for the $A*** 12436cartridge area (@code{RomModuleAName}). 12437 12438@findex -romB 12439@item -romB <name> 12440Specify the filename for the ROM image file for the $B*** 12441cartridge area (@code{RomModuleBName}). 12442 12443@findex -6809romA 12444@item -6809romA <Name> 12445Specify 4KiB to 24KiB ROM file name at $A000 for 6809 12446(@code{H6809RomAName}). 12447 12448@findex -6809romB 12449@item -6809romB <Name> 12450Specify 4KiB to 20KiB ROM file name at $B000 for 6809 12451(@code{H6809RomBName}). 12452 12453@findex -6809romC 12454@item -6809romC <Name> 12455Specify 4KiB to 16KiB ROM file name at $C000 for 6809 12456(@code{H6809RomCName}). 12457 12458@findex -6809romD 12459@item -6809romD <Name> 12460Specify 4KiB to 12KiB ROM file name at $D000 for 6809 12461(@code{H6809RomDName}). 12462 12463@findex -6809romE 12464@item -6809romE <Name> 12465Specify 2KiB or 8KiB ROM file name at $E000 for 6809 12466(@code{H6809RomEName}). 12467 12468@findex -6809romF 12469@item -6809romF <Name> 12470Specify 4KiB ROM file name at $F000 for 6809 12471(@code{H6809RomFName}). 12472 12473@end table 12474 12475@node PET diagnostic pin 12476@subsection The PET diagnostic pin 12477 12478It is possible to enable or disable emulation of the PET diagnostic pin 12479via the @code{DiagPin} resource, or the ``PET userport diagnostic pin'' 12480item in the right-button menu. 12481 12482When the diagnostic pin is set, the Kernal does not try to initialize 12483the BASIC, but directly jumps into the builtin machine monitor. 12484 12485@node PET settings 12486@subsection PET settings 12487 12488@c @node FIXME 12489@subsubsection PET resources 12490 12491@table @code 12492 12493@vindex MachineVideoStandard 12494@item MachineVideoStandard 12495Integer that specifies the video standard of the emulated machine 12496(1: PAL, 2: NTSC). 12497 12498@vindex CPUswitch 12499@item CPUswitch 12500Integer specifying the status of the SuperPET CPU switch 12501(0: 6502, 1: 6809, 2: Prog.) 12502 12503@end table 12504 12505@subsubsection PET command line options 12506 12507These are the commandline options specific for the PET models. 12508 12509@table @code 12510 12511@findex -pal 12512@item -pal 12513Use PAL sync factor 12514(@code{MachineVideoStandard=1}). 12515 12516@findex -ntsc 12517@item -ntsc 12518Use NTSC sync factor 12519(@code{MachineVideoStandard=2}). 12520 12521@findex -model 12522@item -model <model> 12523Specify the PET model you want to emulate 12524(@code{Basic1}, @code{Basic1Chars}, @code{ChargenName}, @code{KernalName}, 12525@code{BasicName}, @code{EditorName}, @code{RomModule9Name}, @code{RomModuleAName}, 12526@code{RomModuleBName}, @code{H6809RomAName}, @code{H6809RomBName}, @code{H6809RomCName}, 12527@code{H6809RomDName}, @code{H6809RomEName}, @code{H6809RomFName}). 12528(2001, 3008, 3016, 3032, 3032B, 4016, 4032, 4032B, 8032, 8096, 8296, SuperPET) 12529 12530@findex -iosize 12531@item -iosize <size> 12532Specify size of I/O in Bytes 12533(@code{IOSize}). 12534(256, 2048) 12535 12536@findex -ramsize 12537@item -ramsize <size> 12538Specify size of RAM in KiB 12539(@code{RamSize}). 12540(8, 16, 32, 96, 128) 12541 12542@findex -videosize 12543@item -videosize <size> 12544Specify video size 12545(@code{VideoSize}). 12546(0: Automatic from ROM, 40: 40 columns, 80: 80 columns) 12547 12548@findex -petram9, +petram9 12549@item -petram9 12550@itemx +petram9 12551Switch on/off RAM mapping at address $9000-$9FFF 12552(@code{Ram9=1}, @code{Ram9=0}). 12553 12554@findex -petramA, +petramA 12555@item -petramA 12556@itemx +petramA 12557Switch on/off RAM mapping at address $A000-$AFFF 12558(@code{RamA=1}, @code{RamA=0}). 12559 12560@findex -superpet, +superpet 12561@item -superpet 12562@itemx +superpet 12563Enable/disable SuperPET I/O and CPU emulation 12564(@code{SuperPET}). 12565 12566@findex -cpu6502 12567@item -cpu6502 12568Set SuperPET CPU switch to '6502' 12569(@code{CPUswitch=0}). 12570 12571@findex -cpu6809 12572@item -cpu6809 12573Set SuperPET CPU switch to '6809' 12574(@code{CPUswitch=1}). 12575 12576@findex -cpuprog 12577@item -cpuprog 12578Set SuperPET CPU switch to 'Prog' 12579(@code{CPUswitch=2}). 12580 12581@findex -basic1, +basic1 12582@item -basic1 12583@itemx +basic1 12584Enable/disable patching the IEEE488 section of the PET2001 ROM when detected 12585(@code{Basic1=1}, @code{Basic1=0}). 12586 12587@findex -basic1char, +basic1char 12588@item -basic1char 12589@itemx +basic1char 12590Enable/disable PET 2001 character generator 12591(@code{Basic1Chars=1}, @code{Basic1Chars=0}). 12592 12593@findex -eoiblank, +eoiblank 12594@item -eoiblank 12595@itemx +eoiblank 12596Enable/disable EOI blanking the screen 12597(@code{EoiBlank=1}, @code{EoiBlank=0}). 12598 12599@findex -diagpin, +diagpin 12600@item -diagpin 12601@itemx +diagpin 12602Enable/disable the diagnostic pin at the PET userport 12603(@code{DiagPin=1}, @code{DiagPin=0}). 12604 12605@end table 12606 12607@node Colour PET 12608@subsection Colour PET 12609The Colour PET is a simple extension by Steve Gray 12610@uref{http://www.6502.org/users/sjgray/projects/colourpet/}. It exploits 12611the similarities and differences between the 4032 and 8032 models, to 12612use memory at $8800 as colour RAM. 12613 12614There are two versions of the extension: 12615 12616with digital colour (RGBI), which can select 16 foreground and 16 12617background colours for each character cell. The 8 colour bits are 12618used as RGBI RGBI, with the most significant bits for the background, 12619and the least significant bits for the foreground. 12620 12621With analog colour, which can use 256 foreground colours for each 12622character cell, the 8 colour bits are used as RRR GGG BB. 12623 12624@node PET colors 12625@subsection Changing screen colors 12626 12627It is also possible to choose what color set is used for the emulation 12628window. This is done by specifying a palette file 12629name (@pxref{Palette files}) in the @code{PaletteName} 12630resource. The menu provides the 12631following values: 12632 12633@itemize @bullet 12634@item 12635@code{green.vpl} (default, ``green)''), the good old green-on-black 12636feeling; 12637@item 12638@code{amber.vpl} (``amber''), an amber phosphor lookalike; 12639@item 12640@code{white.vpl} (``white''), simple white-on-black palette. 12641@end itemize 12642 12643@node PET DWW high resolution graphics 12644 12645@subsection DWW high resolution graphics 12646@cindex DWW 12647The DWW, or Double-W 12648@footnote{Dubbel-W bord, designed by Ben de Winter and Pieter 12649Wolvekamp}, 12650board is a high resolution graphics board for PET models 30xx. It 12651attaches to the internal expansion connector. It would not physically 12652fit in 20xx, 40xx or 80xx models because their connectors are physically 12653and logically different. Apart from this, it requires address space at 12654$EC00-$EFFF, which makes it unfit to work in 40xx and 80xx models, which 12655have only 256 bytes of I/O space at $E800. 12656 12657The DWW board consists of 8 KiB of RAM and a PIA to control various 12658options. The RAM can be mapped either linearly at $9000-$AFFF, 12659or bank-switched in 8 banks of 1 KiB each at $EC00-$EFFF. 12660 12661It seems that in the demo programs, the BASIC versions like to 12662POKE in 60200, where the machine language programs use $EB00. 12663@verbatim 1266460200 Port A or DDR A $EB28 12665$EBx0 1 0 \ 12666 2 1 - RAM block at $EC00 (0-7) 12667 4 2 / 12668 8 3 charrom 0 = off 1 = on 12669 16 4 hires 0 = on 1 = off 12670 32 5 extra charrom 0 = on 1 = off 12671 1267260201 Control Register A: bit #3 (worth 4) controls if 60200 12673$EBx1 accesses the Data Direction Register A (0) or Port A (1). 12674 1267560202 Port B or DDR B 12676$EBx2 0 = RAM is visible from $9000 - $AFFF 12677 1 = RAM is bank-switched in blocks of 1 K in $EC00 - $EFFF 12678 12679 [Control Register B is never mentioned, so putting 1 in this 12680 address would access the DDR, creating an output line, which 12681 after RESET is default 0...] 12682@end verbatim 12683 12684Typical initialisation sequence: 12685@verbatim 12686 poke 60201,0 poke 60200,255 (all outputs) 12687 poke 60201,4 poke 60200,24 or 25 (16 + 8 + 1) 12688@end verbatim 12689 12690Demo programs on disk PBE-110A, 110B, 111A, and 111B. 12691(PBE = PET Benelux Exchange, the Dutch PET user group) 12692 12693The memory mapping is a bit strange. It seems each 1 K block contains 12694the pixeldata for 1 bit-line of each text line. This is probably so that 12695the addressing of the RAM can borrow part of the addressing 12696logic/signals of the text screen. (The screen addressing cycles through 126970-39, then increases the line (= byte offset) which is fetched from 12698the character ROM; for the graphics, the screen position selects the 12699byte in a KiB and the char ROM offset selects which KiB of graphics RAM). 12700 12701My notes say: to set a pixel: 12702@verbatim 12703RE = INT(Y/8): LY = Y - 8*RE (or Y AND 7) 12704BY = INT(X/8): BI = X - 8*BY (or X AND 7) 12705@end verbatim 12706 12707when memory mapped to $9000: 12708@verbatim 12709 L = 36864 + 1024 * LY + 40 * RE + BY 12710 POKE L, PEEK(L) OR 2^BI 12711@end verbatim 12712 12713when memory mapped to $EC00: 12714@verbatim 12715 POKE 60200,LY + 40 (or 8?) 12716 L = 60416 + RE * 40 + BY 12717 POKE L, PEEK(L) OR 2^BI 12718@end verbatim 12719 12720Unfortunately there is no logical means of expanding the memory 12721to 16 K, so even in an 80 columns PET the resolution will be the same. 12722 12723@node PET HRE (HiRes Emulator) high resolution graphics 12724 12725@subsection HRE high resolution graphics 12726 12727This information comes from @email{kontakt@@michau.name, Michal Pleban}, 12728@uref{http://www.cbm-ii.com}. 12729 12730@cindex HRE 12731This is a short information about the HRE (HiRes Emulator) graphics 12732board for PET 8296. This is a small board that is installed on the 12733mainboard into sockets for the CRTC and character ROM. It adds the 12734ability to display 512x256 graphics on the built-in monitor. 12735 12736The board is accompanied with two extension ROMs: 12737 12738@itemize 12739@item 12740324992-02 HiRes Emulator (at $9000) 12741@item 12742324993-02 HiRes BASIC (at $A000) 12743@end itemize 12744 12745The ROMs are initialized by the command 12746@code{SYS 36864}. 12747 12748@cindex HRG 12749After that, the computer recognizes additional BASIC commands like 12750DISPLAY, PLOT and so on; these commands are identical to those of the 12751HiRes Graphics boards based on Thomson chips. All BASIC programs written 12752for the HRG boards should also work on the HRE (albeit much slower). 12753 12754Upon initialization, the ROM code writes some routines into expansion 12755RAM as $8800 - they are used to manipulate the bitmap data. The actual 12756bitmap is located in expansion RAM at addresses $A000-$DFFF, and is 12757organized linearly (first 64 bytes form the first display line, then 12758comes the next line and so on). 12759 12760The RAM is accessed for reading by writing the value #$83 into $E888. 12761This is a register in the CRTC memory space that is intercepted by the 12762board and serves as a latch to drive jumpers on the 8296D mainboard. 12763Because the ROMs are banked out this way, all video memory manipulation 12764must happen with interrupts disabled. Normal ROM operation is restored 12765by writing #$0F into $E888. 12766 12767As usual with the 8296, the RAM can also be written even when the ROMs 12768are mapped normally. 12769 12770The board is initialized into graphics mode by modifying the following 12771values in CRTC registers (it is done by the routine located at $8C1A): 12772 12773@itemize @bullet 12774@item 12775Register $01 (horizontal displayed) = #$20 12776@item 12777Register $02 (horizontal sync position) = original + #$02 12778@item 12779Register $06 (vertical displayed) = #$20 12780@item 12781Register $07 (vertical sync position) = original + #$04 12782@item 12783Register $0C (RAM address high) = #$02 12784@end itemize 12785 12786The last value causes the board to switch into graphics mode; former values set up proper screen dimensions for 512x256 display. 12787 12788@c -------------------------------------------------------------- 12789 12790@node CBM-II-specific, VSID-specific, PET-specific, Machine-specific features 12791@section CBM-II-specific commands and settings 12792 12793This section lists the settings and commands that are CBM-II-specific and 12794thus are not present in the other emulators. 12795 12796@menu 12797* CBM-II model:: 12798* CBM-II commandline options:: 12799* CBM-II colors:: 12800@end menu 12801 12802@node CBM-II model, CBM-II commandline options, CBM-II-specific, CBM-II-specific 12803@subsection Changing CBM-II model 12804 12805With @code{xcbm2} and @code{xcbm5x0}, it is possible to change at runtime the 12806characteristics of the emulated CBM so that it matches (or not) the ones 12807of a certain CBM model, and it is also possible to select from a common 12808set of CBM models so that all the features are selected accordingly. 12809 12810The former is done by changing the following resources (via resource 12811file, command line options or right-menu items): 12812 12813@table @code 12814 12815@vindex RamSize 12816@item RamSize 12817Size of memory in KiB. 12818xcbm2: (128, 256, 512, 1024) 12819xcbm5x0: (64, 128, 256, 512, 1024) 12820 12821@vindex Ram08 12822@item Ram08 12823Boolean specifying whether the RAM should be mapped to the expansion ROM area at $0800-$0FFF or not. 12824 12825@vindex Ram1 12826@item Ram1 12827Boolean specifying whether the RAM should be mapped to the expansion ROM area at $1000-$1FFF or not. 12828 12829@vindex Ram2 12830@item Ram2 12831Boolean specifying whether the RAM should be mapped to the expansion ROM area at $2000-$3FFF or not. 12832 12833@vindex Ram4 12834@item Ram4 12835Boolean specifying whether the RAM should be mapped to the expansion ROM area at $4000-$5FFF or not. 12836 12837@vindex Ram6 12838@item Ram6 12839Boolean specifying whether the RAM should be mapped to the expansion ROM area at $6000-$7FFF or not. 12840 12841@vindex RamC 12842@item RamC 12843Boolean specifying whether the RAM should be mapped to the expansion ROM area at $C000-$CFFF or not. 12844 12845@vindex CartridgeReset 12846@item CartridgeReset 12847Boolean specifying whether the machine should be reset when a cartridge is changed. 12848 12849@vindex Cart1Name 12850@item Cart1Name 12851String specifying the filename for the $1000-$1FFF expansion ROM file. This file contains a 4KiB ROM dump. 12852 12853@vindex Cart2Name 12854@item Cart2Name 12855String specifying the filename for the $2000-$3FFF expansion ROM file. This file contains an 8KiB ROM dump. 12856 12857@vindex Cart4Name 12858@item Cart4Name 12859String specifying the filename for the $4000-$5FFF expansion ROM file. This file contains an 8KiB ROM dump. 12860 12861@vindex Cart6Name 12862@item Cart6Name 12863String specifying the filename for the $6000-$7FFF expansion ROM file. This file contains an 8KiB ROM dump. 12864 12865@vindex ModelLine 12866@item ModelLine 12867The CBM-II business models have two hardcoded lines at one of the I/O ports. 12868From those lines the kernal determines how it should init the 12869CRTC video chip for either 50Hz (Europe) or 60Hz (North America), 12870and either for 8 (C6x0) or 14 (C7x0) scanlines per character. 12871xcbm2: (0: CBM 7x0 (50Hz), 1: 60Hz C6x0, 2: 50Hz C6x0) 12872xcbm5x0: (1: 60Hz C5x0, 2: 50Hz C5x0) 12873 12874@vindex ChargenName 12875@item ChargenName 12876String specifying the name of the character generator ROM 12877(default for xcbm2: @file{chargen.600}, default for xcbm5x0: @file{chargen.500}). 12878 12879@vindex KernalName 12880@item KernalName 12881String specifying the name of the Kernal ROM 12882(default for xcbm2: @file{kernal}, default for xcbm5x0: @file{kernal.500}). 12883 12884@vindex BasicName 12885@item BasicName 12886String specifying the name of the Basic ROM 12887(default for xcbm2: @file{basic.128}, default for xcbm5x0: @file{basic.500}). 12888 12889@vindex MachineVideoStandard 12890@item MachineVideoStandard 12891@c will be 'fixed' for xcbm2 later, for now xcbm5x0 only 12892Integer that specifies the video standard of the emulated machine 12893(1: PAL, 2: NTSC). 12894 12895@end table 12896 12897Choosing a common CBM-II model is done from the right-button menu instead, 12898by choosing an item from the ``Model defaults'' submenu. Available 12899models are: 12900 12901@itemize @bullet 12902@item 12903C510 PAL or NTSC (128KiB RAM) 12904@item 12905C610 PAL or NTSC (128KiB RAM) 12906@item 12907C620 (256KiB RAM) 12908@item 12909C620+ (1024KiB RAM, expanded) PAL or NTSC 12910@item 12911C710 (128KiB RAM) NTSC 12912@item 12913C720 (256KiB RAM) NTSC 12914@item 12915C720+ (1024KiB RAM, expanded) NTSC 12916@end itemize 12917 12918Notice that this will @strong{reset the emulated machine}. 12919 12920@b{Warning:} At this time the 5x0 and other machines are implemented 12921in different executables, so switching between those models is not possible. 12922 12923It is also possible to select the CBM model at startup, with the 12924@code{-model} command-line option: for example, @samp{xcbm2 -model 610} 12925will emulate a CBM 610 while @samp{xcbm2 -model 620} will emulate a CBM 12926620. 12927 12928@c @node FIXME 12929@subsection CBM-II system ROM settings 12930 12931@c @node FIXME 12932@subsubsection CBM-II system ROM resources 12933 12934@c @node FIXME 12935@subsubsection CBM-II system ROM command line options 12936 12937@table @code 12938 12939@findex -kernal 12940@item -kernal <name> 12941Specify the name of the Kernal ROM file 12942(@code{KernalName}). 12943 12944@findex -basic 12945@item -basic <name> 12946Specify the name of the Basic ROM file 12947(@code{BasicName}). 12948 12949@findex -chargen 12950@item -chargen <name> 12951Specify the filename for the character generator ROM file 12952(@code{ChargenName}). 12953 12954@findex +cart 12955@item +cart 12956Disable all cartridges (which would eventually be enabled in the config file). 12957 12958@findex -cartreset, +cartreset 12959@item -cartreset 12960@itemx +cartreset 12961Reset/do not reset machine if a cartridge is attached or detached 12962(@code{CartridgeReset=1}, @code{CartridgeReset=0}). 12963 12964@findex -cart1 12965@item -cart1 <name> 12966Specify the filename for the ROM image file for the cartridge area $1000-$1FFF 12967(@code{Cart1Name}). 12968 12969@findex -cart2 12970@item -cart2 <name> 12971Specify the filename for the ROM image file for the cartridge area $2000-$2FFF 12972(@code{Cart2Name}). 12973 12974@findex -cart4 12975@item -cart4 <name> 12976Specify the filename for the ROM image file for the cartridge area $4000-$5FFF 12977(@code{Cart4Name}). 12978 12979@findex -cart6 12980@item -cart6 <name> 12981Specify the filename for the ROM image file for the cartridge area $6000-$7FFF 12982(@code{Cart6Name}). 12983@end table 12984 12985@node CBM-II commandline options, CBM-II colors, CBM-II model, CBM-II-specific 12986@subsection CBM-II command line options 12987 12988These are the commandline options specific for the CBM-II models. 12989 12990@table @code 12991 12992@findex -pal 12993@item -pal 12994Use PAL sync factor 12995(@code{MachineVideoStandard=1}). 12996 12997@findex -ntsc 12998@item -ntsc 12999Use NTSC sync factor 13000(@code{MachineVideoStandard=2}). 13001 13002@findex -ramsize 13003@item -ramsize <ramsize> 13004Specify size of RAM 13005(@code{RamSize}). 13006xcbm2: (128, 256, 512, 1024) 13007xcbm5x0: (64, 128, 256, 512, 1024) 13008 13009@findex -ram08, +ram08 13010@item -ram08 13011@itemx +ram08 13012Enable/disable RAM mapping in bank 15 at address $0800-$0FFF 13013(@code{Ram08=1}, @code{Ram08=0}). 13014 13015@findex -ram1, +ram1 13016@item -ram1 13017@itemx +ram1 13018Enable/disable RAM mapping in bank 15 at address $1000-$1FFF 13019(@code{Ram1=1}, @code{Ram1=0}). 13020 13021@findex -ram2, +ram2 13022@item -ram2 13023@itemx +ram2 13024Enable/disable RAM mapping in bank 15 at address $2000-$3FFF 13025(@code{Ram2=1}, @code{Ram2=0}). 13026 13027@findex -ram4, +ram4 13028@item -ram4 13029@itemx +ram4 13030Enable/disable RAM mapping in bank 15 at address $4000-$5FFF 13031(@code{Ram4=1}, @code{Ram4=0}). 13032 13033@findex -ram6, +ram6 13034@item -ram6 13035@itemx +ram6 13036Enable/disable RAM mapping in bank 15 at address $6000-$7FFF 13037(@code{Ram6=1}, @code{Ram6=0}). 13038 13039@findex -ramC, +ramC 13040@item -ramC 13041@itemx +ramC 13042Enable/disable RAM mapping in bank 15 at address $C000-$CFFF 13043(@code{RamC=1}, @code{RamC=0}). 13044 13045@findex -model 13046@item -model <modelnumber> 13047Specify CBM-II model to emulate 13048(@code{ModelLine}, @code{MachineVideoStandard}, @code{RamSize}, @code{KernalName}, @code{BasicName}, @code{ChargenName}). 13049xcbm2: (610, 620, 620+, 710, 720, 720+) 13050xcbm5x0: (510) 13051 13052@end table 13053 13054@node CBM-II colors, , CBM-II commandline options, CBM-II-specific 13055@subsection Changing screen colors 13056 13057It is also possible to choose what color set is used for the emulation 13058window. This is done by specifying a palette file name 13059(@pxref{Palette files}) in the @code{PaletteName} 13060resource. The menu provides the 13061following values: 13062 13063@itemize @bullet 13064@item 13065@code{green.vpl} (default, ``green''), the good old green-on-black 13066feeling; 13067@item 13068@code{amber.vpl} (``amber''), an amber phosphor lookalike; 13069@item 13070@code{white.vpl} (``white''), simple white-on-black palette. 13071@end itemize 13072 13073@c ----------------------------------------------------------------- 13074 13075@node VSID-specific, , CBM-II-specific, Machine-specific features 13076@section VSID-specific commands and settings 13077 13078@c @node FIXME 13079@subsection VSID settings 13080 13081@c @node FIXME 13082@subsubsection VSID resources 13083 13084@table @code 13085 13086@vindex PSIDKeepEnv 13087@item PSIDKeepEnv 13088Boolean that specifies whether to override PSID settings for Video standard and 13089SID model. 13090 13091@vindex PSIDTune 13092@item PSIDTune 13093Integer that specifies the currently played sub tune. 13094 13095@vindex HVSCRoot 13096@item HVSCRoot 13097String specifying the location of the HVSC "C64Music" directory. 13098 13099@vindex ChargenName 13100@item ChargenName 13101String specifying the name of the character generator ROM (default @file{chargen}). 13102 13103@vindex KernalName 13104@item KernalName 13105String specifying the name of the Kernal ROM (default @file{kernal}). 13106 13107@vindex BasicName 13108@item BasicName 13109String specifying the name of the Basic ROM (default @file{basic}). 13110 13111@vindex KernalRev 13112@item KernalRev 13113String specifying the Kernal revision. This resource can be used to 13114control what revision of the C64 kernal is being used; it cannot be 13115changed at runtime. VICE is able to automatically convert one ROM 13116revision into another, by manually patching the loaded image. This way, 13117it is possible to use any of the ROM revisions without changing the ROM 13118set. Valid values are: 13119 13120@table @code 13121@item 0 13122Kernal revision 0; 13123@item 3 13124Kernal revision 3; 13125@item sx 13126@itemx 67 13127Commodore SX-64 ROM; 13128@item 100 13129@item 4064 13130Commodore 4064 (also known as ``PET64'' or ``Educator 64'') ROM. 13131@end table 13132 13133@vindex MachineVideoStandard 13134@item MachineVideoStandard 13135Integer that specifies the video standard of the emulated machine 13136(4: PAL-N, 3: Old NTSC, 1: PAL, 2: NTSC). 13137 13138@end table 13139 13140@c @node FIXME 13141@subsubsection VSID command-line options 13142 13143@table @code 13144 13145@findex -keepenv 13146@item -keepenv 13147Override PSID settings for Video standard and SID model 13148(@code{PSIDKeepEnv=1}). 13149 13150@findex -tune 13151@item -tune <number> 13152Specify PSID tune <number> 13153(@code{PSIDTune}). 13154 13155@findex -hvsc-root 13156@item -hvsc-root <path> 13157Specify the location of the HVSC "C64Music" directory. 13158(@code{HVSCRoot}). 13159 13160@findex -chargen 13161@item -chargen <name> 13162Specify name of character generator ROM image 13163(@code{ChargenName}). 13164 13165@findex -kernal 13166@item -kernal <name> 13167Specify name of the Kernal ROM image 13168(@code{KernalName}). 13169 13170@findex -basic 13171@item -basic <name> 13172Specify name of the Basic ROM image 13173(@code{BasicName}). 13174 13175@findex -pal 13176@item -pal 13177Use PAL sync factor 13178(@code{MachineVideoStandard=1}). 13179 13180@findex -ntsc 13181@item -ntsc 13182Use NTSC sync factor 13183(@code{MachineVideoStandard=2}). 13184 13185@findex -ntscold 13186@item -ntscold 13187Use old NTSC sync factor 13188(@code{MachineVideoStandard=3}). 13189 13190@findex -paln 13191@item -paln 13192Use PAL-N sync factor 13193(@code{MachineVideoStandard=4}). 13194 13195@end table 13196 13197@c ----------------------------------------------------------------- 13198 13199@node Platform-specific features, Snapshots, Machine-specific features, Top 13200@chapter Platform-specific features 13201 13202This section lists the settings and commands that are platform specific. 13203 13204@menu 13205@ifset platformsdl 13206* SDL-specific features:: 13207@end ifset 13208@ifset platformgtk3 13209* GTK3 specific features:: 13210@end ifset 13211@end menu 13212 13213@c ----------------------------------------------------------------- 13214 13215@ifset platformsdl 13216@node SDL-specific features 13217@section SDL-specific features 13218 13219This section lists the settings and commands that are common and specific to SDL, and are thus not present in other platforms. 13220 13221@c ----------------------------------------------------------------- 13222@c @node FIXME 13223@subsection SDL specific resources 13224 13225@table @code 13226 13227@vindex HotkeyFile 13228@item HotkeyFile 13229String specifying the name of the hotkey file 13230(all emulators except vsid). 13231 13232@vindex MenuKey 13233@item MenuKey 13234Integer specifying the keycode for activating the SDL menu. 13235 13236@vindex MenuKeyUp 13237@item MenuKeyUp 13238Integer specifying the keycode for 'up' in the SDL menu. 13239 13240@vindex MenuKeyDown 13241@item MenuKeyDown 13242Integer specifying the keycode for 'down' in the SDL menu. 13243 13244@vindex MenuKeyLeft 13245@item MenuKeyLeft 13246Integer specifying the keycode for 'left' in the SDL menu. 13247 13248@vindex MenuKeyRight 13249@item MenuKeyRight 13250Integer specifying the keycode for 'right' in the SDL menu. 13251 13252@vindex MenuKeyPageUp 13253@item MenuKeyPageUp 13254Integer specifying the keycode for 'page up' in the SDL menu. 13255 13256@vindex MenuKeyPageDown 13257@item MenuKeyPageDown 13258Integer specifying the keycode for 'page down' in the SDL menu. 13259 13260@vindex MenuKeyHome 13261@item MenuKeyHome 13262Integer specifying the keycode for 'home' in the SDL menu. 13263 13264@vindex MenuKeyEnd 13265@item MenuKeyEnd 13266Integer specifying the keycode for 'end' in the SDL menu. 13267 13268@vindex MenuKeySelect 13269@item MenuKeySelect 13270Integer specifying the keycode for 'select' in the SDL menu. 13271 13272@vindex MenuKeyCancel 13273@item MenuKeyCancel 13274Integer specifying the keycode for 'cancel' in the SDL menu. 13275 13276@vindex MenuKeyExit 13277@item MenuKeyExit 13278Integer specifying the keycode for 'exit' in the SDL menu. 13279 13280@vindex MenuKeyMap 13281@item MenuKeyMap 13282Integer specifying the keycode for 'map' in the SDL menu. 13283 13284@vindex SaveResourcesOnExit 13285@item SaveResourcesOnExit 13286Boolean specifying whether the emulator should save changed settings 13287before exiting. If this is enabled, the user will be always prompted 13288first, in case the settings have changed. 13289 13290@vindex ConfirmOnExit 13291@item ConfirmOnExit 13292Boolean specifying whether to show a confirmation dialog on exit. 13293 13294@vindex PauseOnSettings 13295@item PauseOnSettings 13296Boolean specifying wheter to pause the emulation when triggering the settings 13297dialog. If set, the emulation will pause when triggering the settings dialog. 13298When closing the settings dialog the pause state will revert to its state before 13299triggering the settings UI. 13300 13301@vindex SDLStatusbar 13302@item SDLStatusbar 13303Boolean to enable/disable the statusbar 13304(all emulators except vsid). 13305 13306@vindex SDLBitdepth 13307@item SDLBitdepth 13308Integer specifying the bitdepth used. 13309(0: current, 8, 15, 16, 24, 32) 13310 13311@vindex SDLLimitMode 13312@item SDLLimitMode 13313Integer specifying the resolution limit mode. 13314(0: off, 1: max, 2: fixed) 13315 13316@vindex SDLCustomWidth 13317@item SDLCustomWidth 13318Integer specifying the custom resolution width. 13319 13320@vindex SDLCustomHeight 13321@item SDLCustomHeight 13322Integer specifying the custom resolution height. 13323 13324@vindex KbdStatusbar 13325@item KbdStatusbar 13326Boolean specifying whether the keyboard-status bar is enabled. 13327 13328@vindex SDL2Renderer 13329@item SDL2Renderer 13330String specifying the preferred SDL2 renderer. 13331 13332@vindex SDLWindowWidth 13333@item SDLWindowWidth 13334Integer specifying the SDL window width. 13335 13336@vindex SDLWindowHeight 13337@item SDLWindowHeight 13338Integer specifying the SDL window height. 13339 13340@vindex SDLGLFilter 13341@item SDLGLFilter 13342Integer specifying the OpenGL filtering mode. 13343 13344@vindex JoyDevice1 13345@item JoyDevice1 13346Integer specifying which joystick device the emulator should use for the emulation of joystick 1 13347(all emulators except xcbm2, xpet and vsid). 13348(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13349 13350@vindex JoyDevice2 13351@item JoyDevice2 13352Integer specifying which joystick device the emulator should use for the emulation of joystick 2 13353(all emulators except xcbm2, xpet, xvic and vsid). 13354(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13355 13356@vindex JoyDevice3 13357@item JoyDevice3 13358Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1 13359(all emulators except xcbm5x0 and vsid). 13360(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13361 13362@vindex JoyDevice4 13363@item JoyDevice4 13364Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2 13365(all emulators except xcbm5x0, xplus4 and vsid). 13366(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13367 13368@vindex CrtcSDLFullscreenMode 13369@item CrtcSDLFullscreenMode 13370Integer specifying the fullscreen mode 13371(xcbm2 and xpet only). 13372 13373@vindex CrtcHwScale 13374@item CrtcHwScale 13375Boolean specifying whether to enable or disable hardware scaling 13376(xcbm2 and xpet only). 13377 13378@vindex CrtcFullscreenDevice 13379@item CrtcFullscreenDevice 13380String specifying the fullscreen device 13381(xcbm2 and xpet only). 13382 13383@vindex CrtcFullscreen 13384@item CrtcFullscreen 13385Boolean specifying whether to use fullscreen mode or not 13386(xcbm2 and xpet only). 13387 13388@vindex CrtcFullscreenStatusbar 13389@item CrtcFullscreenStatusbar 13390Boolean specifying whether to show the status bar in fullscreen mode or not 13391(xcbm2 and xpet only). 13392 13393@vindex TEDSDLFullscreenMode 13394@item TEDSDLFullscreenMode 13395Integer specifying the fullscreen mode 13396(xplus4 only). 13397 13398@vindex TEDHwScale 13399@item TEDHwScale 13400Boolean specifying whether to enable or disable hardware scaling 13401(xplus4 only). 13402 13403@vindex TEDFullscreenDevice 13404@item TEDFullscreenDevice 13405String specifying the fullscreen device 13406(xplus4 only). 13407 13408@vindex TEDFullscreen 13409@item TEDFullscreen 13410Boolean specifying whether to use fullscreen mode or not 13411(xplus4 only). 13412 13413@vindex TEDFullscreenStatusbar 13414@item TEDFullscreenStatusbar 13415Boolean specifying whether to show the status bar in fullscreen mode or not 13416(xplus4 only). 13417 13418@vindex VDCSDLFullscreenMode 13419@item VDCSDLFullscreenMode 13420Integer specifying the fullscreen mode 13421(x128 only). 13422 13423@vindex VDCHwScale 13424@item VDCHwScale 13425Boolean specifying whether to enable or disable hardware scaling 13426(x128 only). 13427 13428@vindex VDCFullscreenDevice 13429@item VDCFullscreenDevice 13430String specifying the fullscreen device 13431(x128 only). 13432 13433@vindex VDCFullscreen 13434@item VDCFullscreen 13435Boolean specifying whether to use fullscreen mode or not 13436(x128 only). 13437 13438@vindex VDCFullscreenStatusbar 13439@item VDCFullscreenStatusbar 13440Boolean specifying whether to show the status bar in fullscreen mode or not 13441(x128 only). 13442 13443@vindex VICSDLFullscreenMode 13444@item VICSDLFullscreenMode 13445Integer specifying the fullscreen mode 13446(xvic only). 13447 13448@vindex VICHwScale 13449@item VICHwScale 13450Boolean specifying whether to enable or disable hardware scaling 13451(xvic only). 13452 13453@vindex VICFullscreenDevice 13454@item VICFullscreenDevice 13455String specifying the fullscreen device 13456(xvic only). 13457 13458@vindex VICFullscreen 13459@item VICFullscreen 13460Boolean specifying whether to use fullscreen mode or not 13461(xvic only). 13462 13463@vindex VICFullscreenStatusbar 13464@item VICFullscreenStatusbar 13465Boolean specifying whether to show the status bar in fullscreen mode or not 13466(xvic only). 13467 13468@vindex VICIISDLFullscreenMode 13469@item VICIISDLFullscreenMode 13470Integer specifying the fullscreen mode 13471(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13472 13473@vindex VICIIHwScale 13474@item VICIIHwScale 13475Boolean specifying whether to enable or disable hardware scaling 13476(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13477 13478@vindex VICIIFullscreenDevice 13479@item VICIIFullscreenDevice 13480String specifying the fullscreen device 13481(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13482 13483@vindex VICIIFullscreen 13484@item VICIIFullscreen 13485Boolean specifying whether to use fullscreen mode or not 13486(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13487 13488@vindex VICIIFullscreenStatusbar 13489@item VICIIFullscreenStatusbar 13490Boolean specifying whether to show the status bar in fullscreen mode or not 13491(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13492 13493@end table 13494 13495@b{The following resources are only present if the OpenGL library is present and used at compile time.} 13496 13497@table @code 13498 13499@vindex AspectRatio 13500@item AspectRatio 13501String/float specifying the aspect ratio. 13502(0.5-2.0) 13503 13504@vindex SDLGLAspectMode 13505@item SDLGLAspectMode 13506Integer specifying the OpenGL aspect mode. 13507(0: off, 1: custom, 2: true) 13508 13509@vindex SDLGLFlipX 13510@item SDLGLFlipX 13511Boolean to enable/disable OpenGL horizontal screen flip. 13512 13513@vindex SDLGLFlipY 13514@item SDLGLFlipY 13515Boolean to enable/disable OpenGL vertical screen flip. 13516 13517@end table 13518 13519@b{The following resources are only present if the SDL library has joystick support at compile time and applies to all emulators except vsid.} 13520 13521@table @code 13522 13523@vindex JoyMapFile 13524@item JoyMapFile 13525String specifying the name of the joystick map file. 13526 13527@vindex JoyThreshold 13528@item JoyThreshold 13529Integer specifying the joystick threshold. 13530(0..32767) 13531 13532@vindex JoyFuzz 13533@item JoyFuzz 13534Integer specifying the joystick fuzz. 13535(0..32767) 13536 13537@end table 13538 13539@c ----------------------------------------------------------------- 13540@c @node FIXME 13541@subsection SDL specific command-line options 13542 13543@table @code 13544 13545@findex -hotkeyfile 13546@item -hotkeyfile <name> 13547Set the hotkey file name 13548(@code{HotkeyFile}) 13549(all emulators except vsid). 13550 13551@findex -menukey 13552@item -menukey <key> 13553Set the keycode of the SDL menu activation key 13554(@code{MenuKey}). 13555 13556@findex -menukeyup 13557@item -menukeyup <key> 13558Set the keycode of the 'up' key in the SDL menu 13559(@code{MenuKeyUp}). 13560 13561@findex -menukeydown 13562@item -menukeydown <key> 13563Set the keycode of the 'down' key in the SDL menu 13564(@code{MenuKeyDown}). 13565 13566@findex -menukeyleft 13567@item -menukeyleft <key> 13568Set the keycode of the 'left' key in the SDL menu 13569(@code{MenuKeyLeft}). 13570 13571@findex -menukeyright 13572@item -menukeyright <key> 13573Set the keycode of the 'right' key in the SDL menu 13574(@code{MenuKeyRight}). 13575 13576@findex -menukeypageup 13577@item -menukeypageup <key> 13578Set the keycode of the 'page up' key in the SDL menu 13579(@code{MenuKeyPageUp}). 13580 13581@findex -menukeypagedown 13582@item -menukeypagedown <key> 13583Set the keycode of the 'page down' key in the SDL menu 13584(@code{MenuKeyPageDown}). 13585 13586@findex -menukeyhome 13587@item -menukeyhome <key> 13588Set the keycode of the 'home' key in the SDL menu 13589(@code{MenuKeyHome}). 13590 13591@findex -menukeyend 13592@item -menukeyend <key> 13593Set the keycode of the 'end' key in the SDL menu 13594(@code{MenuKeyEnd}). 13595 13596@findex -menukeyselect 13597@item -menukeyselect <key> 13598Set the keycode of the 'select' key in the SDL menu 13599(@code{MenuKeySelect}). 13600 13601@findex -menukeycancel 13602@item -menukeycancel <key> 13603Set the keycode of the 'cancel' key in the SDL menu 13604(@code{MenuKeyCancel}). 13605 13606@findex -menukeyexit 13607@item -menukeyexit <key> 13608Set the keycode of the 'exit' key in the SDL menu 13609(@code{MenuKeyExit}). 13610 13611@findex -menukeymap 13612@item -menukeymap <key> 13613Set the keycode of the 'map' key in the SDL menu 13614(@code{MenuKeyMap}). 13615 13616@findex -saveres, +saveres 13617@item -saveres 13618@itemx +saveres 13619Enable/disable automatic saving of settings on exit 13620(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}). 13621 13622@findex -confirmonexit, +confirmonexit 13623@item -confirmonexit 13624Confirm quitting VICE 13625(@code{ConfirmOnExit=1}). 13626@item +confirmonexit 13627Never confirm quitting VICE 13628(@code{ConfirmOnExit=0}). 13629 13630@findex -pauseonsettings, +pauseonsettings 13631@item -pauseonsettings 13632Pause emulation when enabling the settings dialog. 13633(@code{PauseOnSettings=1}). 13634@item +pauseonsettings 13635Do not pause emulation when enabling the settings dialog. 13636(@code{PauseOnSettings=0}). 13637 13638@findex -statusbar, +statusbar 13639@item -statusbar 13640@itemx +statusbar 13641Enable/disable the statusbar 13642(@code{SDLStatusbar=1}, @code{SDLStatusbar=0}) 13643(all emulators except vsid). 13644 13645@findex -sdlbitdepth 13646@item -sdlbitdepth <bpp> 13647Set the display bitdepth 13648(@code{SDLBitdepth}). 13649(0: current, 8, 15, 16, 24, 32) 13650 13651@findex -sdllimitmode 13652@item -sdllimitmode <mode> 13653Set the resolution limit mode 13654(@code{SDLLimitMode}). 13655(0: off, 1: max, 2: fixed) 13656 13657@findex -sdlcustomw 13658@item -sdlcustomw <width> 13659Set the custom resolution width 13660(@code{SDLCustomWidth}). 13661 13662@findex -sdlcustomh 13663@item -sdlcustomh <height> 13664Set the custom resolution height 13665(@code{SDLCustomHeight}). 13666 13667@findex -sdlinitialw 13668@item -sdlinitialw <width> 13669Set initial window width. 13670 13671@findex -sdlinitialh 13672@item -sdlinitialh <height> 13673Set initial window height. 13674 13675@c Move to generic options 13676@findex -kbdstatusbar, +kbdstatusbar 13677@item -kbdstatusbar 13678@itemx +kbdstatusbar 13679Enable/Disable keyboard-status bar (when status bar is enabled) 13680(@code{KbdStatusbar=1}, @code{KbdStatusbar=0}). 13681 13682@findex -sdlglfilter 13683@item -sdlglfilter <mode> 13684Set OpenGL filtering mode (0 = nearest, 1 = linear) 13685(@code{SDLGLFilter}). 13686 13687@findex -sdl2renderer 13688@item -sdl2renderer <renderer name> 13689Set the preferred SDL2 renderer 13690(@code{SDL2Renderer}). 13691 13692@findex -joydev1 13693@item -joydev1 <0-3> / <0-4> 13694Set the device for joystick emulation of port 1 13695(@code{JoyDevice1}) 13696(all emulators except xcbm2, xpet and vsid). 13697(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13698 13699@findex -joydev2 13700@item -joydev2 <0-3> / <0-4> 13701Set the device for joystick emulation of port 2 13702(@code{JoyDevice2}) 13703(all emulators except xcbm2, xpet, xvic and vsid). 13704(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13705 13706@findex -extrajoydev1 13707@item -extrajoydev1 <0-3> / <0-4> 13708Set device for extra joystick port 1 13709(@code{JoyDevice3}) 13710(all emulators except xcbm5x0 and vsid). 13711(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13712 13713@findex -extrajoydev2 13714@item -extrajoydev2 <0-3> / <0-4> 13715Set device for extra joystick port 2 13716(@code{JoyDevice4}) 13717(all emulators except xcbm5x0, xplus4 and vsid). 13718(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Joystick (only if joystick support was present in the compile time SDL library)) 13719 13720@findex -CRTCSDLfullmode 13721@item -CRTCSDLfullmode <Mode> 13722Set the fullscreen mode 13723(@code{CrtcSDLFullscreenMode}) 13724(xcbm2 and xpet only). 13725 13726@findex -CRTChwscale, +CRTChwscale 13727@item -CRTChwscale 13728@itemx +CRTChwscale 13729Enable/Disable hardware scaling 13730(@code{CrtcHwScale=1}, @code{CrtcHwScale=0}) 13731(xcbm2 and xpet only). 13732 13733@findex -CRTCfulldevice 13734@item -CRTCfulldevice <device> 13735Select fullscreen device 13736(@code{CrtcFullscreenDevice}) 13737(xcbm2 and xpet only). 13738 13739@findex -CRTCfull, +CRTCfull 13740@item -CRTCfull 13741@itemx +CRTCfull 13742Enable/Disable fullscreen 13743(@code{CrtcFullscreen=1}, @code{CrtcFullscreen=0}) 13744(xcbm2 and xpet only). 13745 13746@findex -TEDSDLfullmode 13747@item -TEDSDLfullmode <Mode> 13748Set the fullscreen mode 13749(@code{TEDSDLFullscreenMode}) 13750(xplus4 only). 13751 13752@findex -TEDhwscale, +TEDhwscale 13753@item -TEDhwscale 13754@itemx +TEDhwscale 13755Enable/Disable hardware scaling 13756(@code{TEDHwScale=1}, @code{TEDHwScale=0}) 13757(xplus4 only). 13758 13759@findex -TEDfulldevice 13760@item -TEDfulldevice <device> 13761Select fullscreen device 13762(@code{TEDFullscreenDevice}) 13763(xplus4 only). 13764 13765@findex -TEDfull, +TEDfull 13766@item -TEDfull 13767@itemx +TEDfull 13768Enable/Disable fullscreen 13769(@code{TEDFullscreen=1}, @code{TEDFullscreen=0}) 13770(xplus4 only). 13771 13772@findex -VDCSDLfullmode 13773@item -VDCSDLfullmode <Mode> 13774Set the fullscreen mode 13775(@code{VDCSDLFullscreenMode}) 13776(x128 only). 13777 13778@findex -VDChwscale, +VDChwscale 13779@item -VDChwscale 13780@itemx +VDChwscale 13781Enable/Disable hardware scaling 13782(@code{VDCHwScale=1}, @code{VDCHwScale=1}) 13783(x128 only). 13784 13785@findex -VDCfulldevice 13786@item -VDCfulldevice <device> 13787Select fullscreen device 13788(@code{VDCFullscreenDevice}) 13789(x128 only). 13790 13791@findex -VDCfull, +VDCfull 13792@item -VDCfull 13793@itemx +VDCfull 13794Enable/Disable fullscreen 13795(@code{VDCFullscreen=1}, @code{VDCFullscreen=0}) 13796(x128 only). 13797 13798@findex -VICSDLfullmode 13799@item -VICSDLfullmode <Mode> 13800Set the fullscreen mode 13801(@code{VICSDLFullscreenMode}) 13802(xvic only). 13803 13804@findex -VIChwscale, +VIChwscale 13805@item -VIChwscale 13806@item +VIChwscale 13807Enable/Disable hardware scaling 13808(@code{VICHwScale=1}, @code{VICHwScale=0}) 13809(xvic only). 13810 13811@findex -VICfulldevice 13812@item -VICfulldevice <device> 13813Select fullscreen device 13814(@code{VICFullscreenDevice}) 13815(xvic only). 13816 13817@findex -VICfull, +VICfull 13818@item -VICfull 13819@itemx +VICfull 13820Enable/Disable fullscreen 13821(@code{VICFullscreen=1}, @code{VICFullscreen=0}) 13822(xvic only). 13823 13824@findex -VICIISDLfullmode 13825@item -VICIISDLfullmode <Mode> 13826Set the fullscreen mode 13827(@code{VICIISDLFullscreenMode}) 13828(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13829 13830@findex -VICIIhwscale, +VICIIhwscale 13831@item -VICIIhwscale 13832@itemx +VICIIhwscale 13833Enable/Disable hardware scaling 13834(@code{VICIIHwScale=1}, @code{VICIIHwScale=0}) 13835(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13836 13837@findex -VICIIfulldevice 13838@item -VICIIfulldevice <device> 13839Select fullscreen device 13840(@code{VICIIFullscreenDevice}) 13841(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13842 13843@findex -VICIIfull, +VICIIfull 13844@item -VICIIfull 13845@itemx +VICIIfull 13846Enable/Disable fullscreen 13847(@code{VICIIFullscreen=1}, @code{VICIIFullscreen=0}) 13848(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 13849 13850@end table 13851 13852@b{The following command-line options are only present if the OpenGL library is present and used at compile time.} 13853 13854@table @code 13855 13856@findex -aspect 13857@item -aspect <aspect ratio> 13858Set the aspect ratio 13859(@code{AspectRatio}). 13860(0.5-2.0) 13861 13862@findex -sdlaspectmode 13863@item -sdlaspectmode <mode> 13864Set the aspect mode 13865(@code{SDLGLAspectMode}). 13866(0: off, 1: custom, 2: true) 13867 13868@findex -sdlflipx, +sdlflipx 13869@item -sdlflipx 13870@itemx +sdlflipx 13871Enable/disable OpenGL horizontal screen flip 13872(@code{SDLGLFlipX=1}, @code{SDLGLFlipX=0}). 13873 13874@findex -sdlflipy, +sdlflipy 13875@item -sdlflipy 13876@itemx +sdlflipy 13877Enable/disable OpenGL vertical screen flip 13878(@code{SDLGLFlipY=1}, @code{SDLGLFlipY=0}). 13879 13880@end table 13881 13882@b{The following command-line options are only present if the SDL library has joystick support at compile time and applies 13883to all emulators except vsid.} 13884 13885@table @code 13886 13887@findex -joymap 13888@item -joymap <name> 13889Set the joystick map file name 13890(@code{JoyMapFile}). 13891 13892@findex -joythreshold 13893@item -joythreshold <0-32767> 13894Set the joystick threshold 13895(@code{JoyThreshold}). 13896 13897@findex -joyfuzz 13898@item -joyfuzz <0-32767> 13899Set the joystick fuzz 13900(@code{JoyFuzz}). 13901 13902@end table 13903 13904@end ifset 13905@c end platformsdl 13906@c ----------------------------------------------------------------- 13907 13908@ifset platformgtk3 13909@node GTK3 specific features 13910@section GTK3 specific features 13911 13912This section lists the settings and commands that are common and specific to Unix, and are thus not present in other platforms. 13913 13914@c ----------------------------------------------------------------- 13915@c @node FIXME 13916@subsection GTK3 specific resources 13917 13918@table @code 13919 13920@vindex GTKBackend 13921@item GTKBackend 13922Rendering backend to use for the Gtk3 UI 13923(0: Cairo, 1: OpenGL). 13924 13925@vindex GTKFilter 13926@item GTKFilter 13927Rendering filter to use for the Gtk3 UI 13928(0: Nearest neighbor, 1: Bilinear interpolation). 13929 13930@vindex AspectRatio 13931@item AspectRatio 13932String/float specifying the aspect ratio 13933(0.5-2.0). 13934 13935@vindex KeepAspectRatio 13936@item KeepAspectRatio 13937Boolean specifying whether the aspect ratio of the output window should be preserved. 13938(0: free scaling, 1: scale with fixed aspect ratio) 13939 13940@vindex TrueAspectRatio 13941@item TrueAspectRatio 13942Boolean specifying whether to use the true (non square pixels) aspect ratio. 13943 13944@vindex VSync 13945@item VSync 13946Boolean specifying whether to enable vsync to prevent screen tearing. 13947(0: vsync off, 1: vsync on) 13948 13949@vindex StartMinimized 13950@item StartMinimized 13951Boolean specifying whether the emulator should start minimized 13952 13953@vindex RestoreWindowGeometry 13954@item RestoreWindowGeometry 13955Boolean specifying whether to restore an emulator to its last-saved position and size. 13956 13957@vindex SaveResourcesOnExit 13958@item SaveResourcesOnExit 13959Boolean specifying whether the emulator should save changed settings 13960before exiting. If this is enabled, the user will be always prompted 13961first, in case the settings have changed. 13962 13963@vindex ConfirmOnExit 13964@item ConfirmOnExit 13965Boolean specifying whether to show a confirmation dialog on exit. 13966 13967@vindex DisplayDepth 13968@item DisplayDepth 13969Integer specifying the depth of the host display. The value @samp{0} 13970(the default) causes the emulator to autodetect it 13971(all emulators except vsid). 13972(0..32) 13973 13974@vindex Window0Width 13975@vindex Window0Height 13976@vindex Window0Xpos 13977@vindex Window0Ypos 13978@item Window0Width 13979@itemx Window0Height 13980@itemx Window0Xpos 13981@itemx Window0Ypos 13982Integers specifying the position and size of the (first) emulator window 13983(all emulators except vsid). 13984 13985@vindex Window1Width 13986@vindex Window1Height 13987@vindex Window1Xpos 13988@vindex Window1Ypos 13989@item Window1Width 13990@itemx Window1Height 13991@itemx Window1Xpos 13992@itemx Window1Ypos 13993Integers specifying the position and size of the (second) emulator window 13994(x128 only). 13995 13996@vindex CrtcHwScale 13997@item CrtcHwScale 13998Boolean specifying whether to enable or disable hardware scaling 13999(xcbm2 and xpet only). 14000 14001@vindex CrtcFullscreenDevice 14002@item CrtcFullscreenDevice 14003String specifying the fullscreen device 14004(xcbm2 and xpet only). 14005 14006@vindex CrtcFullscreen 14007@item CrtcFullscreen 14008Boolean specifying whether to use fullscreen mode or not 14009(xcbm2 and xpet only). 14010 14011@vindex CrtcFullscreenStatusbar 14012@item CrtcFullscreenStatusbar 14013Boolean specifying whether to show the status bar in fullscreen mode or not 14014(xcbm2 and xpet only). 14015 14016@vindex TEDHwScale 14017@item TEDHwScale 14018Boolean specifying whether to enable or disable hardware scaling 14019(xplus4 only). 14020 14021@vindex TEDFullscreenDevice 14022@item TEDFullscreenDevice 14023String specifying the fullscreen device 14024(xplus4 only). 14025 14026@vindex TEDFullscreen 14027@item TEDFullscreen 14028Boolean specifying whether to use fullscreen mode or not 14029(xplus4 only). 14030 14031@vindex TEDFullscreenStatusbar 14032@item TEDFullscreenStatusbar 14033Boolean specifying whether to show the status bar in fullscreen mode or not 14034(xplus4 only). 14035 14036@vindex VDCHwScale 14037@item VDCHwScale 14038Boolean specifying whether to enable or disable hardware scaling 14039(x128 only). 14040 14041@vindex VDCFullscreenDevice 14042@item VDCFullscreenDevice 14043String specifying the fullscreen device 14044(x128 only). 14045 14046@vindex VDCFullscreen 14047@item VDCFullscreen 14048Boolean specifying whether to use fullscreen mode or not 14049(x128 only). 14050 14051@vindex VDCFullscreenStatusbar 14052@item VDCFullscreenStatusbar 14053Boolean specifying whether to show the status bar in fullscreen mode or not 14054(x128 only). 14055 14056@vindex VICHwScale 14057@item VICHwScale 14058Boolean specifying whether to enable or disable hardware scaling 14059(xvic only). 14060 14061@vindex VICFullscreenDevice 14062@item VICFullscreenDevice 14063String specifying the fullscreen device 14064(xvic only). 14065 14066@vindex VICFullscreen 14067@item VICFullscreen 14068Boolean specifying whether to use fullscreen mode or not 14069(xvic only). 14070 14071@vindex VICFullscreenStatusbar 14072@item VICFullscreenStatusbar 14073Boolean specifying whether to show the status bar in fullscreen mode or not 14074(xvic only). 14075 14076@vindex VICIIHwScale 14077@item VICIIHwScale 14078Boolean specifying whether to enable or disable hardware scaling 14079(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 14080 14081@vindex VICIIFullscreenDevice 14082@item VICIIFullscreenDevice 14083String specifying the fullscreen device 14084(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 14085 14086@vindex VICIIFullscreen 14087@item VICIIFullscreen 14088Boolean specifying whether to use fullscreen mode or not 14089(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 14090 14091@vindex VICIIFullscreenStatusbar 14092@item VICIIFullscreenStatusbar 14093Boolean specifying whether to show the status bar in fullscreen mode or not 14094(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 14095 14096@vindex JoyDevice1 14097@item JoyDevice1 14098Integer specifying which joystick device the emulator should use for the emulation of joystick 1 14099(all emulators except xcbm2, xpet and vsid). 14100(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14101 14102@vindex JoyDevice2 14103@item JoyDevice2 14104Integer specifying which joystick device the emulator should use for the emulation of joystick 2 14105(all emulators except xcbm2, xpet, xvic and vsid). 14106(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14107 14108@vindex JoyDevice3 14109@item JoyDevice3 14110Integer specifying which joystick device the emulator should use for the emulation of extra joystick 1 14111(all emulators except xcbm5x0 and vsid). 14112(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14113 14114@vindex JoyDevice4 14115@item JoyDevice4 14116Integer specifying which joystick device the emulator should use for the emulation of extra joystick 2 14117(all emulators except xcbm5x0, xplus4 and vsid). 14118(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14119 14120@end table 14121 14122@b{The available joysticks might differ depending on operating system and joystick support in the OS.} 14123 14124@table @code 14125 14126@item Devices 4..9 14127Only available if joystick support is available at compile time. 14128 14129@item Devices 10 and 11 14130Only available if digital joystick support is available at compile time. 14131 14132@item Devices 12 and 13 14133Only available if USB joystick support is available at compile time. 14134 14135@end table 14136 14137@b{The following resources are only available if MIDI support is available at compile time.} 14138 14139@table @code 14140 14141@vindex MIDIInDev 14142@item MIDIInDev 14143String specifying the MIDI input device 14144(x64, x64sc, xscpu64, x128 and xvic only). 14145 14146@vindex MIDIOutDev 14147@item MIDIOutDev 14148String specifying the MIDI output device 14149(x64, x64sc, xscpu64, x128 and xvic only). 14150 14151@end table 14152 14153@b{The following resource is only available if MIDI support and ALSA support is available at compile time.} 14154 14155@table @code 14156 14157@vindex MIDIDriver 14158@item MIDIDriver 14159Enum specifying the MIDI driver 14160(x64, x64sc, xscpu64, x128 and xvic only). 14161(0: OSS, 1: ALSA) 14162 14163@end table 14164 14165@c @node FIXME 14166@subsection GTK3 specific command-line options 14167 14168@table @code 14169 14170@findex -saveres, +saveres 14171@item -saveres 14172@itemx +saveres 14173Enable/disable automatic saving of settings on exit 14174(@code{SaveResourcesOnExit=1}, @code{SaveResourcesOnExit=0}). 14175 14176@findex -minimized, +minimized 14177@item -minimized 14178@itemx +minimized 14179Start/Do not start with minimized window 14180(@code{StartMinimized=1}, @code{StartMinimized=0}). 14181 14182@findex -restore-window-geometry, +restore-window-geometry 14183@item -restore-window-geometry 14184@itemx +restore-window-geometry 14185Restore/ignore Window position(s) and dimension(s) stored in vicerc 14186(@code{RestoreWindowGeometry=1}, @code{RestoreWindowGeometry=0}). 14187 14188@findex -aspect 14189@item -aspect <aspect ratio> 14190Set the aspect ratio 14191(@code{AspectRatio}). 14192(0.5-2.0) 14193 14194@findex -gtkbackend 14195@item -gtkbackend <backend> 14196Set the Gtk3 rendering backend 14197(@code{GTKBackend}) 14198(0: Cairo, 1: OpenGL) 14199 14200@findex -gtkfilter 14201@item -gtkfilter <filter> 14202(@code{GTKFilter}) 14203(0: Nearest neighbor, 1: Bilinear interpolation) 14204 14205@findex -keepaspect, +keepaspect 14206@item -keepaspect 14207Enable keeping of the aspect ratio when scaling 14208(@code{KeepAspectRatio=1}). 14209@item +keepaspect 14210Disable keeping of the aspect ratio when scaling (freescaling) 14211(@code{KeepAspectRatio=0}). 14212 14213@findex -trueaspect, +trueaspect 14214@item -trueaspect 14215@itemx +trueaspect 14216Enable/disable whether to use the true (non square pixels) aspect ratio 14217(@code{TrueAspectRatio=1}, (@code{TrueAspectRatio=0}). 14218 14219@findex -vsync, +vsync 14220@item -vsync 14221Enable vsync to prevent screen tearing 14222(@code{VSync=1}). 14223@item +vsync 14224Disable vsync to allow screen tearing 14225(@code{VSync=0}). 14226 14227@findex -confirmonexit, +confirmonexit 14228@item -confirmonexit 14229Confirm quitting VICE 14230(@code{ConfirmOnExit=1}). 14231@item +confirmonexit 14232Never confirm quitting VICE 14233(@code{ConfirmOnExit=0}). 14234 14235@findex -fullscreen, +fullscreen 14236@item -fullscreen 14237@itemx +fullscreen 14238Enable/disable fullscreen mode 14239(@code{UseFullscreen=1}, (@code{UseFullscreen=0}) 14240(all emulators except vsid). 14241 14242@findex -CRTChwscale, +CRTChwscale 14243@item -CRTChwscale 14244@itemx +CRTChwscale 14245Enable/Disable hardware scaling 14246(@code{CrtcHwScale=1}, @code{CrtcHwScale=0}) 14247(xcbm2 and xpet only). 14248 14249@findex -CRTCfulldevice 14250@item -CRTCfulldevice <device> 14251Select fullscreen device 14252(@code{CrtcFullscreenDevice}) 14253(xcbm2 and xpet only). 14254 14255@findex -TEDhwscale, +TEDhwscale 14256@item -TEDhwscale 14257@itemx +TEDhwscale 14258Enable/Disable hardware scaling 14259(@code{TEDHwScale=1}, @code{TEDHwScale=0}) 14260(xplus4 only). 14261 14262@findex -TEDfulldevice 14263@item -TEDfulldevice <device> 14264Select fullscreen device 14265(@code{TEDFullscreenDevice}) 14266(xplus4 only). 14267 14268@findex -VDChwscale, +VDChwscale 14269@item -VDChwscale 14270@itemx +VDChwscale 14271Enable/Disable hardware scaling 14272(@code{VDCHwScale=1}, @code{VDCHwScale=1}) 14273(x128 only). 14274 14275@findex -VIChwscale, +VIChwscale 14276@item -VIChwscale 14277@item +VIChwscale 14278Enable/Disable hardware scaling 14279(@code{VICHwScale=1}, @code{VICHwScale=0}) 14280(xvic only). 14281 14282@findex -VICfulldevice 14283@item -VICfulldevice <device> 14284Select fullscreen device 14285(@code{VICFullscreenDevice}) 14286(xvic only). 14287 14288@findex -VICIIhwscale, +VICIIhwscale 14289@item -VICIIhwscale 14290@itemx +VICIIhwscale 14291Enable/Disable hardware scaling 14292(@code{VICIIHwScale=1}, @code{VICIIHwScale=0}) 14293(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 14294 14295@findex -VICIIfulldevice 14296@item -VICIIfulldevice <device> 14297Select fullscreen device 14298(@code{VICIIFullscreenDevice}) 14299(all emulators except xcbm2, xpet, xplus4, xvic and vsid). 14300 14301@findex -joydev1 14302@item -joydev1 <0-3> / <0-9> / <0-11> / <0-13> 14303Set the device for joystick emulation of port 1 14304(@code{JoyDevice1}) 14305(all emulators except xcbm2, xpet and vsid). 14306(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14307 14308@findex -joydev2 14309@item -joydev2 <0-3> / <0-9> / <0-11> / <0-13> 14310Set the device for joystick emulation of port 2 14311(@code{JoyDevice2}) 14312(all emulators except xcbm2, xpet, xvic and vsid). 14313(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14314 14315@findex -extrajoydev1 14316@item -extrajoydev1 <0-3> / <0-9> / <0-11> / <0-13> 14317Set device for extra joystick port 1 14318(@code{JoyDevice3}) 14319(all emulators except xcbm5x0 and vsid). 14320(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14321 14322@findex -extrajoydev2 14323@item -extrajoydev2 <0-3> / <0-9> / <0-11> / <0-13> 14324Set device for extra joystick port 2 14325(@code{JoyDevice4}) 14326(all emulators except xcbm5x0, xplus4 and vsid). 14327(0: None, 1: Numpad, 2: Keyset 1, 3: Keyset 2, 4: Analog joystick 1, 5: Analog joystick 2, 6: Analog joystick 3, 7: Analog joystick 4, 8: Analog joystick 5, 9: Analog joystick 6, 10: Digital joystick 1, 11: Digital joystick 2, 12: USB joystick 1, 13: USB joystick 2) 14328 14329@end table 14330 14331@b{The available joysticks might differ depending on operating system and joystick support in the OS.} 14332 14333@table @code 14334 14335@item Devices 4..9 14336Only available if joystick support is available at compile time. 14337 14338@item Devices 10 and 11 14339Only available if digital joystick support is available at compile time. 14340 14341@item Devices 12 and 13 14342Only available if USB joystick support is available at compile time. 14343 14344@end table 14345 14346@b{The following command-line options are only available if MIDI support is available at compile time.} 14347 14348@table @code 14349 14350@findex -midiin 14351@item -midiin <name> 14352Specify MIDI-In device 14353(@code{MIDIInDev}) 14354(x64, x64sc, xscpu64, x128 and xvic only). 14355 14356@findex -midiout 14357@item -midiout <name> 14358Specify MIDI-Out device 14359(@code{MIDIOutDev}) 14360(x64, x64sc, xscpu64, x128 and xvic only). 14361 14362@end table 14363 14364@b{The following command-line option is only available if MIDI support and ALSA support is available at compile time.} 14365 14366@table @code 14367 14368@findex -mididrv 14369@item -mididrv <driver> 14370Specify MIDI driver 14371(@code{MIDIDriver}) 14372(x64, x64sc, xscpu64, x128 and xvic only). 14373(0: OSS, 1: ALSA) 14374 14375@end table 14376 14377@end ifset 14378@c platformunix 14379 14380@c ----------------------------------------------------------------- 14381 14382@node Snapshots 14383@chapter Snapshots 14384 14385Every VICE emulator has a built-in snapshot feature, that saves the 14386complete emulator state into one file for later use. 14387You can therefore save the emulator state - including the state of 14388the game you are playing for example - in a single file. 14389 14390Important note: In the past the idea was that snapshots with the same major 14391version can be exchanged with later versions of the emulator. However, this 14392proved to be too difficult to maintain, and insanely hard to test for 14393correctness, which is why now the emulator will reject the snapshot when it 14394finds a module that is too old. @b{Because of this you should not use snapshots 14395for permanent/long term storage.} 14396 14397@menu 14398* Snapshot usage:: 14399* Snapshot format:: 14400@end menu 14401 14402@node Snapshot usage, Snapshot format, Snapshots, Snapshots 14403@section Snapshot usage 14404 14405A snapshot is one file containining the complete emulator state. A 14406snapshot file can be generated by selecting the ``Save snapshot'' 14407command at any time. This will pop up a requester from which you can 14408specify whether the snapshot should also contain the disk and ROM 14409status. 14410 14411A snapshot file can be used to restore the emulator state by selecting 14412the @code{load snapshot} menu entry at any time. 14413Unfortunately attached ROM images/cartridges are only supported in the VIC20, 14414the PET and the CBM-II emulators at this time. 14415 14416The memory configuration of the emulator is saved in the snapshot file as 14417well. This configuration is restored when the snapshot is loaded. 14418 14419A quick snapshot can now be made by pressing the @code{M-F11} key and 14420reloaded by pressing the @code{M-F10} key. 14421 14422@node Snapshot format, , Snapshot usage, Snapshots 14423@section Snapshot format 14424 14425A snapshot file consists of several modules of mostly different types. 14426Each module has a name and saves the state of an entity like a CIA, the CPU, 14427or the memory. 14428 14429@menu 14430* Emulator modules:: 14431* Module formats:: 14432@end menu 14433 14434@node Emulator modules, Module formats, Snapshot format, Snapshot format 14435@subsection Emulator modules 14436 14437This section lists the modules that are contained in each of the 14438emulators snapshot files. 14439 14440@menu 14441* x64 modules:: 14442* x128 modules:: 14443* xvic modules:: 14444* xpet modules:: 14445* xcbm2 and xcbm5x0 modules:: 14446* Drive modules:: 14447@end menu 14448 14449@node x64 modules, x128 modules, Emulator modules, Emulator modules 14450@subsubsection x64 modules 14451 14452The modules in the x64 emulator are: 14453 14454@multitable @columnfractions .1 .4 .5 14455@item Name 14456@tab Type 14457@tab Description 14458@item MAINCPU 14459@tab 6502 14460@tab The Main CPU - although it is a 6510, only the 6502 core is saved here 14461@item C64MEM 14462@tab Memory 14463@tab Holds the RAM contents of the C64. Also the CPU I/O register contents are saved here. 14464@item C64ROM 14465@tab ROM images 14466@tab Dump of the system ROMs 14467@item VIC-II 14468@tab 656* 14469@tab The VIC-II of the C64/128 14470@item CIA1 14471@tab 6526 14472@tab The CIA for the interrupts and the keyboard 14473@item CIA2 14474@tab 6526 14475@tab The CIA for the userport, IEC-bus and RS232. 14476@item SID 14477@tab 6581 14478@tab The SID sound chip of the C64/C128 14479@item REU* 14480@tab 14481@tab The RAM Extension Unit state (optional) 14482@item ACIA1 14483@tab 6551 14484@tab An ACIA (RS232 interface) at $DE00 (optional) 14485@item TPI 14486@tab 6525 14487@tab A TPI at $DF00 for a parallel IEEE488 interface (optional) 14488@item * 14489@tab Drive modules 14490@tab The emulated drive(s) have their own modules @pxref{Drive modules} 14491@end multitable 14492 14493Some of the modules are optional and are only saved if the specific 14494feature is enabled at save-time. If the module is found when restoring 14495the state the optional features are enabled, and disabled otherwise. 14496 14497@node x128 modules, xvic modules, x64 modules, Emulator modules 14498@subsubsection x128 modules 14499 14500The modules in the x128 emulator are: 14501 14502@multitable @columnfractions .1 .4 .5 14503@item Name 14504@tab Type 14505@tab Description 14506@item MAINCPU 14507@tab 6502 14508@tab The Main CPU - although it is a 6510, only the 6502 core is saved here 14509@item C128MEM 14510@tab Memory 14511@tab Holds the RAM contents of the C64. Also the CPU I/O register contents are saved here. 14512@item C128ROM 14513@tab ROM images 14514@tab Dump of the system ROMs 14515@item VIC-II 14516@tab 656* 14517@tab The VIC-II of the C64/128 14518@item CIA1 14519@tab 6526 14520@tab The CIA for the interrupts and the keyboard 14521@item CIA2 14522@tab 6526 14523@tab The CIA for the userport, IEC-bus and RS232. 14524@item SID 14525@tab 6581 14526@tab The SID sound chip of the C64/C128 14527@item ACIA1 14528@tab 6551 14529@tab An ACIA at $DE00 (optional) 14530@item TPI 14531@tab 6525 14532@tab A TPI at $DF00 for a parallel IEEE488 interface (optional) 14533@item * 14534@tab Drive modules 14535@tab The emulated drive(s) have their own modules @pxref{Drive modules} 14536@end multitable 14537 14538Some of the modules are optional and are only saved if the specific 14539feature is enabled at save-time. If the module is found when restoring 14540the state the optional features are enabled, and disabled otherwise. 14541 14542Not yet supported are the 80 column video chip, cartridges and 14543RAM expansion unit. 14544 14545@node xvic modules, xpet modules, x128 modules, Emulator modules 14546@subsubsection xvic modules 14547 14548The modules in the xvic emulator are: 14549 14550@multitable @columnfractions .1 .4 .5 14551@item Name 14552@tab Type 14553@tab Description 14554@item MAINCPU 14555@tab 6502 14556@tab The Main CPU 14557@item VIC20MEM 14558@tab Memory 14559@tab Holds the RAM contents of the VIC20. 14560@item VIC20ROM 14561@tab ROM images 14562@tab Holds the ROM images of the VIC20, including possibly attached cartridges 14563@item VIC-I 14564@tab 656* 14565@tab The VIC-I of the VIC20 14566@item VIA1 14567@tab 6522 14568@tab The VIA for the interrupts and the keyboard 14569@item VIA2 14570@tab 6522 14571@tab The VIA for the userport, IEC-bus and RS232. 14572@item * 14573@tab Drive modules 14574@tab The emulated drive(s) have their own modules @pxref{Drive modules} 14575@end multitable 14576 14577@node xpet modules, xcbm2 and xcbm5x0 modules, xvic modules, Emulator modules 14578@subsubsection xpet modules 14579 14580The modules in the xpet emulator are: 14581 14582@multitable @columnfractions .1 .4 .5 14583@item Name 14584@tab Type 14585@tab Description 14586@item MAINCPU 14587@tab 6502 14588@tab The Main CPU 14589@item PETMEM 14590@tab Memory 14591@tab Holds the RAM contents of the PET. 14592@item PETROM 14593@tab ROM images 14594@tab Holds the ROM images of the PET, including possibly attached cartridges 14595@item CRTC 14596@tab 6545 14597@tab The CRTC of the PET. This is also included if it is a dump of a PET without CRTC, because the video state is saved here anyway. 14598@item PIA1 14599@tab 6520 14600@tab The PIA for the interrupts, tape and the keyboard 14601@item PIA2 14602@tab 6520 14603@tab The PIA for the IEEE488-bus 14604@item VIA 14605@tab 6522 14606@tab The VIA for IEEE488, userport, sound 14607@item ACIA1 14608@tab 6551 14609@tab The ACIA for the SuperPET. This module is optional. 14610@item DWWPIA 14611@tab 6520 14612@tab The PIA for the DWW hires board. 14613@item CPU6809 14614@tab 6809 14615@tab The extra CPU in the SuperPET. This module is optional. 14616@item * 14617@tab Drive modules 14618@tab The emulated drive(s) have their own modules @pxref{Drive modules} 14619@end multitable 14620 14621@node xcbm2 and xcbm5x0 modules, Drive modules, xpet modules, Emulator modules 14622@subsubsection xcbm2 and xcbm5x0 modules 14623 14624The modules in the xcbm2 and xcbm5x0 emulators are: 14625 14626@multitable @columnfractions .1 .4 .5 14627@item Name 14628@tab Type 14629@tab Description 14630@item MAINCPU 14631@tab 6502 14632@tab The Main CPU - although it is a 6509, only the 6502 core is saved here 14633@item CBM2MEM 14634@tab Memory 14635@tab Holds the RAM contents of the CBM-II models. Also holds the exec-bank and indirection bank registers 14636@item C500DATA 14637@tab 14638@tab Holds additional state information necessary for the C500 (e.g. cycles till the next IRQ) 14639@item CBM2ROM 14640@tab Memory 14641@tab optional. Holds the ROM images. 14642@item CRTC 14643@tab 6545 14644@tab The video chip for the C6*0 and C7*0 models (only those models). 14645@item VIC-II 14646@tab 656? 14647@tab The video chip for the C5*0 models (only the C5*0 models). 14648@item CIA1 14649@tab 6526 14650@tab The CIA for IEEE 488 and userport. 14651@item TPI1 14652@tab 6525 14653@tab TPI 1 for IEEE488 14654@item TPI2 14655@tab 6525 14656@tab TPI 2 for interrupts and keyboard. 14657@item ACIA1 14658@tab 6551 14659@tab The RS232 interface 14660@item SID 14661@tab 6581 14662@tab The CBM2s SID sound chip 14663@item * 14664@tab Drive modules 14665@tab The emulated drive(s) have their own modules @pxref{Drive modules} 14666@end multitable 14667 14668@node Drive modules, , xcbm2 and xcbm5x0 modules, Emulator modules 14669@subsubsection Drive modules 14670 14671The modules for the real disk drive emulation are included in the emulator 14672when the emulation is enabled during the writing of the snapshot. 14673 14674@multitable @columnfractions .1 .4 .5 14675@item Name 14676@tab Type 14677@tab Description 14678@item *CPU 14679@tab 6502 14680@tab The Drive 0 CPU 14681@item * 14682@tab * 14683@tab * 14684@end multitable 14685 14686@node Module formats, , Emulator modules, Snapshot format 14687@subsection Module formats 14688 14689This section shows the basic module framework and the contents of the 14690different types of modules. 14691 14692The single chip modules contain the @b{chip} state, and sometimes additional 14693state of the emulator. In the past we tried to make the format as 14694implementation-independent as possible, to allow reuse of snapshots in later 14695versions of the emulator, that however proved to be very impractical and 14696insanely hard to maintain. 14697 14698@menu 14699* Module Terminology:: 14700* Module framework:: 14701* CPU 6502 module:: 14702* CPU 6809 module:: 14703* CIA 6526 module:: 14704* VIA 6522 module:: 14705* PIA 6520 module:: 14706* TPI 6525 module:: 14707* RIOT 6532 module:: 14708* SID 6581 module:: 14709* ACIA 6551 module:: 14710* VIC-I module:: 14711* VIC-II module:: 14712* CRTC module:: 14713* C64 memory module:: 14714* C128 memory module:: 14715* VIC20 memory module:: 14716* PET memory module:: 14717* CBM-II memory module:: 14718* C500 data module:: 14719@end menu 14720 14721@node Module Terminology, Module framework, Module formats, Module formats 14722@subsubsection Terminology 14723 14724In this section we use certain abbreviations to define the types of the 14725data saved in the snapshot. 14726 14727@table @code 14728@item BYTE 147298 bit integer. 14730@item WORD 1473116 bit integer. Saved with low-byte first, high-byte last. 14732@item DWORD 1473332 bit integer. Saved with low-word first, then high-word. Each word saved with its low-byte first. 14734@item ARRAY 14735Array of BYTE values. Length depends on the description. 14736@end table 14737 14738The tables for the single modules state the type, name and description 14739of the data saved in the modules. The data is saved in the order it is 14740in the tables, so no offset is given. 14741 14742@node Module framework, CPU 6502 module, Module Terminology, Module formats 14743@subsubsection Module framework 14744 14745The VICE snapshot file starts with the magic string and includes the 14746fileformat version number. 14747 14748@multitable @columnfractions .2 .3 .5 14749@item Type 14750@tab Name 14751@tab Description 14752@item 19 BYTE 14753@tab MAGIC 14754@tab "VICE Snapshot File\032", padded with 0 14755@item BYTE 14756@tab VMAJOR 14757@tab fileformat major version number 14758@item BYTE 14759@tab VMINOR 14760@tab fileformat minor version number 14761@item 16 BYTE 14762@tab MACHINENAME 14763@tab Name of emulated machine, like "PET", "CBM-II", "VIC20", "C64" or "C128". zerobyte-padded. 14764@item 13 BYTE 14765@tab VERSION MAGIC 14766@tab "VICE Version\032", padded with 0 14767@item 4 BYTE 14768@tab VERSION 14769@tab Release version (major, minor, micro). Byte 4 is always zero. 14770@item DWORD 14771@tab SVNVERSION 14772@tab SVN revision (or 0 if not available) 14773@end multitable 14774 14775The file header is followed by a number of different snapshot modules. 14776 14777Each module has a header with the information given in the table below. 14778The header includes two version numbers, VMAJOR and VMINOR. In the past the 14779idea was that modules with the same VMAJOR should be able to be exchanged. This 14780however proved to be too difficult to maintain, and insanely hard to test for 14781correctness, which is why now the emulator will reject the snapshot when it 14782finds a module that is too old. @b{Because of this you should not use snapshots 14783for permanent/long term storage.} 14784 14785@multitable @columnfractions .1 .4 .5 14786@item Type 14787@tab Name 14788@tab Description 14789@item 16 BYTE 14790@tab MODULENAME 14791@tab The name of the module in ASCII, padded with 0 to 16 byte. 14792@item BYTE 14793@tab VMAJOR 14794@tab major version number 14795@item BYTE 14796@tab VMINOR 14797@tab minor version number 14798@item DWORD 14799@tab SIZE 14800@tab size of the module, including this header 14801@end multitable 14802 14803@node CPU 6502 module, CPU 6809 module, Module framework, Module formats 14804@subsubsection CPU 6502 module 14805 14806This module saves the core 6502 state. You will find a clock value 14807there. All other modules save their own clock values relative to this 14808value. However, the drive modules save their clocks relative to their 14809appropriate CPUs of course. 14810 14811@multitable @columnfractions .1 .4 .5 14812@item Type 14813@tab Name 14814@tab Description 14815@item DWORD 14816@tab CLK 14817@tab the current CPU clock value. All other clock values are relative to this. 14818@item BYTE 14819@tab AC 14820@tab Accumulator 14821@item BYTE 14822@tab XR 14823@tab X index register 14824@item BYTE 14825@tab YR 14826@tab Y index register 14827@item BYTE 14828@tab SP 14829@tab Stack Pointer 14830@item WORD 14831@tab PC 14832@tab Programm Counter 14833@item BYTE 14834@tab ST 14835@tab Status Registers 14836@item DWORD 14837@tab LASTOPCODE 14838@tab ? 14839@item DWORD 14840@tab IRQCLK 14841@tab absolute CLK when the IRQ line came active 14842@item DOWRD 14843@tab NMICLK 14844@tab absolute CLK when the NMI line came active 14845@item DWORD 14846@tab ? 14847@tab ? 14848@item DWORD 14849@tab ? 14850@tab ? 14851@end multitable 14852 14853 14854@node CPU 6809 module, CIA 6526 module, CPU 6502 module, Module formats 14855@subsubsection CPU 6809 module 14856 14857This module saves the core 6809 state. You will find a clock value 14858there. All other modules save their own clock values relative to this 14859value. However, the drive modules save their clocks relative to their 14860appropriate CPUs of course. 14861 14862@multitable @columnfractions .1 .4 .5 14863@item Type 14864@tab Name 14865@tab Description 14866@item DWORD 14867@tab CLK 14868@tab the current CPU clock value. All other clock values are relative to this. 14869@item WORD 14870@tab X 14871@tab The X register 14872@item WORD 14873@tab Y 14874@tab The Y register 14875@item WORD 14876@tab U 14877@tab The U register 14878@item WORD 14879@tab PC 14880@tab The Program Counter register 14881@item BYTE 14882@tab DP 14883@tab The Direct Page register 14884@item BYTE 14885@tab CC 14886@tab The Condition Code register 14887@item BYTE 14888@tab A 14889@tab The A register 14890@item BYTE 14891@tab B 14892@tab The B register 14893@item 14894@tab 14895@tab The following are for 6309 compatibility: 14896@item WORD 14897@tab V 14898@tab The V register 14899@item BYTE 14900@tab E 14901@tab The E register 14902@item BYTE 14903@tab F 14904@tab The F register 14905@end multitable 14906 14907@node CIA 6526 module, VIA 6522 module, CPU 6809 module, Module formats 14908@subsubsection CIA module 14909 14910The CIA 6526 is an I/O port chip with 2 8-bit I/O ports, a shift register, 14911two timers, a Time of Day clock and interrupts. 14912 14913Version numbers: Major 1, Minor 1. 14914 14915@multitable @columnfractions .1 .4 .5 14916@item Type 14917@tab Name 14918@tab Description 14919@item BYTE 14920@tab ORA 14921@tab Output register A 14922@item BYTE 14923@tab ORB 14924@tab Output register B 14925@item BYTE 14926@tab DDRA 14927@tab Data direction register A 14928@item BYTE 14929@tab DDRB 14930@tab Data direction register B 14931@item WORD 14932@tab TAC 14933@tab Timer A counter value 14934@item WORD 14935@tab TBC 14936@tab Timer B counter value 14937@item BYTE 14938@tab TOD_TEN 14939@tab Time of Day - current tenth of second 14940@item BYTE 14941@tab TOD_SEC 14942@tab Time of Day - current seconds 14943@item BYTE 14944@tab TOD_MIN 14945@tab Time of Day - current minutes 14946@item BYTE 14947@tab TOD_HR 14948@tab Time of Day - current hours 14949@item BYTE 14950@tab SDR 14951@tab contents of shift register 14952@item BYTE 14953@tab IER 14954@tab mask of enabled interrupt masks 14955@item BYTE 14956@tab CRA 14957@tab Control register A 14958@item BYTE 14959@tab CRB 14960@tab Control register B 14961@item WORD 14962@tab TAL 14963@tab Timer A latch value 14964@item WORD 14965@tab TBL 14966@tab Timer B latch value 14967@item BYTE 14968@tab IFR 14969@tab mask of currently active interrupts 14970@item BYTE 14971@tab PBSTATE 14972@tab Bit 6/7 reflect the PB6/7 toggle bit state. Bit 2/3 reflect the corresponding port bit state. 14973@item BYTE 14974@tab SRHBITS 14975@tab number of half-bits to still shift in/out SDR 14976@item BYTE 14977@tab ALARM_TEN 14978@tab Time of Day - alarm tenth of second 14979@item BYTE 14980@tab ALARM_SEC 14981@tab Time of Day - alarm seconds 14982@item BYTE 14983@tab ALARM_MIN 14984@tab Time of Day - alarm minutes 14985@item BYTE 14986@tab ALARM_HR 14987@tab Time of Day - alarm hours 14988@item BYTE 14989@tab READICR 14990@tab current clock minus the clock when ICR was read last plus 128. 14991@item BYTE 14992@tab TODLATCHED 14993@tab Bit 0: 1= latched for reading, Bit 1: 2=stopped for writing 14994@item BYTE 14995@tab TODL_TEN 14996@tab Time of Day - latched tenth of second 14997@item BYTE 14998@tab TODL_SEC 14999@tab Time of Day - latched seconds 15000@item BYTE 15001@tab TODL_MIN 15002@tab Time of Day - latched minutes 15003@item BYTE 15004@tab TODL_HR 15005@tab Time of Day - latched hours 15006@item DWORD 15007@tab TOD_TICKS 15008@tab clk ticks till next tenth of second 15009@item -- 15010@tab -- 15011@tab The next items have been added in V1.1 15012@item WORD 15013@tab TASTATE 15014@tab The state bits of the CIA timer A, according to ciatimer.h 15015@item WORD 15016@tab TBSTATE 15017@tab The state bits of the CIA timer B, according to ciatimer.h 15018@end multitable 15019 15020The last two items have been added in CIA snapshot version 1.1 due 15021to the improved CIA emulation in the newer VICE versions. 15022Some state bits correspond to the CIA state as described in the 15023"A Software Model of the CIA 6526" document by Wolfgang Lorenz, 15024some are delayed versions. For more read the source file 15025@code{ciatimer.h}. 15026 15027@node VIA 6522 module, PIA 6520 module, CIA 6526 module, Module formats 15028@subsubsection VIA module 15029 15030The VIA 6522 is the predecessor of the CIA and also an I/O port chip 15031with 2 8-bit I/O ports, a shift register, 15032two timers and interrupts. 15033 15034Version numbers: Major 1, Minor 0. 15035 15036@multitable @columnfractions .1 .4 .5 15037@item Type 15038@tab Name 15039@tab Description 15040@item BYTE 15041@tab ORA 15042@tab Output register A 15043@item BYTE 15044@tab DDRA 15045@tab Data direction register A 15046@item BYTE 15047@tab ORB 15048@tab Output register B 15049@item BYTE 15050@tab DDRB 15051@tab Data direction register B 15052@item WORD 15053@tab T1L 15054@tab Timer 1 Latch value 15055@item WORD 15056@tab T1C 15057@tab Timer 1 counter value 15058@item BYTE 15059@tab T2L 15060@tab Timer 2 latch (8 bit as only lower byte is used) 15061@item WORD 15062@tab T2C 15063@tab Timer 2 counter value 15064@item BYTE 15065@tab RUNFL 15066@tab bit 7: timer 1 will generate IRQ on underflow; bit 6: timer 2 will generate IRQ on underflow 15067@item BYTE 15068@tab SR 15069@tab Shift register value 15070@item BYTE 15071@tab ACR 15072@tab Auxiliary control register 15073@item BYTE 15074@tab PCR 15075@tab Peripheral control register 15076@item BYTE 15077@tab IFR 15078@tab active interrupts 15079@item BYTE 15080@tab IER 15081@tab interrupt mask 15082@item BYTE 15083@tab PB7 15084@tab bit 7 = pb7 state 15085@item BYTE 15086@tab SRHBITS 15087@tab number of half-bits to shift out on SR 15088@item BYTE 15089@tab CABSTATE 15090@tab bit 7: state of CA2 pin, bit 6: state of CB2 pin 15091@item BYTE 15092@tab ILA 15093@tab Port A Input Latch (see ACR bit 0) 15094@item BYTE 15095@tab ILB 15096@tab Port B Input Latch (see ACR bit 1) 15097@end multitable 15098 15099@node PIA 6520 module, TPI 6525 module, VIA 6522 module, Module formats 15100@subsubsection PIA module 15101 15102The PIA 6520 is a chip with two I/O ports (Parallel Interface Adapter) 15103and four additional handshake lines. The chip is pretty the same for 15104Port A and B, only that Port A implements handshake on read operation 15105and port B on write operation. 15106 15107Version numbers: Major 1, Minor 0. 15108 15109@multitable @columnfractions .1 .4 .5 15110@item Type 15111@tab Name 15112@tab Description 15113@item UBYTE 15114@tab ORA 15115@tab Output register A 15116@item UBYTE 15117@tab DDRA 15118@tab Data Direction Register A 15119@item UBYTE 15120@tab CTRLA 15121@tab Control Register A 15122@item UBYTE 15123@tab ORB 15124@tab Output register B 15125@item UBYTE 15126@tab DDRB 15127@tab Data Direction Register B 15128@item UBYTE 15129@tab CTRLB 15130@tab Control Register B 15131@item UBYTE 15132@tab CABSTATE 15133@tab Bit 7 = state of CA2, Bit 6 = state of CB2 15134@end multitable 15135 15136@node TPI 6525 module, RIOT 6532 module, PIA 6520 module, Module formats 15137@subsubsection TPI module 15138 15139The TPI 6525 is a chip with three I/O ports (Tri-Port-Interface). One of 15140the ports can double as an interrupt prioritizer. Therefore we also have 15141to save the states of the interrupt stack etc. 15142 15143Version numbers: Major 1, Minor 0. 15144 15145@multitable @columnfractions .1 .4 .5 15146@item Type 15147@tab Name 15148@tab Description 15149@item BYTE 15150@tab PRA 15151@tab Port A output register 15152@item BYTE 15153@tab PRB 15154@tab Port B output register 15155@item BYTE 15156@tab PRC 15157@tab Port C output register (doubles as IRQ latch register) 15158@item BYTE 15159@tab DDRA 15160@tab Port A data direction register 15161@item BYTE 15162@tab DDRB 15163@tab Port B data direction register 15164@item BYTE 15165@tab DDRC 15166@tab Port C data direction register (doubles as IRQ mask register) 15167@item BYTE 15168@tab CR 15169@tab Control Register 15170@item BYTE 15171@tab AIR 15172@tab Active interrupt register 15173@item BYTE 15174@tab STACK 15175@tab Interrupt stack - the interrupt bits that are not (yet) served. 15176@item BYTE 15177@tab CABSTATE 15178@tab State of CA/CB pins. Bit 7 = state of CA, Bit 6 = state of CB 15179@end multitable 15180 15181@node RIOT 6532 module, SID 6581 module, TPI 6525 module, Module formats 15182@subsubsection RIOT module 15183 15184The RIOT 6532 is a chip with two I/O ports, some RAM and a Timer. 15185The chip contains 128 byte RAM, but the RAM is not saved in the 15186RIOT snapshot, but in the memory section. 15187 15188Version numbers: Major 0, Minor 0. 15189 15190@multitable @columnfractions .1 .4 .5 15191@item Type 15192@tab Name 15193@tab Description 15194@item BYTE 15195@tab ORA 15196@tab Port A output register 15197@item BYTE 15198@tab DDRA 15199@tab Port A data direction register 15200@item BYTE 15201@tab ORB 15202@tab Port B output register 15203@item BYTE 15204@tab DDRB 15205@tab Port B data direction register 15206@item BYTE 15207@tab EDGECTRL 15208@tab Bit 0/1: A0/A1 address bits written to edgecontrol registers 15209@item BYTE 15210@tab IRQFL 15211@tab Bit 6/7: A6/A7 IRQ flag register. Bit 0: state of the IRQ line (0=inactive, 1=active) 15212@item BYTE 15213@tab N 15214@tab timer value 15215@item WORD 15216@tab DIVIDER 15217@tab Pre-scale divider value (1, 8, 64, or 1024) 15218@item WORD 15219@tab REST 15220@tab cycles since the last counter change 15221@item BYTE 15222@tab IRQEN 15223@tab Bit 0: 0= timer IRQ disabled, 1= timer IRQ enabled 15224@end multitable 15225 15226@node SID 6581 module, ACIA 6551 module, RIOT 6532 module, Module formats 15227@subsubsection SID module 15228 15229@node ACIA 6551 module, VIC-I module, SID 6581 module, Module formats 15230@subsubsection ACIA module 15231 15232The ACIA 6551 is an RS232 interface chip. VICE emulates RS232 connections 15233via @code{/dev/ttyS*} (Unix) or @code{COM:} (DOS/WIN - not yet?). 15234When saving a snapshot, those connections are of course lost. 15235The state of the ACIA however is restored if possible. I.e. if a connection 15236is already open when restoring the snapshot, this connection is used 15237instead. If no connection is open, a carrier/DTR drop is emulated. 15238 15239Version numbers: Major 1, Minor 0. 15240 15241@multitable @columnfractions .1 .4 .5 15242@item Type 15243@tab Name 15244@tab Description 15245@item BYTE 15246@tab TDR 15247@tab Transmit Data Register 15248@item BYTE 15249@tab RDR 15250@tab Receiver Data Register 15251@item BYTE 15252@tab SR 15253@tab Status Register 15254@item BYTE 15255@tab CMD 15256@tab Command Register 15257@item BYTE 15258@tab CTRL 15259@tab Ctrl Register 15260@item BYTE 15261@tab INTX 15262@tab 0 = no data to tx; 1 = Data is being transmitted; 2 = Data is being transmitted while data in TDR waiting to be put to internal transmit register 15263@item DWORD 15264@tab TICKS 15265@tab Clock ticks till the next TDR empty interrupt 15266@end multitable 15267 15268@node VIC-I module, VIC-II module, ACIA 6551 module, Module formats 15269@subsubsection VIC-I module 15270 15271@c FIXME: add description 15272 15273@node VIC-II module, CRTC module, VIC-I module, Module formats 15274@subsubsection VIC-II module 15275 15276@c FIXME: add description 15277 15278@node CRTC module, C64 memory module, VIC-II module, Module formats 15279@subsubsection CRTC module 15280 15281Version numbers: Major 1, Minor 1. 15282 15283@multitable @columnfractions .1 .4 .5 15284@item Type 15285@tab Name 15286@tab Description 15287@item 15288@tab 15289@tab Hardware options 15290@item WORD 15291@tab VADDR_MASK 15292@tab Mask of the address bits valid when accessing the video memory 15293@item WORD 15294@tab VADDR_CHARSWITCH 15295@tab If one bit in the video address is used to switch the character generator, it is masked here. 15296@item WORD 15297@tab VADDR_CHAROFFSET 15298@tab The offset in characters in the character generator that CHARSWITCH switches. 15299@item WORD 15300@tab VADDR_REVSWITCH 15301@tab If one bit in the video address inverts the screen, it is masked here. 15302@item WORD 15303@tab CHARGEN_MASK 15304@tab size of character generator in byte - 1 15305@item WORD 15306@tab CHARGEN_OFFSET 15307@tab offset given by external circuitry 15308@item BYTE 15309@tab HW_CURSOR 15310@tab external hardware cursor circuitry enabled 15311@item BYTE 15312@tab HW_COLS 15313@tab number of displayed columns during one character clock cycle 15314@item BYTE 15315@tab HW_BLANK 15316@tab set if the hardware blank feature is available 15317@item 15318@tab 15319@tab CRTC register 15320@item 20 BYTE 15321@tab REGISTERS 15322@tab register DUMP of the CRTC registers 0-19. 15323@item 15324@tab 15325@tab CRTC internal registers 15326@item BYTE 15327@tab REGNO 15328@tab The current index in the CRTC register file 15329@item BYTE 15330@tab CHAR 15331@tab The current cycle within the current rasterline 15332@item BYTE 15333@tab CHARLINE 15334@tab The current character line 15335@item BYTE 15336@tab YCOUNTER 15337@tab The current rasterline in the character 15338@item BYTE 15339@tab CRSRCNT 15340@tab Framecounter for the blinking cursor 15341@item BYTE 15342@tab CRSRSTATE 15343@tab if set the hardware cursor is visible 15344@item BYTE 15345@tab CRSRLINES 15346@tab set if ycounter is within the active cursor rasterlines for a char 15347@item WORD 15348@tab CHARGEN_REL 15349@tab relative base of currently used character generator in ROM (in byte) 15350@item WORD 15351@tab SCREEN_REL 15352@tab screen address to load the counter at the beginning of the next rasterline 15353@item WORD 15354@tab VSYNC 15355@tab number of rasterlines left within vsync; 0 = not in vsync 15356@item BYTE 15357@tab VENABLE 15358@tab vertical enable flipflop; 1= display, 0= blank. 15359@item 15360@tab 15361@tab (VICE-dependent?) variables 15362@item WORD 15363@tab SCREEN_WIDTH 15364@tab width of the current display window 15365@item WORD 15366@tab SCREEN_HEIGHT 15367@tab height of the current display window 15368@item WORD 15369@tab SCREEN_XOFFSET 15370@tab x position where the first character in a line starts in the window@dots{} 15371@item WORD 15372@tab HJITTER 15373@tab @dots{}but only after adding this jitter 15374@item WORD 15375@tab SCREEN_YOFFSET 15376@tab x position where the first character in a line starts in the window@dots{} 15377@item WORD 15378@tab FRAMELINES 15379@tab expected number of rasterlines for the current frame 15380@item WORD 15381@tab CURRENT_LINE 15382@tab current rasterline as seen from the CRTC 15383@item 15384@tab 15385@tab This value has been added in module version V1.1 15386@item BYTE 15387@tab FLAG 15388@tab Bit 0: If 1 then bit in VADDR_REVSWITCH must be set for reverse; if 0 then bit must be cleared for reverse. 15389@end multitable 15390 15391Here is the reference for the previous CRTC snapshot module. It is outdated 15392and will not be read by this and later versions of VICE. 15393 15394Version numbers: Major 0, Minor 0. 15395 15396@multitable @columnfractions .1 .4 .5 15397@item Type 15398@tab Name 15399@tab Description 15400@item BYTE 15401@tab RASTERY 15402@tab The number of clock cycles from rasterlines start 15403@item WORD 15404@tab RASTERLINE 15405@tab The current rasterline 15406@item WORD 15407@tab ADDRMASK 15408@tab The address mask valid for the CRTC. All memory accesses are masked with this value 15409@item BYTE 15410@tab HWFLAG 15411@tab Bit 0: 1= hardware cursor available. Bit 1: 1= number of columns is doubled by external hardware 15412@item 20 BYTE 15413@tab REGISTERS 15414@tab register DUMP of the CRTC registers 0-19. 15415@item BYTE 15416@tab CRSRSTATE 15417@tab Hardware cursor: Bits 0-3: frame counter till next crsr line toggle. Bit 7: 1= cursor line active 15418@end multitable 15419 15420@node C64 memory module, C128 memory module, CRTC module, Module formats 15421@subsubsection C64 memory module 15422 15423The C64 memory module actually consists of two modules. The "C64MEM" module 15424is mandatory and contains the RAM dump. The "C64ROM" module is optional 15425and contains a dump of the ROM images. 15426 15427The size of the C64 memory modules differs with each different memory 15428configuration. The RAM configuration is saved in the snapshot, and 15429restored when the snapshot is loaded. 15430 15431Version numbers: Major 0, Minor 0 15432 15433@b{The C64MEM module} 15434 15435@multitable @columnfractions .1 .4 .5 15436@item Type 15437@tab Name 15438@tab Description 15439@item BYTE 15440@tab CPUDATA 15441@tab CPU port data byte 15442@item BYTE 15443@tab CPUDIR 15444@tab CPU port direction byte 15445@item BYTE 15446@tab EXROM 15447@tab state of the EXROM line (?) 15448@item BYTE 15449@tab GAME 15450@tab state of the GAME line (?) 15451@item ARRAY 15452@tab RAM 15453@tab 64KiB RAM dump 15454@end multitable 15455 15456@b{The C64ROM module} 15457 15458@multitable @columnfractions .1 .4 .5 15459@item Type 15460@tab Name 15461@tab Description 15462@item ARRAY 15463@tab KERNAL 15464@tab 8KiB dump of the kernal ROM 15465@item ARRAY 15466@tab BASIC 15467@tab 8KiB dump of the basic ROM 15468@item ARRAY 15469@tab CHARGEN 15470@tab 4KiB dump of the chargen ROM 15471@end multitable 15472 15473@node C128 memory module, VIC20 memory module, C64 memory module, Module formats 15474@subsubsection C128 memory module 15475 15476The C128 memory module actually consists of two modules. The "C128MEM" module 15477is mandatory and contains the RAM dump. The "C128ROM" module is optional 15478and contains a dump of the ROM images. 15479 15480The size of the C128 memory modules differs with each different memory 15481configuration. The RAM configuration is saved in the snapshot, and 15482restored when the snapshot is loaded. The attached cartridges are 15483also restored upon load if they have been saved in the snapshot. 15484 15485Version numbers: Major 0, Minor 0 15486 15487@b{The C128MEM module} 15488 15489@multitable @columnfractions .1 .4 .5 15490@item Type 15491@tab Name 15492@tab Description 15493@item 12 BYTE 15494@tab MMU 15495@tab dump of the 12 MMU registers 15496@item ARRAY 15497@tab RAM 15498@tab 128KiB RAM dump banks 0 and 1 15499@end multitable 15500 15501@b{The C128ROM module} 15502 15503@multitable @columnfractions .1 .4 .5 15504@item Type 15505@tab Name 15506@tab Description 15507@item ARRAY 15508@tab KERNAL 15509@tab 8KiB dump of the kernal ROM 15510@item ARRAY 15511@tab BASIC 15512@tab 32KiB dump of the basic ROM 15513@item ARRAY 15514@tab EDITOR 15515@tab 4KiB dump of the editor ROM 15516@item ARRAY 15517@tab 4KiB CHARGEN 15518@tab dump of the chargen ROM 15519@end multitable 15520 15521@node VIC20 memory module, PET memory module, C128 memory module, Module formats 15522@subsubsection VIC20 memory module 15523 15524The VIC20 memory module actually consists of two modules. The "VIC20MEM" module 15525is mandatory and contains the RAM dump. The "VIC20ROM" module is optional 15526and contains a dump of the ROM images. 15527 15528The size of the VIC20 memory modules differs with each different memory 15529configuration. The RAM configuration is saved in the snapshot, and 15530restored when the snapshot is loaded. The attached cartridges are 15531also restored upon load if they have been saved in the snapshot. 15532 15533@b{The VIC20MEM module} 15534 15535Version numbers: Major 1, Minor 0 15536 15537@multitable @columnfractions .1 .4 .5 15538@item Type 15539@tab Name 15540@tab Description 15541@item BYTE 15542@tab CONFIG 15543@tab Configuration register. Bits 0,1,2,3,5 reflect if the corresponding memory block is RAM (bit=1) or not (bit=0). 15544@item ARRAY 15545@tab RAM0 15546@tab 1KiB RAM dump $0000-$03ff 15547@item ARRAY 15548@tab RAM1 15549@tab 4KiB RAM dump $1000-$1fff 15550@item ARRAY 15551@tab COLORRAM 15552@tab 2KiB Color RAM, $9400-$9bff 15553@item ARRAY 15554@tab BLK0 15555@tab if CONFIG & 1 then: 3KiB RAM dump $0400-$0fff 15556@item ARRAY 15557@tab BLK1 15558@tab if CONFIG & 2 then: 8KiB RAM dump $2000-$3fff 15559@item ARRAY 15560@tab BLK2 15561@tab if CONFIG & 4 then: 8KiB RAM dump $4000-$5fff 15562@item ARRAY 15563@tab BLK3 15564@tab if CONFIG & 8 then: 8KiB RAM dump $6000-$7fff 15565@item ARRAY 15566@tab BLK5 15567@tab if CONFIG & 32 then: 8KiB RAM dump $a000-$bfff 15568@end multitable 15569 15570@b{The VIC20ROM module} 15571 15572Version numbers: Major 1, Minor 1 15573 15574@multitable @columnfractions .1 .4 .5 15575@item Type 15576@tab Name 15577@tab Description 15578@item BYTE 15579@tab CONFIG 15580@tab Bit 0: 1= ROM block $2*** enabled. Bit 1: 1= ROM block $3*** enabled. Bit 2: 1= ROM block $4*** enabled. Bit 3: 1= ROM block $5*** enabled. Bit 4: 1= ROM block $6*** enabled. Bit 5: 1= ROM block $7*** enabled. Bit 6: 1= ROM block $A*** enabled. Bit 7: 1= ROM block $B*** enabled. 15581@item ARRAY 15582@tab KERNAL 15583@tab 8KiB KERNAL ROM image $e000-$ffff 15584@item ARRAY 15585@tab BASIC 15586@tab 16KiB BASIC ROM image $c000-$dfff 15587@item ARRAY 15588@tab CHARGEN 15589@tab 4KiB CHARGEN ROM image 15590@item ARRAY 15591@tab BLK1A 15592@tab 4KiB ROM image $2*** (if CONFIG & 1) 15593@item ARRAY 15594@tab BLK1B 15595@tab 4KiB ROM image $3*** (if CONFIG & 2) 15596@item ARRAY 15597@tab BLK3A 15598@tab 4KiB ROM image $6*** (if CONFIG & 16) 15599@item ARRAY 15600@tab BLK3B 15601@tab 4KiB ROM image $7*** (if CONFIG & 32) 15602@item ARRAY 15603@tab BLK5A 15604@tab 4KiB ROM image $A*** (if CONFIG & 64) 15605@item ARRAY 15606@tab BLK5B 15607@tab 4KiB ROM image $B*** (if CONFIG & 128) 15608@item ARRAY 15609@tab BLK2A 15610@tab 4KiB ROM image $4*** (if CONFIG & 4; added in V1.1) 15611@item ARRAY 15612@tab BLK2B 15613@tab 4KiB ROM image $5*** (if CONFIG & 8; added in V1.1) 15614@end multitable 15615 15616@node PET memory module, CBM-II memory module, VIC20 memory module, Module formats 15617@subsubsection PET memory module 15618 15619The PET memory module actually consists of three modules. The "PETMEM" module 15620is mandatory and contains the RAM dump. The "PETROM" module is optional 15621and contains a dump of the ROM images. The "PETDWW" module is also 15622optional and contains the image of the hires expansion board (if 15623enabled). 15624 15625The size of the PET memory modules differs with each different memory 15626configuration. The RAM configuration is saved in the snapshot, and 15627restored when the snapshot is loaded. 15628 15629@b{The PETMEM module} 15630 15631Version numbers: Major 1, Minor 3 15632 15633@multitable @columnfractions .1 .4 .5 15634@item Type 15635@tab Name 15636@tab Description 15637@item BYTE 15638@tab CONFIG 15639@tab Configuration value. Bits 0-3: 0= 40 col PET without CRTC; 1= 40 col PET with CRTC; 2 = 80 col PET (with CRTC); 3= SuperPET; 4= 8096; 5= 8296. Bit 6: 1= RAM at $9***. Bit 7: 1= RAM at $A***. 15640@item BYTE 15641@tab KEYBOARD 15642@tab Keyboard type. 0= UK business; 1= Graphics; 2= German business 15643@item BYTE 15644@tab MEMSIZE 15645@tab memory size of low 32KiB in k (possible values 4, 8, 16, 32) 15646@item BYTE 15647@tab CONF8X96 15648@tab Value of the 8x96 configuration register 15649@item BYTE 15650@tab SUPERPET 15651@tab SuperPET config. Bit 0: 1= $9*** RAM enabled. Bit 1: 1= RAM write protected. Bit 2: 1= CTRL register write protected. Bit 3: 0= DIAG pin active. Bits 4-7: RAM block in use. 15652@item ARRAY 15653@tab RAM 15654@tab 4-32KiB RAM (not 8296, size depends on MEMSIZE) 15655@item ARRAY 15656@tab VRAM 15657@tab 2/4KiB RAM (not 8296, size depends on CONFIG) 15658@item ARRAY 15659@tab EXTRAM 15660@tab 64KiB expansion RAM (SuperPET and 8096 only) 15661@item ARRAY 15662@tab RAM 15663@tab 128KiB RAM (8296 only) 15664@item -- 15665@tab -- 15666@tab The following item has been added in V1.1 15667@item BYTE 15668@tab POSITIONAL 15669@tab bit 0=0 = symbolic keyboard mapping, bit 0=1 = positional mapping. 15670@item -- 15671@tab -- 15672@tab The following item has been added in V1.2 15673@item BYTE 15674@tab EOIBLANK 15675@tab bit 0=0 = EOI does not blank screen, bit 0=1 = EOI blanks screen. 15676@item -- 15677@tab -- 15678@tab The following items have been added in V1.3 15679@item WORD 15680@tab CPU_SWITCH 15681@tab 6502 / 6809 / PROG 15682@item BYTE 15683@tab VAL, PREVODD, WANTODD 15684@tab 6702 dongle state information 15685@item WORD[8] 15686@tab SHIFT 15687@item BYTE 15688@tab SuperPET config 2 15689@tab Extra bits due to the Super-OS-9 MMU. Bit 5: FIRQ disabled. Bit 6: 15690expansion memory in OS-9 flat mode. 15691 15692@end multitable 15693 15694The POSITIONAL item has been added in PETMEM snapshot version 1.1. It is 15695ignored by earlier restore routines (V1.0) and the V1.1 restore routines 15696do not change the current setting when reading a V1.0 snapshot. 15697 15698In V1.2 the new EOIBLANK variable has been added. This implements 15699the "blank screen on EOI" feature that was previously linked to a wrong 15700resource. 15701 15702In V1.3 the state for SuperPET has been added. 15703 15704@b{The PETROM module} 15705 15706Version numbers: Major 1, Minor 1 15707 15708@multitable @columnfractions .1 .4 .5 15709@item Type 15710@tab Name 15711@tab Description 15712@item BYTE 15713@tab CONFIG 15714@tab Bit 0: 1= $9*** ROM included. Bit 1: 1= $A*** ROM included. Bit 2: 1= $B*** ROM included. Bit 3: 1= $e900-$efff ROM included. Bit 4: 1= SuperPET ROMs included. 15715@item ARRAY 15716@tab KERNAL 15717@tab 4KiB KERNAL ROM image $f000-$ffff 15718@item ARRAY 15719@tab EDITOR 15720@tab 2KiB EDITOR ROM image $e000-$e7ff 15721@item ARRAY 15722@tab CHARGEN 15723@tab 2KiB CHARGEN ROM image 15724@item ARRAY 15725@tab ROM9 15726@tab 4KiB $9*** ROM image (if CONFIG & 1) 15727@item ARRAY 15728@tab ROMA 15729@tab 4KiB $A*** ROM image (if CONFIG & 2) 15730@item ARRAY 15731@tab ROMB 15732@tab 4KiB $B*** ROM image (if CONFIG & 4) 15733@item ARRAY 15734@tab ROMC 15735@tab 4KiB $C*** ROM image 15736@item ARRAY 15737@tab ROMD 15738@tab 4KiB $D*** ROM image 15739@item ARRAY 15740@tab ROME9 15741@tab 7 blocks $e900-$efff ROM image (if CONFIG & 8) 15742@item -- 15743@tab -- 15744@tab The following items have been added in V1.1 15745@item ROM6809 15746@tab ROM6809 15747@tab 24KiB $A000-$FFFF ROM (if CONFIG & 16) 15748@item ARRAY 15749@tab CHARGEN(2) 15750@tab upper half of CHARGEN (if CONFIG & 16) 15751@end multitable 15752 15753@b{The PETDWW module} 15754 15755For storing the state of the DWW hires expansion board, there is a 15756PETDWWPIA module, and a DWWMEM module. 15757 15758The former has the same format as the PIA1. 15759 15760@multitable @columnfractions .1 .4 .5 15761@item Type 15762@tab Name 15763@tab Description 15764@item WORD 15765@tab SIZE 15766@tab The size of the memory dump that follows, or 0 if DWW disabled. 15767@item ARRAY 15768@tab MEM 15769@tab The memory in the DWW card, SIZE bytes. 15770@end multitable 15771 15772@node CBM-II memory module, C500 data module, PET memory module, Module formats 15773@subsubsection CBM-II memory module 15774 15775The CBM-II memory module actually consists of two modules. The 15776"CBM2MEM" module is mandatory and contains the RAM dump. The "CBM2ROM" 15777module is optional and contains a dump of the ROM images. 15778 15779The size of the CBM-II memory modules differs with each different memory 15780configuration. The RAM configuration is saved in the snapshot, and 15781restored when the snapshot is loaded. 15782 15783Version numbers: Major 1, Minor 0 15784 15785@b{The CBM2MEM module} 15786 15787@multitable @columnfractions .1 .4 .5 15788@item Type 15789@tab Name 15790@tab Description 15791@item UBYTE 15792@tab MEMSIZE 15793@tab Memory size in 128KiB blocks (1=128KiB, 2=256KiB, 4=512KiB, 8=1024KiB) 15794@item UBYTE 15795@tab CONFIG 15796@tab Bit 0 = $f0800-$f0fff RAM, Bit 1 = $f1000-$f1fff RAM, Bit 2 = $f2000-$f3fff RAM, Bit 3 = $f4000-$f5fff RAM, Bit 4 = $f6000-$f7fff RAM, Bit 5 = $fc000-$fcfff RAM, Bit 6 = is a C500 15797@item UBYTE 15798@tab HWCONFIG 15799@tab Bit 0/1: model line configuration 15800@item UBYTE 15801@tab EXECBANK 15802@tab CPUs execution bank register 15803@item UBYTE 15804@tab INDBANK 15805@tab CPUs indirection bank register 15806@item ARRAY 15807@tab SYSRAM 15808@tab 2KiB system RAM $f0000-$f07ff 15809@item ARRAY 15810@tab VIDEO 15811@tab 2KiB video RAM $fd000-$fd7ff 15812@item ARRAY 15813@tab RAM 15814@tab RAM dump, size according to MEMSIZE 15815@item ARRAY 15816@tab RAM08 15817@tab if memsize < 1MiB and CONFIG & 1 : 2KiB RAM $f0800-$f0fff 15818@item ARRAY 15819@tab RAM1 15820@tab if memsize < 1MiB and CONFIG & 2 : 4KiB RAM $f1000-$f1fff 15821@item ARRAY 15822@tab RAM2 15823@tab if memsize < 1MiB and CONFIG & 4 : 8KiB RAM $f2000-$f3fff 15824@item ARRAY 15825@tab RAM4 15826@tab if memsize < 1MiB and CONFIG & 8 : 8KiB RAM $f4000-$f5fff 15827@item ARRAY 15828@tab RAM6 15829@tab if memsize < 1MiB and CONFIG & 16 : 8KiB RAM $f6000-$f7fff 15830@item ARRAY 15831@tab RAMC 15832@tab if memsize < 1MiB and CONFIG & 32 : 4KiB RAM $fc000-$fcfff 15833@end multitable 15834 15835The RAM* arrays are only saved if the RAM itself is less than 1MiB. 15836If the memory size is 1MiB then those areas are taken from the 15837bank 15 area of the normal RAM. 15838 15839The memory array starts at $10000 if the memory size is less than 512KiB, 15840or at $00000 if 512KiB or more. In case of a C510, then the memory array 15841also always starts at $00000. 15842 15843@b{The CBM2ROM module} 15844 15845@multitable @columnfractions .1 .4 .5 15846@item Type 15847@tab Name 15848@tab Description 15849@item UBYTE 15850@tab CONFIG 15851@tab Bit 1: 1= $1*** ROM image included. Bit 2: 1= $2000-$3fff ROM image included. Bit 3: 1= $4000-$5fff ROM image included. Bit 4: 1= $6000-$7fff ROM image included. Bit 5: 1= chargen ROM is VIC-II chargen, 0= CRTC chargen. 15852@item ARRAY 15853@tab KERNAL 15854@tab 8 KERNAL ROM image ($e000-$efff) 15855@item ARRAY 15856@tab BASIC 15857@tab BASIC ROM image ($8000-$bfff) 15858@item ARRAY 15859@tab CHARGEN 15860@tab 4KiB CHARGEN ROM image 15861@item ARRAY 15862@tab ROM1 15863@tab 4KiB cartridge ROM image for $1*** (if CONFIG & 2) 15864@item ARRAY 15865@tab ROM2 15866@tab 8KiB cartridge ROM image for $2000-$3fff (if CONFIG & 4) 15867@item ARRAY 15868@tab ROM4 15869@tab 8KiB cartridge ROM image for $4000-$5fff (if CONFIG & 8) 15870@item ARRAY 15871@tab ROM6 15872@tab 8KiB cartridge ROM image for $6000-$7fff (if CONFIG & 16) 15873@end multitable 15874 15875@node C500 data module, ,CBM-II memory module, Module formats 15876@subsubsection C500 data module 15877 15878The C500 data module contains simple state information not already saved 15879in the other modules. 15880 15881Version numbers: Major 0, Minor 0 15882 15883@b{The C500DATA module} 15884 15885@multitable @columnfractions .1 .4 .5 15886@item Type 15887@tab Name 15888@tab Description 15889@item DWORD 15890@tab IRQCLK 15891@tab CPU clock ticks till next 50Hz IRQ 15892@end multitable 15893 15894@c ----------------------------------------------------------------- 15895@node Media images 15896@chapter Media images 15897 15898@c FIXME: add some info on making screenshots, wav- and avi recordings 15899 15900@c @node FIXME 15901@section Media images resources 15902 15903@table @code 15904 15905@vindex OCPOversizeHandling 15906@item OCPOversizeHandling 15907Integer specifying the way the oversized input should be handled 15908(all emulators except vsid). 15909(0: scale down, 1: crop left top, 2: crop center top, 159103: crop right top, 4: crop left center, 5: crop center, 159116: crop right center, 7: crop left bottom, 8: crop center bottom, 159129: crop right bottom) 15913 15914@vindex OCPUndersizeHandling 15915@item OCPUndersizeHandling 15916Integer specifying the way the undersized input should be handled 15917(all emulators except vsid). 15918(0: scale, 1: borderize) 15919 15920@vindex OCPMultiColorHandling 15921@item OCPMultiColorHandling 15922Integer specifying the way the multicolor to hires should be handled 15923(all emulators except vsid). 15924(0: b&w, 1: 2 colors, 2: 4 colors, 3: gray scale, 4: best cell colors) 15925 15926@vindex OCPTEDLumHandling 15927@item OCPTEDLumHandling 15928Integer specifying the way the TED luminosity should be handled 15929(all emulators except vsid). 15930(0: ignore, 1: dither) 15931 15932@vindex KoalaOversizeHandling 15933@item KoalaOversizeHandling 15934Integer specifying the way the oversized input should be handled 15935(all emulators except vsid). 15936(0: scale down, 1: crop left top, 2: crop center top, 159373: crop right top, 4: crop left center, 5: crop center, 159386: crop right center, 7: crop left bottom, 8: crop center bottom, 159399: crop right bottom) 15940 15941@vindex KoalaUndersizeHandling 15942@item KoalaUndersizeHandling 15943Integer specifying the way the undersized input should be handled 15944(all emulators except vsid). 15945(0: scale, 1: borderize) 15946 15947@vindex KoalaTEDLumHandling 15948@item KoalaTEDLumHandling 15949Integer specifying the way the TED luminosity should be handled 15950(all emulators except vsid). 15951(0: ignore, 1: dither) 15952 15953@vindex FFMPEGFormat 15954@item FFMPEGFormat 15955String specifying the current FFMPEG output driver. 15956@vindex FFMPEGAudioBitrate 15957@item FFMPEGAudioBitrate 15958Integer specifying the current FFMPEG audio bitrate. 15959@vindex FFMPEGVideoBitrate 15960@item FFMPEGVideoBitrate 15961Integer specifying the current FFMPEG video bitrate. 15962@vindex FFMPEGAudioCodec 15963@item FFMPEGAudioCodec 15964Integer specifying the current FFMPEG audio codec. 15965@vindex FFMPEGVideoCodec 15966@item FFMPEGVideoCodec 15967Integer specifying the current FFMPEG video codec. 15968@vindex FFMPEGVideoHalveFramerate 15969@item FFMPEGVideoHalveFramerate 15970Boolean, if true record only every other frame. 15971 15972@end table 15973 15974@c @node FIXME 15975@section Media images command-line options 15976 15977@table @code 15978 15979@findex -ocpoversize 15980@item -ocpoversize <method> 15981Select the way the oversized input should be handled 15982(@code{OCPOversizeHandling}) 15983(all emulators except vsid). 15984(0: scale down, 1: crop left top, 2: crop center top, 159853: crop right top, 4: crop left center, 5: crop center, 159866: crop right center, 7: crop left bottom, 159878: crop center bottom, 9: crop right bottom) 15988 15989@findex -ocpundersize 15990@item -ocpundersize <method> 15991Select the way the undersized input should be handled 15992(@code{OCPUndersizeHandling}) 15993(all emulators except vsid). 15994(0: scale, 1: borderize) 15995 15996@findex -ocpmc 15997@item -ocpmc <method> 15998Select the way the multicolor to hires should be handled 15999(@code{OCPMultiColorHandling}) 16000(all emulators except vsid). 16001(0: b&w, 1: 2 colors, 2: 4 colors, 3: gray scale, 4: best cell colors) 16002 16003@findex -ocptedlum 16004@item -ocptedlum <method> 16005Select the way the TED luminosity should be handled 16006(@code{OCPTEDLumHandling}) 16007(all emulators except vsid). 16008(0: ignore, 1: dither) 16009 16010@findex -koalaoversize 16011@item -koalaoversize <method> 16012Select the way the oversized input should be handled 16013(@code{KoalaOversizeHandling}) 16014(all emulators except vsid). 16015(0: scale down, 1: crop left top, 2: crop center top, 160163: crop right top, 4: crop left center, 5: crop center, 160176: crop right center, 7: crop left bottom, 160188: crop center bottom, 9: crop right bottom) 16019 16020@findex -koalaundersize 16021@item -koalaundersize <method> 16022Select the way the undersized input should be handled 16023(@code{KoalaUndersizeHandling}) 16024(all emulators except vsid). 16025(0: scale, 1: borderize) 16026 16027@findex -koalatedlum 16028@item -koalatedlum <method> 16029Select the way the TED luminosity should be handled 16030(@code{KoalaTEDLumHandling}) 16031(all emulators except vsid). 16032(0: ignore, 1: dither) 16033 16034@findex -ffmpegaudiobitrate 16035@item -ffmpegaudiobitrate <value> 16036Set bitrate for audio stream in media file 16037@findex -ffmpegvideobitrate 16038@item -ffmpegvideobitrate <value> 16039Set bitrate for video stream in media file 16040 16041@end table 16042 16043@c ----------------------------------------------------------------- 16044@node Event history 16045@chapter Event history 16046 16047@c FIXME: the "Event history" section needs to be style-checked. 16048 16049VICE supports recording an arbitrary session on the emulated machine and 16050playing back this session later. This is done by saving a snapshot at the beginning 16051of the recording session and then remembering all the user interaction such as 16052keyboard and joystick input. We call this an 'event history'. 16053The main purpose for having an event history is to create game sessions, e.g. recording 16054how to solve a game. An example walkthrough for the well known game "Fort Apocalypse" is 16055available. 16056 16057@c @node FIXME 16058@section Recommended Settings 16059 16060When using the event history feature it is possible that the playback session 16061differs from what was done at recording time. This might arise due to a problem 16062in the initial snapshot or settings. 16063Here are some suggestions to minimize the chance of failures in the session: 16064a. Reset to default settings. 16065b. Choose refresh rate 1/1. 16066c. Choose joystick and Video/Doublesize settings as desired or needed. 16067d. SID engine must be reSID (which is the default). 16068e. Choose Drive settings/Idle method: None 16069Do not change any settings during recording or playback! 16070 16071@c @node FIXME 16072@section Recorded Events 16073 16074The following is a list of the user interaction that will be recorded: 16075- Joystick movement and button 16076- Keyboard 16077- Resetting the machine (hard and soft) 16078- Attaching or detaching disk/tape images (see 8. Limitations) 16079- Datasette controls 16080 16081@c @node FIXME 16082@section Recording an Event History 16083 16084Recording an event history will create one or two files for a snapshot and 16085the list of the user events. First, create an empty directory in which these 16086files are to be saved and then select this directory and the name of the 16087snapshot files via 'Snapshot//Select History files/directory'. 16088Next, attach the disk or tape image with the game you want to record and load and 16089run the game. 16090 16091Start recording via 'Snapshot//Start/Stop Recording History'. 16092Play the game. All actions will be recorded. 16093After the game is finished, stop recording via 'Snapshot//Start/Stop 16094Recording History'. The selected directory should now contain the two 16095snapshot files (default ist start.vsf and end.vsf). 16096 16097@c @node FIXME 16098@section Setting and Returning to Milestones 16099 16100It is difficult to finish a game in one sitting and noone wants to 16101record all their mistakes and lost lives. Use the milestone feature in a 16102recording session in the following way: 16103 16104Set a milestone when you have finished a level or completed a task 16105('Snapshot//Set recording milestone' or ALT-E). This will save the event 16106history and a snapshot of the machine to the file end.vsf but recording will 16107continue. 16108 16109Return to the last milestone when you have made a mistake or lost a life 16110('Snapshot//Return to milestone' or ALT-U). This will reset the game and the 16111event history to the last milestone snapshot so that you can try again. 16112 16113@c @node FIXME 16114@section Continuing an Event History 16115 16116If you have stopped a recording session and want to continue it later, you 16117should create a backup of your start.vsf and end.vsf files first to avoid 16118overwriting them by accident. 16119 16120Then change the event history start mode: 'Snapshot//Recording start mode//Load 16121existing snapshot'. When you start recording now, you will continue where the 16122session was stopped last time. 16123 16124Another way of continuing an existing history is to start somewhere inside the 16125history (e.g. you have recorded 10 minutes of a game and later recognize that you 16126made a mistake after 6 minutes that makes it impossible to finish the game). 16127For this you have to select the start mode 'Overwrite playback'. Now you can 16128start the playback with 'Snapshot//Start/Stop Playback History' and when you 16129reach the point where you want to change the history you can directly switch to 16130recording via 'Snapshot//Start/Stop Recording History'. 16131 16132@c @node FIXME 16133@section Playing Back an Event History 16134 16135To play back an event history, select the directory with the history files 16136start.vsf and end.vsf via 'Snapshot//Select History directory' and start the 16137playback with 'Snapshot//Start/Stop Playback History'. Enjoy! 16138During playback any user interaction is disabled. 16139The playback stops when the end of the session is reached or if 16140'Snapshot//Select History directory' is selected again. 16141 16142@c @node FIXME 16143@section Limitations and Suggestions 16144 16145a. Snapshot files will be quite big (>1MiB) if a disk image has been attached. 16146If possible, use PRG or T64 images to reduce the size of snapshot files. 16147b. Snapshots may not be 100% accurate even with all the recommended settings. 16148 16149 16150@c @node FIXME 16151@section Event history resources 16152 16153@table @code 16154 16155@vindex EventSnapshotDir 16156@item EventSnapshotDir 16157String specifying the directory used for loading and saving snapshots 16158(all emulators except vsid). 16159 16160@vindex EventStartSnapshot 16161@item EventStartSnapshot 16162String specifying the filename for the start snapshot 16163(all emulators except vsid). 16164 16165@vindex EventEndSnapshot 16166@item EventEndSnapshot 16167String specifying the filename for the end snapshot 16168(all emulators except vsid). 16169 16170@vindex EventStartMode 16171@item EventStartMode 16172Integer specifying how to start event recording 16173(all emulators except vsid). 16174(0: save new snapshot, 1: load existing snapshot, 2: reset, 3: playback) 16175 16176@vindex EventImageInclude 16177@item EventImageInclude 16178Boolean specifying whether to include ROM and Disk images in the snapshots 16179(all emulators except vsid). 16180 16181@end table 16182 16183@c @node FIXME 16184@section Event history command-line options 16185 16186@table @code 16187@findex -playback 16188@item -playback 16189Playback recorded events 16190(all emulators except vsid). 16191 16192@findex -eventsnapshotdir 16193@item -eventsnapshotdir <Name> 16194Set event snapshot directory 16195(@code{EventSnapshotDir}) 16196(all emulators except vsid). 16197 16198@findex -eventstartsnapshot 16199@item -eventstartsnapshot <Name> 16200Set event start snapshot filename 16201(@code{EventStartSnapshot}) 16202(all emulators except vsid). 16203 16204@findex -eventendsnapshot 16205@item -eventendsnapshot <Name> 16206Set event end snapshot filename 16207(@code{EventEndSnapshot}) 16208(all emulators except vsid). 16209 16210@findex -eventstartmode 16211@item -eventstartmode <Mode> 16212Set event start mode 16213(@code{EventStartMode}) 16214(all emulators except vsid). 16215(0: save new snapshot, 1: load existing snapshot, 2: reset, 3: playback) 16216 16217@findex -eventimageinc, +eventimageinc 16218@item -eventimageinc 16219@itemx +eventimageinc 16220Enable/disable the inclusion of disk images in the event 16221(@code{EventImageInclude=1}, @code{EventImageInclude=0}) 16222(all emulators except vsid). 16223 16224@end table 16225 16226@c ----------------------------------------------------------------- 16227 16228@node Monitor 16229@chapter Monitor 16230 16231The VICE emulator has a complete built-in monitor, which can be used 16232to examine, disassemble and assemble machine language programs, as 16233well as debug them through breakpoints. It can be activated by using 16234``Activate monitor'' from the menu. The monitor will either run in a 16235seperate window, or in a terminal emulation program (such as 16236@code{rxvt} or @code{xterm}) when ``native monitor'' has been enabled in 16237the settings. 16238 16239@menu 16240* Terminology:: 16241* Machine state commands:: 16242* Memory commands:: 16243* Assembly commands:: 16244* Checkpoint commands:: 16245* General commands:: 16246* Disk commands:: 16247* Command file commands:: 16248* Label commands:: 16249* Miscellaneous commands:: 16250@end menu 16251 16252@node Terminology, Machine state commands, Monitor, Monitor 16253@section Terminology 16254 16255@table @samp 16256 16257@item address_space 16258This refers to the range of memory locations and a set of registers. 16259This can be the addresses available to the computer's processor, the 16260disk drive's processor or a specific memory configuration of one of 16261the mentioned processors. 16262 16263@item bankname 16264The CPU can only see 64KiB of memory at any one time, due to its 16 bit 16265address bus. The C64 and other computers have more than this amount, 16266and this is handled by banking: a memory address can have different 16267contents, depending on the active memory bank. 16268A bankname names a specific bank in the current address_space. 16269 16270@item register 16271One of the following: program counter (PC), stack pointer (SP), 16272accumulator (A), X register (X), or Y register (Y). 16273 16274@item address 16275A specific memory location in the range $0000 to $FFFF. 16276 16277@item address_range 16278Two addresses. If the second address is less than the first, the 16279range is assumed to wraparound from $FFFF to $0000. Both addresses 16280must be in the same address space. 16281 16282@item address_opt_range 16283An address or an address range. 16284 16285@item label 16286@code{label} is the name of a label. It must start with a dot (".") 16287in order for the monitor to recognize it as a label. Register names preceeded 16288by a dot (for example @code{.PC}) are special labels that evaluate to value of 16289the respective register at the time it is used, and thus can not be used as 16290a regular label. 16291 16292@item prompt 16293The prompt has the format [x:y]. If x is -, memory reads from the 16294monitor do not have side effects. Otherwise, x is S. The second part 16295of the prompt, y, shows the default address space. 16296 16297@item checkpoint 16298The monitor has the ability to setup triggers that perform an action 16299when a specified situation occurs. There are three types of 16300checkpoints; breakpoints, tracepoints and watchpoints. 16301 16302@item breakpoint 16303A breakpoint is triggered based on the program counter. When it is 16304triggered, the monitor is entered. 16305 16306@item tracepoint 16307Like breakpoints, a tracepoint is triggered based on the program 16308counter. Instead of entering the monitor, the program counter is 16309printed and execution continues. 16310 16311@item watchpoint 16312Watchpoints are triggered by a read and/or write to an address. When 16313a watchpoint is triggered, the monitor is entered. 16314 16315@item memmap 16316The memmap keeps track of RAM/ROM/IO read/write/execute 16317accesses. The feature must be enabled with "--enable-cpuhistory" 16318configure option, as it might decrease performance notably on 16319slower hardware. The option also enables CPU history. 16320 16321@item <@dots{}> 16322A data type. 16323 16324@item * 16325Zero or more occurrences. 16326 16327@item [@dots{}] 16328An optional argument. 16329 16330@end table 16331 16332@node Machine state commands, Memory commands, Terminology, Monitor 16333@section Machine state commands 16334 16335@table @code 16336 16337@item backtrace 16338@itemx bt 16339Print JSR call chain (most recent call first). Stack offset 16340relative to SP+1 is printed in parentheses. This is a best guess 16341only. 16342 16343@item cpuhistory [<count>] 16344@itemx chis [<count>] 16345Show <count> last executed commands. 16346(disabled by default; configure with --enable-cpuhistory to enable) 16347 16348@item dump "<filename>" 16349Write a snapshot of the machine into the file specified. 16350This snapshot is compatible with a snapshot written out by the UI. 16351Note: No ROM images are included into the dump. 16352 16353@item goto <address> 16354@itemx g <address> 16355Change the PC to address and continue execution. 16356 16357@item io [<address>] 16358Display i/o registers. Invoking without an address shows a dump of 16359the entire io range, if an address is given then details for the 16360chip at the respective (base-)address are displayed (if available). 16361 16362@item next [<count>] 16363@itemx n [<count>] 16364Advance to the next instruction. Subroutines are treated as a single 16365instruction. 16366 16367@item registers [<reg_name> = <number> [, <reg_name> = <number>]*] 16368@itemx r [<reg_name> = <number> [, <reg_name> = <number>]*] 16369Assign respective registers (use FL for status flags). With no parameters, 16370display register values. 16371 16372@item reset [<type>] 16373Reset the machine or drive. 16374@code{type}: 0 = soft, 1 = hard, 8-11 = drive. 16375 16376@item return 16377@itemx ret 16378Continues execution and returns to the monitor just 16379after the next RTS or RTI is executed. 16380 16381@item step [<count>] 16382@itemx z [<count>] 16383Single step through instructions. An optional count allows stepping 16384more than a single instruction at a time. 16385 16386@item stopwatch [reset] 16387Print the CPU cycle counter of the current device. 'reset' sets the counter to 0. 16388 16389@item undump "<filename>" 16390Read a snapshot of the machine from the file specified. 16391 16392@end table 16393 16394 16395@node Memory commands, Assembly commands, Machine state commands, Monitor 16396@section Memory commands 16397 16398 16399@table @code 16400 16401@item bank [<bankname>] 16402Without a bankname, display all available banks for the current 16403address_space. With a bankname given, switch to the specified 16404bank. If a bank is not completely filled (ROM banks for example) 16405normally the @code{ram} bank is used where the bank has holes. 16406The @code{cpu} bank uses the bank currently used by the CPU. 16407 16408@item compare <address_range> <address> 16409@itemx c <address_range> <address> 16410Compare memory from the source specified by the address range to the 16411destination specified by the address. The regions may overlap. Any 16412values that miscompare are displayed using the default displaytype. 16413 16414@item device [c:|8:|9:] 16415Set the default address space to either the computer `c:' or the 16416specified drive `8:' or `9:' 16417 16418@item fill <address_range> <data_list> 16419@itemx f <address_range> <data_list> 16420Fill memory in the specified address range with the data in 16421<data_list>. If the size of the address range is greater than the 16422size of the data_list, the data_list is repeated. 16423 16424@item hunt <address_range> <data_list> 16425@itemx h <address_range> <data_list> 16426Hunt memory in the specified address range for the data in 16427<data_list>. If the data is found, the starting address of the match 16428is displayed. The entire range is searched for all possible matches. 16429The data list may have `xx' as a wildcard. 16430 16431@item i <address_opt_range> 16432Display memory contents as PETSCII text. 16433 16434@item ii <address_opt_range> 16435Display memory contents as screen code text 16436 16437@item mem [<data_type>] [<address_opt_range>] 16438@itemx m [<data_type>] [<address_opt_range>] 16439Display the contents of memory. If no datatype is given, the default 16440is used. If only one address is specified, the length of data 16441displayed is based on the datatype. If no addresses are given, the 16442'dot' address is used. 16443 16444@item memmapshow [<mask>] [<address_opt_range>] 16445@itemx mmsh [<mask>] [<address_opt_range>] 16446Show the memmap. The mask can be specified to show only those 16447locations with accesses of certain type(s). The mask is a number 16448with the bits "ioRWXrwx", where RWX are for ROM and rwx for RAM. 16449Optionally, an address range can be specified. 16450(disabled by default; configure with --enable-cpuhistory to enable) 16451 16452@item memmapzap 16453@itemx mmzap 16454Clear the memmap. 16455(disabled by default; configure with --enable-cpuhistory to enable) 16456 16457@item memmapsave "<filename>" <format> 16458@itemx mmsave "<filename>" <format> 16459Save the memmap as a picture. @code{format}: 164600 = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF. 16461(disabled by default; configure with --enable-cpuhistory to enable) 16462 16463@item memchar [<data_type>] [<address_opt_range>] 16464@itemx mc [<data_type>] [<address_opt_range>] 16465Display the contents of memory as character data. If only one address 16466is specified, only one character is displayed. If no addresses are 16467given, the ``dot'' address is used. 16468 16469@item memsprite [<data_type>] [<address_opt_range>] 16470@itemx ms [<data_type>] [<address_opt_range>] 16471Display the contents of memory as sprite data. If only one address is 16472specified, only one sprite is displayed. If no addresses are given, 16473the ``dot'' address is used. 16474 16475@item move <address_range> <address> 16476@itemx t <address_range> <address> 16477Move memory from the source specified by the address range to the 16478destination specified by the address. The regions may overlap. 16479 16480@item screen 16481@itemx sc 16482Displays the contents of the screen. 16483 16484@item sidefx [on|off|toggle] 16485@itemx sfx [on|off|toggle] 16486Control how monitor generated reads affect memory locations that have 16487read side-effects, like CIA interrupt registers for example. 16488If the argument is 'on' then reads may cause side-effects. If the 16489argument is 'off' then reads don't cause side-effects. If the 16490argument is 'toggle' then the current mode is switched. No argument 16491displays the current state. 16492 16493@item > [<address>] <data_list> 16494Write the specified data at @code{address}. 16495 16496@end table 16497 16498@node Assembly commands, Checkpoint commands, Memory commands, Monitor 16499@section Assembly commands 16500 16501@table @code 16502 16503@item a <address> [ <instruction> [: <instruction>]* ] 16504Assemble instructions to the specified address. If only one 16505instruction is specified, enter assembly mode (enter an empty line to 16506exit assembly mode). 16507 16508@item disass [<address> [<address>]] 16509@itemx d [<address> [<address>]] 16510Disassemble instructions. If two addresses are specified, they are 16511used as a start and end address. If only one is specified, it is 16512treated as the start address and a default number of instructions are 16513disassembled. If no addresses are specified, a default number of 16514instructions are disassembled from the dot address. 16515 16516@end table 16517 16518@node Checkpoint commands, General commands, Assembly commands, Monitor 16519@section Checkpoint commands 16520 16521 16522@table @code 16523 16524@item break [load|store|exec] [address [address] [if <cond_expr>]] 16525This command allows setting a breakpoint or listing the current 16526breakpoints. If no address is given, the currently valid checkpoints 16527are printed. If an address is given, a breakpoint is set for that 16528address and the breakpoint number is printed. 16529The "load|store|exec" parameter can be either "load", "store" or "exec" 16530(or any combination of these) to determine on which operation the 16531monitor breaks. If not specified, the monitor breaks on "exec". 16532A conditional expression can also be specified for the breakpoint. 16533For more information on conditions, see the CONDITION command. 16534 16535@item enable <checknum> 16536@item disable <checknum> 16537Each checkpoint can be enabled or disabled. This command allows 16538changing between these states. 16539 16540@item command <checknum> "<command>" 16541When checkpoint @code{checknum} is hit, the specified command is 16542executed by the monitor. Note that the @code{x} command is not yet 16543supported as a command argument. 16544 16545@item condition <checknum> if <cond_expr> 16546@itemx cond <checknum> if <cond_expr> 16547Each time the specified checkpoint is examined, the condition is 16548evaluated. If it evalutes to true, the checkpoint is activated. 16549Otherwise, it is ignored. If registers are specified in the 16550expression, the values used are those at the time the checkpoint is 16551examined, not when the condition is set. 16552 16553The condition can use registers (A, X, Y, PC, SP, FL and other cpu 16554specific registers (see manual)) and compare them (==, !=, <, >, <=, >=) 16555against other registers or constants. RL can be used to refer to the 16556current rasterline, and CY refers to the current cycle in the line. 16557 16558Full expressions are also supported (+, -, *, /, &&, ||). This let's 16559you f.e. to check specific bits in the FL register using the bitwise 16560boolean operators. Paranthises are also supported in the expression. 16561Registers can be the registers of other devices; this is denoted by 16562a memspace prefix (i.e., c:, 8:, 9:, 10:, 11: 16563Examples: A == $0, X == Y, 8:X == X) 16564You can also compare against the value of a memory location in a specific 16565bank, i.e you can break only if the vic register $d020 is $f0. 16566use the form @@[bankname]:[$<address>] | [.label]. 16567Note this is for the C : memspace only. 16568Examples : if @@io:$d020 == $f0, if @@io:.vicBorder == $f0 16569 16570@item delete <checknum> 16571@itemx del <checknum> 16572Delete the specified checkpoint. 16573 16574@item ignore <checknum> [<count>] 16575Ignore a checkpoint after a given number of crossings. If no count is 16576given, the default value is 1. 16577 16578@item trace [load|store|exec] [address [address] [if <cond_expr>]] 16579@itemx tr [load|store|exec] [address [address] [if <cond_expr>]] 16580This command is similar to the @code{break} command except that it 16581operates on tracepoints. A tracepoint differs from a breakpoint by 16582not stopping execution but simply printing the PC, giving the user an 16583execution trace. The second optional address can be used to specify 16584the end of an range of addresses to be traced. 16585If no addresses are given, a list of all the checkpoints is printed. 16586The "load|store|exec" parameter can be either "load", "store" or "exec" 16587(or any combination of these) to determine which operation the 16588monitor traces. If not specified, the monitor traces all operations. 16589A conditional expression can also be specified for the tracepoint. 16590For more information on conditions, see the CONDITION command. 16591 16592@item until [<address>] 16593@itemx un [<address>] 16594If no address is given, the currently valid breakpoints are printed. 16595If an address is given, a temporary breakpoint is set for that address 16596and the breakpoint number is printed. Control is returned to the 16597emulator by this command. The breakpoint is deleted once it is hit. 16598 16599@item watch [load|store|exec] [address [address] [if <cond_expr>]] 16600@itemx w [load|store|exec] [address [address] [if <cond_expr>]] 16601This command is similar to the @code{break} command except that it 16602operates on watchpoints. A watchpoint differs from a breakpoint by 16603stopping on a read and/or write to an address or range of addresses. 16604If no addresses are given, a list of all the checkpoints is printed. 16605The "load|store|exec" parameter can be either "load", "store" or "exec" 16606(or any combination of these) to determine on which operation the 16607monitor breaks. If not specified, the monitor breaks on "load" and 16608"store" operations. 16609A conditional expression can also be specified for the watchpoint. 16610For more information on conditions, see the CONDITION command. 16611 16612@item dummy [on|off|toggle] 16613Control whether the checkpoints will trigger on dummy accesses. 16614If the argument is 'on' then dummy accesses will cause checkpoints 16615to trigger. If the argument is 'off' then dummy accesses will not 16616trigger any checkpoints. If the argument is 'toggle' then the current 16617mode is switched. No argument displays the current state. 16618 16619@end table 16620 16621 16622@node General commands, Disk commands, Checkpoint commands, Monitor 16623@section General commands 16624 16625 16626@table @code 16627 16628@item cd <directory> 16629Change the working directory. 16630 16631@item device [c:|8:|9:] 16632@itemx dev [c:|8:|9:] 16633Set the default address space to either the computer (@code{c:}) or 16634the disk (@code{8:|9:}). 16635 16636@item dir [<directory>] 16637@itemx ls [<directory>] 16638Display the directory contents. 16639 16640@item pwd 16641Show current working directory. 16642 16643@item mkdir <directory> 16644Create directory. 16645 16646@item rmdir <directory> 16647Remove directory. 16648 16649@item radix [H|D|O|B] 16650@itemx rad [H|D|O|B] 16651Set the default radix to hex, decimal, octal, or binary. With no 16652argument, the current radix is printed. 16653 16654@item log [on|off|toggle] 16655Control whether the monitor output is logged into a logfile. If the 16656argument is 'on' then all output will be written into the logfile. If 16657the argument is 'off' then no log is produced. If the argument is 16658'toggle' then the current mode is switched. No argument displays the 16659current state. 16660 16661@item logname "<filename>" 16662Sets the filename of the logfile. 16663 16664@end table 16665 16666 16667@node Disk commands, Command file commands, General commands, Monitor 16668@section Disk commands 16669 16670@table @code 16671 16672@item attach <filename> <device> 16673Attach file to device. (device 32 = cart) 16674 16675@item block_read <track> <sector> [<address>] 16676@itemx br <track> <sector> [<address>] 16677Read the block at the specified track and sector. If an address is 16678specified, the data is loaded into memory. If no address is given, 16679the data is displayed using the default datatype. 16680 16681@item block_write <track> <sector> <address> 16682@itemx bw <track> <sector> <address> 16683Write a block of data at @code{address} to the specified track and 16684sector of disk in drive 8. 16685 16686@item detach <device> 16687Detach file from device. (device 32 = cart) 16688 16689@item @@<disk command> 16690Perform a disk command on the currently attached disk image on drive 166918. The specified disk command is sent to the drive's channel #15. 16692 16693@item list [<directory>] 16694List disk contents. 16695 16696@item load "<filename>" <device> [<address>] 16697@itemx l "<filename>" <device> [<address>] 16698Load the specified file into memory. If no address is given, the file 16699is loaded to the address specified by the first two bytes read from 16700the file. If address is given, the file is loaded to the specified 16701address and the first two bytes read from the file are skipped. If 16702device is 0, the file is read from the file system. 16703 16704@item bload "<filename>" <device> <address> 16705@itemx bl "<filename>" <device> <address> 16706Load the specified file into memory at the specified address. 16707If device is 0, the file is read from the file system. 16708 16709@item save "<filename>" <device> <address1> <address2> 16710@itemx s "<filename>" <device> <address1> <address2> 16711Save the memory from address1 to address2 to the specified file. 16712Write two-byte load address. 16713If device is 0, the file is written to the file system. 16714 16715@item bsave "<filename>" <device> <address1> <address2> 16716@itemx bs "<filename>" <device> <address1> <address2> 16717Save the memory from address1 to address2 to the specified file. 16718If device is 0, the file is written to the file system. 16719 16720@item verify "<filename>" <device> [<address>] 16721@itemx v "<filename>" <device> [<address>] 16722Compare the specified file with memory. If no address is given, the 16723address is specified by the first two bytes read from 16724the file. If address is given, the specified address is used and the 16725first two bytes read from the file are skipped. If 16726device is 0, the file is read from the file system. 16727 16728@item bverify "<filename>" <device> <address> 16729@itemx bv "<filename>" <device> <address> 16730Compare the specified file with memory at the specified address. 16731If device is 0, the file is read from the file system. 16732 16733@end table 16734 16735 16736@node Command file commands, Label commands, Disk commands, Monitor 16737@section Command file commands 16738 16739 16740@table @code 16741 16742@item playback "<filename>" 16743@itemx pb "<filename>" 16744Monitor commands from the specified file are read and executed. This 16745command stops at the end of file or when a STOP command is read. 16746 16747@item record "<filename>" 16748@itemx rec "<filename>" 16749After this command, all commands entered are written to the specified 16750file until the STOP command is entered. 16751 16752@item stop 16753Stop recording commands. See @code{record}. 16754 16755@end table 16756 16757@node Label commands, Miscellaneous commands, Command file commands, Monitor 16758@section Label commands 16759 16760 16761@table @code 16762 16763 16764@item add_label <address> <label> 16765@itemx al <address> <label> 16766Map a given address to a label. This label can be used when entering 16767assembly code and is shown during disassembly. Additionally, it can 16768be used whenever an address must be specified. 16769 16770<label> is the name of the label; it must start with a dot (".") in 16771order for the monitor to recognize it as a label. 16772 16773@item delete_label [<address_space>] <label> 16774@itemx dl [<address_space>] <label> 16775Remove the specified label from the label tables. If no address space is 16776checked, all tables are checked. 16777 16778@item load_labels [<address_space>] "<filename>" 16779@itemx ll [<address_space>] "<filename>" 16780Load a file containing a mapping of labels to addresses. If no address 16781space is specified, the default readspace is used. 16782 16783The file must contain commands the monitor understands, e.g. add_label. The 16784compiler cc65 can create such label files. 16785 16786Vice can also load label files created by the Acme assembler. Their syntax is 16787e.g. "labelname = $1234 ; Maybe a comment". A dot will be added automatically 16788to label names assigned in this way to fit to the Vice label syntax. Normally 16789the semicolon seperates commands but after an assignment of this kind it may be 16790used to start a comment to end of line, so unchanged Acme label files can be 16791fed into Vice. 16792 16793@item save_labels [<address_space>] "<filename>" 16794@itemx sl [<address_space>] "<filename>" 16795Save labels to a file. If no address space is specified, all of the 16796labels are saved. 16797 16798@item show_labels [<address_space>] 16799@itemx shl [<address_space>] 16800Display current label mappings. If no address space is specified, show 16801all labels from default address space. 16802 16803@item clear_labels [<address_space>] 16804@itemx cl [<address_space>] 16805Clear current label mappings. If no address space is specified, clear 16806all labels from default address space. 16807 16808@end table 16809 16810 16811@node Miscellaneous commands, , Label commands, Monitor 16812@section Miscellaneous commands 16813 16814 16815@table @code 16816 16817@item ; <text> 16818Add a comment to a file to be read by the monitor. For example: 16819@example 16820; Set border and background to black 16821> d020 00 00 16822@end example 16823 16824@item cartfreeze 16825Use cartridge freeze. 16826 16827@item cpu <type> 16828Specify the type of CPU currently used (6502/z80). 16829 16830@item exit 16831@itemx x 16832Leave the monitor and return to execution. 16833 16834@item export 16835@itemx exp 16836Print out list of attached expansion port devices. 16837 16838@item help [<command>] 16839If no argument is given, prints out a list of all available commands. 16840If an argument is given, prints out specific help for that command. 16841 16842@item keybuf "<string>" 16843Put the specified string into the keyboard buffer. Note that you can specify 16844specific keycodes by using C-style escaped hexcodes ("\x0a"). 16845 16846@item print <expression> 16847@itemx p <expression> 16848Evaluate the specified expression and output the result. 16849 16850@item resourceget "<resource>" 16851@itemx resget "<resource>" 16852Displays the value of the @code{resource}. 16853 16854@item resourceset "<resource>" "<value>" 16855@itemx resset "<resource>" "<value>" 16856Sets the value of the @code{resource}. 16857 16858@item load_resources "<file>" 16859@itemx resload "<file>" 16860Load resources from @code{file}. 16861 16862@item save_resources "<file>" 16863@itemx ressave "<file>" 16864Save resources to @code{file}. 16865 16866@item screenshot "<filename>" [<format>] 16867@itemx scrsh "<filename>" [<format>] 16868Take a screenshot. @code{format}: 16869default = BMP, 1 = PCX, 2 = PNG, 3 = GIF, 4 = IFF. 16870 16871@item tapectrl <command> 16872Control the datasette. @code{command}: 168730 = stop, 1 = start, 2 = forward, 3 = rewind, 4 = record, 168745 = reset, 6 = reset counter. 16875 16876@item quit 16877@itemx q 16878Exit the emulator immediately. 16879 16880@item ~ <number> 16881Display the specified number in decimal, hex, octal and binary. 16882 16883@end table 16884 16885@node Binary monitor 16886@chapter Binary monitor 16887The binary remote monitor commands are sent over a dedicated connection, specified 16888with the command line options @code{-binarymonitor} & @code{-binarymonitoraddress}. @xref{Monitor settings}. 16889The remote monitor detects a binary command because it starts with ASCII STX 16890(0x02). Note that there is no termination character. The command length acts as 16891synchronisation point. 16892 16893All multibyte values are in little endian order unless otherwise specified. 16894 16895@menu 16896* Binary Command Structure:: 16897* Binary Response Structure:: 16898* Binary Monitor Example Exchange:: 16899* Binary Commands:: 16900* Binary Responses:: 16901@end menu 16902 16903@node Binary Command Structure 16904@section Command Structure 16905 16906@table @strong 16907 16908@item byte 0: 0x02 (STX) 16909@item byte 1: API version ID (currently 0x01) 16910The API version identifies incompatible changes, such as modifying the header 16911structure, or rearranging or changing the meaning of existing response fields. 16912The API version does not need to be incremented for additional fields. If all 16913the variable length fields are prefixed with their lengths then you should be 16914able to add new ones to any response. The server can assume default values for 16915older clients, and for newer clients with longer commands 16916it should be able to ignore the extra fields safely. 16917 16918@item byte 2-5: length 16919Note that the command length does *not* count the STX, the command length, 16920the command byte, or the request ID. Basically nothing in the header, 16921just the body. 16922 16923@item byte 6-9: request id 16924In little endian order. All multibyte values are in little endian order, 16925unless otherwise specified. There is no requirement for this to be unique, 16926but it makes it easier to match up the responses if you do. 16927 16928@item byte 10: The numeric command type 16929@xref{Binary Commands}. 16930 16931@item byte 11+: The command body. 16932@xref{Binary Commands}. 16933 16934@end table 16935 16936@node Binary Response Structure 16937@section Response Structure 16938 16939@table @strong 16940 16941@item byte 0: 0x02 (STX) 16942@item byte 1: API version ID (currently 0x01) 16943The API version identifies incompatible changes, such as modifying the header 16944structure, or rearranging or changing the meaning of existing response fields. 16945The API version does not need to be incremented for additional fields. If all 16946the variable length fields are prefixed with their lengths then you should be 16947able to add new ones to any response. The client can assume default values for 16948older versions of VICE, and for newer versions of VICE with longer responses 16949it should be able to ignore the extra fields safely. 16950 16951@item byte 2-5: response body length. Does not include any header fields 16952 16953@item byte 6: response type 16954This is usually the same as the command ID 16955 16956@item byte 7: error code 16957 16958@table @code 16959@item 0x00 16960OK, everything worked 16961 16962@item 0x01 16963The object you are trying to get or set doesn't exist. 16964 16965@item 0x02 16966The memspace is invalid 16967 16968@item 0x80 16969Command length is not correct for this command 16970 16971@item 0x81 16972An invalid parameter value was present 16973 16974@item 0x82 16975The API version is not understood by the server 16976 16977@item 0x83 16978The command type is not understood by the server 16979 16980@item 0x8f 16981The command had parameter values that passed basic checks, but a general failure occurred 16982@* 16983@* 16984@xref{Binary Commands} for other error codes 16985 16986@end table 16987 16988@item byte 8-11: request ID 16989This is the request ID given to initiate this response. 16990If the value is 0xffffffff, Then the response was initiated by an event, 16991such as hitting a checkpoint. 16992 16993@item byte 12+: response body. 16994@xref{Binary Commands}. 16995 16996@end table 16997 16998@node Binary Monitor Example Exchange 16999@section Example Exchange 17000 17001@enumerate 17002 17003@item Client connects to ip4://127.0.0.1:6502 17004 17005@item Client sends a command to set a temporary checkpoint: 17006@* 17007@* @code{02 | 01 | 08 00 00 00 | ad de 34 12 | 12 | e2 fc | e3 fc | 01 | 01 | 04 | 01 } 17008@* 17009@* 17010 17011@table @code 17012@item 0x02 17013Begin command 17014 17015@item 0x01 17016API version 1 17017 17018@item 0x00000008 17019The command excluding the header is 8 bytes long. 17020 17021@item 0x1234dead 17022The request ID is 0x1234dead. The response will contain this ID. 17023 17024@item 0x12 17025@xref{MON_CMD_CHECKPOINT_SET}. 17026 17027@item 0xfce2 17028The address range of the checkpoint starts at 0xfce2. 17029 17030@item 0xfce3 17031The address range of the checkpoint ends at 0xfce3. 17032 17033@item 0x01 17034The checkpoint will cause the emulator to stop. 17035 17036@item 0x01 17037The checkpoint is enabled. 17038 17039@item 0x04 17040The checkpoint will trigger on exec from 0xfce2 - 0xfce3. 17041 17042@item 0x01 17043The checkpoint is temporary. 17044 17045@end table 17046 17047@item The transmission of any command causes the emulator to stop, similar to 17048the regular monitor. This causes the server to respond with a list of register 17049values. @* 17050@* 17051@code{02 | 01 | 26 00 00 00 | 31 | 00 | ff ff ff ff | 09 00 [ 03 @{ 03 | cf e5 @} 03 @{ 00 | 00 00 @} ... ] } @* 17052@* 17053 17054@table @code 17055@item 0x02 17056Begin response 17057 17058@item 0x01 17059API Version 1 17060 17061@item 0x00000026 17062Response length is 38 17063 17064@item 0x31 17065@xref{MON_RESPONSE_REGISTER_INFO}. 17066 17067@item 0x00 17068No error occurred 17069 17070@item 0xffffffff 17071This response was not directly triggered by a command from the client. 17072 17073@item 0x0009 17074The register array is 9 items long 17075 17076@item @strong{PC:} 17077@table @code 17078@item 0x03 17079The register array item is 3 bytes long 17080 17081@item 0x03 17082The register is the PC (ID 3) Note: you should find the names to these IDs using 17083the MON_CMD_REGISTERS_AVAILABLE command. @xref{MON_CMD_REGISTERS_AVAILABLE}. 17084Do not rely on them being consistent. 17085 17086@item 0xe5cf 17087The register value is 0xe5cf 17088 17089@end table 17090 17091@item @strong{A:} 17092@table @code 17093@item 0x03 17094The register array item is 3 bytes long 17095 17096@item 0x00 17097The register is A (ID 0) Note: you should find the names to these IDs using 17098the MON_CMD_REGISTERS_AVAILABLE command. @xref{MON_CMD_REGISTERS_AVAILABLE}. 17099Do not rely on them being consistent. 17100 17101@item 0x0000 17102The register value is 0x0000 17103 17104@end table 17105 17106@end table 17107 17108@item After the register information, the server sends a stopped event to indicate that the emulator is stopped. @* 17109@* 17110@code{02 | 01 | 02 00 00 00 | 62 | 00 | ff ff ff ff | cf e5 } @* 17111@* 17112 17113@table @code 17114@item 0x02 17115Begin response 17116 17117@item 0x01 17118API Version 1 17119 17120@item 0x00000002 17121Response is two bytes long. 17122 17123@item 0x62 17124Response type is 0x62, MON_RESPONSE_STOPPED. 17125 17126@item 0xffffffff 17127This response was not directly triggered by a command from the client. 17128 17129@item 0xe5cf 17130The current program counter 17131 17132@end table 17133 17134@item The server processes the checkpoint set command, and sends a response to the client. @* 17135@* 17136@code{ ... | 11 | ... | 02 00 00 00 | 00 | e2 fc | e3 fc | 01 | 01 | 04 | 01 | 00 00 00 00 | 00 00 00 00 | 00}@* 17137(Some response header fields are omitted (...) for brevity.)@* 17138@* 17139 17140@table @code 17141@item 0x11 17142@xref{MON_RESPONSE_CHECKPOINT_INFO}. 17143 17144@item 0x00000002 17145Checkpoint number is 2 17146 17147@item 0x00 17148Checkpoint was not hit (as it was just created) 17149 17150@item 0xfce2 17151Checkpoint start address 17152 17153@item 0xfce3 17154Checkpoint end address 17155 17156@item 0x01 17157The checkpoint will cause the emulator to stop. 17158 17159@item 0x01 17160The checkpoint is enabled. 17161 17162@item 0x04 17163The checkpoint will trigger on exec from 0xfce2 - 0xfce3. 17164 17165@item 0x01 17166The checkpoint is temporary. 17167 17168@item 0x00000000 17169The checkpoint has been hit zero times. 17170 17171@item 0x00000000 17172The checkpoint has been ignored zero times. 17173 17174@end table 17175 17176@item Client sends a command to continue:@* 17177@* 17178@code{ ... | aa }@* 17179(Some command header fields are omitted (...) for brevity.)@* 17180@* 17181 17182@table @code 17183@item 0xaa 17184@xref{MON_CMD_EXIT}. 17185 17186@end table 17187 17188@item Server acknowledges the command:@* 17189@* 17190@code{ ... | aa | ... } @* 17191(Some response header fields are omitted (...) for brevity.)@* 17192@* 17193 17194@table @code 17195@item 0xaa 17196@xref{MON_CMD_EXIT}. 17197 17198@end table 17199 17200@item Server resumes execution and sends a resume event:@* 17201@* 17202@code{ ... | 63 | ... | cf e5 } @* 17203(Some response header fields are omitted (...) for brevity.)@* 17204@* 17205 17206@table @code 17207@item 0x63 17208@xref{MON_RESPONSE_RESUMED}. 17209 17210@item 0xe5cf 17211Program counter is currently at 0xe5cf 17212 17213@end table 17214 17215@item Some time later, the server hits the breakpoint. This causes it to emit 17216a checkpoint response. This is identical to the previous checkpoint response, 17217except that it is marked as "hit" and the hit and ignore counts are updated. 17218 17219@item The server emits the register information and the stopped event when 17220reentering the monitor, as seen previously. 17221 17222@end enumerate 17223 17224@node Binary Commands 17225@section Commands 17226 17227These are the possible command types and responses, without the header portions 17228mentioned above. 17229 17230@menu 17231* MON_CMD_MEM_GET:: 17232* MON_CMD_MEM_SET:: 17233* MON_CMD_CHECKPOINT_GET:: 17234* MON_CMD_CHECKPOINT_SET:: 17235* MON_CMD_CHECKPOINT_DELETE:: 17236* MON_CMD_CHECKPOINT_LIST:: 17237* MON_CMD_CHECKPOINT_TOGGLE:: 17238* MON_CMD_CONDITION_SET:: 17239* MON_CMD_REGISTERS_GET:: 17240* MON_CMD_REGISTERS_SET:: 17241* MON_CMD_DUMP:: 17242* MON_CMD_UNDUMP:: 17243* MON_CMD_RESOURCE_GET:: 17244* MON_CMD_RESOURCE_SET:: 17245* MON_CMD_ADVANCE_INSTRUCTIONS:: 17246* MON_CMD_KEYBOARD_FEED:: 17247* MON_CMD_EXECUTE_UNTIL_RETURN:: 17248* MON_CMD_PING:: 17249* MON_CMD_BANKS_AVAILABLE:: 17250* MON_CMD_REGISTERS_AVAILABLE:: 17251* MON_CMD_DISPLAY_GET:: 17252* MON_CMD_EXIT:: 17253* MON_CMD_QUIT:: 17254* MON_CMD_RESET:: 17255* MON_CMD_AUTOSTART:: 17256@end menu 17257 17258@node MON_CMD_MEM_GET 17259@subsection Memory get (0x01) 17260 17261Reads a chunk of memory from a start address to an end address (inclusive). 17262 17263Command body: 17264 17265@table @strong 17266@item byte 0: side effects? 17267Should the read cause side effects? 17268 17269@item byte 1-2: start address 17270 17271@item byte 3-4: end address 17272 17273@item byte 5: memspace 17274Describes which part of the computer you want to read: 17275 17276@itemize 17277@item 0x00: main memory 17278@item 0x01: drive 8 17279@item 0x02: drive 9 17280@item 0x03: drive 10 17281@item 0x04: drive 11 17282@end itemize 17283 17284@item byte 6-7: bank ID 17285Describes which bank you want. This is dependent on your 17286machine. @xref{MON_CMD_BANKS_AVAILABLE}. If the memspace selected 17287doesn't support banks, this value is ignored. 17288 17289@end table 17290 17291Response type: 17292 172930x01: MON_RESPONSE_MEM_GET 17294 17295Response body: 17296 17297@table @strong 17298@item byte 0-1: The length of the memory segment. 17299 17300@item byte 2+: The memory at the address. 17301 17302@end table 17303 17304@node MON_CMD_MEM_SET 17305@subsection Memory set (0x02) 17306 17307Writes a chunk of memory from a start address to an end address (inclusive). 17308 17309Command body: 17310 17311@table @strong 17312@item byte 0: side effects? 17313Should the write cause side effects? 17314 17315@item byte 1-2: start address 17316 17317@item byte 3-4: end address 17318 17319@item byte 5: memspace 17320Describes which part of the computer you want to write: 17321 17322@itemize 17323@item 0x00: main memory 17324@item 0x01: drive 8 17325@item 0x02: drive 9 17326@item 0x03: drive 10 17327@item 0x04: drive 11 17328@end itemize 17329 17330@item byte 6-7: bank ID 17331Describes which bank you want. This is dependent on your machine. 17332@xref{MON_CMD_BANKS_AVAILABLE}. 17333If the memspace selected doesn't support banks, this byte is ignored. 17334 17335@item byte 8+: Memory contents to write 17336 17337@end table 17338 17339Response type: 17340 173410x02: MON_RESPONSE_MEM_SET 17342 17343Response body: 17344 17345Currently empty. 17346 17347@node MON_CMD_CHECKPOINT_GET 17348@subsection Checkpoint get (0x11) 17349 17350Gets any type of checkpoint. (break, watch, trace) 17351 17352Command body: 17353 17354@table @strong 17355@item byte 0-3: checkpoint number 17356 17357@end table 17358 17359@xref{MON_RESPONSE_CHECKPOINT_INFO}. 17360 17361@node MON_CMD_CHECKPOINT_SET 17362@subsection Checkpoint set (0x12) 17363 17364Sets any type of checkpoint. This combines the functionality of several 17365textual commands (break, watch, trace) into one, as they are all the same 17366with only minor variations. To set conditions, @pxref{MON_CMD_CONDITION_SET} after 17367executing this one. 17368 17369Command body: 17370 17371@table @strong 17372@item byte 0-1: start address 17373 17374@item byte 2-3: end address 17375 17376@item byte 4: stop when hit 173770x01: true, 0x00: false 17378 17379@item byte 5: enabled 173800x01: true, 0x00: false 17381 17382@item byte 6: CPU operation 173830x01: load, 0x02: store, 0x04: exec 17384 17385@item byte 7: temporary 17386 Deletes the checkpoint after it has been hit once. This is similar to 17387 "until" command, but it will not resume the emulator. 17388 17389@end table 17390 17391@xref{MON_RESPONSE_CHECKPOINT_INFO}. 17392 17393@node MON_CMD_CHECKPOINT_DELETE 17394@subsection Checkpoint delete (0x13) 17395 17396Deletes any type of checkpoint. (break, watch, trace) 17397 17398Command body: 17399 17400@table @strong 17401@item byte 0-3: checkpoint number 17402 17403@end table 17404 17405Response type: 17406 174070x13: MON_RESPONSE_CHECKPOINT_DELETE 17408 17409Response body: 17410 17411Currently empty. 17412 17413@node MON_CMD_CHECKPOINT_LIST 17414@subsection Checkpoint list (0x14) 17415 17416Command body: 17417 17418Currently empty. 17419 17420Response type: 17421 17422Emits a series of MON_RESPONSE_CHECKPOINT_INFO responses 17423(@pxref{MON_RESPONSE_CHECKPOINT_INFO}) followed by 17424 174250x14: MON_RESPONSE_CHECKPOINT_LIST 17426 17427Response body: 17428 17429@table @strong 17430@item byte 0-3: The total number of checkpoints 17431 17432@end table 17433 17434@node MON_CMD_CHECKPOINT_TOGGLE 17435@subsection Checkpoint toggle (0x15) 17436 17437Command body: 17438 17439@table @strong 17440@item byte 0-3: Checkpoint number 17441 17442@item byte 4: Enabled? 174430x00: disabled, 0x01: enabled 17444 17445@end table 17446 17447Response type: 17448 174490x15: MON_RESPONSE_CHECKPOINT_TOGGLE 17450 17451Response body: 17452 17453Currently empty. 17454 17455@node MON_CMD_CONDITION_SET 17456@subsection Condition set (0x22) 17457 17458Sets a condition on an existing checkpoint. It is not currently possible to 17459retrieve conditions after setting them. 17460 17461Command body: 17462 17463@table @strong 17464@item byte 0-3: checkpoint number 17465 17466@item byte 4: condition expression length 17467 17468@item byte 5+: condition expression string 17469This is the same format used on the command line. Not null terminated. 17470 17471@end table 17472 17473Response type: 17474 174750x22: MON_RESPONSE_CONDITION_SET 17476 17477Response body: 17478 17479Currently empty. 17480 17481@node MON_CMD_REGISTERS_GET 17482@subsection Registers get (0x31) 17483 17484Get details about the registers 17485 17486Command body: 17487 17488@table @strong 17489@item byte 0: memspace 17490Describes which part of the computer you want to read: 17491 17492@itemize 17493@item 0x00: main memory 17494@item 0x01: drive 8 17495@item 0x02: drive 9 17496@item 0x03: drive 10 17497@item 0x04: drive 11 17498@end itemize 17499 17500@end table 17501 17502@xref{MON_RESPONSE_REGISTER_INFO}. 17503 17504@node MON_CMD_REGISTERS_SET 17505@subsection Registers set (0x32) 17506 17507Set the register values 17508 17509Command body: 17510 17511@table @strong 17512@item byte 0: memspace 17513Describes which part of the computer you want to write: 17514 17515@itemize 17516@item 0x00: main memory 17517@item 0x01: drive 8 17518@item 0x02: drive 9 17519@item 0x03: drive 10 17520@item 0x04: drive 11 17521@end itemize 17522 17523@item byte 1-2: The count of the array items 17524 17525@item byte 2+: An array with items of structure: 17526 byte 0: Size of the item, excluding this byte 17527 byte 1: ID of the register 17528 byte 2-3: register value 17529 17530@end table 17531 17532@xref{MON_RESPONSE_REGISTER_INFO}. 17533 17534@node MON_CMD_DUMP 17535@subsection Dump (0x41) 17536 17537Saves the machine state to a file. 17538 17539Command body: 17540 17541@table @strong 17542@item byte 0: Save ROMs to snapshot file? 175430x01: true, 0x00: false 17544 17545@item byte 1: Save disks to snapshot file? 175460x01: true, 0x00: false 17547 17548@item byte 2: Length of filename 17549 17550@item byte 3+: Filename 17551The filename to save the snapshot to. 17552 17553@end table 17554 17555Response type: 17556 175570x41: MON_RESPONSE_DUMP 17558 17559Response body: 17560 17561Currently empty. 17562 17563@node MON_CMD_UNDUMP 17564@subsection Undump (0x42) 17565 17566Loads the machine state from a file. 17567 17568Command body: 17569 17570@table @strong 17571@item byte 0: Length of filename 17572 17573@item byte 1+: Filename 17574The filename to load the snapshot from. 17575 17576@end table 17577 17578Response type: 17579 175800x42: MON_RESPONSE_UNDUMP 17581 17582Response body: 17583 17584@table @strong 17585@item byte 0-1: The current program counter position 17586 17587@end table 17588 17589@node MON_CMD_RESOURCE_GET 17590@subsection Resource Get (0x51) 17591 17592Get a resource value from the emulator. @xref{Resource files, Resources and command-line, Settings and resources, Settings and resources}. 17593 17594Command body: 17595 17596@table @strong 17597@item byte 0: Length of resource name 17598 17599@item byte 1+: Resource name 17600 17601@end table 17602 17603Response type: 17604 176050x51: MON_RESPONSE_RESOURCE_GET 17606 17607Response body: 17608 17609@table @strong 17610@item byte 0: Type of the resource 176110x00: String, 0x01: Integer 17612 17613@item byte 1: Length of the value 17614 17615@item byte 2+: The value 17616 17617@end table 17618 17619@node MON_CMD_RESOURCE_SET 17620@subsection Resource Set (0x52) 17621 17622Set a resource value in the emulator. @xref{Resource files, Resources and command-line, Settings and resources, Settings and resources}. 17623 17624Command body: 17625 17626@table @strong 17627@item 1 byte: Type of the resource value 176280x00: String, 0x01: Integer@* 17629Strings will be interpreted if the destination is an Integer. 17630 17631@item 1 byte: Resource name length = (&name) 17632 17633@item (*name) bytes: The resource name 17634 17635@item 1 byte: Resource value length = (&value) 17636 17637@item (*value) bytes: The resource value 17638 17639@end table 17640 17641Response type: 17642 176430x52: MON_RESPONSE_RESOURCE_SET 17644 17645Response body: 17646 17647Currently empty. 17648 17649@node MON_CMD_ADVANCE_INSTRUCTIONS 17650@subsection Advance Instructions (0x71) 17651 17652Step over a certain number of instructions. 17653 17654Command body: 17655 17656@table @strong 17657@item byte 0: Step over subroutines? 17658Should subroutines count as a single instruction? 17659 17660@item byte 1-2: How many instructions to step over. 17661 17662@end table 17663 17664Response type: 17665 176660x71: MON_RESPONSE_ADVANCE_INSTRUCTIONS 17667 17668Response body: 17669 17670Currently empty. 17671 17672@node MON_CMD_KEYBOARD_FEED 17673@subsection Keyboard feed (0x72) 17674 17675Add text to the keyboard buffer. 17676 17677Command body: 17678 17679@table @strong 17680@item byte 0: Length of text 17681 17682@item byte 1+: The text 17683Special characters such as return are escaped with backslashes. 17684 17685@end table 17686 17687Response type: 17688 176890x72: MON_RESPONSE_KEYBOARD_FEED 17690 17691Response body: 17692 17693Currently empty. 17694 17695@node MON_CMD_EXECUTE_UNTIL_RETURN 17696@subsection Execute until return (0x73) 17697 17698Continues execution and returns to the monitor just after the next RTS or RTI is executed. 17699 17700This command is the same as "return" in the text monitor. 17701 17702Command body: 17703 17704Currently empty. 17705 17706Response type: 17707 177080x73: MON_RESPONSE_EXECUTE_UNTIL_RETURN 17709 17710Response body: 17711 17712Currently empty. 17713 17714@node MON_CMD_PING 17715@subsection Ping (0x81) 17716 17717Get an empty response 17718 17719Command body: 17720 17721Always empty 17722 17723Response type: 17724 177250x81: MON_RESPONSE_PING 17726 17727Response body: 17728 17729Always empty 17730 17731@node MON_CMD_BANKS_AVAILABLE 17732@subsection Banks available (0x82) 17733 17734Gives a listing of all the bank IDs for the running machine with their names. 17735 17736Command body: 17737 17738Currently empty. 17739 17740Response type: 17741 177420x82: MON_RESPONSE_BANKS_AVAILABLE 17743 17744Response body: 17745 17746@table @strong 17747@item byte 0-1: The count of the array items 17748@item byte 2+: An array with items of structure: 17749 17750@table @strong 17751@item byte 0: Size of the item, excluding this byte 17752 17753@item byte 1-2: bank ID 17754 17755@item byte 3: Name length 17756 17757@item byte 4+: Name 17758 17759@end table 17760 17761@end table 17762 17763@node MON_CMD_REGISTERS_AVAILABLE 17764@subsection Registers available (0x83) 17765 17766Gives a listing of all the registers for the running machine with their names. 17767 17768Command body: 17769 17770@table @strong 17771 17772@item byte 0: memspace 17773Describes which part of the computer you want to read: 17774 17775@itemize 17776@item 0x00: main memory 17777@item 0x01: drive 8 17778@item 0x02: drive 9 17779@item 0x03: drive 10 17780@item 0x04: drive 11 17781@end itemize 17782 17783@end table 17784 17785Response type: 17786 177870x82: MON_RESPONSE_REGISTERS_AVAILABLE 17788 17789Response body: 17790 17791@table @strong 17792@item byte 0-1: The count of the array items 17793@item byte 2+: An array with items of structure: 17794 17795@table @strong 17796 17797@item byte 0: Size of the item, excluding this byte 17798 17799@item byte 1: ID of the register 17800 17801@item byte 2: Size of the register in bits 17802 17803@item byte 3: Length of name 17804 17805@item byte 4+: Name 17806 17807@end table 17808 17809@end table 17810 17811@node MON_CMD_DISPLAY_GET 17812@subsection Display Get (0x84) 17813 17814Gets the current screen in a requested bit format. 17815 17816Command body: 17817 17818@table @strong 17819@item byte 0: USE VIC-II? 17820Must be included, but ignored for all but the C128. If true, (0x01) the screen 17821returned will be from the VIC-II. If false (0x00), it will be from the VDC. 17822 17823@item byte 1: Format 178240x00: Indexed, 8 bit@* 178250x01: RGB, 24 bit@* 178260x02: BGR, 24 bit@* 178270x03: RGBA, 32 bit@* 178280x04: BGRA, 32 bit@* 17829 17830@end table 17831 17832Response type: 17833 178340x84: MON_RESPONSE_DISPLAY_GET 17835 17836Response body: 17837 17838The length-at-the-beginning format of this object is similar to other 17839response types, except for being four bytes. Also the display buffer length 17840is contained inside another object instead of before the buffer. 17841 17842@table @strong 17843@item 4 bytes: Length of the fields before the display buffer 17844 17845 @table @strong 17846 @item 4 bytes: Length of fields before reserved area 17847 17848 @table @strong 17849 @item 4 bytes: Length of display buffer = (&buffer) 17850 17851 @item 2 bytes: Debug width of display buffer (uncropped) 17852 The largest width the screen gets. 17853 17854 @item 2 bytes: Debug height of display buffer (uncropped) 17855 The largest height the screen gets. 17856 17857 @item 2 bytes: X offset 17858 X offset to the inner part of the screen. 17859 17860 @item 2 bytes: Y offset 17861 Y offset to the inner part of the screen. 17862 17863 @item 2 bytes: Width of the inner part of the screen. 17864 17865 @item 2 bytes: Height of the inner part of the screen. 17866 17867 @item 1 byte: Bits per pixel of display buffer, 8, 24 or 32 17868 17869 @end table 17870 17871 @item 4 bytes: Length of the reserved area = (&reserved) 17872 17873 @table @strong 17874 @item (*reserved) bytes: Reserved TGA area 17875 17876 @end table 17877 17878 @end table 17879 17880@item (*buffer) bytes: Display buffer data 17881 17882@end table 17883 17884@node MON_CMD_EXIT 17885@subsection Exit (0xaa) 17886 17887Exit the monitor until the next breakpoint. 17888 17889Command body: 17890 17891Currently empty. 17892 17893Response type: 17894 178950xaa: MON_RESPONSE_EXIT 17896 17897Response body: 17898 17899Currently empty. 17900 17901@node MON_CMD_QUIT 17902@subsection Quit (0xbb) 17903 17904Quits VICE. 17905 17906Command body: 17907 17908Currently empty. 17909 17910Response type: 17911 179120xbb: MON_RESPONSE_QUIT 17913 17914Response body: 17915 17916Currently empty. 17917 17918@node MON_CMD_RESET 17919@subsection Reset (0xcc) 17920 17921Reset the system or a drive 17922 17923Command body: 17924 17925@table @strong 17926@item byte 0: What to reset 17927 17928@itemize 17929@item 0x00: Soft reset system 17930@item 0x01: Hard reset system 17931@item 0x08 - 0x0b: Reset drives 8 - 11 17932@end itemize 17933 17934@end table 17935 17936Response type: 17937 179380xcc: MON_RESPONSE_RESET 17939 17940Response body: 17941 17942Currently empty. 17943 17944@node MON_CMD_AUTOSTART 17945@subsection Autostart / autoload (0xdd) 17946 17947Load a program then return to the monitor 17948 17949Command body: 17950 17951@table @strong 17952@item byte 0: Run after loading? 179530x01: true, 0x00: false 17954 17955@item byte 1-2: File index 17956The index of the file to execute, if a disk image. 0x00 is the default value. 17957 17958@item byte 3: Length of filename 17959 17960@item byte 4+: Filename 17961The filename to autoload. 17962 17963@end table 17964 17965Response type: 17966 179670xdd: MON_RESPONSE_AUTOSTART 17968 17969Response body: 17970 17971Currently empty. 17972 17973@node Binary Responses 17974@section Responses 17975 17976These responses are generated by many different commands, or by certain events. 17977Events are generated with a request ID of 0xffffffff, so that they can be easily 17978distinguished from regular requests. 17979 17980@menu 17981* MON_RESPONSE_CHECKPOINT_INFO:: 17982* MON_RESPONSE_REGISTER_INFO:: 17983* MON_RESPONSE_JAM:: 17984* MON_RESPONSE_STOPPED:: 17985* MON_RESPONSE_RESUMED:: 17986@end menu 17987 17988@node MON_RESPONSE_CHECKPOINT_INFO 17989@subsection Checkpoint Response (0x11) 17990 17991This response is generated by hitting a checkpoint, or by many of the checkpoint 17992commands. 17993 17994@xref{MON_CMD_CHECKPOINT_GET}. 17995 17996@xref{MON_CMD_CHECKPOINT_SET}. 17997 17998@xref{MON_CMD_CHECKPOINT_LIST}. 17999 18000Response type: 18001 180020x11: MON_RESPONSE_CHECKPOINT_INFO 18003 18004Response body: 18005 18006@table @strong 18007@item byte 0-3: Checkpoint number 18008 18009@item byte 4: Currently hit? 180100x01: true, 0x00: false 18011 18012@item byte 5-6: start address 18013 18014@item byte 7-8: end address 18015 18016@item byte 9: stop when hit 180170x01: true, 0x00: false 18018 18019@item byte 10: enabled 180200x01: true, 0x00: false 18021 18022@item byte 11: CPU operation 180230x01: load, 0x02: store, 0x04: exec 18024 18025@item byte 12: temporary 18026Deletes the checkpoint after it has been hit once. This is similar to 18027"until" command, but it will not resume the emulator. 18028 18029@item byte 13-16: hit count 18030 18031@item byte 17-20: ignore count 18032 18033@item byte 21: Has condition? 180340x01: true, 0x00: false 18035 18036@end table 18037 18038@node MON_RESPONSE_REGISTER_INFO 18039@subsection Register Response (0x31) 18040 18041Response type: 18042 180430x31: MON_RESPONSE_REGISTER_INFO 18044 18045Response body: 18046 18047@table @strong 18048@item byte 0-1: The count of the array items 18049 18050@item byte 2+: An array with items of structure: 18051 18052@table @strong 18053@item byte 0: Size of the item, excluding this byte 18054 18055@item byte 1: ID of the register 18056 18057@item byte 2-3: register value 18058 18059@end table 18060 18061@end table 18062 18063 18064@node MON_RESPONSE_JAM 18065@subsection JAM Response (0x61) 18066 18067When the CPU jams 18068 18069Response type: 18070 180710x61: MON_RESPONSE_JAM 18072 18073Response body: 18074 18075@table @strong 18076@item byte 0-1: The current program counter position 18077 18078@end table 18079 18080@node MON_RESPONSE_STOPPED 18081@subsection Stopped Response (0x62) 18082 18083When the machine stops for the monitor, 18084either due to hitting a checkpoint or stepping. 18085 18086Response type: 18087 180880x62: MON_RESPONSE_STOPPED 18089 18090Response body: 18091 18092@table @strong 18093@item byte 0-1: The current program counter position 18094 18095@end table 18096 18097@node MON_RESPONSE_RESUMED 18098@subsection Resumed Response (0x63) 18099 18100When the machine resumes execution for any reason. 18101 18102Response type: 18103 181040x63: MON_RESPONSE_RESUMED 18105 18106Response body: 18107 18108@table @strong 18109@item byte 0-1: The current program counter position 18110 18111@end table 18112 18113@node c1541 18114@chapter c1541 18115 18116VICE is provided with a complete stand-alone disk image maintenance 18117utility, called @code{c1541}. 18118 18119The syntax is: 18120 18121@example 18122c1541 [IMAGE1 [IMAGE2]] [COMMAND1 COMMAND2 @dots{} COMMANDN] 18123@end example 18124 18125@code{IMAGE1} and @code{IMAGE2} are disk image names that can be 18126attached before @code{c1541} starts. @code{c1541} can handle up to 18127two disk images at the same time by using two virtual built-in drives, 18128numbered @code{8} and @code{9}; @code{IMAGE1} (if present) is always 18129attached to drive @code{8}, while @code{IMAGE2} is attached to drive 18130@code{9}. 18131 18132@code{COMMAND}s specified on the command-line all begin with the minus 18133sign (@code{-}); if present, @code{c1541} executes them in the same 18134order as they are on the command line and returns a zero error code if 18135they were successful. If any of the @code{COMMAND}s fails, @code{c1541} 18136stops and returns a nonzero error code. 18137 18138If no @code{COMMAND}s are specified at all, @code{c1541} enters 18139interactive mode, where you can type commands manually. Commands in 18140interactive mode are the same as commands in batch mode, but do not 18141require a leading @code{-}. As with the monitor, file name completion 18142and command line editing with history are provided via GNU 18143@code{readline}. Use the command @samp{quit} or press @kbd{C-d} to 18144exit. 18145 18146@menu 18147* c1541 file specification:: 18148* c1541 quoting:: 18149* c1541 commands and options:: 18150* c1541 executing shell commands:: 18151* c1541 examples:: 18152@end menu 18153 18154@node c1541 file specification 18155@section Specifying files in c1541 18156 18157When accessing CBM DOS files (i.e. files that reside on disk images), 18158c1541 uses a special syntax that lets you access files on both drive 8 18159and 9. If you prepend the file name with @code{@@8:} or @code{@@9:}, you 18160will specified that file is to be found or created on drive 8 and 9, 18161respectively. 18162 18163For instance, 18164 18165@example 18166@@8:somefile 18167@end example 18168 18169will name file named @code{somefile} on unit 8, while 18170 18171@example 18172@@9:somefile 18173@end example 18174 18175will name file named @code{somefile} on unit 9. 18176 18177@node c1541 quoting 18178@section Using quotes and backslashes 18179 18180You can use quotes (@code{"}) in a command to embed spaces into file 18181names. For instance, 18182 18183@example 18184read some file 18185@end example 18186 18187will read file @code{some} from the disk image and write it into the 18188file system as @code{file}, while 18189 18190@example 18191read "some file" 18192@end example 18193 18194will copy @code{some file} into the file system, with the name 18195@code{some file}. 18196 18197The backslash character (@code{\}) has a special meaning too: it lets 18198you literally insert the following character no matter what it is. For 18199example, 18200 18201@example 18202read some\ file 18203@end example 18204 18205will copy file @code{some file} into the file system, while 18206 18207@example 18208read some\ file this\"file 18209@end example 18210 18211will copy @code{some file} into the file system with name 18212@code{this"file} (with an embedded quote). 18213 18214 18215@node c1541 commands and options 18216@section c1541 commands and options 18217 18218This is a list of the @code{c1541} commands. They are shown in their 18219interactive form, without the leading @code{-}. 18220Square brackets [] indicate an optional part, and "<COMMAND>" translates 18221to a disk command according to CBM DOS, like "i0" for example. 18222 18223@table @code 18224 18225@item @@ [<command>] 18226Execute specified CBM DOS command and print the current status of the 18227drive. If no @code{command} is specified, just print the status. 18228 18229@item ? [<command>] 18230Explain specified command. If no command is specified, list available 18231ones. 18232 18233@item attach <diskimage> [<unit>] 18234Attach @code{diskimage} to @code{unit} (default unit is 8). 18235 18236@item bam [<unit>] | <track-min> <track-max> [<unit>] 18237Show the BAM of @code{unit}, optionally displaying only the entries for 18238@code{track-min} to @code{track-max} 18239 18240@item bcopy <src-trk> <src-sec> <dst-trk> <dst-sec> [<src-unit> [<dst-unit>]] 18241Copy a block to another block, optionally specifying different source and 18242destination units. The block is copied using all 256 bytes. 18243 18244@item bfill <track> <sector> <value> [<unit>] 18245Fill a block with a single value. 18246 18247@item block <track> <sector> [<offset> [<unit>]] 18248Show specified disk block in hex form. 18249 18250@item bpoke [@@unit:<unit>] <track> <sector> <offset> <data @dots{}> 18251Store one or more bytes of @code{data} into a block. The @code{data} can be 18252specified using prefixes: 18253@table @code 18254@item 0b or % 18255binary value (`%11111111`) 18256@item & 18257octal value (`&377`) 18258@item 0x or $ 18259hexadecimal value (`$ff`) 18260@end table 18261The <unit> is optional, and when used must use the CBM DOS notation for the 18262unit number, for example `@@9:`. 18263 18264@item bread <filename> <track> <sector> [<unit>] 18265Read a block from a disk image and write it to the host filesystem as 18266@code{filename}. 18267 18268@item bwrite <filename> <track> <sector> [<unit>] 18269Write data from the host filesystem using @code{filename} as input. At most 256 18270bytes are written to the disk image. 18271 18272@item chain <track> <sector> [<unit>] 18273Show block chain starting at (@code{track}, @code{sector}). The last number 18274shown is the number of bytes used in the final block. 18275 18276@item copy <source1> [<source2> @dots{} <sourceN>] <destination> 18277Copy @code{source1} @dots{} @code{sourceN} into destination. If N > 1, 18278@code{destination} must be a simple drive specifier (@code{@@n:}). 18279To copy a REL file, specify the <source> with a @code{,L} file type suffix. 18280 18281@item delete <file1> [<file2> @dots{} <fileN>] 18282Delete the specified files. 18283 18284@item exit 18285Exit (same as @code{quit}). 18286 18287@item entry [+side] <file1> [<file2> @dots{} <fileN>] 18288Show the directory entries of the given files in full detail. 18289If the @code{+side} option is present, and it is a RELative file, 18290it also shows all side sectors. 18291 18292@item extract 18293Extract all the files to the file system. 18294 18295@item format <diskname,id> [<type> <imagename>] [<unit>] 18296If @code{unit} is specified, format the disk in unit @code{unit}. If 18297@code{type} and @code{imagename} are specified, create a new image named 18298@code{imagename}, attach it to unit 8 and format it. @code{type} is a 18299disk image type, and must be either @code{x64}, @code{d64} (both VC1541/2031), 18300@code{g64} (VC1541/2031 but in GCR coding), @code{d71} (VC1571), 18301@code{g71} (VC1571 but in GCR coding), @code{d81} 18302(VC1581), @code{d80} (CBM8050), @code{d82} (CBM8250/1001), 18303or @code{d90} (CBM D9090). 18304Otherwise, format the disk in the current unit, if any. 18305 18306@item geosread <source> [<destination>] 18307Read GEOS <source> from the disk image and copy it as a Convert file into 18308<destination> in the file system. If <destination> is not specified, copy 18309it into a file with the same name as <source>. 18310 18311@item geoswrite <source> 18312Write GOES Convert file <source> from the file system on a disk image. 18313 18314@item geosextract <source> 18315Extract all the files to the file system and GEOS Convert them. 18316 18317@item help [<command>] 18318Explain specified command. If no command is specified, list available 18319ones. 18320 18321@item info [<unit>] 18322Display information about unit @code{unit} (if unspecified, use the current 18323one). 18324 18325@item list [<pattern>] 18326@item dir [<pattern>] 18327List files matching @code{pattern} (default is all files). 18328 18329@item name <diskname>[,<id>] <unit> 18330Change image name. 18331 18332@item p00save <enable> [<unit>] 18333Save P00 files to the file system. 18334 18335@item pwd 18336Print current working directory. 18337 18338@item quit 18339Exit (same as @code{exit}). 18340 18341@item read <source> [<destination>] 18342Read @code{source} from the disk image and copy it into @code{destination} in 18343the file system. If @code{destination} is not specified, copy it into a 18344file with the same name as @code{source}. 18345By default PRG files are copied. To copy SEQ files add @code{,s} 18346(i.e. the usual DOS file specification syntax). 18347REL files can be copied by adding @code{,l}. Don't specify the record length, 18348@code{c1541} will determine it automatically. 18349 18350@item rename <oldname> <newname> 18351Rename @code{oldname} into @code{newname}. The files must be on the 18352same drive. 18353 18354@item show [copying | warranty] 18355Show conditions for redistributing copies of C1541 (`copying') or the 18356various kinds of warranty you do not have with C1541 (`warranty'). 18357 18358@item tape <t64name> [<file1> @dots{} <fileN>] 18359Extract files from a T64 image. 18360 18361@item unit <number> 18362Make unit @code{number} the current unit. 18363 18364@item unlynx <lynxname> [<unit>] 18365Extract the specified Lynx image file into the specified unit (default 18366is the current unit). 18367 18368@item validate [<unit>] 18369Validate the disk in unit @code{unit}. If @code{unit} is not specified, 18370validate the disk in the current unit. 18371 18372@item verbose ["off"] 18373Enable or disable verbose output. 18374 18375@item version 18376Show C1541 version string 18377 18378@item write <source> [<destination>] 18379Write @code{source} from the file system into @code{destination} on a 18380disk image. 18381 18382To create a REL file, you must specify the @code{destination} including the 18383record length. 18384As a special convenience, you can give it in decimal. 18385Example: @code{write fsname imgname,l,100} 18386Note that the size of the file may be rounded up to fill the last sector. 18387 18388@item unzip <d64name> <zipname> [<label,id>] 18389Create a D64 disk image out of a set of four Zipcoded files named 18390@code{1!zipname}, @code{2!zipname}, @code{3!zipname} and 18391@code{4!zipname}. 18392 18393@end table 18394 18395@node c1541 executing shell commands 18396@section Executing shell commands 18397 18398If you want to execute a shell command from within @code{c1541}, just 18399prepend it with an exclamation mark (@code{!}). For example, 18400 18401@example 18402!ls -la 18403@end example 18404 18405will execute the command @code{ls -la}, which will show you all the 18406files in the current directory. 18407 18408@node c1541 examples 18409@section c1541 examples 18410 18411@c FIXME: add more c1541 examples 18412 18413@table @code 18414@item c1541 -attach test.d64 -list 18415Attach @code{test.d64} and show directory. 18416 18417@item c1541 -attach test.d64 -write test.prg testfile 18418Write @code{test.prg} to @code{test.d64} as @code{testfile}. 18419 18420@item c1541 -format "name,id" d64 disk.d64 18421Create a disk image in @code{d64} format, format it with the @code{name} and @code{id} and save it to @code{disk.d64}. 18422@end table 18423 18424@node Cartconv 18425@chapter cartconv 18426 18427The cartconv program is a cartridge conversion utility, it can convert 18428between binary and .crt images and it can 'insert' binary and/or 18429.crt images into the EPROM type of cartridges. 18430 18431@section cartconv command line options 18432 18433The cartconv program has the following parameters: 18434 18435@table @code 18436@findex -i 18437@item -i "input name" 18438This parameter is mandatory, it should contain the name of the binary/.crt 18439file you want to convert. For the EPROM type of cartridges this parameter 18440can be used multiple times to insert images into the resulting file. 18441@findex -o 18442@item -o "output name" 18443This parameter is mandatory, it should contain the name of the binary/.crt 18444file you want to convert the input file to. 18445@findex -t 18446@item -t carttype 18447This parameter is optional. It is only needed when converting to a .crt 18448file. See below for the supported cartridge types. 18449@findex -s 18450@item -s revision 18451This parameter is optional. It is only needed when converting to a .crt 18452file. See the detailed description of the .crt format for which types support 18453subtypes/revisions. 18454@findex -n 18455@item -n "cart name" 18456This parameter is optional and is used as the cartridge name when creating 18457a .crt file. 18458@findex -l 18459@item -l loadaddress 18460This parameter is optional and is used as the load-address when converting 18461a .crt file to a .prg file, or when converting to a generic type .crt 18462file. 18463@findex -f 18464@item -f "input name" 18465This parameter is optional, and is meant to output information about the 18466named file. It can't be used in conjuction with any of the other parameters. 18467@findex -r 18468@item -r 18469This parameter is optional, it enables repair mode (accept broken input files) 18470@findex -p 18471@item -p 18472This parameter is optional, when it is given cartconv will accept input files that 18473do not match the cartridge sizes (useful for development). 18474@findex -b 18475@item -b 18476This parameter is optional, when it is given cartconv will not omit banks that 18477are empty (filled with $ff). 18478@findex -q 18479@item -q 18480This parameter is optional, it disables all non-error messages 18481@findex --types 18482@item --types 18483This parameter is optional. It shows all supported cartridge types (see below). 18484@findex --version 18485@item --version 18486Show cartconv version string and exit 18487@end table 18488 18489The following cartridge types are supported: 18490 18491@table @code 18492@item bin 18493Binary .bin file (Default crt->bin) 18494@item normal 18495Generic 8KiB/12KiB/16KiB .crt file (Default bin->crt) 18496@item prg 18497Binary C64 .prg file with load-address 18498@item ulti 18499Ultimax mode 4KiB/8KiB/16KiB .crt file 18500@item ap 18501Atomic Power .crt file 18502@item ar2 18503Action Replay MK2 .crt file 18504@item ar3 18505Action Replay MK3 .crt file 18506@item ar4 18507Action Replay MK4 .crt file 18508@item ar5 18509Action Replay V5 .crt file 18510@item bis 18511BIS-Plus .crt file 18512@item bb3 18513Blackbox V3 .crt file 18514@item bb4 18515Blackbox V4 .crt file 18516@item bb8 18517Blackbox V8 .crt file 18518@item bb9 18519Blackbox V9 .crt file 18520@item cap 18521Capture .crt file 18522@item comal 18523Comal 80 .crt file 18524@item dep256 18525Dela EP256 .crt file, extra files can be inserted (1)(2) 18526@item dep64 18527Dela EP64 .crt file, extra files can be inserted (1) 18528@item dep7x8 18529Dela EP7x8 .crt file, extra files can be inserted (1)(2)(3) 18530@item din 18531Dinamic .crt file 18532@item dsm 18533Diashow-Maker .crt file 18534@item easy 18535EasyFlash .crt file 18536@item ecr 18537Easy Calc Result .crt file 18538@item epyx 18539Epyx FastLoad .crt file 18540@item exos 18541EXOS .crt file 18542@item expert 18543Expert Cartridge .crt file 18544@item f64 18545Formel 64 .crt file 18546@item fc1 18547The Final Cartridge .crt file 18548@item fc3 18549The Final Cartridge III .crt file 18550@item fcp 18551Final Cartridge Plus .crt file 18552@item ff 18553Freeze Frame .crt file 18554@item fm 18555Freeze Machine .crt file 18556@item fp 18557Fun Play .crt file 18558@item gk 18559Game Killer .crt file 18560@item gmod2 18561GMod2 .crt file 18562@item gmod3 18563GMod3 .crt file 18564@item gs 18565C64 Games System .crt file 18566@item ide64 18567IDE64 .crt file 18568@item ieee 18569IEEE-488 Interface .crt file 18570@item kcs 18571KCS Power Cartridge .crt file 18572@item ks 18573Kingsoft .crt file 18574@item ltk 18575Lt. Kernal Host Adaptor .crt file 18576@item mach5 18577MACH 5 .crt file 18578@item md 18579Magic Desk .crt file 18580@item mf 18581Magic Formel .crt file 18582@item max 18583MAX Basic .crt file 18584@item mikro 18585Mikro Assembler .crt file 18586@item mmc64 18587MMC64 .crt file 18588@item mmcr 18589MMC Replay .crt file 18590@item mv 18591Magic Voice .crt file 18592@item mm 18593MultiMAX .crt file 18594@item ocean 18595Ocean .crt file 18596@item p64 18597Prophet64 .crt file 18598@item pf 18599Pagefox .crt file 18600@item rep256 18601REX 256KiB EPROM Cart .crt file, extra files can be inserted (1)(2)(3) 18602@item rgcd 18603RGCD .crt file 18604@item ross 18605ROSS .crt file 18606@item rr 18607Retro Replay .crt file 18608@item rrnet 18609RR-Net MK3 .crt file 18610@item rrf 18611REX RAM-Floppy .crt file 18612@item ru 18613REX Utility .crt file 18614@item sdbox 18615SD-BOX .crt file 18616@item s64 18617Snapshot 64 .crt file 18618@item sb 18619Structured BASIC .crt file 18620@item se5 18621Super Explode V5.0 .crt file 18622@item sg 18623Super Games .crt file 18624@item silver 18625Silverrock 128KiB Cartridge .crt file 18626@item simon 18627Simons' BASIC .crt file 18628@item ss4 18629Super Snapshot V4 .crt file 18630@item ss5 18631Super Snapshot V5 .crt file 18632@item star 18633Stardos .crt file 18634@item wl 18635Westermann Learning .crt file 18636@item ws 18637Warp Speed .crt file 18638@item zaxxon 18639Zaxxon .crt file 18640@item zipp 18641ZIPP-CODE 48 .crt file 18642@end table 18643 18644@itemize @bullet 18645@item (1) insertion of 32KiB EPROM files supported. 18646@item (2) insertion of 8KiB .crt/binary files supported. 18647@item (3) insertion of 16KiB .crt/binary files supported. 18648@end itemize 18649 18650@c @node FIXME 18651@section cartconv examples 18652 18653@table @code 18654@item cartconv -i foo.crt -o foo.bin 18655Convert a .crt file to a binary file with no load-address. 18656@item cartconv -t prg -i foo.crt -o foo.prg 18657Convert a .crt file to a .prg file with default load-address. 18658@item cartconv -t prg -l 49152 -i foo.crt -o foo.prg 18659Convert a .crt file to a .prg file with 49152 as the load-address. 18660@item cartconv -t ocean -i foo.bin -o foo.crt 18661Convert a binary file to an ocean type cartridge. 18662@item cartconv -t dep64 -i dep64.bin -i eprom.prg -o foo.crt 18663Inserting a 32KiB EPROM file into an dep64 type cartridge. 18664@itemize @bullet 18665@item step 1 : use the dep64 binary file in VICE as a generic 8KiB cartridge. 18666@item step 2 : generate an EPROM file. 18667@item step 3 : get the EPROM file to the host computer. 18668@item step 4 : insert the EPROM file into the final dep64 .crt file: 18669@end itemize 18670@item cartconv -t dep256 -i dep256.bin -i somegame.crt -o foo.crt 18671Insert an 8KiB .crt file into a dep256 type cartridge. 18672@item cartconv -t rep256 -i rep256.bin -i foo1.crt -i foo2.crt -i foo3.crt -o foo.crt 18673Insert multiple 8KiB .crt files into a rep256 type cartridge. 18674@item cartconv -f foo.crt 18675Get information about a .crt file. 18676@end table 18677 18678@node Petcat 18679@chapter petcat 18680 18681The petcat program is a text conversion utility, it can convert 18682between ASCII, PETSCII and tokenized BASIC. 18683 18684@section petcat command line options 18685 18686@table @code 18687@findex -help 18688@item -help 18689Output help text 18690@findex -? 18691@item -? 18692Same as above 18693@findex -version 18694@item -version 18695show petcat version string and exit 18696@findex -v 18697@item -v 18698verbose output 18699@findex -c 18700@item -c 18701controls (interpret also control codes) (default if textmode) 18702@findex -nc 18703@item -nc 18704no controls (suppress control codes in printout) (default if non-textmode) 18705@findex -qc 18706@item -qc 18707convert all non alphanumeric characters inside quotes into controlcodes 18708@findex -ic 18709@item -ic 18710interpret control codes case-insensitive 18711@findex -d 18712@item -d 18713output raw codes in decimal 18714@findex -h 18715@item -h 18716write header (default if output is stdout) 18717@findex -nh 18718@item -nh 18719no header (default if output is a file) 18720@findex -skip <n> 18721@item -skip <n> 18722Skip <n> bytes in the beginning of input file. Ignored on P00. 18723@findex -text 18724@item -text 18725Force text mode 18726@c @findex -<version> - this one breaks the index (?!) 18727@item -<version> 18728use keywords for <version> instead of the v7.0 ones 18729@findex -w<version> 18730@item -w<version> 18731tokenize using keywords on specified Basic version. 18732@findex -k<version> 18733@item -k<version> 18734list all keywords for the specified Basic version 18735@findex -k 18736@item -k 18737list all Basic versions available. 18738@findex -l 18739@item -l 18740Specify load address for program (in hex, no loading chars!). 18741@findex -o <name> 18742@item -o <name> 18743Specify the output file name 18744@findex -f 18745@item -f 18746Force overwritten the output file. The default depends on the BASIC version. 18747@end table 18748 18749BASIC Versions: 18750@table @code 18751@item 10 18752Basic v10.0 (C65/C64DX) 18753@item 1p 18754Basic v1.0 (PET) 18755@item 2 18756Basic v2.0 (C64/VIC20/PET) 18757@item 3 18758Basic v3.5 (C16) 18759@item 40 18760Basic v4.0 (PET/CBM2) 18761@item 4e 18762Basic v2.0 with Basic v4.0 extension (C64) 18763@item 4v 18764Basic v2.0 with Basic v4.0 extension (VIC20) 18765@item 5 18766Basic v2.0 with Basic v5.0 extension (VIC20) 18767@item 70 18768Basic v7.0 (C128) 18769@item 71 18770Basic v7.0 with Basic v7.1 extension (C128) 18771@item a 18772Basic v2.0 with AtBasic (C64) 18773@item bk 18774Basic v2.0 with Kipper Basic (C64) 18775@item blarg 18776Basic v2.0 with Blarg (C64) 18777@item bob 18778Basic v2.0 with Basic on Bails (C64) 18779@item bsx 18780Basic v2.0 with Basex (C64) 18781@item bwarsaw 18782Basic v2.0 with Warsaw Basic (C64) 18783@item bws 18784Basic v2.0 with WS Basic (C64) 18785@item bwsf 18786Basic v2.0 with WS Basic final (C64) 18787@item drago 18788Basic v2.0 with Drago basic v2.2 (C64) 18789@item easy 18790Basic v2.0 with Easy Basic (VIC20) 18791@item eve 18792Basic v2.0 with Eve Basic (C64) 18793@item exp20 18794Basic v2.0 with Expanded Basic (VIC20) 18795@item exp64 18796Basic v2.0 with Expanded Basic (C64) 18797@item f 18798Basic v2.0 with Final Cartridge III (C64) 18799@item game 18800Basic v2.0 with Game Basic (C64) 18801@item graph 18802Basic v2.0 with Graphics basic (C64) 18803@item lightning 18804Basic v2.0 with Basic Lightning (C64) 18805@item magic 18806Basic v2.0 with Magic Basic (C64) 18807@item mighty 18808Basic v2.0 with Mighty Basic by Craig Bruce (VIC20) 18809@item pegasus 18810Basic v2.0 with Pegasus Basic v4.0 (C64) 18811@item reu 18812Basic v2.0 with REU-Basic (C64) 18813@item simon 18814Basic v2.0 with Simons' Basic extension (C64) 18815@item speech 18816Basic v2.0 with Speech Basic v2.7 (C64) 18817@item superbas 18818Basic v2.0 with Super Basic (C64) 18819@item superexp 18820Basic v2.0 with Super Expander (VIC20) 18821@item supergra 18822Basic v2.0 with Supergrafik 64 (C64) 18823@item sxc 18824Basic v2.0 with Super Expander Chip (C64) 18825@item tt64 18826Basic v2.0 with The Tool 64 (C64) 18827@item turtle 18828Basic v2.0 with Turtle Basic by Craig Bruce (VIC20) 18829@item ultra 18830Basic v2.0 with Ultrabasic-64 (C64) 18831@item xbasic 18832Basic v2.0 with Xbasic (C64) 18833@end table 18834 18835@c @node FIXME 18836@section petcat examples 18837 18838@table @code 18839@item @code{petcat -2 -o outputfile.txt -- inputfile.prg} 18840De-tokenize, Convert inputfile.prg to a text file in outputfile.txt, using BASIC V2 only 18841@item @code{petcat -wsimon -o outputfile.prg -- inputfile.txt} 18842Tokenize, Convert inputfile.txt to a PRG file in outputfile.prg, using Simons' BASIC 18843@item @code{petcat -text -o outputfile.txt -- inputfile.seq} 18844Convert inputfile.seq to a Ascii text file in outputfile.txt. 18845@item @code{petcat -text -w2 -o outputfile.seq -- inputfile.txt} 18846Convert inputfile.txt to a Petscii text SEQ file in outputfile.seq. 18847@end table 18848 18849@node File formats 18850@chapter The emulator file formats 18851 18852This chapter gives a technical description of the various files 18853supported by the emulators. 18854 18855@menu 18856* TAP:: The raw tape image format 18857* T64:: The tape image format 18858* G64:: The GCR-encoded disk image format 18859* D64:: The D64 disk image format 18860* D71:: The D71 disk image format 18861* D80:: The D80 disk image format 18862* D81:: The D81 disk image format 18863* D82:: The D82 disk image format 18864* D90:: The D90 disk image format 18865* X64:: The X64 disk image format 18866* DHD:: The DHD disk image format 18867* P00:: The P00 image format 18868@end menu 18869 18870@node TAP, T64, File formats, File formats 18871@section The raw tape image format 18872 18873(This section is based on v1.1 TAP specification by Per Hakan Sundell and Markus 18874Brenner, additional format v2 expansion by Markus Brenner, plus some editing 18875by groepaz) 18876 18877Designed by Per Hakan Sundell (author of the CCS64 C64 emulator) in 1997, 18878this format attempts to duplicate the data stored on a C64 cassette tape, 18879bit for bit. Since it is simply a representation of the raw serial data 18880from a tape, it should handle *any* custom tape loaders that exist. 18881 18882The TAP images are generally very large, being a minimum of eight times, 18883and up to sixteen times as large as what a raw PRG file would be. This is 18884due to the way the data is stored, with each bit of the original file now 18885being one byte large in the TAP file. The layout is fairly simple, with a 18886small 14-byte header followed by file data. 18887 18888@example 18889 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 18890 ----------------------------------------------- ---------------- 188910000: 43 36 34 2D 54 41 50 45 2D 52 41 57 00 00 00 00 C64-TAPE-RAW???? 188920010: 51 21 08 00 2F 0F 0D 31 64 1D 26 0D 07 21 0A 12 Q!??/??1d?&??!?? 188930020: 4A 2F 2C 34 07 18 0D 31 07 04 23 04 0D 42 0D 1E J/,4???1??#??B?? 188940030: 34 04 42 0D 20 15 5E 04 0D 18 61 0D 26 29 34 0D 4?B???^???a?&)4? 188950040: 23 0D 07 0A 3F 55 04 0A 13 3F 07 0D 12 2B 18 0A #????U???????+?? 18896@end example 18897 18898@multitable @columnfractions .2 .8 18899@item @b{Offset} 18900@tab @b{Description} 18901@item $0000-000B 18902@tab File signature (@code{C64-TAPE-RAW} or @code{C16-TAPE-RAW}) 18903@item $000C 18904@tab @code{G64} TAP version (see below for description), $00 - Original layout, 18905$01 - Updated, $02 - Halfwave Extension 18906@item $000D 18907@tab Computer Platform (0 = C64, 1 = VIC-20, 2 = C16, Plus/4) 18908@item $000E 18909@tab Video Standard (0 = PAL, 1 = NTSC1, 2 = NTSC2) 18910@item 000F 18911@tab reserved for future expansion 18912@item $0010-0013 18913@tab File data size (not including this header, in LOW/HIGH format) i.e. 18914This image is $00082151 bytes long. 18915@item $0014-xxxx 18916@tab File data 18917@end multitable 18918 18919 In TAP version $00 files, each data byte in the file data area represents 18920the length of a pulse, when the C64's hardware will trigger again. This 18921pulse length is determined by the following formula: 18922@example 18923 pulse length (in seconds) = (8 * data byte) / (clock cycles) 18924@end example 18925 Therefore, a data value of $2F (47 in decimal) would be: 18926@example 18927 (47 * 8) / 985248 = .00038975 seconds. 18928@end example 18929 A data value of $00 represents an "overflow" condition, any pulse length 18930which is more that 255 * 8 in length. 18931 18932The value of "clock cyvles" from above (985248) is based on the PAL 18933value. Since this file format was developed in Europe, which is 18934predominantly PAL video, this is only logical. The NTSC value would be 189351022730, which is very close to the PAL, and therefore won't cause a 18936compatability problem converting European and NTSC tapes. I would stick to 18937using the PAL value just in case. 18938 18939In TAP version $01 files, the data value of $00 has been re-coded to 18940represent values greater than 255 * 8. When a $00 is encountered, three 18941bytes will follow which are the actual time (in cycles) of a pulse, and the 18942above formula does not apply. The three bytes are stored in LOW/HIGH 18943format. 18944 18945Version 2 is an extension made by Markus Brenner for C16 tapes. It is version 1, 18946but each value represents a halfwave, starting with a '0'->'1' transition. 18947The time encoding doesn't change. 18948 18949The actual interpretation of the serial data takes a little more work to 18950explain. The typical ROM tape loader (and the turbo loaders) will 18951initialize a timer with a specified value and start it counting down. If 18952either the tape data changes or the timer runs out, an IRQ will occur. The 18953loader will determine which condition caused the IRQ. If the tape data 18954changed before the timer ran out, we have a short pulse, or a "0" bit. If 18955the timer ran out first, we have a long pulse, or a "1" bit. Doing this 18956continuously and we decode the entire file. 18957 18958@node T64, G64, File formats, File formats 18959@section The T64 tape image format 18960 18961(This section was taken from the C64S distribution.) 18962 18963The @code{T64} File Structure was developed by Miha Peternel for use in 18964the C64S emulator. It is easy to use and allows future extensions. 18965 18966@menu 18967* T64 file structure:: 18968* T64 tape record:: 18969* T64 file record:: 18970@end menu 18971 18972@c FIXME: add D67 CBM2040 (DOS1) disk image file structure 18973@c FIXME: add D1M FD2000/FD4000 DD disk image file structure 18974@c FIXME: add D2M FD2000/FD4000 HD disk image file structure 18975@c FIXME: add D4M FD4000 ED disk image file structure 18976 18977@node T64 file structure, T64 tape record, T64, T64 18978@subsection T64 File structure 18979 18980@multitable @columnfractions .3 .3 .4 18981@item @b{Offset} 18982@tab @b{Size} 18983@tab @b{Description} 18984@item 0 18985@tab 64 18986@tab tape record 18987@item 64 18988@tab 32*n 18989@tab file records for n directory entries 18990@item 64+32*n 18991@tab varies 18992@tab binary contents of the files 18993@end multitable 18994 18995@node T64 tape record, T64 file record, T64 file structure, T64 18996@subsection Tape Record 18997 18998@multitable @columnfractions .3 .3 .4 18999@item @b{Offset} 19000@tab @b{Size} 19001@tab @b{Description} 19002@item 0 19003@tab 32 19004@tab DOS tape description + EOF (for type) 19005@item 32 19006@tab 2 19007@tab tape version ($0200) 19008@item 34 19009@tab 2 19010@tab number of directory entries 19011@item 36 19012@tab 2 19013@tab number of used entries (can be 0 in my loader) 19014@item 38 19015@tab 2 19016@tab free 19017@item 40 19018@tab 24 19019@tab user description as displayed in tape menu 19020@end multitable 19021 19022@node T64 file record, , T64 tape record, T64 19023@subsection File record 19024 19025@multitable @columnfractions .3 .3 .4 19026@item @b{Offset} 19027@tab @b{Size} 19028@tab @b{Description} 19029@item 0 19030@tab 1 19031@tab entry type (see below) 19032@item 1 19033@tab 1 19034@tab C64 file type 19035@item 2 19036@tab 2 19037@tab start address 19038@item 4 19039@tab 2 19040@tab end address 19041@item 6 19042@tab 2 19043@tab free 19044@item 8 19045@tab 4 19046@tab offset of file contents start within T64 file 19047@item 12 19048@tab 4 19049@tab free 19050@item 16 19051@tab 16 19052@tab C64 file name 19053@end multitable 19054 19055Valid entry types are: 19056 19057@multitable @columnfractions .3 .7 19058@item @b{Code} 19059@tab @b{Explanation} 19060@item @code{0} 19061@tab free entry 19062@item @code{1} 19063@tab normal tape file 19064@item @code{2} 19065@tab tape file with header: header is saved just before file data 19066@item @code{3} 19067@tab memory snapshot v0.9, uncompressed 19068@item @code{4} 19069@tab tape block 19070@item @code{5} 19071@tab digitized stream 19072@item @code{6} @dots{} @code{255} 19073@tab reserved 19074@end multitable 19075 19076Notes: 19077 19078@itemize @bullet 19079@item VICE only supports file type @code{1}. 19080@item Types @code{3}, @code{4} and @code{5} are subject to change (and 19081are rarely used). 19082@end itemize 19083 19084@node G64, D64 , T64, File formats 19085@section The G64 GCR-encoded disk image format 19086@subsection The original format 19087 19088(This section was contributed by Peter Schepers and slightly edited by 19089Ettore Perazzoli.) 19090 19091This format was defined in 1998 as a cooperative effort between several 19092emulator people, mainly Per H�kan Sundell, author of the CCS64 C64 19093emulator, Andreas Boose of the VICE CBM emulator team and Joe 19094Forster/STA, the author of Star Commander. It was the first real public 19095attempt to create a format for the emulator community which removed 19096almost all of the drawbacks of the other existing image formats, namely 19097@code{D64}. 19098 19099The intention behind @code{G64} is not to replace the widely used 19100@code{D64} format, as @code{D64} works fine with the vast majority of 19101disks in existence. It is intended for those small percentage of 19102programs which demand to work with the 1541 drive in a non-standard way, 19103such as reading or writing data in a custom format. The best example is 19104with speeder software such as Action Cartridge in Warp Save mode or 19105Vorpal which write track/sector data in another format other than 19106standard GCR. The other obvious example is copy-protected software 19107which looks for some specific data on a track, like the disk ID, which 19108is not stored in a standard @code{D64} image. 19109 19110@code{G64} has a deceptively simply layout for what it is capable of 19111doing. We have a signature, version byte, some predefined size values, 19112and a series of offsets to the track data and speed zones. It is what's 19113contained in the track data areas and speed zones which is really at the 19114heart of this format. 19115 19116Each track entry in simply the raw stream of GCR data, just what a read 19117head would see when a diskette is rotating past it. How the data gets 19118interpreted is up to the program trying to access the disk. Because the 19119data is stored in such a low-level manner, just about anything can be 19120done. Most of the time I would suspect the data in the track would be 19121standard sectors, with SYNC, GAP, header, data and checksums. The 19122arrangement of the data when it is in a standard GCR sector layout is 19123beyond the scope of this document. 19124 19125Since it is a flexible format in both track count and track byte size, 19126there is no ``standard'' file size. However, given a few constants like 1912742 tracks and halftracks, a track size of 7928 bytes and no speed offset 19128entries, the typical file size will a minimum of 333744 bytes. 19129 19130Below is a dump of the header, broken down into its various parts. 19131After that will be an explanation of the track offset and speed zone 19132offset areas, as they demand much more explanation. 19133 19134@example 19135Addr 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 19136---- ----------------------------------------------- 191370000: 47 43 52 2D 31 35 34 31 00 54 F8 1E .. .. .. .. 19138@end example 19139 19140@multitable @columnfractions .2 .8 19141@item @b{Offset} 19142@tab @b{Description} 19143@item $0000-0007 19144@tab File signature (@code{GCR-1541}) 19145@item $0008 19146@tab @code{G64} version (presently only $00 defined) 19147@item $0009 19148@tab Number of tracks in image (usually $54, decimal 84) 19149@item $000A-000B 19150@tab Size of each stored track in bytes (usually 7928, or $1EF8) in LO/HI format. 19151@end multitable 19152 19153An obvious question here is ``why are there 84 tracks defined when a 19154normal @code{D64} disk only has 35 tracks?'' Well, by definition, this 19155image includes all half-tracks, so there are actually 42 tracks and 42 19156half tracks. The 1541 stepper motor can access up to 42 tracks and the 19157in-between half-tracks. Even though using more than 35 tracks is not 19158typical, it was important to define this format from the start with what 19159the 1541 is capable of doing, and not just what it typically does. 19160 19161At first, the defined track size value of 7928 bytes may seem to be 19162arbitrary, but it is not. It is determined by the fastest write speed 19163possible (speed zone 0), coupled with the average rotation speed of the 19164disk (300 rpm). After some math, the answer that actually comes up is 191657692 bytes. Why the discrepency between the actual size of 7692 and the 19166defined size of 7928? Simply put, not all drives rotate at 300 rpm. 19167Some can be faster or slower, so a upper safety margin of +3% was built 19168added, in case some disks rotate slower and can write more data. After 19169applying this safety factor, and some rounding-up, 7928 bytes per track 19170was arrived at. 19171 19172Also note that this upper limit of 7928 bytes per track really only 19173applies to 1541 and compatible disks. If this format were applied to 19174another disk type like the SFD1001, this value would be higher. 19175 19176Below is a dump of the first section of a @code{G64} file, showing the offsets 19177to the data portion for each track and half-track entry. Following that 19178is a dump of the speed zone offsets. 19179 19180@example 19181Addr 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 19182---- ----------------------------------------------- 191830000: .. .. .. .. .. .. .. .. .. .. .. .. AC 02 00 00 191840010: 00 00 00 00 A6 21 00 00 00 00 00 00 A0 40 00 00 191850020: 00 00 00 00 9A 5F 00 00 00 00 00 00 94 7E 00 00 191860030: 00 00 00 00 8E 9D 00 00 00 00 00 00 88 BC 00 00 191870040: 00 00 00 00 82 DB 00 00 00 00 00 00 7C FA 00 00 191880050: 00 00 00 00 76 19 01 00 00 00 00 00 70 38 01 00 191890060: 00 00 00 00 6A 57 01 00 00 00 00 00 64 76 01 00 191900070: 00 00 00 00 5E 95 01 00 00 00 00 00 58 B4 01 00 191910080: 00 00 00 00 52 D3 01 00 00 00 00 00 4C F2 01 00 191920090: 00 00 00 00 46 11 02 00 00 00 00 00 40 30 02 00 1919300A0: 00 00 00 00 3A 4F 02 00 00 00 00 00 34 6E 02 00 1919400B0: 00 00 00 00 2E 8D 02 00 00 00 00 00 28 AC 02 00 1919500C0: 00 00 00 00 22 CB 02 00 00 00 00 00 1C EA 02 00 1919600D0: 00 00 00 00 16 09 03 00 00 00 00 00 10 28 03 00 1919700E0: 00 00 00 00 0A 47 03 00 00 00 00 00 04 66 03 00 1919800F0: 00 00 00 00 FE 84 03 00 00 00 00 00 F8 A3 03 00 191990100: 00 00 00 00 F2 C2 03 00 00 00 00 00 EC E1 03 00 192000110: 00 00 00 00 E6 00 04 00 00 00 00 00 E0 1F 04 00 192010120: 00 00 00 00 DA 3E 04 00 00 00 00 00 D4 5D 04 00 192020130: 00 00 00 00 CE 7C 04 00 00 00 00 00 C8 9B 04 00 192030140: 00 00 00 00 C2 BA 04 00 00 00 00 00 BC D9 04 00 192040150: 00 00 00 00 B6 F8 04 00 00 00 00 00 .. .. .. .. 19205@end example 19206 19207@multitable @columnfractions .2 .8 19208@item @b{Offset} 19209@tab @b{Description} 19210@item $000C-000F 19211@tab Offset to stored track 1.0 ($000002AC, in LO/HI format, see below for more) 19212@item $0010-0013 19213@tab Offset to stored track 1.5 ($00000000) 19214@item $0014-0017 19215@tab Offset to stored track 2.0 ($000021A6) 19216@item @dots{} 19217@item $0154-0157 19218@tab Offset to stored track 42.0 ($0004F8B6) 19219@item $0158-015B 19220@tab Offset to stored track 42.5 ($00000000) 19221@end multitable 19222 19223@example 19224 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 19225 ----------------------------------------------- 192260150: .. .. .. .. .. .. .. .. .. .. .. .. 03 00 00 00 192270160: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 192280170: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 192290180: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 192300190: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 1923101A0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 1923201B0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 1923301C0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 1923401D0: 00 00 00 00 03 00 00 00 00 00 00 00 03 00 00 00 1923501E0: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00 1923601F0: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00 192370200: 00 00 00 00 02 00 00 00 00 00 00 00 02 00 00 00 192380210: 00 00 00 00 02 00 00 00 00 00 00 00 01 00 00 00 192390220: 00 00 00 00 01 00 00 00 00 00 00 00 01 00 00 00 192400230: 00 00 00 00 01 00 00 00 00 00 00 00 01 00 00 00 192410240: 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 192420250: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 192430260: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 192440270: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 192450280: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 192460290: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 1924702A0: 00 00 00 00 00 00 00 00 00 00 00 00 .. .. .. .. 19248@end example 19249 19250@multitable @columnfractions .2 .8 19251@item @b{Offset} 19252@tab @b{Description} 19253@item $015C-015F 19254@tab Speed zone entry for track 1 ($03, in LO/HI format, see below for more) 19255@item $0160-0163 19256@tab Speed zone entry for track 1.5 ($03) 19257@item @dots{} 19258@item $02A4-02A7 19259@tab Speed zone entry for track 42 ($00) 19260@item $02A8-02AB 19261@tab Speed zone entry for track 42.5 ($00) 19262@end multitable 19263 19264Starting here at $02AC is the first track entry (from above, it is the 19265first entry for track 1.0) 19266 19267The track offsets (from above) require some explanation. When one is 19268set to all 0's, no track data exists for this entry. If there is a 19269value, it is an absolute reference into the file (starting from the 19270beginning of the file). From the track 1.0 entry we see it is set for 19271$000002AC. Going to that file offset, here is what we see@dots{} 19272 19273@example 19274 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 19275 ----------------------------------------------- 1927602A0: .. .. .. .. .. .. .. .. .. .. .. .. 0C 1E FF FF 1927702B0: FF FF FF 52 54 B5 29 4B 7A 5E 95 55 55 55 55 55 1927802C0: 55 55 55 55 55 55 FF FF FF FF FF 55 D4 A5 29 4A 1927902D0: 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 19280@end example 19281 19282@multitable @columnfractions .2 .8 19283@item @b{Offset} 19284@tab @b{Description} 19285@item $02AC-02AD 19286@tab Actual size of stored track (7692 or $1E0C, in LO/HI format) 19287@item $02AE-02AE+$1E0C 19288@tab Track data 19289@end multitable 19290 19291Following the track data is filler bytes. In this case, there are 368 19292bytes of unused space. This space can contain anything, but for the 19293sake of those wishing to compress these images for storage, they should 19294all be set to the same value. In the sample I used, these are all set 19295to $FF. 19296 19297Below is a dump of the end of the track 1.0 data area. Note the actual 19298track data ends at address $20B9, with the rest of the block being 19299unused, and set to $FF. 19300 19301@example 19302 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 19303 ----------------------------------------------- 193041FE0: 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 193051FF0: 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 193062000: A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 193072010: 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 193082020: 4A 52 94 A5 29 4A 52 94 A5 29 4A 52 94 A5 29 4A 193092030: 55 55 55 55 55 55 FF FF FF FF FF FF FF FF FF FF 193102040: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193112050: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193122060: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193132070: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193142080: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193152090: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 1931620A0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 1931720B0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 1931820C0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 1931920D0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 1932020E0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 1932120F0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193222100: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193232110: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193242120: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193252130: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193262140: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193272150: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193282160: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193292170: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193302180: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 193312190: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 1933221A0: FF FF FF FF FF FF .. .. .. .. .. .. .. .. .. .. 19333@end example 19334 19335The speed offset entries can be a little more complex. The 1541 has four 19336speed zones defined, which means the drive can write data at four 19337distinct speeds. On a normal 1541 disk, these zones are as follows: 19338 19339@multitable @columnfractions .5 .5 19340@item @b{Track Range} 19341@tab @b{Speed Zone} 19342@item 1-17 19343@tab 3 (highest writing speed) 19344@item 18-24 19345@tab 2 19346@item 25-30 19347@tab 1 19348@item 31 and up 19349@tab 0 (lowest writing speed) 19350@end multitable 19351 19352Note that you can, through custom programming of the 1541, change the 19353speed zone of any track to something different (change the 3 to a 0) and 19354write data differently. From the dump of the speed offset entries 19355above, we see that all the entries are in the range of 0-3. If any entry 19356is less than 4, this is not considered a speed offset but defines the 19357whole track to be recorded at that one speed. 19358 19359In the example I had, there were no offsets defined, so no speed zone 19360dump can be shown. However, I can define what should be there. You 19361will have a block of data, 1982 bytes long. Each byte is encoded to 19362represent the speed of 4 bytes in the track offset area, and is broken 19363down as follows: 19364 19365@example 19366Speed entry $FF: in binary %11111111 19367 |'|'|'|' 19368 | | | | 19369 | | | +- 4'th byte speed (binary 11, 3 dec) 19370 | | +--- 3'rd byte speed (binary 11, 3 dec) 19371 | +----- 2'nd byte speed (binary 11, 3 dec) 19372 +------- 1'st byte speed (binary 11, 3 dec) 19373@end example 19374 19375It was very smart thinking to allow for two speed zone settings, one in 19376the offset block and another defining the speed on a per-byte basis. If 19377you are working with a normal disk, where each track is one constant 19378speed, then you don't need the extra blocks of information hanging 19379around the image, wasting space. 19380 19381What may not be obvious is the flexibility of this format to add tracks 19382and speed offset zones at will. If a program decides to write a track 19383out with varying speeds, and no speed offset exist, a new block will be 19384created by appending it to the end of the image, and the offset pointer 19385for that track set to point to the new block. If a track has no offset 19386yet, meaning it doesn't exist (like a half-track), and one needs to be 19387added, the same procedure applies. The location of the actual track or 19388speed zone data is not important, meaning they do not have to be in any 19389particular order since they are all referenced by the offsets at the 19390beginning of the image. 19391 19392@subsection An extension for double sided disks (Commodore VIC 1571) 19393 19394Given that a Commodore VIC 1541/1570/1571 can read/write at most 42 19395tracks per side, it is quite natural to use the half-tracks from 1 19396to 84 for the first side and the following 84 half-tracks (i. e. 19397halg.track 85 to 168) for the second size. 19398 19399In order for this to work, byte 9 of the image (i. e. the maximum 19400number of tracks) usually contains 168 for double sided disks. 19401 19402To make identifying such images easy, the file signature in the first 8 bytes of 19403such files will be @code{GCR-1571}). 19404 19405@subsection Extra mastering info (SPS extension) 19406 19407G64s created by the DTC tool from Kryoflux dumps contain extra info for each 19408track, usually at offset $02ac right after the speedzone entries. 19409 19410First comes the extra info tag: 19411 19412@multitable @columnfractions .2 .8 19413@item @b{Offset} 19414@tab @b{Description} 19415@item $00-$02 19416@tab extra info tag (@b{EXT}) $45,$58,$54 19417@item $03 19418@tab extra info version ($01) 19419@end multitable 19420 19421Followed by 16 bytes of extra info for each track in the image: 19422 19423@multitable @columnfractions .2 .8 19424@item @b{Offset} 19425@tab @b{Description} 19426@item $00 19427@tab write splice position 19428@item $04 19429@tab write area size 19430@item $08 19431@tab bitcell size in nanoseconds (eg 3500 means 3.5us) 19432@item $0c 19433@tab track fill value 19434@item $0d 19435@tab n/a 19436@item $0e 19437@tab format code 19438@item $0f 19439@tab format extension 19440@end multitable 19441 19442A zero value in any of these fields means that the respective default/standard 19443value applies. 19444 19445Format codes: 19446 19447@multitable @columnfractions .2 .8 19448@item @b{ID} 19449@tab @b{Description} 19450@item 0 19451@tab Unknown format 19452@item 1 19453@tab GCR Data 19454@item 2 19455@tab CBM DOS 19456@item 3 19457@tab CBM DOS Extended 19458@item 4 19459@tab MicroProse 19460@item 5 19461@tab RapidLok 19462@item 6 19463@tab Datasoft 19464@item 7 19465@tab Vorpal 19466@item 8 19467@tab V-MAX! 19468@item 9 19469@tab Teque 19470@item 10 19471@tab TDP 19472@item 11 19473@tab Big Five 19474@item 12 19475@tab OziSoft 19476@end multitable 19477 19478Format Extensions: 19479 19480@multitable @columnfractions .2 .8 19481@item @b{ID} 19482@tab @b{Description} 19483@item 0 19484@tab Unknown protection 19485@item 1 19486@tab Datasoft with Weak bits 19487@item 2 19488@tab CBM DOS with Cyan loader, Weak bits 19489@item 3 19490@tab CBM DOS with Datasoft, Weak bits 19491@item 4 19492@tab RapidLok Key 19493@item 5 19494@tab Data Duplication 19495@item 6 19496@tab Melbourne House 19497@item 7 19498@tab Melbourne House, Weak bits 19499@item 8 19500@tab PirateBusters v1.0 19501@item 9 19502@tab PirateBusters v2.0, Track A 19503@item 10 19504@tab PirateBusters v2.0, Track B 19505@item 11 19506@tab PirateSlayer 19507@item 12 19508@tab CBM DOS, XEMAG 19509@end multitable 19510 19511@c @node FIXME 19512@section The P64 NRZI flux pulse disk image format 19513 19514@c FIXME: the P64 section needs to be style-checked. 19515 19516This section is taken from "P64 file format specification" by Benjamin 'BeRo' 19517Rosseaux. 19518 19519All values are in little endian order ! 19520 19521@c @node FIXME 19522@subsection P64 Header Layout 19523 19524@example 19525 0 1 2 3 4 5 6 7 8 9 A B C D E F 19526 +---------------------------------------------------------------+ 195270000: |'P'|'6'|'4'|'-'|'1'|'5'|'4'|'1'| Version | Flags | 19528 +---------------+---------------+-------------------------------+ 195290010: | Size | CRC32Checksum | 19530 +-------------------------------+ 19531@end example 19532 19533 Version: File format version, current is 0x00000000 19534 19535 Size Size of the following whole chunk content stream 19536 19537 Flags: Bit 0 = Write protect 19538 Bit 1 = Number of sides (0 for single sided, 19539 1 for double sided) 19540 Bit 2-31 = Reserved, all set to 0 when creating a file, 19541 preserve existing value when updating 19542 19543 CRC32CheckSum: CRC32 checksum of the following whole chunk content stream 19544 19545@c @node FIXME 19546@subsection P64 Chunk Header Layout 19547 19548@example 19549 0 1 2 3 4 5 6 7 8 9 A B C D E F 19550 +-----------------------------------------------+ 195510000: |Chunk Signature| Size | CRC32Checksum | 19552 +-----------------------------------------------+ 19553@end example 19554 19555 Chunk signature: Signature of chunk 19556 19557 Size: Size of the chunk data 19558 19559 CRC32CheckSum: CRC32 checksum of the chunk data 19560 19561@c @node FIXME 19562@subsection P64 Chunk 'HTPx' Layout 19563 19564 | x = half track index byte | 19565 +---------------------------+ 19566 Bit 7 of the half track index byte contains the side. 19567 19568 Track 18 = Half track 36 = Half track index byte decimal value 36 19569 19570 Half track NRZI transition flux pulse data chunk block 19571 19572@example 19573 0 1 2 3 4 5 6 7 8 9 A B C D E F 19574 +---------------------------------------------------------------+ 195750000: | Count pulses | Size | ..... Range-encoded data .... | 19576 +---------------------------------------------------------------+ 19577@end example 19578 19579 Count pulses: Count of the NRZI transition flux pulses in half track 19580 19581 Size: Size of the range-encoded data 19582 19583@c @node FIXME 19584@subsection 'HTPx' Range encoded data format 19585 19586 Hint: For a working C implememtation see p64.c and p64.h 19587 19588The range coder is a FPAQ0-style range coder combined with 12-bit 0-order 19589models, one model per byte with one bit per byte processing. 19590 19591@example 19592 +--------------------------------------------------------------------------+ 19593 | Sub stream | Count of models | Size per model | Total value bits | 19594 +------------------+-----------------+------------------+------------------+ 19595 | Position | 4 | 65536 | 32 | 19596 +------------------+-----------------+------------------+------------------+ 19597 | Strength | 4 | 65536 | 32 | 19598 +------------------+-----------------+------------------+------------------+ 19599 | Position flag | 1 | 2 | 1 | 19600 +------------------+-----------------+------------------+------------------+ 19601 | Strenth flag | 1 | 2 | 1 | 19602 +------------------+-----------------+------------------+------------------+ 19603 +===Total models===| 10 |==================|==================| 19604 +--------------------------------------------------------------------------+ 19605@end example 19606 19607All initial model state values are initialized with zero. 19608 19609All initial model probability values are initialized with 2048. 19610 19611These model probability values will be updating in a adaptive way on the 19612fly and not precalculated before the encoding and even not loaded before 19613the decoding, see pseudo code below. 19614 1961516000000 Hz / 5 rotations per second at 300 RPM = maximal 3200000 flux pulses 19616 19617So NRZI transition flux pulse positions are in the 0 .. 3199999 value range, 19618which is also a exact single rotation, where each time unit is a cycle at 1961916 MHz with 300 RPM as a mapping for the ideal case. 19620 19621The NRZI transition flux pulse stength are in the 0x00000000 .. 0xffffffff 19622value range, where 0xffffffff indices a strong flux pulse, that always 19623triggers, and 0x00000001 indices a weak flux pulse, that almost never 19624triggers, and 0x00000000 indices a flux pulse, that absolutly never 19625triggers. 19626 19627For 32-bit values, the model sub streams are subdivided byte wide in a 19628little-endian manner, and each byte is processed bitwise with model 19629probability shifting of 4 bits, just as: 19630 19631Pascal-Style pseudo code: 19632@example 19633procedure WriteDWord(Model, Value : longword); 19634var ByteValue, ByteIndex, Context, Bit : longword; 19635begin 19636 for ByteIndex := 0 to 3 do begin 19637 ByteValue := (Value shr (ByteIndex shl 3)) and $ff; 19638 Context := 1; 19639 for Bit := 7 downto 0 do begin 19640 Context := (Context shl 1) or RangeCoderEncodeBit( 19641 RangeCoderProbabilities[ 19642 RangeCoderProbabilityOffsets[Model + ByteIndex] + 19643 (((RangeCoderProbabilityStates[Model + ByteIndex] 19644 shl 8) or Context) and $ffff)], 4, (ByteValue shr 19645 Bit) and 1); 19646 end; 19647 RangeCoderProbabilityStates[Model+ByteIndex] := ByteValue; 19648 end; 19649end; 19650@end example 19651 19652And for 1-bit flag values it is much simpler, but also with model probability 19653shifting of 4 bits, just as: 19654 19655Pascal-Style pseudo code: 19656@example 19657procedure WriteBit(Model, Value : longword); 19658begin 19659 RangeCoderProbabilityStates[Model] := 19660 RangeCoderEncodeBit(RangeCoderProbabilities[ 19661 RangeCoderProbabilityOffsets[Model] + 19662 RangeCoderProbabilityStates[Model]], 4, Value and 1); 19663end; 19664@end example 19665 19666The position and strength values are delta-encoded. If a value is equal to 19667the last previous value, then the value will not encoded, instead, a flag for 19668this will encoded. First the position value will encoded, then the stength 19669value. If the last position delta is 0, then it is a track stream end marker. 19670 19671Pascal-Style pseudo code: 19672@example 19673LastPosition := 0; 19674PreviousDeltaPosition := 0 19675 19676LastStrength := 0; 19677 19678for PulseIndex := 0 to PulseCount - 1 do begin 19679 19680 DeltaPosition := Pulses[PulseIndex].Position - LastPosition; 19681 if PreviousDeltaPosition <> DeltaPosition then begin 19682 PreviousDeltaPosition := DeltaPosition; 19683 WriteBit(ModelPositionFlag, 1) 19684 WriteDWord(ModelPosition, DeltaPosition); 19685 end else begin 19686 WriteBit(ModelPositionFlag, 0); 19687 end; 19688 LastPosition := Pulses[PulseIndex].Position; 19689 19690 if LastStrength <> Pulses[PulseIndex].Strength then begin 19691 WriteBit(ModelStrengthFlag, 1) 19692 WriteDWord(ModelStrength, Pulses[PulseIndex].Strength - LastStrength); 19693 end else begin 19694 WriteBit(ModelStrengthFlag, 0); 19695 end; 19696 LastStrength := Pulses^[PulseIndex].Strength; 19697 19698end; 19699 19700// End code 19701WriteBit(ModelPositionFlag, 1); 19702WriteDWord(ModelPosition, 0); 19703@end example 19704 19705The decoding is simply just in the another direction way. 19706 19707Pseudo code for a FPAQ0-style carryless range coder: 19708 19709Pascal-Style pseudo code: 19710@example 19711procedure RangeCoderInit; // At encoding and decoding start 19712begin 19713 RangeCode := 0; 19714 RangeLow := 0; 19715 RangeHigh := $ffffffff; 19716end; 19717 19718procedure RangeCoderStart; // At decoding start 19719var Counter : longword; 19720begin 19721 for Counter := 1 to 4 do begin 19722 RangeCode := (RangeCode shl 8) or ReadByteFromInput; 19723 end; 19724end; 19725 19726procedure RangeCoderFlush; // At encoding end 19727var Counter : longword; 19728begin 19729 for Counter := 1 to 4 do begin 19730 WriteByteToOutput(RangeHigh shr 24); 19731 RangeHigh := RangeHigh shl 8; 19732 end; 19733end; 19734 19735procedure RangeCoderEncodeNormalize; 19736begin 19737 while ((RangeLow xor RangeHigh) and $ff000000) = 0 do begin 19738 WriteByteToOutput(RangeHigh shr 24); 19739 RangeLow := RangeLow shl 8; 19740 RangeHigh := (RangeHigh shl 8) or $ff; 19741 end; 19742end; 19743 19744function RangeCoderEncodeBit(var Probability : longword; Shift, 19745 BitValue : longword) : longword; 19746begin 19747 RangeMiddle := RangeLow + (((RangeHigh - RangeLow) shr 12) * 19748 Probability); 19749 if BitValue <> 0 then begin 19750 inc(Probability, ($fff - Probability) shr Shift); 19751 RangeHigh := RangeMiddle; 19752 end else begin 19753 dec(Probability, Probability shr Shift); 19754 RangeLow := RangeMiddle + 1; 19755 end; 19756 RangeCoderEncodeNormalize; 19757 result := BitValue; 19758end; 19759 19760procedure RangeCoderDecodeNormalize; 19761begin 19762 while ((RangeLow xor RangeHigh) and $ff000000) = 0 do begin 19763 RangeLow := RangeLow shl 8; 19764 RangeHigh := (RangeHigh shl 8) or $ff; 19765 RangeCode := (RangeCode shl 8) or ReadByteFromInput; 19766 end; 19767end; 19768 19769function RangeCoderDecodeBit(var Probability : longword; 19770 Shift : longword) : longword; 19771begin 19772 RangeMiddle := RangeLow + (((RangeHigh - RangeLow) shr 12) * 19773 Probability); 19774 if RangeCode <= RangeMiddle then begin 19775 inc(Probability, ($fff - Probability) shr Shift); 19776 RangeHigh := RangeMiddle; 19777 result := 1; 19778 end else begin 19779 dec(Probability, Probability shr Shift); 19780 RangeLow := RangeMiddle + 1; 19781 result := 0; 19782 end; 19783 RangeCoderDecodeNormalize; 19784end; 19785@end example 19786 19787The probability may be never zero! But that can't happen here with this 19788adaptive model in this P64 file format, since the adaptive model uses a 19789shift factor of 4 bits and initial probabilities value of 2048, so the 19790probability has a value range from 15 up to 4080 here. If you do want to use 19791the above range coder routines for other stuff with other probability models, 19792then you must to ensure that the probability output value is never zero, for 19793example with "probability |= (probability < 1); " in C. 19794 19795@c @node FIXME 19796@subsection P64 Chunk 'DONE' Layout 19797 19798This is the last empty chunk for to signalize that the correct file end is 19799reached. 19800 19801 19802@node D64, X64 , G64, File formats 19803@section The D64 disk image format 19804 19805@c FIXME: the D64 section needs to be style-checked. 19806 19807(This section was contributed by Peter Schepers and slightly edited by 19808Marco van den Heuvel. Added 42 track info by groepaz) 19809 19810First and foremost we have D64, which is basically a sector-for-sector 19811copy of a 1540/1541 disk. There are several versions of these which I 19812will cover shortly. The standard D64 is a 174848 byte file comprised 19813of 256 byte sectors arranged in 35 tracks with a varying number of 19814sectors per track for a total of 683 sectors. Track counting starts at 198151, not 0, and goes up to 35. Sector counting starts at 0, not 1, for 19816the first sector, therefore a track with 21 sectors will go from 0 to 20. 19817 19818The original media (a 5.25" disk) has the tracks laid out in circles, 19819with track 1 on the very outside of the disk (closest to the sides) to 19820track 35 being on the inside of the disk (closest to the inner hub ring). 19821Commodore, in their infinite wisdom, varied the number of sectors per 19822track and data densities across the disk to optimize available storage, 19823resulting in the chart below. It shows the sectors/track for a standard 19824D64. Since the outside diameter of a circle is the largest (versus closer 19825to the center), the outside tracks have the largest amount of storage. 19826 19827@multitable @columnfractions .33 .33 .33 19828@item @b{Track} 19829@tab @b{Sectors/track} 19830@tab @b{# Sectors} 19831@item 1-17 19832@tab 21 19833@tab 357 19834@item 18-24 19835@tab 19 19836@tab 133 19837@item 25-30 19838@tab 18 19839@tab 108 19840@item 31-35 19841@tab 17 19842@tab 85 19843@item 36-40(*) 19844@tab 17 19845@tab 85 19846@item 41-42(*) 19847@tab 17 19848@tab 34 19849@end multitable 19850 19851@multitable @columnfractions .25 .25 .25 .25 19852@item @b{Track} 19853@tab @b{#Sect} 19854@tab @b{#SectorsIn} 19855@tab @b{D64 Offset} 19856@item 1 19857@tab 21 19858@tab 0 19859@tab $00000 19860@item 2 19861@tab 21 19862@tab 21 19863@tab $01500 19864@item 3 19865@tab 21 19866@tab 42 19867@tab $02A00 19868@item 4 19869@tab 21 19870@tab 63 19871@tab $03F00 19872@item 5 19873@tab 21 19874@tab 84 19875@tab $05400 19876@item 6 19877@tab 21 19878@tab 105 19879@tab $06900 19880@item 7 19881@tab 21 19882@tab 126 19883@tab $07E00 19884@item 8 19885@tab 21 19886@tab 147 19887@tab $09300 19888@item 9 19889@tab 21 19890@tab 168 19891@tab $0A800 19892@item 10 19893@tab 21 19894@tab 189 19895@tab $0BD00 19896@item 11 19897@tab 21 19898@tab 210 19899@tab $0D200 19900@item 12 19901@tab 21 19902@tab 231 19903@tab $0E700 19904@item 13 19905@tab 21 19906@tab 252 19907@tab $0FC00 19908@item 14 19909@tab 21 19910@tab 273 19911@tab $11100 19912@item 15 19913@tab 21 19914@tab 294 19915@tab $12600 19916@item 16 19917@tab 21 19918@tab 315 19919@tab $13B00 19920@item 17 19921@tab 21 19922@tab 336 19923@tab $15000 19924@item 18 19925@tab 19 19926@tab 357 19927@tab $16500 19928@item 19 19929@tab 19 19930@tab 376 19931@tab $17800 19932@item 20 19933@tab 19 19934@tab 395 19935@tab $18B00 19936@item 21 19937@tab 19 19938@tab 414 19939@tab $19E00 19940@item 22 19941@tab 19 19942@tab 433 19943@tab $1B100 19944@item 23 19945@tab 19 19946@tab 452 19947@tab $1C400 19948@item 24 19949@tab 19 19950@tab 471 19951@tab $1D700 19952@item 25 19953@tab 18 19954@tab 490 19955@tab $1EA00 19956@item 26 19957@tab 18 19958@tab 508 19959@tab $1FC00 19960@item 27 19961@tab 18 19962@tab 526 19963@tab $20E00 19964@item 28 19965@tab 18 19966@tab 544 19967@tab $22000 19968@item 29 19969@tab 18 19970@tab 562 19971@tab $23200 19972@item 30 19973@tab 18 19974@tab 580 19975@tab $24400 19976@item 31 19977@tab 17 19978@tab 598 19979@tab $25600 19980@item 32 19981@tab 17 19982@tab 615 19983@tab $26700 19984@item 33 19985@tab 17 19986@tab 632 19987@tab $27800 19988@item 34 19989@tab 17 19990@tab 649 19991@tab $28900 19992@item 35 19993@tab 17 19994@tab 666 19995@tab $29A00 19996@item 36(*) 19997@tab 17 19998@tab 683 19999@tab $2AB00 20000@item 37(*) 20001@tab 17 20002@tab 700 20003@tab $2BC00 20004@item 38(*) 20005@tab 17 20006@tab 717 20007@tab $2CD00 20008@item 39(*) 20009@tab 17 20010@tab 734 20011@tab $2DE00 20012@item 40(*) 20013@tab 17 20014@tab 751 20015@tab $2EF00 20016@item 41(*) 20017@tab 17 20018@tab 768 20019@tab $30000 20020@item 42(*) 20021@tab 17 20022@tab 785 20023@tab $31100 20024@end multitable 20025 20026(*) Tracks 36-40 apply to 40- and 42-track images only. 20027(*) Tracks 41-42 apply to 42-track images only. 20028 20029The directory track should be contained totally on track 18. Sectors 200301-18 contain the entries and sector 0 contains the BAM 20031(Block Availability Map) and disk name/ID. Since the directory is 20032only 18 sectors large (19 less one for the BAM), and each sector can 20033contain only 8 entries (32 bytes per entry), the maximum number of 20034directory entries is 18 * 8 = 144. The first directory sector is 20035always 18/1, even though the t/s pointer at 18/0 (first two bytes) 20036might point somewhere else. It then follows the same chain structure 20037as a normal file, using a sector interleave of 3. This makes the 20038chain links go 18/1, 18/4, 18/7 etc. 20039 20040Note that you can extend the directory off of track 18, but only 20041when reading the disk or image. Attempting to write to a directory 20042sector not on track 18 will cause directory corruption. Each 20043directory sector has the following layout (18/1 partial dump): 20044 20045@example 20046 00: 12 04 81 11 00 4E 41 4D 45 53 20 26 20 50 4F 53 <- notice the T/S link 20047 10: 49 54 A0 A0 A0 00 00 00 00 00 00 00 00 00 15 00 <- to 18/4 ($12/$04) 20048 20: 00 00 84 11 02 41 44 44 49 54 49 4F 4E 41 4C 20 <- and how its not here 20049 30: 49 4E 46 4F A0 11 0C FE 00 00 00 00 00 00 61 01 <- ($00/$00) 20050@end example 20051 20052The first two bytes of the sector ($12/$04) indicate the location of 20053the next track/sector of the directory (18/4). If the track is set 20054to $00, then it is the last sector of the directory. It is possible, 20055however unlikely, that the directory may *not* be competely on track 2005618 (some disks do exist like this). Just follow the chain anyhow. 20057 20058When the directory is done, the track value will be $00. The sector 20059link should contain a value of $FF, meaning the whole sector is 20060allocated, but the actual value doesn't matter. The drive will return 20061all the available entries anyways. 20062 20063This is a breakdown of a standard directory sector: 20064 20065@multitable @columnfractions .2 .8 20066@item @b{Bytes} 20067@tab @b{Description} 20068@item $00-$1F 20069@tab First directory entry 20070@item $20-$3F 20071@tab Second dir entry 20072@item $40-$5F 20073@tab Third dir entry 20074@item $60-$7F 20075@tab Fourth dir entry 20076@item $80-$9F 20077@tab Fifth dir entry 20078@item $A0-$BF 20079@tab Sixth dir entry 20080@item $C0-$DF 20081@tab Seventh dir entry 20082@item $E0-$FF 20083@tab Eighth dir entry 20084@end multitable 20085 20086This is a breakdown of a standard directory entry: 20087 20088@multitable @columnfractions .2 .8 20089@item @b{Bytes} 20090@tab @b{Description} 20091@item $00-$01 20092@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector) 20093@item $02 20094@tab File type 20095@item $03-$04 20096@tab Track/sector location of first sector of file 20097@item $05-$14 20098@tab 16 character filename (in PETASCII, padded with $A0) 20099@item $15-$16 20100@tab Track/Sector location of first side-sector block (REL file only) 20101@item $17 20102@tab REL file record length (REL file only, max. value 254) 20103@item $18-$1D 20104@tab Unused (except with GEOS disks) 20105@item $1E-$1F 20106@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254 20107@end multitable 20108 20109The file type field is used as follows: 20110 20111@multitable @columnfractions .2 .8 20112@item @b{Bits} 20113@tab @b{Description} 20114@item 0-3 20115@tab The actual file type 20116@item 4 20117@tab Unused 20118@item 5 20119@tab Used only during SAVE-@@ replacement 20120@item 6 20121@tab Locked flag (Set produces ">" locked files) 20122@item 7 20123@tab Closed flag (Not set produces "*", or "splat" files) 20124@end multitable 20125 20126The actual file type can be one of the following: 20127 20128@multitable @columnfractions .2 .2 .6 20129@item @b{Binary} 20130@tab @b{Decimal} 20131@tab @b{File type} 20132@item 0000 20133@tab 0 20134@tab DEL 20135@item 0001 20136@tab 1 20137@tab SEQ 20138@item 0010 20139@tab 2 20140@tab PRG 20141@item 0011 20142@tab 3 20143@tab USR 20144@item 0100 20145@tab 4 20146@tab REL 20147@end multitable 20148 20149Values 5-15 are illegal, but if used will produce very strange 20150results. The 1541 is inconsistent in how it treats these bits. 20151Some routines use all 4 bits, others ignore bit 3, resulting in 20152values from 0-7. 20153 20154Files, on a standard 1541, are stored using an interleave of 10. 20155Assuming a starting track/sector of 17/0, the chain would run 2015617/0, 17/10, 17/20, 17/8, 17/18, etc. 20157 20158@c @node FIXME 20159@subsection Non-Standard & Long Directories 20160 20161Most Commdore floppy disk drives use a single dedicated 20162directory track where all filenames are stored. This limits the 20163number of files stored on a disk based on the number of sectors 20164on the directory track. There are some disk images that contain 20165more files than would normally be allowed. This requires extending 20166the directory off the default directory track by changing the last 20167directory sector pointer to a new track, allocating the new 20168sectors in the BAM, and manually placing (or moving existing) file 20169entries there. The directory of an extended disk can be read and 20170the files that reside there can be loaded without problems on a 20171real drive. However, this is still a very dangerous practice as 20172writing to the extended portion of the directory will cause 20173directory corruption in the non-extended part. Many of the floppy 20174drives core ROM routines ignore the track value that the directory 20175is on and assume the default directory track for operations. 20176 20177To explain: assume that the directory has been extended from track 2017818 to track 19/6 and that the directory is full except for a few 20179slots on 19/6. When saving a new file, the drive DOS will find an 20180empty file slot at 19/6 offset $40 and correctly write the filename 20181and a few other things into this slot. When the file is done being 20182saved the final file information will be written to 18/6 offset $40 20183instead of 19/6 causing some directory corruption to the entry at 2018418/6. Also, the BAM entries for the sectors occupied by the new 20185file will not be saved and the new file will be left as a SPLAT (*) 20186file. 20187 20188Attempts to validate the disk will result in those files residing 20189off the directory track to not be allocated in the BAM, and could 20190also send the drive into an endless loop. The default directory 20191track is assumed for all sector reads when validating so if the 20192directory goes to 19/6, then the validate code will read 18/6 20193instead. If 18/6 is part of the normal directory chain then the 20194validate routine will loop endlessly. 20195 20196@c @node FIXME 20197@subsection BAM layout 20198 20199The layout of the BAM area (sector 18/0) is a bit more complicated@dots{} 20200 20201@example 20202 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 20203 ----------------------------------------------- 20204 00: 12 01 41 00 12 FF F9 17 15 FF FF 1F 15 FF FF 1F 20205 10: 15 FF FF 1F 12 FF F9 17 00 00 00 00 00 00 00 00 20206 20: 00 00 00 00 0E FF 74 03 15 FF FF 1F 15 FF FF 1F 20207 30: 0E 3F FC 11 07 E1 80 01 15 FF FF 1F 15 FF FF 1F 20208 40: 15 FF FF 1F 15 FF FF 1F 0D C0 FF 07 13 FF FF 07 20209 50: 13 FF FF 07 11 FF CF 07 13 FF FF 07 12 7F FF 07 20210 60: 13 FF FF 07 0A 75 55 01 00 00 00 00 00 00 00 00 20211 70: 00 00 00 00 00 00 00 00 01 08 00 00 03 02 48 00 20212 80: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 20213 90: 53 48 41 52 45 57 41 52 45 20 31 20 20 A0 A0 A0 20214 A0: A0 A0 56 54 A0 32 41 A0 A0 A0 A0 00 00 00 00 00 20215 B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20216 C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20217 D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20218 E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20219 F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20220@end example 20221 20222@multitable @columnfractions .2 .8 20223@item @b{Bytes} 20224@tab @b{Description} 20225@item $00-$01 20226@tab Track/Sector location of the first directory sector (should be set to 18/1 but it doesn't matter, and don't trust what is there, always go to 18/1 for first directory entry) 20227@item $02 20228@tab Disk DOS version type (see note below) $41 ("A") 20229@item $03 20230@tab Unused 20231@item $04-$8F 20232@tab BAM entries for each track, in groups of four bytes per track, starting on track 1 (see below for more details) 20233@item $90-$9F 20234@tab Disk Name (padded with $A0) 20235@item $A0-$A1 20236@tab Filled with $A0 20237@item $A2-$A3 20238@tab Disk ID 20239@item $A4 20240@tab Usually $A0 20241@item $A5-$A6 20242@tab DOS type, usually "2A" 20243@item $A7-$AA 20244@tab Filled with $A0 20245@item $AB 20246@tab Unused ($00) 20247@item $AC-$BF 20248@tab For DOLPHIN DOS track 36-40 BAM entries, otherwise unused ($00) 20249@item $C0-$D3 20250@tab For SPEED DOS track 36-40 BAM entries, otherwise unused ($00) 20251@item $D4-$FF Unused ($00) 20252@end multitable 20253 20254Note: The BAM entries for SPEED, DOLPHIN and ProLogic DOS use 20255the same layout as standard BAM entries. One of the interesting 20256things from the BAM sector is the byte at offset $02, the DOS 20257version byte. If it is set to anything other than $41 or $00, 20258then we have what is called "soft write protection". Any attempt 20259to write to the disk will return the "DOS Version" error code 2026073 ,"CBM DOS V 2.6 1541". The 1541 is simply telling you that it 20261thinks the disk format version is incorrect. This message will 20262normally come up when you first turn on the 1541 and read the 20263error channel. If you write a $00 or a $41 into 1541 memory 20264location $00FF (for device 0), then you can circumvent this type 20265of write-protection, and change the DOS version back to what it 20266should be. 20267 20268The BAM entries require a bit (no pun intended) more of a 20269breakdown. Take the first entry at bytes $04-$07 ($12 $FF $F9 $17). 20270The first byte ($12) is the number of free sectors on that track. 20271Since we are looking at the track 1 entry, this means it has 18 20272(decimal) free sectors. The next three bytes represent the bitmap 20273of which sectors are used/free. Since it is 3 bytes (8 bits/byte) 20274we have 24 bits of storage. Remember that at most, each track only 20275has 21 sectors, so there are a few unused bits. 20276 20277@multitable @columnfractions .2 .4 .4 20278@item @b{Bytes} 20279@tab @b{Data} 20280@tab @b{Description} 20281@item $04-$07 20282@tab $12 $FF $F9 $17 20283@tab Track 1 BAM 20284@item $08-$0B 20285@tab $15 $FF $FF $FF 20286@tab Track 2 BAM 20287@item $0C-$0F 20288@tab $15 $FF $FF $1F 20289@tab Track 3 BAM 20290@item @dots{} 20291@tab @dots{} 20292@tab @dots{} 20293@item $8C-$8F 20294@tab $11 $FF $FF $01 20295@tab Track 35 BAM 20296@end multitable 20297 20298These entries must be viewed in binary to make any sense. We will 20299use the first entry (track 1) at bytes 04-07: 20300 20301@example 20302 FF=11111111, F9=11111001, 17=00010111 20303@end example 20304 20305In order to make any sense from the binary notation, flip the 20306bits around. 20307 20308@example 20309 111111 11112222 20310 01234567 89012345 67890123 20311 -------------------------- 20312 11111111 10011111 11101000 20313 ^ ^ 20314 sector 0 sector 20 20315@end example 20316 20317Since we are on the first track, we have 21 sectors, and only 20318use up to the bit 20 position. If a bit is on (1), the sector 20319is free. Therefore, track 1 has sectors 9, 10 and 19 used, 20320all the rest are free. Any leftover bits that refer to 20321sectors that don't exist, like bits 21-23 in the above 20322example, are set to allocated. 20323 20324Each filetype has its own unique properties, but most follow 20325one simple structure. The first file sector is pointed to by 20326the directory and follows a t/s chain, until the track value 20327reaches $00. When this happens, the value in the sector link 20328location indicates how much of the sector is used. For 20329example, the following chain indicates a file 6 sectors 20330long, and ends when we encounter the $00/$34 chain. At this 20331point the last sector occupies from bytes $02-$34. 20332 20333@multitable @columnfractions .16 .16 .16 .16 .16 .16 20334@item 1 20335@tab 2 20336@tab 3 20337@tab 4 20338@tab 5 20339@tab 6 20340@item ---- 20341@tab ---- 20342@tab ---- 20343@tab ---- 20344@tab ---- 20345@tab ---- 20346@item 17/0 20347@tab 17/10 20348@tab 17/20 20349@tab 17/1 20350@tab 17/11 20351@tab 0/52 20352@item (11/00) 20353@tab (11/0A) 20354@tab (11/14) 20355@tab (11/01) 20356@tab (11/0B) 20357@tab (0/34) 20358@end multitable 20359 20360@c @node FIXME 20361@subsection Variations on the D64 layout 20362 20363These are some variations of the D64 layout: 20364 203651. Standard 35 track layout but with 683 error bytes added on 20366to the end of the file. Each byte of the error info 20367corresponds to a single sector stored in the D64, indicating 20368if the sector on the original disk contained an error. The 20369first byte is for track 1/0, and the last byte is for track 2037035/16. 20371 203722. A 40 track layout, following the same layout as a 35 track 20373disk, but with 5 extra tracks. These contain 17 sectors each, 20374like tracks 31-35. Some of the PC utilities do allow you to 20375create and work with these files. This can also have error 20376bytes attached like variant #1. 20377 203783. A 42 track layout, with two extra tracks of 17 sectors each. 20379This is extremely uncommon, since real drives often have problems 20380with accessing these tracks, software that uses them is very rare. 20381 203824. The Commodore 128 allowed for "auto-boot" disks. With this, 20383t/s 1/0 holds a specific byte sequence which the computer 20384recognizes as boot code. 20385 20386Below is a small chart detailing the standard file sizes of 20387D64 images, 35, 40 or 42 tracks, with or without error bytes. 20388 20389@multitable @columnfractions .5 .5 20390@item @b{Disk type} 20391@tab @b{Size} 20392@item 35 track, no errors 20393@tab 174848 20394@item 35 track, 683 error bytes 20395@tab 175531 20396@item 40 track, no errors 20397@tab 196608 20398@item 40 track, 768 error bytes 20399@tab 197376 20400@item 42 track, no errors 20401@tab 205312 20402@item 42 track, 802 error bytes 20403@tab 206114 20404@end multitable 20405 20406The following table (provided by Wolfgang Moser) outlines 20407the differences between the standard 1541 DOS and the 20408various "speeder" DOS's that exist. The 'header 7/8' 20409category is the 'fill bytes' as the end of the sector 20410header of a real 1541 disk. 20411 20412@multitable @columnfractions .5 .1 .1 .1 .2 20413@item @b{Disk format} 20414@tab @b{tracks} 20415@tab @b{header 7/8} 20416@tab @b{Dos type} 20417@tab @b{Diskdos vs. type} 20418@item Original CBM DOS v2.6 20419@tab 35 20420@tab $0f $0f 20421@tab "2A" 20422@tab $41/'A' 20423@item *SpeedDOS+ 20424@tab 40 20425@tab $0f $0f 20426@tab "2A" 20427@tab $41/'A' 20428@item Professional DOS Initial 20429@tab 35 20430@tab $0f $0f 20431@tab "2A" 20432@tab $41/'A' 20433@item Professional DOS Version 1/Prototype 20434@tab 40 20435@tab $0f $0f 20436@tab "2A" 20437@tab $41/'A' 20438@item ProfDOS Release 20439@tab 40 20440@tab $0f $0f 20441@tab "4A" 20442@tab $41/'A' 20443@item Dolphin-DOS 2.0/3.0 20444@tab 35 20445@tab $0f $0f 20446@tab "2A" 20447@tab $41/'A' 20448@item Dolphin-DOS 2.0/3.0 20449@tab 40 20450@tab $0d $0f 20451@tab "2A" 20452@tab $41/'A' 20453@item PrologicDOS 1541 20454@tab 35 20455@tab $0f $0f 20456@tab "2A" 20457@tab $41/'A' 20458@item PrologicDOS 1541 20459@tab 40 20460@tab $0f $0f 20461@tab "2P" 20462@tab $50/'P' 20463@item ProSpeed 1571 2.0 20464@tab 35 20465@tab $0f $0f 20466@tab "2A" 20467@tab $41/'A' 20468@item ProSpeed 1571 2.0 20469@tab 40 20470@tab $0f $0f 20471@tab "2P" 20472@tab $50/'P' 20473@end multitable 20474 20475*Note: There are also clones of SpeedDOS that exist, such as 20476RoloDOS and DigiDOS. Both are just a change of the DOS startup 20477string. 20478 20479The location of the extra BAM information in sector 18/0, for 2048040 track images, will be different depending on what standard 20481the disks have been formatted with. SPEED DOS stores them from 20482$C0 to $D3, DOLPHIN DOS stores them from $AC to $BF and 20483PrologicDOS stored them right after the existing BAM entries 20484from $90-A3. PrologicDOS also moves the disk label and ID 20485forward from the standard location of $90 to $A4. 64COPY and 20486Star Commander let you select from several different types of 20487extended disk formats you want to create/work with. 20488 20489All three of the speeder DOS's mentioned above don't alter the 20490standard sector interleave of 10 for files and 3 for 20491directories. The reason is that they use a memory cache 20492installed in the drive which reads the entire track in one 20493pass. This alleviates the need for custom interleave values. 20494They do seem to alter the algorithm that finds the next 20495available free sector so that the interleave value can deviate 20496from 10 under certain circumstances, but I don't know why they 20497would bother. 20498 20499Below is a HEX dump of a Speed DOS BAM sector. Note the 20500location of the extra BAM info from $C0-D3. 20501 20502@example 20503 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 20504 ----------------------------------------------- 20505 0070: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01 20506 0080: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 20507 0090: A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 20508 00A0: A0 A0 30 30 A0 32 41 A0 A0 A0 A0 00 00 00 00 00 20509 00B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20510 00C0: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 20511 00D0: 11 FF FF 01 00 00 00 00 00 00 00 00 00 00 00 00 20512@end example 20513 20514Below is a HEX dump of a Dolphin DOS BAM sector. Note 20515the location of the extra BAM info from $AC-BF. 20516 20517@example 20518 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 20519 ----------------------------------------------- 20520 0070: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01 20521 0080: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 20522 0090: A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 20523 00A0: A0 A0 30 30 A0 32 41 A0 A0 A0 A0 00 11 FF FF 01 20524 00B0: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 20525 00C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20526 00D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20527@end example 20528 20529Below is a HEX dump of a PrologicDOS BAM sector. Note 20530that the disk name and ID are now located at $A4 instead 20531of starting at $90. 20532 20533@example 20534 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 20535 ----------------------------------------------- 20536 0070: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01 20537 0080: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 20538 0090: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 20539 00A0: 11 FF FF 01 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 20540 00B0: A0 A0 A0 A0 A0 A0 30 30 A0 32 50 A0 A0 A0 A0 00 20541 00C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20542 00D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 20543@end example 20544 20545@c @node FIXME 20546@subsection Error codes 20547 20548Here is the meaning of the error bytes added onto the end of 20549any extended D64. The CODE is the same as that generated by 20550the 1541 drive controller@dots{} it reports these numbers, not 20551the error code we usually see when an error occurs. 20552 20553Some of what comes below is taken from Immers/Neufeld book 20554"Inside Commodore DOS". Note the descriptions are not 20555completely accurate as to what the drive DOS is actually 20556doing to seek/read/decode/write sectors, but serve as simple 20557examples only. The "type" field is where the error usually 20558occurs, whether it's searching for any SYNC mark, any header 20559ID, any valid header, or reading a sector. 20560 20561@multitable @columnfractions .15 .15 .15 .15 .4 20562@item @b{Code} 20563@tab @b{Error} 20564@tab @b{Type} 20565@tab @b{D64} 20566@tab @b{Description} 20567@item $01 20568@tab 00 20569@tab N/A 20570@tab * 20571@tab No error. 20572@item $02 20573@tab 20 20574@tab Seek 20575@tab * 20576@tab Header block not found / Header descriptor byte not found 20577@item $03 20578@tab 21 20579@tab Seek 20580@tab * 20581@tab No SYNC sequence found 20582@item $04 20583@tab 22 20584@tab Read 20585@tab * 20586@tab Data descriptor byte not found 20587@item $05 20588@tab 23 20589@tab Read 20590@tab * 20591@tab Checksum error in data block 20592@item $06 20593@tab 24 20594@tab Write 20595@tab 20596@tab Write verify on format (never occurs on 1541) 20597@item $07 20598@tab 25 20599@tab Write 20600@tab 20601@tab Write verify error 20602@item $08 20603@tab 26 20604@tab Write 20605@tab 20606@tab Write protect on 20607@item $09 20608@tab 27 20609@tab Seek 20610@tab * 20611@tab Checksum error in header block 20612@item $0A 20613@tab 28 20614@tab Write 20615@tab 20616@tab Write error (never occurs on 1541) 20617@item $0B 20618@tab 29 20619@tab Seek 20620@tab * 20621@tab Disk sector ID mismatch 20622@item $0F 20623@tab 74 20624@tab Read 20625@tab 20626@tab Drive Not Ready (no disk in drive or no device 1) 20627@end multitable 20628 20629Codes $0 and $C to $E are unused and never occur. 20630 20631These first errors are "seek" errors, where the disk 20632controller is simply reading headers and looking at 20633descriptor bytes, checksums, format ID's and reporting what 20634errors it sees. These errors do *not* necessarily apply to 20635the exact sector being looked for. This fact makes 20636duplication of these errors very unreliable. 20637 20638Code : $03 20639Error : 21 20640Type : Seek 20641Message : No SYNC sequence found. 20642 20643Each sector data block and header block are preceeded by 20644SYNC marks. If *no* sync sequence is found within 20 20645milliseconds (only ~1/10 of a disk rotation!) then this 20646error is generated. This error used to mean the entire 20647track is bad, but it does not have to be the case. Only 20648a small area of the track needs to be without a SYNC 20649mark and this error will be generated. 20650 20651Converting this error to a D64 is very problematic 20652because it depends on where the physical head is on the 20653disk when a read attempt is made. If it is on valid 20654header/sectors then it won't occur. If it happens over 20655an area without SYNC marks, it will happen. 20656 20657Code : $02 20658Error : 20 20659Type : Seek 20660Message : Header descriptor byte not found (HEX $08, GCR $52) 20661 20662Each sector is preceeded by an 8-byte GCR header block, which 20663starts with the value $52 (GCR). If this value is not found 20664after 90 attempts, this error is generated. 20665 20666Basically, what a track has is SYNC marks, and possibly valid 20667data blocks, but no valid header descriptors. 20668 20669Code : $09 20670Error : 27 20671Type : Seek 20672Message : Checksum error in header block 20673 20674The header block contains a checksum value, calculated by 20675XOR'ing the TRACK, SECTOR, ID1 and ID2 values. If this 20676checksum is wrong, this error is generated. 20677 20678Code : $0B 20679Error : 29 20680Type : Seek 20681Message : Disk sector ID mismatch 20682 20683The ID's from the header block of the currently read sector are 20684compared against the ones from the low-level header of 18/0. If 20685there is a mismatch, this error is generated. 20686 20687Code : $02 20688Error : 20 20689Type : Seek 20690Message : Header block not found 20691 20692This error can be reported again when searching for the correct 20693header block. An image of the header is built and searched for, 20694but not found after 90 read attempts. Note the difference from 20695the first occurance. The first one only searches for a valid 20696ID, not the whole header. 20697 20698Note that error 20 occurs twice during this phase. The first 20699time is when a header ID is being searched for, the second is 20700when the proper header pattern for the sector being searched 20701for is not found. 20702 20703From this point on, all the errors apply to the specific 20704sector you are looking for. If a read passed all the previous 20705checks, then we are at the sector being searched for. 20706 20707Note that the entire sector is read before these errors are 20708detected. Therefore the data, checksum and off bytes are 20709available. 20710 20711Code : $04 20712Error : 22 20713Type : Read 20714Message : Data descriptor byte not found (HEX $07, GCR $55) 20715 20716Each sector data block is preceeded by the value $07, the 20717"data block" descriptor. If this value is not there, this 20718error is generated. Each encoded sector has actually 260 20719bytes. First is the descriptor byte, then follows the 20720256 bytes of data, a checksum, and two "off" bytes. 20721 20722Code : $05 20723Error : 23 20724Type : Read 20725Message : Checksum error in data block 20726 20727The checksum of the data read of the disk is calculated, and 20728compared against the one stored at the end of the sector. If 20729there's a discrepancy, this error is generated. 20730 20731Code : $0F 20732Error : 74 20733Type : Read 20734Message : Drive Not Ready (no disk in drive or no device 1) 20735 20736These errors only apply when writing to a disk. I don't see the 20737usefulness of having these as they cannot be present when only 20738*reading* a disk. 20739 20740Code : $06 20741Error : 24 20742Type : Write 20743Message : Write verify (on format) 20744 20745Code : $07 20746Error : 25 20747Type : Write 20748Message : Write verify error 20749 20750Once the GCR-encoded sector is written out, the drive waits for 20751the sector to come around again and verifies the whole 325-byte 20752GCR block. Any errors encountered will generate this error. 20753 20754Code : $08 20755Error : 26 20756Type : Write 20757Message : Write protect on 20758 20759Self explanatory. Remove the write-protect tab, and try again. 20760 20761Code : $0A 20762Error : 28 20763Type : Write 20764Message : Write error 20765 20766In actual fact, this error never occurs, but it is included 20767for completeness. 20768 20769This is not an error at all, but it gets reported when the 20770read of a sector is ok. 20771 20772Code : $01 20773Error : 00 20774Type : N/A 20775Message : No error. 20776 20777Self explanatory. No errors were detected in the reading 20778and decoding of the sector. 20779 20780The advantage with using the 35 track D64 format, regardless of 20781error bytes, is that it can be converted directly back to a 1541 20782disk by either using the proper cable and software on the PC, or 20783send it down to the C64 and writing it back to a 1541. It is the 20784best documented format since it is also native to the C64, with 20785many books explaining the disk layout and the internals of the 207861541. 20787 20788@node X64, D71, D64, File formats 20789@section The X64 disk image format 20790 20791@c FIXME: the X64 section needs to be style-checked. 20792 20793(This section was contributed by Peter Schepers and slightly edited by 20794Marco van den Heuvel.) 20795 20796This file type, created by Teemu Rantanen, was used on the X64 20797emulator (a UNIX-based emulator) which has been superceeded by 20798VICE. Both VICE and X64 support the X64 file standard, with 20799VICE also supporting the regular D64 and T64 files. 20800 20801Note that this ancient format is deprecated and subject for removal. It never 20802got any momentum in the emulation community, and VICE never supported it for 20803anything but 1541 disks. 20804 20805X64 is not a specific type of file, but rather encompasses 20806*all* known C64 disk types (hard disk, floppies, etc). An X64 20807is created by prepending a 64-byte header to an existing image 20808(1541, 1571, etc) and setting specific bytes which describe 20809what type of image follows. This header has undergone some 20810revision, and this description is based on the 1.02 version, 20811which was the last known at the time of writing. 20812 20813The most common X64 file you will see is the D64 variety, 20814typically 174912 bytes long (174848 for the D64 and 64 bytes 20815for the header, assuming no error bytes are appended). The 20816header layout (as used in 64COPY) is as follows: 20817 20818@example 20819 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 20820 ----------------------------------------------- 208210000: 43 15 41 64 01 02 01 23 00 00 00 00 00 00 00 00 208220010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 208230020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 208240030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 208250040: XX XX XX <- standard C64 image starts here@dots{}. 20826@end example 20827 20828@multitable @columnfractions .2 .8 20829@item @b{Bytes} 20830@tab @b{Description} 20831@item $00-$03 20832@tab This is the "Magic header" ($43 $15 $41 $64) 20833@item $04 20834@tab Header version major ($01) 20835@item $05 20836@tab Header version minor ($01, now its up to $02) 20837@item $06 20838@tab Device type represented 20839@item $07 20840@tab Maximum tracks in image (only in version 1.02 or greater) 1540/41/70: 35 1571: 35 1581: 80 (Logical single-sided disk) 20841@item $08 20842@tab Number of disk sides in image. This value must be $00 for all 1541 and 1581 formats. $00=No second side $01=Second side 20843@item $09 20844@tab Error data flag. 20845@item $0A-$1F 20846@tab Unused, set to $00 20847@item $20-$3E 20848@tab Disk image description (in ASCII or ISO Latin/1) 20849@item $3F 20850@tab Always set to $00 20851@item $40- 20852@tab Standard C64 file begins here. 20853@end multitable 20854 20855The device types are: 20856 20857@multitable @columnfractions .2 .8 20858@item @b{Value} 20859@tab @b{Drive type} 20860@item $00 20861@tab 1540 See note below@dots{} 20862@item $01 20863@tab 1541 (Default) 20864@item $02 20865@tab 1542 20866@item $03 20867@tab 1551 20868@item $04 20869@tab 1570 20870@item $05 20871@tab 1571 20872@item $06 20873@tab 1572 20874@item $08 20875@tab 1581 20876@item $10 20877@tab 2031 or 4031 20878@item $11 20879@tab 2040 or 3040 20880@item $12 20881@tab 2041 20882@item $18 20883@tab 4040 20884@item $20 20885@tab 8050 20886@item $21 20887@tab 8060 20888@item $22 20889@tab 8061 20890@item $30 20891@tab SFD-1001 20892@item $31 20893@tab 8250 20894@item $32 20895@tab 8280 20896@end multitable 20897 20898The first four bytes used for the device type at position $06 20899($00 to $03) are functionally the same, and are compatible with 20900older version of X64 files. Some old X64 files might have $00 20901for the device type (instead of $01), but it makes no real 20902difference. 20903 20904As most instances of X64 files will be strictly 1541 images, 20905bytes $08-$3F are set to zero, and some versions of the X64 20906emulator don't use bytes $08-$3F. 20907 20908@node D71, D81, X64, File formats 20909@section The D71 disk image format 20910 20911@c FIXME: the D71 section needs to be style-checked. 20912 20913(This section was contributed by Peter Schepers and slightly edited by 20914Marco van den Heuvel.) 20915 20916Similar to the D64 (1541), the 1571 drive can operate in either 20917single-sided (1541 compatible) mode or double-sided (1571) mode. In 20918this section I will be dealing with the double-sided mode only. For 20919the breakdown of the single-sided mode, see the D64 section. 20920 20921The D71 has 70 tracks, double that of the 1541, with a DOS file 20922size of 349696 bytes. If the error byte block (1366 bytes) is 20923attached, this makes the file size 351062 bytes. The track range 20924and offsets into the D71 files are as follows: 20925 20926@multitable @columnfractions .5 .25 .25 20927@item @b{Track} 20928@tab @b{Sec/trk} 20929@tab @b{# Sectors} 20930@item 1-17 (side 0) 20931@tab 21 20932@tab 357 20933@item 18-24 (side 0) 20934@tab 19 20935@tab 133 20936@item 25-30 (side 0) 20937@tab 18 20938@tab 108 20939@item 31-35 (side 0) 20940@tab 17 20941@tab 85 20942@item 36-52 (side 1) 20943@tab 21 20944@tab 357 20945@item 53-59 (side 1) 20946@tab 19 20947@tab 133 20948@item 60-65 (side 1) 20949@tab 18 20950@tab 108 20951@item 66-70 (side 1) 20952@tab 17 20953@tab 85 20954@end multitable 20955 20956@multitable @columnfractions .25 .25 .25 .25 20957@item @b{Track} 20958@tab @b{#Sect} 20959@tab @b{#SectorsIn} 20960@tab @b{D71 Offset} 20961@item 1 20962@tab 21 20963@tab 0 20964@tab $00000 20965@item 2 20966@tab 21 20967@tab 21 20968@tab $01500 20969@item 3 20970@tab 21 20971@tab 42 20972@tab $02A00 20973@item 4 20974@tab 21 20975@tab 63 20976@tab $03F00 20977@item 5 20978@tab 21 20979@tab 84 20980@tab $05400 20981@item 6 20982@tab 21 20983@tab 105 20984@tab $06900 20985@item 7 20986@tab 21 20987@tab 126 20988@tab $07E00 20989@item 8 20990@tab 21 20991@tab 147 20992@tab $09300 20993@item 9 20994@tab 21 20995@tab 168 20996@tab $0A800 20997@item 10 20998@tab 21 20999@tab 189 21000@tab $0BD00 21001@item 11 21002@tab 21 21003@tab 210 21004@tab $0D200 21005@item 12 21006@tab 21 21007@tab 231 21008@tab $0E700 21009@item 13 21010@tab 21 21011@tab 252 21012@tab $0FC00 21013@item 14 21014@tab 21 21015@tab 273 21016@tab $11100 21017@item 15 21018@tab 21 21019@tab 294 21020@tab $12600 21021@item 16 21022@tab 21 21023@tab 315 21024@tab $13B00 21025@item 17 21026@tab 21 21027@tab 336 21028@tab $15000 21029@item 18 21030@tab 19 21031@tab 357 21032@tab $16500 21033@item 19 21034@tab 19 21035@tab 376 21036@tab $17800 21037@item 20 21038@tab 19 21039@tab 395 21040@tab $18B00 21041@item 21 21042@tab 19 21043@tab 414 21044@tab $19E00 21045@item 22 21046@tab 19 21047@tab 433 21048@tab $1B100 21049@item 23 21050@tab 19 21051@tab 452 21052@tab $1C400 21053@item 24 21054@tab 19 21055@tab 471 21056@tab $1D700 21057@item 25 21058@tab 18 21059@tab 490 21060@tab $1EA00 21061@item 26 21062@tab 18 21063@tab 508 21064@tab $1FC00 21065@item 27 21066@tab 18 21067@tab 526 21068@tab $20E00 21069@item 28 21070@tab 18 21071@tab 544 21072@tab $22000 21073@item 29 21074@tab 18 21075@tab 562 21076@tab $23200 21077@item 30 21078@tab 18 21079@tab 580 21080@tab $24400 21081@item 31 21082@tab 17 21083@tab 598 21084@tab $25600 21085@item 32 21086@tab 17 21087@tab 615 21088@tab $26700 21089@item 33 21090@tab 17 21091@tab 632 21092@tab $27800 21093@item 34 21094@tab 17 21095@tab 649 21096@tab $28900 21097@item 35 21098@tab 17 21099@tab 666 21100@tab $29A00 21101@item 36 21102@tab 21 21103@tab 683 21104@tab $2AB00 21105@item 37 21106@tab 21 21107@tab 704 21108@tab $2C000 21109@item 38 21110@tab 21 21111@tab 725 21112@tab $2D500 21113@item 39 21114@tab 21 21115@tab 746 21116@tab $2EA00 21117@item 40 21118@tab 21 21119@tab 767 21120@tab $2FF00 21121@item 41 21122@tab 21 21123@tab 788 21124@tab $31400 21125@item 42 21126@tab 21 21127@tab 809 21128@tab $32900 21129@item 43 21130@tab 21 21131@tab 830 21132@tab $33E00 21133@item 44 21134@tab 21 21135@tab 851 21136@tab $35300 21137@item 45 21138@tab 21 21139@tab 872 21140@tab $36800 21141@item 46 21142@tab 21 21143@tab 893 21144@tab $37D00 21145@item 47 21146@tab 21 21147@tab 914 21148@tab $39200 21149@item 48 21150@tab 21 21151@tab 935 21152@tab $3A700 21153@item 49 21154@tab 21 21155@tab 956 21156@tab $3BC00 21157@item 50 21158@tab 21 21159@tab 977 21160@tab $3D100 21161@item 51 21162@tab 21 21163@tab 998 21164@tab $3E600 21165@item 52 21166@tab 21 21167@tab 1019 21168@tab $3FB00 21169@item 53 21170@tab 19 21171@tab 1040 21172@tab $41000 21173@item 54 21174@tab 19 21175@tab 1059 21176@tab $42300 21177@item 55 21178@tab 19 21179@tab 1078 21180@tab $43600 21181@item 56 21182@tab 19 21183@tab 1097 21184@tab $44900 21185@item 57 21186@tab 19 21187@tab 1116 21188@tab $45C00 21189@item 58 21190@tab 19 21191@tab 1135 21192@tab $46F00 21193@item 59 21194@tab 19 21195@tab 1154 21196@tab $48200 21197@item 60 21198@tab 18 21199@tab 1173 21200@tab $49500 21201@item 61 21202@tab 18 21203@tab 1191 21204@tab $4A700 21205@item 62 21206@tab 18 21207@tab 1209 21208@tab $4B900 21209@item 63 21210@tab 18 21211@tab 1227 21212@tab $4CB00 21213@item 64 21214@tab 18 21215@tab 1245 21216@tab $4DD00 21217@item 65 21218@tab 18 21219@tab 1263 21220@tab $4EF00 21221@item 66 21222@tab 17 21223@tab 1281 21224@tab $50100 21225@item 67 21226@tab 17 21227@tab 1298 21228@tab $51200 21229@item 68 21230@tab 17 21231@tab 1315 21232@tab $52300 21233@item 69 21234@tab 17 21235@tab 1332 21236@tab $53400 21237@item 70 21238@tab 17 21239@tab 1349 21240@tab $54500 21241@end multitable 21242 21243The directory structure is the same as a D64/1541. All the same 21244filetypes apply, the directory still only holds 144 files per 21245disk and should only exist on track 18. 21246 21247The first two bytes of the sector ($12/$04 or 18/4) indicate 21248the location of the next track/sector of the directory. If the 21249track value is set to $00, then it is the last sector of the 21250directory. It is possible, however unlikely, that the directory 21251may *not* be competely on track 18 (some disks do exist like 21252this). Just follow the chain anyhow. 21253 21254When the directory is done, the track value will be $00. The 21255sector link should contain a value of $FF, meaning the whole 21256sector is allocated, but the actual value doesn't matter. The 21257drive will return all the available entries anyways. This is a 21258breakdown of a standard directory sector and entry: 21259 21260@example 21261 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 21262 ----------------------------------------------- 2126300: 12 04 82 11 00 4A 45 54 20 53 45 54 20 57 49 4C 2126410: 4C 59 A0 A0 A0 00 00 00 00 00 00 00 00 00 2B 00 2126520: 00 00 82 0F 01 4A 53 57 20 31 A0 A0 A0 A0 A0 A0 2126630: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 BF 00 2126740: 00 00 82 06 03 53 4F 4E 20 4F 46 20 42 4C 41 47 2126850: 47 45 52 A0 A0 00 00 00 00 00 00 00 00 00 AE 00 2126960: 00 00 82 15 0D 50 4F 54 54 59 20 50 49 47 45 4F 2127070: 4E A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 A2 00 2127180: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2127290: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21273A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21274B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21275C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21276D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21277E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21278F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21279@end example 21280 21281@multitable @columnfractions .2 .8 21282@item @b{Bytes} 21283@tab @b{Description} 21284@item $00-$1F 21285@tab First directory entry 21286@item $20-$3F 21287@tab Second dir entry 21288@item $40-$5F 21289@tab Third dir entry 21290@item $60-$7F 21291@tab Fourth dir entry 21292@item $80-$9F 21293@tab Fifth dir entry 21294@item $A0-$BF 21295@tab Sixth dir entry 21296@item $C0-$DF 21297@tab Seventh dir entry 21298@item $E0-$FF 21299@tab Eighth dir entry 21300@end multitable 21301 21302This is a breakdown of a standard directory entry: 21303 21304@multitable @columnfractions .2 .8 21305@item @b{Bytes} 21306@tab @b{Description} 21307@item $00-$01 21308@tab Track/Sector location of next directory sector ($00/$FF if its the last sector) 21309@item $02 21310@tab File type 21311@item $03-$04 21312@tab Track/sector location of first sector of file 21313@item $05-$14 21314@tab 16 character filename (in PETASCII, padded with $A0) 21315@item $15-$16 21316@tab Track/Sector location of first side-sector block (REL file only) 21317@item $17 21318@tab REL file record length (REL file only, max. value 254) 21319@item $18-$1D 21320@tab Unused (except with GEOS disks) 21321@item $1E-$1F 21322@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254 21323@end multitable 21324 21325The file type field is used as follows: 21326 21327@multitable @columnfractions .2 .8 21328@item @b{Bits} 21329@tab @b{Description} 21330@item 0-3 21331@tab The actual file type 21332@item 4 21333@tab Unused 21334@item 5 21335@tab Used only during SAVE-@@ replacement 21336@item 6 21337@tab Locked flag (Set produces ">" locked files) 21338@item 7 21339@tab Closed flag (Not set produces "*", or "splat" files) 21340@end multitable 21341 21342The actual file type can be one of the following: 21343 21344@multitable @columnfractions .2 .2 .6 21345@item @b{Binary} 21346@tab @b{Decimal} 21347@tab @b{File type} 21348@item 0000 21349@tab 0 21350@tab DEL 21351@item 0001 21352@tab 1 21353@tab SEQ 21354@item 0010 21355@tab 2 21356@tab PRG 21357@item 0011 21358@tab 3 21359@tab USR 21360@item 0100 21361@tab 4 21362@tab REL 21363@end multitable 21364 21365Values 5-15 are illegal, but if used will produce very strange 21366results. The 1571 is inconsistent in how it treats these bits. 21367Some routines use all 4 bits, others ignore bit 3, resulting in 21368values from 0-7. 21369 21370When the 1571 is in is native ("1571") mode, files are stored 21371with a sector interleave of 6, rather than 10 which the 1541 21372(and the 1571 in "1541" mode) uses. The directory still uses an 21373interleave of 3. 21374 21375@c @node FIXME 21376@subsection Non-Standard & Long Directories 21377 21378Most Commodore floppy disk drives use a single dedicated 21379directory track where all filenames are stored. This limits the 21380number of files stored on a disk based on the number of sectors 21381on the directory track. There are some disk images that contain 21382more files than would normally be allowed. This requires 21383extending the directory off the default directory track by 21384changing the last directory sector pointer to a new track, 21385allocating the new sectors in the BAM, and manually placing (or 21386moving existing) file entries there. The directory of an 21387extended disk can be read and the files that reside there can be 21388loaded without problems on a real drive. However, this is still 21389a very dangerous practice as writing to the extended portion of 21390the directory will cause directory corruption in the non- 21391extended part. Many of the floppy drives core ROM routines 21392ignore the track value that the directory is on and assume the 21393default directory track for operations. 21394 21395To explain: assume that the directory has been extended from 21396track 18 to track 19/6 and that the directory is full except 21397for a few slots on 19/6. When saving a new file, the drive DOS 21398will find an empty file slot at 19/6 offset $40 and correctly 21399write the filename and a few other things into this slot. When 21400the file is done being saved the final file information will 21401be written to 18/6 offset $40 instead of 19/6 causing some 21402directory corruption to the entry at 18/6. Also, the BAM 21403entries for the sectors occupied by the new file will not be 21404saved and the new file will be left as a SPLAT (*) file. 21405 21406Attempts to validate the disk will result in those files 21407residing off the directory track to not be allocated in the 21408BAM, and could also send the drive into an endless loop. The 21409default directory track is assumed for all sector reads when 21410validating so if the directory goes to 19/6, then the validate 21411code will read 18/6 instead. If 18/6 is part of the normal 21412directory chain then the validate routine will loop endlessly. 21413 21414@c @node FIXME 21415@subsection Bam layout 21416The BAM is somewhat different as it now has to 21417take 35 new tracks into account. In order to do this, most of 21418the extra BAM information is stored on track 53/0, and the 21419remaining sectors on track 53 are marked in the BAM as 21420allocated. This does mean that except for one allocated 21421sector on track 53, the rest of the track is unused and 21422wasted. (Track 53 is the equivalent to track 18, but on the 21423flip side of the disk). Here is a dump of the first BAM 21424sector@dots{} 21425 21426@example 21427 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 21428 ----------------------------------------------- 2142900: 12 01 41 80 12 FF F9 17 15 FF FF 1F 15 FF FF 1F 2143010: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 2143120: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 2143230: 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 15 FF FF 1F 2143340: 15 FF FF 1F 15 FF FF 1F 11 FC FF 07 13 FF FF 07 2143450: 13 FF FF 07 13 FF FF 07 13 FF FF 07 13 FF FF 07 2143560: 13 FF FF 07 12 FF FF 03 12 FF FF 03 12 FF FF 03 2143670: 12 FF FF 03 12 FF FF 03 12 FF FF 03 11 FF FF 01 2143780: 11 FF FF 01 11 FF FF 01 11 FF FF 01 11 FF FF 01 2143890: A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 A0 21439A0: A0 A0 30 30 A0 32 41 A0 A0 A0 A0 00 00 00 00 00 21440B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21441C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21442D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 15 15 15 21443E0: 15 15 15 15 15 15 15 15 15 15 15 15 15 15 00 13 21444F0: 13 13 13 13 13 12 12 12 12 12 12 11 11 11 11 11 21445@end example 21446 21447@multitable @columnfractions .5 .5 21448@item @b{Bytes} 21449@tab @b{Description} 21450@item $00-$01 21451@tab Track/Sector location of the first directory sector (should be set to 18/1 but it doesn't matter, and don't trust what is there, always go to 18/1 for first directory entry) 21452@item $02 21453@tab Disk DOS version type (see note below) $41 ('A') = 1541 21454@item $03 21455@tab Double-sided flag $00 - Single sided disk $80 - Double sided disk 21456@item $04-8F 21457@tab BAM entries for each track, in groups of four bytes per track, starting on track 1. 21458@item $90-$9F 21459@tab Disk Name (padded with $A0) 21460@item $A0-$A1 21461@tab Filled with $A0 21462@item $A2-$A3 21463@tab Disk ID 21464@item $A4 21465@tab Usually $A0 21466@item $A5-$A6 21467@tab DOS type, usually "2A" 21468@item $A7-$AA 21469@tab Filled with $A0 21470@item $AB-$DC 21471@tab Not used ($00's) 21472@item $DD-$FF 21473@tab Free sector count for tracks 36-70 (1 byte/track). 21474@end multitable 21475 21476The "free sector" entries for tracks 36-70 are likely included 21477here in the first BAM sector due to some memory restrictions in 21478the 1571 drive. There is only enough memory available for one 21479BAM sector, but in order to generate the "blocks free" value at 21480the end of a directory listing, the drive needs to know the 21481extra track "free sector" values. It does make working with the 21482BAM a little more difficult, though. 21483 21484These are the values that would normally be with the 4-byte BAM 21485entry, but the rest of the entry is contained on 53/0. 21486 21487Note: If the DOS version byte is set to anything other than $41 21488or $00, then we have what is called "soft write protection". Any 21489attempt to write to the disk will return the "DOS Version" error 21490code 73. The 1571 is simply telling you that it thinks the disk 21491format version is incorrect. 21492 21493The BAM entries require some explanation. Take the first entry 21494at bytes $04-$07 ($12 $FF $F9 $17). The first byte ($12) is the 21495number of free sectors on that track. Since we are looking at the 21496track 1 entry, this means it has 18 (decimal) free sectors. 21497 21498The next three bytes represent the bitmap of which sectors are 21499used/free. Since it is 3 bytes (8 bits/byte) we have 24 bits of 21500storage. Remember that at most, each track only has 21 sectors, 21501so there are a few unused bits. These entries must be viewed in 21502binary to make any sense. We will use the first entry (track 1) 21503at bytes 04-07: 21504 21505@example 21506 FF=11111111, F9=11111001, 17=00010111 21507@end example 21508 21509In order to make any sense from the binary notation, flip the 21510bits around. 21511 21512@example 21513 111111 11112222 21514 01234567 89012345 67890123 21515 -------------------------- 21516 11111111 10011111 11101000 21517 ^ ^ 21518 sector 0 sector 20 21519@end example 21520 21521Since we are on the first track, we have 21 sectors, and only 21522use up to the bit 20 position. If a bit is on (1), the sector 21523is free. Therefore, track 1 has sectors 9,10 and 19 used, all 21524the rest are free. 21525 21526In order to complete the BAM, we must check 53/0. 21527 21528@example 21529 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 21530 ----------------------------------------------- 2153100: FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF 2153210: FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 2153320: 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F FF FF 1F 2153430: FF FF 1F 00 00 00 FF FF 07 FF FF 07 FF FF 07 FF 2153540: FF 07 FF FF 07 FF FF 07 FF FF 03 FF FF 03 FF FF 2153650: 03 FF FF 03 FF FF 03 FF FF 03 FF FF 01 FF FF 01 2153760: FF FF 01 FF FF 01 FF FF 01 00 00 00 00 00 00 00 2153870: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2153980: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2154090: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21541A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21542B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21543C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21544D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21545E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21546F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21547@end example 21548 21549Each track from 36-70 has 3 byte entries, starting at 21550address $00. 21551 21552@example 21553Byte: $00-$02: $FF $FF $1F - BAM map for track 36 21554 $03-$05: $FF $FF $1F - BAM map for track 37 21555 @dots{} 21556 $33-$35: $00 $00 $00 - BAM map for track 53 21557 @dots{} 21558 $66-$68: $FF $FF $01 - BAM map for track 70 21559 $69-$FF: - Not used 21560@end example 21561 21562You can break down the entries for tracks 36-70 the same way as 21563track 1, just combine the free sector bytes from 18/0 and the BAM 21564usage from 53 to get the full 4-byte entry. 21565 21566Just like a D64, you can attach error bytes to the file, for 21567sector error information. This block is 1366 bytes long, 1 byte 21568for each of the 1366 sectors in the image. With the error bytes, 21569the file size is 351062 bytes. 21570 21571@node D81, D80, D71, File formats 21572@section The D81 disk image format 21573 21574@c FIXME: the D81 section needs to be style-checked. 21575 21576(This section was contributed by Peter Schepers and slightly edited by 21577Marco van den Heuvel.) 21578 21579Like D64 and D71, this is a byte for byte copy of a physical 1581 21580disk. It consists of 80 tracks, 40 sectors each (0 to 39) for a 21581size of 819200 bytes, or 3200 sectors. If the error byte block is 21582attached, this makes the file size 822400 bytes. 21583 21584There are three sectors on the directory track used for disk 21585internals (header and BAM), leaving 37 sectors for filename 21586entries, thus allowing for 296 files (37 * 8) to be stored at the 21587root level of the disk. 21588 21589The actual physical layout on the disk is quite different from what 21590the user sees, but this is unimportant to the scope of this section. 21591One important difference from the D64 and D71 is all the sector 21592interleaves are now 1 for both files and directory storage (rather 21593than 3 for directory and 10 for file on a D64/D71). This is due to 21594the built-in buffering in the 1581. When reading a sector, the 21595whole track will be buffered in memory, and any sectors being 21596modified will be done in memory. Once it has to be written, the 21597whole track will be written out in one step. 21598 21599The track range and offsets into the D81 files are as follows: 21600 21601@multitable @columnfractions .25 .25 .25 .25 21602@item @b{Track} 21603@tab @b{#Sect} 21604@tab @b{#SectorsIn} 21605@tab @b{D81 Offset} 21606@item 1 21607@tab 40 21608@tab 0 21609@tab $00000 21610@item 2 21611@tab 40 21612@tab 40 21613@tab $02800 21614@item 3 21615@tab 40 21616@tab 80 21617@tab $05000 21618@item 4 21619@tab 40 21620@tab 120 21621@tab $07800 21622@item 5 21623@tab 40 21624@tab 160 21625@tab $0A000 21626@item 6 21627@tab 40 21628@tab 200 21629@tab $0C800 21630@item 7 21631@tab 40 21632@tab 240 21633@tab $0F000 21634@item 8 21635@tab 40 21636@tab 280 21637@tab $11800 21638@item 9 21639@tab 40 21640@tab 320 21641@tab $14000 21642@item 10 21643@tab 40 21644@tab 360 21645@tab $16800 21646@item 11 21647@tab 40 21648@tab 400 21649@tab $19000 21650@item 12 21651@tab 40 21652@tab 440 21653@tab $1B800 21654@item 13 21655@tab 40 21656@tab 480 21657@tab $1E000 21658@item 14 21659@tab 40 21660@tab 520 21661@tab $20800 21662@item 15 21663@tab 40 21664@tab 560 21665@tab $23000 21666@item 16 21667@tab 40 21668@tab 600 21669@tab $25800 21670@item 17 21671@tab 40 21672@tab 640 21673@tab $28000 21674@item 18 21675@tab 40 21676@tab 680 21677@tab $2A800 21678@item 19 21679@tab 40 21680@tab 720 21681@tab $2D000 21682@item 20 21683@tab 40 21684@tab 760 21685@tab $2F800 21686@item 21 21687@tab 40 21688@tab 800 21689@tab $32000 21690@item 22 21691@tab 40 21692@tab 840 21693@tab $34800 21694@item 23 21695@tab 40 21696@tab 880 21697@tab $37000 21698@item 24 21699@tab 40 21700@tab 920 21701@tab $39800 21702@item 25 21703@tab 40 21704@tab 960 21705@tab $3C000 21706@item 26 21707@tab 40 21708@tab 1000 21709@tab $3E800 21710@item 27 21711@tab 40 21712@tab 1040 21713@tab $41000 21714@item 28 21715@tab 40 21716@tab 1080 21717@tab $43800 21718@item 29 21719@tab 40 21720@tab 1120 21721@tab $46000 21722@item 30 21723@tab 40 21724@tab 1160 21725@tab $48800 21726@item 31 21727@tab 40 21728@tab 1200 21729@tab $4B000 21730@item 32 21731@tab 40 21732@tab 1240 21733@tab $4D800 21734@item 33 21735@tab 40 21736@tab 1280 21737@tab $50000 21738@item 34 21739@tab 40 21740@tab 1320 21741@tab $52800 21742@item 35 21743@tab 40 21744@tab 1360 21745@tab $55000 21746@item 36 21747@tab 40 21748@tab 1400 21749@tab $57800 21750@item 37 21751@tab 40 21752@tab 1440 21753@tab $5A000 21754@item 38 21755@tab 40 21756@tab 1480 21757@tab $5C800 21758@item 39 21759@tab 40 21760@tab 1520 21761@tab $5F000 21762@item 40 21763@tab 40 21764@tab 1560 21765@tab $61800 21766@item 41 21767@tab 40 21768@tab 1600 21769@tab $64000 21770@item 42 21771@tab 40 21772@tab 1640 21773@tab $66800 21774@item 43 21775@tab 40 21776@tab 1680 21777@tab $69000 21778@item 44 21779@tab 40 21780@tab 1720 21781@tab $6B800 21782@item 45 21783@tab 40 21784@tab 1760 21785@tab $6E000 21786@item 46 21787@tab 40 21788@tab 1800 21789@tab $70800 21790@item 47 21791@tab 40 21792@tab 1840 21793@tab $73000 21794@item 48 21795@tab 40 21796@tab 1880 21797@tab $75800 21798@item 49 21799@tab 40 21800@tab 1920 21801@tab $78000 21802@item 50 21803@tab 40 21804@tab 1960 21805@tab $7A800 21806@item 51 21807@tab 40 21808@tab 2000 21809@tab $7D000 21810@item 52 21811@tab 40 21812@tab 2040 21813@tab $7F800 21814@item 53 21815@tab 40 21816@tab 2080 21817@tab $82000 21818@item 54 21819@tab 40 21820@tab 2120 21821@tab $84800 21822@item 55 21823@tab 40 21824@tab 2160 21825@tab $87000 21826@item 56 21827@tab 40 21828@tab 2200 21829@tab $89800 21830@item 57 21831@tab 40 21832@tab 2240 21833@tab $8C000 21834@item 58 21835@tab 40 21836@tab 2280 21837@tab $8E800 21838@item 59 21839@tab 40 21840@tab 2320 21841@tab $91000 21842@item 60 21843@tab 40 21844@tab 2360 21845@tab $93800 21846@item 61 21847@tab 40 21848@tab 2400 21849@tab $96000 21850@item 62 21851@tab 40 21852@tab 2440 21853@tab $98800 21854@item 63 21855@tab 40 21856@tab 2480 21857@tab $9B000 21858@item 64 21859@tab 40 21860@tab 2520 21861@tab $9D800 21862@item 65 21863@tab 40 21864@tab 2560 21865@tab $A0000 21866@item 66 21867@tab 40 21868@tab 2600 21869@tab $A2800 21870@item 67 21871@tab 40 21872@tab 2640 21873@tab $A5000 21874@item 68 21875@tab 40 21876@tab 2680 21877@tab $A7800 21878@item 69 21879@tab 40 21880@tab 2720 21881@tab $AA000 21882@item 70 21883@tab 40 21884@tab 2760 21885@tab $AC800 21886@item 71 21887@tab 40 21888@tab 2800 21889@tab $AF000 21890@item 72 21891@tab 40 21892@tab 2840 21893@tab $B1800 21894@item 73 21895@tab 40 21896@tab 2880 21897@tab $B4000 21898@item 74 21899@tab 40 21900@tab 2920 21901@tab $B6800 21902@item 75 21903@tab 40 21904@tab 2960 21905@tab $B9000 21906@item 76 21907@tab 40 21908@tab 3000 21909@tab $BB800 21910@item 77 21911@tab 40 21912@tab 3040 21913@tab $BE000 21914@item 78 21915@tab 40 21916@tab 3080 21917@tab $C0800 21918@item 79 21919@tab 40 21920@tab 3120 21921@tab $C3000 21922@item 80 21923@tab 40 21924@tab 3160 21925@tab $C5800 21926@end multitable 21927 21928The header sector is stored at 40/0, and contains the disk name, 21929ID and DOS version bytes, but the BAM is no longer contained here 21930(like the D64). 21931 21932@example 21933 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 21934 ----------------------------------------------- 2193500: 28 03 44 00 31 35 38 31 20 55 54 49 4C 49 54 59 2193610: 20 56 30 31 A0 A0 47 42 A0 33 44 A0 A0 00 00 00 2193720: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2193830: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2193940: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2194050: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2194160: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2194270: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2194380: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2194490: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21945A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21946B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21947C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21948D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21949E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21950F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 21951@end example 21952 21953@multitable @columnfractions .2 .8 21954@item @b{Bytes} 21955@tab @b{Description} 21956@item $00-$01 21957@tab Track/Sector location of the first directory sector (should be set to 40/3 but it doesn't matter, and don't trust what is there, always go to 40/3 for first directory entry) 21958@item $02 21959@tab Disk DOS version type (see note below) $44 ('D')=1581 21960@item $03 21961@tab $00 21962@item $04-$13 21963@tab 16 character Disk Name (padded with $A0) 21964@item $14-$15 21965@tab $A0 21966@item $16-$17 21967@tab Disk ID 21968@item $18 21969@tab $A0 21970@item $19 21971@tab DOS Version ("3") 21972@item $1A 21973@tab Disk version ("D") 21974@item $1B-$1C 21975@tab $A0 21976@item $1D-$FF 21977@tab Unused (usually $00) 21978@end multitable 21979 21980The following might be set if the disk is a GEOS format (this 21981info is based on the D64 layout, and might not prove to be true) 21982 21983@multitable @columnfractions .2 .8 21984@item @b{Bytes} 21985@tab @b{Description} 21986@item $AB-$AC 21987@tab Border sector (GEOS only, else set to $00) 21988@item $AD-$BC 21989@tab GEOS ID string ("geos FORMAT V1.x" GEOS only, else $00) 21990@item $BD-$FF 21991@tab Unused (usually $00) 21992@end multitable 21993 21994Note: If the DOS version byte is changed to anything other than 21995a $44 (or $00), then we have what is called "soft write 21996protection". Any attempt to write to the disk will return the 21997"DOS Version" error code 73. The drive is simply telling you 21998that it thinks the disk format version is incompatible. 21999 22000The directory track should be contained totally on track 40. 22001Sectors 3-39 contain the entries and sector 1 and 2 contain the 22002BAM (Block Availability Map). Sector 0 holds the disk name and 22003ID. The first directory sector is always 40/3, even though the 22004t/s pointer at 40/0 (first two bytes) might point somewhere 22005else. It goes linearly up the sector count, 3-4-5-6-etc. Each 22006sector holds up to eight entries. 22007 22008The first two bytes of the sector ($28/$04) indicate the location 22009of the next track/sector of the directory (40/4). If the track is 22010set to $00, then it is the last sector of the directory. It is 22011possible, however unlikely, that the directory may *not* be 22012competely on track 40. Just follow the chain anyhow. 22013 22014When the directory is done (track=$00), the sector should contain 22015an $FF, meaning the whole sector is allocated. Theactual value 22016doesn't matter as all the entries will be returned anyways. Each 22017directory sector has the following layout: 22018 22019@example 22020 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 22021 ----------------------------------------------- 2202200: 28 04 81 2B 00 53 43 52 45 45 4E 20 20 33 A0 A0 2202310: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 02 00 2202420: 00 00 81 2B 01 53 43 52 45 45 4E 20 20 34 A0 A0 2202530: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 03 00 2202640: 00 00 81 2B 02 53 43 52 45 45 4E 20 20 35 A0 A0 2202750: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00 2202860: 00 00 81 2B 08 53 43 52 45 45 4E 20 20 36 A0 A0 2202970: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 08 00 2203080: 00 00 81 2B 14 53 43 52 45 45 4E 20 20 37 A0 A0 2203190: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00 22032A0: 00 00 81 24 00 53 43 52 45 45 4E 20 20 38 A0 A0 22033B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0B 00 22034C0: 00 00 82 24 04 46 49 4C 45 34 32 39 33 36 39 30 22035D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 07 00 22036E0: 00 00 82 24 06 46 49 4C 45 32 35 37 38 38 31 35 22037F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00 22038@end example 22039 22040 22041@multitable @columnfractions .2 .8 22042@item @b{Bytes} 22043@tab @b{Description} 22044@item $00-$1F 22045@tab First directory entry 22046@item $20-$3F 22047@tab Second dir entry 22048@item $40-$5F 22049@tab Third dir entry 22050@item $60-$7F 22051@tab Fourth dir entry 22052@item $80-$9F 22053@tab Fifth dir entry 22054@item $A0-$BF 22055@tab Sixth dir entry 22056@item $C0-$DF 22057@tab Seventh dir entry 22058@item $E0-$FF 22059@tab Eighth dir entry 22060@end multitable 22061 22062This is a breakdown of a standard directory entry: 22063 22064@multitable @columnfractions .2 .8 22065@item @b{Bytes} 22066@tab @b{Description} 22067@item $00-$01 22068@tab Track/Sector location of next directory sector 22069@item $02 22070@tab File type 22071@item $03-$04 22072@tab Track/sector location of first sector of file or partition 22073@item $05-$14 22074@tab 16 character filename (in PETASCII, padded with $A0) 22075@item $15-$16 22076@tab Track/Sector location of first SUPER SIDE SECTOR block (REL file only) 22077@item $17 22078@tab REL file record length (REL file only) 22079@item $18-$1B 22080@tab Unused (except with GEOS disks) 22081@item $1C-$1D 22082@tab (Used during an SAVE or OPEN, holds the new t/s link) 22083@item $1E-$1F 22084@tab File or partition size in sectors, low/high byte order ($1E+$1F*256). The approx. file size in bytes is <= #sectors * 254 22085@end multitable 22086 22087The file type field is used as follows: 22088 22089@multitable @columnfractions .2 .8 22090@item @b{Bits} 22091@tab @b{Description} 22092@item 0-3 22093@tab The actual file type 22094@item 4 22095@tab Unused 22096@item 5 22097@tab Used only during SAVE-@@ replacement 22098@item 6 22099@tab Locked flag (Set produces ">" locked files) 22100@item 7 22101@tab Closed flag (Not set produces "*", or "splat" files) 22102@end multitable 22103 22104The actual file type can be one of the following: 22105 22106@multitable @columnfractions .2 .2 .6 22107@item @b{Binary} 22108@tab @b{Decimal} 22109@tab @b{File type} 22110@item 0000 22111@tab 0 22112@tab DEL 22113@item 0001 22114@tab 1 22115@tab SEQ 22116@item 0010 22117@tab 2 22118@tab PRG 22119@item 0011 22120@tab 3 22121@tab USR 22122@item 0100 22123@tab 4 22124@tab REL 22125@item 0101 22126@tab 5 22127@tab CBM (partition or sub-directory) 22128@end multitable 22129 22130Values 6-15 are illegal, but if used will produce very strange results. 22131 22132@c @node FIXME 22133@subsection Non-Standard & Long Directories 22134 22135Most Commdore floppy disk drives use a single dedicated directory 22136track where all filenames are stored. This limits the number of 22137files stored on a disk based on the number of sectors on the 22138directory track. There are some disk images that contain more 22139files than would normally be allowed. This requires extending the 22140directory off the default directory track by changing the last 22141directory sector pointer to a new track, allocating the new 22142sectors in the BAM, and manually placing (or moving existing) 22143file entries there. The directory of an extended disk can be read 22144and the files that reside there can be loaded without problems on 22145a real drive. However, this is still a very dangerous practice as 22146writing to the extended portion of the directory will cause 22147directory corruption in the non-extended part. Many of the floppy 22148drives core ROM routines ignore the track value that the 22149directory is on and assume the default directory track for 22150operations. 22151 22152@c @node FIXME 22153@subsection BAM layout 22154 22155The BAM is located on 40/1 (for side 0, tracks 1-40) and 40/2 22156(for side 1, tracks 41-80). Each entry takes up six bytes, one 22157for the "free sector" count and five for the allocation bitmap. 22158 22159@example 22160 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 22161 ----------------------------------------------- 2216200: 28 02 44 BB 47 42 C0 00 00 00 00 00 00 00 00 00 2216310: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 2216420: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 2216530: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 2216640: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 2216750: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 2216860: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 2216970: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 2217080: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 2217190: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 22172A0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 22173B0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 22174C0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 22175D0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 22176E0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 22177F0: FF FF FF FF 28 FF FF FF FF FF 24 F0 FF 2D FF FE 22178@end example 22179 22180@example 22181Bytes: 22182$00-$01: Track/sector of next bam sector (40/2) 22183 $02: Version # ('D') 22184 $03: One's complement of version# ($BB) 22185$04-$05: Disk ID bytes (same as 40/0 Disk ID) 22186 $06: I/O byte 22187 bit 7 set - Verify on 22188 bit 7 clear - Verify off 22189 bit 6 set - Check header CRC 22190 bit 6 clear - Don't check header CRC 22191 $07: Auto-boot-loader flag 22192$08-$0F: Reserved for future (set to $00) 22193$10-$15: BAM entry for track 1 (track 41, side 1) 22194$16-$1B: BAM entry for track 2 (track 42, side 1) 22195 @dots{} 22196$46-$4B: BAM entry for track 10 (track 50, side 1) 22197 @dots{} 22198$82-$87: BAM entry for track 20 (track 60, side 1) 22199 @dots{} 22200$BE-$C3: BAM entry for track 30 (track 70, side 1) 22201 @dots{} 22202$FA-$FF: BAM entry for track 40 (track 80, side 1) 22203@end example 22204 22205The BAM entries require some explanation, so lets look at the 22206track 40 entry at bytes $FA-FF ($24 $F0 $FF $2D $FF $FE). The 22207first byte ($24, or 36 decimal) is the number of free sectors 22208on that track. The next five bytes represent the bitmap of 22209which sectors are used/free. Since it is five bytes 22210(8 bits/byte) we have 40 bits of storage. Since this format 22211has 40 sectors/track, the whole five bytes are used. 22212 22213@example 22214 F0: .. .. .. .. .. .. .. .. .. .. 24 F0 FF 2D FF FE 22215@end example 22216 22217The last five bytes of any BAM entry must be viewed in binary 22218to make any sense. We will once again use track 40 as our 22219reference: 22220 22221@example 22222 F0=11110000, FF=11111111, 2D=00101101, FF=11111111, FE=11111110 22223@end example 22224 22225In order to make any sense from the binary notation, flip the 22226bits around. 22227 22228@example 22229 111111 11112222 22222233 33333333 22230 Sector 01234567 89012345 67890123 45678901 23456789 22231 -------------------------- -------- -------- 22232 00001111 11111111 10110100 11111111 01111111 22233@end example 22234 22235Note that if a bit is on (1), the sector is free. Therefore, 22236track 40 has sectors 0-3, 17, 20, 22, 23 and 32 used, all the 22237rest are free. 22238 22239The second BAM (for side 1) contains the entries for tracks 2224041-80. 22241 22242@example 22243 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 22244 ----------------------------------------------- 2224500: 00 FF 44 BB 47 42 C0 00 00 00 00 00 00 00 00 00 2224610: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 2224720: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 2224830: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 2224940: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 2225050: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 2225160: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 2225270: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 2225380: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 2225490: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 22255A0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 22256B0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 22257C0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 22258D0: 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 22259E0: FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 28 FF 22260F0: FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF FF FF 22261@end example 22262 22263It is laid out exactly as the side 0 BAM except for one 22264difference. The track/sector reference for the next sector 22265should be set to $00/$FF, indicating there is no next sector. 22266 22267@c @node FIXME 22268@subsection REL files 22269The REL filetype requires some extra explaining. 22270It was designed to make access to data *anywhere* on the disk 22271very fast. Take a look at this directory entry@dots{} 22272 22273@example 22274 00: 00 FF 84 27 00 41 44 44 49 54 49 4F 4E 41 4C 20 22275 10: 49 4E 46 4F A0 27 02 FE 00 00 00 00 00 00 D2 0B 22276@end example 22277 22278The third byte ($84) indicates this entry is a REL file and 22279that the three normally empty entries at offset $15, $16 and 22280$17 are now used as they are explained above. It's the 22281track/sector chain that this entry points to, called the SUPER 22282SIDE SECTOR, which is of interest here (in this case, 39/2). 22283The SUPER SIDE SECTOR is very different from the D64 format. If 22284you check the D64 entry for a REL file and do the calculations, 22285you will find that the maximum file size of the REL file is 720 22286data sectors. With the new SUPER SIDE SECTOR, you can now have 22287126 groups of these SIDE SECTORS chains, allowing for file 22288sizes up to (theoretically) 90720 sectors, or about 22.15 22289Megabytes. 22290 22291Here is a dump of the beginning of the SUPER SIDE SECTOR@dots{} 22292 22293@example 22294 00: 27 01 FE 27 01 15 09 03 0F 38 16 4A 1C 00 00 00 22295 10: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 22296 20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 22297@end example 22298 22299@example 22300Bytes: 22301$00-$01: Track/sector of first side sector in group 0 22302 $02: Always $FE 22303$03-$04: Track/sector of first side sector in group 0 (again) 22304 @dots{} 22305$FD-$FE: Track/sector of first side sector in group 125 22306 $FF: Unused (likely $00) 22307@end example 22308 22309The side sector layout is the same as the D64/1571. 22310 22311@example 22312 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 22313 ----------------------------------------------- 2231400: 12 0A 00 FE 15 09 12 0A 0F 0B 0C 0C 09 0D 06 0E 2231510: 15 07 15 08 15 0A 15 0B 15 0C 15 0D 15 0E 15 0F 2231620: 15 10 15 11 15 12 15 13 15 14 15 15 15 16 15 17 2231730: 15 18 15 19 15 1A 15 1B 15 1C 15 1D 15 1E 15 1F 2231840: 15 20 15 21 15 22 15 23 15 24 15 25 15 26 15 27 2231950: 14 00 14 01 14 02 14 03 14 04 14 05 14 06 14 07 2232060: 14 08 14 09 14 0A 14 0B 14 0C 14 0D 14 0E 14 0F 2232170: 14 10 14 11 14 12 14 13 14 14 14 15 14 16 14 17 2232280: 14 18 14 19 14 1A 14 1B 14 1C 14 1D 14 1E 14 1F 2232390: 14 20 14 21 14 22 14 23 14 24 14 25 14 26 14 27 22324A0: 13 00 13 01 13 02 13 03 13 04 13 05 13 06 13 07 22325B0: 13 08 13 09 13 0A 13 0B 13 0C 13 0D 13 0E 13 0F 22326C0: 13 10 13 11 13 12 13 13 13 14 13 15 13 16 13 17 22327D0: 13 18 13 19 13 1A 13 1B 13 1C 13 1D 13 1E 13 1F 22328E0: 13 20 13 21 13 22 13 23 13 24 13 25 13 26 13 27 22329F0: 12 00 12 01 12 02 12 03 12 04 12 05 12 06 12 07 22330@end example 22331 22332@example 22333Bytes: 22334 $00: Track location of next side-sector ($00 if last sector) 22335 $01: Sector location of next side-sector 22336 $02: Side-sector block number (first sector is $00, the next is 22337 $01, then $02, etc) 22338 $03: REL file RECORD size (from directory entry) 22339$04-$0F: Track/sector locations of the six other side-sectors. Note 22340 the first entry is this very sector we have listed here. 22341 The next is the next t/s listed at the beginning of the 22342 sector. All of this information must be correct. If one of 22343 these chains is $00/$00, then we have no more side sectors. 22344 Also, all of these (up to six) side sectors must have the 22345 same values in this range. 22346$10-$FF: T/S chains of *each* sector of the data portion. When we 22347 get a $00/$00, we are at the end of the file. 22348@end example 22349 22350@c @node FIXME 22351@subsection 1581 Partitions and Sub-directories 22352 22353At the beginning of this section it was stated that the 1581 can 22354hold 296 entries "at the root level". The 1581 also has the 22355ability to partition areas of the disk. Under the right 22356conditions these can become sub-directories, acting as a small 22357diskette, complete with its own directory and BAM. When you are 22358inside of a sub-directory, no other files except those in that 22359directory are visible, or can be affected. 22360 22361To the 1581, this file will show up as a "CBM" filetype in a 22362directory. All this does is tell the disk that a file, starting 22363at X/Y track/sector and Z sectors large exists. Doing a validate 22364will not harm these files as they have a directory entry, and 22365are fully allocated in the BAM. 22366 22367There are two main uses for partitions. One is to simply 22368allocate a section of the disk to be used for direct-access 22369reads/writes, and lock it away from being overwritten after a 22370VALIDATE. The second is as a sub-directory, basically a small 22371"disk within a disk". 22372 22373In order to use a partition as a sub-directory, it must adhere 22374to the following four rules: 22375 22376@example 22377 1. If must start on sector 0 22378 2. It's size must be in multiples of 40 sectors 22379 3. It must be a minimum of 120 sectors long (3 tracks) 22380 4. If must not start on or cross track 40, which limits the 22381 biggest directory to 1600 sectors (tracks 1-39). 22382@end example 22383 22384This is a dump of a sub-directory entry: 22385 22386@example 22387 00: 00 FF 85 29 00 50 41 52 54 49 54 49 4F 4E 20 31 22388 10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 40 06 22389@end example 22390 22391It is a partition starting on track 41/0, extends for 1600 22392sectors, and has been formatted as a sub-directory. Note that 22393when a partition is created, the area being allocated is not 22394touched in any way. If you want it set up as a sub-directory, 22395you must issue the FORMAT command to the 1581 to create the 22396central directory and BAM. Also note that from the directory 22397entry you can't tell whether it is a sub-directory or not, just 22398that it fits the sub-directory parameters. 22399 22400The BAM track for the sub-directory exists on the first track of 22401the partition, and has the same layout as the disk BAM on track 2240240. The biggest difference is the "disk name" is what what given 22403when the partition was formatted rather than what the actual 22404disk name is. Also, except for the free sectors in the partition 22405area, all other sectors in the BAM will be allocated. 22406 22407If the partition size doesn't match the above rules for a 22408sub-directory, it will simply exist as a "protected" area of the 22409disk, and can't be used as a sub-directory. Either way, it still 22410shows up as a "CBM" type in a directory listing. Below is a dump 22411of a 10-sector partition starting on track 5/1, which does not 22412qualify as a sub-directory@dots{} 22413 22414@example 22415 00: 00 00 85 05 01 53 4D 41 4C 4C 50 41 52 54 20 32 22416 10: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0A 00 22417@end example 22418 22419The master BAM shows the entry for this partition on track 5@dots{} 22420 22421@example 22422 00: 28 02 44 BB 43 44 C0 00 00 00 00 00 00 00 00 00 22423 10: 23 C1 FF FF FF FF 28 FF FF FF FF FF 28 FF FF FF 22424 20: FF FF 28 FF FF FF FF FF 1E 01 F8 FF FF FF 28 FF 22425 ^^^^^^^^^^^^^^^^^ 22426@end example 22427 22428The breakdown of the BAM shows the allocation for this track, 22429with sectors 1-10 allocated, as it should be. 22430 22431@example 22432 10000000 00011111 11111111 11111111 11111111 22433 ^ ^ ^ ^ ^ 22434 0 10 20 30 39 22435@end example 22436 22437Partitions and sub-directories share one very important trait. 22438When created, the sub-directory entry simply has the starting 22439track/sector and the size of the partition in sectors. 22440Partitions are created linearly, meaning if one starts on 30/1 22441and is of size 15 sectors, then the sector range from 1 through 2244215 on track 30 will be allocated. If a partition size crosses 22443a track boundary, the allocation will continue on the next 22444track starting on sector 0, and going up. 22445 22446The section allocated will *not* have a track/sector chain like 22447a file would, but rather is dependant on the directory entry to 22448keep it from being overwritten. You can store whatever you want 22449to in the allocated area. 22450 22451@c @node FIXME 22452@subsection AUTO-BOOT LOADER 22453 22454If byte $07 in the BAM is set, then when the drive is reset 22455(and other circumstances) it will look for a USR file called 22456"COPYRIGHT CBM 86". This file will then be loaded into the 22457drive RAM and executed. 22458 22459The format for this auto-loader file is fairly basic. It 22460starts with a two-byte load address, a size byte, program data, 22461and a checksum at the end. 22462 22463@example 22464Bytes: 22465 $00-$01: Load address, low/high format 22466 $02: Size of program (SZ) (smaller than 256 bytes) 22467$03-($03+SZ-1): Program data 22468 $03+SZ: Checksum byte 22469@end example 22470 22471@node D80, D82, D81, File formats 22472@section The D80 disk image format 22473 22474@c FIXME: the D80 section needs to be style-checked. 22475 22476(This section was contributed by Peter Schepers and slightly edited by 22477Marco van den Heuvel.) 22478 22479This is a sector-for-sector copy of an 8050 floppy disk. The 22480file size for an 8050 image is 533248 bytes. It is comprised 22481of 256-byte sectors arranged across 77 tracks, with a 22482varying number of sectors per track for a total of 2083 22483sectors. Track counting starts at 1 (not 0) and sector 22484counting starts at 0 (not 1), therefore a track with 29 22485sectors will go from 0 to 28. 22486 22487The original media (a 5.25" disk) has the tracks laid out in 22488circles, with track 1 on the very outside of the disk 22489(closest to the sides) to track 77 being on the inside of 22490the disk (closest to the inner hub ring). Commodore, in 22491their infinite wisdom, varied the number of sectors per 22492track and data densities across the disk to optimize 22493available storage, resulting in the chart below. It shows 22494the sectors/track for a D80. Since the outside diameter of a 22495circle is the largest (versus closer to the center), the 22496outside tracks have the largest amount of storage. 22497 22498@multitable @columnfractions .33 .33 .33 22499@item @b{Track Range} 22500@tab @b{Sectors/track} 22501@tab @b{# Sectors} 22502@item 1-39 22503@tab 29 22504@tab 1131 22505@item 40-53 22506@tab 27 22507@tab 378 22508@item 54-64 22509@tab 25 22510@tab 275 22511@item 65-77 22512@tab 23 22513@tab 299 22514@end multitable 22515 22516@multitable @columnfractions .25 .25 .25 .25 22517@item @b{Track} 22518@tab @b{#Sect} 22519@tab @b{#SectorsIn} 22520@tab @b{D8x Offset} 22521@item 1 22522@tab 29 22523@tab 0 22524@tab $00000 22525@item 2 22526@tab 29 22527@tab 29 22528@tab $01D00 22529@item 3 22530@tab 29 22531@tab 58 22532@tab $03A00 22533@item 4 22534@tab 29 22535@tab 87 22536@tab $05700 22537@item 5 22538@tab 29 22539@tab 116 22540@tab $07400 22541@item 6 22542@tab 29 22543@tab 145 22544@tab $09100 22545@item 7 22546@tab 29 22547@tab 174 22548@tab $0AE00 22549@item 8 22550@tab 29 22551@tab 203 22552@tab $0CB00 22553@item 9 22554@tab 29 22555@tab 232 22556@tab $0E800 22557@item 10 22558@tab 29 22559@tab 261 22560@tab $10500 22561@item 11 22562@tab 29 22563@tab 290 22564@tab $12200 22565@item 12 22566@tab 29 22567@tab 319 22568@tab $13F00 22569@item 13 22570@tab 29 22571@tab 348 22572@tab $15C00 22573@item 14 22574@tab 29 22575@tab 377 22576@tab $17900 22577@item 15 22578@tab 29 22579@tab 406 22580@tab $19600 22581@item 16 22582@tab 29 22583@tab 435 22584@tab $1B300 22585@item 17 22586@tab 29 22587@tab 464 22588@tab $1D000 22589@item 18 22590@tab 29 22591@tab 493 22592@tab $1ED00 22593@item 19 22594@tab 29 22595@tab 522 22596@tab $20A00 22597@item 20 22598@tab 29 22599@tab 551 22600@tab $22700 22601@item 21 22602@tab 29 22603@tab 580 22604@tab $24400 22605@item 22 22606@tab 29 22607@tab 609 22608@tab $26100 22609@item 23 22610@tab 29 22611@tab 638 22612@tab $27E00 22613@item 24 22614@tab 29 22615@tab 667 22616@tab $29B00 22617@item 25 22618@tab 29 22619@tab 696 22620@tab $2B800 22621@item 26 22622@tab 29 22623@tab 725 22624@tab $2D500 22625@item 27 22626@tab 29 22627@tab 754 22628@tab $2F200 22629@item 28 22630@tab 29 22631@tab 783 22632@tab $30F00 22633@item 29 22634@tab 29 22635@tab 812 22636@tab $32C00 22637@item 30 22638@tab 29 22639@tab 841 22640@tab $34900 22641@item 31 22642@tab 29 22643@tab 870 22644@tab $36600 22645@item 32 22646@tab 29 22647@tab 899 22648@tab $38300 22649@item 33 22650@tab 29 22651@tab 928 22652@tab $3A000 22653@item 34 22654@tab 29 22655@tab 957 22656@tab $3BD00 22657@item 35 22658@tab 29 22659@tab 986 22660@tab $3DA00 22661@item 36 22662@tab 29 22663@tab 1015 22664@tab $3F700 22665@item 37 22666@tab 29 22667@tab 1044 22668@tab $41400 22669@item 38 22670@tab 29 22671@tab 1073 22672@tab $43100 22673@item 39 22674@tab 29 22675@tab 1102 22676@tab $44E00 22677@item 40 22678@tab 27 22679@tab 1131 22680@tab $46B00 22681@item 41 22682@tab 27 22683@tab 1158 22684@tab $48600 22685@item 42 22686@tab 27 22687@tab 1185 22688@tab $4A100 22689@item 43 22690@tab 27 22691@tab 1212 22692@tab $4BC00 22693@item 44 22694@tab 27 22695@tab 1239 22696@tab $4D700 22697@item 45 22698@tab 27 22699@tab 1266 22700@tab $4F200 22701@item 46 22702@tab 27 22703@tab 1293 22704@tab $50D00 22705@item 47 22706@tab 27 22707@tab 1320 22708@tab $52800 22709@item 48 22710@tab 27 22711@tab 1347 22712@tab $54300 22713@item 49 22714@tab 27 22715@tab 1374 22716@tab $55E00 22717@item 50 22718@tab 27 22719@tab 1401 22720@tab $57900 22721@item 51 22722@tab 27 22723@tab 1428 22724@tab $59400 22725@item 52 22726@tab 27 22727@tab 1455 22728@tab $5AF00 22729@item 53 22730@tab 27 22731@tab 1482 22732@tab $5CA00 22733@item 54 22734@tab 25 22735@tab 1509 22736@tab $5E500 22737@item 55 22738@tab 25 22739@tab 1534 22740@tab $5FE00 22741@item 56 22742@tab 25 22743@tab 1559 22744@tab $61700 22745@item 57 22746@tab 25 22747@tab 1584 22748@tab $63000 22749@item 58 22750@tab 25 22751@tab 1609 22752@tab $64900 22753@item 59 22754@tab 25 22755@tab 1634 22756@tab $66200 22757@item 60 22758@tab 25 22759@tab 1659 22760@tab $67B00 22761@item 61 22762@tab 25 22763@tab 1684 22764@tab $69400 22765@item 62 22766@tab 25 22767@tab 1709 22768@tab $6AD00 22769@item 63 22770@tab 25 22771@tab 1734 22772@tab $6C600 22773@item 64 22774@tab 25 22775@tab 1759 22776@tab $6DF00 22777@item 65 22778@tab 23 22779@tab 1784 22780@tab $6F800 22781@item 66 22782@tab 23 22783@tab 1807 22784@tab $70F00 22785@item 67 22786@tab 23 22787@tab 1830 22788@tab $72600 22789@item 68 22790@tab 23 22791@tab 1853 22792@tab $73D00 22793@item 69 22794@tab 23 22795@tab 1876 22796@tab $75400 22797@item 70 22798@tab 23 22799@tab 1899 22800@tab $76B00 22801@item 71 22802@tab 23 22803@tab 1922 22804@tab $78200 22805@item 72 22806@tab 23 22807@tab 1945 22808@tab $79900 22809@item 73 22810@tab 23 22811@tab 1968 22812@tab $7B000 22813@item 74 22814@tab 23 22815@tab 1991 22816@tab $7C700 22817@item 75 22818@tab 23 22819@tab 2014 22820@tab $7DE00 22821@item 76 22822@tab 23 22823@tab 2037 22824@tab $7F500 22825@item 77 22826@tab 23 22827@tab 2060 22828@tab $80C00 22829@end multitable 22830 22831The BAM (Block Availability Map) is on track 38. The D80 is only 2283277 tracks and so the BAM is contained on 38/0 and 38/3. The BAM 22833interleave is 3. 22834 22835The directory is on track 39, with 39/0 contains the header 22836(DOS type, disk name, disk ID's) and sectors 1-28 contain the 22837directory entries. Both files and the directory use an 22838interleave of 1. Since the directory is only 28 sectors large 22839(29 less one for the header), and each sector can contain only 228408 entries (32 bytes per entry), the maximum number of directory 22841entries is 28 * 8 = 224. The first directory sector is always 2284239/1. It then follows a chain structure using a sector 22843interleave of 1 making the links go 39/1, 39/2, 39/3 etc. 22844 22845When reading a disk, you start with 39/0 (disk label/ID) which 22846points to 38/0 (BAM0), 38/3 (BAM1), and finally to 39/1 (first 22847dir entry sector). When writing a file to a blank disk, it will 22848start at 38/1 because 38/0 is already allocated. 22849 22850Below is a dump of the header sector 39/0: 22851 22852@example 22853 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 22854 ----------------------------------------------- 2285500: 26 00 43 00 00 00 73 61 6D 70 6C 65 20 64 38 30 2285610: A0 A0 A0 A0 A0 A0 A0 A0 65 72 A0 32 43 A0 A0 A0 2285720: A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 22858@dots{} 22859F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 22860@end example 22861 22862@multitable @columnfractions .3 .7 22863@item @b{Bytes} 22864@tab @b{Description} 22865@item $00-$01 22866@tab T/S pointer to first BAM sector (38/0) 22867@item $02 22868@tab $43 'C' is for DOS format version 22869@item $03 22870@tab Reserved 22871@item $04-$05 22872@tab Unused 22873@item $06-$16 22874@tab Disk name, padded with 0xA0 ("sample d80") 22875@item $17 22876@tab 0xA0 22877@item $18-$19 22878@tab Disk ID bytes "er" 22879@item $1A 22880@tab 0xA0 22881@item $1B-$1C 22882@tab DOS version bytes "2C" 22883@item $1D-$20 22884@tab 0xA0 22885@item $21-$FF 22886@tab Unused 22887@end multitable 22888 22889Below is a dump of the first directory sector, 39/1 22890 22891@example 22892 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 22893 ----------------------------------------------- 2289400: 27 02 82 26 01 54 45 53 54 A0 A0 A0 A0 A0 A0 A0 2289510: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 2289620: 00 00 82 26 02 54 45 53 54 32 A0 A0 A0 A0 A0 A0 2289730: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 2289840: 00 00 82 26 04 54 45 53 54 33 A0 A0 A0 A0 A0 A0 2289950: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00 2290060: 00 00 82 26 0B 54 45 53 54 34 A0 A0 A0 A0 A0 A0 2290170: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 09 00 2290280: 00 00 82 26 14 54 45 53 54 35 A0 A0 A0 A0 A0 A0 2290390: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0C 00 22904A0: 00 00 82 28 00 54 45 53 54 36 A0 A0 A0 A0 A0 A0 22905B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 22906C0: 00 00 82 28 01 54 45 53 54 37 A0 A0 A0 A0 A0 A0 22907D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 22908E0: 00 00 82 28 02 54 45 53 54 38 A0 A0 A0 A0 A0 A0 22909F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 22910@end example 22911 22912The first two bytes of the directory sector ($27/$02) indicate 22913the location of the next track/sector of the directory (39/2). 22914If the track is set to $00, then it is the last sector of the 22915directory. 22916 22917When the directory is done, the track value will be $00. The sector 22918link should contain a value of $FF, meaning the whole sector is 22919allocated, but the actual value doesn't matter. The drive will 22920return all the available entries anyways. This is a breakdown of a 22921standard directory sector: 22922 22923@multitable @columnfractions .2 .8 22924@item @b{Bytes} 22925@tab @b{Description} 22926@item $00-$1F 22927@tab First directory entry 22928@item $20-$3F 22929@tab Second dir entry 22930@item $40-$5F 22931@tab Third dir entry 22932@item $60-$7F 22933@tab Fourth dir entry 22934@item $80-$9F 22935@tab Fifth dir entry 22936@item $A0-$BF 22937@tab Sixth dir entry 22938@item $C0-$DF 22939@tab Seventh dir entry 22940@item $E0-$FF 22941@tab Eighth dir entry 22942@end multitable 22943 22944This is a breakdown of a standard directory entry: 22945 22946@multitable @columnfractions .2 .8 22947@item @b{Bytes} 22948@tab @b{Description} 22949@item $00-$01 22950@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector) 22951@item $02 22952@tab File type 22953@item $03-$04 22954@tab Track/sector location of first sector of file 22955@item $05-$14 22956@tab 16 character filename (in PETASCII, padded with $A0) 22957@item $15-$16 22958@tab Track/Sector location of first side-sector block (REL file only) 22959@item $17 22960@tab REL file record length (REL file only, max. value 254) 22961@item $18-$1D 22962@tab Unused 22963@item $1E-$1F 22964@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254 22965@end multitable 22966 22967The file type field is used as follows: 22968 22969@multitable @columnfractions .2 .8 22970@item @b{Bits} 22971@tab @b{Description} 22972@item 0-3 22973@tab The actual file type 22974@item 4 22975@tab Unused 22976@item 5 22977@tab Used only during SAVE-@@ replacement 22978@item 6 22979@tab Locked flag (Set produces ">" locked files) 22980@item 7 22981@tab Closed flag (Not set produces "*", or "splat" files) 22982@end multitable 22983 22984The actual file type can be one of the following: 22985 22986@multitable @columnfractions .2 .2 .6 22987@item @b{Binary} 22988@tab @b{Decimal} 22989@tab @b{File type} 22990@item 0000 22991@tab 0 22992@tab DEL 22993@item 0001 22994@tab 1 22995@tab SEQ 22996@item 0010 22997@tab 2 22998@tab PRG 22999@item 0011 23000@tab 3 23001@tab USR 23002@item 0100 23003@tab 4 23004@tab REL 23005@end multitable 23006 23007Values 5-15 are illegal, but if used will produce very strange results. 23008 23009@c @node FIXME 23010@subsection Non-Standard & Long Directories 23011 23012Most Commdore floppy disk drives use a single dedicated 23013directory track where all filenames are stored. This limits the 23014number of files stored on a disk based on the number of sectors 23015on the directory track. There are some disk images that contain 23016more files than would normally be allowed. This requires 23017extending the directory off the default directory track by 23018changing the last directory sector pointer to a new track, 23019allocating the new sectors in the BAM, and manually placing (or 23020moving existing) file entries there. The directory of an 23021extended disk can be read and the files that reside there can 23022be loaded without problems on a real drive. However, this is 23023still a very dangerous practice as writing to the extended 23024portion of the directory will cause directory corruption in the 23025non-extended part. Many of the floppy drives core ROM routines 23026ignore the track value that the directory is on and assume the 23027default directory track for operations. 23028 23029@c @node FIXME 23030@subsection BAM layout 23031 23032The BAM only occupies up to four sectors on track 38, so the 23033rest of the track is empty and is available for file storage. 23034Below is a dump of the first BAM block, 38/0. A D80 will only 23035contain two BAM sectors, 38/0 and 38/3. Each entry takes 5 23036bytes, 1 for the free count on that track, and 4 for the BAM 23037bits. 23038 23039@example 23040 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 23041 ----------------------------------------------- 2304200: 26 03 43 00 01 33 1D FF FF FF 1F 1D FF FF FF 1F 2304310: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D 2304420: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF 2304530: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF 2304640: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 2304750: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 2304860: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D 2304970: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF 2305080: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF 2305190: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 23052A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 23053B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1B 23054C0: F6 FF FF 1F 1B FC FF FF 1F 1B FF FF FF 07 1B FF 23055D0: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF 23056E0: FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 23057F0: 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 23058@end example 23059 23060@multitable @columnfractions .3 .7 23061@item @b{Bytes} 23062@tab @b{Description} 23063@item $00-$01 23064@tab T/S pointer to second BAM sector (38/3) 23065@item $02 23066@tab DOS version byte (0x43='C') 23067@item $03 23068@tab Reserved 23069@item $04 23070@tab Lowest track covered by this BAM (0x01=1) 23071@item $05 23072@tab Highest+1 track covered by this BAM (0x33=51) 23073@item $06-$0A 23074@tab BAM for track 1. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track. 23075@item $0B-$0F 23076@tab BAM for track 2 23077@item @dots{} 23078@tab @dots{} 23079@item $FB-$FF 23080@tab BAM for track 50 23081@end multitable 23082 23083Being bit-based, the BAM entries need some explanation. The 23084first track entry in the above BAM sector is at offset 06, 23085"1D FF FF FF 1F". The first number is how many blocks are 23086free on this track ($1D=29) and the remainder is the bit 23087representation of the usage map for the track. These 23088entries must be viewed in binary to make any sense. First 23089convert the values to binary: 23090 23091@example 23092 FF=11111111, FF=11111111, FF=11111111, 1F=00011111 23093@end example 23094 23095In order to make any sense from the binary notation, flip the 23096bits around. 23097 23098@example 23099 111111 11112222 222222 23100 01234567 89012345 67890123 456789@dots{} 23101 -------------------------- --------- 23102 11111111 11111111 11111111 11111000 23103 ^ ^ 23104 sector 0 sector 28 23105@end example 23106 23107Since we are on the first track, we have 29 sectors, and only 23108use up to the bit 28 position. If a bit is on (1), the sector 23109is free. Therefore, track 1 is clean, all sectors are free. 23110Any leftover bits that refer to sectors that don't exist, 23111like bits 29-31 in the above example, are set to allocated. 23112 23113Second BAM block 38/3. 23114 23115@example 23116 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 23117 ----------------------------------------------- 2311800: 27 01 43 00 33 4E 1B FF FF FF 07 1B FF FF FF 07 2311910: 1B FF FF FF 07 19 FF FF FF 01 19 FF FF FF 01 19 2312020: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF 2312130: FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF 2312240: FF 01 19 FF FF FF 01 19 FF FF FF 01 17 FF FF 7F 2312350: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 2312460: 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 2312570: FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF 2312680: FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 00 00 00 2312790: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23128A0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23129B0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23130C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23131D0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23132E0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23133F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23134@end example 23135 23136@multitable @columnfractions .3 .7 23137@item @b{Bytes} 23138@tab @b{Description} 23139@item $00-$01 23140@tab T/S pointer to second BAM sector (39/1) 23141@item $02 23142@tab DOS version byte (0x43='C') 23143@item $03 23144@tab Reserved 23145@item $04 23146@tab Lowest track covered by this BAM (0x33=51) 23147@item $05 23148@tab Highest+1 track covered by this BAM (0x43=78) 23149@item $06-$0A 23150@tab BAM for track 51. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track. 23151@item $0B-$0F 23152@tab BAM for track 52 23153@item @dots{} 23154@tab @dots{} 23155@item $88-$8C 23156@tab BAM for track 77 23157@item $8D-$FF 23158@tab Not used 23159@end multitable 23160 23161@node D82, D90, D80, File formats 23162@section The D82 disk image format 23163 23164@c FIXME: the D82 section needs to be style-checked. 23165 23166(This section was contributed by Peter Schepers and slightly edited by 23167Marco van den Heuvel.) 23168 23169This is a sector-for-sector copy of an 8250 floppy disk. The file 23170size for an 8250 image is 1066496 bytes. It is comprised of 23171256-byte sectors arranged across 154 tracks, with a varying 23172number of sectors per track for a total of 4166 sectors. Track 23173counting starts at 1 (not 0) and sector counting starts at 0 23174(not 1), therefore a track with 29 sectors will go from 0 to 28. 23175 23176The original media (a 5.25" disk) has the tracks laid out in 23177circles, with track 1 on the very outside of the disk (closest 23178to the sides) to track 77 being on the inside of the disk 23179(closest to the inner hub ring). Commodore, in their infinite 23180wisdom, varied the number of sectors per track and data 23181densities across the disk to optimize available storage, 23182resulting in the chart below. It shows the sectors/track for a 23183D82. Since the outside diameter of a circle is the largest 23184(versus closer to the center), the outside tracks have the 23185largest amount of storage. 23186 23187 23188@multitable @columnfractions .33 .33 .33 23189@item @b{Track Range} 23190@tab @b{Sectors/track} 23191@tab @b{# Sectors} 23192@item 1-39 23193@tab 29 23194@tab 1131 23195@item 40-53 23196@tab 27 23197@tab 378 23198@item 55-64 23199@tab 25 23200@tab 275 23201@item 65-77 23202@tab 23 23203@tab 299 23204@item 78-116 23205@tab 29 23206@tab 1131 23207@item 117-130 23208@tab 27 23209@tab 378 23210@item 131-141 23211@tab 25 23212@tab 275 23213@item 142-154 23214@tab 23 23215@tab 299 23216@end multitable 23217 23218@multitable @columnfractions .25 .25 .25 .25 23219@item @b{Track} 23220@tab @b{#Sect} 23221@tab @b{#SectorsIn} 23222@tab @b{D82 Offset} 23223@item 1 23224@tab 29 23225@tab 0 23226@tab $000000 23227@item 2 23228@tab 29 23229@tab 29 23230@tab $001D00 23231@item 3 23232@tab 29 23233@tab 58 23234@tab $003A00 23235@item 4 23236@tab 29 23237@tab 87 23238@tab $005700 23239@item 5 23240@tab 29 23241@tab 116 23242@tab $007400 23243@item 6 23244@tab 29 23245@tab 145 23246@tab $009100 23247@item 7 23248@tab 29 23249@tab 174 23250@tab $00AE00 23251@item 8 23252@tab 29 23253@tab 203 23254@tab $00CB00 23255@item 9 23256@tab 29 23257@tab 232 23258@tab $00E800 23259@item 10 23260@tab 29 23261@tab 261 23262@tab $010500 23263@item 11 23264@tab 29 23265@tab 290 23266@tab $012200 23267@item 12 23268@tab 29 23269@tab 319 23270@tab $013F00 23271@item 13 23272@tab 29 23273@tab 348 23274@tab $015C00 23275@item 14 23276@tab 29 23277@tab 377 23278@tab $017900 23279@item 15 23280@tab 29 23281@tab 406 23282@tab $019600 23283@item 16 23284@tab 29 23285@tab 435 23286@tab $01B300 23287@item 17 23288@tab 29 23289@tab 464 23290@tab $01D000 23291@item 18 23292@tab 29 23293@tab 493 23294@tab $01ED00 23295@item 19 23296@tab 29 23297@tab 522 23298@tab $020A00 23299@item 20 23300@tab 29 23301@tab 551 23302@tab $022700 23303@item 21 23304@tab 29 23305@tab 580 23306@tab $024400 23307@item 22 23308@tab 29 23309@tab 609 23310@tab $026100 23311@item 23 23312@tab 29 23313@tab 638 23314@tab $027E00 23315@item 24 23316@tab 29 23317@tab 667 23318@tab $029B00 23319@item 25 23320@tab 29 23321@tab 696 23322@tab $02B800 23323@item 26 23324@tab 29 23325@tab 725 23326@tab $02D500 23327@item 27 23328@tab 29 23329@tab 754 23330@tab $02F200 23331@item 28 23332@tab 29 23333@tab 783 23334@tab $030F00 23335@item 29 23336@tab 29 23337@tab 812 23338@tab $032C00 23339@item 30 23340@tab 29 23341@tab 841 23342@tab $034900 23343@item 31 23344@tab 29 23345@tab 870 23346@tab $036600 23347@item 32 23348@tab 29 23349@tab 899 23350@tab $038300 23351@item 33 23352@tab 29 23353@tab 928 23354@tab $03A000 23355@item 34 23356@tab 29 23357@tab 957 23358@tab $03BD00 23359@item 35 23360@tab 29 23361@tab 986 23362@tab $03DA00 23363@item 36 23364@tab 29 23365@tab 1015 23366@tab $03F700 23367@item 37 23368@tab 29 23369@tab 1044 23370@tab $041400 23371@item 38 23372@tab 29 23373@tab 1073 23374@tab $043100 23375@item 39 23376@tab 29 23377@tab 1102 23378@tab $044E00 23379@item 40 23380@tab 27 23381@tab 1131 23382@tab $046B00 23383@item 41 23384@tab 27 23385@tab 1158 23386@tab $048600 23387@item 42 23388@tab 27 23389@tab 1185 23390@tab $04A100 23391@item 43 23392@tab 27 23393@tab 1212 23394@tab $04BC00 23395@item 44 23396@tab 27 23397@tab 1239 23398@tab $04D700 23399@item 45 23400@tab 27 23401@tab 1266 23402@tab $04F200 23403@item 46 23404@tab 27 23405@tab 1293 23406@tab $050D00 23407@item 47 23408@tab 27 23409@tab 1320 23410@tab $052800 23411@item 48 23412@tab 27 23413@tab 1347 23414@tab $054300 23415@item 49 23416@tab 27 23417@tab 1374 23418@tab $055E00 23419@item 50 23420@tab 27 23421@tab 1401 23422@tab $057900 23423@item 51 23424@tab 27 23425@tab 1428 23426@tab $059400 23427@item 52 23428@tab 27 23429@tab 1455 23430@tab $05AF00 23431@item 53 23432@tab 27 23433@tab 1482 23434@tab $05CA00 23435@item 54 23436@tab 25 23437@tab 1509 23438@tab $05E500 23439@item 55 23440@tab 25 23441@tab 1534 23442@tab $05FE00 23443@item 56 23444@tab 25 23445@tab 1559 23446@tab $061700 23447@item 57 23448@tab 25 23449@tab 1584 23450@tab $063000 23451@item 58 23452@tab 25 23453@tab 1609 23454@tab $064900 23455@item 59 23456@tab 25 23457@tab 1634 23458@tab $066200 23459@item 60 23460@tab 25 23461@tab 1659 23462@tab $067B00 23463@item 61 23464@tab 25 23465@tab 1684 23466@tab $069400 23467@item 62 23468@tab 25 23469@tab 1709 23470@tab $06AD00 23471@item 63 23472@tab 25 23473@tab 1734 23474@tab $06C600 23475@item 64 23476@tab 25 23477@tab 1759 23478@tab $06DF00 23479@item 65 23480@tab 23 23481@tab 1784 23482@tab $06F800 23483@item 66 23484@tab 23 23485@tab 1807 23486@tab $070F00 23487@item 67 23488@tab 23 23489@tab 1830 23490@tab $072600 23491@item 68 23492@tab 23 23493@tab 1853 23494@tab $073D00 23495@item 69 23496@tab 23 23497@tab 1876 23498@tab $075400 23499@item 70 23500@tab 23 23501@tab 1899 23502@tab $076B00 23503@item 71 23504@tab 23 23505@tab 1922 23506@tab $078200 23507@item 72 23508@tab 23 23509@tab 1945 23510@tab $079900 23511@item 73 23512@tab 23 23513@tab 1968 23514@tab $07B000 23515@item 74 23516@tab 23 23517@tab 1991 23518@tab $07C700 23519@item 75 23520@tab 23 23521@tab 2014 23522@tab $07DE00 23523@item 76 23524@tab 23 23525@tab 2037 23526@tab $07F500 23527@item 77 23528@tab 23 23529@tab 2060 23530@tab $080C00 23531@item 78 23532@tab 29 23533@tab 2083 23534@tab $082300 23535@item 79 23536@tab 29 23537@tab 2112 23538@tab $084000 23539@item 80 23540@tab 29 23541@tab 2141 23542@tab $085D00 23543@item 81 23544@tab 29 23545@tab 2170 23546@tab $087A00 23547@item 82 23548@tab 29 23549@tab 2199 23550@tab $089700 23551@item 83 23552@tab 29 23553@tab 2228 23554@tab $08B400 23555@item 84 23556@tab 29 23557@tab 2257 23558@tab $08D100 23559@item 85 23560@tab 29 23561@tab 2286 23562@tab $08EE00 23563@item 86 23564@tab 29 23565@tab 2315 23566@tab $090600 23567@item 87 23568@tab 29 23569@tab 2344 23570@tab $092800 23571@item 88 23572@tab 29 23573@tab 2373 23574@tab $094500 23575@item 89 23576@tab 29 23577@tab 2402 23578@tab $096200 23579@item 90 23580@tab 29 23581@tab 2431 23582@tab $097F00 23583@item 91 23584@tab 29 23585@tab 2460 23586@tab $099C00 23587@item 92 23588@tab 29 23589@tab 2489 23590@tab $09B900 23591@item 93 23592@tab 29 23593@tab 2518 23594@tab $09D600 23595@item 94 23596@tab 29 23597@tab 2547 23598@tab $09F300 23599@item 95 23600@tab 29 23601@tab 2576 23602@tab $0A1000 23603@item 96 23604@tab 29 23605@tab 2605 23606@tab $0A2D00 23607@item 97 23608@tab 29 23609@tab 2634 23610@tab $0A4A00 23611@item 98 23612@tab 29 23613@tab 2663 23614@tab $0A6700 23615@item 99 23616@tab 29 23617@tab 2692 23618@tab $0A8400 23619@item 100 23620@tab 29 23621@tab 2721 23622@tab $0AA100 23623@item 101 23624@tab 29 23625@tab 2750 23626@tab $0ABE00 23627@item 102 23628@tab 29 23629@tab 2779 23630@tab $0ADB00 23631@item 103 23632@tab 29 23633@tab 2808 23634@tab $0AF800 23635@item 104 23636@tab 29 23637@tab 2837 23638@tab $0B1500 23639@item 105 23640@tab 29 23641@tab 2866 23642@tab $0B3200 23643@item 106 23644@tab 29 23645@tab 2895 23646@tab $0B4F00 23647@item 107 23648@tab 29 23649@tab 2924 23650@tab $0B6C00 23651@item 108 23652@tab 29 23653@tab 2953 23654@tab $0B8900 23655@item 109 23656@tab 29 23657@tab 2982 23658@tab $0BA600 23659@item 110 23660@tab 29 23661@tab 3011 23662@tab $0BC300 23663@item 111 23664@tab 29 23665@tab 3040 23666@tab $0BE000 23667@item 112 23668@tab 29 23669@tab 3069 23670@tab $0BFD00 23671@item 113 23672@tab 29 23673@tab 3098 23674@tab $0C1A00 23675@item 114 23676@tab 29 23677@tab 3137 23678@tab $0C3700 23679@item 115 23680@tab 29 23681@tab 3156 23682@tab $0C5400 23683@item 116 23684@tab 29 23685@tab 3185 23686@tab $0C7100 23687@item 117 23688@tab 27 23689@tab 3214 23690@tab $0C8E00 23691@item 118 23692@tab 27 23693@tab 3241 23694@tab $0CA900 23695@item 119 23696@tab 27 23697@tab 3268 23698@tab $0CC400 23699@item 120 23700@tab 27 23701@tab 3295 23702@tab $0CDF00 23703@item 121 23704@tab 27 23705@tab 3322 23706@tab $0CFA00 23707@item 122 23708@tab 27 23709@tab 3349 23710@tab $0D1500 23711@item 123 23712@tab 27 23713@tab 3376 23714@tab $0D3000 23715@item 124 23716@tab 27 23717@tab 3403 23718@tab $0D4B00 23719@item 125 23720@tab 27 23721@tab 3430 23722@tab $0D6600 23723@item 126 23724@tab 27 23725@tab 3457 23726@tab $0D8100 23727@item 127 23728@tab 27 23729@tab 3484 23730@tab $0D9C00 23731@item 128 23732@tab 27 23733@tab 3511 23734@tab $0DB700 23735@item 129 23736@tab 27 23737@tab 3538 23738@tab $0DD200 23739@item 130 23740@tab 27 23741@tab 3565 23742@tab $0DED00 23743@item 131 23744@tab 25 23745@tab 3592 23746@tab $0E0800 23747@item 132 23748@tab 25 23749@tab 3617 23750@tab $0E2100 23751@item 133 23752@tab 25 23753@tab 3642 23754@tab $0E3A00 23755@item 134 23756@tab 25 23757@tab 3667 23758@tab $0E5300 23759@item 135 23760@tab 25 23761@tab 3692 23762@tab $0E6C00 23763@item 136 23764@tab 25 23765@tab 3717 23766@tab $0E8500 23767@item 137 23768@tab 25 23769@tab 3742 23770@tab $0E9E00 23771@item 138 23772@tab 25 23773@tab 3767 23774@tab $0EB700 23775@item 139 23776@tab 25 23777@tab 3792 23778@tab $0ED000 23779@item 140 23780@tab 25 23781@tab 3817 23782@tab $0EE900 23783@item 141 23784@tab 25 23785@tab 3842 23786@tab $0F0200 23787@item 142 23788@tab 23 23789@tab 3867 23790@tab $0F1B00 23791@item 143 23792@tab 23 23793@tab 3890 23794@tab $0F3200 23795@item 144 23796@tab 23 23797@tab 3913 23798@tab $0F4900 23799@item 145 23800@tab 23 23801@tab 3936 23802@tab $0F6000 23803@item 146 23804@tab 23 23805@tab 3959 23806@tab $0F7700 23807@item 147 23808@tab 23 23809@tab 3982 23810@tab $0F8E00 23811@item 148 23812@tab 23 23813@tab 4005 23814@tab $0FA500 23815@item 149 23816@tab 23 23817@tab 4028 23818@tab $0FBC00 23819@item 150 23820@tab 23 23821@tab 4051 23822@tab $0FD300 23823@item 151 23824@tab 23 23825@tab 4074 23826@tab $0FEA00 23827@item 152 23828@tab 23 23829@tab 4097 23830@tab $100100 23831@item 153 23832@tab 23 23833@tab 4120 23834@tab $101800 23835@item 154 23836@tab 23 23837@tab 4143 23838@tab $102F00 23839@end multitable 23840 23841The BAM (Block Availability Map) is on track 38. The D82 is 154 23842tracks and so the BAM is contained on 38/0, 38/3, 38/6 and 38/9. 23843The BAM interleave is 3. 23844 23845The directory is on track 39, with 39/0 contains the header (DOS 23846type, disk name, disk ID's) and sectors 1-28 contain the 23847directory entries. Both files and the directory use an 23848interleave of 1. Since the directory is only 28 sectors large 23849(29 less one for the header), and each sector can contain only 8 23850entries (32 bytes per entry), the maximum number of directory 23851entries is 28 * 8 = 224. The first directory sector is always 2385239/1. It then follows a chain structure using a sector 23853interleave of 1 making the links go 39/1, 39/2, 39/3 etc. 23854 23855When reading a disk, you start with 39/0 (disk label/ID) which 23856points to 38/0 (BAM0), 38/3 (BAM1), 38/6 (BAM2), 38/9 (BAM3, and 23857finally to 39/1 (first dir entry sector). When writing a file to 23858a blank disk, it will start at 38/1 because 38/0 is already 23859allocated. 23860 23861Below is a dump of the header sector 39/0: 23862 23863@example 23864 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 23865 ----------------------------------------------- 2386600: 26 00 43 00 00 00 73 61 6D 70 6C 65 20 64 38 30 2386710: A0 A0 A0 A0 A0 A0 A0 A0 65 72 A0 32 43 A0 A0 A0 2386820: A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23869@dots{} 23870F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 23871@end example 23872 23873@multitable @columnfractions .3 .7 23874@item @b{Bytes} 23875@tab @b{Description} 23876@item $00-$01 23877@tab T/S pointer to first BAM sector (38/0) 23878@item $02 23879@tab $43 'C' is for DOS format version 23880@item $03 23881@tab Reserved 23882@item $04-$05 23883@tab Unused 23884@item $06-$16 23885@tab Disk name, padded with 0xA0 ("sample d82") 23886@item $17 23887@tab 0xA0 23888@item $18-$19 23889@tab Disk ID bytes "er" 23890@item $1A 23891@tab 0xA0 23892@item $1B-$1C 23893@tab DOS version bytes "2C" 23894@item $1D-$20 23895@tab 0xA0 23896@item $21-$FF 23897@tab Unused 23898@end multitable 23899 23900Below is a dump of the first directory sector, 39/1 23901 23902@example 23903 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 23904 ----------------------------------------------- 2390500: 27 02 82 26 01 54 45 53 54 A0 A0 A0 A0 A0 A0 A0 2390610: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 2390720: 00 00 82 26 02 54 45 53 54 32 A0 A0 A0 A0 A0 A0 2390830: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 2390940: 00 00 82 26 04 54 45 53 54 33 A0 A0 A0 A0 A0 A0 2391050: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 05 00 2391160: 00 00 82 26 0B 54 45 53 54 34 A0 A0 A0 A0 A0 A0 2391270: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 09 00 2391380: 00 00 82 26 14 54 45 53 54 35 A0 A0 A0 A0 A0 A0 2391490: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 0C 00 23915A0: 00 00 82 28 00 54 45 53 54 36 A0 A0 A0 A0 A0 A0 23916B0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 23917C0: 00 00 82 28 01 54 45 53 54 37 A0 A0 A0 A0 A0 A0 23918D0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 23919E0: 00 00 82 28 02 54 45 53 54 38 A0 A0 A0 A0 A0 A0 23920F0: A0 A0 A0 A0 A0 00 00 00 00 00 00 00 00 00 01 00 23921@end example 23922 23923The first two bytes of the directory sector ($27/$02) indicate 23924the location of the next track/sector of the directory (39/2). 23925If the track is set to $00, then it is the last sector of the 23926directory. 23927 23928When the directory is done, the track value will be $00. The 23929sector link should contain a value of $FF, meaning the whole 23930sector is allocated, but the actual value doesn't matter. The 23931drive will return all the available entries anyways. This is a 23932breakdown of a standard directory sector: 23933 23934@multitable @columnfractions .2 .8 23935@item @b{Bytes} 23936@tab @b{Description} 23937@item $00-$1F 23938@tab First directory entry 23939@item $20-$3F 23940@tab Second dir entry 23941@item $40-$5F 23942@tab Third dir entry 23943@item $60-$7F 23944@tab Fourth dir entry 23945@item $80-$9F 23946@tab Fifth dir entry 23947@item $A0-$BF 23948@tab Sixth dir entry 23949@item $C0-$DF 23950@tab Seventh dir entry 23951@item $E0-$FF 23952@tab Eighth dir entry 23953@end multitable 23954 23955This is a breakdown of a standard directory entry: 23956 23957@multitable @columnfractions .2 .8 23958@item @b{Bytes} 23959@tab @b{Description} 23960@item $00-$01 23961@tab Track/Sector location of next directory sector ($00 $00 if not the first entry in the sector) 23962@item $02 23963@tab File type 23964@item $03-$04 23965@tab Track/sector location of first sector of file 23966@item $05-$14 23967@tab 16 character filename (in PETASCII, padded with $A0) 23968@item $15-$16 23969@tab Track/Sector location of first side-sector block (REL file only) 23970@item $17 23971@tab REL file record length (REL file only, max. value 254) 23972@item $18-$1D 23973@tab Unused 23974@item $1E-$1F 23975@tab File size in sectors, low/high byte order ($1E+$1F*256). The approx. filesize in bytes is <= #sectors * 254 23976@end multitable 23977 23978The file type field is used as follows: 23979 23980@multitable @columnfractions .2 .8 23981@item @b{Bits} 23982@tab @b{Description} 23983@item 0-3 23984@tab The actual file type 23985@item 4 23986@tab Unused 23987@item 5 23988@tab Used only during SAVE-@@ replacement 23989@item 6 23990@tab Locked flag (Set produces ">" locked files) 23991@item 7 23992@tab Closed flag (Not set produces "*", or "splat" files) 23993@end multitable 23994 23995The actual file type can be one of the following: 23996 23997@multitable @columnfractions .2 .2 .6 23998@item @b{Binary} 23999@tab @b{Decimal} 24000@tab @b{File type} 24001@item 0000 24002@tab 0 24003@tab DEL 24004@item 0001 24005@tab 1 24006@tab SEQ 24007@item 0010 24008@tab 2 24009@tab PRG 24010@item 0011 24011@tab 3 24012@tab USR 24013@item 0100 24014@tab 4 24015@tab REL 24016@end multitable 24017 24018Values 5-15 are illegal, but if used will produce very strange results. 24019 24020@c @node FIXME 24021@subsection Non-Standard & Long Directories 24022 24023Most Commdore floppy disk drives use a single dedicated 24024directory track where all filenames are stored. This limits the 24025number of files stored on a disk based on the number of sectors 24026on the directory track. There are some disk images that contain 24027more files than would normally be allowed. This requires 24028extending the directory off the default directory track by 24029changing the last directory sector pointer to a new track, 24030allocating the new sectors in the BAM, and manually placing (or 24031moving existing) file entries there. The directory of an 24032extended disk can be read and the files that reside there can 24033be loaded without problems on a real drive. However, this is 24034still a very dangerous practice as writing to the extended 24035portion of the directory will cause directory corruption in the 24036non-extended part. Many of the floppy drives core ROM routines 24037ignore the track value that the directory is on and assume the 24038default directory track for operations. 24039 24040@c @node FIXME 24041@subsection BAM layout 24042 24043The BAM only occupies up to four sectors on track 38, so the 24044rest of the track is empty and is available for file storage. 24045Below is a dump of the first BAM block, 38/0. A D82 will 24046contain four BAM sectors, 38/0, 38/3, 38/6 and 38/9. Each 24047entry takes 5 bytes, 1 for the free count on that track, and 240484 for the BAM bits. 24049 24050@example 24051 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24052 ----------------------------------------------- 2405300: 26 03 43 00 01 33 1D FF FF FF 1F 1D FF FF FF 1F 2405410: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D 2405520: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF 2405630: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF 2405740: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 2405850: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 2405960: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D 2406070: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF 2406180: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF 2406290: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 24063A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 24064B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1B 24065C0: F6 FF FF 1F 1B FC FF FF 1F 1B FF FF FF 07 1B FF 24066D0: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF 24067E0: FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 24068F0: 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 24069@end example 24070 24071@multitable @columnfractions .3 .7 24072@item @b{Bytes} 24073@tab @b{Description} 24074@item $00-$01 24075@tab T/S pointer to second BAM sector (38/3) 24076@item $02 24077@tab DOS version byte (0x43='C') 24078@item $03 24079@tab Reserved 24080@item $04 24081@tab Lowest track covered by this BAM (0x01=1) 24082@item $05 24083@tab Highest+1 track covered by this BAM (0x33=51) 24084@item $06-$0A 24085@tab BAM for track 1. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track. 24086@item $0B-$0F 24087@tab BAM for track 2 24088@item @dots{} 24089@tab @dots{} 24090@item $FB-$FF 24091@tab BAM for track 50 24092@end multitable 24093 24094Being bit-based, the BAM entries need some explanation. The 24095first track entry in the above BAM sector is at offset 06, 24096"1D FF FF FF 1F". The first number is how many blocks are free 24097on this track ($1D=29) and the remainder is the bit 24098representation of the usage map for the track. These entries 24099must be viewed in binary to make any sense. First convert the 24100values to binary: 24101 24102@example 24103 FF=11111111, FF=11111111, FF=11111111, 1F=00011111 24104@end example 24105 24106In order to make any sense from the binary notation, flip the 24107bits around. 24108 24109@example 24110 111111 11112222 222222 24111 01234567 89012345 67890123 456789@dots{} 24112 -------------------------- --------- 24113 11111111 11111111 11111111 11111000 24114 ^ ^ 24115 sector 0 sector 28 24116@end example 24117 24118Since we are on the first track, we have 29 sectors, and only 24119use up to the bit 28 position. If a bit is on (1), the sector is 24120free. Therefore, track 1 is clean, all sectors are free. Any 24121leftover bits that refer to sectors that don't exist, like bits 2412229-31 in the above example, are set to allocated. 24123 24124Second BAM block 38/3 24125 24126@example 24127 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24128 ----------------------------------------------- 2412900: 26 06 43 00 33 65 1B FF FF FF 07 1B FF FF FF 07 2413010: 1B FF FF FF 07 19 FF FF FF 01 19 FF FF FF 01 19 2413120: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF 2413230: FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF 2413340: FF 01 19 FF FF FF 01 19 FF FF FF 01 17 FF FF 7F 2413450: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 2413560: 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 2413670: FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF 2413780: FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 1D FF FF 2413890: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 24139A0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 24140B0: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D 24141C0: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF 24142D0: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF 24143E0: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 24144F0: 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 24145@end example 24146 24147@multitable @columnfractions .3 .7 24148@item @b{Bytes} 24149@tab @b{Description} 24150@item $00-$01 24151@tab T/S pointer to third BAM sector (38/6) 24152@item $02 24153@tab DOS version byte (0x43='C') 24154@item $03 24155@tab Reserved 24156@item $04 24157@tab Lowest track covered by this BAM (0x33=51) 24158@item $05 24159@tab Highest+1 track covered by this BAM (0x65=101) 24160@item $06-$0A 24161@tab BAM for track 51. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track. 24162@item $0B-$0F 24163@tab BAM for track 52 24164@item @dots{} 24165@tab @dots{} 24166@item $FB-$FF 24167@tab BAM for track 100 24168@end multitable 24169 24170Third BAM block 38/6 24171 24172@example 24173 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24174 ----------------------------------------------- 2417500: 26 09 43 00 65 97 1D FF FF FF 1F 1D FF FF FF 1F 2417610: 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D 2417720: FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF 2417830: FF FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF 2417940: FF 1F 1D FF FF FF 1F 1D FF FF FF 1F 1D FF FF FF 2418050: 1F 1D FF FF FF 1F 1B FF FF FF 07 1B FF FF FF 07 2418160: 1B FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B 2418270: FF FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF 2418380: FF FF 07 1B FF FF FF 07 1B FF FF FF 07 1B FF FF 2418490: FF 07 1B FF FF FF 07 1B FF FF FF 07 19 FF FF FF 24185A0: 01 19 FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 24186B0: 19 FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 24187C0: FF FF FF 01 19 FF FF FF 01 19 FF FF FF 01 19 FF 24188D0: FF FF 01 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 24189E0: 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 24190F0: 00 17 FF FF 7F 00 17 FF FF 7F 00 17 FF FF 7F 00 24191@end example 24192 24193@multitable @columnfractions .3 .7 24194@item @b{Bytes} 24195@tab @b{Description} 24196@item $00-$01 24197@tab T/S pointer to fourth BAM sector (38/9) 24198@item $02 24199@tab DOS version byte (0x43='C') 24200@item $03 24201@tab Reserved 24202@item $04 24203@tab Lowest track covered by this BAM (0x65=101) 24204@item $05 24205@tab Highest+1 track covered by this BAM (0x97=151) 24206@item $06-$0A 24207@tab BAM for track 101. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track. 24208@item $0B-$0F 24209@tab BAM for track 102 24210@item @dots{} 24211@tab @dots{} 24212@item $FB-$FF 24213@tab BAM for track 150 24214@end multitable 24215 24216Fourth BAM block 38/9 24217 24218@example 24219 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24220 ----------------------------------------------- 2422100: 27 01 43 00 97 9B 17 FF FF 7F 00 17 FF FF 7F 00 2422210: 17 FF FF 7F 00 17 FF FF 7F 00 00 00 00 00 00 00 2422320: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2422430: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2422540: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24226@end example 24227 24228@multitable @columnfractions .3 .7 24229@item @b{Bytes} 24230@tab @b{Description} 24231@item $00-$01 24232@tab T/S pointer to first directory sector (39/1) 24233@item $02 24234@tab DOS version byte (0x43='C') 24235@item $03 24236@tab Reserved 24237@item $04 24238@tab Lowest track covered by this BAM (0x97=151) 24239@item $05 24240@tab Highest+1 track covered by this BAM (0x9B=155) 24241@item $06-$0A 24242@tab BAM for track 151. The first byte shows the "blocks free" for this track, the remaining 4 show the BAM for the track. 24243@item $0B-$0F 24244@tab BAM for track 152 24245@item @dots{} 24246@tab @dots{} 24247@item $15-$19 24248@tab BAM for track 154 24249@item $1A-$FF 24250@tab Not used 24251@end multitable 24252 24253@node D90, DHD, D82, File formats 24254@section The D90 disk image format 24255 24256@c FIXME: the D90 section needs to be style-checked. 24257 24258@c ROB 24259 24260The D90 image is bit-for-bit copy of the hard drives in the D9090 and 24261D9060. 24262The specifications are as follows: 24263 24264@multitable @columnfractions .4 .3 .3 24265@item @b{Specifications} 24266@tab @b{D9060} 24267@tab @b{D9090} 24268@item Hard Disk Mechanism 24269@tab Tandom TM602S 24270@tab Tandom TM603S 24271@item Cylinders 24272@tab 153 24273@tab 153 24274@item Heads 24275@tab 4 24276@tab 6 24277@item Sectors 24278@tab 32 24279@tab 32 24280@item Sector Size 24281@tab 256 24282@tab 256 24283@item Disk Interface 24284@tab ST-506 24285@tab ST-506 24286@item Unformatted Capacity 24287@tab 6.4 MB 24288@tab 9.6 MB 24289@item Formatted Capacity 24290@tab 5.01 MB 24291@tab 7.52 MB 24292@item Available Physical Sectors 24293@tab 19584 24294@tab 29376 24295@item Usable CBM Blocks 24296@tab 19441 24297@tab 29162 24298@end multitable 24299 24300Note that the unformatted capacity is simply the total raw storage and makes 24301no accommodation for the management of the information. 24302A disk needs to be low-level formatted to include sync bits, sector 24303identifiers, error checking, and correcting bits to reliably find and hold 24304data. 24305This results in an overall loss of about 22% of space, which wasn't unusual 24306for ST-506 MFM hard disks at the time. 24307Modern drives use more advanced storage techniques to reduce this overhead. 24308Earlier published information stating these drives didn't use their full 24309capacity was incorrect. 24310 24311It can be seen that the only difference between this two mechanisms was the 24312number of heads. 24313In fact the only difference between the two D9090/60 models is the hard drive 24314mechanism and the setting of the J14 configuration jumper which reflects 24315which head count to use. Jumper J13 is connected to the FDC, but in the latest 24316ROM it has no function. 24317 24318The slight difference between the physical sectors and available blocks is 24319due to the overhead of the CBM filing system (BAM, directory sectors, and 24320bad block list). 24321 24322The D9090/60 hard disk is the only Commodore drive which uses a "track 0". 24323Sector 0 of this track contains the track and sector information for the 24324header, directory, beginning of the BAM, and the beginning of the bad 24325sector list. 24326 24327Below is a dump of the configuration sector (track 0, sector 0): 24328 24329@example 24330 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24331 ----------------------------------------------- 2433200: 00 01 00 FF 4C 0A 4C 14 01 00 49 44 00 00 00 00 2433310: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24334@dots{} 24335@end example 24336 24337@multitable @columnfractions .3 .7 24338@item @b{Bytes} 24339@tab @b{Description} 24340@item $00-$01 24341@tab T/S pointer to bad blocks list 24342@item $02 24343@tab Always 0x00 24344@item $03 24345@tab Always 0xff (DOS version?) 24346@item $04-$05 24347@tab T/S pointer to first directory entry 24348@item $06-$07 24349@tab T/S pointer to header 24350@item $08-$08 24351@tab T/S pointer to first BAM sector 24352@item $0A-$0B 24353@tab Disk ID, "ID" in this example 24354@item $0C-$FF 24355@tab Always 0x00 24356@end multitable 24357 24358This sector is the same for both the D9090 and D9060 as the two hard drives 24359had the same number of cylinders. 24360The the header and directory are placed in the middle of the disk (track 76) 24361to minimize access times. 24362The on-board DOS was designed to accommodate for different cylinder 24363configurations so it was easy to install larger disks by only modifying the 24364FDC ROM. 24365The number of sectors can not exceed 32, and the number of heads can not 24366exceed 7 as they would cause unhandled numeric overflow in the DOS. 24367This variation in configuration values makes it difficult to determine them 24368based solely on the D90 file size. 24369At this point only the stock image sizes of 5,013,504, and 7,520,256 will be 24370attachable in VICE. 24371 24372Regardless of the size, access to the drive is translated from CHS 24373(cylinder, head, sector) to LBA (logical block address) in the FDC. 24374Although the drive mechanism interface is ST-506, the AM2910 bridges 24375the SASI communication from the FDC. 24376 24377Since most hard disks of that era had some type of physical defect, and no 24378defect management system, a bad blocks list is included in the DOS. 24379This list begins at track 0, sector 1 as seen from the configuration sector. 24380Below is a dump of an empty bad blocks list (track 0, sector 1): 24381 24382@example 24383 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24384 ----------------------------------------------- 2438500: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 24386@dots{} 24387@end example 24388 24389The list begins as a typical T/S linking sector, however, it is terminated 24390with a T/S of $FF/$FF unlike the typical $00/$xx normally seen in other 24391standard files. 24392The following is a more practical example: 24393 24394@example 24395 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24396 ----------------------------------------------- 2439700: 00 02 10 20 FF 02 30 40 FF 08 50 60 FF 14 70 80 24398@dots{} 24399@end example 24400 24401The actual information starts at offset $02. 24402"Bad" blocks are simply marked as "allocated" in the BAM so the DOS doesn't 24403try to put any new data in them. 24404This file is processed by setting the "working" track to 0. 24405Starting at the beginning (offset $02), a byte is read. 24406If this value is not $FF, it is interpreted as the "working" sector. 24407The "working" track/sector is marked as bad (used). 24408We continue on by reading the next byte as the "working" sector and marking 24409it until a $FF is encountered. 24410In the above example, track $0/$10 and $0/$20 would be marked as bad. 24411Once the $FF is found, the next byte is the new "working" track if it is 24412not $FF; if it is, the list is finished. 24413Otherwise we continue processing the list just as we did when the "working" 24414track was 0. 24415In the above example, track $2/$30, $2/$40, $8/$50, $8/$60, $14/70, and 24416$14/$80 would be marked as bad. 24417Note that the list in this example would continue onto track 0, sector 2 24418at offset $2 as the T/S link is set. 24419This list is processed during a "validation" as the current BAM is erased 24420and rebuilt. It also appears to be processed after a format, but it is 24421not certain if the DOS generates the list or if it was generated in 24422factory by a diagnostic system prior to the drives distribution. 24423 24424The BAM (Block Availability Map) generally begins on track 1, sector 0, 24425and continues on as necessary based on the disk configuration. 24426Below is a dump of that first BAM sector with a configuration of 32 sectors 24427per head, and 6 heads: 24428 24429@example 24430 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24431 ----------------------------------------------- 2443200: 09 00 FF FF 00 08 00 00 00 00 00 00 00 00 00 00 2443310: 1E FC FF FF FF 20 FF FF FF FF 20 FF FF FF FF 20 2443420: FF FF FF FF 20 FF FF FF FF 20 FF FF FF FF 1F FE 2443530: FF FF FF 20 FF FF FF FF 20 FF FF FF FF 20 FF FF 24436@dots{} 24437F0: FF 20 FF FF FF FF 20 FF FF FF FF 20 FF FF FF FF 24438@end example 24439 24440@multitable @columnfractions .3 .7 24441@item @b{Bytes} 24442@tab @b{Description} 24443@item $00-$01 24444@tab T/S pointer to next BAM sector ($9/$0) 24445@item $02-$03 24446@tab T/S pointer to previous BAM sector ($FF/$FF) 24447@item $04 24448@tab Lowest track covered by this BAM ($0) 24449@item $05 24450@tab Highest+1 track covered by this BAM ($8) 24451@item $06 24452@tab Possible start of bitmap data 24453@item $10-$14 (first entry based on this example) 24454@tab BAM for track 0, head 0. The first byte shows the "blocks free" for this head, the remaining 4 show the BAM for this track and head. 24455@item $24-$08 24456@tab BAM for track 0, head 1. 24457@item @dots{} 24458@tab @dots{} 24459@item $2E-$32 24460@tab BAM for track 1, head 0. 24461@item @dots{} 24462@tab @dots{} 24463@item $FB-$FF 24464@tab BAM for track 7, head 5. 24465@end multitable 24466 24467If the T/S pointer is $FF/$FF, it means the end of the BAM. 24468So in this case, there is no previous BAM sector, whereas in the last 24469BAM sector, bytes $01-$02 will be $FF/$FF indicating that there is no 24470next BAM sector. 24471 24472Bytes $4 and $5 show the range of which tracks this BAM sector applies to. 24473There are 250 bytes to hold this information. 24474The size of each bitmap entry is calculated by 24475"ceiling(sectors_per_head/8)+1"; the "1" is to include the block count. 24476This value is then multipled by the head number and divided into 250. 24477The remainder is added to 6 (the offset for the start of bitmap data). 24478For this example, the bitmap entry size would be "ceiling(32/8)+1" which is 5 24479bytes. 24480The offset is "(250%(5*6))+6" which is 16 or $10. 24481The goal of this calculation is to place the maximum number of whole tracks 24482inside each BAM. 24483In this case, "int(250/(5*6))" is 8, so we can store 8 tracks per BAM sector. 24484Therefore the lowest track is 0, and the highest is 0 + 8. 24485The next BAM sector will handle tracks 8 to 15 (16 - 1). 24486The position of the BAMs will start at track 1, and the second will be at 24487track 9 (8 + 1), the third will be at track 17 (2 * 8 + 1), and so on. 24488For this example with 153 tracks, we will need at least 20 (153 divided by 8) 24489BAM sectors. 24490BAM sectors are always placed on sector 0. 24491The header and directory will never start on sector 0, so we don't have to 24492worry if one of the BAM sectors will end up on track 76 for example. 24493 24494Being bit-based, the BAM entries need some explanation. 24495The first track (track 0) entry in the above BAM sector is at offset $10, 24496"1E FC FF FF FF". 24497The first number is how many blocks are free on this track and head ($1E=30) 24498and the remainder is the bit representation of the usage map for the track. 24499These entries must be viewed in binary to make any sense. 24500First convert the values to binary: 24501 24502@example 24503 FC=11111100, FF=11111111, FF=11111111, FF=11111111 24504@end example 24505 24506In order to make any sense from the binary notation, flip the bits around. 24507 24508@example 24509 111111 11112222 22222233 24510 01234567 89012345 67890123 45678901 24511 -------------------------- --------- 24512 00111111 11111111 11111111 11111111 24513 ^ ^ 24514 sector 0 sector 31 24515@end example 24516 24517If a bit is on (1), the sector is free. 24518We can see all but sectors 0 and 1 are free here as it holds the configuration 24519sector, and one sector for the bad block list respectively. 24520 24521At offset $24, "1F FE FF FF FF" describes the allocation at track 1, sector 0. 24522The first value is the number of free blocks ($1F=31) and the next 4 indicate 24523which sectors are used (or available); in this case sector 0 is allocated 24524as it is used by the first BAM sector. 24525 24526Below is the dump of the last BAM sector (track 152, sector 0): 24527 24528@example 24529 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24530 ----------------------------------------------- 2453100: FF FF 91 00 98 99 00 00 00 00 00 00 00 00 00 00 2453210: 1F FE FF FF FF 20 FF FF FF FF 20 FF FF FF FF 20 2453320: FF FF FF FF 20 FF FF FF FF 20 FF FF FF FF 00 00 2453430: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24535@dots{} 24536@end example 24537 24538Here we can see it only covers tracks 152 ($98) to 152 ($99-1). 24539So only 6 entries are valid, and the rest are all zeros. 24540The next T/S pointer is $FF/$FF indicating this is the last BAM sector. 24541 24542When the blocks free is calculated, only track 0 is excluded. 24543Other Commodore drives exclude the dedicated directory track. 24544 24545The directory is generally on track 76 (152 divided by 2), with sector 20 24546containing the header (disk name, disk ID's). 24547The directory entries begin at sector 10. 24548The drives interleave is 10 sectors and it appears the directory entry is 24549allocated before the header on a format. 24550Once the directory grows, the interleave becomes 3, as on most Commodore 24551drives. 24552Unlike most Commodore drives, the directory is not limited to track 76, 24553nor is file data limited to be else where. 24554Once track 76 is filled with directory entries, it will look in other tracks 24555to place more entries. 24556Filling the disk to capacity will also place data into track 76. 24557Be warned though as the directory listing can exceed the amount of memory 24558available on the Commodore machine which is "loading" the directory. 24559It is wise to use a DOS wedge which displays the directory as it is being 24560read but doesn't store it in memory. 24561 24562The D9090/60 emulation in VICE was tested to see how many one block files 24563could be created on a D9090 image. 24564The disk was filled with 25922 files which required 3241 blocks for the 24565directory entries. 24566 24567Below is a dump of the header at track 76, sector 20: 24568 24569@example 24570 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24571 ----------------------------------------------- 2457200: 4C 0A 00 00 00 00 54 45 53 54 A0 A0 A0 A0 A0 A0 2457310: A0 A0 A0 A0 A0 A0 A0 A0 49 44 A0 33 41 A0 A0 A0 2457420: A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24575@dots{} 24576F0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24577@end example 24578 24579This is very similar to the D80/D82 header in placement but without the DOS 24580version value. 24581Also note that the dos version bytes are "3A". 24582For the D90, it is believed that the $FF at offset $3 in the configuration 24583sector dictates the DOS version. 24584 24585The directory entry generally starts at track 76, sector 10. 24586It has the identical layout as all other Commodore drives. 24587There are no files specific to the D90 image other than super side 24588sectors for larger REL files. 24589 24590@node DHD, P00, D90, File formats 24591@section The DHD disk image format 24592 24593The DHD image is bit-for-bit copy of a Creative Micro Designs (CMD) 24594Hard Drive (HD). CMD designed their DOS so that it could co-exist with 24595other operating systems from other computer platforms. At the time, 24596SCSI HDs were very expensive, making this a likely scenario for some. 24597In this section, a block refers to a SCSI HD data block which is 512 24598bytes. A SCSI HD refers to the location of a blocks on the disk as 24599logical block address (LBA). A sector refers to a commodore disk 24600sector which is 256 bytes. SCSI, being a smarter disk system (compared 24601to earlier ones), translates the LBAs into physical head, sector, 24602cylinder coordinates internally thus simplifying the host's interface. 24603So, for example, a 40 MB HD of that era would have had 82332 (or 24604$1419C) LBAs. As HD technology improved, the number of sectors per 24605cylinder became variable depending on the cylinder which allowed for 24606greater capacity. The host therefore has no information about the HD 24607geometry other than the total number of LBAs. 24608Most operating systems place their partition tables or boot code near 24609the beginning of the HD. Because of this variability, CMD designed 24610their DOS to begin at any location in increments of 128 blocks. It was 24611therefore possible to configure foreign partitions on various 24612operating system so that the CMD data was ignored. The starting 24613location of the CMD whole disk partition will be referred to as X 24614blocks. 24615 24616Upon reset, the boot ROM looks for the CMD whole partition by 24617examining LBA X+2 (starting at X=0) and checking for a special 24618signature in the block. If it does not find it, X will increase by 24619128, and it will try again. It will do this until it finds the 24620signature, or until it gets a read error from the HD signaling the end 24621of disk space. The device will the switch to installation mode. 24622 24623The following is an example configuration block of a 40 MB drive: 24624 24625@example 24626X * 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 24627$200 + ----------------------------------------------- ---------------- 24628000400: 94 6C 00 0E 7D E7 00 00 00 00 00 00 00 00 00 00 24629000410: 20 20 20 20 31 2E 39 32 30 33 2F 32 32 2F 39 36 ....1.9203/22/96 24630000420: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24631000430: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24632000440: 03 02 00 7E C9 55 00 00 00 00 00 00 00 00 00 00 24633000450: 20 20 20 20 32 2E 30 30 30 33 2F 32 32 2F 39 36 ....2.0003/22/96 24634000460: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 24635... 24636000500: 00 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 24637000510: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 24638000530: FF FF FF FF FF FF FF FF 00 01 FF FF FF FF FF FF 24639000540: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 24640000570: 00 41 FF FF FF FF FF FF FF FF FF FF FF FF FF FF 24641000580: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 246420005A0: FF FF FF FF FF FF FF FF 00 9C FF FF FF FF FF FF 246430005B0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF 246440005E0: 00 0C 01 01 0C 80 01 00 00 00 00 00 00 00 00 00 246450005F0: 43 4D 44 20 48 44 20 20 8D 03 88 8E 02 88 EA 60 CMD HD.......... 24646... 24647000E00: < start of first OS, n=0, CMD DOS, see $402-$403 > 24648007E00: < start of second OS, n=1, GEOS overlay, see $442-$443 > 24649010000: < start of partition table, see $5E6-$5E7 > 24650@end example 24651 24652The first 256 bytes of the configuration block appear to be a list of 24653loadable operating systems for the drive. Each entry, "n", uses 64 24654bytes, so there can be at most 4. The first is the standard CMD DOS, 24655while the second is an overlay for GEOS. The boot ROM explicitly loads 24656the first (n=0). 24657 24658The CMD DOS supports up to 56 connected HDs: 7 devices with 8 logical 24659units (LUNs) each. For that era, most HDs only supported a single LUN 24660(0), whereas more exotic array devices would allow for multiple LUNs. 24661The relative location of the disk, "d", in the whole drive map, is 24662stored in the next 224 bytes. For example, the first disk would start 24663at location 0. The next disk following the first, would start at LBA 24664$01419C (the size of the first disk plus its starting point in the 24665map). The 24-bit values used here for the placement are adequate since 24666a fully populated CMD HD can only access 255 16 MB partitions, which 24667his just under 4 GiB. 24668 24669The last portion of the configuration block holds the device parameters 24670(device number, partition location, default partition) as well as the 24671CMD HD signature. 24672 24673@multitable @columnfractions .35 .65 24674@item @b{Bytes} 24675@tab @b{Description} 24676@item (X*$200)+($400-$4FF) 24677@tab Operating System Table 24678@item (X*$200+$400+n*$40)+$00 24679@tab Destination memory page 24680@item (X*$200+$400+n*$40)+$01 24681@tab Number of pages 24682@item (X*$200+$400+n*$40)+$02-$03 24683@tab Location of data offset from X in sectors (256 bytes); MSB format 24684@item (X*$200+$400+n*$40)+$04-$05 24685@tab Checksum of data; MSB format 24686@item (X*$200+$400+n*$40)+$06-$0F 24687@tab All 0x00 24688@item (X*$200+$400+n*$40)+$10-$17 24689@tab ASCII of version number 24690@item (X*$200+$400+n*$40)+$18-$1F 24691@tab ASCII of date 24692@item (X*$200+$400+n*$40)+$20-$3F 24693@tab All 0x00 24694@item (X*$200+$500+d*$38)+$00 24695@tab SCSI ID of HD in bits 7-4, LUN in bits 3-0; $FF means not present 24696@item (X*$200+$500+d*$38)+$38 24697@tab MSB of disk location in drive map 24698@item (X*$200+$500+d*$38)+$70 24699@tab Middle byte of disk location in drive map 24700@item (X*$200+$500+d*$38)+$A8 24701@tab LSB of disk location in drive map 24702@item (X*$200+$500)+$E0 24703@tab 0x00 (unknown) 24704@item (X*$200+$500)+$E1 24705@tab Device number (12 or 0x0C by default) 24706@item (X*$200+$500)+$E2 24707@tab 0x01 (unknown) 24708@item (X*$200+$500)+$E3 24709@tab 0x01 (unknown) 24710@item (X*$200+$500)+$E4 24711@tab Device number (12 or 0x0C by default) 24712@item (X*$200+$500)+$E5 24713@tab 0x80: 2 to the power of the SCSI ID of host (which is always 7) 24714@item (X*$200+$500)+$E6-$E7 24715@tab Location of CMD partition table offset from X in sectors (256 bytes); MSB format 24716@item (X*$200+$500)+$E8 24717@tab Default partition number 24718@item (X*$200+$500)+$E9-$EF 24719@tab All 0x00 24720@item (X*$200+$500)+$F0-$F7 24721@tab 0x43 0x4D 0x44 0x20 0x48 0x44 0x20 0x20: First half of signature 24722@item (X*$200+$500)+$F8-$FF 24723@tab 0x8D 0x03 0x88 0x8E 0x02 0x88 0xEA 0x60: Second half of signature; decodes to STA $8803, STX $8802, NOP, RTS 24724@end multitable 24725 24726The CMD partition table is a special disk image with one track and 32 24727sectors. It is very similar the standard directory structure of most 24728CBM drives. The first two bytes of the sector indicate the location of 24729the next track/sector of the partition table; it is usually in sequence. 24730If the next track is set to $00 (the next sector will be $ff), then it 24731is the last sector of the partition table. 24732 24733The standard partition table sectors: 24734 24735@multitable @columnfractions .2 .8 24736@item @b{Bytes} 24737@tab @b{Description} 24738@item $00-$1F 24739@tab First partition entry for this sector 24740@item $20-$3F 24741@tab Second partition entry for this sector 24742@item $40-$5F 24743@tab Third partition entry for this sector 24744@item $60-$7F 24745@tab Fourth partition entry for this sector 24746@item $80-$9F 24747@tab Fifth partition entry for this sector 24748@item $A0-$BF 24749@tab Sixth partition entry for this sector 24750@item $C0-$DF 24751@tab Seventh partition entry for this sector 24752@item $E0-$FF 24753@tab Eighth partition entry for this sector 24754@end multitable 24755 24756The standard partition entry: 24757 24758@multitable @columnfractions .2 .8 24759@item @b{Bytes} 24760@tab @b{Description} 24761@item $00-$01 24762@tab Track/Sector location of next partition sector ($00 $00 if not the first entry in the sector) 24763@item $02 24764@tab Partition type: 0x00=none, 0x01=native, 0x02=1541, 0x03=1571, 0x04=1581, 0x05=1581CPM, 0x06=Print Queue, 0x07=Foreign, 0xFF=System. Only partition 0 can be a system type, and type 6 isn't known to be implemented on any CMD DOS. 24765@item $03-$04 24766@tab 0x00 0x00 24767@item $05-$14 24768@tab 16 character partition name (in PETASCII, padded with $A0) 24769@item $15-$17 24770@tab Location of the partition data offset from X in sectors (256 bytes); MSB format; partition 0, the system partition always starts a 0. 24771@item $18-$1D 24772@tab All 0x00 24773@item $1E-$1F 24774@tab Size of partition (in blocks) in MSB format. Partition 0, the system partition is always 0x90 blocks, which includes blocks from X to the end of the partition table. 24775@end multitable 24776 24777When a partition is deleted, its entry is removed and all others stay 24778in their existing place. The partition data following the deleted 24779partition is moved back to fill in the gap from the deletion; 24780this can be very time consuming. So, when deleting a partition, it is 24781suggested to start with the one with the highest start LBA. 24782 24783The data at the starting LBA is simply the associated disk image of 24784the partition type. It follows the formats (D64, D71, and D81) 24785documented previously. 24786 24787@node P00, , DHD, File formats 24788@section The P00 image format 24789 24790@c FIXME: the P00 section needs to be style-checked. 24791 24792(This section was contributed by Peter Schepers and slightly edited by 24793Marco van den Heuvel.) 24794 24795These files were created for use in the PC64 emulator, written 24796by Wolfgang Lorenz. Each one has the same layout with the 24797filetype being stored in the DOS extension (i.e. Pxx is a PRG, 24798Sxx is a SEQ, Uxx is a USR and Rxx is a RELative file), and the 24799header is only 26 bytes long. 24800 24801This is a dump of a Pxx file (PRG)@dots{} 24802 24803@example 24804 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 24805 ----------------------------------------------- 248060000: 43 36 34 46 69 6C 65 00 43 52 49 53 49 53 20 4D 248070010: 4F 55 4E 54 41 49 4E 00 00 00 24808@end example 24809 24810@multitable @columnfractions .3 .7 24811@item @b{Bytes} 24812@tab @b{Description} 24813@item $00-$06 24814@tab ASCII string "C64File" 24815@item $07 24816@tab Always $00 24817@item $08-$17 24818@tab Filename in PETASCII, padded with $00 (not $A0, like a D64) 24819@item $18 24820@tab Always $00 24821@item $19 24822@tab REL file record size ($00 if not a REL file) 24823@item $1A-?? 24824@tab Program data 24825@end multitable 24826 24827The 'xx' in the extension of the file is usually 00, except when 24828we have two DOS filenames which would be the same, but the C64 24829filenames are different! If we have two C64 filenames which are 24830the same, they *cannot* co-exist in the same directory. If we 24831have two files which do convert down to be the same DOS 24832filename, the extension is incremented until an unused one is 24833found (x01, x02, x03, up to x99). We can have up to 99 different 24834C64 files with the same corresponding DOS names as that's all 24835the extension will hold (from P00 to P99). 24836 24837Each PC64 file only has one entry, there are no multi-file 24838containers allowed. This could result in a large number of 24839these files in a directory, even for only a few programs, as 24840each C64 file will result in a PC64 file entry. The best use 24841for a PC64 file is a single-file program, one which does not 24842load anything else. 24843 24844@c FIXME: the CRT section needs to be style-checked. 24845 24846@c @node FIXME 24847@section The CRT cartridge image format 24848 24849This chapter is based on CRT.txt (rev1.14) compiled by Peter Schepers, with 24850additional contributions from Per Hakan Sundell, Markus Brenner, 24851Marco Van Den Heuvel, Groepaz. 24852 24853 Cartridge files were introduced in the CCS64 emulator, written by Per 24854Hakan Sundell, and use the ".CRT" file extension. This format was created 24855to handle the various ROM cartridges that exist, such as Action Replay, the 24856Power cartridge, and the Final Cartridge. 24857 24858 Normal game cartridges can load into several different memory ranges 24859($8000-9FFF, $A000-BFFF or $E000-FFFF). Newer utility and freezer 24860cartridges were less intrusive, hiding themselves until called upon, and 24861still others used bank-switching techniques to allow much larger ROM's than 24862normal. Because of these "stealthing" and bank-switching methods, a special 24863cartridge format was necessary, to let the emulator know where the 24864cartridge should reside, the control line states to enable it and any 24865special hardware features it uses. 24866 24867@subsection Header contents 24868 24869 Here is a dump of a sample 8KiB normal cartridge, "Attack Of The Mutant 24870Camels"@dots{} 24871 24872@example 24873 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 24874 ----------------------------------------------- ---------------- 248750000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 248760010: 00 00 00 40 01 00 00 00 00 01 00 00 00 00 00 00 ...@@............ 248770020: 41 54 54 41 43 4B 20 4F 46 20 54 48 45 20 4D 55 ATTACK OF THE MU 248780030: 54 41 4E 54 20 43 41 4D 45 4C 53 00 00 00 00 00 TANT CAMELS..... 248790040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 248800050: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13 .......80....... 248810060: 4C B3 9B A9 08 85 5A 88 D0 FD C6 5A D0 F9 60 D0 L.....Z....Z..`. 24882@end example 24883 24884@example 24885 Bytes:$0000-000F - 16-byte cartridge signature "C64 CARTRIDGE" (padded 24886 with space characters) 24887 0010-0013 - File header length ($00000040, in high/low format, 24888 calculated from offset $0000). The default (also the 24889 minimum) value is $40. Some cartridges exist which 24890 show a value of $00000020 which is wrong. 24891 0014-0015 - Cartridge version (high/low, presently 01.01) 24892 0016-0017 - Cartridge hardware type ($0000, high/low) 24893 0 - Normal cartridge 24894 1 - Action Replay 24895 2 - KCS Power Cartridge 24896 3 - Final Cartridge III 24897 4 - Simons' BASIC 24898 5 - Ocean type 1* 24899 6 - Expert Cartridge 24900 7 - Fun Play, Power Play 24901 8 - Super Games 24902 9 - Atomic Power 24903 10 - Epyx Fastload 24904 11 - Westermann Learning 24905 12 - Rex Utility 24906 13 - Final Cartridge I 24907 14 - Magic Formel 24908 15 - C64 Game System, System 3 24909 16 - Warp Speed 24910 17 - Dinamic** 24911 18 - Zaxxon, Super Zaxxon (SEGA) 24912 19 - Magic Desk, Domark, HES Australia 24913 20 - Super Snapshot V5 24914 21 - Comal-80 24915 22 - Structured BASIC 24916 23 - Ross 24917 24 - Dela EP64 24918 25 - Dela EP7x8 24919 26 - Dela EP256 24920 27 - Rex EP256 24921 28 - Mikro Assembler 24922 29 - Final Cartridge Plus 24923 30 - Action Replay 4 24924 31 - Stardos 24925 32 - EasyFlash 24926 33 - EasyFlash Xbank 24927 34 - Capture 24928 35 - Action Replay 3 24929 36 - Retro Replay 24930 37 - MMC64 24931 38 - MMC Replay 24932 39 - IDE64 24933 40 - Super Snapshot V4 24934 41 - IEEE-488 24935 42 - Game Killer 24936 43 - Prophet64 24937 44 - EXOS 24938 45 - Freeze Frame 24939 46 - Freeze Machine 24940 47 - Snapshot64 24941 48 - Super Explode V5.0 24942 49 - Magic Voice 24943 50 - Action Replay 2 24944 51 - MACH 5 24945 52 - Diashow-Maker 24946 53 - Pagefox 24947 54 - Kingsoft 24948 55 - Silverrock 128K Cartridge 24949 56 - Formel 64 24950 57 - RGCD 24951 58 - RR-Net MK3 24952 59 - EasyCalc 24953 60 - GMod2 24954 61 - MAX Basic 24955 62 - GMod3 24956 63 - ZIPP-CODE 48 24957 64 - Blackbox V8 24958 65 - Blackbox V3 24959 66 - Blackbox V4 24960 67 - REX RAM-Floppy 24961 68 - BIS-Plus 24962 69 - SD-BOX 24963 70 - MultiMAX 24964 71 - Blackbox V9 24965 72 - Lt. Kernal Host Adaptor 24966 73 - RAMLink 24967 74 - H.E.R.O. 24968 0018 - Cartridge port EXROM line status 24969 0 - active (lo) 24970 1 - inactive (hi) 24971 0019 - Cartridge port GAME line status 24972 0 - active (lo) 24973 1 - inactive (hi) 24974 001A - Cartridge Hardware Revision/Subtype (usually 0) 24975 001B-001F - Reserved for future use 24976 0020-003F - 32-byte cartridge name "CCSMON" (uppercase, padded 24977 with null characters) 24978 0040-xxxx - Cartridge contents (called CHIP PACKETS, as there can 24979 be more than one per CRT file). See below for a 24980 breakdown of the CHIP format. 24981@end example 24982 24983 (*Note: Ocean type 1 includes Navy Seals, Robocop 2 & 3, Shadow of the 24984 Beast, Toki, Terminator 2 and more) 24985 24986 (**Note: Dinamic includes Narco Police and more) 24987 24988@c @node FIXME 24989@subsection CHIP Contents 24990 24991 24992 The following is the contents of the CHIP packet, from position $0040 on 24993in the CRT file. Note I have re-adjusted the starting address to be $0000, 24994since we are now looking at a file contained in the .CRT file, and all size 24995references are from where it starts. 24996 24997@example 24998 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 24999 ----------------------------------------------- ---------------- 250000000: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 250010010: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13 .......80....... 250020020: 4C B3 9B A9 08 85 5A 88 D0 FD C6 5A D0 F9 60 D0 L.....Z....Z..`. 250030030: F2 60 A9 04 85 49 A9 00 85 48 A2 00 A5 48 9D 40 .`...I...H...H.@@ 250040040: 03 A5 49 9D 60 03 A5 48 18 69 28 85 48 A5 49 69 ..I.`..H.i(.H.Ii 250050050: 00 85 49 E8 E0 18 D0 E4 60 A6 03 A4 02 BD 40 03 ..I.....`.....@@. 25006@end example 25007 25008@example 25009 Bytes:$0000-0003 - Contained ROM signature "CHIP" (note there can be more 25010 than one image in a .CRT file) 25011 0004-0007 - Total packet length ($00002010, ROM image size and 25012 header combined) (high/low format) 25013 0008-0009 - Chip type 25014 0 - ROM 25015 1 - RAM, no ROM data 25016 2 - Flash ROM 25017 000A-000B - Bank number ($0000 - normal cartridge) 25018 000C-000D - Starting load address (high/low format) 25019 000E-000F - ROM image size in bytes (high/low format, typically 25020 $2000 or $4000) 25021 0010-xxxx - ROM data 25022@end example 25023 25024 The following is a chart taken from the "Commodore Programmers Reference 25025Guide". It details the state of various areas of memory depending on the 25026state of the control lines. 25027 25028 25029Legend: 25030L - ROML (low) 25031H - ROMH (high) 25032G - GAME 25033E - EXROM 25034 25035@example 25036Addr LHGE LHGE LHGE LHGE LHGE LHGE LHGE LHGE LHGE 25037Range 25038 1111 101X 1000 011X 001X 1110 0100 1100 XX01 25039 default 00X0 Ultimax 25040------------------------------------------------------------------------- 25041E000-FFFF Kernal RAM RAM Kernal RAM Kernal Kernal Kernal ROMH(*) 25042D000-DFFF IO/CHR IO/CHR IO/RAM IO/CHR RAM IO/CHR IO/CHR IO/CHR I/O 25043C000-CFFF RAM RAM RAM RAM RAM RAM RAM RAM - 25044A000-BFFF BASIC RAM RAM RAM RAM BASIC ROMH ROMH - 250458000-9FFF RAM RAM RAM RAM RAM ROML RAM ROML ROML(*) 250464000-7FFF RAM RAM RAM RAM RAM RAM RAM RAM - 250471000-3FFF RAM RAM RAM RAM RAM RAM RAM RAM - 250480000-0FFF RAM RAM RAM RAM RAM RAM RAM RAM RAM 25049@end example 25050 25051(*) Internal memory does not respond to write accesses in these areas 25052 25053 25054 From the above chart, the following table can be built. It shows standard 25055cartridges, either 8KiB or 16KiB in size, and the memory ranges they load into. 25056 25057@example 25058Type Size Game EXRom Low Bank High Bank 25059 in K Line Line (ROML) (ROMH) 25060------------------------------------------------- 25061Normal 8KiB hi lo $8000 ---- 25062Normal 16KiB lo lo $8000 $A000 25063Ultimax 8KiB lo hi $E000 ---- 25064@end example 25065 25066 The ROMH and ROML lines are CPU-controlled status lines, used to bank 25067in/out RAM, ROM or I/O, depending on what is needed at the time. 25068 25069 Ultimax cartridges typically are situated in the $E000-FFFF (8KiB) ROM 25070address range. There are some cartridges which only use 4KiB of the 8KiB 25071allocation. If the cartridge is 16KiB in size, then it will reside in both 25072$8000-9FFF and $E000-FFFF. 25073 25074@c @node FIXME 25075@subsection Cartridge Specifics 25076 25077@c @node FIXME 25078@subsubsection 0 - Normal cartridge 25079 25080@multitable @columnfractions .3 .7 25081@item Size 25082@tab 8KiB 25083@item EXROM 25084@tab active (lo) (0) 25085@item GAME 25086@tab inactive (hi) (1) 25087@item Load address 25088@tab $8000-9FFF 25089@end multitable 25090 25091@example 25092 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25093 ----------------------------------------------- ---------------- 250940000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 250950010: 00 00 00 40 01 00 00 00 00 01 00 00 00 00 00 00 ...@@............ 250960020: 41 54 54 41 43 4B 20 4F 46 20 54 48 45 20 4D 55 ATTACK OF THE MU 250970030: 54 41 4E 54 20 43 41 4D 45 4C 53 00 00 00 00 00 TANT CAMELS..... 250980040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 250990050: D3 9B BC FE C3 C2 CD 38 30 EA EA EA A9 01 85 13 .......80....... 25100@end example 25101 25102 The second sample below is a dump of "Music Machine", a 4KiB ULTIMAX 25103 mode cartridge. It is still identified as a "standard cartridge" 25104 according to the ID. 25105 25106 Normal cartridge 25107 25108@multitable @columnfractions .3 .7 25109@item Size 25110@tab 4KiB (ULTIMAX mode) 25111@item EXROM 25112@tab inactive (hi) (1) 25113@item GAME 25114@tab active (lo) (0) 25115@item Load address 25116@tab $F000-F7FF 25117@end multitable 25118 25119@example 25120 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25121 ----------------------------------------------- ---------------- 251220000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 251230010: 00 00 00 40 01 00 00 00 01 00 00 00 00 00 00 00 ...@@............ 251240020: 4D 55 53 49 43 20 4D 41 43 48 49 4E 45 00 00 00 MUSIC MACHINE... 251250030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 251260040: 43 48 49 50 00 00 10 10 00 00 00 00 F0 00 10 00 CHIP............ 251270050: 3C 66 C3 C3 66 3C FF FF 18 3C 66 7E 66 66 66 00 <f..f<...<f~fff. 25128@end example 25129 25130 25131 The third sample is a dump of "Adventure Creator", a 16KiB standard 25132 cartridge. 25133 25134 Normal cartridge 25135 25136@multitable @columnfractions .3 .7 25137@item Size 25138@tab 16KiB 25139@item EXROM 25140@tab active (lo) (0) 25141@item GAME 25142@tab active (lo) (0) 25143@item Load address 25144@tab $8000-BFFF 25145@end multitable 25146 25147@example 25148 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25149 ----------------------------------------------- ---------------- 251500000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 251510010: 00 00 00 40 01 00 00 00 00 00 00 00 00 00 00 00 ...@@............ 251520020: 41 64 76 65 6E 74 75 72 65 20 43 72 65 61 74 6F Adventure Creato 251530030: 72 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 r............... 251540040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 251550050: 09 80 81 EA C3 C2 CD 38 30 A2 00 78 D8 8E 11 D0 .......80..x.... 25156@end example 25157 25158 25159@c @node FIXME 25160@subsubsection 1 - Action Replay 25161 25162@multitable @columnfractions .3 .7 25163@item Size 25164@tab 32KiB (4 banks of 8KiB each) 25165@item EXROM 25166@tab active (lo) (0) 25167@item GAME 25168@tab inactive (hi) (1) 25169@item Load address 25170@tab $8000-9FFF (all modules) 25171@end multitable 25172 25173@example 25174 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25175 ----------------------------------------------- ---------------- 251760000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 251770010: 00 00 00 40 01 00 00 01 00 01 00 00 00 00 00 00 ...@@............ 251780020: 41 63 74 69 6F 6E 20 52 65 70 6C 61 79 20 56 00 Action Replay V. 251790030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 251800040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 251810050: 09 80 0C 80 C3 C2 CD 38 30 4C 60 80 4C 63 80 4C .......80L`.Lc.L 25182@end example 25183 25184 This cart has 32KiB of ROM, and 8KiB of RAM. The bank switching is done 25185 by writing to the I/O-1 range as follows: 25186 25187@example 25188 bit meaning 25189 --- ------- 25190 7 extra ROM bank selector (A15) (unused) 25191 6 1 = resets FREEZE-mode (turns back to normal mode) 25192 5 1 = enable RAM at ROML ($8000-$9FFF) & 25193 I/O-2 ($DF00-$DFFF = $9F00-$9FFF) 25194 4 ROM bank selector high (A14) 25195 3 ROM bank selector low (A13) 25196 2 1 = disable cartridge (turn off $DE00) 25197 1 1 = /EXROM high 25198 0 1 = /GAME low 25199@end example 25200 25201 Additionally the RAM or ROM can be available through a window in the 25202 I/O-2 range. 25203 25204 25205@c @node FIXME 25206@subsubsection 2 - KCS Power Cartridge 25207 25208@multitable @columnfractions .3 .7 25209@item Size 25210@tab 16KiB (2 banks of 8KiB each) 25211@item EXROM 25212@tab active (lo) (0) 25213@item GAME 25214@tab active (lo) (0) 25215@item Load address 25216@tab module #1 - $8000-9FFF 25217 module #2 - $A000-BFFF 25218@end multitable 25219 25220@example 25221 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25222 ----------------------------------------------- ---------------- 252230000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 252240010: 00 00 00 20 01 00 00 02 00 00 00 00 00 00 00 00 ... ............ 252250020: 4B 43 53 20 50 6F 77 65 72 20 43 61 72 74 72 69 KCS Power Cartri 252260030: 64 67 65 00 00 00 00 00 00 00 00 00 00 00 00 00 dge............. 252270040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 252280050: 09 80 5E FE C3 C2 CD 38 30 78 D8 A2 FF 9A A9 27 ..^....80x.....' 25229@dots{} 252302050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00 CHIP.. ....... . 252312060: 97 E3 16 A1 FF FF FF 20 13 A0 A5 01 09 01 85 01 ....... ........ 25232@end example 25233 25234 25235@c @node FIXME 25236@subsubsection 3 - Final Cartridge III 25237 25238@multitable @columnfractions .3 .7 25239@item Size 25240@tab 64KiB (4 banks of 16KiB each) 25241@item EXROM 25242@tab inactive (hi) (1) 25243@item GAME 25244@tab inactive (hi) (1) 25245@item Load address 25246@tab $8000-BFFF (all modules) 25247@end multitable 25248 25249@example 25250 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25251 ----------------------------------------------- ---------------- 252520000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 252530010: 00 00 00 40 01 00 00 03 00 00 00 00 00 00 00 00 ...@@............ 252540020: 46 69 6E 61 6C 20 43 61 72 74 72 69 64 67 65 20 Final Cartridge 252550030: 49 49 49 20 31 39 38 37 00 00 00 00 00 00 00 00 III 1987........ 252560040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 252570050: 09 80 5E FE C3 C2 CD 38 30 4C 4C 80 4C 55 95 4C ..^....80LL.LU.L 25258@dots{} 252594050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00 CHIP..@@.......@@. 252604060: 01 02 00 81 5D 81 61 81 99 81 D8 81 0B 82 33 82 ....].a.......3. 25261@dots{} 252628060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00 CHIP..@@.......@@. 252638070: 20 43 80 20 52 80 A9 4E 20 05 DE 20 FD BF AD 39 C. R..N .. ...9 25264@dots{} 25265C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00 CHIP..@@.......@@. 25266C080: A2 06 BD DD 85 95 05 CA 10 F8 AE A0 02 E8 EC A2 ................ 25267@end example 25268 25269 A total of 64 KiB of ROM memory is organized into four $4000 banks 25270 located at $8000-$BFFF. 25271 25272 The banks are arranged in the following way: 25273 25274@example 25275 Bank 0: BASIC, Monitor, Disk-Turbo 25276 Bank 1: Notepad, BASIC (Menu Bar) 25277 Bank 2: Desktop, Freezer/Print 25278 Bank 3: Freezer, Compression 25279@end example 25280 25281 The cartridges uses the entire I/O-1 and I/O-2 range. Bank switching is 25282 done by writing the bank number plus $40 into memory location $DFFF. 25283 For instance, to select bank 2, $DFFF is set to $42. 25284 25285 The CRT file contains four CHIP blocks, each block with a start address 25286 of $8000, length $4000 and the bank number in the bank field. In the 25287 cartridge header, both EXROM ($18) and GAME ($19) are set to 1 to 25288 enable the 16 KiB ROM configuration. 25289 25290 The registers are arranged in the following way: 25291 25292 One register at $DFFF: 25293 25294@example 25295 bit meaning 25296 --- ------- 25297 7 Hide this register (1 = hidden) 25298 6 NMI line (0 = low = active) *1) 25299 5 GAME line (0 = low = active) *2) 25300 4 EXROM line (0 = low = active) 25301 2-3 unassigned (usually set to 0) 25302 0-1 number of bank to show at $8000 25303@end example 25304 25305 1) if either the freezer button is pressed, or bit 6 is 0, then an NMI 25306 is generated 25307 25308 2) if the freezer button is pressed, GAME is also forced low 25309 25310 The rest of I/O-1/I/O-2 contain a mirror of the last 2 pages of the 25311 currently selected ROM bank (also at $dfff, contrary to what some other 25312 documents say) 25313 25314 25315@c @node FIXME 25316@subsubsection 4 - Simons' Basic 25317 25318@multitable @columnfractions .3 .7 25319@item Size 25320@tab 16KiB (2 banks of 8KiB each) 25321@item EXROM 25322@tab active (lo) (0) 25323@item GAME 25324@tab inactive (hi) (1) 25325@item Load address 25326@tab module #1 - $8000-9FFF 25327 module #2 - $A000-BFFF 25328@end multitable 25329 25330@example 25331 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25332 ----------------------------------------------- ---------------- 253330000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 253340010: 00 00 00 40 01 00 00 04 00 00 00 00 00 00 00 00 ...@@............ 253350020: 53 69 6D 6F 6E 27 73 20 42 61 73 69 63 00 00 00 Simon's Basic... 253360030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 253370040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 253380050: 52 81 52 81 C3 C2 CD 38 30 41 4C 52 81 20 2C 81 R.R....80ALR. ,. 25339@dots{} 253402050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00 CHIP.. ....... . 253412060: 20 A4 A6 99 9E CB A0 05 A5 A8 91 20 A4 A6 99 A2 .......... .... 25342@end example 25343 25344 Simons' BASIC permanently uses 16 KiB ($4000) bytes of cartridge memory 25345 from $8000-$BFFF. However, through some custom bank-switching logic the 25346 upper area ($A000-$BFFF) may be disabled so Simons' BASIC may use it as 25347 additional RAM. Writing a value of $01 to address location $DE00 banks 25348 in ROM, $00 disables ROM and enables RAM. 25349 25350 The CRT file contains two CHIP blocks of length $2000 each, the first 25351 block having a start address of $8000, the second block $A000. In the 25352 cartridge header, EXROM ($18) is set to 0, GAME ($19) is set to 1 to 25353 indicate the RESET/power-up configuration of 8 KiB ROM. 25354 25355 25356@c @node FIXME 25357@subsubsection 5 - Ocean type 1 25358 25359@multitable @columnfractions .3 .7 25360@item Size 25361@tab 32KiB, 128KiB, 256KiB or 512KiB sizes (4, 16, 32 or 64 banks of 8KiB) 25362@item EXROM 25363@tab active (lo) (0) 25364@item GAME 25365@tab active (lo) (0) 25366@item Load address 25367@tab Banks 00-15 - $8000-9FFF 25368 Banks 16-31 - $A000-BFFF (except Terminator 2) 25369@end multitable 25370 25371@example 25372 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25373 ----------------------------------------------- ---------------- 2537400000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 2537500010: 00 00 00 40 01 00 00 05 00 00 00 00 00 00 00 00 ...@@............ 2537600020: 53 48 41 44 4F 57 20 4F 46 20 54 48 45 20 42 45 SHADOW OF THE BE 2537700030: 41 53 54 00 00 00 00 00 00 00 00 00 00 00 00 00 AST............. 2537800040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 2537900050: 09 80 83 81 C3 C2 CD 38 30 4C 83 81 4C 76 82 80 .......80L..Lv.. 25380 @dots{} 2538102050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 2538202060: 59 6D 00 56 AD 00 55 AE F0 00 01 A0 FE 00 01 F8 Ym.V..U......... 25383 @dots{} 2538420140: 43 48 49 50 00 00 20 10 00 00 00 10 A0 00 20 00 CHIP.. ....... . 2538520150: 0A 9A 55 FF 9B 69 57 FE AA 65 96 FE 65 0F D6 D9 ..U..iW..e..e... 25386@end example 25387 25388 Here is a list of the known OCEAN cartridges: 25389 25390@example 25391 Batman The Movie (128 KiB) 25392 Battle Command (128 KiB) 25393 Double Dragon (128 KiB) 25394 Navy Seals (128 KiB) 25395 Pang (128 KiB) 25396 Robocop 3 (128 KiB) 25397 Space Gun (128 KiB) 25398 Toki (128 KiB) 25399 Chase H.Q. II (256 KiB) 25400 Robocop 2 (256 KiB) 25401 Shadow of the Beast (256 KiB) 25402 Terminator 2 (512 KiB) 25403@end example 25404 25405 The 32KiB type of cart has 4 banks of 8KiB ($2000), banked in at 25406 $8000-$9FFF. 25407 25408 The 128KiB type of cart has 16 banks of 8KiB ($2000), banked in at 25409 $8000-$9FFF. 25410 25411 The 256KiB type of cart has 32 banks of 8KiB ($2000), 16 banked in at 25412 $8000-$9FFF, and 16 banked in at $A000-$BFFF. 25413 25414 The 512KiB type of cart has 64 banks of 8KiB ($2000), banked in at 25415 $8000-$9FFF. 25416 25417 Bank switching is done by writing to $DE00. The lower six bits give the 25418 bank number (ranging from 0-63). Bit 7 in this selection word is always 25419 set. 25420 25421 25422@c @node FIXME 25423@subsubsection 6 - Expert Cartridge 25424 25425@multitable @columnfractions .3 .7 25426@item Size 25427@tab 8KiB 25428@item EXROM 25429@tab inactive (hi) (1) 25430@item GAME 25431@tab active (lo) (0) 25432@item Load address 25433@tab $8000-9FFF 25434@end multitable 25435 25436@example 25437 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25438 ----------------------------------------------- ---------------- 254390000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 254400010: 00 00 00 40 01 00 00 06 01 00 00 00 00 00 00 00 ...@@............ 254410020: 45 78 70 65 72 74 20 43 61 72 74 72 69 64 67 65 Expert Cartridge 254420030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 254430040: 43 48 49 50 00 00 40 10 00 02 00 00 80 00 20 00 CHIP..@@....... . 254440050: 00 00 00 0A F3 00 00 00 00 00 00 00 00 00 00 00 ................ 25445@end example 25446 25447 25448@c @node FIXME 25449@subsubsection 7 - Fun Play, Power Play 25450 25451@multitable @columnfractions .3 .7 25452@item Size 25453@tab 128KiB (16 banks of 8KiB modules) 25454@item EXROM 25455@tab active (lo) (0) 25456@item GAME 25457@tab inactive (hi) (1) 25458@item Load address 25459@tab $8000-9FFF (all modules) 25460@end multitable 25461 25462@example 25463 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25464 ----------------------------------------------- ---------------- 2546500000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 2546600010: 00 00 00 40 01 00 00 07 00 01 00 00 00 00 00 00 ...@@............ 2546700020: 46 55 4E 20 50 4C 41 59 00 00 00 00 00 00 00 00 FUN PLAY........ 2546800030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 2546900040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 2547000050: 1E 80 86 EA C3 C2 CD 38 30 1B 00 81 0D 08 80 00 .......80....... 25471 @dots{} 2547202050: 43 48 49 50 00 00 20 10 00 00 00 08 80 00 20 00 CHIP.. ....... . 2547302060: 78 A2 F0 86 01 BD 1D 08 9D F8 00 CA D0 F7 4C 00 x.............L. 25474 @dots{} 2547504060: 43 48 49 50 00 00 20 10 00 00 00 10 80 00 20 00 CHIP.. ....... . 2547604070: 38 E5 68 85 03 B0 11 27 03 12 C0 18 69 27 42 90 8.h....'....i'B. 25477 @dots{} 2547806070: 43 48 49 50 00 00 20 10 00 00 00 18 80 00 20 00 CHIP.. ....... . 2547906080: 44 D0 5E 06 02 C0 44 11 40 04 11 44 01 5F 1C 73 D.^...D.@@..D._.s 25480 @dots{} 254811E130: 43 48 49 50 00 00 20 10 00 00 00 39 80 00 20 00 CHIP.. ....9.. . 254821E140: 85 EB 41 EA 9E 08 03 00 C0 06 18 01 00 C0 08 03 ..A............. 25483@end example 25484 25485 The FUN PLAY Cartridge uses $DE00 for bank selection, and uses 8KiB 25486 banks ($2000) at $8000-$9FFF. There are 16 banks of ROM memory and are 25487 referenced by the following values: 25488 25489@example 25490 $00 -> Bank 0 25491 $08 -> Bank 1 25492 $10 -> Bank 2 25493 $18 -> Bank 3 25494 $20 -> Bank 4 25495 $28 -> Bank 5 25496 $30 -> Bank 6 25497 $38 -> Bank 7 25498 $01 -> Bank 8 25499 $09 -> Bank 9 25500 $11 -> Bank 10 25501 $19 -> Bank 11 25502 $21 -> Bank 12 25503 $29 -> Bank 13 25504 $31 -> Bank 14 25505 $39 -> Bank 15 25506@end example 25507 25508 The bank field in the chip headers is set according to the value 25509 written to $DE00. The following bits are used for bank decoding in 25510 $DE00 (0 being the LSB, 3 being the MSB). 25511 25512@example 25513 Bit# 76543210 25514 xx210xx3 25515@end example 25516 25517 After copying memory from the ROM banks, the selection program writes 25518 a value of $86 to $DE00. This seems either to reset or disable the 25519 cartridge ROM. 25520 25521 25522@c @node FIXME 25523@subsubsection 8 - Super Games 25524 25525@multitable @columnfractions .3 .7 25526@item Size 25527@tab 64KiB (4 banks of 16KiB each) 25528@item EXROM 25529@tab active (lo) (0) 25530@item GAME 25531@tab active (lo) (0) 25532@item Startup mode 25533@tab 16KiB game 25534@item Load address 25535@tab $8000-BFFF (all modules) 25536@end multitable 25537 25538@example 25539 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25540 ----------------------------------------------- ---------------- 255410000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 255420010: 00 00 00 40 01 00 00 08 00 00 00 00 00 00 00 00 ...@@............ 255430020: 53 55 50 45 52 20 47 41 4D 45 53 00 00 00 00 00 SUPER GAMES..... 255440030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 255450040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 255460050: 0A 80 0A 80 C3 C2 CD 38 30 00 A9 80 A0 00 85 FB .......80....... 25547@dots{} 255484050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00 CHIP..@@.......@@. 255494060: 27 80 A8 80 C3 C2 CD 38 30 00 40 C0 40 C0 40 C0 '......80.@@.@@.@@. 25550@dots{} 255518060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00 CHIP..@@.......@@. 255528070: 00 00 00 49 4D C7 64 47 46 45 F3 48 DC 08 7E 0B ...IM.dGFE.H..~. 25553@dots{} 25554C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00 CHIP..@@.......@@. 25555C080: D5 F9 F0 C1 D5 F7 F0 BD E8 B5 02 F0 FB C9 05 30 ...............0 25556@end example 25557 25558 The Super Games cartridge uses 4 16KiB banks ($8000-$BFFF) of ROM 25559 memory. Bank selecting is done by writing to $DF00. 25560 25561 $DF00 register is as follows: 25562 25563@example 25564 bit meaning 25565 --- ------- 25566 0 bank bit 0 25567 1 bank bit 1 25568 2 mode (0 = EXROM/GAME (bridged on the same wire - 16KiB config) 25569 1 = cartridge disabled) 25570 3 write-protect-latch (1 = no more changes are possible until 25571 the next hardware-reset ) 25572 4-7 unused 25573@end example 25574 25575@c @node FIXME 25576@subsubsection 9 - Atomic Power 25577 25578@multitable @columnfractions .3 .7 25579@item Size 25580@tab 32KiB (4 banks of 8KiB modules) 25581@item EXROM 25582@tab active (lo) (0) 25583@item GAME 25584@tab inactive (hi) (1) 25585@item Load address 25586@tab $8000-9FFF (all modules) 25587@end multitable 25588 25589@example 25590 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25591 ----------------------------------------------- ---------------- 255920000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 255930010: 00 00 00 40 01 00 00 09 00 01 00 00 00 00 00 00 ...@@............ 255940020: 41 74 6F 6D 69 63 20 50 6F 77 65 72 00 00 00 00 Atomic Power.... 255950030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 255960040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 255970050: 09 80 0C 80 C3 C2 CD 38 30 4C 41 80 4C 1E 80 4C .......80LA.L..L 25598@dots{} 255992050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 256002060: 09 80 0C 80 C3 C2 CD 38 30 4C 3F 80 4C 91 80 4C .......80L?.L..L 25601@dots{} 256024060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 256034070: EF FC 09 80 C3 C2 CD 38 30 4C 27 80 4C DB 81 4C .......80L'.L..L 25604@dots{} 256056070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 256066080: 09 80 0C 80 C3 C2 CD 38 30 4C 73 86 4C 30 80 4C .......80Ls.L0.L 25607@end example 25608 25609 This cart has 32KiB of ROM and 8KiB of RAM 25610 25611 Writing to I/O-1 will do the following: 25612 25613@example 25614 bit meaning 25615 --- ------- 25616 7 extra ROM bank selector (A15) (unused) 25617 6 1 = resets FREEZE-mode (turns back to normal mode) 25618 5 1 = enable RAM at ROML ($8000-$9FFF) & 25619 I/O-2 ($DF00-$DFFF = $9F00-$9FFF) 25620 4 ROM bank selector high (A14) 25621 3 ROM bank selector low (A13) 25622 2 1 = disable cartridge (turn off $DE00) 25623 1 1 = /EXROM high 25624 0 1 = /GAME low 25625@end example 25626 25627 If bit 5 (RAM enable) is 1, bit 0,1 (exrom/game) is == 2 (cart off), 25628 bit 2,6,7 (cart disable, freeze clear) are 0, then cart ROM (Bank 0..3) 25629 is mapped at 8000-9FFF, and cart RAM (Bank 0) is mapped at A000-BFFF 25630 and cart RAM (Bank 0) is is enabled in the I/O-2 area using 16KiB game 25631 config. 25632 25633 The cart RAM or ROM is available through a window in the I/O-2 range. 25634 25635 25636@c @node FIXME 25637@subsubsection 10 - Epyx Fastload 25638 25639@multitable @columnfractions .3 .7 25640@item Size 25641@tab 8KiB 25642@item EXROM 25643@tab active (lo) (0) 25644@item GAME 25645@tab inactive (hi) (1) 25646@item Load address 25647@tab $8000-9FFF 25648@end multitable 25649 25650@example 25651 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25652 ----------------------------------------------- ---------------- 256530000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 256540010: 00 00 00 40 01 00 00 0A 00 01 00 00 00 00 00 00 ...@@............ 256550020: 45 50 59 58 20 46 41 53 54 4C 4F 41 44 00 00 00 EPYX FASTLOAD... 256560030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 256570040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 256580050: 30 80 5E FE C3 C2 CD 38 30 20 04 90 4C 38 DF AB 0.^....80 ..L8.. 25659@end example 25660 25661 The Epyx FastLoad cart uses a simple capacitor to toggle the ROM on 25662 and off: 25663 25664 the capacitor is discharged, and 8KiB game config enabled, by either 25665 reading ROML or reading I/O-1. If none of those accesses happen the 25666 capacitor will charge, and if it is charged (after 512 cycles) then 25667 the ROM will get disabled. 25668 25669@c @node FIXME 25670@subsubsection 11 - Westermann Learning 25671 25672@multitable @columnfractions .3 .7 25673@item Size 25674@tab 16KiB 25675@item EXROM 25676@tab active (lo) (0) 25677@item GAME 25678@tab active (lo) (0) 25679@item Load address 25680@tab $8000-BFFF 25681@end multitable 25682 25683@example 25684 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25685 ----------------------------------------------- ---------------- 256860000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 256870010: 00 00 00 40 01 00 00 0B 00 00 00 00 00 00 00 00 ...@@............ 256880020: 57 45 53 54 45 52 4D 41 4E 4E 00 00 00 00 00 00 WESTERMANN...... 256890030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 256900040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 40 00 CHIP.. .......@@. 256910050: 09 80 9C 80 C3 C2 CD 38 30 A2 00 8E 16 D0 20 84 .......80..... . 25692@end example 25693 25694 Any read from the I/O-2 range will switch the cart off. 25695 25696 25697@c @node FIXME 25698@subsubsection 12 - Rex Utility 25699 25700@multitable @columnfractions .3 .7 25701@item Size 25702@tab 8KiB 25703@item EXROM 25704@tab active (lo) (0) 25705@item GAME 25706@tab inactive (hi) (1) 25707@item Load address 25708@tab $8000-9FFF 25709@end multitable 25710 25711@example 25712 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25713 ----------------------------------------------- ---------------- 257140000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 257150010: 00 00 00 40 01 00 00 0C 00 01 00 00 00 00 00 00 ...@@............ 257160020: 52 45 58 00 00 00 00 00 00 00 00 00 00 00 00 00 REX............. 257170030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 257180040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 257190050: 08 80 C1 FE C3 C2 CD 38 30 6C 95 E3 20 A3 FD 20 .......80l.. .. 25720@end example 25721 25722 Reading from $DF00-DFBF disables ROM, reading from $DFC0-DFFF enables 25723 ROM (8KiB game config). 25724 25725 25726@c @node FIXME 25727@subsubsection 13 - Final Cartridge I 25728 25729@multitable @columnfractions .3 .7 25730@item Size 25731@tab 16KiB 25732@item EXROM 25733@tab active (lo) (0) 25734@item GAME 25735@tab active (lo) (0) 25736@item Load address 25737@tab $8000-BFFF 25738@end multitable 25739 25740@example 25741 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25742 ----------------------------------------------- ---------------- 257430000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 257440010: 00 00 00 40 01 00 00 0D 00 00 00 00 00 00 00 00 ...@@............ 257450020: 54 68 65 20 46 69 6E 61 6C 20 43 61 72 74 72 69 The Final Cartri 257460030: 64 67 65 20 49 00 00 00 00 00 00 00 00 00 00 00 dge I........... 257470040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 257480050: 80 BA 5E FE C3 C2 CD 38 30 00 A0 A0 20 2D FE 58 ..^....80... -.X 25749@end example 25750 25751 Any access to I/O-1 turns cartridge ROM off. Any access to I/O-2 turns 25752 cartridge ROM on. 25753 25754 The cart ROM is visible in I/O-1 and I/O-2. 25755 25756@c @node FIXME 25757@subsubsection 14 - Magic Formel 25758 25759@multitable @columnfractions .3 .7 25760@item Size 25761@tab 64KiB (8 banks of 8KiB) 25762@item EXROM 25763@tab inactive (hi) (1) 25764@item GAME 25765@tab active (lo) (0) 25766@item Load Address 25767@tab $E000-FFFF 25768@end multitable 25769 25770@example 25771 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25772 ----------------------------------------------- ---------------- 257730000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 257740010: 00 00 00 40 01 00 00 0E 01 00 00 00 00 00 00 00 ...@@............ 257750020: 4D 61 67 69 63 20 46 6F 72 6D 65 6C 00 00 00 00 Magic Formel.... 257760030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 257770040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00 CHIP.. ....... . 257780050: 4D 46 30 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D MF0...`...`...`. 25779@dots{} 257802050: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00 CHIP.. ....... . 257812060: 4C 5F E4 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D L_....`...`...`. 25782@dots{} 257834060: 43 48 49 50 00 00 20 10 00 00 00 02 E0 00 20 00 CHIP.. ....... . 257844070: 4D 46 32 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D MF2...`...`...`. 25785@dots{} 257866070: 43 48 49 50 00 00 20 10 00 00 00 03 E0 00 20 00 CHIP.. ....... . 257876080: 4D 46 33 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D MF3...`...`...`. 25788@dots{} 257898080: 43 48 49 50 00 00 20 10 00 00 00 04 E0 00 20 00 CHIP.. ....... . 257908090: 4D 46 34 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D MF4...`...`...`. 25791@dots{} 25792A090: 43 48 49 50 00 00 20 10 00 00 00 05 E0 00 20 00 CHIP.. ....... . 25793A0A0: 4D 46 35 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D MF5...`...`...`. 25794@dots{} 25795C0A0: 43 48 49 50 00 00 20 10 00 00 00 06 E0 00 20 00 CHIP.. ....... . 25796C0B0: 4D 46 36 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D MF6...`...`...`. 25797@dots{} 25798E0B0: 43 48 49 50 00 00 20 10 00 00 00 07 E0 00 20 00 CHIP.. ....... . 25799E0C0: 4D 46 37 8D 00 DF 60 8D 01 DF 60 8D 02 DF 60 8D MF7...`...`...`. 25800@end example 25801 25802 25803@c @node FIXME 25804@subsubsection 15 - C64 Game System, System 3 25805 25806@multitable @columnfractions .3 .7 25807@item Size 25808@tab 512KiB (64 banks of 8KiB each) 25809@item EXROM 25810@tab active (lo) (0) 25811@item GAME 25812@tab inactive (hi) (1) 25813@item Load address 25814@tab $8000-9FFF (all modules) 25815@end multitable 25816 25817@example 25818 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25819 ----------------------------------------------- ---------------- 2582000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 2582100010: 00 00 00 40 01 00 00 0F 00 01 00 00 00 00 00 00 ...@@............ 2582200020: 43 36 34 47 53 20 43 61 72 74 72 69 64 67 65 00 C64GS Cartridge. 2582300030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 2582400040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 2582500050: 6D 80 C5 80 C3 C2 CD 38 30 4C CB 80 4C 36 84 4C m......80L..L6.L 25826@dots{} 2582702050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 2582802060: 18 D0 A9 FF 8D 15 D0 8D 1D D0 8D 17 D0 A2 07 A9 ................ 25829@dots{} 2583004060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 2583104070: E0 08 19 21 77 84 52 98 9F 80 A5 21 31 01 31 89 ...!w.R....!1.1. 25832@dots{} 2583306070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 2583406080: C0 08 1C 1D A0 92 03 03 D8 AA 04 C0 B8 01 40 EA ..............@@. 25835@dots{} 258367E430: 43 48 49 50 00 00 20 10 00 00 00 3F 80 00 20 00 CHIP.. ....?.. . 258377E440: 45 20 41 20 42 49 47 20 58 FE 4F 4E 20 54 48 49 E A BIG X.ON THI 25838@end example 25839 25840 Here is a list of the known cartridges: 25841 25842@example 25843 C64GS 4-in-1 (Commodore) (512 KiB) 25844 Last Ninja Remix (System 3) (512 KiB) 25845 Myth (System 3) (512 KiB) 25846@end example 25847 25848 ROM memory is organized in 8KiB ($2000) banks located at $8000-$9FFF. 25849 Bank switching is done by writing to address $DE00+X, where X is the 25850 bank number (STA $DE00,X). For instance, to read from bank 3, address 25851 $DE03 is written to. Reading from anywhere in the I/O-1 range will 25852 disable the cart. 25853 25854 The CRT file contains a string of CHIP blocks, each block with a start 25855 address of $8000, length $2000 and the bank number in the bank field. 25856 In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set to 25857 1 to enable the 8 KiB ROM configuration. 25858 25859 25860@c @node FIXME 25861@subsubsection 16 - Warp Speed 25862 25863@multitable @columnfractions .3 .7 25864@item Size 25865@tab 16KiB 25866@item EXROM 25867@tab active (lo) (0) 25868@item GAME 25869@tab active (lo) (0) 25870@item Load address 25871@tab $8000-BFFF 25872@end multitable 25873 25874@example 25875 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25876 ----------------------------------------------- ---------------- 258770000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 258780010: 00 00 00 40 01 00 00 10 00 00 00 00 00 00 00 00 ...@@............ 258790020: 57 61 72 70 73 70 65 65 64 00 00 00 00 00 00 00 Warpspeed....... 258800030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 258810040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 258820050: 4C 22 80 4C 22 80 FF 43 42 4D 20 53 E4 20 18 E5 L".L"..CBM S. .. 25883@end example 25884 25885 After RESET or POWER ON, 16KiB of cartridge ROM is visible at 25886 $8000-$BFFF. Additionally, ROM normally located at $9E00-$9FFF is 25887 mirrored into I/O-1 and I/O-2 at $DE00-$DFFF. ROM at $8000-$BFFF is 25888 disabled by writing into the I/O-2 area (typically $DF00) and may be 25889 re-enabled by writing into I/O-1 ($DE00). However, the $DE00-$DFFF 25890 (I/O-1/I/O-2) area itself always remains mapped to cartridge ROM. 25891 25892 25893@c @node FIXME 25894@subsubsection 17 - Dinamic 25895 25896@multitable @columnfractions .3 .7 25897@item Size 25898@tab 128KiB (16 banks of 8KiB each) 25899@item EXROM 25900@tab active (lo) (0) 25901@item GAME 25902@tab inactive (hi) (1) 25903@item Load address 25904@tab $8000-9FFF (all modules) 25905@end multitable 25906 25907@example 25908 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25909 ----------------------------------------------- ---------------- 2591000000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 2591100010: 00 00 00 40 01 00 00 11 00 01 00 00 00 00 00 00 ...@@............ 2591200020: 4E 61 72 63 6F 20 50 6F 6C 69 63 65 00 00 00 00 Narco Police.... 2591300030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 2591400040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 2591500050: 0B 80 0B 80 C3 C2 CD 38 30 00 00 78 A2 FF 9A D8 .......80..x.... 25916.. 2591702050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 2591802060: 1C 8C 1B 8C 16 16 8F 16 16 88 1C 1C 86 1C 1C 89 ................ 25919.. 2592004060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 2592104070: B6 02 07 08 07 07 00 0A 0A B6 00 05 0A 00 07 07 ................ 25922.. 259231E130: 43 48 49 50 00 00 20 10 00 00 00 0F 80 00 20 00 CHIP.. ....... . 259241E140: 00 D5 70 03 F5 70 0F 5F 70 0F F7 70 35 FD F0 37 ..p..p._p..p5..7 25925@end example 25926 25927 Here is a list of the known DINAMIC cartridges: 25928 25929@example 25930 Narco Police (128 KiB) 25931 Satan (128 KiB) 25932@end example 25933 25934 ROM memory is organized in 8KiB ($2000) banks located at $8000-$9FFF. 25935 Bank switching is done by reading from address $DE00+X, where X is the 25936 bank number (LDA $DE00,X). For instance, to read from bank 3, address 25937 $DE03 is accessed. 25938 25939 The CRT file contains a string of CHIP blocks, each block with a start 25940 address of $8000, length $2000 and the bank number in the bank field. 25941 In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set to 25942 1 to enable the 8 KiB ROM configuration. 25943 25944 25945@c @node FIXME 25946@subsubsection 18 - Zaxxon, Super Zaxxon (SEGA) 25947 25948@multitable @columnfractions .3 .7 25949@item Size 25950@tab 20KiB (3 banks of different sizes) 25951@item EXROM 25952@tab active (lo) (0) 25953@item GAME 25954@tab active (lo) (0) 25955@item Load address 25956@tab $8000-8FFF (mirrored in $9000-9FFF, module 0, chip U1) 25957 $A000-BFFF (banked modules 1 and 2, chip U2) 25958@end multitable 25959 25960@example 25961 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 25962 ----------------------------------------------- ---------------- 259630000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 259640010: 00 00 00 40 01 00 00 12 00 00 00 00 00 00 00 00 ...@@............ 259650020: 5A 61 78 78 6F 6E 00 00 00 00 00 00 00 00 00 00 Zaxxon.......... 259660030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 259670040: 43 48 49 50 00 00 10 10 00 00 00 00 80 00 10 00 CHIP............ 259680050: 0D 80 29 80 C3 C2 CD 38 30 78 4C 09 80 78 A9 00 ..)....80xL..x.. 25969.. 259701050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00 CHIP.. ....... . 259711060: A2 0F BD 00 20 D0 04 CA 10 F8 60 BD 70 20 F0 0D .... .....`.p .. 25972.. 259733060: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00 CHIP.. ....... . 259743070: 65 A2 36 A3 E7 A3 CB A4 94 A5 86 A6 5E A7 35 A8 e.6.........^.5. 25975@end example 25976 25977 The (Super) Zaxxon carts use a 4KiB ($1000) ROM at $8000-$8FFF (mirrored 25978 in $9000-$9FFF) along with two 8KiB ($2000) cartridge banks located at 25979 $A000-$BFFF. One of the two banks is selected by doing a read access to 25980 either the $8000-$8FFF area (bank 0 is selected) or to $9000-$9FFF area 25981 (bank 1 is selected). EXROM ($18 = $00) and GAME ($19 = $00) lines are 25982 always pulled to GND to select the 16 KiB ROM configuration. 25983 25984 The CRT file includes three CHIP blocks: 25985@example 25986 a) bank = 0, load address = $8000, size = $1000 25987 b) bank = 0, load address = $A000, size = $2000 25988 c) bank = 1, load address = $A000, size = $2000 25989@end example 25990 25991@c @node FIXME 25992@subsubsection 19 - Magic Desk, Domark, HES Australia 25993 25994@multitable @columnfractions .3 .7 25995@item Size 25996@tab 32KiB, 64KiB or 128KiB sizes (4 to 16 banks of 8KiB each) 25997@item EXROM 25998@tab active (lo) (0) 25999@item GAME 26000@tab inactive (hi) (1) 26001@item Startup mode 26002@tab 8KiB Game 26003@item Load address 26004@tab (banks 00-15) - $8000-9FFF 26005@end multitable 26006 26007@example 26008 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26009 ----------------------------------------------- ---------------- 260100000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 260110010: 00 00 00 40 01 00 00 13 00 01 00 00 00 00 00 00 ...@@............ 260120020: 4D 61 67 69 63 20 44 65 73 6B 00 00 00 00 00 00 Magic Desk...... 260130030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 260140040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 260150050: 09 80 C6 CA C3 C2 CD 38 30 8E 16 D0 20 A3 FD 20 .......80... .. 26016.. 260172050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 260182060: 00 3F 0A 01 00 86 4E 24 28 31 30 29 3A 4A 4F 59 .?....N$(10):JOY 26019.. 260204060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 260214070: 00 8B C9 28 4E 24 2C 31 29 B3 B1 22 FF 22 A7 32 ...(N$,1)..".".2 26022.. 260236070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 260246080: AE 01 83 33 2C 37 2C 22 32 29 20 44 45 4C 20 4B ...3,7,"2) DEL K 26025@end example 26026 26027 This cartridge type is very similar to the OCEAN cart type: ROM memory 26028 is organized in 8KiB ($2000) banks located at $8000-$9FFF. Bank 26029 switching is done by writing the bank number to $DE00. Deviant from the 26030 Ocean type, bit 7 is cleared for selecting one of the ROM banks. If bit 26031 7 is set ($DE00 = $80), the GAME/EXROM lines are disabled, turning on 26032 RAM at $8000-$9FFF instead of ROM. 26033 26034 In the cartridge header, EXROM ($18) is set to 0, GAME ($19) is set to 26035 1 to indicate the RESET/power-up configuration of 8 KiB ROM. 26036 26037 Here is a list of the known cartridges: 26038 26039@example 26040 Ghosbusters (HES Australia) (32 KiB) 26041 Magic Desk (Commodore) (32 KiB) 26042 Badlands (Domark) (64 KiB) 26043 Vindicators (Domark) (64 KiB) 26044 Wonderboy (HES Australia) (64 KiB) 26045 Cyberball (Domark) (128 KiB) 26046@end example 26047 26048 26049@c @node FIXME 26050@subsubsection 20 - Super Snapshot V5 26051 26052@multitable @columnfractions .3 .7 26053@item Size 26054@tab 64KiB (4 banks of 16KiB each) 26055@item EXROM 26056@tab active (lo) (0) 26057@item GAME 26058@tab active (lo) (0) 26059@item Load address 26060@tab $8000-BFFF 26061@end multitable 26062 26063@example 26064 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26065 ----------------------------------------------- ---------------- 260660000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 260670010: 00 00 00 40 01 00 00 14 00 00 00 00 00 00 00 00 ...@@............ 260680020: 53 75 70 65 72 20 53 6E 61 70 73 68 6F 74 20 35 Super Snapshot 5 260690030: 20 4E 54 53 43 00 00 00 00 00 00 00 00 00 00 00 NTSC........... 260700040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 260710050: 09 80 59 80 C3 C2 CD 38 30 20 03 9F 00 FA F4 20 ..Y....80 ..... 26072@dots{} 260734050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00 CHIP..@@.......@@. 260744060: 79 DE BC FE C3 C2 CD 38 30 A9 05 8D 20 D0 8D 21 y......80... ..! 26075@dots{} 260768060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00 CHIP..@@.......@@. 260778070: 50 DE BC FE C3 C2 CD 38 30 A9 0A 85 6A A9 0D 85 P......80...j... 26078@dots{} 26079C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00 CHIP..@@.......@@. 26080C080: 50 DE BC FE C3 C2 CD 38 30 85 07 20 1A AD A5 76 P......80.. ...v 26081@end example 26082 26083 The first page of the currently selected ROM bank is mirrored in the 26084 I/O-1 range when reading. 26085 26086 The control Register is the I/O-1 range when writing: 26087 26088@example 26089 bit meaning 26090 --- ------- 26091 7-5 unused 26092 4 ROM/RAM bank bit 1 26093 3 ROM enable 26094 2 ROM/RAM bank bit 0 26095 1 RAM enable, EXROM 26096 0 release freeze, !GAME 26097@end example 26098 26099 26100@c @node FIXME 26101@subsubsection 21 - Comal-80 26102 26103@multitable @columnfractions .3 .7 26104@item Size 26105@tab 64KiB (4 banks of 16KiB each) 26106@item EXROM 26107@tab active (low) (0) 26108@item GAME 26109@tab active (low) (0) 26110@item Load address 26111@tab $8000-BFFF 26112@end multitable 26113 26114@example 26115 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26116 ----------------------------------------------- ---------------- 261170000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 261180010: 00 00 00 40 01 00 00 15 00 00 00 00 00 00 00 00 ...@@............ 261190020: 43 6F 6D 61 6C 20 38 30 00 00 00 00 00 00 00 00 Comal 80........ 261200030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 261210040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 261220050: 87 87 70 CF C3 C2 CD 38 30 4C AA CF 4C 70 CF 4C ..p....80L..Lp.L 26123@dots{} 261244050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00 CHIP..@@.......@@. 261254060: AA CF 70 CF C3 C2 CD 38 30 01 29 01 28 01 2C 04 ..p....80.).(.,. 26126@dots{} 261278060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00 CHIP..@@.......@@. 261288070: AA CF 70 CF C3 C2 CD 38 30 91 92 92 92 92 92 92 ..p....80....... 26129@dots{} 26130C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00 CHIP..@@.......@@. 26131C080: 7B C8 7E C8 C3 C2 CD 38 30 43 4F 4D 41 4C 80 93 @{.~....80COMAL.. 26132@end example 26133 26134 26135 The Comal-80 Cartridge uses 16KiB banks ($4000) at $8000-$BFFF. There are 4 26136 banks of ROM memory and the cart has 1 (write-only) bank control register which 26137 is located at $DE00 and mirrored throughout the $DE00-$DEFF range. 26138 26139@example 26140 bit meaning 26141 --- ------- 26142 7 exrom? 26143 6 game? 26144 5 unknown function (used by the software to disable the cartridge) 26145 4 unused? 26146 3 unused? 26147 2 unknown function (used by the software however) 26148 0-1 selects bank 26149@end example 26150 26151 26152@c @node FIXME 26153@subsubsection 22 - Structured Basic 26154 26155@multitable @columnfractions .3 .7 26156@item Size 26157@tab 16KiB (2 banks of 8KiB each) 26158@item EXROM 26159@tab inactive (hi) (1) 26160@item GAME 26161@tab active (0) 26162@item Load address 26163@tab $8000-9FFF 26164@end multitable 26165 26166 No sample data/file available. 26167 26168 IF YOU OWN THIS TYPE OF CARTRIDGE AND/OR CAN PROVIDE A ROM IMAGE, PLEASE 26169 GET IN TOUCH WITH US! 26170 26171 Any read/write access to $DE00 or $DE01 will switch in bank 0. Any 26172 read/write access to $DE02 will switch in bank 1. Any read/write access 26173 to $DE03 will switch off EXROM. 26174 26175 26176@c @node FIXME 26177@subsubsection 23 - Ross 26178 26179@multitable @columnfractions .3 .7 26180@item Size 26181@tab 16KiB or 32KiB sizes (1 or 2 banks of 16KiB each) 26182@item EXROM 26183@tab active (lo) (0) 26184@item GAME 26185@tab active (lo) (0) 26186@item Load address 26187@tab $8000-BFFF 26188@end multitable 26189 26190@example 26191 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26192 ----------------------------------------------- ---------------- 261930000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 261940010: 00 00 00 40 01 00 00 17 00 00 00 00 00 00 00 00 ...@@............ 261950020: 52 6F 73 73 20 31 34 00 00 00 00 00 00 00 00 00 Ross 14......... 261960030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 261970040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 261980050: 09 80 09 80 C3 C2 CD 38 30 A2 00 BD 20 80 4D 0E .......80... .M. 26199@dots{} 262004050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00 CHIP..@@.......@@. 262014060: 3F 5A 4D 4D 50 4D 8D 25 3F 1A 1F 77 3F CD E0 3F ?ZMMPM.%?..w?..? 26202@end example 26203 26204 Any read access to $DE00 will switch in bank 1 (if cart is 32KiB). Any 26205 read access to $DF00 will switch off EXROM and GAME. 26206 26207 26208@c @node FIXME 26209@subsubsection 24 - Dela EP64 26210 26211@multitable @columnfractions .3 .7 26212@item Size 26213@tab 8KiB to 72KiB sizes (1 to 9 banks of 8KiB each, 26214 or 1 bank of 8KiB and 1 or 2 banks 26215 of 32KiB each) 26216@item EXROM 26217@tab active (lo) (0) 26218@item GAME 26219@tab inactive (hi) (1) 26220@item Load address 26221@tab $8000-9FFF 26222@end multitable 26223 26224@example 26225 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26226 ----------------------------------------------- ---------------- 262270000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 262280010: 00 00 00 40 01 00 00 18 00 01 00 00 00 00 00 00 ...@@............ 262290020: 44 45 4C 41 20 45 50 36 34 00 00 00 00 00 00 00 DELA EP64....... 262300030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 262310040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 262320050: 00 85 5E FE C3 C2 CD 38 30 FF FF FF FF FF FF FF ..^....80....... 26233@dots{} 262342050: 43 48 49 50 00 00 80 10 00 00 00 01 80 00 80 00 CHIP............ 262352060: 54 45 53 54 0D 2A 0D 54 45 20 36 34 0D 00 00 00 TEST.*.TE 64.... 26236@end example 26237 26238 This is an eprom cartridge. It has 1 2764 (8KiB) which holds the base 26239 eprom with the base menu, and 2 27256 eproms of which 8KiB parts are 26240 banked into the $8000-9FFF area. 26241 26242 The bank selecting is done by writing to $DE00. The following bits are 26243 used for bank decoding in $DE00 (0 being the LSB, 3 being the MSB). 26244 26245@example 26246 Bit# 76543210 26247 xx10xx32 26248@end example 26249 26250 Any bank value below 4 or above 11 switches in the base bank (bank 0). 26251 26252 The bit values for each eprom bank are : 26253 26254@example 26255 eprom bank 1 : xx00xx01 26256 eprom bank 2 : xx01xx01 26257 eprom bank 3 : xx10xx01 26258 eprom bank 4 : xx11xx01 26259 eprom bank 5 : xx00xx10 26260 eprom bank 6 : xx01xx10 26261 eprom bank 7 : xx10xx10 26262 eprom bank 8 : xx11xx10 26263@end example 26264 26265 Setting bit 7 high will switch off EXROM. 26266 26267 26268@c @node FIXME 26269@subsubsection 25 - Dela EP7x8 26270 26271@multitable @columnfractions .3 .7 26272@item Size 26273@tab 8KiB to 64KiB sizes (1 to 8 banks of 8KiB each) 26274@item EXROM 26275@tab active (lo) (0) 26276@item GAME 26277@tab inactive (hi) (1) 26278@item Load address 26279@tab $8000-9FFF 26280@end multitable 26281 26282@example 26283 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26284 ----------------------------------------------- ---------------- 262850000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 262860010: 00 00 00 40 01 00 00 19 00 01 00 00 00 00 00 00 ...@@............ 262870020: 44 45 4C 41 20 45 50 37 78 38 00 00 00 00 00 00 DELA EP7x8...... 262880030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 262890040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 262900050: 09 80 5E FE C3 C2 CD 38 30 78 A2 FF 9A D8 8E 16 ..^....80x...... 26291@dots{} 262922050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 262932060: 94 83 A0 83 C3 C2 CD 38 30 02 BB 5A 30 5F EE 3D .......80..Z0_.= 26294@end example 26295 26296 This is an eprom cartridge. It has 8 8KiB banks of which the first holds 26297 the base menu, the other eproms can be banked into the $8000-9FFF area. 26298 26299 The bank selecting is done by writing to $DE00. Each low bit is used to 26300 bank in the respective eprom. If all bits are high then the EXROM is 26301 switched off. 26302 26303 The bit values for each eprom bank is: 26304 26305@example 26306 eprom bank 1 : 11111110 ($FE) (base eprom) 26307 eprom bank 2 : 11111101 ($FD) 26308 eprom bank 3 : 11111011 ($FB) 26309 eprom bank 4 : 11110111 ($F7) 26310 eprom bank 5 : 11101111 ($EF) 26311 eprom bank 6 : 11011111 ($DF) 26312 eprom bank 7 : 10111111 ($BF) 26313 eprom bank 8 : 01111111 ($7F) 26314 26315 EXROM off : 11111111 ($FF) 26316@end example 26317 26318@c @node FIXME 26319@subsubsection 26 - Dela EP256 26320 26321@multitable @columnfractions .3 .7 26322@item Size 26323@tab 8KiB to 262KiB sizes (1 to 33 banks of 8KiB each) 26324@item EXROM 26325@tab active (lo) (0) 26326@item GAME 26327@tab inactive (hi) (1) 26328@item Load address 26329@tab $8000-9FFF 26330@end multitable 26331 26332@example 26333 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26334 ----------------------------------------------- ---------------- 263350000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 263360010: 00 00 00 40 01 00 00 1A 00 01 00 00 00 00 00 00 ...@@............ 263370020: 44 45 4C 41 20 45 50 32 35 36 00 00 00 00 00 00 DELA EP256...... 263380030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 263390040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 263400050: 00 85 5E FE C3 C2 CD 38 30 93 0D 2B 2B 2B 20 45 ..^....80..+++ E 26341@dots{} 263422050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 263432060: 09 80 28 80 C3 C2 CD 38 30 78 A2 05 8E 16 D0 20 ..(....80x..... 26344@dots{} 263454060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 263464070: 0B 80 BC FE C3 C2 CD 38 30 DC 10 8E 16 D0 20 87 .......80..... . 26347@dots{} 263486070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 263496080: 09 80 F6 8E C3 C2 CD 38 30 A2 C8 8E 16 D0 20 .. ?.?....80...?.?. 26350@dots{} 263518080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00 CHIP.. ....... . 263528090: 94 83 A0 83 C3 C2 CD 38 30 02 BB 5A 30 5F EE 3D .......80..Z0_.= 26353@end example 26354 26355 This is an eprom cartridge. It has 33 8KiB banks of which the first 26356 holds the base menu, the other eproms can be banked into the $8000-9FFF 26357 area. 26358 26359 The bank selecting is done by writing to $DE00. 26360 26361 The values for the (extra) eprom banks are: 26362 26363@example 26364 eprom banks 1- 8 : $38-3F 26365 eprom banks 9-16 : $28-2F 26366 eprom banks 17-24 : $18-1F 26367 eprom banks 25-32 : $08-0F 26368@end example 26369 26370 Setting bit 7 high will switch off EXROM. 26371 26372 26373@c @node FIXME 26374@subsubsection 27 - Rex EP256 26375 26376@multitable @columnfractions .3 .7 26377@item Size 26378@tab 8KiB to 262KiB sizes (1 bank of 8KiB and 1 to 8 banks of either 26379 8KiB, 16KiB or 32KiB) 26380@item EXROM 26381@tab active (lo) (0) 26382@item GAME 26383@tab inactive (hi) (1) 26384@item Load address 26385@tab $8000-9FFF 26386@end multitable 26387 26388@example 26389 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26390 ----------------------------------------------- ---------------- 263910000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 263920010: 00 00 00 40 01 00 00 1B 00 01 00 00 00 00 00 00 ...@@............ 263930020: 52 45 58 20 45 50 32 35 36 00 00 00 00 00 00 00 REX EP256....... 263940030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 263950040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 263960050: 09 80 C1 FE C3 C2 CD 38 30 20 A3 FD 20 50 FD 20 .......80 .. P. 26397@dots{} 263982050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 263992060: 09 80 F2 8F C3 C2 CD 38 30 A2 C8 8E 16 D0 20 A3 .......80..... . 26400@dots{} 264014060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00 CHIP..@@.......@@. 264024070: 09 80 09 80 C3 C2 CD 38 30 58 D8 20 84 FF 20 8A .......80X. .. . 26403@end example 26404 26405 This is an eprom cartridge. It has 9 eprom sockets, of which the first 26406 holds the base eprom with the base menu which is an 8KiB eprom, the 26407 other eprom sockets can handle 8KiB, 16KiB or 32KiB eproms, of which 8KiB 26408 can be banked into the $8000-9FFF area. 26409 26410 The bank selecting is done by writing to $DFA0. Bits 2, 1 and 0 26411 determine which socket is used and bits 5 and 4 are used to select an 26412 8KiB piece of the eprom. 26413 26414 The possible values for bits 5 and 4 for the (extra) eprom banks are: 26415 26416@example 26417 8KiB : 3, 2, 1, 0 26418 26419 16KiB bank 0 : 2, 0 26420 16KiB bank 1 : 3, 1 26421 26422 32KiB bank 0 : 0 26423 32KiB bank 1 : 1 26424 32KiB bank 2 : 2 26425 32KiB bank 3 : 3 26426@end example 26427 26428 Reading from $DFC0 switches off the EXROM. 26429 Reading from $DFE0 switches on the EXROM. 26430 26431@c @node FIXME 26432@subsubsection 28 - Mikro Assembler 26433 26434@multitable @columnfractions .3 .7 26435@item Size 26436@tab 8KiB (1 bank of 8KiB) 26437@item EXROM 26438@tab active (lo) (0) 26439@item GAME 26440@tab inactive (hi) (1) 26441@item Load address 26442@tab $8000-9FFF 26443@end multitable 26444 26445@example 26446 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26447 ----------------------------------------------- ---------------- 264480000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 264490010: 00 00 00 40 01 00 00 1C 00 01 00 00 00 00 00 00 ...@@............ 264500020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 264510030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 264520040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 264530050: 60 80 FE 80 C3 C2 CD 38 30 4C 07 87 4C CA 82 41 `......80L..L..A 26454@end example 26455 26456 26457 The $9E00-$9EFF range is mirrored at $DE00-$DEFF. The $9F00-$9FFF range 26458 is mirrored at $DF00-$DFFF. 26459 26460@c @node FIXME 26461@subsubsection 29 - Final Cartridge Plus 26462 26463@multitable @columnfractions .3 .7 26464@item Size 26465@tab 32KiB (1 bank of 32KiB) 26466@item EXROM 26467@tab inactive (hi) (1) 26468@item GAME 26469@tab active (lo) (0) 26470@item Load address 26471@tab $0000-$7FFF 26472@end multitable 26473 26474@example 26475 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26476 ----------------------------------------------- ---------------- 264770000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 264780010: 00 00 00 40 01 00 00 1D 01 00 00 00 00 00 00 00 ...@@............ 264790020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 264800030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 264810040: 43 48 49 50 00 00 80 10 00 00 00 00 00 00 80 00 CHIP............ 264820050: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF ................ 26483@end example 26484 26485 26486 This cart has 32KiB of ROM, bank 0 is in the cart image but is unused. 26487 The first 8KiB of the cart image is unused, the second 8KiB of the cart 26488 image is mapped to $E000-$FFFF, the third 8KiB of the cart image is 26489 mapped to $8000-$9FFF and the fourth 8KiB of the cart image is mapped 26490 to $A000-$BFFF. An NMI can be triggered by the cart, if address $0001 26491 is written to and the cartridge is enabled. The cart can be disabled 26492 by software, by clearing bit 4 when writing to $DF00-$DFFF. Cart ROM 26493 at $E000-$FFFF can be disabled by setting bit 5 to 0 when writing to 26494 $DF00-$DFFF. Cart ROM at $8000-$BFFF can be disabled by setting bit 6 26495 to 1 when writing to $DF00-$DFFF. Bit 7 of a byte written to 26496 $DF00-$DFFF can be read back from the cartridge if enabled (like a 26497 memory cell). 26498 26499@c @node FIXME 26500@subsubsection 30 - Action Replay 4 26501 26502@multitable @columnfractions .3 .7 26503@item Size 26504@tab 32KiB (4 banks of 8KiB) 26505@item EXROM 26506@tab active (lo) (0) 26507@item GAME 26508@tab inactive (hi) (1) 26509@item Load address 26510@tab $8000-$9FFF 26511@end multitable 26512 26513@example 26514 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26515 ----------------------------------------------- ---------------- 265160000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 265170010: 00 00 00 40 01 00 00 1E 00 01 00 00 00 00 00 00 ...@@............ 265180020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 265190030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 265200040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 265210050: EA 78 48 A9 7F 8D 0D DD D0 0E 48 AD 0D DD 10 04 .xH.......H..... 26522@dots{} 265232050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 265242060: 09 80 0C 80 C3 C2 CD 38 30 4C E9 80 4C 81 81 4C .......80L..L..L 26525@dots{} 265264060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 265274070: 09 80 0E 80 C3 C2 CD 38 30 A2 00 4C EF FC 20 BC .......80..L.. . 26528@dots{} 265296070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 265306080: 09 80 0C 80 C3 C2 CD 38 30 4C 70 88 4C 3F 80 4C .......80Lp.L?.L 26531@end example 26532 26533 The control register is the I/O-1 range: 26534 26535@example 26536 bit meaning 26537 --- ------- 26538 0 Eprom banking bit 0 (bank address 13) 26539 1 Controls the GAME line (0 sets GAME low, 1 sets GAME high) 26540 2 Freeze-end bit (disables the register and hides any rom bank) 26541 3 Controls the Exrom line (1 sets EXROM low, 0 sets EXROM high) 26542 4 Eprom banking bit 1 (bank address 14) 26543 5-7 Unused 26544@end example 26545 26546 The first page of the currently banked ROM block can be read in the 26547 I/O-2 range. 26548 26549@c @node FIXME 26550@subsubsection 31 - Stardos 26551 26552@multitable @columnfractions .3 .7 26553@item Size 26554@tab 16KiB (2 banks of 8KiB) 26555@item EXROM 26556@tab inactive (hi) (1) 26557@item GAME 26558@tab active (lo) (0) 26559@item Load address 26560@tab $8000-$9FFF (bank 0), 26561 $E000-$FFFF (bank 1) 26562@end multitable 26563 26564@example 26565 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26566 ----------------------------------------------- ---------------- 265670000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 265680010: 00 00 00 40 01 00 00 1F 01 00 00 00 00 00 00 00 ...@@............ 265690020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 265700030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 265710040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 265720050: F9 80 B6 80 C3 C2 CD 38 30 FD 80 89 80 4C 0C 88 .......80....L.. 26573@dots{} 265742050: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00 CHIP.. ....... . 265752060: 85 56 20 0F BC A5 61 C9 88 90 03 20 D4 BA 20 CC .V ...a.... .. . 26576@end example 26577 26578 This cart has 16KiB of ROM, of which the first 8KiB is mapped in at 26579 $8000-$9FFF and the second 8KiB is used as a kernel replacement. The 26580 kernel replacement is achieved by a clip that needs to be installed 26581 inside the C64. 26582 26583 Reading from I/O-1 causes a capacitor to get charged with every read, 26584 once the capacitor is charged enough it switches the cart on. 26585 26586 Reading from I/O-2 causes a different capacitor to get charged with 26587 every read, once the capacitor is charged enough it switched the cart 26588 off. 26589 26590@c @node FIXME 26591@subsubsection 32 - EasyFlash 26592 26593@multitable @columnfractions .3 .7 26594@item Size 26595@tab 1024KiB (64 banks of 2 * 8KiB) 26596@item EXROM 26597@tab inactive (hi) (1) 26598@item GAME 26599@tab active (lo) (0) 26600@item Load address 26601@tab $8000-$9FFF (ROML), $A000-$BFFF or $E000-$FFFF (ROMH) 26602@end multitable 26603 26604@example 26605 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26606 ----------------------------------------------- ---------------- 266070000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 266080010: 00 00 00 40 01 00 00 20 01 00 00 00 00 00 00 00 ...@@... ........ 266090020: 45 61 73 79 46 6C 61 73 68 20 43 61 72 74 72 69 EasyFlash Cartri 266100030: 64 67 65 00 00 00 00 00 00 00 00 00 00 00 00 00 dge............. 266110040: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 266120050: 00 85 5E FE C3 C2 CD 38 30 93 0D 2B 2B 2B 20 45 ..^....80..+++ E 26613@end example 26614 26615 26616 EasyFlash is a 1 MiB Flash EPROM card with multiple configurations 26617 and banks possible, it also has 256 bytes of RAM which is mapped into 26618 the I/O-2 range. 26619 26620 There are two control registers, one at $DE00 and one at $DE02. 26621 26622 The register at $DE00 does the following: 26623 26624@example 26625 bit meaning 26626 --- ------- 26627 7 LED control 26628 6-3 Unused 26629 2 Mode (0/1) 26630 1 Exrom line control 26631 0 Game line control 26632@end example 26633 26634 The register at $DE02 controls which bank is mapped into ROMH and 26635 ROML. 26636 26637@c @node FIXME 26638@subsubsection 33 - EasyFlash Xbank 26639 26640@multitable @columnfractions .3 .7 26641@item Size 26642@tab - 26643@item EXROM 26644@tab - 26645@item GAME 26646@tab - 26647@item Load address 26648@tab - 26649@end multitable 26650 26651This CRT type is not actually related to a seperate hardware, it is used by some 26652EasyFlash related tools as a container format. Consequently VICE does (can) not 26653load files of this type. 26654 26655@c @node FIXME 26656@subsubsection 34 - Capture 26657 26658@multitable @columnfractions .3 .7 26659@item Size 26660@tab 8KiB (1 bank of 8KiB) 26661@item EXROM 26662@tab inactive (hi) (1) 26663@item GAME 26664@tab inactive (hi) (1) 26665@item Load address 26666@tab $E000-$FFFF 26667@end multitable 26668 26669@example 26670 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26671 ----------------------------------------------- ---------------- 266720000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 266730010: 00 00 00 40 01 00 00 22 00 00 00 00 00 00 00 00 ...@@..."........ 266740020: 4D 61 67 69 63 20 46 6F 72 6D 65 6C 00 00 00 00 Magic Formel.... 266750030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 266760040: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00 CHIP.. ....... . 266770050: 00 0A 0D 8A B4 A1 20 80 00 0A 82 8A 8D 20 9E 20 ...... ...... . 26678@end example 26679 26680 26681 This cart has 8KiB of ROM which is mapped to $E000, and 8KiB of RAM 26682 which is mapped to $6000. The cartridge is disabled after a reset. 26683 26684 When the freeze button is pressed the following happens: 26685 26686@itemize @bullet 26687@item an NMI is generated 26688@item as soon as the current adress is in bank 0xfe the cart switches to 26689 ultimax mode. The cart ROM then contains one page full of 26690 "jmp $eaea", which ultimately calls the freezer code. 26691@item the $FFF7/$FFF8 "register" logic is enabled and any access (read or 26692 write) to $FFF7 will turn the cart_enabled off (leave ultimax mode), 26693 and an access to $FFF8 will turn the cart back on (enter ultimax 26694 mode). the "register logic" that causes this can only be disabled 26695 again by a hardware reset. 26696@end itemize 26697 26698@c @node FIXME 26699@subsubsection 35 - Action Replay 3 26700 26701@multitable @columnfractions .3 .7 26702@item Size 26703@tab 16KiB (2 banks of 8KiB) 26704@item EXROM 26705@tab active (lo) (0) 26706@item GAME 26707@tab inactive (hi) (1) 26708@item Load address 26709@tab $8000-$9FFF 26710@end multitable 26711 26712@example 26713 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26714 ----------------------------------------------- ---------------- 267150000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 267160010: 00 00 00 40 01 00 00 23 00 01 00 00 00 00 00 00 ...@@...#........ 267170020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 267180030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 267190040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 267200050: EA A9 E3 48 A9 7B 48 08 4C 1A 80 EA EA EA 48 AD ...H.@{H.L.....H. 26721@dots{} 267222050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 267232060: 09 80 5E FE C3 C2 CD 38 30 78 A2 FB D8 9A A9 27 ..^....80x.....' 26724@end example 26725 26726 26727 This cart has 16KiB of ROM of which 8KiB is mapped in at both ROML and 26728 ROMH. Bank switching and control register is done through the I/O-1 26729 range: 26730 26731@example 26732 bit meaning 26733 --- ------- 26734 7-4 unused 26735 3 Exrom line control 26736 2 Disable cart 26737 1 Unused 26738 0 Bank 26739@end example 26740 26741@c @node FIXME 26742@subsubsection 36 - Retro Replay 26743 26744@multitable @columnfractions .3 .7 26745@item Size 26746@tab 32KiB, 64KiB or 128KiB (4, 8 or 16 banks of 8KiB) 26747@item EXROM 26748@tab active (lo) (0) 26749@item GAME 26750@tab inactive (hi) (1) 26751@item Load address 26752@tab $8000-$9FFF 26753@end multitable 26754 26755@example 26756 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26757 ----------------------------------------------- ---------------- 267580000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 267590010: 00 00 00 40 01 00 00 24 00 01 00 00 00 00 00 00 ...@@...$........ 267600020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 267610030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 267620040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 267630050: 09 80 0C 80 C3 C2 CD 38 30 4C 7F 81 4C 87 81 4C .......80L..L..L 26764@end example 26765 26766 Note: When the Cartridge Hardware Subtype/Revision (Offset 0x1A in the 26767 CRT Header) is 1, then the image utilizes features only present in the 26768 "Nordic Replay" (see description of Nordic/Atomic Power) 26769 26770 The Retro Replay has three registers: Two write-only ($DE00 & $DE01) 26771 and one read-only register ($DE00 & $DE01 giving the same results). 26772 26773 The register at $DE00 is reset to $00 on a hard reset if not in flash 26774 mode. If in flash mode, it is set to $02 in order to prevent the 26775 computer from starting the normal cartridge. Flash mode is selected 26776 with a jumper. 26777 26778 Register at $DE00: 26779 26780@example 26781 bit meaning 26782 --- ------- 26783 0 Controls the GAME line: A 1 asserts the line, a 0 will deassert 26784 it. 26785 1 Controls the EXROM line: A 0 will assert it, a 1 will deassert 26786 it. 26787 2 Writing a 1 will disable further write accesses to all registers 26788 of the Retro Replay, and set the memory map of the C64 to 26789 standard, as if there is no cartridge installed at all. 26790 3 Controls bank-address 13 for ROM and RAM banking. 26791 4 Controls bank-address 14 for ROM and RAM banking. 26792 5 Switches between ROM and RAM: 0=ROM, 1=RAM 26793 6 Must be written once to "1" after a successful freeze in order to 26794 set the correct memory map and enable bits 0 and 1 of this 26795 register. Otherwise no effect. 26796 7 Controls bank-address 15 for ROM banking. 26797@end example 26798 26799 The register at $DE01 is the extended control register. If not in 26800 Flash mode, bits 1, 2 and 6 can only be written once. If in Flash 26801 mode, the REUcomp bit cannot be set, but the register will not be 26802 disabled by the first write. Bit 5 is always set to 0 if not in Flash 26803 mode. 26804 26805 Register at $DE01: 26806 26807@example 26808 bit meaning 26809 --- ------- 26810 0 Enable clockport connector. 26811 1 AllowBank (1 allows banking of RAM in $DF00/$DE02 area) 26812 2 NoFreeze (1 disables Freeze function) 26813 3 Bank-address 13 for RAM and ROM (mirror of $DE00) 26814 4 Bank-address 14 for RAM and ROM (mirror of $DE00) 26815 5 Bank-address 16 for ROM (only in flash mode) 26816 6 REU compatibility bit. 0=standard memory map, 1 = REU compatible 26817 memory map 26818 7 Bank-address 15 for ROM (mirror of $DE00) 26819@end example 26820 26821 Reading from the registers at either $DE00 or $DE01 will return the 26822 content of the status register. 26823 26824 Status register: 26825 26826@example 26827 bit meaning 26828 --- ------- 26829 0 1=Flashmode active (jumper set) 26830 1 feedback of AllowBank bit 26831 2 1=Freeze button pressed 26832 3 feedback of banking bit 13 26833 4 feedback of banking bit 14 26834 5 feedback of banking bit 16 26835 6 1=REU compatible memory map active 26836 7 feedback of banking bit 15 26837@end example 26838 26839 The following memory maps are available: 26840 26841@itemize @bullet 26842@item standard - 26843 $DE00 and $DE01 registers are active, $DF00-$DFFF contain the last 26844 page of the selected 8KiB bank of either ROM or RAM, whatever is 26845 selected. RAM can only be accessed in $8000-$9FFF. ROM can be mapped 26846 to $8000, $A000 or $E000 with the corresponding status on GAME and 26847 EXROM. 26848 26849 Note: If the AllowBank bit is not set, the $DF00-$DFFF area will 26850 always access bank 0 of the RAM, so the older cartridge images will 26851 work. The AllowBank bit does not have any effect on the ROM mirror in 26852 that area. 26853 26854@item Freeze - 26855 ROM is mapped to $E000-$FFFF, bank 0 is active directly after Freeze. 26856 Writing to bits 0 and 1 of the $DE00 register will have no effect on 26857 GAME and EXROM. RAM can be selected and used in $DF00 or $DE02, 26858 respectively, but not in $8000. Banking bits work, so you have full 26859 read access to the ROM, and access to up to four RAM pages with the 26860 AllowBank bit set (minus 2 bytes if REU compatible bit is set). You 26861 should leave this memory map ASAP by setting bit 6 of $DE00, because 26862 C64 RAM in the $E000 area is not available, and you don't have control 26863 of the GAME and EXROM lines. 26864 26865@item REU compatible - 26866 $DE00 and $DE01 registers are active, $DE02-$DEFF contain a mirror of 26867 $9E02-$9EFF of the selected 8KiB-bank of either ROM or RAM, whatever is 26868 selected. RAM can only be accessed in $8000-$9FFF. ROM can be mapped 26869 to $8000, $A000 or $E000 with the corresponding status on GAME and 26870 EXROM. The $DF00 stays free for use with the 1764 Ram Expansion Unit 26871 (REU). 26872 26873 Note: If the AllowBank bit is not set, the $DE02-$DEFF area will 26874 always access bank 0 of the RAM, so the older cartridge images will 26875 work. The AllowBank bit does not have any effect on the ROM mirror in 26876 that area. 26877@end itemize 26878 26879@c @node FIXME 26880@subsubsection 37 - MMC64 26881 26882@multitable @columnfractions .3 .7 26883@item Size 26884@tab 8KiB (1 bank of 8KiB) 26885@item EXROM 26886@tab active (lo) (0) 26887@item GAME 26888@tab inactive (hi) (1) 26889@item Load address 26890@tab $8000-$9FFF 26891@end multitable 26892 26893@example 26894 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26895 ----------------------------------------------- ---------------- 268960000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 268970010: 00 00 00 40 01 00 00 25 00 01 00 00 00 00 00 00 ...@@...%........ 268980020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 268990030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 269000040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 269010050: 09 80 64 97 C3 C2 CD 38 30 78 D8 A2 FF 9A 20 D4 ..d....80x.... . 26902@end example 26903 26904 26905 The clockport registers of this cart can be switched to either 26906 $DE01-$DE0F or $DF21-$DF2F. The control registers are available at 26907 $DF10-$DF13. 26908 26909 The register at $DE01 / $DF21 is write only: 26910 26911@example 26912 bit meaning 26913 --- ------- 26914 7-1 Unused 26915 0 0 = disable clock port, 1 = enable clockport 26916@end example 26917 26918 The registers at $DE02-$DE0F / $DF22-$DF2F are for the clock port and 26919 are read/write. 26920 26921 The register at $DF10 is the MMC64 SPI transfer register, a byte 26922 written to this registers is sent to the card & response from the card 26923 is read here. 26924 26925 The register at $DF11 is the MMC64 control register: 26926 26927@example 26928 bit meaning 26929 --- ------- 26930 0 0 = MMC64 BIOS active, 1 = external ROM active 26931 1 0 = card selected, 1 = card not selected 26932 2 0 = 250khz transfer, 1 = 8mhz transfer 26933 3 0 = clock port @@ $DE00, 1 = clock port @@ $DF20 26934 4 0 = normal Operation, 1 = flash mode (*) 26935 5 0 = allow external rom when BIOS is disabled, 26936 1 = disable external ROM 26937 6 0 = SPI write trigger mode, 1 = SPI read trigger mode 26938 7 0 = MMC64 is active, 1 = MMC64 is completely disabled (**) 26939@end example 26940 26941 (*) bit can only be programmed when flash jumper is set 26942 (**) bit can only be modified after unlocking 26943 26944 The register at $DF12 is the MMC64 status register, which is 26945 read-only: 26946 26947@example 26948 bit meaning 26949 --- ------- 26950 0 0 = SPI ready, 1 = SPI busy 26951 1 external GAME line 26952 2 external EXROM line 26953 3 0 = card inserted, 1 = no card inserted 26954 4 0 = card write enabled, 1 = card write disabled 26955 5 0 = flash jumper not set, 1 = flash jumper set 26956 6-7 unused 26957@end example 26958 26959 The register at $DF13 is the MMC64 identification register, which when 26960 reading from it can have the following values: 26961 26962 $64 when bit 1 of $DF11 is 0. 26963 $01 when bit 1 of $DF11 is 1 and REV A hardware is used. 26964 $02 when bit 1 of $DF11 is 1 and REV B hardware is used. 26965 26966 when writing to it it can be used to unlock bit 7 of $DF11 or to 26967 re-enable the cart: 26968 26969 Write $55 & $AA into this register to unlock bit 7 of $DF11. 26970 Write $0A & $1C into this register to re-enable MMC64 hardware. 26971 26972@c @node FIXME 26973@subsubsection 38 - MMC Replay 26974 26975@multitable @columnfractions .3 .7 26976@item Size 26977@tab 64KiB or 512KiB (8 or 64 banks of 8KiB) 26978@item EXROM 26979@tab active (lo) (0) 26980@item GAME 26981@tab active (lo) (0) 26982@item Load address 26983@tab $8000-$9FFF 26984@end multitable 26985 26986@example 26987 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 26988 ----------------------------------------------- ---------------- 269890000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 269900010: 00 00 00 40 01 00 00 26 00 00 00 00 00 00 00 00 ...@@...&........ 269910020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 269920030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 269930040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 269940050: 1A 80 6E 9E C3 C2 CD 38 30 4D 4D 43 52 45 50 4C ..n....80MMCREPL 26995@end example 26996 26997 26998 The cart uses the following registers: 26999 27000 $DE00 - RR control register write 27001 27002@example 27003 bit meaning 27004 --- ------- 27005 0 GAME line 27006 1 EXROM line 27007 2 1 = disable RR, bit can be reset by setting bit 6 of $DF12 27008 3 bank address 13 27009 4 bank address 14 27010 5 0 = rom enable, 1 = ram enable 27011 6 1 = exit freeze mode 27012 7 bank address 15 27013@end example 27014 27015 $DE01 - extended RR control register write 27016 27017@example 27018 bit meaning 27019 --- ------- 27020 0 0 = disable clockport, 1 = enable clockport 27021 1 0 = disable I/O RAM banking, 1 = enable I/O RAM banking 27022 2 0 = enable freeze, 1 = disable freeze 27023 3 bank address 13 (mirror of $DE00) 27024 4 bank address 14 (mirror of $DE00) 27025 5 0 = enable MMC registers, 1 = disable MMC registers. Can only be 27026 written when bit 6 of $DF12 is 1. Register becomes effective when 27027 bit 0 of $DF11 is 1. 27028 6 0 = RAM/ROM at $DFxx, 1 = RAM/ROM at $DExx 27029 7 bank address 15 (mirror of $DE00) 27030@end example 27031 27032 $DE02-$DE0F - Clockport memory area (when enabled) 27033 27034 $DF10 - MMC SPI transfer register, a byte written is sent to the card 27035 & response from the card is read here. 27036 27037 $DF11 - MMC control register 27038 27039@example 27040 bit meaning 27041 --- ------- 27042 0 0 = MMC BIOS enabled, 1 = MMC BIOS disabled. Enabling MMC BIOS 27043 sets ROM banking to the last 64KiB bank. 27044 1 0 = card selected, 1 = card not selected. This bit also controls 27045 the green activity LED. 27046 2 0 = 250khz transfer, 1 = 8mhz transfer 27047 3 ALWAYS 0 27048 4 ALWAYS 0 27049 5 (in RR-Mode:) 27050 0 = allow RR rom when MMC BIOS disabled , 1 = disable RR ROM 27051 (in mmcreplay bios mode:) 27052 RAM banking (0 = $E000 - $FFFF, 1 = $8000 - $9FFF) 27053 (in 16KiB mode:) 27054 enable RAM at $A000 - $BFFF 27055 6 0 = SPI write trigger mode, 1 = SPI read trigger mode 27056 7 ALWAYS 0 27057@end example 27058 27059 $DF12 - MMC status register 27060 27061@example 27062 bit meaning 27063 --- ------- 27064 0 0 = SPI ready, 1 = SPI busy (read) 27065 1 = forbid ROM write accesses (write). Setting 27066 this bit will disable writes to ROM until next 27067 reset 27068 1 feedback of $DE00 bit 0 (GAME) 27069 2 feedback of $DE00 bit 1 (EXROM) 27070 3 0 = card inserted, 1 = no card inserted 27071 4 0 = card write enabled, 1 = card write disabled 27072 5 EEPROM DATA line / DDR register. Setting DATA to "1" enables 27073 reading data bit from EEPROM at this position. 27074 6 0 = RR compatibility mode, 1 = Extended mode 27075 Selecting RR compatibility mode limits RAM to 32KiB and disables 27076 writes to extended banking register. Selecting Extended mode 27077 enables full RAM banking and enables Nordic Power mode in RR mode. 27078 7 EEPROM CLK line 27079@end example 27080 27081 27082 $DF13 - Extended banking register 27083 Can only be read/written to when bit 6 of $DF12 is 1 27084 27085@example 27086 bit meaning 27087 --- ------- 27088 0 bank address 16 27089 1 bank address 17 27090 2 bank address 18 27091 3 ALWAYS 0 27092 4 ALWAYS 0 27093 5 16KiB rom mapping 27094 6 1 = enable RR register. Disabling RR register disables ALL 27095 ROM/RAM banking too. 27096 7 ALWAYS 0 27097@end example 27098 27099 NOTE THAT THE MMC REPLAY EMULATION IS CURRENTLY INCOMPLETE AND CONSIDERED 27100 BROKEN. 27101 27102@c @node FIXME 27103@subsubsection 39 - IDE64 27104 27105@multitable @columnfractions .3 .7 27106@item Size 27107@tab 64KiB or 128KiB (4 or 8 banks of 16KiB) 27108@item EXROM 27109@tab active (lo) (0) 27110@item GAME 27111@tab inactive (hi) (1) 27112@item Load address 27113@tab $8000-$BFFF 27114@end multitable 27115 27116@example 27117 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27118 ----------------------------------------------- ---------------- 271190000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 271200010: 00 00 00 40 01 00 00 27 00 01 00 00 00 00 00 00 ...@@...'........ 271210020: 49 44 45 36 34 20 43 41 52 54 52 49 44 47 45 20 IDE64 CARTRIDGE 271220030: 49 44 45 44 4f 53 20 32 30 31 33 31 32 31 32 00 IDEDOS 20131212? 271230040: 43 48 49 50 00 00 40 10 00 02 00 00 80 00 40 00 CHIP..@@.......@@. 271240050: 63 80 5E FE C3 C2 CD 38 30 20 49 44 45 36 34 20 c.^....80 IDE64 27125@end example 27126 27127 The IDE64 cart uses the following registers: 27128 27129@example 27130 $DE20 - $DE2F IDE BUS Registers 27131 $DE30 - Low Data HDD register 27132 $DE31 - High Data HDD register 27133@end example 27134 27135 $DE32 register: 27136 27137@example 27138 bit meaning 27139 --- ------- 27140 7 unused (0) 27141 6 unused (0) 27142 5 unused (0) 27143 4 version number (1) 27144 3 romaddr15 27145 2 romaddr14 27146 1 game 27147 0 exrom 27148@end example 27149 27150@example 27151 $DE32 - $DE35 = IDE64 ROM bank select registers 27152 $DE5F = RTC access (bit 0 only to serial accessed RTC) 27153 $DE60 - $DEFF = ROM used by software 27154 $DEFB = IDE64 clock reset, kill the cartridge 27155 $DEFC - $DEFF = IDE64 memory configuration registers 27156@end example 27157 27158@c @node FIXME 27159@subsubsection 40 - Super Snapshot V4 27160 27161@multitable @columnfractions .3 .7 27162@item Size 27163@tab 32KiB (4 banks of 8KiB) 27164@item EXROM 27165@tab active (lo) (0) 27166@item GAME 27167@tab active (lo) (0) 27168@item Load address 27169@tab $8000-$9FFF 27170@end multitable 27171 27172@example 27173 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27174 ----------------------------------------------- ---------------- 271750000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 271760010: 00 00 00 40 01 00 00 28 00 00 00 00 00 00 00 00 ...@@...(........ 271770020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 271780030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 271790040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 271800050: 80 AD B5 80 C3 C2 CD 38 30 08 48 A9 06 8D 00 DF .......80.H..... 27181@dots{} 271822050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00 CHIP.. ....... . 271832060: 4C FA A0 A9 07 8D 00 DD 2C 00 DD 50 FB 2C 00 DD L.......,..P.,.. 27184@dots{} 271854060: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 271864070: 13 80 BC FE C3 C2 CD 38 30 08 48 A9 02 8D 00 DF .......80.H..... 27187@dots{} 271886070: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00 CHIP.. ....... . 271896080: F0 8A 48 A9 00 85 22 85 23 8D 53 0F 20 0C A1 B0 ..H...".#.S. ... 27190@end example 27191 27192 27193 This cart has 32KiB of ROM and 8KiB of RAM, it uses I/O-1 as a mirror of 27194 the last page of cart RAM. It has the following registers in the I/O-2 27195 range: 27196 27197 ROM config register at $DF00 (can only be written to): 27198 27199@example 27200 bit meaning 27201 --- ------- 27202 0 ? 27203 1 ? (write 1 to release freeze mode) 27204 2 ROM bank select 27205 3 write 1 to disable cartridge 27206 4-6 unused 27207 7 ? 27208@end example 27209 27210 Note: if bit0, bit1, bit7 are all 0, then ultimax mapping is selected 27211 and RAM is enabled at ROML, otherwise if bit 0 is 0, then 16KiB mapping 27212 is enabled, or if bit 0 is 1, then 8KiB mapping is enabled. 27213 27214 RAM config register at $DF01 (read/write): 27215 27216 If written value == last value - 1, then ultimax mapping is selected 27217 and RAM is enabled at ROML, if written value == last value + 1, then 27218 ROM is enabled at ROML and exrom is deasserted (switch to either 8KiB or 27219 16KiB mapping) 27220 27221 $DF02-$DFFF holds the last page of the first 8KiB of the current bank. 27222 27223@c @node FIXME 27224@subsubsection 41 - IEEE-488 27225 27226@multitable @columnfractions .3 .7 27227@item Size 27228@tab 4KiB (1 bank of 4KiB) 27229@item EXROM 27230@tab active (lo) (0) 27231@item GAME 27232@tab inactive (hi) (1) 27233@item Load address 27234@tab $8000-$8FFF 27235@end multitable 27236 27237@example 27238 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27239 ----------------------------------------------- ---------------- 272400000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 272410010: 00 00 00 40 01 00 00 29 00 01 00 00 00 00 00 00 ...@@...)........ 272420020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 272430030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 272440040: 43 48 49 50 00 00 10 10 00 00 00 00 80 00 10 00 CHIP............ 272450050: 09 80 7A 80 C3 C2 CD 38 30 8E 16 D0 20 84 FF 20 ..z....80... .. 27246@end example 27247 27248 27249 The cart uses a TPI for the IEEE488 interface/communication in the 27250 I/O-2 range: 27251 27252@example 27253 $DF00 - Port A Data 27254 $DF01 - Port B Data 27255 $DF02 - Port C Data 27256 $DF03 - Port A Direction 27257 $DF04 - Port B Direction 27258 $DF05 - Port C Direction 27259 $DF06 - Control register 27260 $DF07 - Active Interrupt register 27261@end example 27262 27263@c @node FIXME 27264@subsubsection 42 - Game Killer 27265 27266@multitable @columnfractions .3 .7 27267@item Size 27268@tab 8KiB (1 bank of 8KiB) 27269@item EXROM 27270@tab inactive (hi) (1) 27271@item GAME 27272@tab active (lo) (0) 27273@item Load address 27274@tab $E000-$FFFF 27275@end multitable 27276 27277@example 27278 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27279 ----------------------------------------------- ---------------- 272800000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 272810010: 00 00 00 40 01 00 00 2A 01 00 00 00 00 00 00 00 ...@@...*........ 272820020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 272830030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 272840040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00 CHIP.. ....... . 272850050: 00 25 08 CF 07 9E 32 30 38 38 20 4D 43 2E 43 52 .%....2088 MC.CR 27286@end example 27287 27288 27289 When the cartridge is active, ultimax is enabled when the address 27290 being accessed is is the $E000-$FFFF range, so the ROM is visible at 27291 $E000, below is normal C64 RAM. The cart can be disabled by writing to 27292 either I/O-1 or I/O-2 range. When the freezer button is pressed, the 27293 cartridge will be enabled and an NMI will be triggered. 27294 27295@c @node FIXME 27296@subsubsection 43 - Prophet64 27297 27298@multitable @columnfractions .3 .7 27299@item Size 27300@tab 256KiB (32 banks of 8KiB) 27301@item EXROM 27302@tab active (lo) (0) 27303@item GAME 27304@tab inactive (hi) (1) 27305@item Load address 27306@tab $8000-$9FFF 27307@end multitable 27308 27309@example 27310 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27311 ----------------------------------------------- ---------------- 273120000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 273130010: 00 00 00 40 01 00 00 2B 00 01 00 00 00 00 00 00 ...@@...+........ 273140020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 273150030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 273160040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 273170050: 09 80 09 80 C3 C2 CD 38 30 78 A0 00 84 F8 84 FA .......80x...... 27318@end example 27319 27320 27321 The control register is the I/O-2 range: 27322 27323@example 27324 bit meaning 27325 --- ------- 27326 7-6 unused 27327 5 disable cart 27328 4-0 bank select 27329@end example 27330 27331@c @node FIXME 27332@subsubsection 44 - EXOS 27333 27334@multitable @columnfractions .3 .7 27335@item Size 27336@tab 8KiB (1 bank of 8KiB) 27337@item EXROM 27338@tab inactive (hi) (1) 27339@item GAME 27340@tab active (lo) (0) 27341@item Load address 27342@tab $E000-$FFFF 27343@end multitable 27344 27345@example 27346 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27347 ----------------------------------------------- ---------------- 273480000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 273490010: 00 00 00 40 01 00 00 2C 01 00 00 00 00 00 00 00 ...@@...,........ 273500020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 273510030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 273520040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00 CHIP.. ....... . 273530050: 85 56 20 0F BC A5 61 C9 88 90 03 20 D4 BA 20 CC .V ...a.... .. . 27354@end example 27355 27356 27357 This cart has 8KiB of ROM, mapped in at $E000-$FFFF only when hirom is 27358 selected. The cart uses a clip that needs to be installed inside the 27359 C64. 27360 27361@c @node FIXME 27362@subsubsection 45 - Freeze Frame 27363 27364@multitable @columnfractions .3 .7 27365@item Size 27366@tab 8KiB (1 bank of 8KiB) 27367@item EXROM 27368@tab active (lo) (0) 27369@item GAME 27370@tab inactive (hi) (1) 27371@item Load address 27372@tab $8000-$9FFF 27373@end multitable 27374 27375@example 27376 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27377 ----------------------------------------------- ---------------- 273780000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 273790010: 00 00 00 40 01 00 00 2D 00 01 00 00 00 00 00 00 ...@@...-........ 273800020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 273810030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 273820040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 273830050: 10 80 10 80 C3 C2 CD 38 30 20 00 00 00 00 00 00 .......80 ...... 27384@end example 27385 27386 27387 When reading from the I/O-1 range the cart is enabled, when reading 27388 from the I/O-2 range the cart is disabled. When the freeze button is 27389 pressed the ROM is mapped to both $8000-$9FFF and $E000-$FFFF. 27390 27391@c @node FIXME 27392@subsubsection 46 - Freeze Machine 27393 27394@multitable @columnfractions .3 .7 27395@item Size 27396@tab 16KiB or 32KiB (2 or 4 banks of 8KiB) 27397@item EXROM 27398@tab active (lo) (0) 27399@item GAME 27400@tab inactive (hi) (1) 27401@item Load address 27402@tab $8000-$9FFF 27403@end multitable 27404 27405@example 27406 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27407 ----------------------------------------------- ---------------- 274080000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 274090010: 00 00 00 40 01 00 00 2E 00 01 00 00 00 00 00 00 ...@@............ 274100020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 274110030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 274120040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 274130050: 3A 83 60 80 C3 C2 CD 38 30 20 00 00 40 00 00 00 :.`....80 ..@@... 27414@dots{} 274152050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00 CHIP.. ....... . 274162060: 78 A9 34 85 01 A0 00 B1 F8 91 F6 E6 F8 D0 02 E6 x.4............. 27417@dots{} 274184060: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 274194070: 3A 83 60 80 C3 C2 CD 38 30 20 00 00 40 00 00 00 :.`....80 ..@@... 27420@dots{} 274216070: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00 CHIP.. ....... . 274226080: 78 A9 34 85 01 A0 00 B1 F8 91 F6 E6 F8 D0 02 E6 x.4............. 27423@end example 27424 27425 27426 Warning, the following information is based on guess-work and might be 27427 incorrect, any further information and/or corrections are appreciated. 27428 27429 When reading from the I/O-1 range ROM bank 0(/2) is mapped to 27430 $8000-$9FFF and ROM bank 1(/3) is mapped to $A000-$BFFF. When reading 27431 from the I/O-2 range the cart is disabled. When a reset happens the 27432 ROM banks get switched and ROM bank 0(/2) is mapped to $8000-$9FFF. 27433 When a freeze happens ROM bank 0(/2) is mapped to both $8000-$9FFF and 27434 $E000-$FFFF. 27435 27436 27437@c @node FIXME 27438@subsubsection 47 - Snapshot 64 27439 27440@multitable @columnfractions .3 .7 27441@item Size 27442@tab 4KiB (1 bank of 4KiB) 27443@item EXROM 27444@tab inactive (hi) (1) 27445@item GAME 27446@tab inactive (hi) (1) 27447@item Load address 27448@tab $E000-$EFFF 27449@end multitable 27450 27451@example 27452 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27453 ----------------------------------------------- ---------------- 274540000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 274550010: 00 00 00 40 01 00 00 2F 00 00 00 00 00 00 00 00 ...@@.../........ 274560020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 274570030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 274580040: 43 48 49 50 00 00 10 10 00 00 00 00 E0 00 10 00 CHIP............ 274590050: 78 D8 48 8A 48 98 48 AC 0D DD 10 03 4C EE F2 AD x.H.H.H.....L... 27460@end example 27461 27462 27463 Warning, the following information is based on guess-work and might be 27464 incorrect, any further information and/or corrections are appreciated. 27465 27466 The cart has a control bit (bit 0) in the I/O-2 range which is used to 27467 disable or enable the cart. 27468 27469 27470@c @node FIXME 27471@subsubsection 48 - Super Explode V5.0 27472 27473@multitable @columnfractions .3 .7 27474@item Size 27475@tab 16KiB (2 banks of 8KiB) 27476@item EXROM 27477@tab active (lo) (0) 27478@item GAME 27479@tab inactive (hi) (1) 27480@item Load address 27481@tab $8000-$9FFF 27482@end multitable 27483 27484@example 27485 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27486 ----------------------------------------------- ---------------- 274870000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 274880010: 00 00 00 40 01 00 00 30 00 01 00 00 00 00 00 00 ...@@...0........ 274890020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 274900030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 274910040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 274920050: D7 86 5E FE C3 C2 CD 38 30 A9 00 2C A9 FF 85 FE ..^....80..,.... 27493@dots{} 274942050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 274952060: E8 96 5E FE C3 C2 CD 38 30 20 6C 81 A9 09 8D 99 ..^....80 l..... 27496@end example 27497 27498 27499 Warning, the following information is based on guess-work and might be 27500 incorrect, any further information and/or corrections are appreciated. 27501 27502 The cart has 16KiB of ROM which are used as two banks of 8KiB, they are 27503 mapped into $8000-$9FFF and the last page of the current ROM bank is 27504 mirrored in $DF00-$DFFF. The cart has a control bit (bit 7) at $DF00, 27505 which is used to select what ROM bank is used. 27506 27507 27508@c @node FIXME 27509@subsubsection 49 - Magic Voice 27510 27511@multitable @columnfractions .3 .7 27512@item Size 27513@tab 16KiB (2 banks of 8KiB) 27514@item EXROM 27515@tab inactive (hi) (1) 27516@item GAME 27517@tab active (lo) (0) 27518@item Load address 27519@tab $8000-$9FFF (bank 1), 27520 $A000-$BFFF (bank 2) 27521@end multitable 27522 27523@example 27524 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27525 ----------------------------------------------- ---------------- 275260000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 275270010: 00 00 00 40 01 00 00 31 01 00 00 00 00 00 00 00 ...@@...1........ 275280020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 275290030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 275300040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 275310050: EA 2C 80 DF 50 FB A0 00 8C 80 DF B9 E3 A3 29 0F .,..P.........). 27532@dots{} 275332050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00 CHIP.. ....... . 275342060: 4A EB C0 49 6A EA BB FB 4E CA 43 1E 75 63 15 97 J..Ij...N.C.uc.. 27535@end example 27536 27537 27538 This cart has 16KiB of ROM, mapped in at reset at $8000-$BFFF. The cart 27539 is controled through a TPI at $DF80-$DF87: 27540 27541@example 27542 $DF80 - Port A Data 27543 $DF81 - Port B Data 27544 $DF82 - Port C Data 27545 $DF83 - Port A Direction 27546 $DF84 - Port B Direction 27547 $DF85 - Port C Direction 27548 $DF86 - Control register 27549 $DF87 - Active Interrupt register 27550@end example 27551 27552 The cart has a pass-through port and does the following at start-up: 27553 27554@itemize @bullet 27555@item Program starts after reset at $FFD3, and copies code from 27556 $FF36-$FFD2 to $0200-$029C (157 bytes) 27557 27558@item Program continues at $021A, copies $A000-$BFFF from EPROM to RAM at 27559 $A000-$BFFF (8KiB), copies $E000-$FFFF from EPROM to RAM at 27560 $E000-$FFFF (8KiB), copies $AE62-$B461 from RAM to RAM at $C000-$C5FF 27561 (Magic Voice Code) 27562 27563@item Jump to beginning of Magic Voice code at $C000 27564@end itemize 27565 27566@c @node FIXME 27567@subsubsection 50 - Action Replay 2 27568 27569@multitable @columnfractions .3 .7 27570@item Size 27571@tab 16KiB (2 banks of 8KiB) 27572@item EXROM 27573@tab active (lo) (0) 27574@item GAME 27575@tab inactive (hi) (1) 27576@item Startup mode 27577@tab 8KiB Game 27578@item Load address 27579@tab $8000-$9FFF 27580@end multitable 27581 27582@example 27583 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27584 ----------------------------------------------- ---------------- 275850000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 275860010: 00 00 00 40 01 00 00 32 00 01 00 00 00 00 00 00 ...@@...2........ 275870020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 275880030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 275890040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 275900050: EA EA 68 AA 68 85 94 68 85 95 68 85 96 68 85 97 ..h.h..h..h..h.. 27591@dots{} 275922050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 275932060: 30 80 5E FE C3 C2 CD 38 30 20 04 90 4C 38 DF 1A 0.^....80 ..L8.. 27594@end example 27595 27596 27597 Warning, the following information is based on guess-work and might be 27598 incorrect, any further information and/or corrections are appreciated. 27599 27600 I/O-1 is somehow used to enable the cart, the exact way in which this 27601 is done is unknown. Reading from the I/O-2 range will give you the 27602 last page of the current ROM bank, and writing to it will disable the 27603 cart. 27604 27605@c @node FIXME 27606@subsubsection 51 - MACH 5 27607 27608@multitable @columnfractions .3 .7 27609@item Size 27610@tab 4KiB or 8KiB (1 bank of 4KiB or 8KiB) 27611@item EXROM 27612@tab active (lo) (0) 27613@item GAME 27614@tab inactive (hi) (1) 27615@item Startup mode 27616@tab 8KiB Game 27617@item Load address 27618@tab $8000-$8FFF (4KiB), 27619 $8000-$9FFF (8KiB) 27620@end multitable 27621 27622@example 27623 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27624 ----------------------------------------------- ---------------- 276250000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 276260010: 00 00 00 40 01 00 00 33 00 01 00 00 00 00 00 00 ...@@...3........ 276270020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 276280030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 276290040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 276300050: AF 83 5E FE C3 C2 CD 38 30 4D 41 43 48 35 A5 93 ..^....80MACH5.. 27631@end example 27632 27633 27634 This cart has 8KiB ROM mapped at $8000-$9FFF, the $9E00-$9EFF range is 27635 mirrored at $DE00-$DEFF and the $9F00-$9FFF range is mirrored at 27636 $DF00-$DFFF. 27637 27638 27639@c @node FIXME 27640@subsubsection 52 - Diashow maker 27641 27642@multitable @columnfractions .3 .7 27643@item Size 27644@tab 8KiB (1 bank of 8KiB) 27645@item EXROM 27646@tab active (lo) (0) 27647@item GAME 27648@tab inactive (hi) (1) 27649@item Startup mode 27650@tab 8KiB Game 27651@item Load address 27652@tab $8000-$9FFF 27653@end multitable 27654 27655@example 27656 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27657 ----------------------------------------------- ---------------- 276580000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 276590010: 00 00 00 40 01 00 00 34 00 01 00 00 00 00 00 00 ...@@...4........ 276600020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 276610030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 276620040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 276630050: 09 80 09 80 C3 C2 CD 38 30 AD 11 D0 29 10 D0 62 .......80...)..b 27664@end example 27665 27666 27667 Accessing I/O-1 (the software uses $DE00 only it seems) disables 27668 cartridge ROM. A reset enables 8KiB game mode and the ROM bank is mapped 27669 to $8000. A freeze causes ROM to be mapped to $8000. 27670 27671 27672@c @node FIXME 27673@subsubsection 53 - Pagefox 27674 27675@multitable @columnfractions .3 .7 27676@item Size 27677@tab 64KiB (4 banks of 16KiB) 27678@item EXROM 27679@tab active (lo) (0) 27680@item GAME 27681@tab active (lo) (0) 27682@item Startup mode 27683@tab 16KiB Game 27684@item Load address 27685@tab $8000-$BFFF 27686@end multitable 27687 27688@example 27689 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27690 ----------------------------------------------- ---------------- 276910000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 276920010: 00 00 00 40 01 00 00 35 00 00 00 00 00 00 00 00 ...@@...5........ 276930020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 276940030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 276950040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 276960050: 31 80 BB 0E C3 C2 CD 38 30 50 46 20 56 31 2E 30 1......80PF V1.0 27697@dots{} 276984050: 43 48 49 50 00 00 40 10 00 00 00 01 80 00 40 00 CHIP..@@.......@@. 276994060: A2 FE 9A 20 EC AE 20 82 80 20 74 86 20 A5 8B 4C ... .. .. t. ..L 27700@dots{} 277018060: 43 48 49 50 00 00 40 10 00 00 00 02 80 00 40 00 CHIP..@@.......@@. 277028070: 5A 01 02 03 04 06 0A 0B 10 14 1E 28 3C 00 00 00 Z..........(<... 27703@dots{} 27704C070: 43 48 49 50 00 00 40 10 00 00 00 03 80 00 40 00 CHIP..@@.......@@. 27705C080: 1E 03 14 82 09 05 09 0F 0C 0D 0F 05 09 09 0B 0A ................ 27706@end example 27707 27708 27709 This cart has 64KiB ROM (2 32KiB Eproms, mapped to $8000 and $A000 in 27710 16KiB Game Mode), and 32KiB RAM (mapped to $8000 and $A000 in 16KiB Game 27711 Mode). The cart has 1 (write-only) bank control register which is 27712 located at $DE80 and mirrored throughout the $DE80-$DEFF range: 27713 27714@example 27715 Bit 0: unused/don't care 27716 Bit 1: Bank select: 0=upper, 1=lower (not correct ?!) 27717 Bit 2: chip select 0 27718 Bit 3: chip select 1 27719 Bit 4: cartridge enable/disable: 0=enable, 1=disable 27720 Bits 5-7: unused/don't care 27721@end example 27722 27723 Chip select combinations of 0/1 are: 27724@example 27725 00: Eprom "79" 27726 01: Eprom "ZS3" 27727 10: Ram 27728 11: empty space (reading returns VIC-II data) 27729@end example 27730 27731 note: on the original hardware "disabling" the cartridge by setting 27732 bit 4 of the control register does NOT prevent write accesses to 27733 the cartridge RAM!. So to actually disable the RAM, it is 27734 suggested to write $FF to the register. 27735 27736@c @node FIXME 27737@subsubsection 54 - Kingsoft 27738 27739@multitable @columnfractions .3 .7 27740@item Size 27741@tab 24KiB (3 banks of 8KiB) 27742@item EXROM 27743@tab active (lo) (0) 27744@item GAME 27745@tab active (lo) (0) 27746@item Startup mode 27747@tab 16KiB Game 27748@item Load address 27749@tab $8000-$9FFF 27750@end multitable 27751 27752@example 27753 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27754 ----------------------------------------------- ---------------- 277550000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 277560010: 00 00 00 40 01 00 00 36 00 00 00 00 00 00 00 00 ...@@...6........ 277570020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 277580030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 277590040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 277600050: 09 80 A2 89 C3 C2 CD 38 30 20 D3 83 78 8D 00 DE .......80 ..x... 27761@dots{} 277622050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 277632060: 72 A2 05 A5 45 10 01 CA A5 46 10 02 CA CA 86 28 r...E....F.....( 27764@dots{} 277654060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 277664070: 78 A2 FF 9A D8 A9 08 8D 16 D0 A0 00 98 99 02 00 x............... 27767@end example 27768 27769 This cart has 24KiB ROM (3 8KiB Eproms) 27770 27771@example 27772 reading io1: 27773 - switches to 16KiB game mode 27774 - first eprom mapped to 8000 (ROML) 27775 - second eprom mapped to A000 (ROMH) 27776 27777 writing io1: 27778 - switches to ultimax mode _only_: 27779 - if 0xc000 > address >= 0x8000 27780 - if address >= 0xe000 27781 (meaning 0x0000-0x7fff and 0xc000-0xdfff gives normal c64 ram/io) 27782 - first eprom mapped to 8000 (ROML) 27783 - third eprom mapped to e000 (ROMH) 27784@end example 27785 27786@c @node FIXME 27787@subsubsection 55 - Silverrock 128 27788 27789@multitable @columnfractions .3 .7 27790@item Size 27791@tab 128KiB (16 banks of 8KiB) 27792@item EXROM 27793@tab active (lo) (0) 27794@item GAME 27795@tab inactive (hi) (1) 27796@item Startup mode 27797@tab 8KiB Game 27798@item Load address 27799@tab $8000-$9FFF 27800@end multitable 27801 27802@example 27803 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27804 ----------------------------------------------- ---------------- 2780500000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 2780600010: 00 00 00 40 01 00 00 37 00 01 00 00 00 00 00 00 ...@@...7........ 2780700020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 2780800030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 2780900040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 2781000050: 09 80 09 80 C3 C2 CD 38 30 78 A2 FF 9A D8 A9 00 .......80x...... 27811@dots{} 2781202050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 2781302060: 00 21 1D A9 90 1B 67 70 FD B0 04 C3 19 B9 11 2D .!....gp.......- 27814@dots{} 2781504060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 2781604070: 00 41 62 92 AD 71 32 87 08 20 BE 90 4C 36 8F 20 .Ab..q2.. ..L6. 27817@dots{} 2781806070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 2781906080: 00 61 00 02 02 03 0D 40 82 15 D0 A1 08 40 84 00 .a.....@@.....@@.. 27820@dots{} 2782108080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00 CHIP.. ....... . 2782208090: 00 81 8A 85 0D F0 8A 28 83 F8 8A 00 8B 58 83 60 .......(.....X.` 27823@dots{} 278240A090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00 CHIP.. ....... . 278250A0A0: 00 A1 C2 E3 C4 86 32 14 00 C5 40 EA 13 CA CB CC ......2...@@..... 27826@dots{} 278270C0A0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00 CHIP.. ....... . 278280C0B0: 00 C1 81 59 60 00 81 5D D9 58 5E EE 58 6E 3C 28 ...Y`..].X^.Xn<( 27829@dots{} 278300E0B0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00 CHIP.. ....... . 278310E0C0: 00 E1 0F BF 3D 56 00 7E 52 FD 50 03 AA 00 0D 40 ....=V.~R.P....@@ 27832@dots{} 27833100C0: 43 48 49 50 00 00 20 10 00 00 00 08 80 00 20 00 CHIP.. ....... . 27834100D0: 01 01 B9 D1 0D 15 89 55 65 45 41 C5 01 45 45 A8 .......UeEA..EE. 27835@dots{} 27836120D0: 43 48 49 50 00 00 20 10 00 00 00 09 80 00 20 00 CHIP.. ....... . 27837120E0: 01 21 0C C7 29 54 41 29 4D C5 06 24 C7 24 8F 81 .!..)TA)M..$.$.. 27838@dots{} 27839140E0: 43 48 49 50 00 00 20 10 00 00 00 0A 80 00 20 00 CHIP.. ....... . 27840140F0: 01 41 EA 87 7A AF 95 67 BD F7 00 7D 6E C4 5D A6 .A..z..g...@}n.]. 27841@dots{} 27842160F0: 43 48 49 50 00 00 20 10 00 00 00 0B 80 00 20 00 CHIP.. ....... . 2784316100: 01 61 6A 92 6B 93 6B 94 6C 95 6D 96 6E 97 6E 98 .aj.k.k.l.m.n.n. 27844@dots{} 2784518100: 43 48 49 50 00 00 20 10 00 00 00 0C 80 00 20 00 CHIP.. ....... . 2784618110: 01 81 0E 83 0D 0B 0F 81 FF 28 28 1E E3 0A 14 62 .........((....b 27847@dots{} 278481A110: 43 48 49 50 00 00 20 10 00 00 00 0D 80 00 20 00 CHIP.. ....... . 278491A120: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 27850@dots{} 278511C120: 43 48 49 50 00 00 20 10 00 00 00 0E 80 00 20 00 CHIP.. ....... . 278521C130: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 27853@dots{} 278541E130: 43 48 49 50 00 00 20 10 00 00 00 0F 80 00 20 00 CHIP.. ....... . 278551E140: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 27856@end example 27857 27858Cartridge hardware is designed around a 128KiB ROM (PROM or Mask ROM) which is 27859divided into 16 banks each of 8KiB. When adressing the onboard bank-switching logic 27860the requested ROM bank is mapped at address range $8000-$9fff (8KiB) 27861 27862The cartridge PCB layout was cost-optimized for mass-production purposes. 27863 27864The address-/data-lines and bank-switching logic uses the closest address-/data-lines 27865with shortest and most direct path/distance in order to avoid too much PCB re-routing 27866and keep production costs as low as possible. 27867 27868This means that the respective address-/data-lines from the cartridge port 27869may not necessarily connect with the corresponding address-/data-line of 27870the ROM according to the official specs of the ROM. 27871 27872This has over the years given some headaches and invalid dumps when cartridge 27873dumpers that wanted to dump the cartridge contents by de-soldering the ROM and 27874dumping it using an EPROM programmer/reader. 27875 27876The image extracted from such an operation would need transformation according 27877to the actual cartridge PCB re-routing of address-/data-lines. Alternatively 27878one can make an adapter that implements this applied re-routing of the 27879address-/data-lines. 27880 27881This mass-production cost optimization also results in an obscured bank-switching 27882address pattern/values more info on that later. 27883 27884[HWrev1]: The original "Hugo" PCB [HWrev1] is labeled "HUGO Copyright 1990" 27885on both sides of the PCB. 27886PCB production date is stamped on the back og PCB in the format: "YYMM" 278871Mib 27C010 EPROM or PROM (typical Atmel) 27888"Hugo" PCB [HWrev1] contains the following discrete logic IC components: 2788974LS00N (DIP) and 74LS237N (DIP) 27890DIP pitch (pin spacing) 2.54mm (0.1 inch) 27891Assembly/production facilities: Philips, Strandlodsvej (Amager), Copenhagen, Denmark 27892 27893[HWrev1] Bank-switching pattern: 27894In order for the rom contents to appear as a continuous memory layout the following 27895ROM bank-switching pattern must be applied by writing to adress 0xDE00: 27896Cartridge bank-switching values: 00 80 10 90 20 a0 30 b0 40 c0 50 d0 60 e0 70 f0 27897Writing the bank-switch value to any address in address-range 0xDE00-0xDEFF 27898will work. 27899 27900[HWrev2]: Revised PCB [HWrev2] for SMD mount is labeled "SO-A4-1" 27901on both sides of PCB. 279021Mib Mask ROM (SOIC-32) 27903PCB contains the following discrete logic SMD IC components: 2790474HCT02T (SOIC-14) and 74HCT174T (SOIC-16) 27905SOIC (pitch) pin spacing 1.27mm (SMD mounted) 27906Assembly/production facilities: Sono Press, Germany. 27907 27908[HWrev2] Uses alternative bank-switching pattern: 27909Writing *ANY* value to address 0xDE0y (offset y) will select ROM bank y 27910Cartridge still has 16 banks and the lower four bits in the address selects 27911the right bank. Hence the valid address range is 0xDE00-0xDE0F 27912 27913@c @node FIXME 27914@subsubsection 56 - Formel 64 27915 27916@multitable @columnfractions .3 .7 27917@item Size 27918@tab 32KiB (4 banks of 8KiB) 27919@item EXROM 27920@tab inactive (hi) (1) 27921@item GAME 27922@tab active (lo) (0) 27923@item Startup mode 27924@tab Ultimax 27925@item Load address 27926@tab $E000-$FFFF 27927@end multitable 27928 27929@example 27930 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 27931 ----------------------------------------------- ---------------- 279320000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 279330010: 00 00 00 40 01 00 00 38 00 00 00 00 00 00 00 00 ...@@...8........ 279340020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 279350030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 279360040: 43 48 49 50 00 00 20 10 00 00 00 00 E0 00 20 00 CHIP.. ....... . 279370050: 48 A9 FC 0C A9 FE 8D C2 DF 68 48 C9 8C F0 1C C9 H........hH..... 27938@dots{} 279392050: 43 48 49 50 00 00 20 10 00 00 00 01 E0 00 20 00 CHIP.. ....... . 279402060: EA EA 58 48 A9 FC 8D C2 DF 4C 6E E2 EA EA A9 FA ..XH.....Ln..... 27941@dots{} 279424060: 43 48 49 50 00 00 20 10 00 00 00 02 E0 00 20 00 CHIP.. ....... . 279434070: 4C 86 E4 A9 FE 78 8D C2 DF 60 78 8C C3 DF A9 FA L....x...`x..... 27944@dots{} 279456070: 43 48 49 50 00 00 20 10 00 00 00 03 E0 00 20 00 CHIP.. ....... . 279466080: EA EA 48 58 A9 FC 8D C2 DF 68 48 C9 46 D0 7E 68 ..HX.....hH.F.~h 27947@end example 27948 27949the following is a quick overview of how the cartridge works, as its a bit 27950unusual and different from most other cartridges: 27951 27952@example 27953- 27256 EPROM (32KiB) 27954- 7430 TTL 27955- MC6821 27956- 1 button (reset) 27957 27958rom bank 0x00 - 0x03 (0x04) 8192* 4 32KiB mapped to e000 27959MC6821 registers mapped to io2 at dfc0..dfc4 27960 27961- press reset and hold delete to get the main menu 27962- press reset and hold control to skip cbm80 check 27963 (dont start additional cartridge) 27964 27965- press RESTORE, then... 27966 - left arrow, return show disk directory 27967 - delete, 1 load"*" from disk, run 27968 - f1/f2 ? (disk stuff?) 27969 - f3/f4 ? (disk stuff?) 27970 - f5/f6, q enter monitor 27971 - f7/f8, 2 show drive error channel 27972 - control, cursor back to basic 27973 27974 - type "help" in basic to get a list of available commands 27975 27976*** MC6821 Port usage 27977 27978Port A (parallel cable to floppy drive): 27979dfc0 port a ddr 27980dfc1 port a (in/out) 27981 27982Port B (controls banking) 27983dfc2 port b ddr ($7f) 27984dfc3 port b (out) 27985 27986bit3 1 = rom at $e000 enabled, 0 = cartridge disabled 27987bit1-2 rom bank number 27988bit0 ? 27989@end example 27990 27991@c @node FIXME 27992@subsubsection 57 - RGCD 27993 27994@multitable @columnfractions .3 .7 27995@item Size 27996@tab 64KiB (8 banks of 8KiB) 27997@item EXROM 27998@tab active (lo) (0) 27999@item GAME 28000@tab inactive (hi) (1) 28001@item Startup mode 28002@tab 8KiB Game 28003@item Load address 28004@tab $8000-$9FFF 28005@end multitable 28006 28007@example 28008 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28009 ----------------------------------------------- ---------------- 280100000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 280110010: 00 00 00 40 01 00 00 39 00 01 00 00 00 00 00 00 ...@@...9........ 280120020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 280130030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 280140040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 280150050: 0C 80 0C 80 C3 C2 CD 38 30 31 30 34 8E 16 D0 20 .......80104... 28016@dots{} 280172050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 280182060: B9 0A 72 AB 0B F0 08 C9 2F 0C 10 27 E8 EF 5A C5 ..r...../..'..Z. 28019@dots{} 280204060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 280214070: C0 B4 6C A6 6A 0A 14 5E 65 AD 94 02 86 C8 30 1F ..l.j..^e.....0. 28022@dots{} 280236070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 280246080: A4 89 C6 3A C4 60 F0 10 4D F5 89 F0 13 6C E0 78 ...:.`..M....l.x 28025@dots{} 280268080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00 CHIP.. ....... . 280278090: 00 0B 08 14 00 9E 32 30 36 31 00 00 00 A0 35 BA ......2061....5. 28028@dots{} 28029A090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00 CHIP.. ....... . 28030A0A0: 1B 4A 00 53 90 77 8E 1A 1D 94 00 A6 E2 50 29 11 .J.S.w.......P). 28031@dots{} 28032C0A0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00 CHIP.. ....... . 28033C0B0: 14 F7 2E 1A 34 B4 60 53 07 88 C4 F0 21 F6 88 20 ....4.`S....!.. 28034@dots{} 28035E0B0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00 CHIP.. ....... . 28036E0C0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 28037@end example 28038 28039 This cartridge type is very similar to the Magic Desk cart type: ROM memory 28040 is organized in 8KiB ($2000) banks located at $8000-$9FFF. Bank 28041 switching is done by writing the bank number to $DE00. 28042 28043@example 28044 bit 0-2 bank number 28045 bit 3 exrom latch (1 = cart disabled until reset or powercycle) 28046@end example 28047 28048@c @node FIXME 28049@subsubsection 58 - RR-Net MK3 28050 28051@multitable @columnfractions .3 .7 28052@item Size 28053@tab 8KiB 28054@item EXROM 28055@tab active (lo) (0) 28056@item GAME 28057@tab inactive (hi) (1) 28058@item Startup mode 28059@tab 8KiB Game 28060@item Load address 28061@tab $8000-$9FFF 28062@end multitable 28063 28064@example 28065 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28066 ----------------------------------------------- ---------------- 280670000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 280680010: 00 00 00 40 01 00 00 3A 00 01 00 00 00 00 00 00 ...@@...:........ 280690020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 280700030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 280710040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 280720050: 09 80 09 80 C3 C2 CD 38 30 78 A2 FF 9A D8 8E 16 .......80x...... 28073@end example 28074 28075 This cartridge has a CS8900a based RR-Net compatible network interface, and 28076 on 8KiB ($2000) bank ROM located at $8000-$9FFF. The ROM can be switched 28077 on/off by writing to the IO1 space: 28078 28079@example 28080 a write to $de80 enables the ROM 28081 a write to $de88 disables the ROM 28082@end example 28083 28084@c @node FIXME 28085@subsubsection 59 - EasyCalc 28086 28087@multitable @columnfractions .3 .7 28088@item Size 28089@tab 24KiB (3 banks of 8KiB) 28090@item EXROM 28091@tab active (lo) (0) 28092@item GAME 28093@tab active (lo) (0) 28094@item Startup mode 28095@tab 16KiB Game 28096@item Load address 28097@tab $8000-$9FFF (bank 1), 28098 $A000-$BFFF (banks 2/3) 28099@end multitable 28100 28101@example 28102 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28103 ----------------------------------------------- ---------------- 281040000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 281050010: 00 00 00 40 01 00 00 3B 00 00 00 00 00 00 00 00 ...@@...;........ 281060020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 281070030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 281080040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 281090050: 59 89 BC FE C3 C2 CD 38 30 0B 80 B1 84 48 E6 84 Y......80....H.. 28110@dots{} 281112050: 43 48 49 50 00 00 20 10 00 00 00 00 A0 00 20 00 CHIP.. ....... . 281122060: 04 0B 20 52 45 50 4C 49 43 41 54 45 20 FB 89 0F .. REPLICATE ... 28113@dots{} 281144060: 43 48 49 50 00 00 20 10 00 00 00 01 A0 00 20 00 CHIP.. ....... . 281154070: 02 10 B5 00 C9 E3 D0 01 C8 C9 E2 D0 01 C8 C9 E0 ................ 28116@end example 28117 28118This cart uses 8KiB mapped in at $8000-$9FFF and 2 banks of 8KiB mapped in at $A000-$BFFF. 28119 28120The bank at $A000-$BFFF is selected by bit 0 of the address of a write access to I/O-1. 28121 28122@example 28123 A0 | bank 28124 --------- 28125 0 | 0 28126 1 | 1 28127@end example 28128 28129@c @node FIXME 28130@subsubsection 60 - GMod2 28131 28132@multitable @columnfractions .3 .7 28133@item Size 28134@tab 512KiB (64 banks of 8KiB) 28135@item EXROM 28136@tab active (lo) (0) 28137@item GAME 28138@tab inactive (hi) (1) 28139@item Startup mode 28140@tab 8KiB Game 28141@item Load address 28142@tab $8000-$9FFF 28143@end multitable 28144 28145@example 28146 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28147 ----------------------------------------------- ---------------- 2814800000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 2814900010: 00 00 00 40 01 00 00 3C 00 01 00 00 00 00 00 00 ...@@...<........ 2815000020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 2815100030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 2815200040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 2815300050: 09 80 09 80 C3 C2 CD 38 30 78 8E 16 D0 20 A3 FD .......80x... .. 28154@dots{} 2815502050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 2815602060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 28157@dots{} 281587E430: 43 48 49 50 00 00 20 10 00 00 00 3F 80 00 20 00 CHIP.. ....?.. . 281597E440: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 28160@end example 28161 28162GMod2 (Individual Computers) 28163 28164This cart uses 512KiB Flash ROM (29F040) in 64 banks, mapped in at $8000-$9fff 28165and has a 2KiB serial EEPROM (m93C86). 28166 28167@example 28168 io1 28169 - register at de00 28170 28171 bit7 (rw) write enable (write 1), EEPROM data output (read) 28172 bit6 (ro) EXROM (0=active) and EEPROM chip select (1=selected) 28173 bit5-0 (ro) rom bank bit5 EEPROM clock bit4 EEPROM data input 28174 28175 see http://wiki.icomp.de/wiki/GMod2 28176@end example 28177 28178@c @node FIXME 28179@subsubsection 61 - MAX Basic 28180 28181@multitable @columnfractions .3 .7 28182@item Size 28183@tab 16KiB (ULTIMAX mode) 28184@item EXROM 28185@tab inactive (hi) (1) 28186@item GAME 28187@tab active (lo) (0) 28188@item Load address 28189@tab $8000-$9FFF (bank 1), 28190 $E000-$FFFF (bank 2) 28191@end multitable 28192 28193@example 28194 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28195 ----------------------------------------------- ---------------- 281960000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 281970010: 00 00 00 40 01 00 00 3D 01 00 00 00 00 00 00 00 ...@@...=........ 281980020: 4D 41 58 20 42 41 53 49 43 00 00 00 00 00 00 00 MAX BASIC....... 281990030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 282000040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 282010050: 94 E3 7B E3 43 42 4D 42 41 53 49 43 30 88 41 87 ....CBMBASIC0.A. 28202@end example 28203 28204This cartridge uses two 8KiB ROMs that contain BASIC and KERNAL for the MAX Machine. 28205It also provides additional 2KiB RAM which will be mapped to $0800. 28206 28207@c @node FIXME 28208@subsubsection 62 - GMod3 28209 28210@multitable @columnfractions .3 .7 28211@item Size 28212@tab 2MiB/4MiB/8MiB/16MiB (256/512/1024/2048 banks of 8KiB) 28213@item EXROM 28214@tab active (lo) (0) 28215@item GAME 28216@tab inactive (hi) (1) 28217@item Startup mode 28218@tab 8KiB Game 28219@item Load address 28220@tab $8000-$9FFF 28221@end multitable 28222 28223@example 28224 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28225 ----------------------------------------------- ---------------- 2822600000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 2822700010: 00 00 00 40 01 00 00 3E 00 01 00 00 00 00 00 00 ...@@...<........ 2822800020: 56 49 43 45 20 43 41 52 54 00 00 00 00 00 00 00 VICE CART....... 2822900030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 2823000040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 2823100050: 09 80 09 80 C3 C2 CD 38 30 78 8E 16 D0 20 A3 FD .......80x... .. 28232@dots{} 2823302050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 2823402060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 28235@dots{} 28236001FF030: 43 48 49 50 00 00 20 10 00 00 00 FF 80 00 20 00 CHIP.. ....?.. . 28237001FF040: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 28238 28239@end example 28240 28241GMod3 (Individual Computers) 28242 28243This cart uses 2MiB/4MiB/8MiB/16MiB Flash ROM (EN25QH128A(2T)) in 256/512/1024/2048 banks, 28244mapped in at $8000-$9fff. 28245 28246@example 28247 io1 28248 - register at de00-de07 (write) 28249 28250 To select the ROM bank, write to de00-7. The lower 3 bits of the address 28251 are the upper three bits of the bank, as in: 28252 28253 ldx #bankhi ; upper 3 bits of the bank number 28254 lda #banklo ; lower 8 bits of the bank number 28255 sta $de00,x 28256 28257 - register at de00/de08 (read) 28258 28259 The current ROM bank can be read from de00/de08, as in: 28260 28261 ldx $de08 ; upper 3 bits of the bank number 28262 lda $de00 ; lower 8 bits of the bank number 28263 28264 - register at de08 (write) 28265 28266 bit7 (w) bitbang mode enabled 28267 bit6 (w) EXROM (0=active) 28268 bit5 (w) enable cartridge irq vectors 28269 28270 - register at de00 (bitbang mode) 28271 28272 bit7 (r) EEPROM data output 28273 bit6 (w) EEPROM chip select (0=selected) 28274 bit5 (w) EEPROM clock 28275 bit4 (w) EEPROM data input 28276 28277 see http://wiki.icomp.de/wiki/GMod3 28278@end example 28279 28280@c @node FIXME 28281@subsubsection 63 - ZIPP-CODE 48 28282 28283@multitable @columnfractions .3 .7 28284@item Size 28285@tab 8KiB 28286@item EXROM 28287@tab active (lo) (0) 28288@item GAME 28289@tab inactive (hi) (1) 28290@item Load address 28291@tab $8000-9FFF 28292@end multitable 28293 28294@example 28295 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28296 ----------------------------------------------- ---------------- 282970000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 282980010: 00 00 00 40 01 00 00 3f 00 01 00 00 00 00 00 00 ...@@...?........ 282990020: 5a 49 50 50 2d 43 4f 44 45 20 34 38 00 00 00 00 ZIPP-CODE 48.... 283000030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 283010040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 283020050: 11 de 7b e3 c3 c2 cd 38 30 41 80 00 00 03 81 31 ..?....80A.....1 28303 28304@end example 28305 28306@example 28307 reading IO1 enables the cartridge ROM 28308 reading IO2 disables the cartridge ROM 28309 the second last page of the ROM is mirrored in IO1 28310@end example 28311 28312@subsubsection 64 - Blackbox V8 28313 28314@multitable @columnfractions .3 .7 28315@item Size 28316@tab 32KiB or 64KiB 28317@item EXROM 28318@tab active (lo) (0) 28319@item GAME 28320@tab active (lo) (0) 28321@item Load address 28322@tab $8000-BFFF 28323@end multitable 28324 28325@example 28326 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28327 ----------------------------------------------- ---------------- 283280000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 283290010: 00 00 00 40 01 00 00 40 00 00 00 00 00 00 00 00 ...@@...@@........ 283300020: 42 4c 41 43 4b 42 4f 58 20 56 38 00 00 00 00 00 BLACKBOX V8..... 283310030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 283320040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 283330050: 09 80 22 80 c3 c2 cd 38 30 8e 16 d0 20 a3 fd 20 ..?....80... .. 28334 28335@end example 28336 28337@example 28338 writing to IO2 sets the cartridge config: 28339 A0 - EXROM 28340 A1 - GAME 28341 A2 - bank lsb 28342 A3 - bank msb 28343@end example 28344 28345@subsubsection 65 - Blackbox V3 28346 28347@multitable @columnfractions .3 .7 28348@item Size 28349@tab 8KiB 28350@item EXROM 28351@tab active (lo) (0) 28352@item GAME 28353@tab inactive (hi) (1) 28354@item Load address 28355@tab $8000-9FFF 28356@end multitable 28357 28358@example 28359 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28360 ----------------------------------------------- ---------------- 283610000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 283620010: 00 00 00 40 01 00 00 41 00 01 00 00 00 00 00 00 ...@@...A........ 283630020: 42 4c 41 43 4b 42 4f 58 20 56 33 00 00 00 00 00 BLACKBOX V3..... 283640030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 283650040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 283660050: a7 85 2b 80 c3 c2 cd 38 30 8e 16 d0 20 a3 fd 20 ..+....80... .. 28367 28368@end example 28369 28370@example 28371 writing IO1 disables the cartridge ROM 28372 writing IO2 enables the cartridge ROM 28373@end example 28374 28375@subsubsection 66 - Blackbox V4 28376 28377@multitable @columnfractions .3 .7 28378@item Size 28379@tab 16KiB 28380@item EXROM 28381@tab active (lo) (0) 28382@item GAME 28383@tab active (lo) (0) 28384@item Load address 28385@tab $8000-BFFF 28386@end multitable 28387 28388@example 28389 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28390 ----------------------------------------------- ---------------- 283910000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 283920010: 00 00 00 40 01 00 00 42 00 00 00 00 00 00 00 00 ...@@...B........ 283930020: 42 4c 41 43 4b 42 4f 58 20 56 34 00 00 00 00 00 BLACKBOX V4..... 283940030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 283950040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 283960050: a7 85 2b 80 c3 c2 cd 38 30 8e 16 d0 20 a3 fd 20 ..+....80... .. 28397 28398@end example 28399 28400@example 28401 reading IO1 enables the cartridge ROM 28402 reading IO2 disables the cartridge ROM 28403@end example 28404 28405@subsubsection 67 - REX RAM-Floppy 28406 28407@multitable @columnfractions .3 .7 28408@item Size 28409@tab 8KiB 28410@item EXROM 28411@tab active (lo) (0) 28412@item GAME 28413@tab inactive (hi) (1) 28414@item Load address 28415@tab $8000-9FFF 28416@end multitable 28417 28418@example 28419 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28420 ----------------------------------------------- ---------------- 284210000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 284220010: 00 00 00 40 01 00 00 43 00 01 00 00 00 00 00 00 ...@@...C........ 284230020: 52 45 58 20 52 41 4d 2d 46 4c 4f 50 50 59 00 00 REX RAM-FLOPPY.. 284240030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 284250040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 284260050: 09 80 09 fe c3 c2 cd 38 30 20 a3 fd 20 50 fd 20 .......80 .. P. 28427 28428@end example 28429 28430This cartridge contains an 8KiB ROM which contains the software, plus up to 256KiB 28431RAM which can then be used to store up to 100 programs. The RAM is battery 28432buffered, and the cartridge can be disabled with a switch on the board. 28433 28434@example 28435 dfa0 (write) selects RAM bank 28436 df50 (read) toggles RAM writeable 28437 dfc0 (read) toggles cartridge enable 28438 dfe0 (read) toggles RAM enable 28439@end example 28440 28441@subsubsection 68 - BIS-Plus Cartridge 28442 28443@multitable @columnfractions .3 .7 28444@item Size 28445@tab 2, 4 or 8KiB 28446@item EXROM 28447@tab active (lo) (0) 28448@item GAME 28449@tab inactive (hi) (1) 28450@item Load address 28451@tab $8000-9FFF 28452@end multitable 28453 28454@example 28455 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28456 ----------------------------------------------- ---------------- 284570000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 284580010: 00 00 00 40 01 00 00 44 00 01 00 00 00 00 00 00 ...@@...D........ 284590020: 42 49 53 2d 50 4c 55 53 00 00 00 00 00 00 00 00 BIS-PLUS........ 284600030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 284610040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 284620050: 09 80 5e fe c3 c2 cd 38 30 8e 16 d0 20 a3 fd a0 ..^....80... ... 28463 28464@end example 28465 28466This cartridge contains a 2, 4 or 8KiB ROM. The software is copied to RAM and then 28467the cartridge disables itself by writing to IO1 (de00). 28468 28469@subsubsection 69 - SD-BOX 28470 28471@multitable @columnfractions .3 .7 28472@item Size 28473@tab 128KiB 28474@item EXROM 28475@tab active (lo) (0) 28476@item GAME 28477@tab active (lo) (0) 28478@item Load address 28479@tab $8000-BFFF 28480@end multitable 28481 28482@example 28483 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28484 ----------------------------------------------- ---------------- 284850000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 284860010: 00 00 00 40 01 00 00 45 00 00 00 00 00 00 00 00 ...@@...E........ 284870020: 53 44 2d 42 4f 58 00 00 00 00 00 00 00 00 00 00 SD-BOX.......... 284880030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 284890040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 284900050: 09 80 81 ea c3 c2 cd 38 30 a9 00 8d 00 de a9 40 .......80......@@ 28491 28492@end example 28493 28494This cartridge contains a 128KiB banked ROM with a filebrowser and some extra 28495software on it. It also contains a sd2iec clone, which seems to be seperate 28496and runs the original sd2iec firmware. 28497 28498@example 28499 there is one register at de00: 28500 28501 bit 0-3 ROM bank 28502 bit 4 reset SD 28503 bit 5 CE ROM 28504 bit 6 EXROM 28505 bit 7 register enable 28506 28507 additionally there are 3 "ram cells" at de01-de03 28508@end example 28509 28510@c @node FIXME 28511@subsubsection 70 - MultiMAX 28512 28513@multitable @columnfractions .3 .7 28514@item Size 28515@tab 1MiB, 64*16KiB (ULTIMAX mode) 28516@item EXROM 28517@tab inactive (hi) (1) 28518@item GAME 28519@tab active (lo) (0) 28520@item Load address 28521@tab $8000-$9FFF (odd banks), 28522 $E000-$FFFF (even banks) 28523@end multitable 28524 28525@example 28526 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28527 ----------------------------------------------- ---------------- 285280000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 285290010: 00 00 00 40 01 00 00 46 01 00 00 00 00 00 00 00 ...@@...F........ 285300020: 4d 55 4c 54 49 4d 41 58 00 00 00 00 00 00 00 00 MULTIMAX........ 285310030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 285320040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 285330050: 48 80 48 83 48 83 48 83 64 85 64 85 f5 87 aa 88 H.H.H.H.d.d..... 28534@end example 28535 28536This cartridge contains 1MiB ROM organised in 64 16KiB banks. It operates in 28537ultimax mode and contains all known ultimax releases. 28538It also provides additional 2KiB RAM for MAX-Basic, which will be mapped to $0800. 28539 28540@example 28541 there is one register mirrored in the entire IO1 space: 28542 28543 bit 7 when set, the register is disabled and can only be reenabled by reset 28544 bit 0-5 select ROM bank 0-63 28545@end example 28546 28547@c @node FIXME 28548@subsubsection 71 - Blackbox V9 28549 28550@multitable @columnfractions .3 .7 28551@item Size 28552@tab 32KiB, 2*16KiB 28553@item EXROM 28554@tab inactive (hi) (1) 28555@item GAME 28556@tab active (lo) (0) 28557@item Load address 28558@tab $8000-$9FFF 28559 $E000-$FFFF 28560@end multitable 28561 28562@example 28563 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28564 ----------------------------------------------- ---------------- 285650000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 285660010: 00 00 00 40 01 00 00 47 00 00 00 00 00 00 00 00 ...@@...G........ 285670020: 42 4c 41 43 4b 42 4f 58 20 56 39 00 00 00 00 00 BLACKBOX V9..... 285680030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 285690040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 40 00 CHIP..@@.......@@. 285700050: 00 9a b6 fe c3 c2 cd 38 30 c3 ff 00 ff 00 ff 00 .......80....... 28571@end example 28572 28573The cartridge starts in ultimax mode in the last bank. The IO1 area also contains 28574a mirror of the second last ROM page. 28575 28576@example 28577 a register is mapped to IO1, which is changed by accessing an address in 28578 the IO space, the address bits are mapped like this: 28579 28580 bit 7 - bank (inverted on write) 28581 bit 6 - exrom 28582 bit 0 - game 28583@end example 28584 28585@c @node FIXME 28586@subsubsection 72 - Lt. Kernal Host Adaptor 28587 28588@multitable @columnfractions .3 .7 28589@item Size 28590@tab 8KiB ROM, 16KiB RAM 28591@item EXROM 28592@tab active (lo) (0) Initially 28593@item GAME 28594@tab inactive (hi) (1) Initially 28595@item Load address 28596@tab $8000-$9FFF 28597@end multitable 28598 28599@example 28600 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28601 ----------------------------------------------- ---------------- 286020000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 286030010: 00 00 00 40 01 00 00 48 00 01 00 00 00 00 00 00 ...@@...H........ 286040020: 4c 54 2e 20 4b 45 52 4e 41 4c 20 48 4f 53 54 20 LT. KERNAL HOST 286050030: 41 44 41 50 54 4f 52 20 36 2e 32 20 52 4f 4d 00 ADAPTOR 6.2 ROM. 286060040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP............ 286070050: 14 80 14 80 c3 c2 cd 38 30 00 38 37 30 30 30 30 .......80....... 28608 28609@end example 28610 28611The Lt. Kernal Host Adaptor (SCSI ID 7) boot rom looks on sector 0 of drive 0 28612(ID 0) to find the partition (LU or logical unit) information and DOS. If the 28613drive is not found, it will start up in stock mode. See 28614src/c64/cart/ltkernal.c for more details. 28615 28616The Lt. Kernal Host Adaptor uses the following registers: 28617 28618@example 28619 $DF00 = MC6821 Port A: Data and DDR 28620 $DF01 = MC6821 Port A: Control 28621 $DF02 = MC6821 Port B: Data and DDR 28622 $DF03 = MC6821 Port B: Control 28623 $DF04..7 = LTK Port and Freeze state 28624@end example 28625 28626MC6821 Port A connects to the SCSI data bus (inverted). Data is saved to hard 28627disk inverted to save data processing time. 28628 28629@example 28630 signal meaning 28631 ------ ------- 28632 PA 7-0 /Data bus on SCSI (input/output) 28633 CA2 Pulses SCSI ACK (low to high) 28634@end example 28635 28636MC6821 Port B connects to mostly the SCSI control bus. PB2.6 controls write 28637access to 16KiB SRAM. When low (0), no writes are permitted, when high (1) 28638writes are permitted to $8000-$9FFF AND $E000-$FFFF. Initially, this signal is 28639low, which keeps the boot ROM mapped to $8000-$9FFF (lower 4KiB for the C64, 28640upper 4KiB for the C128). Once a high (1) is written, the boot ROM is mapped 28641out permanently until a reset. CB2 controls which KERNAL is in place. A high 28642(1) uses the stock KERNAL while a low (0) maps in one of the 8K RAMs as the 28643KERNAL. The other RAM at $8000-$9FFF memory is ONLY mapped in when PB2.6 is 28644high (1). The HIRAM line from the PLA goes to the adaptor so it can determine 28645the proper write action to the main RAM or adaptor RAM. Writing a high (1) to 28646CB2 while PB2.6 is low (0) causes a system reset. The stock KERNAL is copied and 28647then patched by the LTK DOS on startup. 28648 28649@example 28650 signal meaning 28651 ------ ------- 28652 PB 7 /REQ on SCSI (input) 28653 PB 6 SRAM control 28654 PB 5 RST on SCSI (output) 28655 PB 4 SEL on SCSI (output) 28656 PB 3 /BUSY on SCSI (input) 28657 PB 2 /CD on SCSI (input) 28658 PB 1 /MSG on SCSI (input) 28659 PB 0 /IO on SCSI (input) 28660 CB2 KERNAL control 28661@end example 28662 28663$DF04 - $DF07: 28664 28665The LTK Port can be between 0 and 15. Only adaptors set to port 0 are allowed 28666to change the host configuration. Any writes to this register while PB2.6 and 28667CA2 are high (1), will result in the Lt. Kernal Host Adaptor being removed from 28668the bus until a reset, essentially reconfiguring to a stock system. 28669 28670@example 28671 bit meaning 28672 --- ------- 28673 3-0 LTK port number (input) 28674 4 Freeze state (0: active, 1: inactive) 28675@end example 28676 28677@c @node FIXME 28678@subsubsection 73 - RAMLink 28679 28680@multitable @columnfractions .3 .7 28681@item Size 28682@tab 64KiB ROM, 8KiB RAM 28683@item EXROM 28684@tab active (lo) (0) Initially 28685@item GAME 28686@tab inactive (hi) (1) Initially 28687@item Load address 28688@tab $8000-$BFFF and $E000-$FFFF 28689@end multitable 28690 28691@example 28692 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28693 ----------------------------------------------- ---------------- 286940000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 286950010: 00 00 00 40 01 00 00 49 00 01 00 00 00 00 00 00 ................ 286960020: 43 4d 44 20 52 41 4d 4c 49 4e 4b 20 32 2e 30 31 CMD RAMLink 2.01 286970030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 286980040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 20 00 CHIP............ 286990050: 00 00 00 00 00 00 00 00 ee 42 df 20 1c b9 ee 42 ................ 28700@dots{} 287012050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP............ 287022060: 03 4c 75 9c 88 f0 01 88 8c 80 de a9 8d 20 38 8f ................ 28703@dots{} 287044060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP............ 287054070: 0a 17 d8 8d 64 8c be 00 ce 42 df 20 48 88 ce 42 ................ 28706@dots{} 287076070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP............ 287086080: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................ 28709@dots{} 287108080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00 CHIP............ 287118090: 40 48 20 c9 ff aa 68 90 01 8a 60 20 bd ff 20 64 ................ 28712@dots{} 28713a090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00 CHIP............ 28714a0a0: 85 56 20 0f bc a5 61 c9 88 90 03 20 d4 ba 20 cc ................ 28715@dots{} 28716c0a0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00 CHIP............ 28717c0b0: 80 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 28718@dots{} 28719e0b0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00 CHIP............ 28720e0c0: a2 ff 78 9a d8 a9 00 8d 00 ff a2 0a bd 4b e0 9d ................ 28721 28722or 28723 28724 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28725 ----------------------------------------------- ---------------- 287260000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 287270010: 00 00 00 40 01 00 00 49 00 01 00 00 00 00 00 00 ................ 287280020: 43 4d 44 20 52 41 4d 4c 49 4e 4b 20 31 2e 34 30 CMD RAMLink 1.40 287290030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 287300040: 43 48 49 50 00 00 40 10 00 00 00 00 80 00 20 00 CHIP............ 287310050: 52 41 4d 4c 49 4e 4b 20 44 4f 53 20 28 43 29 31 ................ 28732@dots{} 287332050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP............ 287342060: 4e 54 41 58 20 45 52 52 4f 52 00 57 52 49 54 45 ................ 28735@dots{} 287364060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP............ 287374070: aa 09 f9 10 ec b9 9e 1b ec ce 3f 70 8d 84 df a9 ................ 28738@dots{} 287396070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP............ 287406080: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................ 28741@dots{} 287428080: 43 48 49 50 00 00 20 10 00 00 00 04 80 00 20 00 CHIP............ 287438090: 40 48 20 c9 ff aa 68 90 01 8a 60 20 bd ff 20 64 ................ 28744@dots{} 28745a090: 43 48 49 50 00 00 20 10 00 00 00 05 80 00 20 00 CHIP............ 28746a0a0: 85 56 20 0f bc a5 61 c9 88 90 03 20 d4 ba 20 cc ................ 28747@dots{} 28748c0a0: 43 48 49 50 00 00 20 10 00 00 00 06 80 00 20 00 CHIP............ 28749c0b0: 80 8d 3f de a9 1b 8d 32 de 8d 34 de a9 ee 8d 33 ................ 28750@dots{} 28751e0b0: 43 48 49 50 00 00 20 10 00 00 00 07 80 00 20 00 CHIP............ 28752e0c0: a2 ff 78 9a d8 a9 00 8d 00 ff a2 0a bd 4b e0 9d ................ 28753@end example 28754 28755The RAMLink CRT file is 64 KiB and consists of eight 8 KiB banks. The first 28756two are for the RAMLink DOS which is banked in from $8000-$BFFF (16 KiB). 28757The third and forth are the configuration portion of the DOS which also banks 28758in at $8000-$BFFF, however only the first 8 KiB is officially used. 28759The banks are the 64 shadow kernal, 64 trap kernal, 128 shadow kernal, and 28760128 trap kernal respectively. 28761The first bytes of the configuration DOS bank contain 16-bit checksums of 28762various parts of the ROM. The precise mapping is specific to the particular 28763version of the ROM as the code resides there. 28764The ROMs verify these checksums on boot up. 28765Should this fail, the firmware turns on the error LED and goes into an 28766infinite loop. 28767Since vice doesn't provide an error or activity LED for RAMLink, the system 28768would just appear to hang. 28769 28770The actual RAMLink appears to have the ability to upgrade to a 128 KiB ROM, 28771but no firmware which utilizes it is known to exist. 28772 28773The RAMLink uses many locations in IO2 primarily so that it can co-exist with 28774other cartridges. Most of these registers are write only, that is to say, all 28775that is required to activate them is a write; the contents of the write are 28776not important. This technique minimizes the coding required to interact with 28777the device. 28778Although RAMLink has 2 pass-thru ports, they are not complete shorts to 28779the cartridge bus, some of the control lines are altered based on the state 28780of the device. 28781Initially, RAMLink is disabled, the trap kernal is active and only one of its 28782registers is visisble: 28783 28784@example 28785 $DF7E = Enable RAMLink registers and switch to shadow kernal 28786@end example 28787 28788Once a write is done to $DF7E, all the other registers become active. The 28789shadow kernal also switches in. 28790 28791@example 28792 $DF20 = NMI Trap Enable? (not certain as to its function) 28793 $DF21 = Mirror to $DF01 (for REU) when NMI trap is on 28794 $DF22 = NMI Trap Disable? (not certain as to its function) 28795 $DF40 = I8255A Port A (Main board and parallel interface) 28796 $DF41 = I8255A Port B 28797 $DF42 = I8255A Port C 28798 $DF43 = I8255A Control 28799 $DF60 = Enable DOS mapping (maps in $8000-$BFFF) 28800 $DF70 = Disable DOS mapping 28801 $DF7F = Disable RAMLink registers and switch to trap kernal 28802 (also disables DOS mapping) 28803 $DF80..9F = Switch SRAM page ($DF80 selects page 0, 28804 $DF81 selects page 1, $DF82 selects page 2, etc.) 28805 $DFA0 = I8255A Port A (RAMCard 1; RAMCard 2 uses custom circuit 28806 but same interface) 28807 $DFA1 = I8255A Port B 28808 $DFA2 = I8255A Port C 28809 $DFA3 = I8255A Control 28810 $DFB0..BF = 72421 RTC interface (RAMCard 2 only) 28811 $DFC0 = Maps in SRAM to $DE00-$DEFF 28812 $DFC1 = Maps in RAMCard to $DE00-$DEFF 28813 $DFC2 = Maps in RAM Port $DE00-$DEFF (GEORAM, RAMDrive) 28814 $DFC3 = Maps in Pass-Thru to $DE00-$DEFF 28815@end example 28816 28817Note that only address $DF40..42, $DFB0..BF present valid information when 28818read. Addresses $DFA0..$DFA3 also require valid data when being written to. 28819See src/c64/cart/ramlink.c for more details. 28820 28821When kernal swiching, the ROMs change inbetween instructions. This is possible 28822as the CPU does not cache any incoming instructions. The following is 28823an example of a JSR to the trap kernal at $E000: 28824 28825@example 28826PC TRAP SHADOW DETAILS 28827 KERNAL KERNAL 28828----- --------- --------- ------------------------------------------ 28829$C000 JSR $E000 JSR $E000 Same code 28830$E000 STA $DF7E STA $DF7F In trap kernel, next instruction in shadow 28831$E003 INC $D021 INC $D020 Increment $D020 28832$E006 STA $DF7E STA $DF7F Switch back to trap on next instruction 28833$E009 RTS NOP Return to $C003 28834@end example 28835 28836If the shadow kernal was active, a JSR to $E000 would result in $D021 being 28837incremented and continuing on back to the NOP in the shadow kernal. 28838The use of write only registers allows the RAMLink Kernal and DOS to perform 28839ROM switching with minimal instructions and time. 28840 28841The RAMLink includes two switches: "Enable/Disable" and "Normal/Direct". 28842"Enable/Disable" controls whether or not RAMLink is active. In the "Disabled" 28843state, control will be given back to the stock ROMs. 28844"Normal/Direct" controls how the IO cartidge lines to the RAM Port (REU, 28845GEORAM, RAMDrive) are passed. In "Normal" mode, these lines are connected 28846only when the RAMLink registers are active. This prevents any unauthorized 28847access to these devices while RAMLink code isn't running. "Direct" connects 28848the IO lines all the time. 28849 28850@c @node FIXME 28851@subsubsection 74 - H.E.R.O. 28852 28853@multitable @columnfractions .3 .7 28854@item Size 28855@tab 32KiB (4 banks of 8KiB each) 28856@item EXROM 28857@tab active (lo) (0) 28858@item GAME 28859@tab inactive (hi) (1) 28860@item Startup mode 28861@tab 8KiB Game 28862@item Load address 28863@tab $8000-9FFF 28864@end multitable 28865 28866@example 28867 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ASCII 28868 ----------------------------------------------- ---------------- 288690000: 43 36 34 20 43 41 52 54 52 49 44 47 45 20 20 20 C64 CARTRIDGE 288700010: 00 00 00 40 01 00 00 4a 00 01 00 00 00 00 00 00 ...@...J........ 288710020: 44 52 45 41 4e 20 48 45 52 4f 00 00 00 00 00 00 DREAN HERO...... 288720030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ 288730040: 43 48 49 50 00 00 20 10 00 00 00 00 80 00 20 00 CHIP.. ....... . 288740050: 0b 80 bc fe c3 c2 cd 38 30 03 49 8e 16 d0 bd 00 .......80.I..... 28875.. 288762050: 43 48 49 50 00 00 20 10 00 00 00 01 80 00 20 00 CHIP.. ....... . 288772060: 32 aa 5a aa 00 00 ff 00 90 d9 68 d9 00 00 90 05 2.Z.......h..... 28878.. 288794060: 43 48 49 50 00 00 20 10 00 00 00 02 80 00 20 00 CHIP.. ....... . 288804070: ff 7f 7f ff ff 3f 00 00 00 00 00 c0 00 c0 ff 3f .....?.........? 28881.. 288826070: 43 48 49 50 00 00 20 10 00 00 00 03 80 00 20 00 CHIP.. ....... . 288836080: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................ 28884@end example 28885 28886 This cartridge type was found in an argentinian H.E.R.O. clone cartridge, 28887 ROM memory is organized in 8KiB ($2000) banks located at $8000-$9FFF. 28888 There appears to be one register mirrored over IO2 (the software uses $DFFF). 28889 Banks are selected by writing to the lower 2 bits of the register, bit 5 28890 disables the cartridge. 28891 28892@c @node FIXME 28893@section The PSID image format for ripped SID tunes 28894 28895This section describes the SID file format used for SID tunes in the HVSC 28896(High Voltage SID Collection - http://hvsc.de). It is based mostly on 28897Michael Schwendt's document that describes the file format and the PSID v2NG 28898extensions described by Simon White and Dag Lem and was further extended by 28899Wilfred Bos (PSID v3/v4, RSID v3/v4) and LaLa (assembled most of the following text) 28900and last not least tweaked a bit by Groepaz to fit into the VICE documentation. 28901 28902The original documentation maintained by the HVSC team can be found here: 28903 @uref{http://www.hvsc.de/download/C64Music/DOCUMENTS/SID_file_format.txt} 28904 28905SID files use the .sid file extension. 28906 28907Since PSID v2 is simply an extension of PSID v1, PSID v2NG is an extension of 28908PSID v2, RSID is a restricted version of PSID v2NG, PSID v3/v4 and RSID v3/v4 are 28909extentions of PSID v2NG and RSID v2, all of the formats are discussed together 28910below. RSID in specific is discussed in detail under the 'magicID' field 28911description. 28912 28913The information presented here targets programmers or other people with 28914reasonable background. It is not suitable for newbies who have never before 28915used a machine code monitor, a disassembler, or a hexadecimal editor. 28916 28917 28918@c @node FIXME 28919@subsection The SID file header v1 28920 28921The detailed structure of the SID header looks like the following. Header 28922offsets are in hexadecimal notation. Other integer values are decimal unless 28923explicitly marked otherwise. Any stored integer values are in big-endian 28924format: 28925 28926@example 28927+00 magicID: ``PSID'' or ``RSID'' 28928@end example 28929 28930This is a four byte long ASCII character string containing the value 289310x50534944 or 0x52534944. 'RSID' (Real SID) denotes that the file strictly 28932requires a true Commodore-64 environment to run properly. 'PSID' files will 28933generally run trouble-free on older PlaySID and libsidplay1 based emulators, 28934too. 28935 28936Some words about the Real C64 SID file format (RSID): 28937 28938The RSID format was designed to contain tunes that are not PlaySID compatible, 28939but strictly require a real C64 environment to run. Tunes that are multi-speed 28940and/or contain samples and/or use additional interrupt sources or do busy 28941looping will cause older SID emulators to lock up or play very wrongly (if at 28942all). 28943 28944By using the name RSID for such rips all existing SID emulators will reject 28945these tunes safely until they can be upgraded to cope with the additional 28946requirements. 28947 28948Due to the nature of these tunes, every effort must be made to make sure they 28949are directly runnable on an actual C64 computer. As such the tunes will only 28950be presented with the default C64 power-on environment and expected to 28951configure and use all hardware appropriately. 28952 28953RSID is based on PSIDv2NG with the following modifications: 28954 28955@itemize 28956@item magicID = RSID 28957@item version = 2, 3 and 4 only 28958@item loadAddress = 0 (reserved) 28959@item playAddress = 0 (reserved) 28960@item speed = 0 (reserved) 28961@item psidSpecific flag is called C64BASIC flag 28962@end itemize 28963 28964The above fields MUST be checked and if any differ from the above then the 28965tune MUST be rejected. The definitions above will force tunes to contain 28966proper hardware configuration code and install valid interrupt handlers. 28967 28968See section "The SID file environment" below for the default C64 power-on 28969environment for each SID file format. 28970 28971@example 28972+04 WORD version 28973@end example 28974 28975Available version number can be 0001, 0002, 0003 or 0004. Headers of version 2, 3 and 4 28976provide additional fields. RSID and PSID v2NG files must have 0002, 0003 or 0004 here. 28977 28978@example 28979+06 WORD dataOffset 28980@end example 28981 28982This is the offset from the start of the file to the C64 binary data area. 28983Because of the fixed size of the header, this is either 0x0076 for version 1 28984and 0x007C for version 2, 3 and 4. 28985 28986@example 28987+08 WORD loadAddress 28988@end example 28989 28990The C64 memory location where to put the C64 data. 0 means the data are in 28991original C64 binary file format, i.e. the first two bytes of the data contain 28992the little-endian load address (low byte, high byte). This must always be true 28993for RSID files. Furthermore, the actual load address must NOT be less than 28994$07E8 in RSID files. 28995 28996You must be absolutely sure what to enter here. There is no way to detect 28997automatically whether the first two bytes in a C64 data file are meant to be a 28998load address or some arbitrary bytes of code or data. Unless your C64 file is 28999not a normal binary file and thus has no load address in front, you need not 29000enter anything else than 0 here. The SID tune will not play if you specify a 29001load address which is present in the C64 file already. 29002 29003Normal C64 binary data files have a load address in their first two bytes, so 29004they can be loaded to a pre-defined destination address by executing 29005LOAD"FILE",8,1, for instance. If a load address is explicitly specified in the 29006sidtune info file, some sidtune converters and utilities conjecture that the 29007C64 data don't have a load address in their first two bytes. Hence, the 29008explicit load address from the info file is moved in front of the C64 data to 29009create a valid C64 binary file which can be easily loaded on a C64, too. If 29010that C64 file were to be saved, it would contain two superfluous data bytes at 29011offset 2 if an original load address had been in the first two bytes of the 29012old file. This process of adding a duplicate load address can be repeated. The 29013file loader strips off the first two bytes (the used load address) and puts 29014the rest of the file contents (including the now obsolete load address at file 29015offset 2) into memory. If the new load address is the same than the old one 29016the two added bytes cause the whole data to be displaced by two bytes, which 29017most likely results in malfunctioning code. Also, superfluous bytes in memory 29018then can confuse disassemblers which start at the beginning of the file or 29019memory buffer. 29020 29021@example 29022+0A WORD initAddress 29023@end example 29024 29025The start address of the machine code subroutine that initializes a song, 29026accepting the contents of the 8-bit 6510 Accumulator as the song number 29027parameter. 0 means the address is equal to the effective load address. 29028 29029In RSID files initAddress must never point to a ROM area ($A000-$BFFF or 29030$D000-$FFFF) or be lower than $07E8. Also, if the C64 BASIC flag is set, 29031initAddress must be 0. 29032 29033@example 29034+0C WORD playAddress 29035@end example 29036 29037The start address of the machine code subroutine that can be called frequently 29038to produce a continuous sound. 0 means the initialization subroutine is 29039expected to install an interrupt handler, which then calls the music player at 29040some place. This must always be true for RSID files. 29041 29042@example 29043+0E WORD songs 29044@end example 29045 29046The number of songs (or sound effects) that can be initialized by calling the 29047init address. The minimum is 1. The maximum is 256. 29048 29049@example 29050+10 WORD startSong 29051@end example 29052 29053The song number to be played by default. This value is optional. It often 29054specifies the first song you would hear upon starting the program is has been 29055taken from. It has a default of 1. 29056 29057@example 29058+12 LONGWORD speed 29059@end example 29060 29061This is a 32 bit big endian number. 29062 29063For version 1 and 2 and for version 2NG, 3 and 4 with PlaySID specific flag (+76) 29064set, the 'speed' should be handled as follows: 29065 29066Each bit in 'speed' specifies the speed for the corresponding tune number, 29067i.e. bit 0 specifies the speed for tune 1. If there are more than 32 tunes, 29068the speed specified for tune 32 is the same as tune 1, for tune 33 it is the 29069same as tune 2, etc. 29070 29071For version 2NG, 3 and 4 with PlaySID specific flag (+76) cleared, the 'speed' 29072should be handled as follows: 29073 29074Each bit in 'speed' specifies the speed for the corresponding tune number, 29075i.e. bit 0 specifies the speed for tune 1. If there are more than 32 tunes, 29076the speed specified for tune 32 is also used for all higher numbered tunes. 29077 29078For all version counts: 29079 29080@itemize 29081@item A 0 bit specifies vertical blank interrupt (50Hz PAL, 60Hz NTSC), and a 1 bit 29082specifies CIA 1 timer interrupt (default 60Hz). 29083@item Surplus bits in 'speed' should be set to 0. 29084@item For RSID files 'speed' must always be set to 0. 29085@end itemize 29086 29087Note that if 'play' = 0, the bits in 'speed' should still be set for backwards 29088compatibility with older SID players. New SID players running in a C64 29089environment will ignore the speed bits in this case. 29090 29091WARNING: This field does not work in PlaySID for Amiga like it was intended, 29092therefore the above is a redefinition of the original 'speed' field in SID 29093v2NG! See also the 'clock' (video standard) field described below for 'flags'. 29094 29095@example 29096+16 ``<name>'' 29097+36 ``<author>'' 29098+56 ``<released>'' (once known as ``<copyright>'') 29099@end example 29100 29101These are 32 byte long ASCII character strings. Upon evaluating the header, 29102these fields may hold a character string of 32 bytes which is not zero 29103terminated. For less than 32 characters the string should be zero terminated. 29104The maximum number of available free characters is 32. 29105 29106@example 29107+76 <data> 29108@end example 29109 29110Version 1 of the SID header is complete at this point. The binary C64 data 29111starts here. 29112 29113@c @node FIXME 29114@subsection The SID file header v2, v3 and v4 29115 29116Version 2, 3 and 4 of the header incorporates the v1 header fields and provides 29117additional fields. Some of these are actually v2NG, v3 or v4 specific - those are 29118noted below. 29119 29120@example 29121+76 WORD flags 29122@end example 29123 29124This is a 16 bit big endian number containing the following bitfields: 29125 29126@itemize 29127@item Bit 0 specifies format of the binary data (musPlayer): 29128 0 = built-in music player, 29129 1 = Compute!'s Sidplayer MUS data, music player must be merged. 29130@end itemize 29131 29132If this bit is set, the appended binary data are in Compute!'s Sidplayer MUS 29133format, and does not contain a built-in music player. An external player 29134machine code must be merged to replay such a sidtune. 29135 29136@itemize 29137@item Bit 1 specifies whether the tune is PlaySID specific, e.g. uses PlaySID 29138 samples (psidSpecific): 29139 0 = C64 compatible, 29140 1 = PlaySID specific (PSID v2NG, v3, v4) 29141 1 = C64 BASIC flag (RSID) 29142@end itemize 29143 29144This is a v2NG and RSID specific field. 29145 29146PlaySID samples were invented to facilitate playback of C64 volume register 29147samples with the original Amiga PlaySID software. PlaySID samples made samples 29148a reality on slow Amiga hardware with a player that was updated only once a 29149frame. 29150 29151Unfortunately, converting C64 volume samples to PlaySID samples means that 29152they can no longer be played on a C64, and furthermore the conversion might 29153potentially break the non-sample part of a tune if the timing between writes 29154to the SID registers is at all altered. This follows from the ADSR bugs in the 29155SID chip. 29156 29157Today, the speed of common hardware and the sophistication of the SID players 29158is such that there is little need for PlaySID samples. However, with all the 29159PlaySID sample PSIDs in existence there's a need to differentiate between SID 29160files containing only original C64 code and PSID files containing PlaySID 29161samples or having other PlaySID specific issues. As stated above, bit 1 in 29162'flags' is reserved for this purpose. 29163 29164Since RSID files do not have the need for PlaySID samples, this flag is used 29165for a different purpose: tunes that include a BASIC executable portion will 29166be played (with the BASIC portion executed) if the C64 BASIC flag is set. At 29167the same time, initAddress must be 0. 29168 29169@itemize 29170@item Bits 2-3 specify the video standard (clock): 29171 00 = Unknown, 29172 01 = PAL, 29173 10 = NTSC, 29174 11 = PAL and NTSC. 29175@end itemize 29176 29177This is a v2NG specific field. 29178 29179As can be seen from the 'speed' field, it is not possible to specify NTSC C64 29180playback. This is unfortunate, since the different clock speeds means that a 29181tune written for the NTSC C64 will be slightly detuned if played back on a PAL 29182C64. Furthermore, NTSC C64 tunes driven by a vertical blank interrupt have to 29183be converted to use the CIA 1 timer to fit into this scheme. This can cause 29184severe problems, as the NTSC refresh rate is once every 17045 cycles, while 29185the CIA 1 timer A is latched with 17095 cycles. Apart from the difference in 29186timing itself, the SID ADSR bugs can actually break the tune. 29187 29188The 'clock' (video standard) field was introduced to circumvent this problem. 29189 29190@itemize 29191@item Bits 4-5 specify the SID version (sidModel): 29192 00 = Unknown, 29193 01 = MOS6581, 29194 10 = MOS8580, 29195 11 = MOS6581 and MOS8580. 29196@end itemize 29197 29198This is a v2NG specific field. 29199 29200@itemize 29201@item Bits 6-7 specify the SID version (sidModel) of the second SID: 29202 00 = Unknown, 29203 01 = MOS6581, 29204 10 = MOS8580, 29205 11 = MOS6581 and MOS8580. 29206@end itemize 29207 29208If bits 6-7 are set to Unknown then the second SID will be set to the same SID 29209model as the first SID. 29210 29211This is a v3 specific field. 29212 29213@itemize 29214@item Bits 8-9 specify the SID version (sidModel) of the third SID: 29215 00 = Unknown, 29216 01 = MOS6581, 29217 10 = MOS8580, 29218 11 = MOS6581 and MOS8580. 29219@end itemize 29220 29221If bits 8-9 are set to Unknown then the third SID will be set to the same SID 29222model as the first SID. 29223 29224This is a v4 specific field. 29225 29226The MOS6581 and the MOS8580 have three notable differences. First, combined 29227waveforms are generally louder on a MOS8580, to the extent that some 29228combinations that are clearly audible on a MOS8580 are completely silent on a 29229MOS6581. Second, the internal DC levels in the MOS8580 are so small that 29230software or hardware tricks must be used to play volume samples. Third, the 29231MOS8580 analog filter has totally different characteristics from the MOS6581 29232analog filter. 29233 29234To ensure that music specifically written for one of the two SID versions can 29235be played back correctly, bits 4-9 in 'flags' are used as stated above. 29236 29237@itemize 29238@item Bits 10-15 are reserved and should be set to 0. 29239@end itemize 29240 29241@example 29242+78 BYTE startPage (relocStartPage) 29243@end example 29244 29245This is a v2NG specific field. 29246 29247This is an 8 bit number. If 'startPage' is 0, the SID file is clean, i.e. it 29248does not write outside its data range within the driver ranges. In this case 29249the largest free memory range can be determined from the start address and the 29250data length of the SID binary data. If 'startPage' is 0xFF, there is not even 29251a single free page, and driver relocation is impossible. Otherwise, 29252'startPage' specifies the start page of the single largest free memory range 29253within the driver ranges. For example, if 'startPage' is 0x1E, this free 29254memory range starts at $1E00. 29255 29256@example 29257+79 BYTE pageLength (relocPages) 29258@end example 29259 29260This is a v2NG specific field. 29261 29262This is an 8 bit number indicating the number of free pages after 'startPage'. 29263If 'startPage' is not 0 or 0xFF, 'pageLength' is set to the number of free 29264pages starting at 'startPage'. If 'startPage' is 0 or 0xFF, 'pageLength' must 29265be set to 0. 29266 29267The relocation range indicated by 'startPage' and 'pageLength' should never 29268overlap or encompass the load range of the C64 data. For RSID files, the 29269relocation range should also not overlap or encompass any of the ROM areas 29270($A000-$BFFF and $D000-$FFFF) or the reserved memory area ($0000-$03FF). 29271 29272@example 29273+7A BYTE secondSIDAddress 29274@end example 29275 29276This is a v3 specific field. For v2NG, it should be set to 0. 29277 29278This is an 8 bit number indicating the address of the second SID. It specifies 29279the middle part of the address, $Dxx0, starting from value $42 for $D420 to 29280$FE for $DFE0). Only even values are valid. Ranges $00-$41 ($D000-$D410) and 29281$80-$DF ($D800-$DDF0) are invalid. Any invalid value means that no second SID 29282is used, like $00. 29283 29284@example 29285+7B BYTE thirdSIDAddress 29286@end example 29287 29288This is a v4 specific field. For v2NG and v3, it should be set to 0. 29289 29290This is an 8 bit number indicating the address of the third SID. It specifies 29291the middle part of the address, $Dxx0, starting from value $42 for $D420 to 29292$FE for $DFE0). Only even values are valid. Ranges $00-$41 ($D000-$D410) and 29293$80-$DF ($D800-$DDF0) are invalid. Any invalid value means that no third SID 29294is used, like $00. 29295The address of the third SID cannot be the same as the second SID. 29296 29297@example 29298+7C <data> 29299@end example 29300 29301Version 2, 3 and 4 of the SID header ends here. This offset is the start of the 29302binary C64 data. See also 'loadAddress' for what the first 2 bytes of 'data' 29303might indicate. 29304 29305@c @node FIXME 29306@subsection The SID file environment 29307 29308Before the data of a SID file is loaded in memory of a C64, certain addresses 29309and chips must be initialized in order to play the SID tune correctly. 29310 29311For RSID and PSID files the following address must be set: 29312 29313@multitable @columnfractions .3 .7 29314@item $02A6 29315@tab depending on the PAL/NTSC flag in the SID file header, it is set to 293160x01 for PAL and set to 0x00 for NTSC. 29317@end multitable 29318 29319The default C64 environment for PSID files is as follows: 29320 29321@multitable @columnfractions .3 .7 29322@item VIC 29323@tab IRQ set to any raster value less than 0x100. Enabled when speed 29324 flag is 0, otherwise disabled. 29325@item CIA 1 timer A 29326@tab set to 60Hz (0x4025 for PAL and 0x4295 for NTSC) with the 29327counter running. IRQs active when speed flag is 1, otherwise 29328IRQs are disabled. 29329@item Other timers 29330@tab disabled and loaded with 0xFFFF. 29331@end multitable 29332 29333When the init and play addresses are called the bank register value must be 29334written for every call and the value is calculated as follows: 29335 29336@example 29337if address < $A000 -> 0x37 // I/O, Kernal-ROM, Basic-ROM 29338else address < $D000 -> 0x36 // I/O, Kernal-ROM 29339else address >= $E000 -> 0x35 // I/O only 29340else -> 0x34 // RAM only 29341@end example 29342 29343The default C64 environment for RSID files is as follows: 29344 29345@multitable @columnfractions .3 .7 29346@item VIC 29347@tab IRQ set to raster 0x137, but not enabled. 29348@item CIA 1 timer A 29349@tab set to 60Hz (0x4025 for PAL and 0x4295 for NTSC) with the 29350counter running and IRQs active. 29351@item Other timers 29352@tab disabled and loaded with 0xFFFF. 29353@item Bank register 29354@tab 0x37 29355@end multitable 29356 29357@itemize 29358@item A side effect of the bank register is that init MUST NOT be located under a 29359ROM/IO memory area (addresses $A000-$BFFF and $D000-$FFFF) or outside the 29360load image. 29361 29362@item Since every effort needs to be made to run the tune on a real 29363C64 the load address of the image MUST NOT be set lower than $07E8. 29364 29365@item If the C64 BASIC flag is set, the value at $030C must be set with the song 29366number to be played (0x00 for song 1). 29367@end itemize 29368 29369@c section used in file generation, keep to the format used. 29370@node Acknowledgments 29371@chapter Acknowledgments 29372 29373VICE derives from X64, the first Commodore 64 emulator for the 29374X Window System. Here is an informal list of the people who were 29375mostly involved in the development of X64 and VICE: 29376 29377The VICE core team: 29378@itemize @bullet 29379@c The Texinfo manual says we should not use @b though! 29380 29381@item 29382@b{Martin Pottendorfer} 29383Implemented the Gnome Port based on Oliver Schaertels GTK+ 29384port. Added support code for internationalization based on 29385gettext. Improved the *nix fullscreen support. Added multi- 29386threaded GUI display for *nix. Translated the UI to German. 29387Implemented the fliplists + UI (*nix). 29388 29389@item 29390@b{Marco van den Heuvel} 29391Translated the UI to Dutch. Made the internationalization 29392support for the Win32 and Amiga ports. Wrote the GEO-RAM and 29393RamCart cartridge code. Wrote the c64 +60K, +256K and 256K 29394memory expansions code. Wrote the pet REU code. Wrote the plus4 29395memory expansions code. Made the ethernet support for the DOS 29396port. Maintains the QNX 4.x, QNX 6.x, Solaris, Openserver, 29397Unixware, Minix 3.x, Amiga, Syllable and OS/2 binary ports. 29398Maintains the Win64 and Open Watcom project files. Maintains 29399the SDL port(s). Added new .crt support. Added new screenshot 29400formats. Added new sound recording support. Added SIDcart 29401support for xpet, xplus4 and xvic. Improved the MMC64 29402emulation. Added 2 MHz mode and banks 2/3 support for x128. 29403Added the various userport joystick emulations. Added text copy 29404and paste support to the Amiga and BeOS ports. Added DQBB and 29405ISEPIC cartridge support. Added SFX Sound Sampler and SFX Sound 29406Expander support. Added PCI support to the Amiga and DOS ports. 29407Rewrote the sound system into a modular one, added always mono 29408and always stereo support for the sound output. Added the RTC 29409system. Added digiblaster support. Added 3rd SID support. Added 29410the 6309 CPU emulation. Added the 65(S)C02 emulation. Added the 2941165816 emulation. Added native screenshot (koala/doodle) 29412support. Added 6502/6510/8500/8502 cpu port unused bit fading. 29413Added vice.chm (windows), vice.guide (amiga), vice.hlp 29414(windows), vice.inf (os/2), vice.pdf (generic) and vice.txt 29415documentation generation. Added Android port based on 29416'AnVICE 1.0.5'. Improved/fixed the 'in-source' FFMPEG support 29417and fixed it for msvc7.0 and up. Generalized the 'RS232 net' 29418support to be able to be used on any network supporting arch. 29419Started the SDL2 port. Added generic sampler input support. 29420Added new joyport system and converted the joystick, mouse and 29421lightpen code to use the new system. Added joyport attached 29422rtc (bbrtc). Added joyport attached cardkey keypad. Added 29423joyport attached coplin keypad. Added joyport attached atari 29424cx21 keypad. Added joyport attached atari cx85 keypad. Added 29425joyport attached paperclip 64 dongle. Added joyport attached 29426rushware keypad. Added joyport attached 2/4 bit samplers. Added 29427vic20 I/O-2 and I/O-3 RAM support. Added the c64 cp/m (z80) 29428cartridge. Added IDE64 digimax short bus device emulation. 29429Added tapeport system and the tapelog, cp-clockf83, tape-sense 29430dongle, and (not yet working) dtl basic dongle devices. Added 29431easy calc result cartridge emulation. Added hardware SID I/O 29432access system which allows CW3, HardSID, ParSID and SSI2001 to 29433work on AmigaOS, BeOS, DOS, SDL, *nix and windows with and 29434without device drivers. Added clockport system for mmc64, 29435mmcreplay, retroreplay and ide64. Added rrnet clockport device. 29436Added mp3@@64 clockport device. And lots of other fixes and 29437improvements. 29438 29439@item 29440@b{Fabrizio Gennari} 29441Added some improvements to the DOS and GTK+ ports. Changed the 29442Windows video to use GDI as fallback, making it compile without 29443DX if needed. Fixed the t64 support. Added monitor window support 29444using VTE to the GTK+ GUI. Made some monitor fixes. Fixed some 29445tape code issues. 29446 29447@item 29448@b{Groepaz} 29449Added new more precise CRT emulation. Added support for the new 29450cartridge system and many new cartridges. Fixed up parts of 29451cartconv, c1541 and petcat. Added video to audio leak sound support. 29452Improved the GTK3 GUI. Added x64(sc), x128, x64dtv, xplus4, xvic model 29453selection system. Added KoalaPad emulation. Added keyrah keymaps. 29454Added joystick keys mapping to the keymap system. CIA emulation 29455improvements. Added basic support for compute gazette sidplayer 29456files (mus/str) to vsid. Added new palette files. Added 29457'available features' code. Fixed/added some items in the OSX GUI. 29458Added random tape wobble emulation. Added 64KiB RGCD cartridge 29459emulation. Added psid v4 3sid support to vsid. Added single frame 29460advance. Added drive RPM and wobble support. Added rrnet mk3 29461emulation. Added GMod2 and GMod3 cartridge emulation. Added xvic BehrBonz 29462cartridge emulation. Added VICII VSP-bug emulation. Wrote alot of 29463test programs. Updated this document after a long period of 29464outdated mess. And various fixes and improvements. 29465 29466@item 29467@b{Olaf Seibert} 29468Contributed some PET, including PET DWW hires, Xaw, lightpen, 29469hardware scaling, and disk drive patches. Added proper SuperPET 29470support, including 6809/6309 CPU emulation. Maintains the Xaw UI. 29471Added PET HRE (High Res Emulator) board emulation. Added the 294722-chip colour board for the Universal PET mainboard. Added 29473support for 'printer/plotter' Commodore 1520. 29474 29475@item 29476@b{Marcus Sutton} 29477Made some console, dialog and joystick fixes for the BeOS port. 29478Maintains the BeOS port. Added some GTK2 fixes. Fixed some PET model 29479selection issues. Revived the Windows NT Unicode port. 29480 29481@item 29482@b{Kajtar Zsolt} 29483Wrote the IDE64 interface emulation, FD2000/4000 drive emulation, SCPU64 29484emulation and alot of fixes. Improved the mouse support. Added drive 29485burst modification support. Added 1541 drive sounds emulation. Improved 29486c64 cart emulation. Added DAC high pass filtering. Added the xscpu64 29487emulator. Added scroll wheel support for the Micromys mouse emulation. 29488Added Swiss ROM support to x128. Added IDE64 USB server emulation. Added 294891540 drive emulation. Improved monitor support. Improved vdrive 29490compatibility. Added godot screenshot support. And fixed various issues. 29491 29492@item 29493@b{AreaScout} 29494Fixed the SDL2 port. Revived the Android port. Maintains the SDL1, 29495SDL2 and Android ports. 29496 29497@item 29498@b{Bas Wassink} 29499Fixed some gtk2/3 issues. Fixed t64 file handling. Fixed memory 29500leaks. Added more doxygen documentation. Fixed c1541 issues. 29501Updated the Linux-Native-Howto.txt file. Added autoconf, automake and 29502yasm version checking. Fixed runtime linker path issues with *BSD. Fixed 29503out-of-tree building. One of the driving forces behind the 'native' GTK3 29504port. 29505 29506@item 29507@b{Michael C. Martin} 29508One of the driving forces behind the 'native' GTK3 port. 29509 29510@end itemize 29511 29512Former/inactive team members: 29513 29514@itemize @bullet 29515 29516@item 29517@b{BSzili} 29518Provided many amigaos4 fixes. Maintained the amigaos based and derived 29519ports. 29520 29521@item 29522@b{Errol Smith} 29523Improved VDC emulation. Improved MPS803 printer emulation. 29524 29525@item 29526@b{Daniel Kahlin} 29527Worked on DTV VIC emulation, palette, DTV SID support in resid, 29528better DMA/Blitter support and did lots of refactoring. Added 29529new monitor commands and features. Improved the VIC emulation 29530for xvic. Made MIDI driver code for Win32. Rewrote the xvic 29531cartridge system. Added Mega-Cart and Final Expansion V3.2 29532support to xvic. Wrote large parts of the new VIC-II emulation 29533used in x64sc, especially the dot clock domain emulation. Wrote 29534many test programs for hardware analysis. 29535 29536@item 29537@b{Andreas Matthies} 29538Improved the datasette support, the VIC20 video emulation and 29539some UI stuff in the Win32 and DOS ports. He also wrote the 29540BeOS port and implemented video/audio capture support. Improved 29541history recording/playback and implemented support for video 29542recording and the netlink feature. Made the Win32 user 29543changable keyboard shortcut system. Improved CIA and VIA 29544emulation. Worked on x64sc, especially interrupt timing. 29545Improved the FFMPEG support and started the 'in-source' 29546FFMPEG support/merge. Wrote test programs. Various 29547bug(fixe)s. ;-) 29548 29549@item 29550@b{Ulrich Schulz} 29551Maintains the Dingoo port(s). 29552 29553@item 29554@b{Stefan Haubenthal} 29555Added some Amiga fixes. 29556 29557@item 29558@b{Thomas Giesel} 29559Added new monitor commands, features and improvements. 29560 29561@item 29562@b{Ingo Korb} 29563Corrected block allocation and interleave for c1541/vdrive, 29564added rudimentary xplus4 tape recording support, fixed some GTK2 29565issues, corrected a case of missing Pi symbols in petcat, changed 29566the trap opcode byte, stopped the high-level serial drive code 29567from responding to addresses 16-30 and was forced to update this 29568entry himself. 29569 29570@item 29571@b{Antti S. Lankila} 29572Made the ReSID-fp engine, rewrote the PAL emulation code and 29573fixed the sound core for lower latency. Rewrote DTV SID support 29574(ReSID-dtv). Improved 1541 drive rotation emulation. Worked on 29575x64sc. Added RSID BASIC tunes support to vsid. Several ReSID 29576fixes and improvements. 29577 29578@item 29579@b{Christian Vogelgsang} 29580Maintained the Mac OS X port. Added Intel Mac support and 29581universal binary creation. Wrote the build scripts for all 29582external Mac libraries and the bindist bundle tool. Improved 29583the TFE chip emulation. Added some GTK+ fixes. 29584 29585@item 29586@b{Dag Lem} 29587Implemented the reSID SID emulation engine and video hardware 29588scaling. 29589 29590@item 29591@b{Spiro Trikaliotis} 29592Copyright @copyright{} 2000-2011 29593Wrote the Win32 console implementation for the built-in 29594monitor, corrected some REU related bugs, improved the CIA 29595emulation, added com-port CIA support to the Win32 port, added 29596text copy and paste support to the Win32 port, added support 29597for the TFE and RR-Net (cs8900a), and wrote some further 29598patches. 29599 29600@item 29601@b{Hannu Nuotio} 29602Copyright @copyright{} 2007-2011 29603Implemented DTV flash emulation, DTV support in the monitor, 29604large parts of the DTV VIC, burst mode and skip cycle emulation 29605as well as many other things. Added NEOS and Amiga mouse, 29606paddle and light pen support. Added new monitor commands and 29607features, including memmap. Made MIDI support and OSS MIDI 29608driver. Implemented most of the SDL UI. Rewrote xvic CPU/VIC-I 29609core for cycle based emulation. Implemented C64 cartridge 29610snapshot support. Initiated and worked on all parts of 29611implementing x64sc. Wrote test programs. 29612 29613@item 29614@b{Andreas Boose} 29615Copyright @copyright{} 1998-2010 29616Gave lots of information and bug reports about the VIC-II, the 296176510 and the CIAs; moreover, he wrote several test-routines 29618that were used to improve the emulation. He also added 29619cartridge support and has been the main head behind the drive 29620and datasette emulation since version 0.15. Also added several 29621UI elements to the DOS, Win32 and *nix ports. He rewrote the 29622C128 emulation adding Z80 mode, C64 mode and function ROM 29623support, wrote the screenshot and the event system and started 29624the plus4 emulator. Restructured the serial bus emulation and 29625added realdrive and rawdrive support. 29626 29627@item 29628@b{Tibor Biczo} 29629Copyright @copyright{} 1998-2010 29630Improved the Win32 port and plus4 emulation. 29631 29632@item 29633@b{M. Kiesel} 29634Copyright @copyright{} 2007-2010 29635Started implementing x64dtv. The C64DTV memory model and early 29636versions of the DMA and Blitter engine have been implemented by 29637him. Added new monitor commands and features. 29638 29639@item 29640@b{Andreas Dehmel} 29641Copyright @copyright{} 1999-2007 29642Wrote the Acorn RISC OS port. 29643 29644@item 29645@b{David Hansel} 29646Copyright @copyright{} 2003-2005 29647Wrote the Star NL10 printer driver, implemented IEC devices and 29648improved the tape emulation. 29649 29650@item 29651@b{Markus Brenner} 29652Copyright @copyright{} 2000-2004 29653Added VDC emulation to x128 and added support for some more 29654cartridges. 29655 29656@item 29657@b{Thomas Bretz} 29658Copyright @copyright{} 1999-2004 29659Started the OS/2 port. 29660 29661@item 29662@b{Daniel Sladic} 29663Copyright @copyright{} 1997-2001 29664Started the work on hardware-level 1541 emulation and wrote the 29665new monitor introduced with VICE 0.15. 29666 29667@item 29668@b{Andr� Fachat} 29669Copyright @copyright{} 1996-2001 29670Wrote the PET and CBM-II emulators, the CIA and VIA emulation, 29671the IEEE488 interface, implemented the IEC serial bus in `xvic' 29672and made tons of bug fixes. 29673 29674@item 29675@b{Ettore Perazzoli} 29676Copyright @copyright{} 1996-1999 29677Made the 6510, VIC-II, VIC-I and CRTC emulations, part of the 29678hardware-level 1541 emulation, speed optimizations, bug fixes, 29679the event-driven cycle-exact engine, the Xt/Xaw/Xfwf-based GUI 29680for X11, a general code reorganization, the new resource 29681handling, most of the documentation. He also wrote the DOS port 29682and the initial Win32 port (well, somebody had to do it). 29683 29684@item 29685@b{Teemu Rantanen} 29686Copyright @copyright{} 1993-1994, 1997-1999 29687Implemented the SID emulation and the trap-based disk drive and 29688serial bus implementation; added support for multiple display 29689depths under X11. Also wrote @code{c1541} 29690 29691@item 29692@b{Jouko Valta} 29693Copyright @copyright{} 1993-1996 29694Wrote @code{petcat} and @code{c1541}, @code{T64} handling, user 29695service and maintenance (most of the work in x64 0.3.x was made 29696by him); retired from the project in July 96, after VICE 296970.10.0. 29698 29699@item 29700@b{Jarkko Sonninen} 29701Copyright @copyright{} 1993-1994 29702He was the founder of the project, wrote the old version of the 297036502 emulation and the XDebugger, and retired from the project 29704after x64 0.2.1. 29705 29706@end itemize 29707 29708Internationalization Team: 29709 29710@itemize @bullet 29711 29712@item 29713@c ---translation-team--- 29714@b{Mikkel Holm Olsen} 29715Copyright @copyright{} 2009-2017 29716Provided the Danish user interface translations and fixed a few monitor bugs. 29717 29718@b{Martin Pottendorfer} 29719Copyright @copyright{} 2000-2017 29720Provided the German user interface translations. 29721 29722@b{Manuel Antonio Rodriguez Bas} 29723Copyright @copyright{} 2011-2017 29724Provided the Spanish user interface translations. 29725 29726@b{Paul Dub�} 29727Copyright @copyright{} 2004-2017 29728Provided the French user interface translations. 29729 29730@b{Czirkos Zoltan} 29731Copyright @copyright{} 2006-2017 29732Provided the Hungarian user interface translations. 29733 29734@b{Karai Csaba} 29735Copyright @copyright{} 2006-2017 29736Provided the Hungarian user interface translations. 29737 29738@b{Andrea Musuruane} 29739Copyright @copyright{} 2001-2017 29740Provided the Italian user interface translations. 29741 29742@b{Jesse Lee} 29743Copyright @copyright{} 2011-2016 29744Provided the Korean user interface translations. 29745 29746@b{Marco van den Heuvel} 29747Copyright @copyright{} 2005-2017 29748Provided the Dutch user interface translations. 29749 29750@b{Jarek Sobolewski} 29751Copyright @copyright{} 2011-2017 29752Provided the Polish user interface translations. 29753 29754@b{Michael Litvinov} 29755Copyright @copyright{} 2010-2017 29756Provided the Russian user interface translations. 29757 29758@b{Peter Krefting} 29759Copyright @copyright{} 2000-2017 29760Provided the Swedish user interface translations. 29761 29762@b{Emir Akaydin} 29763Copyright @copyright{} 2008-2017 29764Provided the Turkish user interface translations. 29765 29766@c ---translation-team-end--- 29767@end itemize 29768 29769Documentation Team: 29770 29771@itemize @bullet 29772 29773@item 29774@c ---documentation-team--- 29775@b{Daniel Kahlin} 29776 29777@b{Groepaz} 29778 29779@b{Kajtar Zsolt} 29780 29781@b{Marco van den Heuvel} 29782 29783@b{Olaf Seibert} 29784 29785@c ---documentation-team-end--- 29786 29787@end itemize 29788 29789External contributors: 29790 29791@itemize @bullet 29792 29793@item 29794@b{Alexis Ballier} 29795Provided some ffmpeg fixes. 29796 29797@item 29798@b{Christian Bauer} 29799Wrote the very interesting ``VIC article'' from which we got 29800invaluable information about the VIC-II chip: without this, the 29801VIC-II implementation would not have been possible. 29802 29803@item 29804@b{Anthony J. Bentley} 29805Provided some man page fixes. 29806 29807@item 29808@b{Eliseo Bianchi} 29809Provided the italian Amiga translations. 29810 29811@item 29812@b{Enrico Bruttomesso} 29813Improved some italian translations. 29814 29815@item 29816@b{Frank Buss} 29817Provide some midi fixes. 29818 29819@item 29820@b{ck!} 29821Provided a win32 cbm character font. 29822 29823@item 29824@b{iAN CooG} 29825Added win32 vsid GUI and contributed various patches. 29826 29827@item 29828@b{Mike Dawson} 29829Provided the GP2X port. 29830 29831@item 29832@b{Hans Deragon} 29833Added support for dead keys in X11. 29834 29835@item 29836@b{Paul David Doherty} 29837Wrote @code{zip2disk}, on which the Zipcode support in @code{c1541} is based. 29838 29839@item 29840@b{Sven A. Droll} 29841Added Supergrafik support to petcat. 29842 29843@item 29844@b{Peter Edwards} 29845Implemented the SDL UI slider control and fixed some 29846GP2X/Dingoo SDL UI issues. 29847 29848@item 29849@b{Istv�n F�bi�n} 29850Contributed a initial patch with the more correct 1541 bus 29851timing code and which gave us hints for to improving the 1541 29852emulation. 29853 29854@item 29855@b{Daniel Fandrich} 29856Contributed some disk drive patches. 29857 29858@item 29859@b{Dirk Farin} 29860Rewrote the MITSHM code. 29861 29862@item 29863@b{Georg Feil} 29864Added support for toggling CB2 sound output line in the PET 29865emulator. 29866 29867@item 29868@b{Peter Andrew Felvegi aka Petschy} 29869Fixed a couple of bugs in the fast serial emulation. 29870 29871@item 29872@b{Ricardo Ferreira} 29873Contributed the @code{unlynx} and @code{system} commands in @code{c1541} and 29874added aRts sound support. 29875 29876@item 29877@b{Flooder} 29878Provided parts of the Polish user interface translations. 29879 29880@item 29881@b{Robert H. Forsman Jr.} 29882Provided parts of the widget set for implementing the Xaw GUI. 29883 29884@item 29885@b{Ian Gledhill} 29886Added support for the catweasel.device driver. 29887 29888@item 29889@b{Peter Gordon} 29890Provided support for native AmigaOS4 compiling. 29891 29892@item 29893@b{Richard Hable} 29894Contributed the initial version of the REU emulation. 29895 29896@item 29897@b{Shawn Hargreaves} 29898Wrote Allegro, the graphics and audio library used in the DOS 29899version. 29900 29901@item 29902@b{Ville-Matias Heikkila} 29903Rewrote the vic20 sound code. 29904 29905@item 29906@b{David Holz} 29907Provided a label file which gives the built-in monitor the 29908labels for the C64. 29909 29910@item 29911@b{Nathan Huizinga} 29912Added support for Expert and Super Snapshot carts. 29913 29914@item 29915@b{Derrick Inksley} 29916Fixed loading of zip files with brackets ([]) in 29917the filename for the windows port. Added drive selection 29918functionality to the window sdl port. Some drive sound 29919fixes. Fixed some windows drag'n'drop issues. Fixed some 29920monitor code issues. 29921 29922@item 29923@b{Craig Jackson} 29924Contributed miscellaneous patches in the old X64 times. 29925 29926@item 29927@b{Dirk Jagdmann} 29928Wrote the Catweasel sound driver. 29929 29930@item 29931@b{Uffe Jakobsen} 29932Wrote the Silverrock cartridge emulation and fixed the 29933ocean cartridge bank wrap. Fixed some network code 29934issues. Fixed some monitor issues. Provided some SDL 29935port fixes. 29936 29937@item 29938@b{Lasse Jyrkinen} 29939Contributed miscellaneous patches in the old X64 times. 29940 29941@item 29942@b{Peter Karlsson} 29943Provided the swedish UI translations in the past. 29944 29945@item 29946@b{Greg King} 29947Added a working RTC to the emulation of the IDE64 29948cartridge. Provided some vdrive fixes. Added Inkwell 29949Systems lightpen support. Fixed some monitor code 29950issues. Provided some windows port fixes. Provided some 29951SDL port fixes. 29952 29953@item 29954@b{Michael Klein} 29955Fixed some MacOSX code issues. Contributed the ESD sound 29956driver, basic support for the OPENCBM library and some 29957other patches. 29958 29959@item 29960@b{Frank K�nig} 29961Contributed the Win32 joystick autofire feature. 29962 29963@item 29964@b{Bernd Kortz} 29965Provided some fixes for ZETA and the ZETA binary package. 29966 29967@item 29968@b{Bernhard Kuhn} 29969Made some joystick improvements for Linux. 29970 29971@item 29972@b{Alexander Lehmann} 29973Added complete support for all the VIC20 memory configurations 29974for the old VICE 0.12. 29975 29976@item 29977@b{Ilkka "itix" Lehtoranta} 29978Provided the routines for the cybergraphics support for the 29979Amiga ports. 29980 29981@item 29982@b{Magnus Lind} 29983Atari ST mouse and Atari CX-22 trackball emulation and pixel 29984aspect fixes. Improved the Amiga mouse emulation. Improved 29985the vic20 sound output. Added windows POV hat support. 29986Improved sound fragment size handling. Provided some windows 29987fixes. Provided some gtk port fixes. Provided some SDL port 29988fixes. 29989 29990@item 29991@b{Lioncash} 29992Provided some c1541 fixes. Fixed some 'geninfocontrib' helper tool 29993issues. Fixed some 'embedded' build issues. Fixed some memory leaks. 29994 29995@item 29996@b{Locnet} 29997Made the initial android port of x64. 29998 29999@item 30000@b{Wolfgang Lorenz} 30001Wrote an excellent 6510 test suite that helped us to debug the 30002CPU emulation. 30003 30004@item 30005@b{lvd} 30006Provided some monitor fixes. 30007 30008@item 30009@b{Marko M�kel�} 30010Wrote lots of CPU documentation. Wrote the VIC Flash Plugin 30011cartridge emulation in xvic. Wrote the Ultimem cartridge 30012emulation in xvic. 30013 30014@item 30015@b{mar77i} 30016Fixed some resource handling issues. 30017 30018@item 30019@b{Robert McIntyre} 30020Bugged people enough to get the improved g64 support rolling, 30021updated g64 support to allow variable-length tracks, and 30022performed initial development of half-track support. 30023 30024@item 30025@b{Robert W. McMullen} 30026Provided parts of the widget set for implementing the Xaw GUI. 30027 30028@item 30029@b{Jennifer Medkief} 30030Was in charge of checking up on the GUIs for elements that are 30031wrong, unaccessable, and missing. 30032 30033@item 30034@b{Dan Miner} 30035Contributed some patches to the fast disk drive emulation. 30036 30037@item 30038@b{mjhn} 30039Provided some *nix 'readme' fixes. 30040 30041@item 30042@b{Moiree} 30043Provided some command line fixes. Improved the build system. Fixed 30044some vsid bugs. Fixed some SDL GUI issues. Fixed some documentation 30045items. 30046 30047@item 30048@b{Luca Montecchiani} 30049Contributed a new Unix joystick driver. 30050 30051@item 30052@b{Wolfgang Moser} 30053Provided small optimization fixes to the GCR code, provided an 30054excellent REU test suite and added REU fixes, and is always the 30055good guy reviewing and commenting changes in the background. 30056 30057@item 30058@b{Roberto Muscedere} 30059Improved support for REL files in vdrive. Added Lt. Kernal Host Adaptor, 30060CMD HD, CMD RAMLINK, and CBM D9090/60 emulation. Added D90 support to vdrive. 30061 30062@item 30063@b{Leandro Nini} 30064Improved ReSID emulation. And fixed some c64dtv cpu opcode issues. 30065 30066@item 30067@b{Tomi Ollila} 30068Donated @code{findpath.c}. 30069 30070@item 30071@b{Per Olofsson} 30072Digitalized the C64 colors used in the (old) default palette. 30073 30074@item 30075@b{Lasse ��rni} 30076Contributed the Windows Multimedia sound driver 30077 30078@item 30079@b{Stein Pedersen} 30080Fixed windows midi driver for 64bit windows. 30081 30082@item 30083@b{Helfried Peyrl} 30084Supplied a patch that fixes REL file records larger 256 bytes 30085when using vdrive. 30086 30087@b{Christopher Phillips} 30088Fixed and improved some Mac OS X gui items. 30089 30090@item 30091@b{Frank Prindle} 30092Contributed some patches. 30093 30094@item 30095@b{Giuliano Procida} 30096Used to maintain the VICE @code{deb} package for the Debian 30097distribution, and also helped proofreading the documentation. 30098 30099@item 30100@b{Vesa-Matti Puro} 30101Wrote the very first 6502 CPU emulator in x64 0.1.0. That was 30102the beginning of the story@dots{} 30103 30104@item 30105@b{Rami Rasanen} 30106Rewrote the VIC20 sound code. 30107 30108@item 30109@b{Peter Rittwage} 30110Made 1541 GCR hardware tests. 30111 30112@item 30113@b{David Roden} 30114Fixed various issues related to ffmpeg settings. 30115 30116@item 30117@b{Pablo Rold�n} 30118Contributed initial patch for VIC-II PAL-N model selection. 30119 30120@item 30121@b{Mathias Roslund} 30122Provided the AmigaOS4 port. 30123 30124@item 30125@b{Gunnar Ruthenberg} 30126Provided some VIC-II enhancements and improved the Win32 port. 30127 30128@item 30129@b{Johan Samuelsson} 30130Provided the Swedish Amiga translations. 30131 30132@item 30133@b{Oliver Schaertel} 30134Wrote the X11 full screen, parts of custom ROM set support and 301351351 mouse emulation for unix. 30136 30137@item 30138@b{Peter Schepers} 30139Contributed a document describing the G64 image format. 30140 30141@item 30142@b{Michael Schwendt} 30143Helped with the SID (audio) chip emulation, bringing important 30144suggestions and bug reports, as well as the wave tables and 30145filter emulation from his SIDplay emulator. 30146 30147@item 30148@b{Heiko Selber} 30149Contributed some VIC20 I/O patches. 30150 30151@item 30152@b{John Selck} 30153Improved the video rendering and added the fast PAL emulation. 30154Implemented new color generation based on P. Timmermanns 30155knowledge. 30156 30157@item 30158@b{Chris Sharp} 30159Wrote the AIX sound driver. 30160 30161@item 30162@b{Andr351 "JoBBo" Siegel} 30163Provided the native MorphOS icons. 30164 30165@item 30166@b{Harry "Piru" Sintonen} 30167Provided lots of fixes and improvements for the Amiga ports. 30168 30169@item 30170@b{Manfred Spraul} 30171Wrote the Win32 text lister. 30172 30173@item 30174@b{Markus Stehr} 30175Provided the MMC64 emulation. 30176 30177@item 30178@b{Michael Steil} 30179Provided some c1541 fixes. 30180 30181@item 30182@b{Dominique Strigl} 30183Contributed miscellaneous patches in the old X64 times. 30184 30185@item 30186@b{Samuli Suominen} 30187Fixed XShm includes for newer xextproto versions and updated 30188libpng check for newer versions. 30189 30190@item 30191@b{Steven Tieu} 30192Added initial support for 16/24 bpp X11 displays. 30193 30194@item 30195@b{Philip Timmermann} 30196Did a lot of research about the VIC-II colors. 30197 30198@item 30199@b{TMLPiper} 30200Provided fixes for the osx port. 30201 30202@item 30203@b{Brian Totty} 30204Provided parts of the widget set for implementing the Xaw GUI. 30205 30206@item 30207@b{Mustafa "GnoStiC" Tufan} 30208Made improvements to the GP2x port. 30209 30210@item 30211@b{Lionel Ulmer} 30212Implemented joystick support for Linux and a first try of a SID 30213emulation for SGI machines. 30214 30215@item 30216@b{vonred} 30217Added multiple monitor support to the windows port. 30218 30219@item 30220@b{Krister Walfridsson} 30221Implemented joystick and sound support for NetBSD. 30222 30223@item 30224@b{webulator} 30225Provided Win32 drag & drop support 30226 30227@item 30228@b{Robert Willie} 30229Added some additional commands to the fsdevice emulation. 30230 30231@item 30232@b{Peter Weighill} 30233Gave many ideas and contributed the ROM patcher. 30234 30235@item 30236@b{Gerhard Wesp} 30237Contributed the @code{extract} command in @code{c1541}. 30238 30239@item 30240@b{Maciej Witkowiak} 30241Did some IDE64 and C1541 fixes. 30242 30243@item 30244@b{David Wood} 30245Provided some monitor fixes. 30246 30247@item 30248@b{Count Zero} 30249Fixed some monitor issues. 30250 30251@item 30252@b{Bjoern Odendahl} 30253Created the new VICE logo and volunteered to create new icons. 30254 30255@end itemize 30256 30257(We hope we have not forgotten anybody; if you think we have, 30258please tell us.) 30259 30260The people around the world providing results from running our 30261test programs on various machines deserve a special mention: 30262 30263@itemize @bullet 30264 30265@item 30266@b{hedning} (Drean C64 PAL-N, various C64 PAL boxes) 30267@item 30268@b{Jason Compton} (Various C64 and C128 NTSC boxes) 30269@item 30270@b{The Woz} (Drean C64 PAL-N) 30271@item 30272@b{Thierry} (Drean C64 PAL-N) 30273@item 30274@b{MOS6569} (C64C PAL) 30275@item 30276@b{Mike} (VIC-20 PAL) 30277@item 30278@b{Wilson} (VIC-20 NTSC) 30279@item 30280@b{Vicassembly} (VIC-20 NTSC) 30281@item 30282@b{David "jbevren" Wood} (C64 NTSC-OLD) 30283@end itemize 30284 30285Thanks also to everyone else for sending suggestions, ideas, 30286bug reports, questions and requests. In particular, a warm 30287thanks goes to the following people: 30288 30289@itemize @bullet 30290@item 30291@b{Lutz Sammer} 30292@item 30293@b{Ralph Mason} 30294@item 30295@b{George Caswell} 30296@item 30297@b{Jasper Phillips} 30298@item 30299@b{Luca Forcucci} 30300@item 30301@b{Asger Alstrup} 30302@item 30303@b{Bernhard Schwall} 30304@item 30305@b{Salvatore Valente} 30306@item 30307@b{Arthur Hagen} 30308@item 30309@b{Douglas Carmichael} 30310@item 30311@b{Ferenc Veres} 30312@item 30313@b{Frank Reichel} 30314@item 30315@b{Ullrich von Bassewitz} 30316@item 30317@b{Holger Busse} 30318@item 30319@b{David "jbevren" Wood} 30320@item 30321@b{Gary Glenn} 30322@end itemize 30323 30324Last but not least, a very special thank to Andreas Arens, Lutz 30325Sammer, Edgar Tornig, Christian Bauer, Wolfgang Lorenz, Miha 30326Peternel, Per H�kan Sundell, David Horrocks, Benjamin Rosseaux and William McCabe 30327for writing cool emulators to compete with. @t{:-)} 30328 30329@c end of file generation section. 30330@node Copyright 30331@chapter Copyright 30332 30333@itemize @bullet 30334@item 30335Copyright @copyright{} 1999-2020 Martin Pottendorfer 30336@item 30337Copyright @copyright{} 2005-2020 Marco van den Heuvel 30338@item 30339Copyright @copyright{} 2007-2020 Fabrizio Gennari 30340@item 30341Copyright @copyright{} 2009-2020 Groepaz 30342@item 30343Copyright @copyright{} 2009-2020 Errol Smith 30344@item 30345Copyright @copyright{} 2009-2020 Ingo Korb 30346@item 30347Copyright @copyright{} 2010-2020 Olaf Seibert 30348@item 30349Copyright @copyright{} 2011-2020 Marcus Sutton 30350@item 30351Copyright @copyright{} 2011-2020 Kajtar Zsolt 30352@item 30353Copyright @copyright{} 2016-2020 AreaScout 30354@item 30355Copyright @copyright{} 2016-2020 Bas Wassink 30356@item 30357Copyright @copyright{} 2017-2020 Michael C. Martin 30358@item 30359Copyright @copyright{} 2018-2020 Christopher Phillips 30360@item 30361Copyright @copyright{} 2019-2020 David Hogan 30362@item 30363Copyright @copyright{} 2020 Empathic Qubit 30364 30365@item 30366Copyright @copyright{} 2011-2016 Stefan Haubenthal 30367@item 30368Copyright @copyright{} 2015-2016 BSzili 30369@item 30370Copyright @copyright{} 1999-2016 Andreas Matthies 30371@item 30372Copyright @copyright{} 2007-2015 Daniel Kahlin 30373@item 30374Copyright @copyright{} 2012-2014 Benjamin 'BeRo' Rosseaux 30375@item 30376Copyright @copyright{} 2011-2014 Ulrich Schulz 30377@item 30378Copyright @copyright{} 2011-2014 Thomas Giesel 30379@item 30380Copyright @copyright{} 2006-2014 Christian Vogelgsang 30381@item 30382Copyright @copyright{} 1998-2014 Dag Lem 30383@item 30384Copyright @copyright{} 2000-2011 Spiro Trikaliotis 30385@item 30386Copyright @copyright{} 1998-2010 Tibor Biczo 30387@item 30388Copyright @copyright{} 1998-2010 Andreas Boose 30389@item 30390Copyright @copyright{} 2007-2010 M. Kiesel 30391@item 30392Copyright @copyright{} 2007-2011 Hannu Nuotio 30393@item 30394Copyright @copyright{} 1999-2007 Andreas Dehmel 30395@item 30396Copyright @copyright{} 2003-2005 David Hansel 30397@item 30398Copyright @copyright{} 2000-2004 Markus Brenner 30399 30400@item 30401Copyright @copyright{} 1999-2004 Thomas Bretz 30402@item 30403Copyright @copyright{} 1997-2001 Daniel Sladic 30404@item 30405Copyright @copyright{} 1996-1999 Ettore Perazzoli 30406@item 30407Copyright @copyright{} 1996-1999 Andr� Fachat 30408@item 30409Copyright @copyright{} 1993-1994, 1997-1999 Teemu Rantanen 30410@item 30411Copyright @copyright{} 1993-1996 Jouko Valta 30412@end itemize 30413 30414 30415This program is free software; you can redistribute it and/or modify 30416it under the terms of the GNU General Public License as published by 30417the Free Software Foundation; either version 2 of the License, or 30418(at your option) any later version. 30419 30420This program is distributed in the hope that it will be useful, 30421but WITHOUT ANY WARRANTY; without even the implied warranty of 30422MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 30423GNU General Public License for more details. 30424 30425You should have received a copy of the GNU General Public License 30426along with this program; if not, write to the Free Software 30427Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 3042802111-1307 USA 30429 30430 30431@node Contacts 30432@chapter Contact information 30433 30434@menu 30435* Home page:: The official VICE WWW page. 30436* Sending feedback:: How to report impressions and 30437 bugs to the authors. 30438* Contributing:: How to help developing VICE. 30439@end menu 30440 30441@node Home page, Sending feedback, Contacts, Contacts 30442@section VICE home page 30443 30444You can find the latest news about VICE at the official VICE 30445home page: 30446 30447@example 30448@uref{http://vice-emu.sourceforge.net} 30449@end example 30450 30451VICE has moved its source repository to public services provided by 30452SourceForge. You can find it at 30453@example 30454@uref{http://sf.net/projects/vice-emu}. 30455@end example 30456 30457We would like to thank the SourceForge staff for that help. 30458 30459If you are going to report a bug, please check those pages @emph{first}; 30460it is possible that the problem you encountered has already been 30461fixed with a newer version. 30462 30463@node Sending feedback, Contributing, Home page, Contacts 30464@section How to send feedback 30465 30466Before contacting us, have a look at this manual and see if your question is answered 30467there. Keep in mind that we work on VICE in our spare-time, so the more 30468time we don't need to answer the same questions over and over again, the 30469more time we have to improve the emulation itself. On the other hand, 30470that does not mean that you should not contact us, especially if you 30471find bugs or have suggestions which might improve the emulation. 30472 30473Bug reports, suggestions, support requests should be directed to the 30474SourceForge trackers at 30475 30476@itemize @bullet 30477 30478@item 30479@uref{https://sourceforge.net/p/vice-emu/bugs/}. 30480@end itemize 30481 30482This way, you, the users, and we, the developers, can track what has 30483been reported and what has been already fixed. Ideally, also sent the 30484report to the mailing address of the Vice team at 30485 30486@itemize @bullet 30487 30488@item 30489VICE Mailing List (@email{vice-emu-mail@@lists.sourceforge.net}) for all 30490general questions, bug reports, suggestions. 30491 30492@end itemize 30493 30494You can also contact (some of) us on IRC, at #vice-dev on freenode. 30495 30496It's always nice to receive feedback and/or bugreports about VICE, but 30497please read these few notes before sending mail to anybody in the 30498team. 30499 30500@itemize @bullet 30501 30502@item 30503Please put the word @samp{VICE} @emph{in all capitals} in your subject 30504line (e.g., @samp{VICE fails to run game XXX}). This helps mail 30505splitting and reduces chances that your message is unintentionally 30506deleted, forgotten or lost. 30507 30508@item 30509Please don't send any HTML mail (we really hate that!). Be patient when your 30510mail does not show up on the mailing list - it is moderated manually. Once your 30511mail shows up you should be approved and be able to send mail without further 30512delay. 30513 30514@item 30515Please don't send @emph{any} binaries without asking first. 30516 30517@item 30518Please read the following documents carefully before reporting a bug 30519or a problem you cannot solve: 30520 30521@itemize @bullet 30522@item 30523the VICE documentation (you are reading it!); 30524@item 30525the VICE FAQ (it is available on the Internet, and reachable from the 30526VICE home page: 30527@uref{http://vice-emu.sourceforge.net}); 30528@end itemize 30529 30530@item 30531When you report a bug, please try to be as accurate as possible and 30532describe how it can be reproduced to the very detail. You should also 30533tell us what machine you are running on, what operating system you are 30534using as well as the version of it. 30535 30536@item 30537Please don't ask us how to transfer original C64 disk or tapes to your 30538PC; this has been asked a gazillion times through email. To transfer 30539disks, you can use the Star Commander 30540(@uref{http://sta.c64.org/sc.html}) on DOS, and OpenCBM 30541(@uref{http://www.trikaliotis.net/opencbm}) on Windows and Linux. And 30542no, you cannot read C64 disks with your old 5"1/4 PC drive. 30543 30544@item 30545Please don't ask us where to find games for the emulator on the 30546Internet. It should be very easy to find them using your favourite search 30547engine. 30548 30549@item 30550Please don't ask us when the next version will be out, because we 30551really don't know. 30552 30553@item 30554Please write in English. 30555 30556@end itemize 30557 30558In any case, we would be @emph{really} glad to receive your comments 30559about VICE. We cannot always answer all the email, but we surely read 30560all of it. 30561 30562Thanks! 30563 30564 30565@node Contributing, , Sending feedback, Contacts 30566@section How to contribute 30567 30568If you want to make a major contribution, please @emph{ask} first. It 30569has already happened a couple of times that somebody started working at 30570something that had already been done but not released to the public yet, 30571and we really do @emph{not} want anybody to waste time. 30572 30573If you are going to make a patch, please make sure the patch is relative 30574to the very latest version, and provide us with the following: 30575 30576@itemize @bullet 30577@item 30578Make sure you are giving us a diff against the latest Subversion 30579trunk version of VICE. Get it with the command: 30580@example 30581@samp{svn checkout svn://svn.code.sf.net/p/vice-emu/code/trunk vice-src} 30582@end example 30583@item 30584send a unified diff file against the trunk version of VICE (see above 30585bullet point) by using the command: @samp{svn diff} inside of the 30586SVN workspace you checked out before. 30587 30588@item 30589If you cannot use SVN for one or the other reason, send a unified diff 30590file containing all the changes you have made @samp{diff -u}; 30591please don't use plain @samp{diff}), as it adds much work for us to get 30592it working; 30593@end itemize 30594 30595Preferably post your patch on the tracker: 30596@uref{https://sourceforge.net/p/vice-emu/patches/}. 30597 30598This is very important, and makes adding patches much smoother and 30599safer. 30600 30601People willing to port VICE to other platforms are always welcome. 30602But notice from experience it will take at least a full year of 30603continuous work to write a well working and stable port. 30604 30605@node Concept Index 30606@unnumbered Concept Index 30607 30608@printindex cp 30609 30610@node Resource Index, Command-line Index, Concept Index, Top 30611@unnumbered Index of Resources 30612 30613@printindex vr 30614 30615@node Command-line Index, , Resource Index, Top 30616@unnumbered Index of Command-line options 30617 30618@printindex fn 30619 30620@contents 30621 30622@bye 30623