1
0
mirror of https://github.com/fadden/6502bench.git synced 2025-02-06 08:30:04 +00:00

Update tutorial

Two main changes:
 - "Seek nearby targets" is no longer enabled by default.
 - The application asks the user to save new projects immediately.

Various minor edits were also made.

A couple of the images are slightly stale, showing ".org" rather than
".addrs", but they're in the advanced section and the difference
isn't notable.
This commit is contained in:
Andy McFadden 2024-08-19 13:00:50 -07:00
parent 5544014b71
commit eef1710d5d
14 changed files with 105 additions and 86 deletions

View File

@ -2111,7 +2111,6 @@ namespace SourceGen {
/// <summary>
/// Returns the next redo operation, and moves the pointer to the next item.
/// </summary>
/// <returns></returns>
public ChangeSet PopRedoSet() {
if (!CanRedo) {
throw new Exception("Can't redo");

View File

@ -152,13 +152,13 @@ CopyData lda #&lt;addrs ;get pointer into
<p>The process can be improved by keeping track of the flags in the
6502 status register. For example, in the code fragment shown
earlier, <code>BMI</code> conditional branch instruction is used.
earlier, the <code>BMI</code> conditional branch instruction is used.
A simple tracing algorithm would both follow the branch and fall
through to the following instruction. However, the code that precedes
the <code>BMI</code> ensures that the branch is always taken, so a
clever disassembler would only trace that path.</p>
<p>(The situation is worse on the 65816, because the length of
<p>(This is even more important on the 65816, because the length of
certain instructions is determined by the values of the processor
status flags.)</p>

View File

@ -96,7 +96,8 @@
<samp>Select File</samp> and navigate to the 6502bench Examples directory.
In the "A2-Amper-fdraw" directory, select the file "AMPERFDRAW#061d60"
(just ignore the existing .dis65 file).
Click <samp>OK</samp> to create the project.</p>
Click <samp>OK</samp> to create the project. Click <samp>Cancel</samp>
to skip saving the project file.</p>
</div>
</div>
@ -145,7 +146,7 @@
<div class="grid-item-text">
<p>As it happens, the start address of the code
is $1D60 -- the last four digits of the filename -- so let's make that
change. Double-click the initial <code>.ORG</code> statement,
change. Double-click the initial <code>.ADDRS</code> statement,
and change it from $2000 to $1D60. We can now see that $1D70 starts
right after this initial chunk of code.</p>
</div>
@ -212,7 +213,7 @@
<code>&lt;FUNC-152</code>, you forgot to select the high part.)</p>
<p>We've now changed the first entry in the address table to a
symbolic reference, which is helps someone reading the code to
symbolic reference, which will help someone reading the code to
understand what is being referenced. You could repeat these
steps (tag as code, set label, change address bytes to symbols)
for the remaining items, but there's an easier way.</p>

View File

@ -87,9 +87,10 @@
<div class="grid-container">
<div class="grid-item-text">
<p>This tutorial will walk you through some of the fancier things SourceGen
can do. We assume you've already finished the basic features tutorial,
and know how to create projects and move around in them.</p>
<p>This part of the tutorial will walk you through some of the
fancier things SourceGen can do. We assume you've already finished
the basic features tutorial, and know how to create projects and move
around in them.</p>
<p>Start a new project. Select <samp>Generic 6502</samp>. For the
data file, navigate to the Examples directory, then from the Tutorial
directory select "Tutorial2".</p>

View File

@ -105,10 +105,11 @@
<img src="images/t1-data-editdlg-1.png" alt="t1-data-editdlg-1"/>
</div>
<div class="grid-item-text">
<p>Select the last line in the file, then <samp>Actions &gt; Edit Operand</samp>.
You'll notice that this dialog is much different from the one you got when editing
the operand of an instruction. At the top it will say "<samp>65 bytes
selected</samp>". You can format this as a single 65-byte string, as 65 individual
<p>Select the last line of data in the file ($2030), then
<samp>Actions &gt; Edit Operand</samp>. You'll notice that this dialog
is much different from the one you got when editing the operand of an
instruction. At the top it will say "<samp>65 bytes selected</samp>".
You can format this as a single 65-byte string, as 65 individual
items, or various things in between. For now, select <samp>Single bytes</samp>,
and then on the right, select <samp>ASCII (low or high) character</samp>.
Click <samp>OK</samp>.</p>

View File

@ -93,7 +93,9 @@
<p>An earlier tutorial demonstrated how to manually mark bytes as
inline data. We're going to do it a faster way. For this tutorial,
start a new project with the <samp>Generic 6502</samp> profile, and
in the SourceGen Examples/Tutorial directory select "Tutorial4".</p>
in the SourceGen Examples/Tutorial directory select "Tutorial4" as
the data file.
You can choose to save the project file or not.</p>
<!--<p>We'll need to load scripts from the project directory, so we have to
save the project. <samp>File &gt; Save</samp>,
use the default name ("Tutorial4.dis65").</p>-->
@ -125,9 +127,10 @@
</div>
<div class="grid-item-text">
<p>Nothing happened. If you look at the script with an editor (and you
know some C#), you'll see that it's looking for a <code>JSR</code> to a
function that begins with certain prefixes. For ASCII length-delimited
strings, the prefix is <code>InA1_</code>. So let's set a label.</p>
know some C#), you'll see that it's looking for <code>JSR</code>
instructions that call functions whose names begin with certain strings.
For ASCII strings prefixed with a 1-byte length, the appropriate
function name prefix is <code>InA1_</code>. So let's set a label.</p>
</div>
</div>
@ -149,9 +152,9 @@
<div class="grid-item-text">
<p>This time, double-click the <code>JSR</code> <i>operand</i>
("<samp>L1036</samp>") to edit the operand.
Click <samp>Create Label</samp>, and enter <kbd>InA1_PrintString</kbd>.
Remember that labels are case-sensitive;
you must enter it exactly as shown. Hit <samp>OK</samp> to accept the label,
Click <samp>Create Label</samp>, and enter "<kbd>InA1_PrintString</kbd>".
Remember that labels are case-sensitive; you must enter it exactly
as shown (note the lower-case 'n'). Hit <samp>OK</samp> to accept the label,
and <samp>OK</samp> to close the operand editor.</p>
</div>
</div>
@ -177,9 +180,9 @@
<p>Double-click the operand on line $100D ("<code>L1037</code>"),
click <samp>Create Label</samp>,
and set the label to "<kbd>InAZ_PrintString1</kbd>".
Hit <samp>OK</samp> twice. That formatted the first one and got us
to the next <code>JSR</code>, at $1019. Repeat the process on line $1019
("<code>L1038</code>"), setting the label to
Hit <samp>OK</samp> twice. That formatted the string that followed,
and got us to the next <code>JSR</code>, at $1019. Repeat the
process on line $1019 ("<code>L1038</code>"), setting the label to
"<kbd>InAZ_PrintString2</kbd>".</p>
</div>
</div>
@ -192,14 +195,14 @@
<p>The last <code>JSR</code>, at $1025, is followed by a 16-bit
pointer. Edit the operand, and use <samp>Create Label</samp> to
set the label at the target address to "<kbd>InWA_StringPtr</kbd>".
Because the bytes were formatted as an address and not a just a
16-bit value, a label was generated automatically.</p>
This causes the two bytes to be formatted as a 16-bit address,
rather than just a 16-bit value, so a label was generated
automatically at the target address ("<code>L102B</code>").</p>
<p>What we'd really like to do in this case is to have it format the
16-bit address as a pointer, and format the data it points to as
a null-terminated string. The StdInline script doesn't know how to
do that though, so you'd need to write a custom script. (Scripts
can format multiple data items, add symbolic references to labels
<p>It would be even more helpful if it formatted the data at $102B
as a null-terminated string. The basic StdInline script doesn't
happen to do that, but it's possible to do it with a custom script.
(Scripts can format multiple data items, add symbolic references to labels
and constants, and chase pointers around.)</p>
<p>The entire project is now nicely formatted. In a real project the
@ -207,7 +210,9 @@
instructions. There would likely be multiple <code>JSR</code>s to the print function,
so labeling a single function entry point could format dozens of inline
strings and clean up the disassembly automatically. The reason for
allowing wildcard names is that some functions may have multiple
using name prefixes like <code>InAZ_</code>, rather than full function
names, is that there may be more than one function with the same stack
mechanics. Also, some functions may have multiple
entry points or chain through different locations.</p>
</div>
</div>

View File

@ -94,13 +94,13 @@
can greatly improve the readability of the code: something like
<code>JSR DrawSprite</code> is far more helpful for human readers.
Further, once the code has been disassembled to source code, using symbols
instead of fixed addresses makes it easier to alter the program or re-use
the code.</p>
instead of fixed addresses makes it easier to alter the program or reuse
the code in another project.</p>
<p>When the target address of instructions like <code>JSR</code> and
<code>LDA</code> falls within the scope of the data file, SourceGen classifies
the reference as <i>internal</i>, and automatically adds a generic
symbolic label (e.g. <code>L1000</code>). This can be edited if desired.</p>
symbolic label (e.g. <code>L1000</code>). The label can be edited if desired.</p>
</div>
</div>
@ -367,7 +367,7 @@
button is selected automatically if you start a label with '@' (or
whatever character you have configured). Click <samp>OK</samp>.</p>
<p>You now have two lines with the same label. In some cases the
assembly source generator need to may "promote" them to globals, or
assembly source generator may need to "promote" them to globals, or
rename them to make them unique, depending on what your preferred assembler
allows.</p>
</div>

View File

@ -91,7 +91,7 @@
</div>
<div class="grid-item-text">
<p>Let's move on to the code at $203D. It starts by storing a couple of
values into direct page address $02/03. This appears to be setting up a
values into zero page addresses $02/03. This appears to be setting up a
pointer to $2063, which is a data area inside the file. So let's make it
official.</p>
</div>
@ -158,8 +158,8 @@
<img src="images/t2-20a7.png" alt="t2-20a7"/>
</div>
<div class="grid-item-text">
<p>Double-click on the <code>JSR</code> opcode on line $2045 to jump to
<samp>L20A7</samp>.
<p>Double-click on the <code>JSR</code> opcode on line $2045 to jump
way down to <samp>L20A7</samp>.
The code here just loads a value from $3000 into the accumulator
and returns, so not much to see here. Hit the back-arrow in the
toolbar to jump back to the <code>JSR</code>.</p>
@ -256,7 +256,8 @@
<samp>Edit &gt; Settings</samp> to open the app settings panel.
In the <samp>Miscellaneous</samp> group on the right side, click the
<samp>Show cycle counts for instructions</samp> checkbox, then click
<samp>OK</samp>. (There's also a toolbar button for this.)</p>
<samp>OK</samp>. (There's also a toolbar button that toggles it
on and off.)</p>
</div>
</div>
@ -287,7 +288,8 @@
The following instruction, <code>ORA #$80</code>, cleared the 'Z' flag and
set the 'N' flag, so a <code>BMI</code> would also be an always-taken branch.)</p>
<p>The cycle-count comments can be added to generated source code as well.</p>
<p>The cycle-count comments can be added to generated source code as well,
with an application setting in the <code>Asm Config</code> tab.</p>
<p>If you add an end-of-line comment, it appears after the cycle count.
(Try it.)</p>
</div>

View File

@ -146,7 +146,7 @@
window on the bottom left. Notes are like long comments, with three key
differences:</p>
<ol>
<li>You can't pick their line width, but you can pick their color.</li>
<li>You can't really format the text, but you can pick their color.</li>
<li>They don't appear in generated assembly sources, making them
useful for leaving notes to yourself as you work.</li>
<li>They're listed in the Notes window. Double-clicking them jumps

View File

@ -99,7 +99,7 @@
<li>Symbols. All known symbols. The buttons at the top allow you
to filter out symbol types that you're not interested in.</li>
<li>Info. Information about the selected line. For code, this
will have a summary of the instruction.</li>
will include a summary of the instruction's behavior.</li>
</ol>
</div>
</div>
@ -151,8 +151,9 @@
<li>Address 1017 and label L1017 were highlighted. When you select
a line with an operand that targets an in-file address, the target
address is highlighted.</li>
<li>An entry appeared in the References window. This tells you that the
only reference to L1002 is a branch from address $100B.</li>
<li>An entry appeared in the References window. This tells you
that the only reference to L1002 is a branch from address $1009. The
branch operand on line $1009 was also highlighted.</li>
<li>The Info window filled with a bunch of text that describes the
line format and some details about the LDA instruction.</li>
</ul>
@ -224,9 +225,10 @@
on opcodes or lines in the side windows, the locations are added to a
navigation history. The arrows let you move forward and backward
through it.</p>
<p>The "Nav Backward" feature is bound to the 4th button found on some
mice (usually found on the side, activated with the thumb). This can
be used to navigate quickly through a project using only the mouse.</p>
<p>The "Nav Backward" feature is usually bound to the 4th button found
on some mice (generally found on the side, activated with the thumb).
This can be used to navigate quickly through a project using only the
mouse.</p>
</div>
</div>

View File

@ -141,17 +141,11 @@
<div class="grid-item-text">
<p>Continuing on, the code at $2086 touches a few consecutive locations
that have auto-generated labels.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2081-stuff.png" alt="t2-2081-stuff"/>
</div>
<div class="grid-item-text">
<p>Edit the label on line $2081, setting it to <kbd>STUFF</kbd>.
Notice how the references to $2081 through $2084 have changed from
auto-generated labels to references to <code>STUFF</code>.</p>
The operand label on line $2086 also changed. But what if we want
to treat these as a single four-byte item?</p>
</div>
</div>
</div>
@ -160,25 +154,34 @@
<img src="images/t2-seek-nearby.png" alt="t2-seek-nearby"/>
</div>
<div class="grid-item-text">
<p>For some projects this may be undesirable. Use
<samp>Edit &gt; Project Properties</samp>, then in the
<samp>Analysis Parameters</samp> box un-check
<p>Use <samp>Edit &gt; Project Properties</samp>, then in the
<samp>Analysis Parameters</samp> box check
<samp>Seek nearby targets</samp>, and click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2081-stuff.png" alt="t2-2081-stuff"/>
</div>
<div class="grid-item-text">
<p>You'll notice that the references to $2081 and later have switched
back to auto labels. If you scroll up, you'll see that the references to
<p>You'll notice that the references to $2081 and later are now
also references to <code>STUFF</code>. The nearby-target behavior
is often useful, because it lets you avoid explicitly labeling every
part of a multi-byte data item. References to the byte before
a string or array are automatically resolved to <code>LABEL-1</code>.
You can use <samp>Edit &gt; Undo</samp> to turn it back off:
changes to project properties are added to the undo/redo buffer
just like any other change to the project.</p>
<p>(This feature used to be enabled by default, but is now
disabled for new projects because it can be more distracting than
helpful for some types of code.)
<p>If you scroll up, you'll see that the references to
<code>PTR1+1</code> and <code>PTR2+1</code> were
not affected, because local variables use explicit widths rather
than the "nearby" logic.</p>
<p>The nearby-target behavior is generally desirable, because it lets you
avoid explicitly labeling every part of a multi-byte data item. For now,
use <samp>Edit &gt; Undo</samp> to switch it back on.
(Changes to project properties are added to the undo/redo buffer
just like any other change to the project.)</p>
than the "nearby target" logic.</p>
</div>
</div>
@ -187,10 +190,11 @@
<img src="images/t2-2092.png" alt="t2-2092"/>
</div>
<div class="grid-item-text">
<p>The code at $2092 looks a bit strange. <code>LDX</code>, then a
<code>BIT</code> with a weird symbol, then another <code>LDX</code>. If
you look at the "bytes" column, you'll notice that the three-byte
<code>BIT</code> instruction has only one byte on its line.</p>
<p>While we're here, the code at $2092 looks a bit strange.
<code>LDX</code>, then a <code>BIT</code> with a weird symbol, then
another <code>LDX</code>. If you look at the "Bytes" column, you'll
notice that the three-byte <code>BIT</code> instruction has only one
byte on its line.</p>
</div>
</div>
@ -199,9 +203,9 @@
<p>The trick here is that the <code>LDX #$01</code> is embedded inside the
<code>BIT</code> instruction. When the code runs through here, X is set
to $00, then the <code>BIT</code> instruction sets some flags, then the
<code>STA</code> runs. Several lines down there's a <code>BNE</code>
to $2095, which is in the middle of the <code>BIT</code> instruction.
It loads X with $01, then also continues to the <code>STA</code>.</p>
following <code>STA</code> runs. Several lines down at $20A4 there's a
<code>BNE</code> to $2095, which is in the middle of the <code>BIT</code>
instruction. It loads X with $01, then also continues to the <code>STA</code>.</p>
<p>Embedded instructions are unusual but not unheard-of. (This trick is
used extensively in Microsoft BASICs, such as Applesoft.) When you see the
extra symbol in the opcode field, you need to look closely at what's going

View File

@ -93,12 +93,14 @@ suggestions to help you on your way.</p>
disassembled code before, this is the time to play with different
conventions, like whether to use MixedCase or underscore_separated
or SCREAMING_CAPS for labels.</li>
<li>Use the program thoroughly. Understand all of what it does.</li>
<li>Use the program you're disassembling thoroughly before you start.
Understand all of what it does.</li>
<li>Start with easily identifiable subroutines. If a chunk of code is
reading from the keyboard, you can make reasonable guesses about the
purpose of the code that interacts with it.
The start of the program is often the hardest place to begin, because it
usually just initializes a bunch of stuff you haven't identified.</li>
usually just initializes a bunch of stuff you haven't identified.
Work bottom-up.</li>
<li>Expect to figure out little pieces. Use what you learn from these
to figure out other little pieces. It's a jigsaw puzzle, not a book.</li>
<li>Don't get discouraged if there's a ton of code that you can't make
@ -114,8 +116,8 @@ Begin each project by finding the code. Identify external
entry points, format tables of addresses, and find JSRs that are
followed by inline data. Use an extension script to handle the
inlines so you won't keep tripping over them. If parts of the program
are relocated to a different address, set the appropriate address
overrides.</p>
are relocated to a different address, create the appropriate address
regions.</p>
<p>Code start tags are rarely needed, and code end tags are almost
never needed. You shouldn't have to spend a lot of time manually
tagging things. If a piece of code isn't being found, it's usually

View File

@ -176,11 +176,12 @@
<div class="grid-container">
<div class="grid-item-text">
<p>The first thing you should do after creating a new project is save it.
<p>You will be asked to save the project file.
Some features create or load files from the directory where the project
file lives, so we want to establish that. Use <samp>File &gt; Save</samp>
or <kbd class="key">Ctrl+S</kbd> to save it, with the default name
(<kbd>Tutorial1.dis65</kbd>), in the directory where the data file lives.</p>
file lives, so we want to establish where that is. It also enables the
optional auto-save feature. Save it with the default name
(<kbd>Tutorial1.dis65</kbd>), in the directory where the tutorial data
file lives.</p>
<p>(It's okay to create the project in the installation directory. You
don't need to work off of a copy of the data file; SourceGen doesn't modify
it, so you don't have to worry about trashing the example data.)</p>
@ -210,7 +211,8 @@
(The settings that affect projects are accessed through a
different screen, via <samp>Edit &gt; Project Properties</samp>.)</p>
<p>For now, you can leave everything set to default values.</p>
<p>For now, click <samp>Cancel</samp> to leave everything set to
default values.</p>
</div>
</div>

View File

@ -96,14 +96,14 @@
<p>Start a new project with the <samp>Generic 6502</samp> profile,
and from the SourceGen Tutorial directory select "Tutorial5".
We'll need to load an extension script from
the project directory, so immediately save the project, using the
the project directory, so go ahead and save the project, using the
default name ("Tutorial5.dis65").</p>
<p>Normally a project will give you some sort of hint as to the data
format, e.g. the graphics might be a platform-specific sprite. For
non-standard formats you can glean dimensions from the drawing code. For
the purposes of this tutorial we're just using a simple monochrome bitmap
format, with 8 pixels per byte, and we'll know that our images are for
format, with 8 pixels per byte, and we know that our images are for
a Tic-Tac-Toe game. The 'X' and the 'O' are 8x8, the game board is 40x40.
The bitmaps are sprites with transparency, so pixels are either solid
or transparent.</p>
@ -147,7 +147,7 @@
(that way, if you change the address, your visualizations don't break).
This is followed by the bitmap's width in bytes, and the bitmap's height.
Because we have 8 pixels per byte, we're currently showing an 8x1 image.
We'll come back to row stride.</p>
(We'll come back to look at row stride in a bit.)</p>
</div>
</div>