6502bench/SourceGen/RuntimeData/Help/tutorials.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Tutorials - 6502bench SourceGen</title>
</head>

<body>
<div id=content>
<h1>6502bench SourceGen: Tutorials</h1>
<p><a href="index.html">Back to index</a></p>

<ul>
  <li><a href="#basic-features">Basic Features</a></li>
  <li><a href="#advanced-features">Advanced Features</a></li>
</ul>


<h2><a name="basic-features">Basic Features</a></h2>

<p>This tutorial introduces SourceGen and covers some of the basic
features.  This skims lightly over some important concepts, so reading the
manual is recommended.</p>

<p>Start by launching SourceGen.  The initial screen has a large
center area with some links, and some mostly-empty windows on the sides.
The links are shortcuts for menu items in the File menu.</p>


<h3>Create the project</h3>

<p>Click "Start new project".</p>

<p>The New Project window has three parts.  The top-left window has a
tree of known platforms, arranged by manufacturer.  The top-right window
provides some details on whichever platform is selected.  The bottom
window will have some information about the data file, once we choose one.</p>
<p>Scroll down in the list, and select "Generic 6502".  Then click
"Select File...", navigate to the SourceGen installation directory,
open the Examples folder, then open the "Tutorial" folder.  Select the
file named "Tutorial1", and click "Open".</p>
<p>The filename now appears in the bottom window, along with an indication
of the file's size.
<p>Click OK to create the project.</p>


<h3>Getting Around</h3>

<p>The first thing we'll do is save the project.  Some features create or
load files from the directory where the project lives, so we want to
establish that.</p>
<p>Select File &gt; Save, which will bring up a standard save-file dialog.
Make sure you're in still in the Examples/Tutorial folder.  The default
project file name is "Tutorial1.dis65", which is what we want, so just
click "Save".</p>

<p>The display is divided into rows, one per line of disassembled code
or data.  This is a standard Windows "list view", so you can select a row
by left-clicking anywhere in it.  Use Ctrl+Click to toggle the selection
on individual lines, and Shift+Click to select a range of lines.  You can
move the selection around with the up/down arrow keys and PgUp/PgDn.  Scroll
the window with the mouse wheel or by grabbing the scroll bar.</p>

<p>Each row is divided into nine columns.  You can adjust the column
widths by clicking and dragging the column dividers in the header.  The
columns on the right side of the screen are similar to what you'd find
in assembly source code: label, opcode, operand, comment.  The columns
on the left are what you'd find in a disassembly (file offset, address,
raw bytes), plus some information about processor status flags and line
attributes that may or may not be useful to you.  If you find any of
these distracting, collapse the column.</p>

<p>Click on the fourth line down, which has address 1002.  The line has
a label, "L1002", and is performing an indexed load from L1017.  Both
of these labels were automatically generated, and are named for the
address at which they appear.  When you clicked on the line, a few
things happened:</p>
<ul>
  <li>The line was highlighted in the system selection color (usually
    blue).</li>
  <li>Address 1017 and label L1017 were highlighted.  When a line
    with an in-file operand is selected, 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>The Info window filled with a bunch of text that describes the
    line format and some details about the LDA instruction.</li>
</ul>

<p>Click some other lines, such as address $100B and $1014.  Note how the
highlights and contents of other windows change.</p>
<p>Click on L1002 again, then double-click on the opcode ("LDA").  The
selection jumps to L1017.  When an operand references an in-file address,
double-clicking on the opcode will take you to it.  (Double-clicking on
the operand itself opens a format editor; more on that later.)</p>
<p>With L1017 highlighted, double-click on the line that appears in the
References window.  Note the selection jumps to L1002.  You can immediately
jump to any reference.</p>
<p>At the top of the Symbols window on the right side of the screen is a
row of buttons.  Make sure "Auto" is selected.  You should see three
labels in the window (L1002, L1014, L1017).  Double-click on L1014.  The
selection jumps to the appropriate line.</p>

