mirror of
https://github.com/fadden/6502bench.git
synced 2024-06-12 08:29:29 +00:00
4537f24958
Biggest changes were to the address region handling in Tutorial1 and the use of StdInline.cs for the inline strings in Tutorial4. Also, fixed the off-by-one error in Tutorial1.
342 lines
15 KiB
HTML
342 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<!-- START: /incl-head.html -->
|
|
<!-- common head elements -->
|
|
<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"/>
|
|
<!-- END: /incl-head.html -->
|
|
|
|
<title>Making Edits - SourceGen Tutorial</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- START: /incl-masthead.html -->
|
|
<div id="masthead">
|
|
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
|
|
<div class="masthead-title">
|
|
6502bench
|
|
</div>
|
|
</div>
|
|
<!-- END: /incl-masthead.html -->
|
|
|
|
<!-- START: /incl-topnav.html active:#topnav-sgtutorial -->
|
|
<div id="topnav">
|
|
<!-- 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>
|
|
// 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>
|
|
</div>
|
|
<!-- END: /incl-topnav.html -->
|
|
|
|
<!-- START: incl-sidenav.html active:#sidenav-making-edits -->
|
|
<div id="sidenav">
|
|
<!-- 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>
|
|
<ul>
|
|
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
|
|
<li id="sidenav-making-edits" class="active"><a href="making-edits.html">Making Edits</a></li>
|
|
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels & 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>
|
|
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a>
|
|
<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 & Ends</a></li>
|
|
</ul></li>
|
|
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a>
|
|
<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></li>
|
|
<li id="sidenav-suggestions"><a href="suggestions.html">Suggestions</a></li>
|
|
</ul>
|
|
</div>
|
|
<!-- END: incl-sidenav.html -->
|
|
|
|
<div id="main">
|
|
|
|
<h2>Making 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". That's not very inspiring,
|
|
so let's change it. There are three ways to open the comment editor:</p>
|
|
<ol>
|
|
<li>Select <samp>Actions > 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 > 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>
|
|
|
|
|
|
<h4>Operands & End-of-Line Comments</h4>
|
|
|
|
<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 $1000 ("<code>LDY #$70</code>"), then
|
|
<samp>Actions > Edit Operand</samp>. This allows you to pick how you
|
|
want the operand to look. It's currently set to <samp>Default</samp>,
|
|
which for an 8-bit immediate argument means it's shown as a hexadecimal
|
|
value. Click <samp>Decimal</samp>, then <samp>OK</samp>. It now appears
|
|
as a decimal value.</p>
|
|
<p>You can also open the editor by double-clicking the operand.</p>
|
|
|
|
<p>If you double-click on a data item, such as the string at $100e,
|
|
you will open the Data Operand Editor instead of the Instruction
|
|
Operand Editor. (There will be more about this later.)</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-1000-comment.png" alt="t1-1000-comment"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>On the line at $1000, select <samp>Actions > Edit Comment</samp>.
|
|
Type a short comment, and hit <kbd class="key">Enter</kbd>. Your
|
|
comment appears at the end of the line, in the "comment" column.</p>
|
|
<p>You can also open the editor by double-clicking in the comment column.</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<h4>Address Regions</h4>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-code-list-1000.png" alt="t1-code-list-1000"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Let's take a closer look at the program, which has a short section of
|
|
code followed by a bunch of data. The initial code segment is reading
|
|
bytes from $1017 and writing them to $2000, using an index register that
|
|
starts at 112 ($70) and counts down past zero. That means it's copying
|
|
113 ($71) bytes. When the copy is done, execution jumps to the copy of
|
|
the code at $2000. It appears to be relocating the next part of the code
|
|
before executing it. The disassembler needs to be told about the address
|
|
change, which we do with the Address Region Editor.</p>
|
|
<p>When defining an address region, there are two ways to go about it.
|
|
If you know where the region ends, you can select the entire thing,
|
|
and create it with an explicit size. If you're not sure where it
|
|
ends, you can create a region with a "floating" end that continues
|
|
until it runs into another region or the end of the file. Let's
|
|
try it both ways.</p>
|
|
</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>Select the line at address $1017 and then
|
|
<samp>Actions > Create/Edit Address Region</samp>. (Or double-click
|
|
on "<code>1017</code>" in the <samp>Addr</samp> column.)
|
|
Since we only have one line selected, the address region editor
|
|
defaulted to "<samp>Create floating</samp>". It will put the floating
|
|
end marker $71 bytes after the start, which happens to be what we
|
|
want. (It turns out the tutorial is copying all data to the end of
|
|
the file... how convenient.)
|
|
In the <samp>Address</samp> field, type "<kbd>2000</kbd>", and click
|
|
<samp>OK</samp> (or hit <kbd class="key">Enter</kbd>).</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. We now have all code and data correctly identified
|
|
automatically, without the need to explicitly tag anything.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>From the menu, select <samp>Edit > Undo</samp>. Notice how
|
|
everything reverts to the way it was. Now, select
|
|
<samp>Edit > 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>Hit <samp>Edit > Undo</samp> one more time, so we're back to
|
|
where we were before we added the address region. Let's try creating
|
|
it the other way.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-select-info.png" alt="t1-select-info"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Click on line $1017, then scroll to the bottom and shift-click on
|
|
the very last line ("<code>.adrend</code>"). (If you prefer to use
|
|
keyboard navigation, move to line $1017, then hit
|
|
<kbd class="key">Shift+PgDn</kbd> until the selection includes the
|
|
end of the file.)
|
|
If you look at the Info window in the bottom-right, you should see a
|
|
line that says, "<samp>Selection spans 113 ($71) bytes</samp>", which
|
|
is what we want.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-set-addr-fixed.png" alt="t1-set-addr-fixed"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Use <samp>Actions > Create/Edit Address Region</samp> to open
|
|
the editor.
|
|
This time we have selected more than one line, so
|
|
"<samp>Create fixed</samp>" is selected by default. Enter
|
|
"<kbd>2000</kbd>" in the Address field, and click <samp>OK</samp>.</p>
|
|
|
|
<p>The results are the same as before. If the region being copied
|
|
had been a small part of the file, rather than continuing all the
|
|
way to the end, the outcome would have been slightly different.
|
|
When an address region with a fixed length ends, the next byte will
|
|
be assigned an address based on the <i>previous</i> region. So if
|
|
you created a region that mapped addresses $1017-$1046 to $2000-202f,
|
|
then the next byte would be at address $1047. This is very useful
|
|
for code that relocates small parts of itself, or uses memory
|
|
mapping tricks to execute parts of itself at different locations.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<h4>Address vs. Offset</h4>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>As you make alterations to the addresses, you will 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>
|
|
<p>In some cases, such as programs with multiple segments or overlays,
|
|
the same address may apply to several different areas. SourceGen fully
|
|
supports binaries with overlapping parts.</p>
|
|
</div>
|
|
</div>
|
|
|
|
</div> <!-- #main -->
|
|
|
|
<div id="prevnext">
|
|
<a href="moving-around.html" class="btn-previous">« Previous</a>
|
|
<a href="labels-symbols.html" class="btn-next">Next »</a>
|
|
</div>
|
|
|
|
<!-- START: /incl-footer.html -->
|
|
<div id="footer">
|
|
<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> -->
|
|
</div>
|
|
<!-- END: /incl-footer.html -->
|
|
|
|
</body>
|
|
</html>
|