Document updates for the R4 release
[clinton/Virtual-Jaguar-Rx.git] / res / help.html
CommitLineData
cf76e892
JPM
1<html>
2
3<head>
4<title>Virtual Jaguar: The Documentation</title>
5</head>
6
7<body>
6dd66dca
JPM
8<h1><em>Virtual Jaguar:</em> The Documentation</h1>
9<h2><em>Virtual Jaguar</em> Quick Start</h2>
10<p>Welcome to <em>Virtual Jaguar!</em> If this is your first time using <em>Virtual Jaguar</em>, you can get a feel for what it is and does by doing the following:</p>
cf76e892
JPM
11<ul>
12<li>Select &ldquo;Insert Cartridge&rdquo; from the &ldquo;Jaguar&rdquo; menu, or press the &ldquo;Insert Cartridge&rdquo; toolbar button.</li>
6dd66dca
JPM
13<li>In the dialogue that shows up, you will see the pack-in title of <em>Downfall</em> which is brought to you courtesy of <strong>Reboot</strong> (<a href="http://reboot.atari.org">http://reboot.atari.org</a>). Please note, the Rx version doesn't have games included.</li>
14<li>Click on the <em>Insert</em> button in the lower right-hand corner of the dialogue or simply press the <strong>Enter</strong> key on your keyboard.</li>
15<li>In a few moments, the <em>Downfall</em> title screen should show in the <em>Virtual Jaguar</em> main window.</li>
cf76e892 16</ul>
6dd66dca 17<p>To play, use the left and right keys (mapped to <strong>Z</strong> and <strong>C</strong> on your keyboard) and the&nbsp;B button (mapped to <strong>K</strong> on your keyboard). You can pause <em>Virtual Jaguar</em> by selecting &ldquo;Pause&rdquo; from the &ldquo;Jaguar&rdquo; menu, pressing the &ldquo;Pause&rdquo; toolbar button, or by pressing the <strong>Esc</strong> key on your keyboard. You can quit <em>Virtual Jaguar</em> by selecting &ldquo;Exit&rdquo; from the &ldquo;Jaguar&rdquo; menu, or by pressing <strong>Ctrl</strong> + <strong>Q</strong> on your keyboard.</p>
cf76e892 18<h2>System Requirements</h2>
6dd66dca
JPM
19<p><em>Virtual Jaguar</em> should be able to run on most late model computers equipped with an OpenGL compliant video card. It requires a lot of raw <em>oomph</em> in its present form to run well; do not be surprised if it doesn&rsquo;t run at 100% speed with all the options turned on. Certain subsystems of the Jaguar are not optimized yet and as such take more time than they would if they were optimized. To run <em>Virtual Jaguar</em> at full speed with all options on, we recommend using liquid nitrogen. At least until we get it properly optimized. ;-)</p>
20<h2><em>Virtual Jaguar</em> In Depth</h2>
21<p>This version of <em>Virtual Jaguar</em> has been redesigned with a modern GUI and as such should be fairly easy to use and understand. However, some options may not do what you expect: What follows is an exhaustive look at what the various toolbar buttons and menu options do.</p>
cf76e892 22<h2>The Toolbar</h2>
6dd66dca 23<p>The main <em>Virtual Jaguar</em> toolbar contains the following buttons:</p>
cf76e892
JPM
24<ul>
25<li>Power</li>
26<li>Pause</li>
6dd66dca 27<li>Frame Advance</li>
cf76e892
JPM
28<li>Insert Cartridge</li>
29<li>Use CD Unit</li>
6dd66dca 30<li>Screenshot</li>
cf76e892
JPM
31<li>Scale x1</li>
32<li>Scale x2</li>
33<li>Scale x3</li>
34<li>NTSC</li>
35<li>PAL</li>
36<li>Blur</li>
37<li>Full Screen</li>
38</ul>
cf76e892 39<p>Here&rsquo;s what they do.</p>
cf76e892 40<h3>Power</h3>
6dd66dca 41<p>This toolbar button acts just like the power switch on a real Jaguar, complete with untuned tank circuit noise showing on the screen when the emulated Jaguar is turned off. Some options can only be changed after the power has been turned off, such as the NTSC/PAL switches, or the &ldquo;Use CD Unit&rdquo; option. The &ldquo;Use Jaguar BIOS&rdquo; option in the Configuration dialogue will only take effect after the power has been cycled.</p>
cf76e892 42<h3>Pause</h3>
6dd66dca
JPM
43<p>Pressing the Pause toolbar button will pause execution of the emulated Jaguar. Note that most games have a pause feature that is built into the game; this feature is separate from and will override any built-in game pause feature. Also, the emulator will go into pause mode if the power is on when you activate the &ldquo;Insert Cartridge&rdquo; dialogue. Pressing the <strong>Esc</strong> key will also activate this option. Selecting this option in any of the ways listed above, while in pause mode, will take it out of pause mode.</p>
44<h3>Frame Advance</h3>
45<p>Pressing the button causes <em>Virtual Jaguar</em> to run for one frame (1/60th of a second for NTSC, 1/50th for PAL), and update the screen. This function can also be activated by pressing the <strong>F7</strong> key on your keyboard. This option only works when <em>Virtual Jaguar</em> is paused.</p>
cf76e892 46<h3>Insert Cartridge</h3>
6dd66dca
JPM
47<p>Pressing the Insert Cartridge button will bring up the Insert Cartridge dialogue; it can also be launched by pressing <strong>Ctrl</strong> + <strong>I</strong> on your keyboard. On the left side of the dialogue will be a list of software that <em>Virtual Jaguar</em> recognizes from the directory you tell it to look into (see the &ldquo;Configure&rdquo; menu option and the &ldquo;General&rdquo; tab, &ldquo;Software&rdquo; item for more information). Selecting an item in the list will bring up some information about the software on the right side of the dialogue&nbsp;if <em>Virtual Jaguar</em> knows about it. Pressing the icon in the lower right-hand side of the dialogue will then cause <em>Virtual Jaguar</em> to attempt to run the selected item. <em>Virtual Jaguar</em> cycles the power when it attempts to run the software you select.</p>
48<p>There are also some keyboard shortcuts that come with the Insert Cartridge dialogue: Pressing a letter key will highlight the nearest item in the list that starts with that letter. Pressing more than one letter key in quick succession will narrow in on the item that matches those letter keys pressed. Pressing the <strong>Esc</strong> key will dismiss the dialogue without attempting to load anything, and pressing the <strong>Enter</strong> key is the same as pressing the icon on the lower right-hand side of the dialogue.</p>
cf76e892 49<h3>Use CD Unit</h3>
6dd66dca
JPM
50<p>Pressing this toolbar button will virtually plug in a Jaguar CD unit into the emulated Jaguar. It can only be toggled with the virtual machine powered <strong>off</strong>.</p>
51<p>As of the release date for this emulator, this option <strong>DOES NOT WORK</strong> 100% the way it&rsquo;s intended to: When it&rsquo;s working correctly, selecting this option will allow you to insert a Jaguar CD game into your computer&rsquo;s CD/DVD drive and play it as if it were on a real Jaguar. For now, you can see the CD BIOS make pretty patterns on your screen if you use it.</p>
52<p>Note that once this is working as it should, the DSP will be required to be <strong>enabled</strong> for it to work properly. It <strong>WILL NOT WORK</strong> properly without the DSP.</p>
53<h3>Screenshot</h3>
54<p>Pressing the screenshot button will create a picture file based on the screen displayed in the main window. The file will be saved in the screenshot dedicated directory.</p>
cf76e892 55<h3>Scale x1</h3>
cf76e892 56<p>Selecting this toolbar button will cause the screen to be displayed with pixels that are sized 1 to 1 with your display; this will give you a very small display.</p>
cf76e892 57<h3>Scale x2</h3>
cf76e892 58<p>This will cause the screen to be displayed with pixels that are sized 2 to 1 with your display.</p>
cf76e892 59<h3>Scale x3</h3>
cf76e892 60<p>This will cause the screen to be displayed with pixels that are sized 3 to 1 with your display; this should yield a fairly large display.</p>
cf76e892 61<h3>NTSC</h3>
6dd66dca 62<p>Selecting this item will cause the emulated Jaguar to behave as if it were an NTSC type Jaguar, running at 60 Hz. This option can only be toggled when the virtual machine is powered <strong>off</strong>.</p>
cf76e892 63<h3>PAL</h3>
6dd66dca 64<p>Selecting this item will cause the emulated Jaguar to behave as if it were a PAL type Jaguar, running at 50 Hz. As an added bonus, you also get a few extra scan lines as compared with NTSC mode; some games will even utilize this extra screen real estate. This option can only be toggled when the virtual machine is powered <strong>off</strong>.</p>
cf76e892 65<h3>Blur</h3>
6dd66dca 66<p>Normally, the emulated Jaguar&rsquo;s display shows pixels that are razor sharp and is what you would likely see if the Jaguar was hooked up to a high-quality monitor. Selecting this item will cause the emulated Jaguar&rsquo;s display to be averaged, resulting in a screen that looks slightly blurry&mdash;more like what you would expect to see if the Jaguar was hooked up to a television. This is an aesthetic option that some people prefer; you may or may not like it.</p>
cf76e892 67<h3>Full Screen</h3>
6dd66dca 68<p>Selecting this toolbar button will switch the display into full-screen mode; selecting it again will switch it back to windowed mode. This option can also be activated by pressing the <strong>F9</strong> key on your keyboard. Note that on monitors with a wide aspect ratio that <em>Virtual Jaguar</em> will still display its virtual screen in a 4:3 aspect ratio&mdash;this is normal and expected.</p>
cf76e892 69<h2>Jaguar Menu</h2>
cf76e892 70<p>This menu has the following options:</p>
cf76e892
JPM
71<ul>
72<li>Power</li>
73<li>Pause</li>
cf76e892
JPM
74<li>Insert Cartridge...</li>
75<li>Use CD Unit</li>
76<li>Configure</li>
6dd66dca 77<li>Status</li>
cf76e892
JPM
78<li>Exit</li>
79</ul>
6dd66dca
JPM
80<p><strong>Power</strong> does the same as the toolbar button; see the &ldquo;Power&rdquo; toolbar button description for details.</p>
81<p><strong>Pause</strong> does the same as the toolbar button; see the &ldquo;Pause&rdquo; toolbar button description for details.</p>
82<p><strong>Insert Cartridge...</strong> does the same as the toolbar button; see the &ldquo;Insert Cartridge&rdquo; toolbar button description for details.</p>
83<p><strong>Use CD Unit</strong> does the same as the toolbar button; see the &ldquo;Use CD Unit&rdquo; toolbar button description for details.</p>
84<p><strong>Configure</strong> launches the Configure dialogue. A full description is given in the &ldquo;Configure Dialog&rdquo; section below.</p>
85<p><strong>Status</strong>&nbsp;launches a window with emulator internal information.</p>
86<p><strong>Exit</strong> quits <em>Virtual Jaguar</em> immediately. You can also quit <em>Virtual Jaguar</em> by pressing <strong>Ctrl</strong> + <strong>Q</strong> on your keyboard.</p>
cf76e892 87<h2>Help Menu</h2>
cf76e892 88<p>This menu has the following options:</p>
cf76e892
JPM
89<ul>
90<li>Contents</li>
91<li>About</li>
92</ul>
6dd66dca
JPM
93<p>The <strong>Contents</strong> is what you&rsquo;re reading right now. The voice you are hearing in your head is probably your own, though we can&rsquo;t guarantee that. ;-) This dialogue can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialogue, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
94<p>The <strong>About</strong> option shows a credits dialogue. It can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialogue, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
cf76e892 95<h2>The Configure Dialog</h2>
6dd66dca 96<p>The Configure dialogue has the following tabs:</p>
cf76e892
JPM
97<ul>
98<li>General</li>
6dd66dca
JPM
99<li>Models and BIOS</li>
100<li>Controllers</li>
101<li>Key Bindings</li>
cf76e892 102</ul>
cf76e892 103<h2>General Tab</h2>
cf76e892 104<p>Under the General tab, there are the following options:</p>
cf76e892
JPM
105<ul>
106<li>EEPROMs</li>
107<li>Software</li>
6dd66dca 108<li>Screenshots</li>
cf76e892
JPM
109<li>Enable GPU</li>
110<li>Enable DSP</li>
6dd66dca 111<li>Start Virtual Jaguar in full screen</li>
cf76e892
JPM
112<li>Show all files in file chooser</li>
113<li>Use fast blitter</li>
114</ul>
cf76e892 115<p>Here&rsquo;s what they do.</p>
cf76e892 116<h3>EEPROMs</h3>
6dd66dca 117<p>This field holds the location on your filesystem where your EEPROM files will live (see the &ldquo;EEPROMs&rdquo; section below for details). The path can be either absolute or relative; if relative, it will be relative to where the <em>Virtual Jaguar</em> executable is located on your filesystem.</p>
cf76e892 118<h3>Software</h3>
6dd66dca
JPM
119<p>This field holds the location on your filesystem where your Jaguar software files will live (see the &ldquo;Software&rdquo; section below for details). The path can be either absolute or relative; if relative, it will be relative to where the <em>Virtual Jaguar</em> executable is located on your filesystem.</p>
120<h3>Screenshots</h3>
121<p>This field holds the location on your screenshots (see the &ldquo;Screenshots&rdquo; section below for details). The path can be either absolute or relative; if relative, it will be relative to where the <em>Virtual Jaguar</em> executable is located on your filesystem.</p>
cf76e892 122<h3>Enable GPU</h3>
cf76e892 123<p>The GPU is one of the three main processors in the Jaguar, and checking this option enables it. Most software will not work without this.</p>
cf76e892 124<h3>Enable DSP</h3>
6dd66dca
JPM
125<p>The DSP is one of the three main processors in the Jaguar, and checking this option enables it. Much software will work without it, however, there is some software that will not. Note that if the DSP is disabled, there will be <strong>no</strong> sound.</p>
126<h3>Start Virtual Jaguar in full screen</h3>
127<p>Virtual Jaguar will display his video output in full screen.</p>
cf76e892 128<h3>Show all files in file chooser</h3>
6dd66dca 129<p>Normally the &ldquo;Insert Cartridge...&rdquo; dialogue will ignore any files it encounters that it doesn&rsquo;t know how to deal with. You can override this behavior by checking this option. However, this will <strong>not</strong> cause <em>Virtual Jaguar</em> to be able to load such files.</p>
cf76e892 130<h3>Use fast blitter</h3>
6dd66dca
JPM
131<p>Checking this option will force <em>Virtual Jaguar</em> to use the older, less compatible yet faster blitter. Some games will <strong>not</strong> work properly with this option checked!</p>
132<h2>Models and Bios Tab</h2>
133<p>Under the Models and Bios tab, there are the following options:</p>
134<ul>
135<li>Jaguar model</li>
136<li>Retail BIOS</li>
137<li>Developer BIOS</li>
138</ul>
139<h3>Jaguar Model</h3>
140<p>Option to select the Jaguar model; set as "M" by default; there is no model specific usage except when selecting the retail BIOS.</p>
141<h3>Retail BIOS</h3>
142<p>Selecting this option will cause the emulated Jaguar to run with the built-in system BIOS upon powering on. This is usually not necessary, but some games will not run correctly without it. Note that this option will only affect cartridge images; also, it won't take effect until the virtual machine has been power cycled.</p>
143<h3>Developer BIOS</h3>
144<p>Selecting this option will cause the emulated Jaguar to run with the built-in developer BIOS upon powering on. This option has been set mostly for testing purposes. Note that this option will only affect cartridge images; also, it won't take effect until the virtual machine has been power cycled.</p>
145<h2>Controllers Tab</h2>
cf76e892 146<p>Under the Controller tab, there are the following options:</p>
cf76e892
JPM
147<ul>
148<li>A combobox labeled &ldquo;Host Device&rdquo;</li>
149<li>A combobox labeled &ldquo;Map Name&rdquo;</li>
150<li>Two buttons labelled &ldquo;+&rdquo; and &ldquo;-&rdquo;</li>
151<li>A combobox labeled &ldquo;Maps to&rdquo;</li>
152<li>A picture of a Jaguar controller showing which inputs are defined</li>
153<li>A button labeled &ldquo;Define All Inputs&rdquo;</li>
154</ul>
6dd66dca 155<p><em>Virtual Jaguar</em> utilizes a profile system for controllers. What this means is that you can set up any device that <em>Virtual Jaguar</em> recognizes with any number of different configurations for it. Here&rsquo;s how it works:</p>
cf76e892 156<p>The &ldquo;Host Device&rdquo; combobox lets you select whichever gamepad device you have connected to your computer. This, plus the unique &ldquo;Map Name&rdquo; will show the keymapping set up for that particular host device/key map combination.</p>
cf76e892 157<p>The &ldquo;Map Name&rdquo; combobox lets you set up multiple key maps for your detected device. To add a new key map to the current device, press the &ldquo;+&rdquo; button next to the combobox. It will then ask your for a human readable name for the new map. If you want to remove any maps that you don't want anymore, you can delete the currently selected map by pressing the &ldquo;-&rdquo; button; it will ask for confirmation. Keep in mind that this action cannot be undone!</p>
6dd66dca
JPM
158<p>The &ldquo;Maps to&rdquo; combobox tells <em>Virtual Jaguar</em> which virtual controller slot you would like your device to be plugged into. Selecting <em>None</em> disables that key mapping for that device. Selecting <em>Controller #1</em> will map the device to virtual controller slot #1. Selecting <em>Controller #2</em> will map the device to virtual controller slot #2. Selecting <em>Either one that&rsquo;s free</em> will attempt to connect the device to a free virtual controller slot if one is still available after all other connected devices have had a chance to plug into a definite slot. If other devices have filled up the virtual slots, this option will cause the device to <strong>not</strong> attempt to connect itself.</p>
159<p>Hovering over a letter on the picture of the Jaguar controller will highlight it; clicking on the letter will let you redefine that input by pressing a key on the keyboard or button on a connected gamepad. If you prefer, you can define all inputs at once by clicking on the &ldquo;Define All Inputs&rdquo; button. It will then step through each input on the controller, one at a time, and wait for you to press the key/button that you wish to set it to. You can exit the key redefinition process at any time by pressing the <strong>Esc</strong> key on your keyboard.</p>
160<p>NOTE: For gamepads to be detected, they must be connected to the computer before starting <em>Virtual Jaguar</em>.</p>
161<h2>Key Bindings Tab</h2>
162<p>This tab adapts based on the stock, alpine and debugger mode. User can change the emulator keyboards interactions but not all features have keybinding.</p>
cf76e892 163<h2>EEPROMs</h2>
6dd66dca 164<p>EEPROMs (Electrically Erasable Programmable Read Only Memory) were typically installed on Jaguar cartridges to save high scores and the like, and <em>Virtual Jaguar</em> emulates this. The EEPROMs are keyed to specific games by making a CRC32 checksum of the game and using this as a filename. If an EEPROM file does not exist, it is created when the emulated Jaguar writes to it. The EEPROM files are stored in the location specified by the &ldquo;EEPROMs&rdquo; field of the Configuration dialog, under the &ldquo;General&rdquo; tab.</p>
cf76e892 165<h2>Software</h2>
6dd66dca
JPM
166<p>Software can be either uncompressed or stored in a ZIP file. <em>Virtual Jaguar</em> looks for software in the location specified by the &ldquo;Software&rdquo; field in the Configuration dialog, under the &ldquo;General&rdquo; tab.</p>
167<p><em>Virtual Jaguar</em> is a bit picky about file formats, but tries its best to figure out what you&rsquo;re trying to feed it. In general, if the file is a ROM image, or an Alpine image, <em>Virtual Jaguar</em> will recognize and utilize it. If it&rsquo;s a file meant to load into the emulated Jaguar&rsquo;s RAM space, <em>Virtual Jaguar</em> will load and run it as long as the file contains proper headers. A headerless file of this kind (as opposed to a cartridge or Alpine ROM image) is useless; it contains no information to help <em>Virtual Jaguar</em> know how to load and run it. There is no excuse for this kind of file to exist other than programmer laziness: So, if a file is not recognized by <em>Virtual Jaguar</em>, complain to the author and ask <em>politely</em> for a file with headers. :-)</p>
168<h2>Screenshots</h2>
169<p>Screenshots use JPEG file, with 100% quality.</p>
cf76e892 170<h2>Some Issues You May Encounter</h2>
6dd66dca
JPM
171<p>Most of the time <em>Virtual Jaguar</em> tries to do the right thing with what you tell it to do. There are some options, however, that would be more annoying to use if <em>Virtual Jaguar</em> got in the way and forced you to do the right thing, so, in those places where it&rsquo;s possible to tell <em>Virtual Jaguar</em> to do bad things, it will willingly oblige.</p>
172<p>Some cartridge based games will not work without either the DSP enabled, the BIOS enabled, or both. <em>Virtual Jaguar</em> will let you attempt to run those games with those options disabled, but the result probably won&rsquo;t be what you want.</p>
cf76e892 173<h2>Jaguar Programmer&rsquo;s Zone</h2>
6dd66dca
JPM
174<p><em>Virtual Jaguar</em> has 2 modes available that makes it more convenient for developers to use. In order to use a mode, you must start <em>Virtual Jaguar</em> with the --alpine or --debugger option.</p>
175<p>When started in Debugger mode, a specific tab&nbsp;is made available in the configuration dialogue which gives you the following options:</p>
176<ul>
177<li>Disassembly lines</li>
178<li>Display M68000 opcodes</li>
179<li>Display HW labels</li>
180<li>Display source filename</li>
9b25d85d 181<li>ELF sections check</li>
6dd66dca
JPM
182</ul>
183<p><strong>Disassembly lines</strong>&nbsp;represent the number of disassembly lines to display in the M68000 tracing window. This doesn't include the number of source lines displayed.</p>
184<p><strong>Display M68000 opcode</strong>&nbsp;allows or not the opcode display. Can be useful in case of user prefers to see the disassembly only.</p>
185<p><strong>Display HW labels</strong>&nbsp;allows or not the name of the Jaguar hardware registers as reported in the official documentation.</p>
186<p><strong>Display source filename</strong>&nbsp;allows or not the source code filename display depend the disassembly in the M68000 tracing window.</p>
9b25d85d 187<p><strong>ELF sections check</strong>&nbsp;allows or not potential unknown ELF section, it will stop, or not stop, the sections decoding.</p>
6dd66dca 188<p>When started in Alpine mode, or in Debugger mode, a specific tab is made available in the configuration dialogue which gives you the following options:</p>
cf76e892
JPM
189<ul>
190<li>ROM to load</li>
191<li>ABS to load</li>
6dd66dca
JPM
192<li>Windows refresh</li>
193<li>Allow writes to cartdridge ROM</li>
cf76e892 194</ul>
6dd66dca
JPM
195<p><strong>ROM to load</strong> is the path to a Jaguar executable file that will be loaded into the Jaguar&rsquo;s cartridge memory space at $800000 (Alpine ROM images will load at $802000). As a convenience to coders, this file can be of any length, as long as it fits into the cartridge memory space (a file of this type is treated as an Alpine ROM and is loaded at $802000). The file thus loaded into memory will not be executed.</p>
196<p><strong>ABS to load</strong> is the path to a Jaguar executable file that will be loaded in the Jaguar&rsquo;s main RAM. This file must have valid headers, otherwise <em>Virtual Jaguar</em> won&rsquo;t be able to load it. Assuming the file exists and has the correct headers in it, it will be loaded and run when <em>Virtual Jaguar</em> is first run.</p>
197<p><strong>Windows refresh</strong>&nbsp;is the refresh rate for open windows. The smaller the rate, the faster the refresh window will occur. A 0 value will disable the refresh operations.</p>
198<p><strong>Allow writes to cartdridge ROM</strong>&nbsp;is the option allowing or not the cartdridge ROM writing. If allowed, emulator won't interfere but when turned off the emulator will display a dialog box with proper information, at this point user can allow to continue or stop the code.</p>
199<p>Also, when in Debugger mode,&nbsp;extra toolbar buttons are defined (also found under the extra &ldquo;Debug&rdquo; menu) and also include the Alpine mode features:</p>
200<ul>
201<li>Restart</li>
202<li>Step Into</li>
203<li>Step Over</li>
9b25d85d
JPM
204<li>Breakpoints</li>
205<li>New Function Breakpoint</li>
206<li>Delete All Breakpoints</li>
207<li>Disable All Breakpoints</li>
6dd66dca
JPM
208<li>Exception Vector Table</li>
209<li>All Watch</li>
210<li>Locals</li>
211<li>Call Stack</li>
212<li>Heap Allocator</li>
213<li>Memory (1-4)</li>
9b25d85d
JPM
214<li>Save Dump As...</li>
215<li>Cartridge directory and files list.</li>
6dd66dca
JPM
216</ul>
217<h3>Restart</h3>
218<p>Restart M68000 code (PC) and the stack (SP) pointer to the original ones provided in the ROM.</p>
219<h3>Step Into</h3>
220<p>Trace into M68000 instruction, similar to a step by step tracing.</p>
221<h3>Step Over</h3>
222<p>Trace over M68000 instruction such as jsr/bsr, otherwise this feature functions like a Step Into.</p>
9b25d85d
JPM
223<h3>Breakpoints</h3>
224<p>List the breakpoints and their status. The first breakpoint represents the breakpoint set via the CPU browser, also named as BPM.</p>
225<h3>New Function Breakpoint</h3>
226<p>Add breakpoint to a function.</p>
227<h3>Delete All Breakpoints</h3>
228<p>Delete all breakpoints, also reset the BPM.</p>
229<h3>Disable All Breakpoints</h3>
230<p>Disable all breakpoints, and also disable BPM.</p>
6dd66dca
JPM
231<h3>Exception Vector Table</h3>
232<p>Display a partial table of the M68000 exception vectors as reported by Motorola.</p>
233<h3>All Watch</h3>
234<p>Display all global variables used by the Jaguar code. It uses the available DWARF debug information.</p>
235<h3>Locals</h3>
236<p>Display the local variables of the traced M68000 function.&nbsp;It uses the available DWARF debug information, and the A6 register to point on the stack.</p>
237<h3>Call Stack</h3>
238<p>Display the M68000 call stack functions.&nbsp;It uses the available DWARF debug information, and the A6 register to point on the stack.</p>
239<h3>Heap Allocator</h3>
240<p>Display the status of all memory allocations. It uses a specific structure memory allocation, if such structure is not found then nothing will be displayed.</p>
241<h3>Memory (1-4)</h3>
242<p>This 4 independent windows lets you inspect <em>Virtual Jaguar</em>&rsquo;s emulated memory space. The <strong>PgDn</strong> key will advance the top of the window&rsquo;s memory location by 480 bytes, and <strong>PgUp</strong> will go back by the same amount. The <strong>Plus (+)</strong> key will advance the top of the window&rsquo;s memory location by 16 bytes, and <strong>Minus (-)</strong> will go back by the same amount. Entering a memory location, in hexadecimal, label or decimal, in the edit field and pressing the <strong>Go</strong> button will display memory from that location. It can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialog, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
9b25d85d
JPM
243<h3>Save Dump As...</h3>
244<p>Save a memory portion to a file.</p>
245<h3>Cartridge directory and files list</h3>
246<p>List the cartridge's directory and files; available only if specific structure is used.</p>
6dd66dca
JPM
247<h3><em>Main window</em></h3>
248<p>In the debugger mode, the main window doesn't display anymore the video output; it is replaced by a source code files viewer and a disassembly window made of tabs to allow tracing / display of code.</p>
249<p><strong>Source code files</strong></p>
250<p>It is available for convenience reason; it display all the filenames found in the DWARF information. It is turned off by default but user can turn it on.</p>
251<p><strong>Disassembly tabs</strong></p>
252<p>There are 3 tabs, each of them is dedicated to a specific processor (M68000, GPU, and DSP). Currently, only the M68000 is tracable, others 2 display only the code pointed by their respective program counter (PC).</p>
cf76e892 253<p>Also, when in Alpine mode, extra toolbar buttons are defined (also found under the extra &ldquo;Debug&rdquo; menu):</p>
cf76e892
JPM
254<ul>
255<li>Memory Browser</li>
6dd66dca 256<li>Stack Browser</li>
cf76e892
JPM
257<li>CPU Browser</li>
258<li>OP Browser</li>
259<li>M68K Disassembly Browser</li>
260<li>RISC Disassembly Browser</li>
261</ul>
cf76e892 262<h3>Memory Browser</h3>
6dd66dca
JPM
263<p>This window lets you inspect <em>Virtual Jaguar</em>&rsquo;s emulated memory space. The <strong>PgDn</strong> key will advance the top of the window&rsquo;s memory location by 480 bytes, and <strong>PgUp</strong> will go back by the same amount. The <strong>Plus (+)</strong> key will advance the top of the window&rsquo;s memory location by 16 bytes, and <strong>Minus (-)</strong> will go back by the same amount. Entering a memory location, in hexadecimal, in the edit field and pressing the <strong>Go</strong> button will display memory from that location. It can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialog, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
264<h3>Stack Browser</h3>
265<p>This window lets you inspect <em>Virtual Jaguar</em>&rsquo;s emulated memory stack (SP) space. The <strong>PgDn</strong> key will advance the top of the window&rsquo;s memory location by 480 bytes, and <strong>PgUp</strong> will go back by the same amount. The <strong>Plus (+)</strong> key will advance the top of the window&rsquo;s memory location by 16 bytes, and <strong>Minus (-)</strong> will go back by the same amount. Entering a memory location, in hexadecimal, in the edit field and pressing the <strong>Go</strong> button will display memory from that location. It can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialog, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
cf76e892 266<h3>CPU Browser</h3>
9b25d85d 267<p>This window shows the state of the various CPUs in the emulated Jaguar, a breakpoint can also be set via the BPM setting. The window can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialog, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
cf76e892 268<h3>OP Browser</h3>
6dd66dca 269<p>This window shows the current state of object list that the Object Processor is pointing to. Note that most of the time, this will likely show an object list that has had its objects processed. It can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialog, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
cf76e892 270<h3>M68K Disassembly Browser</h3>
6dd66dca 271<p>This window provides a disassembly of 68000 opcodes. It can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialog, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
cf76e892 272<h3>RISC Disassembly Browser</h3>
6dd66dca
JPM
273<p>This window provides a disassembly of RISC opcodes. It can be dismissed by clicking on the &ldquo;X&rdquo; in the upper corner of the dialog, or by pressing the <strong>Esc</strong> key on your keyboard.</p>
274<p>The aforementioned options will only work when <em>Virtual Jaguar</em> is run in Alpine or Debugger mode, that is, when the --alpine or --debugger flag is passed in. If you do not pass such flag, <em>Virtual Jaguar</em> will run as it normally does, i.e., as a stock Jaguar, and nothing will be loaded by default.</p>
cf76e892 275<h2>For The Curious</h2>
6dd66dca
JPM
276<p>If you&rsquo;re wondering why some cartridges have labels in the &ldquo;Insert Cartridge...&rdquo; dialogue and some don&rsquo;t, read on...</p>
277<p><em>Virtual Jaguar</em> looks at your ZIP file as a container&mdash;if it finds what it expects in the ZIP, it will use it. For example, label images: If you put an image file of a cartridge label in the ZIP file with your ROM image, <em>Virtual Jaguar</em> will use that image in the &ldquo;Insert Cartridge...&rdquo; dialogue &mdash; assuming it&rsquo;s a valid image file. The image should be 365 x 168 for it to show up on the big cartridge image without any scaling; any bigger is just a waste of space and <em>Virtual Jaguar</em> will scale it down to 365 x 168 anyway.</p>
278<p>Using the ZIP file as a container this way opens up some exciting possibilities: Box art, overlays and documentation can be included and future versions of <em>Virtual Jaguar</em> will be able to utilize them.</p>
cf76e892 279<h2>Legal Nigglings</h2>
6dd66dca
JPM
280<p>Or, as it&rsquo;s more commonly known, the disclaimer: <em>&ldquo;O liability, I do disclaim thee!&rdquo;</em></p>
281<p>Trademarks used in <em>Virtual Jaguar</em> and/or this documentation are the property of their respective owners. The user(s) of <em>Virtual Jaguar</em> assumes all risk associated with using the software; the authors are not responsible for anything the user(s) does with said software or what happens to the user(s) as a result of using this software.</p>
282<p><em>Virtual Jaguar</em> is Free (as in Libre) software and is licensed under the GPL version 3. You should have received a copy of the license with this software; if you did not, you may view a copy at <a href="http://www.gnu.org/licenses">http://www.gnu.org/licenses</a>. A copy of the source code is available at <a href="http://icculus.org/virtualjaguar">http://icculus.org/virtualjaguar</a>. A copy of the Rx version source code is available at&nbsp;<a href="https://github.com/djipi/Virtual-Jaguar-Rx">https://github.com/djipi/Virtual-Jaguar-Rx</a>.</p>
283<p><em>Downfall</em> is &copy; 2011 <strong>Reboot</strong>, All Rights Reserved. Distribution of <em>Downfall</em> with <em>Virtual Jaguar</em> has been graciously authorized by <strong>Reboot</strong>, and may not be distributed as part of any other package. As previously stated, the&nbsp;Rx version doesn't have the game included.</p>
cf76e892
JPM
284</body>
285</html>