6502/6502bench
1
0
Fork 0
mirror of https://github.com/fadden/6502bench.git synced 2025-04-05 17:37:11 +00:00
Code Issues Projects Releases Wiki Activity

Execute scripts

Browse Source 
This change applies the substitution scripts on the HTML files,
replacing away the jQuery load() calls with the actual file contents,
and setting the correct URLs to the prev/next buttons.
This commit is contained in:
Andy McFadden 2021-06-07 17:14:16 -07:00
parent 154cff3347
commit a37143e9fc
18 changed files with 4125 additions and 3311 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

369
docs/sgtutorial/about-disasm.html
View File

@ -1,161 +1,208 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>About Disassembly - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-about-disasm -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-about-disasm").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>About Disassembly</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Well-written assembly-language source code has meaningful
comments and labels, so that humans can read and understand it.
For example:</p>
<pre>
.org $2000
sec ;set carry
ror A ;shift into high bit
bmi CopyData ;branch always
.asciiz "first string"
.asciiz "another string"
.asciiz "string the third"
.asciiz "last string"
CopyData lda #&lt;addrs ;get pointer into
sta ptr ; address table
lda #&gt;addrs
sta ptr+1
</pre>
<p>Computers operate at a much lower level, so a piece of software
called an <i>assembler</i> is used to convert the source code to
object code that the CPU can execute.
Object code looks more like this:</p>
<pre>
38 6a 30 39 66 69 72 73 74 20 73 74 72 69 6e 67
00 61 6e 6f 74 68 65 72 20 73 74 72 69 6e 67 00
73 74 72 69 6e 67 20 74 68 65 20 74 68 69 72 64
00 6c 61 73 74 20 73 74 72 69 6e 67 00 a9 63 85
02 a9 20 85 03
</pre>
<p>This arrangement works perfectly well until somebody needs to
modify the software and nobody can find the original sources.
<i>Disassembly</i> is the act of taking a raw hex
dump and converting it to source code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t0-bad-disasm.png" alt="t0-bad-disasm"/>
</div>
<div class="grid-item-text">
<p>Disassembling a blob of data can be tricky. A simple
disassembler can format instructions, but can't generally tell
the difference between instructions and data. Many 6502 programs
intermix code and data freely, so simply dumping everything as
an instruction stream can result in sections with nonsensical output.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>One way to separate code from data is to try to execute all
possible data paths. There are a number of reasons why it's difficult
or impossible to do this perfectly, but you can get pretty good
results by identifying execution entry points and just walking through
the code. When a conditional branch is encountered, both paths are
traversed. When all code has been traced, every byte that hasn't
been visited is either
data used by the program, or dead space not used by anything.</p>
<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.
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
certain instructions is determined by the values of the processor
status flags.)</p>
<p>Once the instructions and data are separated and formatted
nicely, it's still up to a human to figure out what it all means.
Comments and meaningful labels are needed to make sense of it.
These should be added to the disassembly listing.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t0-sourcegen.png" alt="t0-sourcegen"/>
</div>
<div class="grid-item-text">
<p>SourceGen performs the instruction tracing, and makes it easy
to format operands and add labels and comments.
When the disassembled code is ready, SourceGen can generate source code
for a variety of modern cross-assemblers, and produce HTML listings
with embedded graphic visualizations.</p>
</div>
</div>
</div> <!-- grid-container -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>About Disassembly - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-about-disasm -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm" class="active"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>About Disassembly</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Well-written assembly-language source code has meaningful
comments and labels, so that humans can read and understand it.
For example:</p>
<pre>
.org $2000
sec ;set carry
ror A ;shift into high bit
bmi CopyData ;branch always
.asciiz "first string"
.asciiz "another string"
.asciiz "string the third"
.asciiz "last string"
CopyData lda #&lt;addrs ;get pointer into
sta ptr ; address table
lda #&gt;addrs
sta ptr+1
</pre>
<p>Computers operate at a much lower level, so a piece of software
called an <i>assembler</i> is used to convert the source code to
object code that the CPU can execute.
Object code looks more like this:</p>
<pre>
38 6a 30 39 66 69 72 73 74 20 73 74 72 69 6e 67
00 61 6e 6f 74 68 65 72 20 73 74 72 69 6e 67 00
73 74 72 69 6e 67 20 74 68 65 20 74 68 69 72 64
00 6c 61 73 74 20 73 74 72 69 6e 67 00 a9 63 85
02 a9 20 85 03
</pre>
<p>This arrangement works perfectly well until somebody needs to
modify the software and nobody can find the original sources.
<i>Disassembly</i> is the act of taking a raw hex
dump and converting it to source code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t0-bad-disasm.png" alt="t0-bad-disasm"/>
</div>
<div class="grid-item-text">
<p>Disassembling a blob of data can be tricky. A simple
disassembler can format instructions, but can't generally tell
the difference between instructions and data. Many 6502 programs
intermix code and data freely, so simply dumping everything as
an instruction stream can result in sections with nonsensical output.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>One way to separate code from data is to try to execute all
possible data paths. There are a number of reasons why it's difficult
or impossible to do this perfectly, but you can get pretty good
results by identifying execution entry points and just walking through
the code. When a conditional branch is encountered, both paths are
traversed. When all code has been traced, every byte that hasn't
been visited is either
data used by the program, or dead space not used by anything.</p>
<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.
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
certain instructions is determined by the values of the processor
status flags.)</p>
<p>Once the instructions and data are separated and formatted
nicely, it's still up to a human to figure out what it all means.
Comments and meaningful labels are needed to make sense of it.
These should be added to the disassembly listing.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t0-sourcegen.png" alt="t0-sourcegen"/>
</div>
<div class="grid-item-text">
<p>SourceGen performs the instruction tracing, and makes it easy
to format operands and add labels and comments.
When the disassembled code is ready, SourceGen can generate source code
for a variety of modern cross-assemblers, and produce HTML listings
with embedded graphic visualizations.</p>
</div>
</div>
</div> <!-- grid-container -->
<div id="prevnext">
<a href="using-sourcegen.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

582
docs/sgtutorial/address-tables.html
View File

@ -1,267 +1,315 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Address Tables - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-address-tables -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-address-tables").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Address Tables</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Code often contains tables of addresses to code or data.
Formatting them one at a time can be tedious, so SourceGen
provides a faster way. For this tutorial we'll start by labeling
and tagging a single entry by hand, then do the rest in one shot.</p>
<p>Start a new project. Select the Apple //e platform, click
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-initial.png" alt="t3-initial"/>
</div>
<div class="grid-item-text">
<p>Not a lot to see here -- just half a dozen lines of loads and stores,
then nothing but data.
This particular program interfaces with Applesoft BASIC, so we can make it
a bit more meaningful by loading an additional platform
symbol file.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-a2-props.png" alt="t3-a2-props"/>
</div>
<div class="grid-item-text">
<p>Select <samp>Edit &gt; Project Properties</samp>, then the
<samp>Symbol Files</samp> tab. Click <samp>Add Symbol Files from Runtime</samp>.
The file browser starts in the "RuntimeData" directory.
Open the "Apple" folder, then select "Applesoft.sym65",
and click <samp>Open</samp>. Click <samp>OK</samp> to close
the project properties window.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-amperv.png" alt="t3-amperv"/>
</div>
<div class="grid-item-text">
<p>The <code>STA</code> instructions now reference <code>BAS_AMPERV</code>,
which is noted as a code vector. We can see the code setting up a jump
(opcode $4C) to $1D70.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d70.png" alt="t3-1d70"/>
</div>
<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,
and change it from $2000 to $1D60. We can now see that $1D70 starts
right after this initial chunk of code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d70-code.png" alt="t3-1d70-code"/>
</div>
<div class="grid-item-text">
<p>Select the line with address $1D70, then
<samp>Actions &gt; Tag Address As Code Start Point</samp>.
More code appears, but not much -- if you scroll down you'll see that most
of the file is still data.</p>
<p>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 then <code>JMP</code>s away. This code is pushing a return address onto the stack.
When the code at <code>BAS_CHRGET</code> returns, it'll return to that
address. Because of a quirk of the 6502 architecture, the address pushed
must be the desired address minus one.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d97.png" alt="t3-1d97"/>
</div>
<div class="grid-item-text">
<p>The first byte in the first address table at $1D97 (which
has the auto-label <code>L1D97</code>) is $B4.
The first byte in the second table is $1D. So the first
address we want is $1DB4 + 1 = $1DB5.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d97-edit.png" alt="t3-1d97-edit.png"/>
</div>
<div class="grid-item-text">
<p>Select the line at $1DB5, and use
<samp>Actions &gt; Tag Address As Code Start Point</samp>.
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 "<kbd>FUNC</kbd>".
Then, at $1D97, edit the data item (double-click on "<samp>$B4</samp>"),
click <samp>Single bytes</samp>, then type "<kbd>FUNC</kbd>"
(note the text field gets focus immediately, and the radio button
automatically switches to <samp>symbolic reference</samp> when you start typing).
Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d97-post.png" alt="t3-1d97-post.png"/>
</div>
<div class="grid-item-text">
<p>The operand at $1D97 should now say <code>&lt;FUNC-1</code>.
Repeat the process at $1DA6, this time clicking the <samp>High</samp>
part radio button below the symbol entry text box,
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 address table to a
symbolic reference, which is helps 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-format-dialog.png" alt="t3-format-dialog"/>
</div>
<div class="grid-item-text">
<p>Click on the line at address $1D97, then shift-click the line at
address $1DA9 (which should be <code>.FILL 12,$1e</code>). Select
<samp>Actions &gt; Format Address Table</samp>.</p>
<p>Contrary to first impressions, this imposing dialog does not allow you
to launch objects into orbit. There are a variety of common ways to
structure an address table, all of which are handled here. You can
configure the various parameters and see the effects as you make
each change.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-format-cfg.png" alt="t3-format-cfg"/>
</div>
<div class="grid-item-text">
<p>The message at the top should indicate that there are 30 bytes
selected. In <samp>Address Characteristics</samp>, click the
<samp>Parts are split across sub-tables</samp> checkbox and the
<samp>Adjusted for RTS/RTL</samp> checkbox.
As soon as you do, the first line of the <samp>Generated Addresses</samp>
list should show the symbol "<code>FUNC</code>".
The rest of the addresses will look like
"<code>(+) T1DD0</code>". The "(+)" means that a label was not found at
that location, so a new global label will be generated automatically.</p>
<p>Down near the bottom, check the
<samp>Tag targets as code start points</samp> checkbox.
Because we saw the table contents being pushed onto the stack for
<code>RTS</code>, we know that they're all code entry points.</p>
<p>Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-format-done.png" alt="t3-format-done"/>
</div>
<div class="grid-item-text">
<p>The table of address bytes at $1D97 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
<samp>Edit &gt; Undo</samp>, then work through the steps again.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The formatter did the same series of actions you went through earlier,
<!-- set a
label, apply the label to the low and high bytes in the table, add a
code start point tag -->
but applied them to multiple locations in one shot. The next step in
the disassembly process would be to rename the "Tnnnn" labels to
something more meaninful.</p>
<p>We don't want to save this project, so select
<samp>File &gt; Close</samp>. When SourceGen asks for confirmation,
click <samp>Discard &amp; Continue</samp>.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Address Tables - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-address-tables -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables" class="active"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Address Tables</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Code often contains tables of addresses to code or data.
Formatting them one at a time can be tedious, so SourceGen
provides a faster way. For this tutorial we'll start by labeling
and tagging a single entry by hand, then do the rest in one shot.</p>
<p>Start a new project. Select the Apple //e platform, click
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-initial.png" alt="t3-initial"/>
</div>
<div class="grid-item-text">
<p>Not a lot to see here -- just half a dozen lines of loads and stores,
then nothing but data.
This particular program interfaces with Applesoft BASIC, so we can make it
a bit more meaningful by loading an additional platform
symbol file.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-a2-props.png" alt="t3-a2-props"/>
</div>
<div class="grid-item-text">
<p>Select <samp>Edit &gt; Project Properties</samp>, then the
<samp>Symbol Files</samp> tab. Click <samp>Add Symbol Files from Runtime</samp>.
The file browser starts in the "RuntimeData" directory.
Open the "Apple" folder, then select "Applesoft.sym65",
and click <samp>Open</samp>. Click <samp>OK</samp> to close
the project properties window.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-amperv.png" alt="t3-amperv"/>
</div>
<div class="grid-item-text">
<p>The <code>STA</code> instructions now reference <code>BAS_AMPERV</code>,
which is noted as a code vector. We can see the code setting up a jump
(opcode $4C) to $1D70.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d70.png" alt="t3-1d70"/>
</div>
<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,
and change it from $2000 to $1D60. We can now see that $1D70 starts
right after this initial chunk of code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d70-code.png" alt="t3-1d70-code"/>
</div>
<div class="grid-item-text">
<p>Select the line with address $1D70, then
<samp>Actions &gt; Tag Address As Code Start Point</samp>.
More code appears, but not much -- if you scroll down you'll see that most
of the file is still data.</p>
<p>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 then <code>JMP</code>s away. This code is pushing a return address onto the stack.
When the code at <code>BAS_CHRGET</code> returns, it'll return to that
address. Because of a quirk of the 6502 architecture, the address pushed
must be the desired address minus one.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d97.png" alt="t3-1d97"/>
</div>
<div class="grid-item-text">
<p>The first byte in the first address table at $1D97 (which
has the auto-label <code>L1D97</code>) is $B4.
The first byte in the second table is $1D. So the first
address we want is $1DB4 + 1 = $1DB5.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d97-edit.png" alt="t3-1d97-edit.png"/>
</div>
<div class="grid-item-text">
<p>Select the line at $1DB5, and use
<samp>Actions &gt; Tag Address As Code Start Point</samp>.
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 "<kbd>FUNC</kbd>".
Then, at $1D97, edit the data item (double-click on "<samp>$B4</samp>"),
click <samp>Single bytes</samp>, then type "<kbd>FUNC</kbd>"
(note the text field gets focus immediately, and the radio button
automatically switches to <samp>symbolic reference</samp> when you start typing).
Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-1d97-post.png" alt="t3-1d97-post.png"/>
</div>
<div class="grid-item-text">
<p>The operand at $1D97 should now say <code>&lt;FUNC-1</code>.
Repeat the process at $1DA6, this time clicking the <samp>High</samp>
part radio button below the symbol entry text box,
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 address table to a
symbolic reference, which is helps 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-format-dialog.png" alt="t3-format-dialog"/>
</div>
<div class="grid-item-text">
<p>Click on the line at address $1D97, then shift-click the line at
address $1DA9 (which should be <code>.FILL 12,$1e</code>). Select
<samp>Actions &gt; Format Address Table</samp>.</p>
<p>Contrary to first impressions, this imposing dialog does not allow you
to launch objects into orbit. There are a variety of common ways to
structure an address table, all of which are handled here. You can
configure the various parameters and see the effects as you make
each change.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-format-cfg.png" alt="t3-format-cfg"/>
</div>
<div class="grid-item-text">
<p>The message at the top should indicate that there are 30 bytes
selected. In <samp>Address Characteristics</samp>, click the
<samp>Parts are split across sub-tables</samp> checkbox and the
<samp>Adjusted for RTS/RTL</samp> checkbox.
As soon as you do, the first line of the <samp>Generated Addresses</samp>
list should show the symbol "<code>FUNC</code>".
The rest of the addresses will look like
"<code>(+) T1DD0</code>". The "(+)" means that a label was not found at
that location, so a new global label will be generated automatically.</p>
<p>Down near the bottom, check the
<samp>Tag targets as code start points</samp> checkbox.
Because we saw the table contents being pushed onto the stack for
<code>RTS</code>, we know that they're all code entry points.</p>
<p>Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t3-format-done.png" alt="t3-format-done"/>
</div>
<div class="grid-item-text">
<p>The table of address bytes at $1D97 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
<samp>Edit &gt; Undo</samp>, then work through the steps again.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The formatter did the same series of actions you went through earlier,
<!-- set a
label, apply the label to the low and high bytes in the table, add a
code start point tag -->
but applied them to multiple locations in one shot. The next step in
the disassembly process would be to rename the "Tnnnn" labels to
something more meaninful.</p>
<p>We don't want to save this project, so select
<samp>File &gt; Close</samp>. When SourceGen asks for confirmation,
click <samp>Discard &amp; Continue</samp>.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="advanced-topics.html" class="btn-previous">&laquo; Previous</a>
<a href="extension-scripts.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