<p>Select Edit &gt; Find.  Type "hello", and hit Enter.  The selection will
move to address $100E, which is a string that says "hello!".  You can use
Edit &gt; Find Next to try to find the next occurrence (there isn't one).  You
can search for any text that appears in the rightmost columns (label, opcode,
operand, comment).</p>
<p>Select Edit &gt; Go To.  You can enter a label, address, or file offset.
Enter "100b" to set the selection to $100B.</p>

<p>Near the top-left of the SourceGen window is a set of toolbar icons.
Click the left-arrow, and watch the selection moves.  Click it again.  Then
click the right-arrow a couple of times.  Whenever you jump around in the
file by using the Go To feature, or by double-clicking on opcodes or
lines in side-windows, the locations are added to a navigation history.  The
arrows let you move forward and backward through it.</p>


<h3>Editing</h3>

<p>Click the very first line of the file, which is a comment that says
something like "6502bench SourceGen vX.Y.Z".  There are three ways to
open the comment editor:</p>
<ol>
  <li>Select Actions &gt; Edit Long Comment from the menu bar.</li>
  <li>Right click, and select Edit Long Comment from the
    pop-up menu.  (This menu is exactly the same as the Actions menu.)</li>
  <li>Double-click the comment</li>
</ol>
<p>Most things in the code list will respond to a double-click.
Double-clicking on addresses, flags, labels, operands, and comments will
open editors for those things.  Double-clicking on a value in the "bytes"
column will open a floating hex dump viewer.  This is usually the most
convenient way to edit something: point and click.</p>
<p>Double-click the comment to open the editor.  Type some words into the
upper window, and note that a formatted version appears in the bottom
window.  Experiment with the maximum line width and "render in box"
settings to see what they do.  You can hit Enter to create line breaks,
or let SourceGen wrap lines for you.  When you're done, click OK.  (Or
hit Ctrl+Enter.)</p>
<p>When the dialog closes, you'll see your new comment in place at the
top of the file.  If you typed enough words, your comment will span
multiple lines.  You can select the comment by selecting any line in it.</p>

<p>Click on the comment, then shift-click on L1014.  Right-click, and look
at the menu.  Nearly all of the menu items are disabled.  Most editors are
only enabled when a single instance of a relevant item is selected, so
for example Edit Long Comment won't be enabled if you have an instruction
selected.</p>

<p>Let's add a note.  Click on $100E (the line with "hello!"), then
select Actions &gt; Edit Note.  Type a few words, pick a color, and click "OK"
(or hit Ctrl+Enter).  Your note appears in the code, and also in the
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>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
    the selection to the note, making them useful as bookmarks.</li>
</ol>

<p>It's time to do something with the code.  If you look at what the code
does you'll see that it's copying several dozen bytes from $1017
to $2000, then jumping to $2000.  It appears to be relocating the next
part of the code before
executing it.  We want to let the disassembler know what's going on, so
select the line at address $1017 and then
Edit &gt; Edit Address.  (Or double-click the "1017" in the addr column.)
In the Edit Address dialog, type "2000", and hit Enter.)</p>

