6502/6502bench
1
0
Fork 0
mirror of https://github.com/fadden/6502bench.git synced 2024-12-03 05:49:48 +00:00
Code Issues Projects Releases Wiki Activity
154cff3347
6502bench/docs/sgtutorial/extension-scripts.html

192 lines
7.5 KiB
HTML
Raw Normal View History

First draft of updated web site Added a SourceGen tutorial with lots of screen shots. Uses "responsive web design" so it works well on mobile devices. This version is using jQuery load() calls to pull in pieces, but that causes a lot of blink when loading because the loads are asynchronous and may not complete until after the initial page render has finished. Tutorial prev/next links not yet working.
2021-06-06 21:07:36 +00:00
<!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">
First cut at HTML block substitution script Fairly straightfoward in Python. Also, fixed the sidenav references, which should be using the file in the sgtutorial subdirectory. Also, tweaked index.html a bit.
2021-06-07 21:51:28 +00:00
<!-- START: sidenav-incl.html active:#sidenav-extension-scripts -->
First draft of updated web site Added a SourceGen tutorial with lots of screen shots. Uses "responsive web design" so it works well on mobile devices. This version is using jQuery load() calls to pull in pieces, but that causes a lot of blink when loading because the loads are asynchronous and may not complete until after the initial page render has finished. Tutorial prev/next links not yet working.
2021-06-06 21:07:36 +00:00
<script>
// Load local sidenav content, and mark current page active.
$("#sidenav").load("sidenav-incl.html", function() {
$("#sidenav-extension-scripts").addClass("active");
});
</script>
First cut at HTML block substitution script Fairly straightfoward in Python. Also, fixed the sidenav references, which should be using the file in the sgtutorial subdirectory. Also, tweaked index.html a bit.
2021-06-07 21:51:28 +00:00
<!-- END: sidenav-incl.html -->
First draft of updated web site Added a SourceGen tutorial with lots of screen shots. Uses "responsive web design" so it works well on mobile devices. This version is using jQuery load() calls to pull in pieces, but that causes a lot of blink when loading because the loads are asynchronous and may not complete until after the initial page render has finished. Tutorial prev/next links not yet working.
2021-06-06 21:07:36 +00:00
</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>
Reference in New Issue Copy Permalink