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.
9
docs/footer-incl.html
Normal file
@ -0,0 +1,9 @@
|
||||
<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> -->
|
316
docs/index.html
@ -1,145 +1,171 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
|
||||
<head>
|
||||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<link href="main.css" rel="stylesheet" type="text/css" />
|
||||
|
||||
<title>6502bench Tools</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div id="content">
|
||||
<h1>6502bench SourceGen</h1>
|
||||
|
||||
<p>6502bench is a code development "workbench" for the 65xx family
|
||||
of processors, including the 6502, 65C02, and 65802/65816. It currently
|
||||
features one tool, the SourceGen disassembler.</p>
|
||||
|
||||
<p>Quick links:</p>
|
||||
<ul>
|
||||
<li>Watch a 9-minute video of
|
||||
<a href="https://youtu.be/dalISyBPQq8">basic product features</a> (from v1.0)</li>
|
||||
<li>See an 8-minute
|
||||
<a href="https://youtu.be/lSvEr5nCHbY">demonstration of visualizers</a>
|
||||
in a disassembly of the Apple II game <i>Space Eggs</i></li>
|
||||
<li>Download source & binaries for the latest version
|
||||
<a href="https://github.com/fadden/6502bench/releases/">from the Releases page</a></li>
|
||||
<li>Check out the
|
||||
<a href="https://github.com/fadden/6502bench/">GitHub project</a></li>
|
||||
<li>SourceGen has been used to disassemble software for the Apple II,
|
||||
NES (Nintendo Entertainment System), Atari 2600 VCS, and coin-op arcade
|
||||
systems. Visit 6502disassembly.com to see some
|
||||
<a href="https://6502disassembly.com/">disassembly project examples</a>.</li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
|
||||
<p><strong>SourceGen</strong> is an industrial-strength disassembler for 6502,
|
||||
65C02, and 65816 programs. It runs on Windows 7 or later. Key features include:</p>
|
||||
<ul>
|
||||
<li>Fully interactive point-and-click GUI. Define labels, set addresses,
|
||||
add comments, and see the results immediately. Add multi-line comments
|
||||
and have them word-wrapped automatically. Create inline visualizations of
|
||||
embedded bitmaps and wireframe data, and define animated sequences.</li>
|
||||
<li>Sophisticated static analysis. The disassembly engine traces code
|
||||
execution, automatically finding all instructions reachable from a given
|
||||
starting point. Changes to the processor status flags are tracked,
|
||||
allowing identification of branches that are always/never taken,
|
||||
accurate cycle count listings, and easier analysis of 65816 code with
|
||||
variable-width registers.</li>
|
||||
<li>Easy generation of assembly source code in popular formats (currently
|
||||
64tass, ACME, cc65, and Merlin 32). Cross-assemblers can be invoked from the GUI to
|
||||
verify correctness.</li>
|
||||
<li>Symbols and constants are provided for ROM and operating system entry
|
||||
points on several popular systems (Apple, Atari, Commodore, others).</li>
|
||||
<li>Project files are designed for sharing and collaboration.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
<a href="images/screenshot-15-mainwin.png"><img border="2" src="images/screenshot-15-mainwin-small.png" alt="Main Window Screenshot" width="320" height="180"/></a>
|
||||
<a href="images/screenshot-15-asmwin.png"><img border="2" src="images/screenshot-15-asmwin-small.png" alt="Gen/Asm Dialog Screenshot" width="320" height="180"/></a>
|
||||
<a href="images/screenshot-15-vis.png"><img border="2" src="images/screenshot-15-vis-small.png" alt="Gen/Asm Dialog Screenshot" width="320" height="180"/></a>
|
||||
</p>
|
||||
|
||||
<h4>Features in Detail:</h4>
|
||||
<ul>
|
||||
<li>Analyzer:
|
||||
<ul>
|
||||
<li>Support for 6502, 65C02, and 65816, including undocumented
|
||||
opcodes and the W65C02 extensions.</li>
|
||||
<li>Code tagging mechanism allows manual identification of code start/stop
|
||||
points and inline data.</li>
|
||||
<li>Editable labels are generated for every branch destination and data
|
||||
target.</li>
|
||||
<li>Automatic detection and classification of character strings and runs
|
||||
of identical bytes.</li>
|
||||
<li>Symbol files for ROM entry points, operating system constants, and
|
||||
other platform-specific data are stored in plain text files loaded at runtime.</li>
|
||||
<li>Extension scripts can be defined that automatically reformat code and
|
||||
identify inline data that follows a JSR, JSL, or BRK.</li>
|
||||
</ul></li>
|
||||
<li>User interface:
|
||||
<ul>
|
||||
<li>"Infinite" undo/redo of all operations.</li>
|
||||
<li>Cross-reference tables are generated for every branch and data target
|
||||
address, as well as for external platform symbols.</li>
|
||||
<li>Instruction operand formats (hex, decimal, binary, character, symbol) can
|
||||
be set for individual instructions. References to nearby symbols are
|
||||
offset, allowing simple expressions like "addr + 1".</li>
|
||||
<li>Data areas can be formatted in various formats, including individual
|
||||
bytes, 16-bit and 24-bit words, addresses, or strings.
|
||||
Multiple character encodings are supported, including ASCII, high ASCII,
|
||||
C64 PETSCII, and C64 screen codes.</li>
|
||||
<li>Zero-page variables can be given different labels at different points
|
||||
in the program.</li>
|
||||
<li>Multi-line comments can be "boxed" for an authentic retro feel.</li>
|
||||
<li>Notes can be added that aren't included in generated output. These
|
||||
also function as color-coded bookmarks. Very useful for marking up a
|
||||
work in progress. Similarly, symbols can be marked as uncertain by
|
||||
adding a '?' that is automatically stripped away during code generation.</li>
|
||||
<li>Instruction reference data, such as CPU cycles and flags modified, are
|
||||
shown along with a description of the opcode's function. Very useful when
|
||||
encountering rarely-used undocumented instructions.</li>
|
||||
<li>Various aspects of the code display can be reconfigured, including
|
||||
upper/lower case, pseudo-opcode naming, and expression formats. These
|
||||
choices are not part of the project definition, so everyone can view a
|
||||
project according to their own personal preferences.</li>
|
||||
</ul></li>
|
||||
<li>Code generation:
|
||||
<ul>
|
||||
<li>Labels can be global or local. Use non-unique labels like "@Loop"
|
||||
for clarity. Labels will be promoted from local to global or renamed to
|
||||
be unique as required by each assembler.</li>
|
||||
<li>Symbols may be exported from one project and imported into another
|
||||
to facilitate multi-binary disassembly.</li>
|
||||
<li>Listings can be generated in HTML form for publication on the web. Many
|
||||
aspects of the output format can be configured. Inline visualizations
|
||||
are exported as GIF or animated GIF.</li>
|
||||
</ul></li>
|
||||
<li>Miscellaneous:
|
||||
<ul>
|
||||
<li>All project data is stored in text formats (primarily JSON).</li>
|
||||
<li>The project file includes nothing from the data file but a CRC. This
|
||||
may allow the project to be shared without violating copyrights (subject
|
||||
to local laws).</li>
|
||||
<li>Handy tools: file slicer, file concatenator, CPU instruction reference
|
||||
chart, ASCII chart, file hex dump.</li>
|
||||
<li>The OMF converter tool can be used to disassemble Apple IIgs executables.</li>
|
||||
</ul></li>
|
||||
</ul>
|
||||
|
||||
<p>SourceGen is written in C# .NET, using the (free to download) Visual
|
||||
Studio Community 2019 IDE as the primary development environment.
|
||||
The user interface uses the Windows Presentation Foundation (WPF) API.
|
||||
The full source code for the project is available on GitHub, licensed under Apache 2.0.</p>
|
||||
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<hr/>
|
||||
<p>Copyright 2020 faddenSoft</p>
|
||||
</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>6502bench Tools</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-home -->
|
||||
<script>
|
||||
// Load global topnav content, and mark current page active.
|
||||
$("#topnav").load("/topnav-incl.html", function() {
|
||||
$("#topnav-home").addClass("active")
|
||||
});
|
||||
</script>
|
||||
<!-- END: /topnav-incl.html -->
|
||||
</div>
|
||||
|
||||
<div id="main" class="no-sidenav">
|
||||
|
||||
<p>6502bench is a code development "workbench" for the 65xx family
|
||||
of processors, including the 6502, 65C02, and 65802/65816. It currently
|
||||
features one tool, the SourceGen disassembler.</p>
|
||||
|
||||
<p><strong>SourceGen</strong> is an industrial-strength disassembler for 6502,
|
||||
65C02, and 65816 programs. It runs on Windows 7 or later.</p>
|
||||
|
||||
<p>Quick links:</p>
|
||||
<ul>
|
||||
<li>Watch a 9-minute
|
||||
<a href="https://youtu.be/dalISyBPQq8">product introduction video</a> (from v1.0).</li>
|
||||
<li>See an 8-minute
|
||||
<a href="https://youtu.be/lSvEr5nCHbY">demonstration of visualizers</a>
|
||||
in a disassembly of the Apple II game <i>Space Eggs</i>.</li>
|
||||
<li>Download source & binaries for the latest version
|
||||
<a href="https://github.com/fadden/6502bench/releases/">from the Releases page</a>.</li>
|
||||
<li>Check out the
|
||||
<a href="https://github.com/fadden/6502bench/">GitHub project</a>.</li>
|
||||
<li>SourceGen has been used to disassemble software for the Apple II,
|
||||
NES (Nintendo Entertainment System), Atari 2600 VCS, and coin-op arcade
|
||||
systems. Visit 6502disassembly.com to see some
|
||||
<a href="https://6502disassembly.com/">disassembly project examples</a>.</li>
|
||||
</ul>
|
||||
|
||||
<p>Key features include:</p>
|
||||
<ul>
|
||||
<li>Fully interactive point-and-click GUI. Define labels, set addresses,
|
||||
add comments, and see the results immediately. Add multi-line comments
|
||||
and have them word-wrapped automatically. Create inline visualizations of
|
||||
embedded bitmaps and wireframe data, and define animated sequences.</li>
|
||||
<li>Sophisticated static analysis. The disassembly engine traces code
|
||||
execution, automatically finding all instructions reachable from a given
|
||||
starting point. Changes to the processor status flags are tracked,
|
||||
allowing identification of branches that are always/never taken,
|
||||
accurate cycle count listings, and easier analysis of 65816 code with
|
||||
variable-width registers.</li>
|
||||
<li>Easy generation of assembly source code in popular formats (currently
|
||||
64tass, ACME, cc65, and Merlin 32). Cross-assemblers can be invoked from the GUI to
|
||||
verify correctness.</li>
|
||||
<li>Symbols and constants are provided for ROM and operating system entry
|
||||
points on several popular systems (Apple, Atari, Commodore, others).</li>
|
||||
<li>Project files are designed for sharing and collaboration.</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
<a href="images/screenshot-15-mainwin.png"><img border="2" src="images/screenshot-15-mainwin-small.png" alt="Main Window Screenshot" width="320" height="180"/></a>
|
||||
<a href="images/screenshot-15-asmwin.png"><img border="2" src="images/screenshot-15-asmwin-small.png" alt="Gen/Asm Dialog Screenshot" width="320" height="180"/></a>
|
||||
<a href="images/screenshot-15-vis.png"><img border="2" src="images/screenshot-15-vis-small.png" alt="Gen/Asm Dialog Screenshot" width="320" height="180"/></a>
|
||||
</p>
|
||||
|
||||
<h4>Features in Detail:</h4>
|
||||
<ul>
|
||||
<li>Analyzer:
|
||||
<ul>
|
||||
<li>Support for 6502, 65C02, and 65816, including undocumented
|
||||
opcodes and the W65C02 extensions.</li>
|
||||
<li>Code tagging mechanism allows manual identification of code start/stop
|
||||
points and inline data.</li>
|
||||
<li>Editable labels are generated for every branch destination and data
|
||||
target.</li>
|
||||
<li>Automatic detection and classification of character strings and runs
|
||||
of identical bytes.</li>
|
||||
<li>Symbol files for ROM entry points, operating system constants, and
|
||||
other platform-specific data are stored in plain text files loaded at runtime.</li>
|
||||
<li>Extension scripts can be defined that automatically reformat code and
|
||||
identify inline data that follows a JSR, JSL, or BRK.</li>
|
||||
</ul></li>
|
||||
<li>User interface:
|
||||
<ul>
|
||||
<li>"Infinite" undo/redo of all operations.</li>
|
||||
<li>Cross-reference tables are generated for every branch and data target
|
||||
address, as well as for external platform symbols.</li>
|
||||
<li>Instruction operand formats (hex, decimal, binary, character, symbol) can
|
||||
be set for individual instructions. References to nearby symbols are
|
||||
offset, allowing simple expressions like "addr + 1".</li>
|
||||
<li>Data areas can be formatted in various formats, including individual
|
||||
bytes, 16-bit and 24-bit words, addresses, or strings.
|
||||
Multiple character encodings are supported, including ASCII, high ASCII,
|
||||
C64 PETSCII, and C64 screen codes.</li>
|
||||
<li>Zero-page variables can be given different labels at different points
|
||||
in the program.</li>
|
||||
<li>Multi-line comments can be "boxed" for an authentic retro feel.</li>
|
||||
<li>Notes can be added that aren't included in generated output. These
|
||||
also function as color-coded bookmarks. Very useful for marking up a
|
||||
work in progress. Similarly, symbols can be marked as uncertain by
|
||||
adding a '?' that is automatically stripped away during code generation.</li>
|
||||
<li>Instruction reference data, such as CPU cycles and flags modified, are
|
||||
shown along with a description of the opcode's function. Very useful when
|
||||
encountering rarely-used undocumented instructions.</li>
|
||||
<li>Various aspects of the code display can be reconfigured, including
|
||||
upper/lower case, pseudo-opcode naming, and expression formats. These
|
||||
choices are not part of the project definition, so everyone can view a
|
||||
project according to their own personal preferences.</li>
|
||||
</ul></li>
|
||||
<li>Code generation:
|
||||
<ul>
|
||||
<li>Labels can be global or local. Use non-unique labels like "@Loop"
|
||||
for clarity. Labels will be promoted from local to global or renamed to
|
||||
be unique as required by each assembler.</li>
|
||||
<li>Symbols may be exported from one project and imported into another
|
||||
to facilitate multi-binary disassembly.</li>
|
||||
<li>Listings can be generated in HTML form for publication on the web. Many
|
||||
aspects of the output format can be configured. Inline visualizations
|
||||
are exported as GIF or animated GIF.</li>
|
||||
</ul></li>
|
||||
<li>Miscellaneous:
|
||||
<ul>
|
||||
<li>All project data is stored in text formats (primarily JSON).</li>
|
||||
<li>The project file includes nothing from the data file but a CRC. This
|
||||
may allow the project to be shared without violating copyrights (subject
|
||||
to local laws).</li>
|
||||
<li>Handy tools: file slicer, file concatenator, CPU instruction reference
|
||||
chart, ASCII chart, file hex dump.</li>
|
||||
<li>The OMF converter tool can be used to disassemble Apple IIgs executables.</li>
|
||||
</ul></li>
|
||||
</ul>
|
||||
|
||||
<hr/>
|
||||
|
||||
<p>6502bench is written in C# .NET, using the (free to download) Visual
|
||||
Studio Community 2019 IDE as the primary development environment.
|
||||
The user interface uses the Windows Presentation Foundation (WPF) API.
|
||||
6502bench is an open-source project, licensed under Apache 2.0.
|
||||
The full source code is available on
|
||||
<a href="https://github.com/fadden/6502bench/">GitHub</a>.</p>
|
||||
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
315
docs/main.css
@ -1,18 +1,311 @@
|
||||
/*
|
||||
/*
|
||||
Responsive web design layout for 6502bench site.
|
||||
|
||||
All pages define elements with these IDs:
|
||||
masthead (site logo / title)
|
||||
topnav (top items, menu button) (consider "sticky" navbar?); contents
|
||||
reduce to home/menu for XS
|
||||
sidenav (large: float on left; medium/small: "collapsed sidepanel" or toggle)
|
||||
main (80% for large, 100% for medium/small)
|
||||
footer (with prev/next)
|
||||
|
||||
"main" section of tutorial pages:
|
||||
2-column grid for large/medium, 1-column grid for small/XS
|
||||
*/
|
||||
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
/*
|
||||
* Overall look and feel.
|
||||
*/
|
||||
*/
|
||||
html {
|
||||
/* always show scrollbar, so centered masthead doesn't shift */
|
||||
overflow-y: scroll;
|
||||
}
|
||||
body {
|
||||
font-family: Arial, Helvetica, sans-serif;
|
||||
font-family: "Segoe UI", Arial, Helvetica, sans-serif;
|
||||
padding: 0px;
|
||||
margin: 0px;
|
||||
}
|
||||
#content {
|
||||
/* top right bottom left */
|
||||
margin: 20px 10px 10px 10px;
|
||||
/*position: relative;*/
|
||||
background-color: #ffffff;
|
||||
}
|
||||
/*code {
|
||||
font-size: 125%;
|
||||
}*/
|
||||
|
||||
/*
|
||||
* Display of keyboard shortcuts in the <kbd> element.
|
||||
*/
|
||||
kbd.key {
|
||||
border-radius: 5px;
|
||||
padding: 0px 2px 0;
|
||||
border: 1px solid black;
|
||||
background-color: #f7f7f7;
|
||||
}
|
||||
|
||||
/*
|
||||
* ==========================================================================
|
||||
* Extra small devices (phones) - DEFAULT:
|
||||
* - Main content grid is single-column.
|
||||
* - For top nav, show only the first link and menu icon.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Masthead.
|
||||
*/
|
||||
#masthead {
|
||||
/* background-color: #202020;
|
||||
color: #ffffff; */
|
||||
background-color: #e0e0e0;
|
||||
color: #101010;
|
||||
position: relative;
|
||||
}
|
||||
#masthead .masthead-title {
|
||||
text-align: center;
|
||||
font-size: 4em;
|
||||
font-weight: bolder;
|
||||
padding: 10px;
|
||||
margin: 0px;
|
||||
}
|
||||
#masthead .masthead-titleZZZ {
|
||||
/* place text */
|
||||
position: absolute;
|
||||
top: 50%;
|
||||
left: 50%;
|
||||
transform: translate(-50%, -50%);
|
||||
|
||||
bottom: 0;
|
||||
background: rgb(0, 0, 0); /* fallback color */
|
||||
background: rgba(0, 0, 0, 0.5); /* black, 50% opacity */
|
||||
color: #f1f1f1;
|
||||
width: 100%;
|
||||
padding: 20px;
|
||||
}
|
||||
#masthead img {
|
||||
/* fill space with image */
|
||||
background-position: center;
|
||||
background-repeat: no-repeat;
|
||||
background-size: cover;
|
||||
background-attachment: fixed;
|
||||
width: 100%;
|
||||
height: auto;
|
||||
}
|
||||
|
||||
/*
|
||||
* Top navigation bar. Home on the left, primary links next to it,
|
||||
* sidenav menu icon on the right for smaller screens.
|
||||
*/
|
||||
#topnav {
|
||||
border-style: none;
|
||||
border-width: thin;
|
||||
padding: 10px;
|
||||
background-color: #5f5f5f;
|
||||
}
|
||||
|
||||
/* inline-block seems to help keep the text and icon consistent when
|
||||
expanding and collapsing (vs. inline) */
|
||||
#topnav a {display:inline-block;}
|
||||
#topnav a:not(:first-child) {display:none;}
|
||||
#topnav a.icon {
|
||||
float: right;
|
||||
display: block;
|
||||
}
|
||||
#topnav button {
|
||||
float: right;
|
||||
display: block;
|
||||
color: #ffffff;
|
||||
background-color: #5f5f5f;
|
||||
text-decoration: none;
|
||||
padding: .2em 1em .2em 1em;
|
||||
}
|
||||
|
||||
#topnav nav {
|
||||
text-align: left;
|
||||
padding: 0px;
|
||||
}
|
||||
#topnav nav a {
|
||||
color: #ffffff;
|
||||
background-color: #5f5f5f;
|
||||
padding: .2em 1em .2em 1em;
|
||||
text-decoration: none;
|
||||
}
|
||||
#topnav nav a:hover {
|
||||
border-style: none;
|
||||
color: #ffffff;
|
||||
background-color: #000000;
|
||||
}
|
||||
|
||||
#topnav nav a.active {
|
||||
color: #8bc349;
|
||||
}
|
||||
|
||||
/*
|
||||
* Side navigation bar. Always visible on large screens, pops out when
|
||||
* the hamburger icon is clicked on smaller screens.
|
||||
*/
|
||||
#sidenav {
|
||||
display: none;
|
||||
width: 180px;
|
||||
margin: 0 8px 0 0;
|
||||
padding: 5px;
|
||||
}
|
||||
#sidenav ul {
|
||||
list-style-type: none;
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
}
|
||||
#sidenav li {
|
||||
padding: 0 0px 1px 0; /* top right bottom left */
|
||||
}
|
||||
#sidenav ul ul li {
|
||||
padding: 0 0 1px 10px; /* top right bottom left */
|
||||
}
|
||||
#sidenav a {
|
||||
color: #ffffff;
|
||||
display: block;
|
||||
background-color: #5f5f5f;
|
||||
padding: 5px 5px 5px 8px; /* top right bottom left */
|
||||
text-decoration: none;
|
||||
}
|
||||
#sidenav a:hover {
|
||||
color: #ffffff;
|
||||
background-color: #000000;
|
||||
}
|
||||
#sidenav .active a {
|
||||
color: #8bc349;
|
||||
}
|
||||
|
||||
/*
|
||||
* Main content area.
|
||||
*/
|
||||
#main {
|
||||
margin: 8px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
/*
|
||||
* Grid layout for tutorial. Each grid has two items, forming a {text,image}
|
||||
* pair, either of which may be absent. The document is a series of grids.
|
||||
*
|
||||
* We can have images come before or after the related text by adjusting
|
||||
* the grid-row values.
|
||||
*/
|
||||
.grid-container {
|
||||
display: grid;
|
||||
grid-template-rows: auto auto;
|
||||
/*margin-bottom: 4px;*/
|
||||
}
|
||||
|
||||
.grid-item-text {
|
||||
/* background-color: #e0e0ff; */
|
||||
grid-row: 1;
|
||||
}
|
||||
.grid-item-text p {
|
||||
/* items in grids don't collapse margins */
|
||||
/* cf. https://stackoverflow.com/q/18963421/294248 */
|
||||
margin-block-start: 0;
|
||||
}
|
||||
|
||||
.grid-item-image {
|
||||
/* background-color: #ffe0e0; */
|
||||
grid-row: 2;
|
||||
justify-self: center; /* center narrow images, mostly for 1-col layout */
|
||||
}
|
||||
.grid-item-image img {
|
||||
width: 100%;
|
||||
height: auto;
|
||||
/* don't expand image beyond original size */
|
||||
max-height: max-content;
|
||||
max-width: max-content;
|
||||
border: 1px solid #e0e0e0;
|
||||
margin-top: 5px; /* align closer to top of text */
|
||||
}
|
||||
|
||||
/*
|
||||
* Previous/next buttons.
|
||||
*/
|
||||
#prevnext {
|
||||
/* clear: both; */
|
||||
margin: 8px;
|
||||
margin-top: 30px;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
#prevnext a {
|
||||
text-decoration: none;
|
||||
display: inline-block;
|
||||
padding: 8px 16px;
|
||||
border-radius: 5px;
|
||||
background-color: #f1f1f1;
|
||||
color: black;
|
||||
}
|
||||
#prevnext a:hover {
|
||||
background-color: #ddd;
|
||||
}
|
||||
|
||||
/*
|
||||
* Footer.
|
||||
*/
|
||||
#footer {
|
||||
/* top right bottom left */
|
||||
margin: 20px 10px 10px 10px;
|
||||
/*position: relative;*/
|
||||
/* top margin gets eaten up by sidenav on short pages */
|
||||
clear: both;
|
||||
margin: 8px;
|
||||
}
|
||||
|
||||
/*
|
||||
* ==========================================================================
|
||||
* Small devices (portrait tablets, large phones):
|
||||
* - For top nav, want to show all links in the top nav bar, as well
|
||||
* as the menu icon.
|
||||
*/
|
||||
@media only screen and (min-width: 600px) {
|
||||
#topnav a:not(:first-child) {display:inline-block;}
|
||||
}
|
||||
|
||||
/*
|
||||
* ==========================================================================
|
||||
* Medium devices (landscape tablets):
|
||||
* - Switch to two-column layout, text on the left, image on the right.
|
||||
*/
|
||||
@media only screen and (min-width: 768px) {
|
||||
.grid-container {
|
||||
grid-template-columns: 50% 50%;
|
||||
grid-template-rows: initial;
|
||||
grid-column-gap: 8px;
|
||||
}
|
||||
.grid-item-text {
|
||||
grid-row: 1;
|
||||
grid-column: 1;
|
||||
}
|
||||
.grid-item-image {
|
||||
grid-row: 1;
|
||||
grid-column: 2;
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* ==========================================================================
|
||||
* Large devices (laptops/desktops):
|
||||
* - Show sidenav on the side.
|
||||
* - Don't show menu icon in the topnav bar.
|
||||
*/
|
||||
@media only screen and (min-width: 992px) {
|
||||
#sidenav {
|
||||
display: block;
|
||||
float: left;
|
||||
}
|
||||
|
||||
#main {
|
||||
/* make room for sidenav */
|
||||
margin-left: 188px;
|
||||
}
|
||||
#main.no-sidenav {
|
||||
/* ...or not */
|
||||
margin-left: 8px;
|
||||
}
|
||||
|
||||
#topnav a.icon {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
4
docs/masthead-incl.html
Normal file
@ -0,0 +1,4 @@
|
||||
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
|
||||
<div class="masthead-title">
|
||||
6502bench
|
||||
</div>
|
161
docs/sgtutorial/about-disasm.html
Normal file
@ -0,0 +1,161 @@
|
||||
<!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 #<addrs ;get pointer into
|
||||
sta ptr ; address table
|
||||
lda #>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">« Previous</a>
|
||||
<a href="#" class="btn-next">Next »</a>
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
267
docs/sgtutorial/address-tables.html
Normal file
@ -0,0 +1,267 @@
|
||||
<!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 > 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 > 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 > 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><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>>FUNC</code>. (If it says
|
||||
<code><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 > 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 > 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 > Close</samp>. When SourceGen asks for confirmation,
|
||||
click <samp>Discard & Continue</samp>.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
</div> <!-- #main -->
|
||||
|
||||
<div id="prevnext">
|
||||
<a href="#" class="btn-previous">« Previous</a>
|
||||
<a href="#" class="btn-next">Next »</a>
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
80
docs/sgtutorial/advanced-topics.html
Normal file
@ -0,0 +1,80 @@
|
||||
<!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> </p>
|
||||
|
||||
</div> <!-- #main -->
|
||||
|
||||
<div id="prevnext">
|
||||
<a href="#" class="btn-previous">« Previous</a>
|
||||
<a href="#" class="btn-next">Next »</a>
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
167
docs/sgtutorial/digging-deeper.html
Normal file
@ -0,0 +1,167 @@
|
||||
<!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 > 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 > 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 > 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 > 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 > Set Address</samp>, and enter "2000". With that line
|
||||
still selected, use <samp>Actions > 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 > 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">« Previous</a>
|
||||
<a href="#" class="btn-next">Next »</a>
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
204
docs/sgtutorial/editing-data.html
Normal file
@ -0,0 +1,204 @@
|
||||
<!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 > 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 > 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 > 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 > 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 > 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">« Previous</a>
|
||||
<a href="#" class="btn-next">Next »</a>
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
191
docs/sgtutorial/extension-scripts.html
Normal file
@ -0,0 +1,191 @@
|
||||
<!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 > 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 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">« Previous</a>
|
||||
<a href="#" class="btn-next">Next »</a>
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
131
docs/sgtutorial/generating-code.html
Normal file
@ -0,0 +1,131 @@
|
||||
<!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 > 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 > 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 > 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">« Previous</a>
|
||||
<a href="#" class="btn-next">Next »</a>
|
||||
</div>
|
||||
|
||||
<div id="footer">
|
||||
<!-- START: /footer-incl.html -->
|
||||
<script>$("#footer").load("/footer-incl.html");</script>
|
||||
<!-- END: /footer-incl.html -->
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
BIN
docs/sgtutorial/images/t0-bad-disasm.png
Normal file
After Width: | Height: | Size: 4.3 KiB |
BIN
docs/sgtutorial/images/t0-sourcegen.png
Normal file
After Width: | Height: | Size: 22 KiB |
BIN
docs/sgtutorial/images/t1-2003-done.png
Normal file
After Width: | Height: | Size: 8.3 KiB |
BIN
docs/sgtutorial/images/t1-addr-chg-1017.png
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
docs/sgtutorial/images/t1-all-columns.png
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
docs/sgtutorial/images/t1-asmgen-asmout.png
Normal file
After Width: | Height: | Size: 15 KiB |
BIN
docs/sgtutorial/images/t1-asmgen-dlg.png
Normal file
After Width: | Height: | Size: 17 KiB |
BIN
docs/sgtutorial/images/t1-asmgen-preview.png
Normal file
After Width: | Height: | Size: 19 KiB |
BIN
docs/sgtutorial/images/t1-click-1002.png
Normal file
After Width: | Height: | Size: 51 KiB |
BIN
docs/sgtutorial/images/t1-click-1017.png
Normal file
After Width: | Height: | Size: 28 KiB |
BIN
docs/sgtutorial/images/t1-data-editdlg-1.png
Normal file
After Width: | Height: | Size: 52 KiB |
BIN
docs/sgtutorial/images/t1-data-editdlg-2.png
Normal file
After Width: | Height: | Size: 51 KiB |
BIN
docs/sgtutorial/images/t1-data-editdlg-3.png
Normal file
After Width: | Height: | Size: 52 KiB |
BIN
docs/sgtutorial/images/t1-data-edited-1.png
Normal file
After Width: | Height: | Size: 7.8 KiB |
BIN
docs/sgtutorial/images/t1-data-edited-2.png
Normal file
After Width: | Height: | Size: 8.6 KiB |
BIN
docs/sgtutorial/images/t1-data-edited-3.png
Normal file
After Width: | Height: | Size: 13 KiB |
BIN
docs/sgtutorial/images/t1-data-string-bytes.png
Normal file
After Width: | Height: | Size: 11 KiB |
BIN
docs/sgtutorial/images/t1-data-stringblob.png
Normal file
After Width: | Height: | Size: 8.0 KiB |
BIN
docs/sgtutorial/images/t1-edit-2000-done.png
Normal file
After Width: | Height: | Size: 20 KiB |
BIN
docs/sgtutorial/images/t1-edit-label.png
Normal file
After Width: | Height: | Size: 29 KiB |
BIN
docs/sgtutorial/images/t1-edit-long-comment.png
Normal file
After Width: | Height: | Size: 16 KiB |
BIN
docs/sgtutorial/images/t1-edit-note.png
Normal file
After Width: | Height: | Size: 34 KiB |
BIN
docs/sgtutorial/images/t1-edit-sym-2000.png
Normal file
After Width: | Height: | Size: 58 KiB |
BIN
docs/sgtutorial/images/t1-export-dlg.png
Normal file
After Width: | Height: | Size: 22 KiB |
BIN
docs/sgtutorial/images/t1-fresh-install.png
Normal file
After Width: | Height: | Size: 80 KiB |
BIN
docs/sgtutorial/images/t1-fullscreen.png
Normal file
After Width: | Height: | Size: 95 KiB |
BIN
docs/sgtutorial/images/t1-goto-box.png
Normal file
After Width: | Height: | Size: 32 KiB |
BIN
docs/sgtutorial/images/t1-local-loop-edit.png
Normal file
After Width: | Height: | Size: 27 KiB |
BIN
docs/sgtutorial/images/t1-local-loop1.png
Normal file
After Width: | Height: | Size: 7.3 KiB |
BIN
docs/sgtutorial/images/t1-local-loop2.png
Normal file
After Width: | Height: | Size: 7.5 KiB |
BIN
docs/sgtutorial/images/t1-multi-disab.png
Normal file
After Width: | Height: | Size: 54 KiB |
BIN
docs/sgtutorial/images/t1-new-project.png
Normal file
After Width: | Height: | Size: 32 KiB |
BIN
docs/sgtutorial/images/t1-new-tutorial1.png
Normal file
After Width: | Height: | Size: 27 KiB |
BIN
docs/sgtutorial/images/t1-pre-sym-2000.png
Normal file
After Width: | Height: | Size: 5.5 KiB |
BIN
docs/sgtutorial/images/t1-set-addr-1017.png
Normal file
After Width: | Height: | Size: 29 KiB |
BIN
docs/sgtutorial/images/t1-settings.png
Normal file
After Width: | Height: | Size: 40 KiB |
BIN
docs/sgtutorial/images/t1-simple-instr-edit.png
Normal file
After Width: | Height: | Size: 46 KiB |
BIN
docs/sgtutorial/images/t1-sym-2005-adjust.png
Normal file
After Width: | Height: | Size: 6.9 KiB |
BIN
docs/sgtutorial/images/t1-sym-2005-before.png
Normal file
After Width: | Height: | Size: 4.1 KiB |
BIN
docs/sgtutorial/images/t1-sym-2005-edit.png
Normal file
After Width: | Height: | Size: 28 KiB |
BIN
docs/sgtutorial/images/t1-sym-2005-explicit.png
Normal file
After Width: | Height: | Size: 12 KiB |
BIN
docs/sgtutorial/images/t1-sym-2005-labeled.png
Normal file
After Width: | Height: | Size: 13 KiB |
BIN
docs/sgtutorial/images/t1-sym-2005-msg-window.png
Normal file
After Width: | Height: | Size: 7.4 KiB |
BIN
docs/sgtutorial/images/t1-sym-2005-nosym.png
Normal file
After Width: | Height: | Size: 5.9 KiB |
BIN
docs/sgtutorial/images/t1-symbol-filters.png
Normal file
After Width: | Height: | Size: 6.8 KiB |
BIN
docs/sgtutorial/images/t1-toolbar.png
Normal file
After Width: | Height: | Size: 8.5 KiB |
BIN
docs/sgtutorial/images/t2-1000-edit1.png
Normal file
After Width: | Height: | Size: 6.0 KiB |
BIN
docs/sgtutorial/images/t2-1000-edit2.png
Normal file
After Width: | Height: | Size: 6.5 KiB |
BIN
docs/sgtutorial/images/t2-1000-fmt-word.png
Normal file
After Width: | Height: | Size: 6.3 KiB |
BIN
docs/sgtutorial/images/t2-1000-ready.png
Normal file
After Width: | Height: | Size: 12 KiB |
BIN
docs/sgtutorial/images/t2-1000-setcode.png
Normal file
After Width: | Height: | Size: 8.4 KiB |
BIN
docs/sgtutorial/images/t2-203d-after-edit2.png
Normal file
After Width: | Height: | Size: 6.1 KiB |
BIN
docs/sgtutorial/images/t2-203d-edit1.png
Normal file
After Width: | Height: | Size: 29 KiB |
BIN
docs/sgtutorial/images/t2-203d-start.png
Normal file
After Width: | Height: | Size: 5.1 KiB |
BIN
docs/sgtutorial/images/t2-2048.png
Normal file
After Width: | Height: | Size: 7.3 KiB |
BIN
docs/sgtutorial/images/t2-204e-lv.png
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
docs/sgtutorial/images/t2-2055.png
Normal file
After Width: | Height: | Size: 7.3 KiB |
BIN
docs/sgtutorial/images/t2-206b.png
Normal file
After Width: | Height: | Size: 6.9 KiB |
BIN
docs/sgtutorial/images/t2-2078-done.png
Normal file
After Width: | Height: | Size: 6.0 KiB |
BIN
docs/sgtutorial/images/t2-2078.png
Normal file
After Width: | Height: | Size: 8.7 KiB |
BIN
docs/sgtutorial/images/t2-2081-stuff.png
Normal file
After Width: | Height: | Size: 7.3 KiB |
BIN
docs/sgtutorial/images/t2-2086.png
Normal file
After Width: | Height: | Size: 8.5 KiB |
BIN
docs/sgtutorial/images/t2-2092.png
Normal file
After Width: | Height: | Size: 6.2 KiB |
BIN
docs/sgtutorial/images/t2-20a7.png
Normal file
After Width: | Height: | Size: 2.9 KiB |
BIN
docs/sgtutorial/images/t2-20ab-1.png
Normal file
After Width: | Height: | Size: 6.2 KiB |
BIN
docs/sgtutorial/images/t2-20ab-2.png
Normal file
After Width: | Height: | Size: 4.9 KiB |
BIN
docs/sgtutorial/images/t2-after-ptr-entry.png
Normal file
After Width: | Height: | Size: 6.6 KiB |
BIN
docs/sgtutorial/images/t2-create-ptr-entry.png
Normal file
After Width: | Height: | Size: 18 KiB |
BIN
docs/sgtutorial/images/t2-enable-counts.png
Normal file
After Width: | Height: | Size: 42 KiB |
BIN
docs/sgtutorial/images/t2-fmt-xdata-done.png
Normal file
After Width: | Height: | Size: 5.1 KiB |
BIN
docs/sgtutorial/images/t2-fmt-xdata.png
Normal file
After Width: | Height: | Size: 25 KiB |
BIN
docs/sgtutorial/images/t2-inline-after.png
Normal file
After Width: | Height: | Size: 6.1 KiB |
BIN
docs/sgtutorial/images/t2-inline-tag.png
Normal file
After Width: | Height: | Size: 12 KiB |
BIN
docs/sgtutorial/images/t2-override-status.png
Normal file
After Width: | Height: | Size: 26 KiB |
BIN
docs/sgtutorial/images/t2-seek-nearby.png
Normal file
After Width: | Height: | Size: 37 KiB |
BIN
docs/sgtutorial/images/t2-show-cycle-counts.png
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
docs/sgtutorial/images/t2-str-null-term-bad.png
Normal file
After Width: | Height: | Size: 35 KiB |
BIN
docs/sgtutorial/images/t2-str-null-term-good.png
Normal file
After Width: | Height: | Size: 8.8 KiB |
BIN
docs/sgtutorial/images/t2-str-null-term-start.png
Normal file
After Width: | Height: | Size: 9.0 KiB |
BIN
docs/sgtutorial/images/t2-tutorial-top.png
Normal file
After Width: | Height: | Size: 10 KiB |
BIN
docs/sgtutorial/images/t3-1d70-code.png
Normal file
After Width: | Height: | Size: 13 KiB |
BIN
docs/sgtutorial/images/t3-1d70.png
Normal file
After Width: | Height: | Size: 17 KiB |
BIN
docs/sgtutorial/images/t3-1d97-edit.png
Normal file
After Width: | Height: | Size: 12 KiB |
BIN
docs/sgtutorial/images/t3-1d97-post.png
Normal file
After Width: | Height: | Size: 9.4 KiB |
BIN
docs/sgtutorial/images/t3-1d97.png
Normal file
After Width: | Height: | Size: 9.1 KiB |
BIN
docs/sgtutorial/images/t3-a2-props.png
Normal file
After Width: | Height: | Size: 26 KiB |
BIN
docs/sgtutorial/images/t3-amperv.png
Normal file
After Width: | Height: | Size: 7.2 KiB |
BIN
docs/sgtutorial/images/t3-format-cfg.png
Normal file
After Width: | Height: | Size: 53 KiB |
BIN
docs/sgtutorial/images/t3-format-dialog.png
Normal file
After Width: | Height: | Size: 79 KiB |