2021-06-08 00:14:16 +00:00
|
|
|
<!DOCTYPE html>
|
|
|
|
|
<html lang="en">
|
|
|
|
|
<head>
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- START: /incl-head.html -->
|
2021-06-28 20:37:26 +00:00
|
|
|
<!-- common head elements -->
|
2021-06-08 00:14:16 +00:00
|
|
|
<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"/>
|
2021-06-28 20:37:26 +00:00
|
|
|
<link rel="stylesheet" href="../main.css"/>
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- END: /incl-head.html -->
|
2021-06-08 00:14:16 +00:00
|
|
|
|
|
|
|
|
<title>Using SourceGen - SourceGen Tutorial</title>
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- START: /incl-masthead.html -->
|
2021-06-08 00:14:16 +00:00
|
|
|
<div id="masthead">
|
2021-06-28 20:37:26 +00:00
|
|
|
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
|
|
|
|
|
<div class="masthead-title">
|
|
|
|
|
6502bench
|
|
|
|
|
</div>
|
2021-06-08 00:14:16 +00:00
|
|
|
</div>
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- END: /incl-masthead.html -->
|
2021-06-08 00:14:16 +00:00
|
|
|
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- START: /incl-topnav.html active:#topnav-sgtutorial -->
|
2021-06-08 00:14:16 +00:00
|
|
|
<div id="topnav">
|
2021-06-28 20:37:26 +00:00
|
|
|
<!-- top navigation bar contents -->
|
|
|
|
|
<nav>
|
|
|
|
|
<a id="topnav-home" href=".././">HOME</a>
|
|
|
|
|
<a id="topnav-sgtutorial" class="active" href="../sgtutorial">SourceGen Tutorial</a>
|
|
|
|
|
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
|
|
|
|
|
<i class="fa fa-bars"></i>
|
|
|
|
|
</a>
|
|
|
|
|
</nav>
|
|
|
|
|
<script>
|
|
|
|
|
// Sidenav toggle function.
|
|
|
|
|
//
|
|
|
|
|
// Use a jQuery function to toggle the sidenav bar. The initial state
|
|
|
|
|
// is undefined / inherited, so it will pop in and out as the screen
|
|
|
|
|
// resizes around the "large" breakpoint.
|
|
|
|
|
function toggleSidenav() {
|
|
|
|
|
$("#sidenav").toggle("fast");
|
|
|
|
|
}
|
|
|
|
|
</script>
|
2021-06-08 00:14:16 +00:00
|
|
|
</div>
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- END: /incl-topnav.html -->
|
2021-06-08 00:14:16 +00:00
|
|
|
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- START: incl-sidenav.html active:#sidenav-using-sourcegen -->
|
2021-06-08 00:14:16 +00:00
|
|
|
<div id="sidenav">
|
2021-06-28 20:37:26 +00:00
|
|
|
<!-- side navigation bar contents -->
|
2021-06-08 00:14:16 +00:00
|
|
|
<ul>
|
2021-06-28 20:37:26 +00:00
|
|
|
<li id="sidenav-index"><a href="./">Introduction</a></li>
|
|
|
|
|
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
|
|
|
|
|
<li id="sidenav-using-sourcegen" class="active"><a href="using-sourcegen.html">Using SourceGen</a>
|
|
|
|
|
<ul>
|
|
|
|
|
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
|
|
|
|
|
<li id="sidenav-simple-edits"><a href="simple-edits.html">Simple Edits</a></li>
|
|
|
|
|
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels & Symbols</a></li>
|
|
|
|
|
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
|
|
|
|
|
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
|
|
|
|
|
</ul></li>
|
|
|
|
|
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a>
|
|
|
|
|
<ul>
|
|
|
|
|
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
|
|
|
|
|
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
|
|
|
|
|
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
|
|
|
|
|
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds & Ends</a></li>
|
|
|
|
|
</ul></li>
|
|
|
|
|
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a>
|
|
|
|
|
<ul>
|
|
|
|
|
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
|
|
|
|
|
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
|
|
|
|
|
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
|
|
|
|
|
</ul></li>
|
2021-08-03 21:48:40 +00:00
|
|
|
<li id="sidenav-suggestions"><a href="suggestions.html">Suggestions</a></li>
|
2021-06-28 20:37:26 +00:00
|
|
|
</ul>
|
2021-06-08 00:14:16 +00:00
|
|
|
</div>
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- END: incl-sidenav.html -->
|
2021-06-08 00:14:16 +00:00
|
|
|
|
|
|
|
|
<div id="main">
|
|
|
|
|
|
|
|
|
|
<h2>Using SourceGen</h2>
|
|
|
|
|
|
2021-09-06 18:41:08 +00:00
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>Many disassemblers take a very simple approach: they dump
|
|
|
|
|
the entire binary as if it were an instruction stream. It's then
|
|
|
|
|
left to the human to carve away the data sections. SourceGen
|
|
|
|
|
comes at the problem from a different angle, and assumes
|
|
|
|
|
everything is data until proven otherwise. The human need only
|
|
|
|
|
identify where code areas start. The computer will trace through
|
|
|
|
|
code automatically, following branches and subroutine calls, and
|
|
|
|
|
whatever isn't traced is either data storage or junk (dead code,
|
|
|
|
|
alignment padding, etc).</p>
|
|
|
|
|
<p>The difference in approach can be confusing at first for people
|
|
|
|
|
accustomed to other software. Code tracing tends to produce better
|
|
|
|
|
results more quickly, however, because much of the tedium is handled
|
|
|
|
|
by the software.</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<hr style="width:80%;"/>
|
|
|
|
|
|
2021-06-08 00:14:16 +00:00
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>This first section covers the basics of working with SourceGen: how to
|
|
|
|
|
move around, make edits, generate code, and so on.
|
2021-09-06 18:41:08 +00:00
|
|
|
You can't do anything useful until you open an existing project or
|
2021-06-08 00:14:16 +00:00
|
|
|
create a new one, so we'll start there.</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>A SourceGen project is always associated with a data file, which
|
|
|
|
|
holds part or all of the program being disassembled.
|
|
|
|
|
For simplicity, the project is given the same name as the data file, with
|
|
|
|
|
<code>.dis65</code> on the end.
|
|
|
|
|
No part of the data file is included in the project file, so you need
|
|
|
|
|
to keep both files in the same place.
|
|
|
|
|
If the program you're disassembling was split into more than one data
|
2021-09-06 18:41:08 +00:00
|
|
|
file, you'll need a separate project file for each (or combine them into
|
|
|
|
|
a single file with the concatenation tool).</p>
|
2021-06-08 00:14:16 +00:00
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-image">
|
|
|
|
|
<img src="images/t1-fresh-install.png" alt="t1-fresh-install"/>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>To start a new project, launch SourceGen, and click on the
|
|
|
|
|
"Start New Project" button on
|
|
|
|
|
the initial screen, or use <samp>File > New</samp>. This opens the "New Project"
|
|
|
|
|
window, which lets you specify the target system and data file.</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-image">
|
|
|
|
|
<img src="images/t1-new-project.png" alt="t1-new-project"/>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>Choosing a target system, such as Apple //e or Commodore 64, will
|
|
|
|
|
create a project configured with the appropriate CPU and options.
|
|
|
|
|
If nothing in the list matches the file you want to work on,
|
|
|
|
|
there are "generic" entries for each
|
|
|
|
|
of the primary CPU varieties (6502, 65C02, W65C02, and 65816). If
|
|
|
|
|
you're unsure, just take your best guess. It's easy to change things after the
|
|
|
|
|
project has been started.</p>
|
2021-09-06 18:41:08 +00:00
|
|
|
<p>The area on the right side of the window has a list of the symbol
|
|
|
|
|
files, scripts, and optional features that will be enabled for the
|
2021-06-08 00:14:16 +00:00
|
|
|
selected system. The various items here will be explained in more
|
|
|
|
|
detail later on.</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-image">
|
|
|
|
|
<img src="images/t1-new-tutorial1.png" alt="t1-new-tutorial1"/>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>For this tutorial, we're going to use "<samp>Generic 6502</samp>",
|
|
|
|
|
near the bottom of the list.</p>
|
|
|
|
|
<p>The other thing we need to do here is select the data file to be
|
|
|
|
|
disassembled. Click <samp>Select File</samp>, navigate to the <samp>Examples</samp>
|
|
|
|
|
directory in the SourceGen installation directory, open <samp>Tutorial</samp>,
|
|
|
|
|
and select <samp>Tutorial1</samp>.
|
|
|
|
|
<p>Click <samp>OK</samp> to create the project.</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>The first thing you should do after creating a new project is save it.
|
|
|
|
|
Some features create or load files from the directory where the project
|
|
|
|
|
file lives, so we want to establish that. Use <samp>File > Save</samp>
|
|
|
|
|
or <kbd class="key">Ctrl+S</kbd> to save it, with the default name
|
|
|
|
|
(<kbd>Tutorial1.dis65</kbd>), in the directory where the data file lives.</p>
|
|
|
|
|
<p>(It's okay to create the project in the installation directory. You
|
|
|
|
|
don't need to work off of a copy of the data file; SourceGen doesn't modify
|
|
|
|
|
it, so you don't have to worry about trashing the example data.)</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-image">
|
|
|
|
|
<img src="images/t1-settings.png" alt="t1-settings"/>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>The disassembly display can be tailored to your personal
|
|
|
|
|
preferences. Use <samp>Edit > Settings</samp> to open the
|
|
|
|
|
settings editor. You can change fonts, upper/lower case, text
|
|
|
|
|
delimiters, line wrapping, pseudo-op names, and more. There
|
|
|
|
|
are "quick set" buttons on some screens that allow you to make the
|
|
|
|
|
output resemble various popular assemblers.</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="grid-container">
|
|
|
|
|
<div class="grid-item-text">
|
|
|
|
|
<p>All app settings are local to your system, and do not affect
|
|
|
|
|
the project in any way. If somebody else opens the same project,
|
|
|
|
|
they may see entirely different pseudo-ops and upper-case choices,
|
|
|
|
|
based on their own personal preferences.
|
|
|
|
|
(The settings that affect projects are accessed through a
|
|
|
|
|
different screen, via <samp>Edit > Project Properties</samp>.)</p>
|
|
|
|
|
|
|
|
|
|
<p>For now, you can leave everything set to default values.</p>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</div> <!-- #main -->
|
|
|
|
|
|
|
|
|
|
<div id="prevnext">
|
|
|
|
|
<a href="about-disasm.html" class="btn-previous">« Previous</a>
|
|
|
|
|
<a href="moving-around.html" class="btn-next">Next »</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- START: /incl-footer.html -->
|
2021-06-08 00:14:16 +00:00
|
|
|
<div id="footer">
|
2021-06-28 20:37:26 +00:00
|
|
|
<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> -->
|
2021-06-08 00:14:16 +00:00
|
|
|
</div>
|
2021-07-11 01:46:33 +00:00
|
|
|
<!-- END: /incl-footer.html -->
|
2021-06-08 00:14:16 +00:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