208
docs/sgtutorial/advanced-topics.html
View File

@ -1,80 +1,128 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Advanced Topics - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-advanced-topics -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-advanced-topics").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Advanced Topics</h2>
<p>This section has tutorials for three subjects:</p>
<ul>
<li><a href="address-tables.html">Address Tables</a>: how to format
a table of code or data addresses easily.</li>
<li><a href="extension-scripts.html">Extension Scripts</a>: an introduction
to scripts that automate formatting of inline data.</li>
<li><a href="visualizations.html">Visualizations</a>: converting graphical
data to bitmap or wireframe images that can be embedded into the
disassembly listing.</li>
</ul>
<p>These features are not essential, but they can make your life easier.
All of the tutorials assume you are already familiar with SourceGen.</p>
<p>&nbsp;</p>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Advanced Topics - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-advanced-topics -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics" class="active"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Advanced Topics</h2>
<p>This section has tutorials for three subjects:</p>
<ul>
<li><a href="address-tables.html">Address Tables</a>: how to format
a table of code or data addresses easily.</li>
<li><a href="extension-scripts.html">Extension Scripts</a>: an introduction
to scripts that automate formatting of inline data.</li>
<li><a href="visualizations.html">Visualizations</a>: converting graphical
data to bitmap or wireframe images that can be embedded into the
disassembly listing.</li>
</ul>
<p>These features are not essential, but they can make your life easier.
All of the tutorials assume you are already familiar with SourceGen.</p>
<p>&nbsp;</p>
</div> <!-- #main -->
<div id="prevnext">
<a href="odds-ends.html" class="btn-previous">&laquo; Previous</a>
<a href="address-tables.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

382
docs/sgtutorial/digging-deeper.html
View File

@ -1,167 +1,215 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Digging Deeper - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-digging-deeper -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-digging-deeper").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Digging Deeper</h2>
<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>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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-tutorial-top.png" alt="t2-tutorial-top"/>
</div>
<div class="grid-item-text">
<p>Looking at the code list, the first thing you'll notice is that we
immediately ran into a
<code>BRK</code>, which is a pretty reliable sign that we're not in
a code section. This particular file begins with <code>00 20</code>, which
could be a load address (e.g. some C64 binaries look like this). So let's start
with that assumption.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>As discussed in the introductory material, SourceGen separates code
from data by tracing all possible execution paths from declared entry
points. The generic profiles mark the first byte of the file as an entry
point, but that's wrong here. We want to change the entry point to
be after the 16-bit load address, at offset +000002.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-edit1.png" alt="t2-1000-edit1"/>
</div>
<div class="grid-item-text">
<p>Click on the first line of code at address $1000, and select
<samp>Actions &gt; Remove Analyzer Tags</samp>
(<kbd class="key">Ctrl+H</kbd> <kbd class="key">Ctrl+R</kbd>).
This removes the "code entry point" tag.
Unfortunately the $20 is still auto-detected as being part of a string
directive.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-edit2.png" alt="t2-1000-edit2"/>
</div>
<div class="grid-item-text">
<p>The string is making it hard to manipulate the next few bytes,
so let's fix that by selecting <samp>Edit &gt; Toggle Data Scan</samp>
(<kbd class="key">Ctrl+D</kbd>). This turns off the feature that
automatically generates string and <code>.FILL</code> directives,
so now each uncategorized byte is on its own line.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-fmt-word.png" alt="t2-1000-fmt-word"/>
</div>
<div class="grid-item-text">
<p>You could select the first two lines and use
<samp>Actions &gt; Edit Operand</samp> to format them as a 16-bit
little-endian hex value, but there's a shortcut: select the first
line with data (address $1000), then <samp>Actions &gt; Format As Word</samp>
(<kbd class="key">Ctrl+W</kbd>).
It automatically grabbed the following byte and combined them.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-setcode.png" alt="t2-1000-setcode"/>
</div>
<div class="grid-item-text">
<p>Since we believe $2000 is the load address for everything that follows,
click on the line with address $1002, select
<samp>Actions &gt; Set Address</samp>, and enter "2000". With that line
still selected, use <samp>Actions &gt; Tag Address As Code Start Point</samp>
(<kbd class="key">Ctrl+H</kbd> <kbd class="key">Ctrl+C</kbd>) to
tell the analyzer to start looking for code there.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-ready.png" alt="t2-1000-ready"/>
</div>
<div class="grid-item-text">
<p>That looks better, but the branch destination ($203D) is off the bottom of the
screen (unless you have a really tall screen or small fonts) because of
all the intervening data. Use <samp>Edit &gt; Toggle Data Scan</samp>
(<kbd class="key">Ctrl+D</kbd>)
to turn the string-finder back on. Now it's easier to read.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Digging Deeper - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-digging-deeper -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper" class="active"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Digging Deeper</h2>
<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>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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-tutorial-top.png" alt="t2-tutorial-top"/>
</div>
<div class="grid-item-text">
<p>Looking at the code list, the first thing you'll notice is that we
immediately ran into a
<code>BRK</code>, which is a pretty reliable sign that we're not in
a code section. This particular file begins with <code>00 20</code>, which
could be a load address (e.g. some C64 binaries look like this). So let's start
with that assumption.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>As discussed in the introductory material, SourceGen separates code
from data by tracing all possible execution paths from declared entry
points. The generic profiles mark the first byte of the file as an entry
point, but that's wrong here. We want to change the entry point to
be after the 16-bit load address, at offset +000002.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-edit1.png" alt="t2-1000-edit1"/>
</div>
<div class="grid-item-text">
<p>Click on the first line of code at address $1000, and select
<samp>Actions &gt; Remove Analyzer Tags</samp>
(<kbd class="key">Ctrl+H</kbd> <kbd class="key">Ctrl+R</kbd>).
This removes the "code entry point" tag.
Unfortunately the $20 is still auto-detected as being part of a string
directive.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-edit2.png" alt="t2-1000-edit2"/>
</div>
<div class="grid-item-text">
<p>The string is making it hard to manipulate the next few bytes,
so let's fix that by selecting <samp>Edit &gt; Toggle Data Scan</samp>
(<kbd class="key">Ctrl+D</kbd>). This turns off the feature that
automatically generates string and <code>.FILL</code> directives,
so now each uncategorized byte is on its own line.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-fmt-word.png" alt="t2-1000-fmt-word"/>
</div>
<div class="grid-item-text">
<p>You could select the first two lines and use
<samp>Actions &gt; Edit Operand</samp> to format them as a 16-bit
little-endian hex value, but there's a shortcut: select the first
line with data (address $1000), then <samp>Actions &gt; Format As Word</samp>
(<kbd class="key">Ctrl+W</kbd>).
It automatically grabbed the following byte and combined them.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-setcode.png" alt="t2-1000-setcode"/>
</div>
<div class="grid-item-text">
<p>Since we believe $2000 is the load address for everything that follows,
click on the line with address $1002, select
<samp>Actions &gt; Set Address</samp>, and enter "2000". With that line
still selected, use <samp>Actions &gt; Tag Address As Code Start Point</samp>
(<kbd class="key">Ctrl+H</kbd> <kbd class="key">Ctrl+C</kbd>) to
tell the analyzer to start looking for code there.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-1000-ready.png" alt="t2-1000-ready"/>
</div>
<div class="grid-item-text">
<p>That looks better, but the branch destination ($203D) is off the bottom of the
screen (unless you have a really tall screen or small fonts) because of
all the intervening data. Use <samp>Edit &gt; Toggle Data Scan</samp>
(<kbd class="key">Ctrl+D</kbd>)
to turn the string-finder back on. Now it's easier to read.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="generating-code.html" class="btn-previous">&laquo; Previous</a>
<a href="string-formatting.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

456
docs/sgtutorial/editing-data.html
View File

@ -1,204 +1,252 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Editing Data - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-editing-data -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-editing-data").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Editing Data</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-stringblob.png" alt="t1-data-stringblob"/>
</div>
<div class="grid-item-text">
<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. (You may need
to increase the width of the Operand column to see the whole thing.) Notice
that the opcode for the very last line is '+', which means the operand
is 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-edited-1.png" alt="t1-data-edited-1"/>
</div>
<div class="grid-item-text">
<p>Each character is now on its own line. The selection still spans the
same set of addresses.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-editdlg-2.png" alt="t1-data-editdlg-2"/>
</div>
<div class="grid-item-text">
<p>Select address $203D on its own, then Actions &gt; Edit Label. Set the
label to "<kbd>STR1</kbd>". Move up a bit and select address $2030, then scroll to
the bottom and shift-click address $2070. Select
<samp>Actions &gt; Edit Operand</samp>.
At the top it should now say, "<samp>65 bytes selected in 2 groups</samp>".
There are two groups because the presence of a label split the data into
two separate regions. From the <samp>Character encoding</samp> pop-up down
in the "String" section, make sure <samp>Low or High ASCII</samp> encoding
is selected, then select the <samp>Mixed character and non-character</samp>
string type and click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-edited-2.png" alt="t1-data-edited-2"/>
</div>
<div class="grid-item-text">
<p>We now have two <code>.STR</code> lines, one for <samp>"string zero "</samp>,
and one with the "<samp>STR1</samp>" label and the rest of the string data.
This is okay,
but it's not really what we want. The code at $200B appears to be loading
a 16-bit address from data at $2025, so we want to use that if we can.</p>
<p>Select <samp>Edit &gt; Undo</samp> three times. You should be back to the
state where there's a single <code>.STR</code> line at the bottom of
the file, split across two lines with a '+'.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-string-bytes.png" alt="t1-data-string-bytes"/>
</div>
<div class="grid-item-text">
<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
<samp>Actions &gt; Toggle Single-Byte Format</samp>
(or hit <kbd class="key">Ctrl+B</kbd>).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The data starting at $2025 appears to be 16-bit little-endian
addresses that point into the table of strings, so let's format
them appropriately.</p>
<!--
<p>Double-click the operand column on line $2025 ("$30") to open
the operand data format editor. Because you only have one byte selected,
most of the options are disabled. This won't do what we want, so
click <samp>Cancel</samp>.</p>
-->
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-editdlg-3.png" alt="t1-data-editdlg-3"/>
</div>
<div class="grid-item-text">
<p>Select the line at $2025, then shift-click the line at $202E. Right-click
and select <samp>Edit Operand</samp>. If you selected the correct set of bytes,
the top line in the dialog should now say, "<samp>10 bytes selected</samp>".
Because 10 is a multiple of two, the 16-bit formats are enabled. It's not a multiple
of 3 or 4, so the 24-bit and 32-bit options are not enabled. Click the
<samp>16-bit words, little-endian</samp> radio button, then over to the right,
click the <samp>Address</samp> radio button. Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-edited-3.png" alt="t1-data-edited-3"/>
</div>
<div class="grid-item-text">
<p>We just told SourceGen that those 10 bytes are actually five 16-bit numeric
references. SourceGen determined that the addresses are contained in the
file, and generated labels for each of them. Labels only work if they're
on their own line, so the long string was automatically split into five
separate <code>.STR</code> statements.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Note we didn't explicitly format the string data. We formatted
the addresses at $2025, which placed labels at the start of the strings,
but the strings themselves were automatically detected and formatted
by SourceGen. By default, SourceGen looks for ASCII strings, but this
can be changed in the project properties. You can even disable the
string auto-detection entirely if you want.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Editing Data - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-editing-data -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data" class="active"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Editing Data</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-stringblob.png" alt="t1-data-stringblob"/>
</div>
<div class="grid-item-text">
<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. (You may need
to increase the width of the Operand column to see the whole thing.) Notice
that the opcode for the very last line is '+', which means the operand
is 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-edited-1.png" alt="t1-data-edited-1"/>
</div>
<div class="grid-item-text">
<p>Each character is now on its own line. The selection still spans the
same set of addresses.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-editdlg-2.png" alt="t1-data-editdlg-2"/>
</div>
<div class="grid-item-text">
<p>Select address $203D on its own, then Actions &gt; Edit Label. Set the
label to "<kbd>STR1</kbd>". Move up a bit and select address $2030, then scroll to
the bottom and shift-click address $2070. Select
<samp>Actions &gt; Edit Operand</samp>.
At the top it should now say, "<samp>65 bytes selected in 2 groups</samp>".
There are two groups because the presence of a label split the data into
two separate regions. From the <samp>Character encoding</samp> pop-up down
in the "String" section, make sure <samp>Low or High ASCII</samp> encoding
is selected, then select the <samp>Mixed character and non-character</samp>
string type and click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-edited-2.png" alt="t1-data-edited-2"/>
</div>
<div class="grid-item-text">
<p>We now have two <code>.STR</code> lines, one for <samp>"string zero "</samp>,
and one with the "<samp>STR1</samp>" label and the rest of the string data.
This is okay,
but it's not really what we want. The code at $200B appears to be loading
a 16-bit address from data at $2025, so we want to use that if we can.</p>
<p>Select <samp>Edit &gt; Undo</samp> three times. You should be back to the
state where there's a single <code>.STR</code> line at the bottom of
the file, split across two lines with a '+'.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-string-bytes.png" alt="t1-data-string-bytes"/>
</div>
<div class="grid-item-text">
<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
<samp>Actions &gt; Toggle Single-Byte Format</samp>
(or hit <kbd class="key">Ctrl+B</kbd>).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The data starting at $2025 appears to be 16-bit little-endian
addresses that point into the table of strings, so let's format
them appropriately.</p>
<!--
<p>Double-click the operand column on line $2025 ("$30") to open
the operand data format editor. Because you only have one byte selected,
most of the options are disabled. This won't do what we want, so
click <samp>Cancel</samp>.</p>
-->
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-editdlg-3.png" alt="t1-data-editdlg-3"/>
</div>
<div class="grid-item-text">
<p>Select the line at $2025, then shift-click the line at $202E. Right-click
and select <samp>Edit Operand</samp>. If you selected the correct set of bytes,
the top line in the dialog should now say, "<samp>10 bytes selected</samp>".
Because 10 is a multiple of two, the 16-bit formats are enabled. It's not a multiple
of 3 or 4, so the 24-bit and 32-bit options are not enabled. Click the
<samp>16-bit words, little-endian</samp> radio button, then over to the right,
click the <samp>Address</samp> radio button. Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-data-edited-3.png" alt="t1-data-edited-3"/>
</div>
<div class="grid-item-text">
<p>We just told SourceGen that those 10 bytes are actually five 16-bit numeric
references. SourceGen determined that the addresses are contained in the
file, and generated labels for each of them. Labels only work if they're
on their own line, so the long string was automatically split into five
separate <code>.STR</code> statements.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Note we didn't explicitly format the string data. We formatted
the addresses at $2025, which placed labels at the start of the strings,
but the strings themselves were automatically detected and formatted
by SourceGen. By default, SourceGen looks for ASCII strings, but this
can be changed in the project properties. You can even disable the
string auto-detection entirely if you want.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="labels-symbols.html" class="btn-previous">&laquo; Previous</a>
<a href="generating-code.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