<p>Note the way the code list has changed.  When you changed the address,
the "JMP $2000" at L1014 found a home inside the bounds of the file, so
the code tracer was able to find the instructions there.<p>
<p>From the menu, select Edit &gt; Undo.  Notice how everything reverts to
the way it was.  Now, select Edit &gt; Redo.  You can undo any change you
make to the project.  (The undo history is <strong>not</strong> saved in
the project file, though, so when you exit the program the history is
lost.)</p>
<p>Notice that, while the address column has changed, the offset column
has not.  File offsets never change, which is why they're shown here and
in the References and Notes windows.  (They can, however, be distracting,
so you'll be forgiven if you reduce the offset column width to zero.)</p>
<p>On the line at address $2000, select Actions &gt; Edit Label, or
double-click on the label "L2000".  Change the label to "MAIN", and hit
Enter.  The label changes on that line, and on the two lines that refer
to address $2000.  (If you're not sure what refers to line $2000, select
it and check the References window.)</p>
<p>On that same line, select Actions &gt; Edit Comment.  Type a short
comment, and hit Enter.  Your comment appears in the "comment" column.</p>


<h3>Editing Operands</h3>

<p>The operand in the LDA instruction at line $2000 refers to an address
($3000) that isn't part of the file.  We want to create an equate directive to
give it a name.  With the line at $2000 selected, use Actions &gt; Edit Operand,
or double-click on "$3000".  Select the "Symbol" radio button, then type
"INPUT" in the text box.  Click "OK".</p>
<p>Disappointed?  Nothing seems to have happened.  The problem is that we
updated the operand to reference a symbol that doesn't exist.  Open the
operand editor again, but this time click on "Set operand AND create project
symbol".  Click "OK".</p>
<p>That's better.  If you scroll up to the top of the project, you'll see
that there's now a ".EQ" line for the symbol.</p>
<p>Operands that refer to in-file locations behave similarly.  Select the
line two down, at address $2005, and Actions &gt; Edit Operand.  Enter the
symbol "IS_OK".  (Note you don't actually have to click Symbol first -- if
you just start typing as soon as the dialog opens, it'll select Symbol
for you automatically.)  Click "OK".</p>
<p>As before, nothing appears to have happened, but if you were watching
carefully you would have noticed that the label at $2009 ("L2009") has
disappeared.  This happened because the code at $2005 used to have a
<i>numeric</i> reference to $2009, and SourceGen automatically created a
label.  However, you changed the code at $2005 to have a <i>symbolic</i>
reference to a symbol called "IS_OK", so the auto-label was no longer
needed.  Because IS_OK doesn't exist, the operand at $2005 is just formatted
as a hexadecimal value.</p>
<p>Let's fix this.  Select the line at address $2009, then
Actions &gt; Edit Label.  Enter "IS_OK", and hit Enter.  (NOTE: labels are
case-sensitive, so it needs to match the operand at $2005 exactly.)  You'll
see the new label appear, and the operand at line $2005 will use it.</p>
<p>There's an easier way.  Use Edit &gt; Undo twice, to get back to the place
where line $2005 is using "L2009" as its operand.  Select that line and
Actions &gt; Edit Operand.  Enter "IS_OK", then select "Create label at target
address instead".  Hit "OK".</p>
<p>You should now see that both the operand at $2005 and the label at
$2009 have changed to IS_OK, accomplishing what we wanted to do in a
single step.  (There's actually a subtle difference compared to the two-step
process: the operand at $2005 is still a numeric reference.  It was
automatically changed to match IS_OK in the same way that the references
to MAIN were when we renamed "L2000" earlier.  If you actually do want the
symbolic reference, there's another option in the Edit Operand dialog that
does it.)</p>


<h3>Editing Data Formats</h3>

<p>There's some string and numeric data down at the bottom of the file.  The
final string appears to be multiple strings stuck together.  Notice that
the opcode for the very last line is '+', which means it's a continuation
of the previous line.  Long data items can span multiple lines, split
every 64 characters (including delimiters), but they are still single
items: selecting any part selects the whole.</p>
<p>Select the last line, then Edit &gt; Edit Data Format.  At the top of the
dialog that appears, it will say "65 bytes selected".  You can format this
as a single 65-byte string, as 65 individual items, or various things
in between.  For now, select "Single bytes", and then on the right,
select "ASCII".  Click "OK".</p>
<p>Each character is now on its own line.  The selection still spans the
same set of addresses.</p>
<p>Select address $203D on its own, then Actions &gt; Edit Label.  Set the
label to "STR1".  Move up a bit and select address $2030, then scroll to
the bottom and shift-click address $2070.  Select Actions &gt; Edit Data
Format.  At the top it should now say, "65 bytes selected in 2 groups".
There are two groups because the presence of a label split the data into
two separate regions.  Select "mixed ASCII and non-ASCII", then click
"OK".</p>
<p>We now have two ".STR" lines, one for "string zero  ", one with the
STR1 label and the rest of the string data.  This is okay, but it's not
really what we want.  The code at $2022 appears to be loading a 16-bit
address from data at $2025, so we want to use that if we can.</p>
<p>Select Edit &gt; Undo twice.  You should be back to a state where there's
a single ".STR" line at the bottom, split across two lines with a '+'.</p>
<p>Select the line at $2026.  This is currently formatted as a string,
but that appears to be incorrect, so let's format it as individual bytes
instead.  There's an easy way to do that: use Actions &gt; Toggle Single-Byte
Format (or hit Ctrl+B).</p>
<p>The data starting at $2025 appears to be 16-bit addresses that point
into the table of strings, so let's format them appropriately.</p>
<p>Select the line at $2025, then shift-click the line at $202E.  Select
Actions &gt; Edit Data Format.  If you selected the correct set of bytes,
the top should say, "10 bytes selected".  Click the
"16-bit words, little-endian" radio button, then over to the right, click
the "Address" radio button.  Click "OK".</p>
<p>We just told SourceGen that those 10 bytes are actually five numeric
references.  SourceGen determined that the addresses are contained in the
file, and created labels for each of them.  Labels only work if they're
on their own line, so each string is now in a separate ".STR" statement.

<p>Use File &gt; Save (or hit Ctrl+S) to save your hard work.</p>


<h3>Generating Assembly Code</h3>

<p>You can generate assembly source code from the disassembled data.
Select File &gt; Assembler (or hit Ctrl+Shift+A) to open the generation
and assembly dialog.</p>
<p>Pick your favorite assembler from the drop list at the top right,
then click "Generate".  An assembly source file will be generated in the
directory where your project files lives, named after a combination of the
project name and the assembler name.  A preview of the assembled code
appears in the top window.  (It's a "preview" because it has line numbers
added and is cut off after a certain limit.)</p>

<p>If you have a cross-assembler installed and configured, you can run
it by clicking "Run Assembler".  The output from the assembler will appear
in the lower window, along with an indication of whether the assembled
file matches the original.  (Barring bugs in SourceGen or the assembler,
it should always match exactly.)</p>

<p>Click "Close" to close the window.</p>


<h3>Go Forth</h3>

<p>That's it for the basic tutorial.  Play with the program some more to see
what it can do, or do something wild like read the manual.</p>
<p>While you can do some fancy things, nothing you do will alter the
data file.  The assembled output will always match the original.</p>


<h2><a name="advanced-features">Advanced Features</a></h2>

<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.</p>


<h3>Split-Address Table Formatting</h3>

<p>Start a new project.  Select the Apple //e platform, click Select File
and navigate to the Examples directory.  In A2-Amper-fdraw, select
<code>AMPERFDRAW#061d60</code>.  Click OK to create the project.</p>
<p>Not a lot to see here -- just half a dozen lines of loads and stores.
This particular program interfaces with Applesoft BASIC, so we can make it
a bit more meaningful by loading an additional platform
symbol file.  Select Edit > Project Properties, then the Symbol Files
tab.  Click Add Symbol Files.  The file browser starts in the RuntimeData
directory.  In the Apple folder, select <code>Applesoft.sym65</code>, and
click Open.  Click OK to close the project properties window.</p>
<p>The STA instructions now reference <code>AMPERV</code>, which is noted
as a call vector.  We can see the code setting up a jump to $1d70.  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 .ORG
statement, and change it from $2000 to $1d60.  We can now see that $1d70
starts right after this initial chunk of code.</p>

<p>Select the line with address $1d70, then Actions > Hint As Code Entry Point.
More code appears, but not much -- if you scroll down you'll see that most
of the file is still data.  The code at $1d70 searches through a table at
$1d88 for a match with the contents of the accumulator.  If it finds a match,
it loads bytes from tables at $1da6 and $1d97, pushes them on the stack,
and the JMPs away.  This code is pushing a return address onto the stack.
When the code at CHRGET returns, it'll return to that address.  Because of
a quirk of the 6502 architecture, the address pushed must be the target
address minus one.</p>
<p>The first byte in the first table at $1d97 (which has the auto-label
L1D97) is $b4.  The first byte in the second table is $1d.  So the first
address we want is $1db4 + 1 = $1db5.</p>
<p>Select the line at $1db5, and use Actions > Hint As Code Entry Point.
More code appears, but again it's only a few lines.  Let's dress this one
up a bit.  Set a label on the code at $1db5 called "FUNC".  At $1d97, edit
the data item (double-click on "$b4"), click "Single bytes", then type "FUNC"
(note the text field gets focus immediately, and the radio button
automatically switches to "symbolic reference" when you start typing).
Click OK.  The operand at $1d97 should now say <code>&lt;FUNC-1</code>.
Repeat the process at $1da6, this time clicking the "High" part button,
to make the operand there say <code>&gt;FUNC</code>.  (If it says
<code>&lt;FUNC-152</code>, you forgot to select the High part.)</p>

<p>We've now changed the first entry in the table to symbolic references.
You could repeat these steps for the remaining items, but there's a faster
way.  Click on the line at address $1d97, then shift-click the line at
address $1da9 (which should be <code>.FILL 12,$1e</code>).  Select
Actions &gt; Format Split-Address Table.</p>
<p>The message at the top should indicate that there are 30 bytes
selected.  In Address Characteristics, click the "adjusted for RTS/RTL"
checkbox.  As soon as you do, the first line of the Generated Addresses
list should show the symbol "FUNC".  The rest of the addresses will look like
<code>(+) T1DD0</code>.  The "(+)" means that a label was not found at
that location, so a label will be generated automatically.</p>
<p>Down near the bottom, check the "add code entry hint if needed" checkbox.
Because we saw the table contents being pushed onto the stack for RTS,
we know that they're all code entry points.</p>
<p>Click OK.  The table of address bytes should now all be references to
symbols -- 15 low parts followed by 15 high parts.  If you scroll down,
you should see nothing but instructions until you get to the last dozen
bytes at the end of the file.  (If this isn't the case, use Edit > Undo,
then work through the steps again.)</p>
<p>The formatter did the same steps you went through earlier -- set a
label, apply the label to the low and high bytes in the table, add a
code entry point hint -- but did several of them at once.</p>

<p>We don't want to save this project, so select File > Close.  When
SourceGen asks if you want to continue, click OK.</p>


<h3>[to be continued]</h3>


</div>

<div id=footer>
<p><a href="index.html">Back to index</a></p>
</div>
</body>
<!-- Copyright 2018 faddenSoft -->
</html>