2018-09-28 17:05:11 +00:00
|
|
|
<!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>
|
|
|
|
|
|
|
|
|
|
<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 > 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
|
2018-10-04 01:03:04 +00:00
|
|
|
address at which they appear. When you clicked on the line, a few
|
|
|
|
|
things happened:</p>
|
2018-09-28 17:05:11 +00:00
|
|
|
<ul>
|
2018-10-04 01:03:04 +00:00
|
|
|
<li>The line was highlighted in the system selection color (usually
|
|
|
|
|
blue).</li>
|
2018-09-28 17:05:11 +00:00
|
|
|
<li>Address 1017 and label L1017 were highlighted. When a line
|
2018-10-04 01:03:04 +00:00
|
|
|
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>
|
2018-09-28 17:05:11 +00:00
|
|
|
<li>The Info window filled with a bunch of text that describes the
|
2018-10-04 01:03:04 +00:00
|
|
|
line format and some details about the LDA instruction.</li>
|
2018-09-28 17:05:11 +00:00
|
|
|
</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
|
2018-10-04 01:03:04 +00:00
|
|
|
row of buttons. Make sure "Auto" is selected. You should see three
|
2018-09-28 17:05:11 +00:00
|
|
|
labels in the window (L1002, L1014, L1017). Double-click on L1014. The
|
|
|
|
|
selection jumps to the appropriate line.</p>
|
|
|
|
|
|
|
|
|
|
<p>Select Edit > Find. Type "hello", and hit Enter. The selection will
|
|
|
|
|
move to address $100E, which is a string that says "hello!". You can use
|
|
|
|
|
Edit > Find Next to try to find the next occurrence (there isn't one). You
|
2018-10-04 01:03:04 +00:00
|
|
|
can search for any text that appears in the rightmost columns (label, opcode,
|
2018-09-28 17:05:11 +00:00
|
|
|
operand, comment).</p>
|
|
|
|
|
<p>Select Edit > Go To. You can enter a label, address, or file offset.
|
2018-10-04 01:03:04 +00:00
|
|
|
Enter "100b" to set the selection to $100B.</p>
|
2018-09-28 17:05:11 +00:00
|
|
|
|
|
|
|
|
<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 > Edit Long Comment from the menu bar.</li>
|
2018-10-04 01:03:04 +00:00
|
|
|
<li>Right click, and select Edit Long Comment from the
|
|
|
|
|
pop-up menu. (This menu is exactly the same as the Actions menu.)</li>
|
2018-09-28 17:05:11 +00:00
|
|
|
<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
|
2018-10-04 01:03:04 +00:00
|
|
|
convenient way to edit something: point and click.</p>
|
2018-09-28 17:05:11 +00:00
|
|
|
<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
|
2018-10-04 01:03:04 +00:00
|
|
|
hit Ctrl+Enter.)</p>
|
2018-09-28 17:05:11 +00:00
|
|
|
<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 > 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
|
2018-10-04 01:03:04 +00:00
|
|
|
useful for leaving notes to yourself as you work.</li>
|
2018-09-28 17:05:11 +00:00
|
|
|
<li>They're listed in the Notes window. Double-clicking them jumps
|
|
|
|
|
the selection to the note, making them useful as bookmarks.</li>
|
|
|
|
|
</ol>
|
|
|
|
|
|
2018-10-04 01:03:04 +00:00
|
|
|
<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
|
2018-09-28 17:05:11 +00:00
|
|
|
Edit > 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 > Undo. Notice how everything reverts to
|
|
|
|
|
the way it was. Now, select Edit > 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 > 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
|
2018-10-04 01:03:04 +00:00
|
|
|
to address $2000. (If you're not sure what refers to line $2000, select
|
|
|
|
|
it and check the References window.)</p>
|
2018-09-28 17:05:11 +00:00
|
|
|
<p>On that same line, select Actions > 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 > 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 > 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 > 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 > Undo twice, to get back to the place
|
2018-10-04 01:03:04 +00:00
|
|
|
where line $2005 is using "L2009" as its operand. Select that line and
|
2018-09-28 17:05:11 +00:00
|
|
|
Actions > 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
|
2018-10-04 01:03:04 +00:00
|
|
|
single step. (There's actually a subtle difference compared to the two-step
|
2018-09-28 17:05:11 +00:00
|
|
|
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 > 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 > 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 > 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
|
2018-10-04 01:03:04 +00:00
|
|
|
two separate regions. Select "mixed ASCII and non-ASCII", then click
|
2018-09-28 17:05:11 +00:00
|
|
|
"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 > 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 > Toggle Single-Byte
|
|
|
|
|
Format (or hit Ctrl+B).</p>
|
2018-10-04 01:03:04 +00:00
|
|
|
<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>
|
2018-09-28 17:05:11 +00:00
|
|
|
<p>Select the line at $2025, then shift-click the line at $202E. Select
|
|
|
|
|
Actions > 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 > Save (or hit Ctrl+S) to save your hard work.</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Generating Assembly Code</h3>
|
|
|
|
|
|
2018-10-04 01:03:04 +00:00
|
|
|
<p>You can generate assembly source code from the disassembled data.
|
2018-09-28 17:05:11 +00:00
|
|
|
Select File > 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 this 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>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div id=footer>
|
|
|
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
|
</div>
|
|
|
|
|
</body>
|
|
|
|
|
<!-- Copyright 2018 faddenSoft -->
|
|
|
|
|
</html>
|