430
docs/sgtutorial/extension-scripts.html
View File

@ -1,191 +1,239 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Extension Scripts - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-extension-scripts -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-extension-scripts").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Extension Scripts</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Some repetitive formatting tasks can be handled with automatic scripts.
This is especially useful for inline data, which can confuse the code
analyzer.</p>
<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>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-add-inlinel1.png" alt="t4-add-inlinel1"/>
</div>
<div class="grid-item-text">
<p>Take a look at the disassembly listing. The file starts with a
<code>JSR</code> followed by a string that begins with a small number.
This appears to be a string with a leading length byte. We want to load
a script that can handle that, so use
<samp>Edit &gt; Project Properties</samp>, select the
<samp>Extension Scripts</samp> tab, and click
<samp>Add Scripts from Project</samp>. The file
browser opens in the project directory. Select the file
"InlineL1String.cs", click <samp>Open</samp>, then <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinel1-src.png" alt="t4-inlinel1-src"/>
</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 called <code>PrintInlineL1String</code>. So let's give it one.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Double-click the <code>JSR</code> opcode on line $1000
to jump to address $1026. The only thing there is an <code>RTS</code>.
It's supposed to be a routine that prints a string with a leading length
byte, but for the sake of keeping the example code short it's just a
place-holder. Use the curly toolbar arrow
(or <kbd class="key">Alt+LeftArrow</kbd>) to jump back to $1026.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinel1-edit.png" alt="t4-inlinel1-edit"/>
</div>
<div class="grid-item-text">
<p>This time, double-click the <code>JSR</code> <i>operand</i>
("<samp>L1026</samp>") to edit the operand.
Click <samp>Create Label</samp>, and enter <kbd>PrintInlineL1String</kbd>.
Remember that labels are case-sensitive;
you must enter it exactly as shown. Hit <samp>OK</samp> to accept the label,
and <samp>OK</samp> to close the operand editor.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinel1-done.png" alt="t4-inlinel1-done"/>
</div>
<div class="grid-item-text">
<p>If all went well, address $1003
should now be an L1 string "<code>How long?</code>", and address $100D
should be another <code>JSR</code>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The next <code>JSR</code> appears to be followed by a null-terminated string, so
we'll need something that handles that.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinenull-src.png" alt="t4-inlinenull-src"/>
</div>
<div class="grid-item-text">
<p>Go back into Project Properties
and add the script called "InlineNullTermString.cs" from the project directory.
This script is slightly different, in that it handles any <code>JSR</code> to a label
that starts with <code>PrintInlineNullString</code>. So let's give it a couple of
those.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinenull-done.png" alt="t4-inlinenull-done"/>
</div>
<div class="grid-item-text">
<p>Double-click the operand on line $100D ("<code>L1027</code>"),
click <samp>Create Label</samp>,
and set the label to "<kbd>PrintInlineNullStringOne</kbd>".
Hit <samp>OK</samp> twice. That formatted the first one and got us
to the next <code>JSR</code>. Repeat the process on line $1019
("<code>L1028</code>"), setting the label to "<kbd>PrintInlineNullStringTwo</kbd>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The entire project is now nicely formatted. In a real project the
"Print Inline" locations would be actual print functions, not just <code>RTS</code>
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
entry points or chain through different locations.</p>
<p>Extension scripts can make your life much easier, but they do require
some programming experience. See the SourceGen manual for more details.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Extension Scripts - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-extension-scripts -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts" class="active"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Extension Scripts</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Some repetitive formatting tasks can be handled with automatic scripts.
This is especially useful for inline data, which can confuse the code
analyzer.</p>
<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>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-add-inlinel1.png" alt="t4-add-inlinel1"/>
</div>
<div class="grid-item-text">
<p>Take a look at the disassembly listing. The file starts with a
<code>JSR</code> followed by a string that begins with a small number.
This appears to be a string with a leading length byte. We want to load
a script that can handle that, so use
<samp>Edit &gt; Project Properties</samp>, select the
<samp>Extension Scripts</samp> tab, and click
<samp>Add Scripts from Project</samp>. The file
browser opens in the project directory. Select the file
"InlineL1String.cs", click <samp>Open</samp>, then <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinel1-src.png" alt="t4-inlinel1-src"/>
</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 called <code>PrintInlineL1String</code>. So let's give it one.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Double-click the <code>JSR</code> opcode on line $1000
to jump to address $1026. The only thing there is an <code>RTS</code>.
It's supposed to be a routine that prints a string with a leading length
byte, but for the sake of keeping the example code short it's just a
place-holder. Use the curly toolbar arrow
(or <kbd class="key">Alt+LeftArrow</kbd>) to jump back to $1026.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinel1-edit.png" alt="t4-inlinel1-edit"/>
</div>
<div class="grid-item-text">
<p>This time, double-click the <code>JSR</code> <i>operand</i>
("<samp>L1026</samp>") to edit the operand.
Click <samp>Create Label</samp>, and enter <kbd>PrintInlineL1String</kbd>.
Remember that labels are case-sensitive;
you must enter it exactly as shown. Hit <samp>OK</samp> to accept the label,
and <samp>OK</samp> to close the operand editor.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinel1-done.png" alt="t4-inlinel1-done"/>
</div>
<div class="grid-item-text">
<p>If all went well, address $1003
should now be an L1 string "<code>How long?</code>", and address $100D
should be another <code>JSR</code>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The next <code>JSR</code> appears to be followed by a null-terminated string, so
we'll need something that handles that.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinenull-src.png" alt="t4-inlinenull-src"/>
</div>
<div class="grid-item-text">
<p>Go back into Project Properties
and add the script called "InlineNullTermString.cs" from the project directory.
This script is slightly different, in that it handles any <code>JSR</code> to a label
that starts with <code>PrintInlineNullString</code>. So let's give it a couple of
those.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t4-inlinenull-done.png" alt="t4-inlinenull-done"/>
</div>
<div class="grid-item-text">
<p>Double-click the operand on line $100D ("<code>L1027</code>"),
click <samp>Create Label</samp>,
and set the label to "<kbd>PrintInlineNullStringOne</kbd>".
Hit <samp>OK</samp> twice. That formatted the first one and got us
to the next <code>JSR</code>. Repeat the process on line $1019
("<code>L1028</code>"), setting the label to "<kbd>PrintInlineNullStringTwo</kbd>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The entire project is now nicely formatted. In a real project the
"Print Inline" locations would be actual print functions, not just <code>RTS</code>
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
entry points or chain through different locations.</p>
<p>Extension scripts can make your life much easier, but they do require
some programming experience. See the SourceGen manual for more details.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="address-tables.html" class="btn-previous">&laquo; Previous</a>
<a href="visualizations.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

310
docs/sgtutorial/generating-code.html
View File

@ -1,131 +1,179 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Generating Code - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-generating-code -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-generating-code").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Generating Code</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-asmgen-dlg.png" alt="t1-asmgen-dlg"/>
</div>
<div class="grid-item-text">
<p>You can generate assembly source code from the disassembled data.
Select <samp>File &gt; Assemble</samp> (or hit <kbd class="key">Ctrl+Shift+A</kbd>)
to open the source generation and assembly dialog.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-asmgen-preview.png" alt="t1-asmgen-preview"/>
</div>
<div class="grid-item-text">
<p>Pick your favorite assembler from the drop list at the top right,
then click <samp>Generate</samp>. 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 called a "preview" because it has line numbers
added and is cut off after a certain limit.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-asmgen-asmout.png" alt="t1-asmgen-asmout"/>
</div>
<div class="grid-item-text">
<p>If you have a cross-assembler installed and configured, you can run
it by clicking <samp>Run Assembler</samp>. The output from the assembler will appear
in the lower window, along with an indication of whether the assembled
file matches the original. (Unless there are bugs in SourceGen or the assembler,
it should always match exactly.)</p>
<p>Click <samp>Close</samp> to close the window.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>If you want to output source code for display on a web site or
posting in an online forum, you have a couple of options. The easiest
way to do this is to select the lines and use <samp>Edit &gt; Copy</samp>
to copy them to the system clipboard, and then simply paste it elsewhere.
The format will match what's on the screen, and will not be tailored to
any specific assembler. The set of columns included in the copy can be
configured in the application settings editor, e.g. you can limit it to
just the columns typically found in source code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-export-dlg.png" alt="t1-export-dlg"/>
</div>
<div class="grid-item-text">
<p>To export some or all of the project as text or HTML, use
<samp>File &gt; Export</samp> (<kbd class="key">Ctrl+Shift+E</kbd>).
This is an easy way to share a disassembly listing with people who
don't have access to SourceGen. The feature is primarily useful in
situations where you want to show the disassembly data (Address
and Bytes), or want to embed visualizations (explained later).</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Generating Code - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-generating-code -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code" class="active"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Generating Code</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-asmgen-dlg.png" alt="t1-asmgen-dlg"/>
</div>
<div class="grid-item-text">
<p>You can generate assembly source code from the disassembled data.
Select <samp>File &gt; Assemble</samp> (or hit <kbd class="key">Ctrl+Shift+A</kbd>)
to open the source generation and assembly dialog.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-asmgen-preview.png" alt="t1-asmgen-preview"/>
</div>
<div class="grid-item-text">
<p>Pick your favorite assembler from the drop list at the top right,
then click <samp>Generate</samp>. 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 called a "preview" because it has line numbers
added and is cut off after a certain limit.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-asmgen-asmout.png" alt="t1-asmgen-asmout"/>
</div>
<div class="grid-item-text">
<p>If you have a cross-assembler installed and configured, you can run
it by clicking <samp>Run Assembler</samp>. The output from the assembler will appear
in the lower window, along with an indication of whether the assembled
file matches the original. (Unless there are bugs in SourceGen or the assembler,
it should always match exactly.)</p>
<p>Click <samp>Close</samp> to close the window.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>If you want to output source code for display on a web site or
posting in an online forum, you have a couple of options. The easiest
way to do this is to select the lines and use <samp>Edit &gt; Copy</samp>
to copy them to the system clipboard, and then simply paste it elsewhere.
The format will match what's on the screen, and will not be tailored to
any specific assembler. The set of columns included in the copy can be
configured in the application settings editor, e.g. you can limit it to
just the columns typically found in source code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-export-dlg.png" alt="t1-export-dlg"/>
</div>
<div class="grid-item-text">
<p>To export some or all of the project as text or HTML, use
<samp>File &gt; Export</samp> (<kbd class="key">Ctrl+Shift+E</kbd>).
This is an easy way to share a disassembly listing with people who
don't have access to SourceGen. The feature is primarily useful in
situations where you want to show the disassembly data (Address
and Bytes), or want to embed visualizations (explained later).</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="editing-data.html" class="btn-previous">&laquo; Previous</a>
<a href="digging-deeper.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

220
docs/sgtutorial/index.html
View File

@ -1,86 +1,134 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-index -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-index").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h1>SourceGen Tutorial</h1>
<p>This tutorial demonstrates many of the features of SourceGen. It will not
teach you 6502 assembly language, nor reveal any tricks for working with a
specific system.</p>
<p>The tutorial is divided into four broad sections:</p>
<ul>
<li><a href="about-disasm.html">About Disassembly</a>: start here if you're
unclear how "disassembling" works. Or is.</li>
<li><a href="using-sourcegen.html">Using SourceGen</a>: start here if you're
familiar with disassembly. This shows how to create a project, move around in
the file, make edits, and generate assembly source.</li>
<li><a href="deeper-subjects.html">Deeper Subjects</a>: some less-common
situations you may run into are discussed, along with some advanced features.</li>
<li><a href="advanced-topics.html">Advanced Topics</a>: a quick look at
some optional but very handy features.</li>
</ul>
<p>The tutorials work best if you follow along.</p>
<p>The 6502bench software distribution comes with a full manual. Launch
SourceGen and hit <kbd class="key">F1</kbd> to access it.
<!--
You can see the tip-of-tree documentation via a
<a href="https://htmlpreview.github.io/?https://github.com/fadden/6502bench/blob/master/SourceGen/RuntimeData/Help/index.html">htmlpreview</a>
URL.
-->
</p>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-index -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index" class="active"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h1>SourceGen Tutorial</h1>
<p>This tutorial demonstrates many of the features of SourceGen. It will not
teach you 6502 assembly language, nor reveal any tricks for working with a
specific system.</p>
<p>The tutorial is divided into four broad sections:</p>
<ul>
<li><a href="about-disasm.html">About Disassembly</a>: start here if you're
unclear how "disassembling" works. Or is.</li>
<li><a href="using-sourcegen.html">Using SourceGen</a>: start here if you're
familiar with disassembly. This shows how to create a project, move around in
the file, make edits, and generate assembly source.</li>
<li><a href="deeper-subjects.html">Deeper Subjects</a>: some less-common
situations you may run into are discussed, along with some advanced features.</li>
<li><a href="advanced-topics.html">Advanced Topics</a>: a quick look at
some optional but very handy features.</li>
</ul>
<p>The tutorials work best if you follow along.</p>
<p>The 6502bench software distribution comes with a full manual. Launch
SourceGen and hit <kbd class="key">F1</kbd> to access it.
<!--
You can see the tip-of-tree documentation via a
<a href="https://htmlpreview.github.io/?https://github.com/fadden/6502bench/blob/master/SourceGen/RuntimeData/Help/index.html">htmlpreview</a>
URL.
-->
</p>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

