forked from DizTools/DiztinGUIsh
-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathhelp.html
More file actions
533 lines (437 loc) · 41.2 KB
/
Copy pathhelp.html
File metadata and controls
533 lines (437 loc) · 41.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
<html>
<head>
<title>DiztinGUIsh Help File</title>
</head>
<body>
<h1>DiztinGUIsh Help - v1.0.1.6</h1>
<hr />
<h2>Table of Contents</h2>
<ul>
<li><a href="#intro">Introduction</a></li>
<li>
<a href="#mainwindow">DiztinGUIsh Main Window</a>
<ul>
<li><a href="#projectfiles">Project Files</a></li>
<li><a href="#tablegrid">Table Grid View</a></li>
<li><a href="#stepping">Stepping</a></li>
<li><a href="#autostep">Auto Stepping</a></li>
<li><a href="#goto">Goto</a></li>
<li><a href="#marking">Marking</a></li>
<li><a href="#labelcomment">Labels and Comments</a></li>
<li><a href="#desynching">Misalignments & Desynching</a></li>
<li><a href="#inoutpoints">In/Out/End/Read Points</a></li>
<li><a href="#hotkeys">Keyboard Hotkeys</a></li>
</ul>
</li>
<li>
<a href="#gotowindow">Goto Window</a>
<ul>
<li><a href="#romvspc">ROM Address vs PC Offset</a></li>
<li><a href="#hexvsdec">Hexadecimal vs Decimal</a></li>
</ul>
</li>
<li>
<a href="#markmany">Mark Many Window</a>
<ul>
<li><a href="#propertyvalue">Property & Value</a></li>
<li><a href="#addressrange">Address Range</a></li>
</ul>
</li>
<li><a href="#misalignedflags">Fix Misaligned Flags Window</a></li>
<li><a href="#rescanpoints">Rescan for In/Out Points Window</a></li>
<li><a href="#labellist">Label List Window</a></li>
<li>
<a href="#disassembly">Export Disassembly Window</a>
<ul>
<li><a href="#outputformat">Output Format</a></li>
<li><a href="#unlabeled">Unlabeled Instructions</a></li>
<li><a href="#bankstructure">Bank Structure</a></li>
<li><a href="#maxdatabytes">Max Data Bytes Per Line</a></li>
<li><a href="#asarassembly">Reassembly with Asar</a></li>
</ul>
</li>
<li>
<a href="#fileformat">Project File Format</a>
<ul>
<li><a href="#version01">Version 01</a></li>
<li><a href="#version00">Version 00</a></li>
</ul>
</li>
</ul>
<hr />
<h2 id="intro">Introduction</h2>
<p>DiztinGUIsh is a Super NES ROM disassembler. Open a ROM file, flag each byte as code or data, add some extra info like labels and comments, and disassemble. The output will be one or more .asm files that are (idealy) equivalent to the original source code of the game. The assembly files can then be re-assembled with <a href="https://github.com/RPGHacker/asar/releases">Asar</a> to check for integrity, and/or to make simple changes to the code.</p>
<p>As you may guess, tagging every single byte as data or code is a tedious process, so DiztinGUIsh has many tools built in to make the process more bareable. Disassembling 65C816 code can be quite tricky, so some human input is still required to get a 100% accurate disassembly, but most of the job will be done automatically.</p>
<hr />
<h2 id="mainwindow">DiztinGUIsh Main Window</h2>
<p>This is the window where most of the work is done. It consists of one very large table, some text at the bottom, and some options at the top.</p>
<h4>File</h4>
<p>Create new projects, open & save <a href="#projectfiles">projects</a>, <a href="#disassembly">export a disassembly</a>, and exit from this menu.</p>
<p><em>Note: Importing CDLs and Trace Logs are not supported yet.</em></p>
<h4>Edit</h4>
<p>This menu has the meat of the program in it. Each option here has a <a href="#hotkeys">keyboard hotkey</a> associated to it. You can see them by using the alt key to open this menu--the hotkeys will be underlined.</p>
<h4>Tools</h4>
<p>This menu will bring up additional tools to help you with managing data.</p>
<ul>
<li><strong>Visual Map</strong>: This window lets you see a visual map of the entire ROM, including what each byte is flagged as. <em>Not supported yet.</em></li>
<li><strong>Graphics Window</strong>: This window lets you interpret the ROM data as various SNES graphics formats. <em>Not supported yet.</em></li>
<li><strong>Constants</strong>: This changes what base the "raw byte" column is shown in. You can pick from decimal, hexadecimal, and binary.</li>
<li>
<strong>Options</strong>
<ul>
<li><strong>Move With Step</strong>: When enabled, the currently selected cell in the table will jump to the byte after the last modified byte after a auto step or mark many operation.</li>
</ul>
</li>
</ul>
<h4>Help</h4>
<p>This menu has a link to this file, a link to the <a href="https://github.com/Dotsarecool/DiztinGUIsh">Github repository</a>, and the about window where you can see what version of DiztinGUIsh you have.</p>
<hr />
<h3 id="projectfiles">Project Files</h3>
<p>All of the flags, labels, comments, and other data you make to help with disassembling will be put into a single <a href="#fileformat">Project File</a> (*.diz). This file contains a <em>link</em> to the ROM you are currently working on, but doesn't contain the ROM itself. This is for copyright reasons, and so you can easily share project files without worry of sharing ROM files as well. Because of this, if the ROM file you are working on is deleted or is relocated on your computer, DiztinGUIsh will ask to relocate the file. The ROM's internal name and checksum are stored to make sure you relink the same ROM you started with, but it is techincally possible to relink a different ROM. Not sure what would happen then, but it wouldn't be anything you'd want.</p>
<p>When you start DiztinGUIsh, you can start a new project or open an existing one. Opening an existing project is simple, though you may have to relink your ROM if it moved, or if you recieved this project file from a friend. When you start a new project, DiztinGUIsh will first prompt you to select a ROM file you want to work on.</p>
<h4>Starting a Project</h4>
<p>DiztinGUIsh currently supports seven types of <em>ROM Mapping Modes</em>: LoROM, HiROM, two SA-1 modes, SuperFX, ExHiROM, & ExLoROM. The program will try its best to detect what mode the ROM you selected uses. There is a chance it won't be able to figure it out, or it will guess wrong. After you select a ROM file, DiztinGUIsh will show the ROM's internal name. If this doesn't look correct, try changing the ROM Map mode.</p>
<p><em>Note: Some Japanese titles will display as gibberish, so it is possible that the correct ROM Mapping Mode will result in a garbage looking title.</em></p>
<p><em>Note: Although mapping mode 2, Super MMC, is an option, it currently functions identically to HiROM.</em></p>
<p>DiztinGUIsh also provides a few extra jumpstart options on the New Project window. The table of numbers on the bottom half of the window show the ROM's <em>vectors</em>, which are special pointers that locate code that runs under special circumstances (interrupts, bootup, etc.). By default, DiztinGUIsh will check off the vectors it thinks are important. Checking off a vector will automatically generate a label at the location of the pointer (e.g. "Native_NMI").</p>
<p>If the final checkbox is checked, DiztinGUIsh will automatically mark flags for the entire internal header. This includes the internal name, ROM meta info & mapping settings, developer codes, & the vectors.</p>
<hr />
<h3 id="tablegrid">Table Grid View</h3>
<p>In DiztinGUIsh, <em>one byte equals one row in the table</em>. Instructions will be one or more rows depending on how many operands there are. Pointers will be more than one row. Each byte has many pieces of data associated with it--these are stored in each of the table's columns.</p>
<h4>Label</h4>
<p>Here you can create a custom label for this location in the ROM. Labels are useful to identify what things are in the ROM. You can label code, data, or anything really. Labels will be automatically used in the disassembly when available.</p>
<h4>PC</h4>
<p>This column shows the "program counter" for the current byte. This is effectively the location in the SNES's address space where this byte will be found.</p>
<h4>@</h4>
<p>This column shows an ASCII representation of the current byte. Mainly useful for locating text within the ROM.</p>
<h4>#</h4>
<p>This column shows the raw byte. You can change what base this value is displayed in via the View -> Constants menu.</p>
<h4><*></h4>
<p>This column shows <em>in points, out points, end points, & read points</em>.</p>
<ul>
<li>In points are locations in ROM where execution can jump to from somewhere other than the instruction directly before it. These are denoted by a ">" symbol. In points are usually the result of a branch, jump, or call instruction.</li>
<li>Out points are locations where execution can jump elsewhere other than the instruction directly after it. These are denoted by a "<" symbol. Out points are usually the result of a branch, jump, call, or return instruction.</li>
<li>End points are special out points where execution cannot directly flow from this instruction to the next directly after. These are denoted by a "X" symbol. End points are usually the result of a jump or return instruction.</li>
<li>Finally, read points are locations in ROM that are the intermediate address of some other load/store/math instruction in the ROM. These are denoted by a "*" symbol. Read points are often the start of a table of data.</li>
</ul>
<h4>Instruction</h4>
<p>This column shows what instruction this byte would be disassembled to if it were treated as an opcode.</p>
<p>The instruction may be highlighted in yellow if DiztinGUIsh thinks the instruction is risky. That is, a rarely used instruction that more likely than not means that the code is desynched.</p>
<h4>IA</h4>
<p>This column shows the intermediate address of the instruction or pointer located at this byte. The intermediate address is basically the "address of importance" of an instruction--what address is actually being read/stored/jumped to, etc. Often, the instruction operands only specify a small chunk of the intermediate address, and the rest of it has to be inferred by other registers such as the program counter, data bank register, or direct page register. This column does all the math for you and spits out the intermediate address of the instruction. Note that this is not to be confused with the <em>effective address</em>, which is the "final result" address after locating indirect operands and/or adding index registers.</p>
<p>The intermediate address will be calculated assuming this byte is marked as an opcode--UNLESS it is marked as some sort of pointer. Then, the intermediate address will just be the value of the pointer.</p>
<p><em>Note: If the byte is marked as a 16-bit pointer, the bank of the intermediate address will be derived from the Data Bank register (B).</em></p>
<h4>Flag</h4>
<p>This column displays what kind of data this byte will be treated as.</p>
<ul>
<li><strong>Unreached</strong>: This is the default flag. Basically means unknown.</li>
<li><strong>Opcode</strong>: This byte is the opcode of an instruction. Zero or more Operands may follow it.</li>
<li><strong>Operand</strong>: This byte is an operand of an instruction. Which instruction? The one marked as an Opcode a byte or more before it.</li>
<li><strong>Data (8-bit)</strong>: Generic 8-bit (1-byte) long data.</li>
<li><strong>Graphics</strong>: Special 8-bit data specifically used as graphics. Isn't treated any differently than plain 8-bit data (<em>yet</em>).</li>
<li><strong>Music</strong>: Special 8-bit data specifically used as music. Isn't treated any differently than plain 8-bit data (<em>yet</em>).</li>
<li><strong>Empty</strong>: Special 8-bit data specifically used as empty filler. Isn't treated any differently than plain 8-bit data (<em>yet</em>).</li>
<li><strong>Data (16-bit)</strong>: Generic 16-bit (2-byte) long data.</li>
<li><strong>Pointer (16-bit)</strong>: The lower 16-bits of a pointer. The bank of the intermediate address is derived from the Data Bank register (B).</li>
<li><strong>Data (24-bit)</strong>: Generic 24-bit (3-byte) long data.</li>
<li><strong>Pointer (24-bit)</strong>: A full 24-bit pointer.</li>
<li><strong>Data (32-bit)</strong>: Generic 32-bit (4-byte) long data.</li>
<li><strong>Pointer (32-bit)</strong>: A full 24-bit pointer, followed by a filler byte. This is common so that pointers are separated by 4 bytes (a power of 2).</li>
<li><strong>Text</strong>: Special 8-bit data specifically used as ASCII text. This will be disassembled into a human-readable string.</li>
</ul>
<h4>B</h4>
<p>The value of the <em>Data Bank register</em> during execution of this code. Some instructions derive their intermediate address using the value of the data bank register. The data bank register is also used as the bank byte of a 16-bit pointer.</p>
<p>The value will be highlighted in yellow if the instruction at this location stores the data bank register (<tt>PHB</tt>). It will be highlighted in red if the instruction writes to the data bank register (<tt>PLB : MVP : MVN</tt>). This way you can be on a lookout for changes to this register.</p>
<h4>D</h4>
<p>The value of the <em>Direct Page register</em> during execution of this code. Some instructions derive their intermediate address using the value of the direct page register.</p>
<p>The value will be highlighted in yellow if the instruction at this location stores the direct page register (<tt>PHD : TDC</tt>). It will be highlighted in red if the instruction writes to the direct page register (<tt>PLD : TCD</tt>). This way you can be on a lookout for changes to this register.</p>
<h4>M</h4>
<p>The current state of the M flag in the program status register (P). When the flag is cleared (m = 0), the accumulator A is 16 bits wide. When it is set (M = 1), the accumulator A is 8 bits wide. Some instructions interpret their operands differently according to the state of the M flag. If some code is desynched or doesn't make since, try toggling the M flag.</p>
<p>The value will be highlighted in yellow if the instruction at this location stores the program status register (<tt>PHP</tt>). It will be highlighted in red if the instruction writes to the program status register and potentially modifies the M flag (<tt>PLP : REP : SEP</tt>). This way you can be on a lookout for changes to this flag.</p>
<h4>X</h4>
<p>The current state of the X flag in the program status register (P). When the flag is cleared (x = 0), the index registers X and Y are 16 bits wide. When it is set (X = 1), the index registers X and Y are 8 bits wide. Some instructions interpret their operands differently according to the state of the X flag. If some code is desynched or doesn't make since, try toggling the X flag.</p>
<p>The value will be highlighted in yellow if the instruction at this location stores the program status register (<tt>PHP</tt>). It will be highlighted in red if the instruction writes to the program status register and potentially modifies the X flag (<tt>PLP : REP : SEP</tt>). This way you can be on a lookout for changes to this flag.</p>
<h4>Comment</h4>
<p>Here you can write notes about the project. These comments will be output into the disassembly, but <em>only on bytes that start a line</em>. For example, a comment on a byte that is marked as an opcode will be written, but a comment on an operand byte will not be written.</p>
<h4>Status Bar</h4>
<p>The status bar at the bottom of the window will show the number of bytes reached, and the currently selected marking flag.</p>
<h4>Navigation</h4>
<p>Use the arrow keys to move to different cells. Page Up & Page Down will move 16 rows at a time, and Home & End will move 256 rows at a time.</p>
<p>Cells you can type in are highlighted in green.</p>
<p>Intermediate addresses of the currently selected cell will be highlighted in pink. So will instructions whose intermediate addresses are the currently selected cell.</p>
<hr />
<h3 id="stepping">Stepping</h3>
<p><strong>Hotkey: S, I</strong></p>
<p>Stepping is the method of marking bytes as code. Instead of marking each byte as opcode and operand separately, you can step through the instruction, and DiztinGUIsh will automatically assign opcode and operand flags as necessary.</p>
<p>Stepping an instruction will automatically copy the D, B, M, & X values from the previous instruction. If a <tt>REP</tt> or <tt>SEP</tt> instruction is stepped, the M and X values will be modified as necessary.</p>
<p><em>Note: Most trace logs will reflect changes to the D, B, M, & X values on the instruction after the one that modifies the register. However, DiztinGUIsh likes to show the updated values on the same row as the instruction that updates the values.</em></p>
<p>There are two stepping commands: step, and step in. Step will advance the selector to the instruction directly following this instruction. Step in will advance to the intermediate address of this instruction. This is useful for taking a branch or jumping into a routine call. Note that plain step will still step in if the instruction is a jump instruction.</p>
<hr />
<h3 id="autostep">Auto Stepping</h3>
<p><strong>Hotkey: A, Ctrl + A</strong></p>
<p>There is a lot of code in a ROM, so stepping through each instruction can be time consuming. Therefore, this option will let you step through instructions automatically until something happens.</p>
<h4>Auto Step (Safe)</h4>
<p>This is the recommended way of auto stepping. When auto step hits a branch, it will not take it. When it hits a jump, it will jump. When it hits a function call, it will save the program counter and jump to the routine. When it hits a return, it will try to restore the program counter to what it was before the call. It also saves and restores the value of the program status register and the M and X flags.</p>
<p>Basically, it pretends to execute code until it hits something it can't do. Some jump instructions refer to values in RAM, which are not kept track of. At this point, the auto step will pause and wait for you to continue it at a point that makes sense.</p>
<p>Auto Step will also stop if it hits a branch or jump that it has already seen in one go. This is to prevent it getting stuck on infinite loops. It will also stop if it hits a risky instruction--that is, a rare instruction that more likely than not means that the code is desynched. It will also stop if it hits an instruction that is already marked as something other than code.</p>
<h4>Auto Step (Harsh)</h4>
<p>This auto step will rush through bytes like a freight train and disassemble them one directly after the other. It doesn't care about jumps, branches, or anything. The only smart thing it does is updates the M and X flags upon stepping through <tt>REP</tt> and <tt>SEP</tt> instructions.</p>
<p>Because of how hardy it is, it will never stop if it hits something risky. You have to specify how many bytes to disassemble. It will also clobber over stuff that is already marked as something other than code.</p>
<hr />
<h3 id="goto">Goto</h3>
<p><strong>Hotkey: Ctrl + G, T, U, H, N</strong></p>
<p>This is an easy way to hop around the ROM without having to scroll all the way to where you want.</p>
<p>Hitting Ctrl + G will bring up the <a href="#gotowindow">Goto window</a>. You can type in a ROM address or PC offset in decimal or hex to go directly to that location.</p>
<p>You can press T to jump to the intermediate address of the currently selected instruction. Only if the intermediate address refers to ROM of course.</p>
<p>You can press U, H, or N to jump to the first unreached byte of the project, the nearest unreached block behind the selected address, or the nearest unreached block ahead of the selected address. These are useful just to get somewhere you haven't been yet.</p>
<hr />
<h3 id="marking">Marking</h3>
<p><strong>Hotkey: K, Ctrl + K, B, D, M, X</strong></p>
<p>For anything that isn't code, you will have to mark manually. You can select which flag type to mark with under the Edit -> Select Marker menu. The currently selected flag type is shown in the status bar at the bottom of the window.</p>
<p>Pressing K will mark a single instance of that flag type. That is, 8-bit data will mark 1 byte at a time, 16-bit data 2 bytes at a time, etc.</p>
<p>You can press Ctrl + K to bring up a window that lets you mark an entire range at once. You can specify ROM address or PC offset, in hex or decimal, and you can specify the range via start & end points, or just the number of bytes to mark.</p>
<p>Pressing B, D, M, or X will jump the selected cell to the data bank, direct page, M flag, or X flag cell respectively. You can hold Ctrl while pressing one of these keys to bring up the same window as Ctrl + K with default options to mark that value.</p>
<hr />
<h3 id="labelcomment">Labels and Comments</h3>
<p><strong>Hotkey: L, C</strong></p>
<p>Pressing L will jump the selected cell to the label cell automatically so you can add a label to this byte. Pressing C will do the same for the comment column.</p>
<h4>Valid Labels</h4>
<p>Asar has a limitation on what characters can make up a label, and DiztinGUIsh follows the same format. Currently, labels must only contain the following characters:</p>
<p><tt>a-z A-Z 0-9 _</tt></p>
<p>Characters within a label that don't fit this description will be converted to <tt>_</tt>s.</p>
<p>DiztinGUIsh currently does not support sublabels (starting with a <tt>.</tt>), or +/- labels (made of <tt>+ -</tt> characters).</p>
<p>DiztinGUIsh also currently does not check for duplicate labels; that is, two more more addresses with the same label. For now, please use the <a href="#labellist">Label List</a> to check for any duplicate labels.</p>
<hr />
<h3 id="desynching">Misalignments & Desynching</h3>
<p><strong>Hotkey: Ctrl + F</strong></p>
<p><em>Desynching</em> refers to incorrect instructions being disassembled due to opcodes being marked as operands and vice versa. Some instructions have a different amount of operand bytes associated with them depending on the state of the M and X flags. If these flags are assumed incorrectly, the size of the instruction will be assumed incorrectly, causing a byte that should be an operand being treated as an opcode or vice versa.</p>
<p>Sometimes desynched instructions are hard to catch. In fact, they can be disassembled and reassembled, and you wouldn't even notice. The SNES CPU would just execute the code as it would normally; it just wouldn't match what the disassembly says. For example, take the following bytecode: <tt>A9 00 8D 85 00</tt>. This could be <tt>LDA #$00 : STA $0085</tt> or it could be <tt>LDA #$8D00 : STA $00</tt>. Both are perfectly legitimate, but only one is correct.</p>
<p>A common cause of desynched code in DiztinGUIsh has to do with stepping through code while the X and M flags are incorrect. Sometimes, bytes can be marked as opcodes and operands incorrectly that accidentally overwrite already marked bytes.</p>
<p>In DiztinGUIsh, <em>misalignment</em> refers to bytes that are marked incorrectly, due to the length of the instruction or data not matching the flags. For example, the <tt>TAX</tt> instruction has no operands. But if the byte following this instruction is marked as an operand, this is a misalignment. Misalignments can also occur with data and pointers. If there is a block of 9 bytes marked as 16-bit data, there is a misalignment somewhere since the number of bytes is odd.</p>
<p>The Misaligned Flags checker window will look for misalignments. You can just scan the ROM without actually modifying anything. Misalignments will be identified and output into the text box so you can correct them manually. You can also just have DiztinGUIsh attempt to fix all misalignments automatically. It uses a pretty brute force method, so it may not produce correct results, but at least it will get rid of all misalignments.</p>
<p>It is recommended to scan for misalignments before outputting a disassembly.</p>
<hr />
<h3 id="inoutpoints">In/Out/End/Read Points</h3>
<p><strong>Hotkey: Ctrl + P</strong></p>
<p>As DiztinGUIsh steps through instructions, it will mark <a href="#tablegrid">in points, out points, end points, and read points</a>. However, marking bytes as opcode and operand manually will not produce these points. Importing CDLs will also not generate points. Also, once a byte is marked with a point, you can't unmark it.</p>
<p>The Rescan for In/Out Points window will clear all points and readd them using the current flags.</p>
<p>It is recommended to rescan for in/out/end/read points before outputting a disassembly.</p>
<hr />
<h3 id="hotkeys">Keyboard Hotkeys</h3>
<p>Pretty much everything has a hotkey associated with it, so you can use the entire program with the keyboard. Note that hotkeys won't work when the selected cell is editable, as typing anything will just put it into the box.</p>
<ul>
<li><strong>Ctrl + N</strong>: New Project</li>
<li><strong>Ctrl + O</strong>: Open Project</li>
<li><strong>Ctrl + S</strong>: Save Project</li>
<li><strong>Ctrl + Shift + S</strong>: Save Project As</li>
<li><strong>Ctrl + E</strong>: Export Disassembly</li>
<li><strong>Ctrl + I</strong>: Import CDL <em>Not supported yet</em></li>
<li><strong>Alt + F4</strong>: Exit</li>
<li><strong>S</strong>: Step</li>
<li><strong>I</strong>: Step In</li>
<li><strong>A</strong>: Auto Step (Safe)</li>
<li><strong>Ctrl + A</strong>: Auto Step (Harsh)</li>
<li><strong>Ctrl + G</strong>: Goto</li>
<li><strong>T</strong>: Goto Intermediate Address</li>
<li><strong>U</strong>: Goto First Unreached</li>
<li><strong>H</strong>: Goto Previous Unreached</li>
<li><strong>N</strong>: Goto Next Unreached</li>
<li><strong>Alt + U</strong>: Select Unreached Marker</li>
<li><strong>Alt + O</strong>: Select Opcode Marker</li>
<li><strong>Alt + P</strong>: Select Operand Marker</li>
<li><strong>Alt + 1</strong>: Select 8-Bit Data Marker</li>
<li><strong>Alt + G</strong>: Select Graphics Marker</li>
<li><strong>Alt + M</strong>: Select Music Marker</li>
<li><strong>Alt + E</strong>: Select Empty Marker</li>
<li><strong>Alt + 2</strong>: Select 16-Bit Data Marker</li>
<li><strong>Alt + W</strong>: Select Word Pointer Marker</li>
<li><strong>Alt + 3</strong>: Select 24-Bit Data Marker</li>
<li><strong>Alt + L</strong>: Select Long Pointer Marker</li>
<li><strong>Alt + 4</strong>: Select 32-Bit Data Marker</li>
<li><strong>Alt + D</strong>: Select DWord Pointer Marker</li>
<li><strong>Alt + T</strong>: Select Text Marker</li>
<li><strong>K</strong>: Mark One</li>
<li><strong>Ctrl + K</strong>: Mark Many</li>
<li><strong>L</strong>: Add Label</li>
<li><strong>B</strong>: Set Data Bank</li>
<li><strong>Ctrl + B</strong>: Set Many Data Bank</li>
<li><strong>D</strong>: Set Direct Page</li>
<li><strong>Ctrl + D</strong>: Set Many Direct Page</li>
<li><strong>M</strong>: Toggle M Flag</li>
<li><strong>Ctrl + M</strong>: Set Many M Flag</li>
<li><strong>X</strong>: Toggle X Flag</li>
<li><strong>Ctrl + X</strong>: Set Many X Flag</li>
<li><strong>C</strong>: Add Comment</li>
<li><strong>Ctrl + F</strong>: Fix Misaligned Flags</li>
<li><strong>Ctrl + P</strong>: Rescan for In/Out Points</li>
<li><strong>Ctrl + V</strong>: View Visual Map <em>Not supported yet</em></li>
<li><strong>Ctrl + W</strong>: View Graphics Window <em>Not supported yet</em></li>
<li><strong>Alt + C</strong>: View Constants in Decimal</li>
<li><strong>Alt + H</strong>: View Constants in Hexadecimal</li>
<li><strong>Alt + B</strong>: View Constants in Binary</li>
<li><strong>F1</strong>: View Help</li>
</ul>
<hr />
<h2 id="gotowindow">Goto Window</h2>
<p>Using this window you can select any byte in the ROM without having to scroll all the way to it.</p>
<hr />
<h3 id="romvspc">ROM Address vs PC Offset</h3>
<p>The ROM address, also known as the SNES offset, is the location in the SNES's address space where the byte is located.</p>
<p>The PC offset is the raw offset of the byte in the ROM file. The first byte has an offset of 0. The ROM is always treated as unheadered, even if the ROM linked to the project has an SMC header.</p>
<hr />
<h3 id="hexvsdec">Hexadecimal vs Decimal</h3>
<p>Hexadecimal is a base 16 counting system. It is what most hex editors use for displaying offsets, since 16 is a power of 2.</p>
<p>Decimal is a base 10 counting system.</p>
<p><em>Note: Using decimal to specify the ROM address is silly, I've found.</em></p>
<hr />
<h2 id="markmany">Mark Many Window</h2>
<p>This window lets you set flags and registers for more than one byte at a time.</p>
<hr />
<h3 id="propertyvalue">Property & Value</h3>
<p>You can choose which property to modify, and what value to give for the entire specified range.</p>
<p>The property field will default to a different setting depending on what hotkey you used to open the window.</p>
<hr />
<h3 id="addressrange">Address Range</h3>
<p>See the <a href="#gotowindow">Goto Window</a> for info on ROM vs PC and Hex vs Dec.</p>
<p>Changing the bounds of the range will automatically update the number of bytes and vice versa. If the values you input go past the end of the ROM, they will snap to the end of the ROM.</p>
<hr />
<h2 id="misalignedflags">Fix Misaligned Flags Window</h2>
<p>See <a href="#desynching">Misalignments & Desynching</a>.</p>
<hr />
<h2 id="rescanpoints">Rescan for In/Out Points Window</h2>
<p>See <a href="#inoutpoints">In/Out/End/Read Points</a>.</p>
<hr />
<h2 id="labellist">Label List Window</h2>
<p>This window shows every single label that has been created, and the address it is associated with. Labels in this list will automatically be updated, added, or removed when they are modified via the Main Window. You can also add, remove, or edit them from this window. The labels can be sorted by address or name by clicking on the table header.</p>
<h4>Jump to</h4>
<p>Clicking on this button will jump to the location of this label in the Main Window.</p>
<h4>Import...</h4>
<p>Use this to import a *.csv file with a list of labels in the format described below. This is useful if you have an external program that generates labels for you.</p>
<p>Importing labels will add them to the current list. If a label in the new list already exists in the current list it will be overwritten by the new label name.</p>
<h4>Export...</h4>
<p>This will export a *.csv file with all of the current labels. The format is quite simple; each label is one line in the CSV file, formatted as such:</p>
<p><tt>snes_address,label_name</tt></p>
<p>Note: Since neither the address nor the label should contain spaces or quotation marks, DiztinGUIsh will expect no quotation marks surrounding either field.</p>
<h4>Label Table</h4>
<p>Pretty self-explanitory--the first column is the SNES address that the label name in the second column corresponds to.</p>
<p>You can modify labels by double-clicking on them. Hitting the <tt>del</tt> key will delete a label. You can even select more than one at once to delete. To add a label, just add the address and label name to the empty row at the end of the table. Make sure the address is a valid 24-bit address in hexadecimal, that the address you enter isn't already in the list, and that the label name contains only valid characters. See <a href="labelcomment">here</a> for what makes a valid label name.</p>
<p>Since DiztinGUIsh currently does not prevent you from reusing a label name more than once, it will warn you of duplicates by highlighting the rows that contain duplicate label names in yellow.</p>
<hr />
<h2 id="disassembly">Export Disassembly Window</h2>
<p>This window lets you set the options for outputting a disassembly that can reassembled by Asar.</p>
<hr />
<h3 id="outputformat">Output Format</h3>
<p>This box lets you choose how each line of the disassembly will be formatted. There are several types of arguments you can specify. Arguments are put inbetween percent signs (%). Some arguments can be followed by a length parameter, which is defined by a colon (:) and then a number. A positive number will align the argument to the left; negative will align to the right.</p>
<ul>
<li><strong>*</strong>: Anything that isn't an argument will be output directly into the line.</li>
<li><strong>%%</strong>: Output a percent sign.</li>
<li><strong>%label:length%</strong>: Output the label for this line. Default length of -22.</li>
<li><strong>%code:length%</strong>: Output the instruction, data, pointer, etc. for this line. This is where assembler directives will appear as well. Default length of 37.</li>
<li><strong>%ia%</strong>: Output the intermediate address of this instruction or pointer if applicable. Forced length of 6.</li>
<li><strong>%pc%</strong>: Output the ROM address of this code. Forced length of 6.</li>
<li><strong>%offset%</strong>: Output the PC offset of this code. Forced length of -6.</li>
<li><strong>%bytes%</strong>: Output the bytecode of this instruction. Forced length of 8.</li>
<li><strong>%comment:length%</strong>: Output the comment for this line.</li>
<li><strong>%b%</strong>: Output the Data Bank register for this line. Forced length of 2.</li>
<li><strong>%d%</strong>: Output the Direct Page register for this line. Forced length of 4.</li>
<li><strong>%m:length%</strong>: Output the M flag for this line. Default length of 1. If length is 1, it will output "M" when set and "m" when cleared. Otherwise, it will output "08" or "16".</li>
<li><strong>%x:length%</strong>: Output the X flag for this line. Default length of 1. If length is 1, it will output "X" when set and "x" when cleared. Otherwise, it will output "08" or "16".</li>
</ul>
<hr />
<h3 id="unlabeled">Unlabeled Instructions</h3>
<p>This controls how DiztinGUIsh will output lines that have no labels.</p>
<ul>
<li><strong>Create All</strong>: Temporary labels will be added to every line.</li>
<li><strong>In Points Only</strong>: Temporary labels will only be added to in points and read points.</li>
<li><strong>None</strong>: No extra labels will be added.</li>
</ul>
<hr />
<h3 id="bankstructure">Bank Structure</h3>
<p>This controls the structure of the output disassembly.</p>
<ul>
<li><strong>All in one file</strong>: The disassembly will be contained within one, potentially large file.</li>
<li><strong>One bank per file</strong>: Each bank will be put in a separate bank_*.asm file. A file called main.asm will be created as the root file, and a file called labels.asm will be created to store all label assignments (e.g. RAM addresses).</li>
</ul>
<hr />
<h3 id="maxdatabytes">Max Data Bytes Per Line</h3>
<p>This controls the maximum number of bytes output per line on bytes marked as data.</p>
<p>This is actually not the max, but the "min-max"--a maximum of 5 bytes will still allow two 32-bit data elements (total of 8 bytes) per line. A maximum of 4 bytes will limit this to one 32-bit data element (4 bytes). In other words, a data element will not be split over two lines.</p>
<hr />
<h3 id="asarassembly">Reassembly with Asar</h3>
<p>If DiztinGUIsh outputs a disassembly without any warnings, it should <em>always</em> be assemblable with Asar. The code may be desynched or flagged incorrectly, but it should still assemble at least. You can assemble a disassembly via the command <tt>asar.exe [name].asm [output].sfc</tt>, where [name] is the disassembly file (or main.asm if output to multiple files).</p>
<p>In theory if the world were perfect, the reassembled ROM should match the original ROM. Sometimes it will, and sometimes it won't. It depends on the code itself. The output should always <em>run</em> similarly (unless the ROM has built-in modification or checksum detection).</p>
<p>The reason this may not be the case is due to mirroring, and the way DiztinGUIsh deals with labels. Take the following two code snippets: <tt>JML $C00054 : JML $400054</tt>. One has an intermediate address of <tt>$C00054</tt> and the other has intermediate address <tt>$400054</tt>. These two addresses refer to the same byte in the ROM due to memory mapping mirroring. That is, they both refer to PC offset <tt>0x54</tt>. Currently, DiztinGUIsh stores labels according to PC offset, not ROM address. So when disassembled, these instructions will be given the same label, and they will be assembled to the exact same instruction.</p>
<p>This will be changed in a future update, along with the ability to assign labels to non-ROM addresses (addresses that don't refer to a PC offset). So sit tight, this will be fixed soon.</p>
<hr />
<h2 id="fileformat">Project File Format</h2>
<p>This section is mainly for my benefit so I can make sure I deal with project files correctly, but you can use this to build/read from *.diz and *.dizraw project files.</p>
<p>All *.diz files are compressed and decompressed with the C# GZipStream. (This means you can rename a *.diz to a *.gz and extract the original file!)</p>
<p>All *.dizraw files are uncompressed. Choose this option if you want to easily modify project files in an external program.</p>
<hr />
<h3 id="version01">Version 01</h3>
<ul>
<li>1 byte: project file version (always 01)</li>
<li>11 bytes: ASCII "DiztinGUIsh"</li>
<li>244 bytes: reserved for project info</li>
<li>1 byte: ROM Map Mode (00 = LoROM, 01 = HiROM, 02 = ExHiROM, 03 = SA-1, 04 = ExSA-1, 05 = SuperFX, 06 = Super MMC, 07 = ExLoROM)</li>
<li>1 byte: ROM Speed (00 = SlowROM, 01 = FastROM)</li>
<li>1 int: ROM Size in bytes; call this [size]</li>
<li>21 bytes: ROM Internal Name ($00FFC0 - $00FFD4)</li>
<li>4 bytes: ROM Internal Checksum ($00FFDC - $00FFDF)</li>
<li>null-terminated string: Absolute path to ROM file</li>
<li>[size] bytes: Data Bank register for each byte in ROM</li>
<li>[size] bytes: Direct Page register (low byte) for each byte in ROM</li>
<li>[size] bytes: Direct Page register (high byte) for each byte in ROM</li>
<li>[size] bytes: X Flag for each byte in ROM (0 for clear, 1 for set)</li>
<li>[size] bytes: M Flag for each byte in ROM (0 for clear, 1 for set)</li>
<li>
[size] bytes: Flag for each byte in ROM
<ul>
<li>Unreached = 0x00</li>
<li>Opcode = 0x10</li>
<li>Operand = 0x11</li>
<li>Data8Bit = 0x20</li>
<li>Graphics = 0x21</li>
<li>Music = 0x22</li>
<li>Empty = 0x23</li>
<li>Data16Bit = 0x30</li>
<li>Pointer16Bit = 0x31</li>
<li>Data24Bit = 0x40</li>
<li>Pointer24Bit = 0x41</li>
<li>Data32Bit = 0x50</li>
<li>Pointer32Bit = 0x51</li>
<li>Text = 0x60</li>
</ul>
</li>
<li>[size] bytes: Archetecture for each byte in ROM <em>(currently always 00, or things will break)</em></li>
<li>
[size] bytes: In/Out/End/Read Point for each byte in ROM (bitwise - can be combined)
<ul>
<li>InPoint = 0x01</li>
<li>OutPoint = 0x02</li>
<li>EndPoint = 0x04</li>
<li>ReadPoint = 0x08</li>
</ul>
</li>
<li>1 int: number of labels; call this [labelcount]</li>
<li>
[labelcount] of struct:
<ul>
<li>1 int: SNES address of this label</li>
<li>null-terminated string: the label</li>
</ul>
</li>
<li>1 int: number of comments; call this [commentcount]</li>
<li>
[commentcount] of struct:
<ul>
<li>1 int: SNES address of this comment</li>
<li>null-terminated string: the comment</li>
</ul>
</li>
</ul>
<h3 id="version00">Version 00</h3>
<p>Version 00 stored comments' and labels' locations via PC offset instead of SNES address. For more info, check the Github repository history for this help file <a href="https://github.com/Dotsarecool/DiztinGUIsh/commits/master/help.html">here</a>.</p>
<hr />
</body>
</html>