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.
251 lines
11 KiB
HTML
251 lines
11 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>Extension Scripts - 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-extension-scripts -->
|
|
<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"><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" class="active"><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>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" as
|
|
the data file.
|
|
You can choose to save the project file or not.</p>
|
|
<!--<p>We'll need to load scripts from the project directory, so we have to
|
|
save the project. <samp>File > 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 > Project Properties</samp>, select the
|
|
<samp>Extension Scripts</samp> tab, and click
|
|
<samp>Add Scripts from Runtime</samp>. The file
|
|
browser opens in the RuntimeData directory. Open the
|
|
"<samp>Common</samp>" folder, select the file
|
|
"<samp>StdInline.cs</samp>", click <samp>Open</samp>,
|
|
then <samp>OK</samp>.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t4-stdinline-src.png" alt="t4-stdinline-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 <code>JSR</code>
|
|
instructions that call functions whose names begin with certain strings.
|
|
For ASCII strings prefixed with a 1-byte length, the appropriate
|
|
function name prefix is <code>InA1_</code>. So let's set a label.</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 $1036. 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 $1000.</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>L1036</samp>") to edit the operand.
|
|
Click <samp>Create Label</samp>, and enter "<kbd>InA1_PrintString</kbd>".
|
|
Remember that labels are case-sensitive; you must enter it exactly
|
|
as shown (note the lower-case 'n'). 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>. This one appears to be followed
|
|
by an inline 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-done.png" alt="t4-inlinenull-done"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Double-click the operand on line $100D ("<code>L1037</code>"),
|
|
click <samp>Create Label</samp>,
|
|
and set the label to "<kbd>InAZ_PrintString1</kbd>".
|
|
Hit <samp>OK</samp> twice. That formatted the string that followed,
|
|
and got us to the next <code>JSR</code>, at $1019. Repeat the
|
|
process on line $1019 ("<code>L1038</code>"), setting the label to
|
|
"<kbd>InAZ_PrintString2</kbd>".</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t4-inlinemulti-done.png" alt="t4-inlinemulti-done"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>The last <code>JSR</code>, at $1025, is followed by a 16-bit
|
|
pointer. Edit the operand, and use <samp>Create Label</samp> to
|
|
set the label at the target address to "<kbd>InWA_StringPtr</kbd>".
|
|
This causes the two bytes to be formatted as a 16-bit address,
|
|
rather than just a 16-bit value, so a label was generated
|
|
automatically at the target address ("<code>L102B</code>").</p>
|
|
|
|
<p>It would be even more helpful if it formatted the data at $102B
|
|
as a null-terminated string. The basic StdInline script doesn't
|
|
happen to do that, but it's possible to do it with a custom script.
|
|
(Scripts can format multiple data items, add symbolic references to labels
|
|
and constants, and chase pointers around.)</p>
|
|
|
|
<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
|
|
using name prefixes like <code>InAZ_</code>, rather than full function
|
|
names, is that there may be more than one function with the same stack
|
|
mechanics. Also, some functions may have multiple
|
|
entry points or chain through different locations.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>Extension scripts can make your life much easier, but they do require
|
|
some programming experience. See the "Advanced Topics" section in the
|
|
SourceGen manual for more details.</p>
|
|
</div>
|
|
</div>
|
|
|
|
</div> <!-- #main -->
|
|
|
|
<div id="prevnext">
|
|
<a href="address-tables.html" class="btn-previous">« Previous</a>
|
|
<a href="visualizations.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>
|