320
docs/sgtutorial/inline-data.html
View File

@ -1,136 +1,184 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Inline Data - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-inline-data -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-inline-data").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Inline Data</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-206b.png" alt="t2-206b"/>
</div>
<div class="grid-item-text">
<p>Consider the code at address $206B. It's a <code>JSR</code> followed by some
ASCII text, then a $00 byte, and then what might be code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-20ab-1.png" alt="t2-20ab-1"/>
<br/>
...
<br/>
<img src="images/t2-20ab-2.png" alt="t2-20ab-2"/>
</div>
<div class="grid-item-text">
<p>Double-click on the <code>JSR</code> opcode
to jump to $20AB to see the function. It pulls the
call address off the stack, and uses it as a pointer. When it encounters
a zero byte, it breaks out of the loop, pushes the adjusted pointer
value back onto the stack, and returns.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>This is an example of "inline data", where a function uses the return
address to get a pointer to data. The return address is adjusted to
point past the inline data before returning (technically, it points at
the very last byte of the inline data, because
<code>RTS</code> jumps to address + 1).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-inline-tag.png" alt="t2-inline-tag"/>
</div>
<div class="grid-item-text">
<p>To format the data, we first need to tell SourceGen that there's data
in line with the code. Select the line at address $206E, then
shift-click the line at address $2077. Use
<samp>Actions &gt; Tag Bytes As Inline Data</samp>
(<kbd class="key">Ctrl+H</kbd><kbd class="key">Ctrl+I</kbd>).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-inline-after.png" alt="t2-inline-after"/>
</div>
<div class="grid-item-text">
<p>The data turns to single-byte values, and we now see the code
continuing at address $2078. We can format the data as a string by
using <samp>Actions &gt; Edit Operand</samp>,
setting the Character Encoding to <samp>Low or High ASCII</samp>,
and selecting <samp>null-terminated strings</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>That's pretty straightforward, but this could quickly become tedious if
there were a lot of these. SourceGen allows you to define scripts to
automate common formatting tasks. This is covered in the "Extension
Scripts" tutorial.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Inline Data - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-inline-data -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data" class="active"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Inline Data</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-206b.png" alt="t2-206b"/>
</div>
<div class="grid-item-text">
<p>Consider the code at address $206B. It's a <code>JSR</code> followed by some
ASCII text, then a $00 byte, and then what might be code.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-20ab-1.png" alt="t2-20ab-1"/>
<br/>
...
<br/>
<img src="images/t2-20ab-2.png" alt="t2-20ab-2"/>
</div>
<div class="grid-item-text">
<p>Double-click on the <code>JSR</code> opcode
to jump to $20AB to see the function. It pulls the
call address off the stack, and uses it as a pointer. When it encounters
a zero byte, it breaks out of the loop, pushes the adjusted pointer
value back onto the stack, and returns.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>This is an example of "inline data", where a function uses the return
address to get a pointer to data. The return address is adjusted to
point past the inline data before returning (technically, it points at
the very last byte of the inline data, because
<code>RTS</code> jumps to address + 1).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-inline-tag.png" alt="t2-inline-tag"/>
</div>
<div class="grid-item-text">
<p>To format the data, we first need to tell SourceGen that there's data
in line with the code. Select the line at address $206E, then
shift-click the line at address $2077. Use
<samp>Actions &gt; Tag Bytes As Inline Data</samp>
(<kbd class="key">Ctrl+H</kbd><kbd class="key">Ctrl+I</kbd>).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-inline-after.png" alt="t2-inline-after"/>
</div>
<div class="grid-item-text">
<p>The data turns to single-byte values, and we now see the code
continuing at address $2078. We can format the data as a string by
using <samp>Actions &gt; Edit Operand</samp>,
setting the Character Encoding to <samp>Low or High ASCII</samp>,
and selecting <samp>null-terminated strings</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>That's pretty straightforward, but this could quickly become tedious if
there were a lot of these. SourceGen allows you to define scripts to
automate common formatting tasks. This is covered in the "Extension
Scripts" tutorial.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="local-variables.html" class="btn-previous">&laquo; Previous</a>
<a href="odds-ends.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

752
docs/sgtutorial/labels-symbols.html
View File

