mirror of
https://github.com/fadden/6502bench.git
synced 2025-03-02 23:29:02 +00:00
eef1710d5d
Two main changes: - "Seek nearby targets" is no longer enabled by default. - The application asks the user to save new projects immediately. Various minor edits were also made. A couple of the images are slightly stale, showing ".org" rather than ".addrs", but they're in the advanced section and the difference isn't notable.
341 lines
15 KiB
HTML
341 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. 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 really format the text, but you can pick their color.</li>
|
|
<li>They don't appear in generated assembly sources, making them
|
|
useful for leaving notes to yourself as you work.</li>
|
|
<li>They're listed in the Notes window. Double-clicking them jumps
|
|
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>
|