@ -1,352 +1,400 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Labels &amp; Symbols - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-labels-symbols -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-labels-symbols").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Labels &amp; Symbols</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Suppose you want to call some code at address $1000. CPUs
fundamentally deal with numeric values, so the machine code to
call it would be <code>JSR $1000</code>. Humans tend to work better with
words, so associating a meaningful symbol with address $1000
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>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-label.png" alt="t1-edit-label"/>
</div>
<div class="grid-item-text">
<p>On the line at address $2000, select
<samp>Actions &gt; Edit Label</samp>, or double-click on the label
"<code>L2000</code>". Change the label to "<kbd>MAIN</kbd>", and hit
<kbd class="key">Enter</kbd>. The label changes on that line,
and on the two lines that refer to address $2000.
(If you're not sure which lines refer to address $2000,
select line $2000 and check the list in the References window.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Sometimes the target address falls outside the data file. Examples
include calls to ROM routines, use of zero-page storage, and access to
memory-mapped I/O locations. SourceGen classifies these as <i>external</i>,
and does not generate a symbol. In an assembler source file, symbols
for these would be expressed as equates (e.g. <code>FOO = $8000</code>),
usually at the top of the file or in an "include file". SourceGen
allows you to specify symbols for addresses and numeric constants within
the project ("<i>project symbols</i>"), or in a symbol file that can be
included in multiple projects ("<i>platform symbols</i>"). The SourceGen
distribution includes platform symbol files with ROM addresses for
several common systems.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-pre-sym-2000.png" alt="t1-pre-sym-2000"/>
</div>
<div class="grid-item-text">
<p>For an example, consider the code at address $2000, which is
<code>LDA $3000</code>. We want to assign the symbol "INPUT" to address
$3000, but we can't do that by editing a label because it's not inside
the file bounds. We can open the project symbol editor from the project
properties editor, or we can use a shortcut.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-sym-2000.png" alt="t1-edit-sym-2000"/>
</div>
<div class="grid-item-text">
<p>With the line at $2000 selected, use <samp>Actions &gt; Edit Operand</samp>,
or double-click on the value in the <samp>Operand</samp> column
("<code>$3000</code>"). This opens the
Edit Instruction Operand dialog. In the bottom left, click
<samp>Create Project Symbol</samp>. Set the <samp>Label</samp> field to
"<kbd>INPUT</kbd>", and
click <samp>OK</samp>, then <samp>OK</samp> in the operand editor.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-2000-done.png" alt="t1-edit-2000-done"/>
</div>
<div class="grid-item-text">
<p>The instruction at $2000 now uses the symbol "<samp>INPUT</samp>"
as its operand. If you scroll to the top of the file, you will see a
"<code>.EQ</code>" line for the symbol.</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Numeric v. Symbolic</h4>
<div class="grid-container">
<div class="grid-item-text">
<p>When SourceGen sees a reference to an address, such as the operand of an
absolute <code>JSR</code> or <code>LDA</code>, it recognizes it
as a <i>numeric reference</i>. You can edit the instruction's operand
to use a symbol instead, changing to a <i>symbolic reference</i>.
Sometimes the way these are handled can be confusing.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-before.png" alt="t1-sym-2005-before"/>
</div>
<div class="grid-item-text">
<p>Let's use the branch statement at $2005 to illustrate the difference.
It performs a branch to $2009, which was automatically assigned the
label "<samp>L2009</samp>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-labeled.png" alt="t1-sym-2005-labeled"/>
</div>
<div class="grid-item-text">
<p>Edit the label at $2009 (double-click on "<samp>L2009</samp>" there),
and change it to "<kbd>IN_RANGE</kbd>". Line $2005 changes to match.
This works because SourceGen
is auto-formatting line $2005's operand based on the label it finds when it
chases the numeric reference to $2009.
The Info window shows this as <code>Format (auto): symbol "IN_RANGE"</code>.</p>
<p>Use <samp>Edit &gt; Undo</samp> to revert the label change.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-edit.png" alt="t1-sym-2005-edit"/>
</div>
<div class="grid-item-text">
<p>Edit the instruction operand at $2005 (double-click on
"<samp>L2009</samp>" there). Change the format to <samp>Symbol</samp>,
and type "<kbd>IN_RANGE</kbd>" in the symbol box.
The preview shows <samp>BCC IN_RANGE (?)</samp>, which hints at a
problem. Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-nosym.png" alt="t1-sym-2005-nosym"/>
</div>
<div class="grid-item-text">
<p>Some things changed, but not the things we wanted. Line $2005 now
says <code>BCC $2009</code>, instead of <code>BCC L2009</code>, and the
label at $2009 has disappeared entirely. What went wrong?</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The problem is that we edited the operand to use a symbol that isn't
defined anywhere. Because "IN_RANGE" isn't defined, the operand was
given the default format, and displayed as a hex value.
The numeric reference to $2009 was replaced by the symbol, and nothing
else refers to that address,
so SourceGen no longer had any reason to put an auto-generated label
on line $2009, which is why that disappeared.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-msg-window.png" alt="t1-sym-2005-msg-window"/>
</div>
<div class="grid-item-text">
<p>The missing symbol is called out in a message window that popped up
at the bottom of the code list window. The message window only appears
when there are messages to read. You can hide the window with the
<samp>Hide</samp> button, and make it re-appear with the button in the
bottom right of the main window that currently says <samp>1 message</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-explicit.png" alt="t1-sym-2005-explicit"/>
</div>
<div class="grid-item-text">
<p>We can resolve this issue by providing the desired symbol. As you
did earlier, edit the label on line $2009 (double-click in the label column)
and set it to "<kbd>IN_RANGE</kbd>". When you do, the operand on line $2005
is updated appropriately.
If you select line $2005, the Info window shows the format as
<samp>Format: symbol "IN_RANGE"</samp>, indicating that the symbol
was set explicitly rather than automatically.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-adjust.png" alt="t1-sym-2005-adjust"/>
</div>
<div class="grid-item-text">
<p>Symbolic references always link to the symbol, even when the symbol
doesn't match the numeric reference. To see this, remove the label from
line $2009 by undoing that change with <samp>Edit &gt; Undo</samp>,
so the symbol is again undefined. Now set the label on the following line,
$200A, to "<kbd>IN_RANGE</kbd>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Line $2005 now says "<code>BCC IN_RANGE-1</code>". Earlier you set
the operand to be a symbolic reference to "<samp>IN_RANGE</samp>", but the symbol
doesn't quite match, so SourceGen automatically adjusted the operand by
one byte to point to the correct address. Generally speaking, SourceGen
will do its best to use the symbols that you tell it to, and will adjust the
symbolic references so that the code assembles correctly.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Edit the label on line $200A, and change it to "<kbd>NIFTY</kbd>".
Note how the reference on line $2005 also changed. This is an example
of a "refactoring rename": when you changed the label, SourceGen
automatically found everything that referred to it and updated it.
If you edit the operand on line $2005, you can confirm that the
symbol has changed.</p>
<p>(If you want to clean this up before continuing on to the next
section, put the label back on line $2009.)</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Non-Unique Label</h4>
<div class="grid-container">
<div class="grid-item-text">
<p>Most assemblers have a notion of "local" labels, which go out of
scope when a non-local (global) label is encountered. The actual
definition of "local" is assembler-specific, but SourceGen allows you
to create labels that serve the same purpose.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-local-loop-edit.png" alt="t1-local-loop-edit"/>
</div>
<div class="grid-item-text">
<p>By default, newly-created labels have global scope and must be
unique. You can change these attributes when you edit the label. Up near the
top of the file, at address $1002, double-click on the label ("L1002").
Change the label to "<kbd>LOOP</kbd>" and click the "non-unique local"
radio button.
Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-local-loop1.png" alt="t1-local-loop1"/>
</div>
<div class="grid-item-text">
<p>The label at line $1002 (and the operand on line $100B) should now
be "<samp>@LOOP</samp>". By default, '@' is used to indicate non-unique labels,
though you can change it to a different character in the application
settings.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-local-loop2.png" alt="t1-local-loop2"/>
</div>
<div class="grid-item-text">
<p>At address $2019, double-click to edit the label ("<samp>L2019</samp>"). If
you type "<kbd>MAIN</kbd>" or "<kbd>IS_OK</kbd>" with Global selected you'll
get an error, but if you type "<kbd>@LOOP</kbd>" it will be accepted. Note
the "non-unique local" radio
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
rename them to make them unique, depending on what your preferred assembler
allows.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Labels &amp; Symbols - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-labels-symbols -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols" class="active"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Labels &amp; Symbols</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Suppose you want to call some code at address $1000. CPUs
fundamentally deal with numeric values, so the machine code to
call it would be <code>JSR $1000</code>. Humans tend to work better with
words, so associating a meaningful symbol with address $1000
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>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-label.png" alt="t1-edit-label"/>
</div>
<div class="grid-item-text">
<p>On the line at address $2000, select
<samp>Actions &gt; Edit Label</samp>, or double-click on the label
"<code>L2000</code>". Change the label to "<kbd>MAIN</kbd>", and hit
<kbd class="key">Enter</kbd>. The label changes on that line,
and on the two lines that refer to address $2000.
(If you're not sure which lines refer to address $2000,
select line $2000 and check the list in the References window.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Sometimes the target address falls outside the data file. Examples
include calls to ROM routines, use of zero-page storage, and access to
memory-mapped I/O locations. SourceGen classifies these as <i>external</i>,
and does not generate a symbol. In an assembler source file, symbols
for these would be expressed as equates (e.g. <code>FOO = $8000</code>),
usually at the top of the file or in an "include file". SourceGen
allows you to specify symbols for addresses and numeric constants within
the project ("<i>project symbols</i>"), or in a symbol file that can be
included in multiple projects ("<i>platform symbols</i>"). The SourceGen
distribution includes platform symbol files with ROM addresses for
several common systems.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-pre-sym-2000.png" alt="t1-pre-sym-2000"/>
</div>
<div class="grid-item-text">
<p>For an example, consider the code at address $2000, which is
<code>LDA $3000</code>. We want to assign the symbol "INPUT" to address
$3000, but we can't do that by editing a label because it's not inside
the file bounds. We can open the project symbol editor from the project
properties editor, or we can use a shortcut.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-sym-2000.png" alt="t1-edit-sym-2000"/>
</div>
<div class="grid-item-text">
<p>With the line at $2000 selected, use <samp>Actions &gt; Edit Operand</samp>,
or double-click on the value in the <samp>Operand</samp> column
("<code>$3000</code>"). This opens the
Edit Instruction Operand dialog. In the bottom left, click
<samp>Create Project Symbol</samp>. Set the <samp>Label</samp> field to
"<kbd>INPUT</kbd>", and
click <samp>OK</samp>, then <samp>OK</samp> in the operand editor.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-2000-done.png" alt="t1-edit-2000-done"/>
</div>
<div class="grid-item-text">
<p>The instruction at $2000 now uses the symbol "<samp>INPUT</samp>"
as its operand. If you scroll to the top of the file, you will see a
"<code>.EQ</code>" line for the symbol.</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Numeric v. Symbolic</h4>
<div class="grid-container">
<div class="grid-item-text">
<p>When SourceGen sees a reference to an address, such as the operand of an
absolute <code>JSR</code> or <code>LDA</code>, it recognizes it
as a <i>numeric reference</i>. You can edit the instruction's operand
to use a symbol instead, changing to a <i>symbolic reference</i>.
Sometimes the way these are handled can be confusing.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-before.png" alt="t1-sym-2005-before"/>
</div>
<div class="grid-item-text">
<p>Let's use the branch statement at $2005 to illustrate the difference.
It performs a branch to $2009, which was automatically assigned the
label "<samp>L2009</samp>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-labeled.png" alt="t1-sym-2005-labeled"/>
</div>
<div class="grid-item-text">
<p>Edit the label at $2009 (double-click on "<samp>L2009</samp>" there),
and change it to "<kbd>IN_RANGE</kbd>". Line $2005 changes to match.
This works because SourceGen
is auto-formatting line $2005's operand based on the label it finds when it
chases the numeric reference to $2009.
The Info window shows this as <code>Format (auto): symbol "IN_RANGE"</code>.</p>
<p>Use <samp>Edit &gt; Undo</samp> to revert the label change.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-edit.png" alt="t1-sym-2005-edit"/>
</div>
<div class="grid-item-text">
<p>Edit the instruction operand at $2005 (double-click on
"<samp>L2009</samp>" there). Change the format to <samp>Symbol</samp>,
and type "<kbd>IN_RANGE</kbd>" in the symbol box.
The preview shows <samp>BCC IN_RANGE (?)</samp>, which hints at a
problem. Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-nosym.png" alt="t1-sym-2005-nosym"/>
</div>
<div class="grid-item-text">
<p>Some things changed, but not the things we wanted. Line $2005 now
says <code>BCC $2009</code>, instead of <code>BCC L2009</code>, and the
label at $2009 has disappeared entirely. What went wrong?</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The problem is that we edited the operand to use a symbol that isn't
defined anywhere. Because "IN_RANGE" isn't defined, the operand was
given the default format, and displayed as a hex value.
The numeric reference to $2009 was replaced by the symbol, and nothing
else refers to that address,
so SourceGen no longer had any reason to put an auto-generated label
on line $2009, which is why that disappeared.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-msg-window.png" alt="t1-sym-2005-msg-window"/>
</div>
<div class="grid-item-text">
<p>The missing symbol is called out in a message window that popped up
at the bottom of the code list window. The message window only appears
when there are messages to read. You can hide the window with the
<samp>Hide</samp> button, and make it re-appear with the button in the
bottom right of the main window that currently says <samp>1 message</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-explicit.png" alt="t1-sym-2005-explicit"/>
</div>
<div class="grid-item-text">
<p>We can resolve this issue by providing the desired symbol. As you
did earlier, edit the label on line $2009 (double-click in the label column)
and set it to "<kbd>IN_RANGE</kbd>". When you do, the operand on line $2005
is updated appropriately.
If you select line $2005, the Info window shows the format as
<samp>Format: symbol "IN_RANGE"</samp>, indicating that the symbol
was set explicitly rather than automatically.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-sym-2005-adjust.png" alt="t1-sym-2005-adjust"/>
</div>
<div class="grid-item-text">
<p>Symbolic references always link to the symbol, even when the symbol
doesn't match the numeric reference. To see this, remove the label from
line $2009 by undoing that change with <samp>Edit &gt; Undo</samp>,
so the symbol is again undefined. Now set the label on the following line,
$200A, to "<kbd>IN_RANGE</kbd>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Line $2005 now says "<code>BCC IN_RANGE-1</code>". Earlier you set
the operand to be a symbolic reference to "<samp>IN_RANGE</samp>", but the symbol
doesn't quite match, so SourceGen automatically adjusted the operand by
one byte to point to the correct address. Generally speaking, SourceGen
will do its best to use the symbols that you tell it to, and will adjust the
symbolic references so that the code assembles correctly.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Edit the label on line $200A, and change it to "<kbd>NIFTY</kbd>".
Note how the reference on line $2005 also changed. This is an example
of a "refactoring rename": when you changed the label, SourceGen
automatically found everything that referred to it and updated it.
If you edit the operand on line $2005, you can confirm that the
symbol has changed.</p>
<p>(If you want to clean this up before continuing on to the next
section, put the label back on line $2009.)</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Non-Unique Label</h4>
<div class="grid-container">
<div class="grid-item-text">
<p>Most assemblers have a notion of "local" labels, which go out of
scope when a non-local (global) label is encountered. The actual
definition of "local" is assembler-specific, but SourceGen allows you
to create labels that serve the same purpose.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-local-loop-edit.png" alt="t1-local-loop-edit"/>
</div>
<div class="grid-item-text">
<p>By default, newly-created labels have global scope and must be
unique. You can change these attributes when you edit the label. Up near the
top of the file, at address $1002, double-click on the label ("L1002").
Change the label to "<kbd>LOOP</kbd>" and click the "non-unique local"
radio button.
Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-local-loop1.png" alt="t1-local-loop1"/>
</div>
<div class="grid-item-text">
<p>The label at line $1002 (and the operand on line $100B) should now
be "<samp>@LOOP</samp>". By default, '@' is used to indicate non-unique labels,
though you can change it to a different character in the application
settings.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-local-loop2.png" alt="t1-local-loop2"/>
</div>
<div class="grid-item-text">
<p>At address $2019, double-click to edit the label ("<samp>L2019</samp>"). If
you type "<kbd>MAIN</kbd>" or "<kbd>IS_OK</kbd>" with Global selected you'll
get an error, but if you type "<kbd>@LOOP</kbd>" it will be accepted. Note
the "non-unique local" radio
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
rename them to make them unique, depending on what your preferred assembler
allows.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="simple-edits.html" class="btn-previous">&laquo; Previous</a>
<a href="editing-data.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

588
docs/sgtutorial/local-variables.html
View File

@ -1,270 +1,318 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Local Variables - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-local-variables -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-local-variables").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Local Variables</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-203d-start.png" alt="t2-203d-start"/>
</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
pointer to $2063, which is a data area inside the file. So let's make it
official.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-203d-edit1.png" alt="t2-203d-edit1"/>
</div>
<div class="grid-item-text">
<p>Select the line at address $2063, and use
<samp>Actions &gt; Edit Label</samp> to
give it the label "<kbd>XDATA?</kbd>". The question mark on the end is there to
remind us that we're not entirely sure what this is. Now edit the
operand on line $203D, and set it to the symbol "<kbd>XDATA</kbd>",
with the part "low". The question mark isn't really part of the label,
so you don't need to type it here.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-203d-after-edit2.png" alt="t2-203d-after-edit2"/>
</div>
<div class="grid-item-text">
<p>Edit the operand on line $2041,
and set it to "<kbd>XDATA</kbd>" with the part "high". (The symbol text box
gets focus immediately, so you can start typing the symbol name as soon
as the dialog opens; you don't need to click around first.) If all
went well, the operands should now read <code>LDA #&lt;XDATA?</code>
and <code>LDA #&gt;XDATA?</code>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-create-ptr-entry.png" alt="t2-create-ptr-entry"/>
</div>
<div class="grid-item-text">
<p>Let's give the pointer a name. Select line $203D, and use
<samp>Actions &gt; Create Local Variable Table</samp>
to create an empty table. Click <samp>New Symbol</samp> on the right side.
Leave the Address button selected. Set the Label field to "<kbd>PTR1</kbd>",
the Value field to "$02", and the width to "2" (it's a 2-byte pointer).
Click "OK" to create the entry, and then
"OK" to update the table.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-after-ptr-entry.png" alt="t2-after-ptr-entry"/>
</div>
<div class="grid-item-text">
<p>There's now a <code>.VAR</code> statement
(similar to a <code>.EQU</code>) above line $203D,
and the stores to $02/$03 have changed to
"<samp>PTR1</samp>" and "<samp>PTR1+1</samp>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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>.
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2048.png" alt="t2-2048"/>
</div>
<div class="grid-item-text">
<p>The next bit of code masks the accumulator so it holds a value between
0 and 3, then doubles it and uses it as an index into <code>PTR1</code>.
We know <code>PTR1</code> points to <code>XDATA</code>,
which looks like it has some 16-bit addresses. The
values loaded are stored in two more zero-page locations, $04-05.
Let's make these a pointer as well.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-204e-lv.png" alt="t2-204e-lv"/>
</div>
<div class="grid-item-text">
<p>Double-click the operand on line $204E ("<samp>$04</samp>"),
and click <samp>Create Local Variable</samp>. Set the Label
to "<kbd>PTR2</kbd>" and the width to 2. Click <samp>OK</samp>
to create the symbol, then <samp>OK</samp>
to close the operand editor, which should still be set to Default format --
we didn't actually edit the operand, we just used the operand edit
dialog as a convenient way to create a local variable table entry. All
accesses to $04/$05 now use <code>PTR2</code>, and there's a new entry in the local
variable table we created earlier.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2055.png" alt="t2-2055"/>
</div>
<div class="grid-item-text">
<p>The next section of code, at $2055, copies bytes from <code>PTR2</code>
to $0400, stopping when it hits a zero byte.
It looks like this is copying null-terminated strings.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-fmt-xdata.png" alt="t2-fmt-xdata"/>
</div>
<div class="grid-item-text">
<p>This confirms our idea that <code>XDATA</code> holds 16-bit addresses,
so let's format it. Select lines $2063 to $2066, and
<samp>Actions &gt; Edit Operand</samp>.
The editor window should say "<samp>8 bytes selected</samp>" at the top.
Click the <samp>16-bit words, little-endian</samp> radio button,
and then in the <samp>Display As</samp> box, click <samp>Address</samp>.
Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-fmt-xdata-done.png" alt="t2-fmt-xdata-done"/>
</div>
<div class="grid-item-text">
<p>The values at <code>XDATA</code> should now be four
<code>.DD2</code> 16-bit addresses.
If you scroll up, you'll see that the <code>.ZSTR</code> strings
near the top now have labels that match the operands in <code>XDATA</code>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Now that we know what <code>XDATA</code> holds, let's rename it.
Change the label to <kbd>STRADDR</kbd>. The symbol parts in the
operands at $203D and $2041 update automatically.</p>
</div>
</div>
<hr style="width:80%;"/>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-enable-counts.png" alt="t2-enable-counts"/>
</div>
<div class="grid-item-text">
<p>Let's take a quick look at the cycle-count feature. Use
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-show-cycle-counts.png" alt="t2-show-cycle-counts"/>
</div>
<div class="grid-item-text">
<p>Every line with an instruction now has a cycle count on it. The cycle
counts are adjusted for everything SourceGen can figure out. For example,
the <code>BEQ</code> on line $205A shows "2+" cycles, meaning that
it takes at least two cycles but might take more. That's because
conditional branches take an
extra cycle if the branch is taken. The <code>BNE</code> on line
$2061 shows 3 cycles, because we know that the branch is always
taken and doesn't cross a page boundary.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>(If you want to see why it's always taken,
look at the value of the 'Z' flag in the "flags" column, which indicates
the state of the flags before the instruction on that line is executed.
Lower-case 'z' means the zero-flag is clear (0), upper-case 'Z' means it's
set (1). The analyzer determined that the flag was clear for instructions
following the <code>BEQ</code> because we're on the branch-not-taken path.
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>If you add an end-of-line comment, it appears after the cycle count.
(Try it.)</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Local Variables - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-local-variables -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables" class="active"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Local Variables</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-203d-start.png" alt="t2-203d-start"/>
</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
pointer to $2063, which is a data area inside the file. So let's make it
official.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-203d-edit1.png" alt="t2-203d-edit1"/>
</div>
<div class="grid-item-text">
<p>Select the line at address $2063, and use
<samp>Actions &gt; Edit Label</samp> to
give it the label "<kbd>XDATA?</kbd>". The question mark on the end is there to
remind us that we're not entirely sure what this is. Now edit the
operand on line $203D, and set it to the symbol "<kbd>XDATA</kbd>",
with the part "low". The question mark isn't really part of the label,
so you don't need to type it here.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-203d-after-edit2.png" alt="t2-203d-after-edit2"/>
</div>
<div class="grid-item-text">
<p>Edit the operand on line $2041,
and set it to "<kbd>XDATA</kbd>" with the part "high". (The symbol text box
gets focus immediately, so you can start typing the symbol name as soon
as the dialog opens; you don't need to click around first.) If all
went well, the operands should now read <code>LDA #&lt;XDATA?</code>
and <code>LDA #&gt;XDATA?</code>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-create-ptr-entry.png" alt="t2-create-ptr-entry"/>
</div>
<div class="grid-item-text">
<p>Let's give the pointer a name. Select line $203D, and use
<samp>Actions &gt; Create Local Variable Table</samp>
to create an empty table. Click <samp>New Symbol</samp> on the right side.
Leave the Address button selected. Set the Label field to "<kbd>PTR1</kbd>",
the Value field to "$02", and the width to "2" (it's a 2-byte pointer).
Click "OK" to create the entry, and then
"OK" to update the table.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-after-ptr-entry.png" alt="t2-after-ptr-entry"/>
</div>
<div class="grid-item-text">
<p>There's now a <code>.VAR</code> statement
(similar to a <code>.EQU</code>) above line $203D,
and the stores to $02/$03 have changed to
"<samp>PTR1</samp>" and "<samp>PTR1+1</samp>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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>.
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2048.png" alt="t2-2048"/>
</div>
<div class="grid-item-text">
<p>The next bit of code masks the accumulator so it holds a value between
0 and 3, then doubles it and uses it as an index into <code>PTR1</code>.
We know <code>PTR1</code> points to <code>XDATA</code>,
which looks like it has some 16-bit addresses. The
values loaded are stored in two more zero-page locations, $04-05.
Let's make these a pointer as well.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-204e-lv.png" alt="t2-204e-lv"/>
</div>
<div class="grid-item-text">
<p>Double-click the operand on line $204E ("<samp>$04</samp>"),
and click <samp>Create Local Variable</samp>. Set the Label
to "<kbd>PTR2</kbd>" and the width to 2. Click <samp>OK</samp>
to create the symbol, then <samp>OK</samp>
to close the operand editor, which should still be set to Default format --
we didn't actually edit the operand, we just used the operand edit
dialog as a convenient way to create a local variable table entry. All
accesses to $04/$05 now use <code>PTR2</code>, and there's a new entry in the local
variable table we created earlier.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2055.png" alt="t2-2055"/>
</div>
<div class="grid-item-text">
<p>The next section of code, at $2055, copies bytes from <code>PTR2</code>
to $0400, stopping when it hits a zero byte.
It looks like this is copying null-terminated strings.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-fmt-xdata.png" alt="t2-fmt-xdata"/>
</div>
<div class="grid-item-text">
<p>This confirms our idea that <code>XDATA</code> holds 16-bit addresses,
so let's format it. Select lines $2063 to $2066, and
<samp>Actions &gt; Edit Operand</samp>.
The editor window should say "<samp>8 bytes selected</samp>" at the top.
Click the <samp>16-bit words, little-endian</samp> radio button,
and then in the <samp>Display As</samp> box, click <samp>Address</samp>.
Click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-fmt-xdata-done.png" alt="t2-fmt-xdata-done"/>
</div>
<div class="grid-item-text">
<p>The values at <code>XDATA</code> should now be four
<code>.DD2</code> 16-bit addresses.
If you scroll up, you'll see that the <code>.ZSTR</code> strings
near the top now have labels that match the operands in <code>XDATA</code>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Now that we know what <code>XDATA</code> holds, let's rename it.
Change the label to <kbd>STRADDR</kbd>. The symbol parts in the
operands at $203D and $2041 update automatically.</p>
</div>
</div>
<hr style="width:80%;"/>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-enable-counts.png" alt="t2-enable-counts"/>
</div>
<div class="grid-item-text">
<p>Let's take a quick look at the cycle-count feature. Use
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-show-cycle-counts.png" alt="t2-show-cycle-counts"/>
</div>
<div class="grid-item-text">
<p>Every line with an instruction now has a cycle count on it. The cycle
counts are adjusted for everything SourceGen can figure out. For example,
the <code>BEQ</code> on line $205A shows "2+" cycles, meaning that
it takes at least two cycles but might take more. That's because
conditional branches take an
extra cycle if the branch is taken. The <code>BNE</code> on line
$2061 shows 3 cycles, because we know that the branch is always
taken and doesn't cross a page boundary.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>(If you want to see why it's always taken,
look at the value of the 'Z' flag in the "flags" column, which indicates
the state of the flags before the instruction on that line is executed.
Lower-case 'z' means the zero-flag is clear (0), upper-case 'Z' means it's
set (1). The analyzer determined that the flag was clear for instructions
following the <code>BEQ</code> because we're on the branch-not-taken path.
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>If you add an end-of-line comment, it appears after the cycle count.
(Try it.)</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="string-formatting.html" class="btn-previous">&laquo; Previous</a>
<a href="inline-data.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

450
docs/sgtutorial/moving-around.html
View File

@ -1,201 +1,249 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Moving Around - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-starting-project -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-moving-around").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Moving Around</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-fullscreen.png" alt="t1-fullscreen"/>
</div>
<div class="grid-item-text">
<p>The display is divided into five main areas:</p>
<ol>
<li>Code listing. Disassembled code and data is shown here.</li>
<li>References. Shows a list of the places in the file that
reference the currently selected line.</li>
<li>Notes. A list of notes in the project. Useful as bookmarks.</li>
<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>
</ol>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The center code list window is divided into rows, one per line of disassembled
code or data. This is a standard "list view" control, so you can select a
row by left-clicking anywhere in it. Use <kbd class="key">Ctrl</kbd>+click
to toggle the selection on individual lines, and
<kbd class="key">Shift</kbd>+click to select a range of lines. You can move
the selection around with the up/down arrow keys and
<kbd class="key">PgUp</kbd>/<kbd class="key">PgDn</kbd>. Scroll the window
with the mouse wheel, or by dragging the scroll bar thumb.</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</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-all-columns.png" alt="t1-all-columns"/>
</div>
<div class="grid-item-text">
<p>The columns on the right side of the window 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. (Many of the screen shots captured here will omit the
"Attr" column for the sake of compactness.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-click-1002.png" alt="t1-click-1002"/>
</div>
<div class="grid-item-text">
<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 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>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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-click-1017.png" alt="t1-click-1017"/>
</div>
<div class="grid-item-text">
<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 line L1017 selected, 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-symbol-filters.png" alt="t1-symbol-filters"/>
</div>
<div class="grid-item-text">
<p>At the top of the Symbols window on the right side of the screen is a
row of buttons. Make sure "Auto" and "Addr" are selected. You should see
three labels in the window (L1002, L1014, L1017). Double-click on "L1014"
in the Symbols list. The selection jumps to the appropriate line.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Select Navigate &gt; Find. Type "hello", and hit Enter. The selection will
move to address $100E, which is a string that says "hello!". You can use
Navigate &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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-goto-box.png" alt="t1-goto-box"/>
</div>
<div class="grid-item-text">
<p>Select Navigate &gt; Go To. You can enter a label, address, or file offset.
Enter "100b" to set the selection to the line at address $100B.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-toolbar.png" alt="t1-toolbar"/>
</div>
<div class="grid-item-text">
<p>Near the top-left of the SourceGen window is a set of toolbar icons.
Click the curly left-pointing arrow, and watch the selection move. Click
it again. Then click the curly 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 the side windows, the locations are added to a
navigation history. The arrows let you move forward and backward
through it.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Moving Around - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-starting-project -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Moving Around</h2>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-fullscreen.png" alt="t1-fullscreen"/>
</div>
<div class="grid-item-text">
<p>The display is divided into five main areas:</p>
<ol>
<li>Code listing. Disassembled code and data is shown here.</li>
<li>References. Shows a list of the places in the file that
reference the currently selected line.</li>
<li>Notes. A list of notes in the project. Useful as bookmarks.</li>
<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>
</ol>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The center code list window is divided into rows, one per line of disassembled
code or data. This is a standard "list view" control, so you can select a
row by left-clicking anywhere in it. Use <kbd class="key">Ctrl</kbd>+click
to toggle the selection on individual lines, and
<kbd class="key">Shift</kbd>+click to select a range of lines. You can move
the selection around with the up/down arrow keys and
<kbd class="key">PgUp</kbd>/<kbd class="key">PgDn</kbd>. Scroll the window
with the mouse wheel, or by dragging the scroll bar thumb.</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</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-all-columns.png" alt="t1-all-columns"/>
</div>
<div class="grid-item-text">
<p>The columns on the right side of the window 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. (Many of the screen shots captured here will omit the
"Attr" column for the sake of compactness.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-click-1002.png" alt="t1-click-1002"/>
</div>
<div class="grid-item-text">
<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 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>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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-click-1017.png" alt="t1-click-1017"/>
</div>
<div class="grid-item-text">
<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 line L1017 selected, 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-symbol-filters.png" alt="t1-symbol-filters"/>
</div>
<div class="grid-item-text">
<p>At the top of the Symbols window on the right side of the screen is a
row of buttons. Make sure "Auto" and "Addr" are selected. You should see
three labels in the window (L1002, L1014, L1017). Double-click on "L1014"
in the Symbols list. The selection jumps to the appropriate line.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>Select Navigate &gt; Find. Type "hello", and hit Enter. The selection will
move to address $100E, which is a string that says "hello!". You can use
Navigate &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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-goto-box.png" alt="t1-goto-box"/>
</div>
<div class="grid-item-text">
<p>Select Navigate &gt; Go To. You can enter a label, address, or file offset.
Enter "100b" to set the selection to the line at address $100B.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-toolbar.png" alt="t1-toolbar"/>
</div>
<div class="grid-item-text">
<p>Near the top-left of the SourceGen window is a set of toolbar icons.
Click the curly left-pointing arrow, and watch the selection move. Click
it again. Then click the curly 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 the side windows, the locations are added to a
navigation history. The arrows let you move forward and backward
through it.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="using-sourcegen.html" class="btn-previous">&laquo; Previous</a>
<a href="simple-edits.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

442
docs/sgtutorial/odds-ends.html
View File

@ -1,197 +1,245 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Odds &amp; Ends - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-odds-ends -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-odds-ends").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Odds &amp; Ends</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>The rest of the code isn't really intended to do anything useful. It
just exists to illustrate some odd situations.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2078.png" alt="t2-2078"/>
</div>
<div class="grid-item-text">
<p>Look at the code starting at $2078. It ends with a <code>BRK</code>
at $2081, which as noted earlier is a bad sign. If you look two lines
above the <code>BRK</code>, you'll see that it's loading the accumulator
with zero, then doing a <code>BNE</code>, which should never be
taken (note the cycle count for the <code>BNE</code> is 2).
The trick is in the two lines before that, which use self-modifying code to
change the <code>LDA</code> immediate operand from $00 to $ff.
The <code>BNE</code> is actually a branch-always.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-override-status.png" alt="t2-override-status.png"/>
</div>
<div class="grid-item-text">
<p>We can fix this by correcting the status flags. Select line $207F,
and then <samp>Actions &gt; Override Status Flags</samp>. This lets us specify what
the flags should be before the instruction is executed. For each flag,
we can override the default behavior and specify that the flag is
clear (0), set (1), or indeterminate (could be 0 or 1). In this case,
we know that the self-modified code will be loading a non-zero value, so
in the "<samp>Z</samp>" column click on the button in the "<samp>Zero</samp>" row.
Click "<samp>OK</samp>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2078-done.png" alt="t2-2078-done"/>
</div>
<div class="grid-item-text">
<p>The <code>BNE</code> is now an always-taken branch, and the code
list rearranges itself appropriately (and the cycle count is now 3).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2086.png" alt="t2-2086"/>
</div>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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
<samp>Seek nearby targets</samp>, and click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<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
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<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>
<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
on.</p>
</div>
</div>
<hr style="width:80%;"/>
<div class="grid-container">
<div class="grid-item-text">
<p>This is the end of the basic tutorial (congratulations!).
The next sections explore some advanced topics.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Odds &amp; Ends - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-odds-ends -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends" class="active"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Odds &amp; Ends</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>The rest of the code isn't really intended to do anything useful. It
just exists to illustrate some odd situations.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2078.png" alt="t2-2078"/>
</div>
<div class="grid-item-text">
<p>Look at the code starting at $2078. It ends with a <code>BRK</code>
at $2081, which as noted earlier is a bad sign. If you look two lines
above the <code>BRK</code>, you'll see that it's loading the accumulator
with zero, then doing a <code>BNE</code>, which should never be
taken (note the cycle count for the <code>BNE</code> is 2).
The trick is in the two lines before that, which use self-modifying code to
change the <code>LDA</code> immediate operand from $00 to $ff.
The <code>BNE</code> is actually a branch-always.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-override-status.png" alt="t2-override-status.png"/>
</div>
<div class="grid-item-text">
<p>We can fix this by correcting the status flags. Select line $207F,
and then <samp>Actions &gt; Override Status Flags</samp>. This lets us specify what
the flags should be before the instruction is executed. For each flag,
we can override the default behavior and specify that the flag is
clear (0), set (1), or indeterminate (could be 0 or 1). In this case,
we know that the self-modified code will be loading a non-zero value, so
in the "<samp>Z</samp>" column click on the button in the "<samp>Zero</samp>" row.
Click "<samp>OK</samp>".</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2078-done.png" alt="t2-2078-done"/>
</div>
<div class="grid-item-text">
<p>The <code>BNE</code> is now an always-taken branch, and the code
list rearranges itself appropriately (and the cycle count is now 3).</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-2086.png" alt="t2-2086"/>
</div>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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
<samp>Seek nearby targets</samp>, and click <samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<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
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<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>
<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
on.</p>
</div>
</div>
<hr style="width:80%;"/>
<div class="grid-container">
<div class="grid-item-text">
<p>This is the end of the basic tutorial (congratulations!).
The next sections explore some advanced topics.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="inline-data.html" class="btn-previous">&laquo; Previous</a>
<a href="advanced-topics.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

52
docs/sgtutorial/sidenav-incl.html
View File

@ -1,26 +1,26 @@
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>

456
docs/sgtutorial/simple-edits.html
View File

@ -1,204 +1,252 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Simple Edits - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-simple-edits -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-simple-edits").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Simple Edits</h2>
<div class="grid-container">
<div class="grid-item-text">
<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 <samp>Actions &gt; Edit Long Comment</samp> from the menu bar.</li>
<li>Right click, and select <samp>Edit Long Comment</samp> 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-long-comment.png" alt="t1-edit-long-comment"/>
</div>
<div class="grid-item-text">
<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 <samp>OK</samp>.
(Or hit <kbd class="key">Ctrl+Enter</kbd>.)</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>
</div>
</div>
<div class="grid-container">
<!--<div class="grid-item-image">
<img src="images/t1-multi-disab.png" alt="t1-multi-disab"/>
</div>-->
<div class="grid-item-text">
<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 edit features
are only enabled when a single instance of a relevant item is selected, so
for example <samp>Edit Long Comment</samp> won't be enabled if you have an
instruction selected.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-note.png" alt="t1-edit-note"/>
</div>
<div class="grid-item-text">
<p>Let's add a note. Click on $100E (the line with "hello!"), then
select <samp>Actions &gt; Edit Note</samp>. Type a few words, pick a color,
and click <samp>OK</samp> (or hit <kbd class="key">Ctrl+Enter</kbd>).
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-set-addr-1017.png" alt="t1-set-addr-1017"/>
</div>
<div class="grid-item-text">
<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
<samp>Actions &gt; Set Address</samp>. (Or double-click on
"<code>1017</code>" in the <samp>Addr</samp> column.)
In the <samp>Set Address</samp> dialog, type "<kbd>2000</kbd>", and hit Enter.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-addr-chg-1017.png" alt="t1-addr-chg-1017"/>
</div>
<div class="grid-item-text">
<p>Note the way the code list has changed. When you changed the address,
the <code>JMP $2000</code> at address $1014 found a home inside
the bounds of the file, so
the code tracer was able to find the instructions there.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>From the menu, select <samp>Edit &gt; Undo</samp>. Notice how
everything reverts to the way it was. Now, select
<samp>Edit &gt; Redo</samp> to restore the changes. 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>As you make alterations to the addresses, notice that, while the
<samp>Address</samp> column changes, the <samp>Offset</samp> column does 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-simple-instr-edit.png" alt="t1-simple-instr-edit"/>
</div>
<div class="grid-item-text">
<p>Select the line with address $2003 ("CMP #$04"), then
<samp>Actions &gt; Edit Operand</samp>. This allows you to pick how you want the
operand to look. It's currently set to "Default", which for an 8-bit
immediate argument means it's shown as a hexadecimal value. Click
"Binary", then "OK". It now appears as a binary value.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-2003-done.png" alt="t1-2003-done"/>
</div>
<div class="grid-item-text">
<p>On that same line, select <samp>Actions &gt; Edit Comment</samp>. Type a short
comment, and hit <kbd class="key">Enter</kbd>. Your comment appears
in the "comment" column.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Simple Edits - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-simple-edits -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits" class="active"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Simple Edits</h2>
<div class="grid-container">
<div class="grid-item-text">
<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 <samp>Actions &gt; Edit Long Comment</samp> from the menu bar.</li>
<li>Right click, and select <samp>Edit Long Comment</samp> 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-long-comment.png" alt="t1-edit-long-comment"/>
</div>
<div class="grid-item-text">
<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 <samp>OK</samp>.
(Or hit <kbd class="key">Ctrl+Enter</kbd>.)</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>
</div>
</div>
<div class="grid-container">
<!--<div class="grid-item-image">
<img src="images/t1-multi-disab.png" alt="t1-multi-disab"/>
</div>-->
<div class="grid-item-text">
<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 edit features
are only enabled when a single instance of a relevant item is selected, so
for example <samp>Edit Long Comment</samp> won't be enabled if you have an
instruction selected.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-edit-note.png" alt="t1-edit-note"/>
</div>
<div class="grid-item-text">
<p>Let's add a note. Click on $100E (the line with "hello!"), then
select <samp>Actions &gt; Edit Note</samp>. Type a few words, pick a color,
and click <samp>OK</samp> (or hit <kbd class="key">Ctrl+Enter</kbd>).
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-set-addr-1017.png" alt="t1-set-addr-1017"/>
</div>
<div class="grid-item-text">
<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
<samp>Actions &gt; Set Address</samp>. (Or double-click on
"<code>1017</code>" in the <samp>Addr</samp> column.)
In the <samp>Set Address</samp> dialog, type "<kbd>2000</kbd>", and hit Enter.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-addr-chg-1017.png" alt="t1-addr-chg-1017"/>
</div>
<div class="grid-item-text">
<p>Note the way the code list has changed. When you changed the address,
the <code>JMP $2000</code> at address $1014 found a home inside
the bounds of the file, so
the code tracer was able to find the instructions there.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>From the menu, select <samp>Edit &gt; Undo</samp>. Notice how
everything reverts to the way it was. Now, select
<samp>Edit &gt; Redo</samp> to restore the changes. 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>As you make alterations to the addresses, notice that, while the
<samp>Address</samp> column changes, the <samp>Offset</samp> column does 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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-simple-instr-edit.png" alt="t1-simple-instr-edit"/>
</div>
<div class="grid-item-text">
<p>Select the line with address $2003 ("CMP #$04"), then
<samp>Actions &gt; Edit Operand</samp>. This allows you to pick how you want the
operand to look. It's currently set to "Default", which for an 8-bit
immediate argument means it's shown as a hexadecimal value. Click
"Binary", then "OK". It now appears as a binary value.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-2003-done.png" alt="t1-2003-done"/>
</div>
<div class="grid-item-text">
<p>On that same line, select <samp>Actions &gt; Edit Comment</samp>. Type a short
comment, and hit <kbd class="key">Enter</kbd>. Your comment appears
in the "comment" column.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="moving-around.html" class="btn-previous">&laquo; Previous</a>
<a href="labels-symbols.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

290
docs/sgtutorial/string-formatting.html
View File

@ -1,121 +1,169 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>String Formatting - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-string-formatting -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-string-formatting").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>String Formatting</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Programs can encode strings, such as human-readable text or
filenames, in a variety of ways. Assemblers generally support one
or more of these. SourceGen allows you to choose from a number of
different formats, and automatically generates appropriate assembler
directives.</p>
<p>The most popular formats are null-terminated (string data followed
by $00), length-delimited (first byte or two holds the string length),
and dextral character inverted (the high bit on the last byte is
flipped). Sometimes strings are stored in reverse, so the output
routine can decrement a register to zero.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-str-null-term-start.png" alt="t2-str-null-term-start"/>
</div>
<div class="grid-item-text">
<p>Looking at the Tutorial2 code, there are four strings starting
at address $2004, each of which is followed by $00. These look like
null-terminated strings, so let's make it official.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-str-null-term-bad.png" alt="t2-str-null-term-bad"/>
</div>
<div class="grid-item-text">
<p>First, let's do it wrong. Click on the line with
address $2004 to select it. Hold the shift key down, then double-click
on the operand field of the line with address $2031 (i.e. double-click on
the words "<samp>last string</samp>").</p>
<p>The Edit Data Operand dialog opens, but the null-terminated strings
option is not available. This is because we didn't include the null byte
on the last string. To be recognized as one of the "special" string types,
every selected string must match the expected pattern.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-str-null-term-good.png" alt="t2-str-null-term-good"/>
</div>
<div class="grid-item-text">
<p>Cancel out of the dialog. Hold the shift key down, and double-click
on the operand on line $203C (<code>$00</code>).
With all 57 bytes selected,
you should now see "<samp>Null-terminated strings (4)</samp>" as an available
option (make sure the Character Encoding pop-up is set to
"<samp>Low or High ASCII</samp>"). Click on that, then click <samp>OK</samp>.
The strings are now shown as <samp>.ZSTR</samp> operands.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>String Formatting - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-string-formatting -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting" class="active"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>String Formatting</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Programs can encode strings, such as human-readable text or
filenames, in a variety of ways. Assemblers generally support one
or more of these. SourceGen allows you to choose from a number of
different formats, and automatically generates appropriate assembler
directives.</p>
<p>The most popular formats are null-terminated (string data followed
by $00), length-delimited (first byte or two holds the string length),
and dextral character inverted (the high bit on the last byte is
flipped). Sometimes strings are stored in reverse, so the output
routine can decrement a register to zero.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-str-null-term-start.png" alt="t2-str-null-term-start"/>
</div>
<div class="grid-item-text">
<p>Looking at the Tutorial2 code, there are four strings starting
at address $2004, each of which is followed by $00. These look like
null-terminated strings, so let's make it official.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-str-null-term-bad.png" alt="t2-str-null-term-bad"/>
</div>
<div class="grid-item-text">
<p>First, let's do it wrong. Click on the line with
address $2004 to select it. Hold the shift key down, then double-click
on the operand field of the line with address $2031 (i.e. double-click on
the words "<samp>last string</samp>").</p>
<p>The Edit Data Operand dialog opens, but the null-terminated strings
option is not available. This is because we didn't include the null byte
on the last string. To be recognized as one of the "special" string types,
every selected string must match the expected pattern.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t2-str-null-term-good.png" alt="t2-str-null-term-good"/>
</div>
<div class="grid-item-text">
<p>Cancel out of the dialog. Hold the shift key down, and double-click
on the operand on line $203C (<code>$00</code>).
With all 57 bytes selected,
you should now see "<samp>Null-terminated strings (4)</samp>" as an available
option (make sure the Character Encoding pop-up is set to
"<samp>Low or High ASCII</samp>"). Click on that, then click <samp>OK</samp>.
The strings are now shown as <samp>.ZSTR</samp> operands.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="digging-deeper.html" class="btn-previous">&laquo; Previous</a>
<a href="local-variables.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

396
docs/sgtutorial/using-sourcegen.html
View File

@ -1,174 +1,222 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Using SourceGen - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-using-sourcegen -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-using-sourcegen").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Using SourceGen</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>This first section covers the basics of working with SourceGen: how to
move around, make edits, generate code, and so on.
SourceGen has some unusual features, so it's worth reading through this
even if you've used other disassemblers.</p>
<p>You can't do anything useful until you open an existing project or
create a new one, so we'll start there.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>A SourceGen project is always associated with a data file, which
holds part or all of the program being disassembled.
For simplicity, the project is given the same name as the data file, with
<code>.dis65</code> on the end.
No part of the data file is included in the project file, so you need
to keep both files in the same place.
If the program you're disassembling was split into more than one data
file, you'll need a separate project file for each.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-fresh-install.png" alt="t1-fresh-install"/>
</div>
<div class="grid-item-text">
<p>To start a new project, launch SourceGen, and click on the
"Start New Project" button on
the initial screen, or use <samp>File &gt; New</samp>. This opens the "New Project"
window, which lets you specify the target system and data file.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-new-project.png" alt="t1-new-project"/>
</div>
<div class="grid-item-text">
<p>Choosing a target system, such as Apple //e or Commodore 64, will
create a project configured with the appropriate CPU and options.
If nothing in the list matches the file you want to work on,
there are "generic" entries for each
of the primary CPU varieties (6502, 65C02, W65C02, and 65816). If
you're unsure, just take your best guess. It's easy to change things after the
project has been started.</p>
<p>The area on the right side of the window has a list of the files, scripts,
and optional features that will be enabled for the
selected system. The various items here will be explained in more
detail later on.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-new-tutorial1.png" alt="t1-new-tutorial1"/>
</div>
<div class="grid-item-text">
<p>For this tutorial, we're going to use "<samp>Generic 6502</samp>",
near the bottom of the list.</p>
<p>The other thing we need to do here is select the data file to be
disassembled. Click <samp>Select File</samp>, navigate to the <samp>Examples</samp>
directory in the SourceGen installation directory, open <samp>Tutorial</samp>,
and select <samp>Tutorial1</samp>.
<p>Click <samp>OK</samp> to create the project.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The first thing you should do after creating a new project is save it.
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>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-settings.png" alt="t1-settings"/>
</div>
<div class="grid-item-text">
<p>The disassembly display can be tailored to your personal
preferences. Use <samp>Edit &gt; Settings</samp> to open the
settings editor. You can change fonts, upper/lower case, text
delimiters, line wrapping, pseudo-op names, and more. There
are "quick set" buttons on some screens that allow you to make the
output resemble various popular assemblers.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>All app settings are local to your system, and do not affect
the project in any way. If somebody else opens the same project,
they may see entirely different pseudo-ops and upper-case choices,
based on their own personal preferences.
(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>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Using SourceGen - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-using-sourcegen -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen" class="active"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Using SourceGen</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>This first section covers the basics of working with SourceGen: how to
move around, make edits, generate code, and so on.
SourceGen has some unusual features, so it's worth reading through this
even if you've used other disassemblers.</p>
<p>You can't do anything useful until you open an existing project or
create a new one, so we'll start there.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>A SourceGen project is always associated with a data file, which
holds part or all of the program being disassembled.
For simplicity, the project is given the same name as the data file, with
<code>.dis65</code> on the end.
No part of the data file is included in the project file, so you need
to keep both files in the same place.
If the program you're disassembling was split into more than one data
file, you'll need a separate project file for each.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-fresh-install.png" alt="t1-fresh-install"/>
</div>
<div class="grid-item-text">
<p>To start a new project, launch SourceGen, and click on the
"Start New Project" button on
the initial screen, or use <samp>File &gt; New</samp>. This opens the "New Project"
window, which lets you specify the target system and data file.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-new-project.png" alt="t1-new-project"/>
</div>
<div class="grid-item-text">
<p>Choosing a target system, such as Apple //e or Commodore 64, will
create a project configured with the appropriate CPU and options.
If nothing in the list matches the file you want to work on,
there are "generic" entries for each
of the primary CPU varieties (6502, 65C02, W65C02, and 65816). If
you're unsure, just take your best guess. It's easy to change things after the
project has been started.</p>
<p>The area on the right side of the window has a list of the files, scripts,
and optional features that will be enabled for the
selected system. The various items here will be explained in more
detail later on.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-new-tutorial1.png" alt="t1-new-tutorial1"/>
</div>
<div class="grid-item-text">
<p>For this tutorial, we're going to use "<samp>Generic 6502</samp>",
near the bottom of the list.</p>
<p>The other thing we need to do here is select the data file to be
disassembled. Click <samp>Select File</samp>, navigate to the <samp>Examples</samp>
directory in the SourceGen installation directory, open <samp>Tutorial</samp>,
and select <samp>Tutorial1</samp>.
<p>Click <samp>OK</samp> to create the project.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>The first thing you should do after creating a new project is save it.
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>
<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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t1-settings.png" alt="t1-settings"/>
</div>
<div class="grid-item-text">
<p>The disassembly display can be tailored to your personal
preferences. Use <samp>Edit &gt; Settings</samp> to open the
settings editor. You can change fonts, upper/lower case, text
delimiters, line wrapping, pseudo-op names, and more. There
are "quick set" buttons on some screens that allow you to make the
output resemble various popular assemblers.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>All app settings are local to your system, and do not affect
the project in any way. If somebody else opens the same project,
they may see entirely different pseudo-ops and upper-case choices,
based on their own personal preferences.
(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>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="about-disasm.html" class="btn-previous">&laquo; Previous</a>
<a href="moving-around.html" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>

733
docs/sgtutorial/visualizations.html
View File

@ -1,343 +1,390 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Visualizations - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<script>$("#masthead").load("/masthead-incl.html");</script>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<script>
// Load global topnav content, and mark current page active.
$("#topnav").load("/topnav-incl.html", function() {
$("#topnav-sgtutorial").addClass("active");
});
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-visualizations -->
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-visualizations").addClass("active");
});
</script>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Visualizations</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Many programs contain a significant amount of graphical data. This is
especially true for games, where the space used for bitmaps is often
larger than the space required for the code. When disassembling a program
it can be very helpful to be able to see the contents of the data
regions in graphical form.</p>
<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
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
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-add-vis.png" alt="t5-add-vis"/>
</div>
<div class="grid-item-text">
<p>The first thing we need to do is load an extension script that can
decode this format. The SourceGen "RuntimeData" directory has a few,
but for this tutorial we're using a custom one. Select
<samp>Edit &gt; Project Properties</samp>, select the
<samp>Extension Scripts</samp> tab, and click
<samp>Add Scripts from Project</samp>.
Double-click on "<samp>VisTutorial5.cs</samp>",
then click </samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-new-vis.png" alt="t5-new-vis"/>
</div>
<div class="grid-item-text">
<p>The addresses of the three bitmaps are helpfully identified by the
load instructions at the top of the file. Select the line at
address $100A, then
<samp>Actions &gt; Create/Edit Visualization Set</samp>. In
the window that opens, click <samp>New Visualization</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>We're going to ignore most of what's going on and just focus on the
list of parameters at the bottom. The file offset indicates where in
the file the bitmap starts; note this is an offset, not an address
(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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-set-height-8.png" alt="t5-set-height-8"/>
</div>
<div class="grid-item-text">
<p>We happen to know (by playing the game and/or reading the fictitious
drawing code) that the image is 8x8, so change the value in the
<samp>Height</samp>
field to 8. As soon as you do, the preview window shows a big blue 'X'.
(The 'X' is 7x7; the last row/column of pixels are transparent so adjacent
images don't bump into each other.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-set-height-80.png" alt="t5-set-height-80"/>
</div>
<div class="grid-item-text">
<p>Let's try doing it wrong. Add a '0' in the <samp>Height</samp>
field to make the
height 80. You can see some additional bitmap data.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-set-height-800.png" alt="t5-set-height-800"/>
</div>
<div class="grid-item-text">
<p>Add another 0 to make it 800. Now you get
a big red X, and the <samp>Height</samp> parameter is shown in red.
That's because the maximum value for the height is 512, as shown
by "<samp>[1,512]</samp>" on the right.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-addvis1.png" alt="t5-addvis1"/>
</div>
<div class="grid-item-text">
<p>Change it back to 8, and hit <samp>OK</samp>.
Hit <samp>OK</samp> in the <samp>Edit Visualization Set</samp>
window as well. You should now see the blue 'X' in the code listing
above line $100A.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-addvis2.png" alt="t5-addvis2"/>
</div>
<div class="grid-item-text">
<p>Repeat the process at line $1012: select the line, create a visualization
set, create a new visualization. The height will default to 8 because
that's what you used last time, so you shouldn't have to
make any changes to the initial values.
Click <samp>OK</samp> in both dialogs to close them.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-101a-mess.png" alt="t5-101a-mess"/>
</div>
<div class="grid-item-text">
<p>Repeat the process at line $101A, but this time the image is 40x40
rather than 8x8. Set the width to 5, and the height to 40. This makes
a mess.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-101a-good.png" alt="t5-101a-good"/>
</div>
<div class="grid-item-text">
<p>In this case, the bitmap data is 5 bytes wide, but the data is stored
as 8 bytes per row. This is known as the "stride" or "pitch" of the row.
To tell the visualizer to skip the last 3 bytes on each row, set the
<samp>Row stride (bytes)</samp> field to 8.
Now we have a proper Tic-Tac-Toe grid.
Note that it fills the preview window just as the 'X' and 'O' did, even
though it's 5x as large. The preview window scales everything up. Hit
<samp>OK</samp> twice to create the visualization.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-fmt-dense.png" alt="t5-fmt-dense"/>
</div>
<div class="grid-item-text">
<p>Let's format the bitmap data. Select line $101A, then shift-click the
last line in the file ($1159). <samp>Actions &gt; Edit Operand</samp>. Select
<samp>Densely-packed bytes</samp>, and click <samp>OK</samp>.
This is perhaps a little too
dense. Open the operand editor again, but this time select the
densely-packed bytes sub-option <samp>...with a limit</samp>, and set the limit
to 8 bytes per line. Instead of one very dense statement spread across
a few lines, you get one line of source code per row of bitmap.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>To change whether or not commas appear between bytes in the operand,
open <samp>Edit &gt; Settings</samp>, select the
<samp>Display Format</samp> tab, and check
<samp>Use comma-separated format for bulk data</samp>.
This trades off compactness for ease of reading.</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Bitmap Animations</h4>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-bitmap-anim-editor.png" alt="t5-bitmap-anim-editor"/>
</div>
<div class="grid-item-text">
<p>Some bitmaps represent individual frames in an animated sequence.
You can convert those as well. Double-click on the blue 'X' to open
the visualization set editor, then click "New Bitmap Animation". This
opens the Bitmap Animation Editor.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-xo-anim.png" alt="t5-xo-anim"/>
</div>
<div class="grid-item-text">
<p>Let's try it with our Tic-Tac-Toe board pieces. From the list
on the left, select the blue 'X' and click <samp>Add</samp>, then
click the 'O' and click <samp>Add</samp>. Below the list, set the
frame delay to 500 msec. Near the bottom, click
<samp>Start / Stop</samp>. This causes the animation to play in a loop.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>You can use the controls to add and remove items, change their order, and change
the animation speed. You can add the grid bitmap to the animation set, but the
preview scales the bitmaps up to full size, so it may not look the way
you expect.</p>
<p>Hit <samp>OK</samp> to save the animation, then
<samp>OK</samp> to update the visualization set.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-list-xanim.png" alt="t5-list-xanim"/>
</div>
<div class="grid-item-text">
<p>The code list now shows two entries in the line: the first is the 'X'
bitmap, the second is the animation, which is shown as the initial frame
with a blue triangle superimposed. (If you go back into the editor and
reverse the order of the frames, the list will show the 'O' instead.)
You can have as many bitmaps and animations on a line as you want.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>If you have a lot of bitmaps it can be helpful to give them meaningful
names, so that they're easy to identify and sort together in the list.
The <samp>Tag</samp> field at the top of the editor windows lets you
give things names. Tags must be unique.</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Other Notes</h4>
<div class="grid-container">
<div class="grid-item-text">
<p>The visualization editor is intended to be very dynamic, showing the
results of parameter changes immediately. This can be helpful if you're
not exactly sure what the size or format of a bitmap is. Just keep
tweaking values until it looks right.</p>
<p>Visualization generators are defined by extension scripts. If you're
disassembling a program with a totally custom way of storing graphics,
you can write a totally custom visualizer and distribute it with the
project. Because the file offset is a parameter, you're not limited to
placing visualizations at the start of the graphic data -- you can put
them on any code or data line.</p>
<p>Visualizations have no effect on assembly source code generation,
but they do appear in code exported to HTML. Bitmaps are converted to GIF
images, and animations become animated GIFs.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-wireframe-sample.png" alt="t5-wireframe-sample"/>
</div>
<div class="grid-item-text">
<p>You can also create animated visualizations of wireframe objects
(vector graphics, 3D shapes), but that's not covered in this tutorial.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="#" class="btn-previous">&laquo; Previous</a>
<a href="#" class="btn-next">Next &raquo;</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<script>$("#footer").load("/footer-incl.html");</script>
<!-- END: /footer-incl.html -->
</div>
</body>
</html>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
<link rel="stylesheet" href="/main.css"/>
<title>Visualizations - SourceGen Tutorial</title>
</head>
<body>
<div id="masthead">
<!-- START: /masthead-incl.html -->
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
<div class="masthead-title">
6502bench
</div>
<!-- END: /masthead-incl.html -->
</div>
<div id="topnav">
<!-- START: /topnav-incl.html active:#topnav-sgtutorial -->
<!-- top navigation bar contents -->
<nav>
<a id="topnav-home" href="/">HOME</a>
<a id="topnav-sgtutorial" class="active" href="/sgtutorial">SourceGen Tutorial</a>
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
<i class="fa fa-bars"></i>
</a>
</nav>
<script>
// If page has no sidenav, don't show the sidenav toggle button.
if (document.getElementById("sidenav") == undefined) {
$("#topnav-menuicon").hide();
}
// Sidenav toggle function.
//
// Use a jQuery function to toggle the sidenav bar. The initial state
// is undefined / inherited, so it will pop in and out as the screen
// resizes around the "large" breakpoint.
function toggleSidenav() {
$("#sidenav").toggle("fast");
}
</script>
<!-- END: /topnav-incl.html -->
</div>
<div id="sidenav">
<!-- START: sidenav-incl.html active:#sidenav-visualizations -->
<!-- side navigation bar contents -->
<ul>
<li id="sidenav-index"><a href="./">Introduction</a></li>
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a></li>
<ul>
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels &amp; Symbols</a></li>
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
</ul>
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a></li>
<ul>
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds &amp; Ends</a></li>
</ul>
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a></li>
<ul>
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
<li id="sidenav-visualizations" class="active"><a href="visualizations.html">Visualizations</a></li>
</ul>
</ul>
<!-- END: sidenav-incl.html -->
</div>
<div id="main">
<h2>Visualizations</h2>
<div class="grid-container">
<div class="grid-item-text">
<p>Many programs contain a significant amount of graphical data. This is
especially true for games, where the space used for bitmaps is often
larger than the space required for the code. When disassembling a program
it can be very helpful to be able to see the contents of the data
regions in graphical form.</p>
<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
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
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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-add-vis.png" alt="t5-add-vis"/>
</div>
<div class="grid-item-text">
<p>The first thing we need to do is load an extension script that can
decode this format. The SourceGen "RuntimeData" directory has a few,
but for this tutorial we're using a custom one. Select
<samp>Edit &gt; Project Properties</samp>, select the
<samp>Extension Scripts</samp> tab, and click
<samp>Add Scripts from Project</samp>.
Double-click on "<samp>VisTutorial5.cs</samp>",
then click </samp>OK</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-new-vis.png" alt="t5-new-vis"/>
</div>
<div class="grid-item-text">
<p>The addresses of the three bitmaps are helpfully identified by the
load instructions at the top of the file. Select the line at
address $100A, then
<samp>Actions &gt; Create/Edit Visualization Set</samp>. In
the window that opens, click <samp>New Visualization</samp>.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>We're going to ignore most of what's going on and just focus on the
list of parameters at the bottom. The file offset indicates where in
the file the bitmap starts; note this is an offset, not an address
(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>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-set-height-8.png" alt="t5-set-height-8"/>
</div>
<div class="grid-item-text">
<p>We happen to know (by playing the game and/or reading the fictitious
drawing code) that the image is 8x8, so change the value in the
<samp>Height</samp>
field to 8. As soon as you do, the preview window shows a big blue 'X'.
(The 'X' is 7x7; the last row/column of pixels are transparent so adjacent
images don't bump into each other.)</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-set-height-80.png" alt="t5-set-height-80"/>
</div>
<div class="grid-item-text">
<p>Let's try doing it wrong. Add a '0' in the <samp>Height</samp>
field to make the
height 80. You can see some additional bitmap data.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-set-height-800.png" alt="t5-set-height-800"/>
</div>
<div class="grid-item-text">
<p>Add another 0 to make it 800. Now you get
a big red X, and the <samp>Height</samp> parameter is shown in red.
That's because the maximum value for the height is 512, as shown
by "<samp>[1,512]</samp>" on the right.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-addvis1.png" alt="t5-addvis1"/>
</div>
<div class="grid-item-text">
<p>Change it back to 8, and hit <samp>OK</samp>.
Hit <samp>OK</samp> in the <samp>Edit Visualization Set</samp>
window as well. You should now see the blue 'X' in the code listing
above line $100A.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-addvis2.png" alt="t5-addvis2"/>
</div>
<div class="grid-item-text">
<p>Repeat the process at line $1012: select the line, create a visualization
set, create a new visualization. The height will default to 8 because
that's what you used last time, so you shouldn't have to
make any changes to the initial values.
Click <samp>OK</samp> in both dialogs to close them.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-101a-mess.png" alt="t5-101a-mess"/>
</div>
<div class="grid-item-text">
<p>Repeat the process at line $101A, but this time the image is 40x40
rather than 8x8. Set the width to 5, and the height to 40. This makes
a mess.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-101a-good.png" alt="t5-101a-good"/>
</div>
<div class="grid-item-text">
<p>In this case, the bitmap data is 5 bytes wide, but the data is stored
as 8 bytes per row. This is known as the "stride" or "pitch" of the row.
To tell the visualizer to skip the last 3 bytes on each row, set the
<samp>Row stride (bytes)</samp> field to 8.
Now we have a proper Tic-Tac-Toe grid.
Note that it fills the preview window just as the 'X' and 'O' did, even
though it's 5x as large. The preview window scales everything up. Hit
<samp>OK</samp> twice to create the visualization.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-fmt-dense.png" alt="t5-fmt-dense"/>
</div>
<div class="grid-item-text">
<p>Let's format the bitmap data. Select line $101A, then shift-click the
last line in the file ($1159). <samp>Actions &gt; Edit Operand</samp>. Select
<samp>Densely-packed bytes</samp>, and click <samp>OK</samp>.
This is perhaps a little too
dense. Open the operand editor again, but this time select the
densely-packed bytes sub-option <samp>...with a limit</samp>, and set the limit
to 8 bytes per line. Instead of one very dense statement spread across
a few lines, you get one line of source code per row of bitmap.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>To change whether or not commas appear between bytes in the operand,
open <samp>Edit &gt; Settings</samp>, select the
<samp>Display Format</samp> tab, and check
<samp>Use comma-separated format for bulk data</samp>.
This trades off compactness for ease of reading.</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Bitmap Animations</h4>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-bitmap-anim-editor.png" alt="t5-bitmap-anim-editor"/>
</div>
<div class="grid-item-text">
<p>Some bitmaps represent individual frames in an animated sequence.
You can convert those as well. Double-click on the blue 'X' to open
the visualization set editor, then click "New Bitmap Animation". This
opens the Bitmap Animation Editor.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-xo-anim.png" alt="t5-xo-anim"/>
</div>
<div class="grid-item-text">
<p>Let's try it with our Tic-Tac-Toe board pieces. From the list
on the left, select the blue 'X' and click <samp>Add</samp>, then
click the 'O' and click <samp>Add</samp>. Below the list, set the
frame delay to 500 msec. Near the bottom, click
<samp>Start / Stop</samp>. This causes the animation to play in a loop.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>You can use the controls to add and remove items, change their order, and change
the animation speed. You can add the grid bitmap to the animation set, but the
preview scales the bitmaps up to full size, so it may not look the way
you expect.</p>
<p>Hit <samp>OK</samp> to save the animation, then
<samp>OK</samp> to update the visualization set.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-list-xanim.png" alt="t5-list-xanim"/>
</div>
<div class="grid-item-text">
<p>The code list now shows two entries in the line: the first is the 'X'
bitmap, the second is the animation, which is shown as the initial frame
with a blue triangle superimposed. (If you go back into the editor and
reverse the order of the frames, the list will show the 'O' instead.)
You can have as many bitmaps and animations on a line as you want.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-text">
<p>If you have a lot of bitmaps it can be helpful to give them meaningful
names, so that they're easy to identify and sort together in the list.
The <samp>Tag</samp> field at the top of the editor windows lets you
give things names. Tags must be unique.</p>
</div>
</div>
<hr style="width:80%;"/>
<h4>Other Notes</h4>
<div class="grid-container">
<div class="grid-item-text">
<p>The visualization editor is intended to be very dynamic, showing the
results of parameter changes immediately. This can be helpful if you're
not exactly sure what the size or format of a bitmap is. Just keep
tweaking values until it looks right.</p>
<p>Visualization generators are defined by extension scripts. If you're
disassembling a program with a totally custom way of storing graphics,
you can write a totally custom visualizer and distribute it with the
project. Because the file offset is a parameter, you're not limited to
placing visualizations at the start of the graphic data -- you can put
them on any code or data line.</p>
<p>Visualizations have no effect on assembly source code generation,
but they do appear in code exported to HTML. Bitmaps are converted to GIF
images, and animations become animated GIFs.</p>
</div>
</div>
<div class="grid-container">
<div class="grid-item-image">
<img src="images/t5-wireframe-sample.png" alt="t5-wireframe-sample"/>
</div>
<div class="grid-item-text">
<p>You can also create animated visualizations of wireframe objects
(vector graphics, 3D shapes), but that's not covered in this tutorial.</p>
</div>
</div>
</div> <!-- #main -->
<div id="prevnext">
<a href="extension-scripts.html" class="btn-previous">&laquo; Previous</a>
</div>
<div id="footer">
<!-- START: /footer-incl.html -->
<hr/>
<p>Copyright 2021 faddenSoft</p>
<!-- <p id="screen-size"></p>
<script>
var w = window.innerWidth;
var h = window.innerHeight;
var x = document.getElementById("screen-size");
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
</script> -->
<!-- END: /footer-incl.html -->
</div>
</body>
</html>