6502/6502bench
1
0
Fork 0
mirror of https://github.com/fadden/6502bench.git synced 2024-12-01 22:50:35 +00:00
Code Issues Projects Releases Wiki Activity

Update reference manual formatting

Browse Source 
Switched from XHTML to HTML5.  Added formatting for menu items and
keyboard shortcuts.

Made various minor edits to the text.
This commit is contained in:
Andy McFadden 2021-10-18 17:56:08 -07:00
parent 55f0230e6f
commit 22c47e1d0b
15 changed files with 797 additions and 663 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
SourceGen/SGTestData/README.md
View File

@ -31,6 +31,21 @@ If the leading number is 20000 or greater, the test file will be loaded as
a saved project. A file with the same name plus a ".dis65" extension will
be opened as the project file.
### Overriding Settings ###
All tests are run with a fixed set of app settings, so that the tests look
the same regardless of how the assemblers are configured. For example,
upper-case conversion is disabled, and cycle counts are not shown.
Sometimes a test will want to exercise one of these settings, so we need
a way to tell the test harness to override the default. We do this by
creating project symbols.
| Name | Value | Description
| ---------------------- | ----- | -------------------------------------------|
| __ENABLE_LABEL_NEWLINE | any | Puts long labels on their own line |
| __ENABLE_CYCLE_COUNTS | any | Adds cycle count to end-of-line comments |
### Execution ###
With debug features enabled, you can open the test runner from the menu

68
docs/sgmanual/advanced.html
View File

@ -1,20 +1,21 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Advanced Topics - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Advanced Topics - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Advanced Topics</h1>
<h1>SourceGen: Advanced Topics</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="platform-symbols">Platform Symbol Files (.sym65)</a></h2>
<h2 id="platform-symbols">Platform Symbol Files (.sym65)</h2>
<p>Platform symbol files contain lists of symbols, each of which has a
label and a value. SourceGen comes with a collection of symbols for
@ -124,8 +125,8 @@ the symbol established for the masked value will be used instead.</p>
<p>If there are multiple masked values for a given address, the precedence
is undefined.</p>
<p>To disable the MULTI_MASK and resume normal declarations, write the
tag without arguments:
<pre> *MULTI_MASK</pre></p>
tag without arguments:</p>
<pre> *MULTI_MASK</pre>
<h3>Creating a Project-Specific Symbol File</h3>
@ -151,7 +152,7 @@ not detected automatically. Use File &gt; Reload External Files to
import the changes.</p>
<h2><a name="extension-scripts">Extension Scripts</a></h2>
<h2 id="extension-scripts">Extension Scripts</h2>
<p>Extension scripts, also called "plugins", are C# programs with access to
the full .NET Standard 2.0 APIs. They're compiled at run time by SourceGen
@ -212,7 +213,6 @@ $1234 InAZ_PrintString PLA
<li><code>InNR_</code> : non-returning call (i.e. the JSR acts like
a JMP)</li>
</ul>
</p>
<p>Anything more complicated will require a custom script.</p>
@ -298,7 +298,7 @@ circumstances change, so I'm using app domains as a way to keep the API
honest.</p>
<h2><a name="multi-bin">Working With Multiple Binaries</a></h2>
<h2 id="multi-bin">Working With Multiple Binaries</h2>
<p>Sometimes a program is split into multiple files on disk. They
may be all loaded at once, or some may be loaded into the same place
@ -320,7 +320,7 @@ once, so there's no reason to treat them as separate projects. Currently,
the best way to deal with this is to concatenate the files into a single
file, and operate on that.</p>
<h2><a name="overlap">Overlapping Address Spaces</a></h2>
<h2 id="overlap">Overlapping Address Spaces</h2>
<p>Some programs use memory overlays, where multiple parts of the
code run in the same address in RAM. Others use bank switching to access
parts of the program that reside in separate physical RAM or ROM,
@ -382,7 +382,7 @@ If we hit the top of the tree without finding a match, we conclude
that the reference is to an external address.</p>
<h2><a name="reloc-data">OMF Relocation Dictionaries</a></h2>
<h2 id="reloc-data">OMF Relocation Dictionaries</h2>
<p><i>This feature is considered experimental. Some features,
like cross-reference tracking, may not work correctly with it.</i></p>
@ -406,14 +406,14 @@ Without context, the disassembler will treat the PEA instruction as two
independent 16-bit addresses, and the immediate values as constants:</p>
<pre>
.dbank $02
02/317c: f4 02 00 L2317C pea L20002 & $ffff
02/317f: f4 54 32 pea L23254 & $ffff
02/317c: f4 02 00 L2317C pea L20002 &amp; $ffff
02/317f: f4 54 32 pea L23254 &amp; $ffff
02/3182: a2 0c 20 ldx #WriteCString
02/3185: 22 00 00 e1 jsl Toolbox
02/3189: a9 00 00 L23189 lda #$0000
02/318c: 8d 78 3f sta L23F78 & $ffff
02/318c: 8d 78 3f sta L23F78 &amp; $ffff
02/318f: a9 03 00 lda #$0003
02/3192: 8d 7a 3f sta L23F78 & $ffff +2
02/3192: 8d 7a 3f sta L23F78 &amp; $ffff +2
</pre>
<p>Worse yet, those <code>STA</code> instruction operands would have been
shown as hex values or incorrect labels if the DBR had been set incorrectly.
@ -422,14 +422,14 @@ address from which the addresses were formed, and we can tell when
immediate values are addresses rather than constants. And we can do this
even without setting the DBR.</p>
<pre>
02/317c: f4 02 00 L2317C pea L23254 >> 16
02/317f: f4 54 32 pea L23254 & $ffff
02/317c: f4 02 00 L2317C pea L23254 &gt;&gt; 16
02/317f: f4 54 32 pea L23254 &amp; $ffff
02/3182: a2 0c 20 ldx #WriteCString
02/3185: 22 00 00 e1 jsl Toolbox
02/3189: a9 00 00 L23189 lda #L30000 & $ffff
02/318c: 8d 78 3f sta L23F78 & $ffff
02/318f: a9 03 00 lda #L30000 >> 16
02/3192: 8d 7a 3f sta L23F78 & $ffff +2
02/3189: a9 00 00 L23189 lda #L30000 &amp; $ffff
02/318c: 8d 78 3f sta L23F78 &amp; $ffff
02/318f: a9 03 00 lda #L30000 &gt;&gt; 16
02/3192: 8d 7a 3f sta L23F78 &amp; $ffff +2
</pre>
<p>The absence of relocation data can be a useful signal as well. For
example, when pushing arguments for a toolbox call, the disassembler
@ -449,10 +449,10 @@ relocated. Consider this bit of source code:</p>
<pre>
02/0aa8: a5 42 lda $42
02/0aaa: 48 pha
02/0aab: f4 02 00 pea L20002 & $ffff
02/0aae: f4 03 31 pea L23103 & $ffff
02/0ab1: f4 05 00 pea L20005 & $ffff
02/0ab4: f4 00 00 pea L20000 & $ffff
02/0aab: f4 02 00 pea L20002 &amp; $ffff
02/0aae: f4 03 31 pea L23103 &amp; $ffff
02/0ab1: f4 05 00 pea L20005 &amp; $ffff
02/0ab4: f4 00 00 pea L20000 &amp; $ffff
02/0ab7: a2 0b 26 ldx #Int2Dec
02/0aba: 22 00 00 e1 jsl Toolbox
</pre>
@ -460,8 +460,8 @@ relocated. Consider this bit of source code:</p>
<pre>
02/0aa8: a5 42 lda $42
02/0aaa: 48 pha
02/0aab: f4 02 00 pea L230C2 >> 16
02/0aae: f4 03 31 pea L23103 & $ffff
02/0aab: f4 02 00 pea L230C2 &gt;&gt; 16
02/0aae: f4 03 31 pea L23103 &amp; $ffff
02/0ab1: f4 05 00 pea $0005
02/0ab4: f4 00 00 pea $0000
02/0ab7: a2 0b 26 ldx #Int2Dec
@ -469,7 +469,7 @@ relocated. Consider this bit of source code:</p>
</pre>
<h2><a name="debug">Debug Menu Options</a></h2>
<h2 id="debug">Debug Menu Options</h2>
<p>The DEBUG menu is hidden by default in release builds, but can be
exposed by checking the "enable DEBUG menu" box in the application
@ -478,8 +478,8 @@ not help you debug 6502 projects.</p>
<p>Features:</p>
<ul>
<li>Re-analyze (F5). Causes a full re-analysis. Useful if you think
the display is out of sync.</li>
<li>Re-analyze (<kbd class="key">F5</kbd>). Causes a full re-analysis.
Useful if you think the display is out of sync.</li>
<li>Source Generation Tests. Opens the regression test harness. See
<code>README.md</code> in the SGTestData directory for more information.
If the regression tests weren't included in the SourceGen distribution,

33
docs/sgmanual/analysis.html
View File

@ -1,22 +1,23 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Instruction and Data Analysis - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Instruction and Data Analysis - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Instruction and Data Analysis</h1>
<h1>SourceGen: Instruction and Data Analysis</h1>
<p><a href="index.html">Back to index</a></p>
<p><i>This section discusses the internal workings of SourceGen. It is
not necessary to understand this to use the program.</i></p>
<h2><a name="analysis-process">Analysis Process</a></h2>
<h2 id="analysis-process">Analysis Process</h2>
<p>Analysis of the file data is a complex multi-step process. Some
changes to the project, such as adding a code start point or
@ -87,7 +88,7 @@ many lines it will occupy, so it's done immediately and cached for re-use
on subsequent runs.</p>
<h3><a name="auto-format">Automatic Formatting</a></h3>
<h3 id="auto-format">Automatic Formatting</h3>
<p>Every offset in the file is marked as an instruction byte, data byte, or
inline data byte. Some offsets are also marked as the start of an instruction
@ -142,7 +143,7 @@ to the user-specified descriptor list. During the analysis pass it would
be added to the Anattrib array at offset +000000.</p>
<h3><a name="undo-redo">Interaction With Undo/Redo</a></h3>
<h3 id="undo-redo">Interaction With Undo/Redo</h3>
<p>The analysis pass always considers the current state of the user
data structures. Whether you're adding a label or removing one, the
@ -189,7 +190,7 @@ add up quickly). When undoing a change, before and after are simply
reversed.</p>
<h2><a name="code-analysis">Code Analysis</a></h2>
<h2 id="code-analysis">Code Analysis</h2>
<p>The code tracer walks through the instructions, examining them to
determine where execution will proceed next. There are five possibilities
@ -282,7 +283,7 @@ assumes that it's equal to the program bank register ("K"), and provides
a way to override the value.</p>
<h3><a name="extension-scripts">Extension Scripts</a></h3>
<h3 id="extension-scripts">Extension Scripts</h3>
<p>Extension scripts can mark data that follows a JSR, JSL, or BRK as inline
data, or change the format of nearby data or instructions. The first
@ -303,7 +304,7 @@ with inline data tags specified by the user, because those are applied
before code analysis starts.)</p>
<h2><a name="data-analysis">Data Analysis</a></h2>
<h2 id="data-analysis">Data Analysis</h2>
<p>The data analyzer performs two tasks. It matches operands with
offsets, and it analyzes uncategorized data. This behavior can be
modified in the
@ -321,9 +322,9 @@ the instruction start. This is necessary because labels are only visible
if they're associated with the first (opcode) byte of an instruction.</p>
<p>The uncategorized data analyzer tries to find character strings and
opportunities to use the ".FILL" operation. It breaks the file into
pieces, where contiguous regions hold nothing but data, are not split
across address region start/end directives, are not interrupted by data,
opportunities to use the "<code>.FILL</code>" operation. It breaks the file
into pieces where contiguous regions hold nothing but data, are not split
across address region start/end directives, are not interrupted by labels,
and do not contain anything that the user has chosen to format. Each
region is scanned for matching patterns. If a match is found, a format entry
is added to the Anattrib array. Otherwise, data is added as single-byte

120
docs/sgmanual/codegen.html
View File

@ -1,32 +1,35 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Code Generation &amp; Assembly - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Code Generation &amp; Assembly - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Code Generation &amp; Assembly</h1>
<h1>SourceGen: Code Generation &amp; Assembly</h1>
<p><a href="index.html">Back to index</a></p>
<p>SourceGen can generate an assembly source file that, when fed into
the target assembler, will recreate the original data file exactly.
Every assembler is different, so support must be added to SourceGen
for each.</p>
<p>The generation / assembly dialog can be opened with File &gt; Assemble.</p>
<p>The generation / assembly dialog can be opened with
<samp>File &gt; Assemble</samp>.</p>
<p>If you want to show code to others, perhaps by adding a page to
your web site, you can "export" the formatted code as text or HTML.
This is explained in more detail <a href="#export-source">below</a>.
<h2><a name="generate">Generating Source Code</a></h2>
<h2 id="generate">Generating Source Code</h2>
<p>Cross assemblers tend to generate additional files, either compiler
intermediaries ("file.o") or metadata ("_FileInformation.txt"). Some
intermediaries ("<samp>file.o</samp>") or metadata
("<samp>_FileInformation.txt</samp>"). Some
generators may produce multiple source files, perhaps a link script or
symbol definition header to go with the assembly source. To avoid
spreading files across the filesystem, SourceGen does all of its work
@ -34,14 +37,15 @@ in the same directory where the project lives. Before you can generate
code, you have to have assigned your project a directory. This is why
you can't assemble a project until you've saved it for the first time.</p>
<p>The Generate and Assemble dialog has a drop-down list near the top
that lets you pick which assembler to target. The name of the assembler
will be shown with the detected version number. If the assembler
executable isn't configured, "[latest version]" will be shown instead
of a version number.</p>
<p>The Settings button will take you directly to the assembler configuration
tab in the application settings dialog.</p>
<p>Hit the Generate button to generate the source code into a file on disk.
<p>The <samp>Generate and Assemble</samp> dialog has a drop-down list near
the top that lets you pick which assembler to target. The name of the
assembler will be shown with the detected version number. If the assembler
executable isn't configured, "<samp>[latest version]</samp>" will be
shown instead of a version number.</p>
<p>The <samp>Settings</samp> button will take you directly to the
assembler configuration tab in the application settings dialog.</p>
<p>Hit the <samp>Generate</samp> button to generate the source code into
a file on disk.
The file will use the project name, with the <code>.dis65</code> extension
replaced by <code>_&lt;assembler&gt;.S</code>.</p>
<p>The first 64KiB of each generated file will be shown in the preview
@ -51,26 +55,27 @@ prepended to each line to make it easier to track down errors.</p>
<h3><a name="localizer">Label Localizer</a></h3>
<h3 id="localizer">Label Localizer</h3>
<p>The label localizer is an optional feature that automatically converts
some labels to an assembler-specific less-than-global label format. Local
labels may be reusable (e.g. using "]LOOP" for multiple consecutive
loops is easier to understand than giving each one a unique label) or
reduce the size of a generated link table. There are usually restrictions
on local labels, e.g. references to them may not be allowed to cross a
global label definition, which the localizer factors in automatically.</p>
labels may be reusable (e.g. using "<code>@LOOP</code>" for multiple
consecutive loops is easier to understand than giving each one a unique
label) or reduce the size of a generated link table. There are usually
restrictions on local labels, e.g. references to them may not be allowed
to cross a global label definition, which the localizer factors in
automatically.</p>
<h3><a name="reserved-labels">Reserved Label Names</a></h3>
<h3 id="reserved-labels">Reserved Label Names</h3>
<p>Some label names aren't allowed. For example, 64tass reserves the
use of labels that begin with two underscores. Most assemblers will
also prevent you from using opcode mnemonics as labels (which means
you can't assemble <code>jmp jmp jmp</code>).</p>
you can't assemble the infinite loop <code>jmp jmp jmp</code>).</p>
<p>If a label doesn't appear to be legal, the generated code will use
a suitable replacement (e.g. <code>jmp_1 jmp jmp_1</code>).</p>
<h3><a name="platform-features">Platform-Specific Features</a></h3>
<h3 id="platform-features">Platform-Specific Features</h3>
<p>SourceGen needs to be able to assemble binaries for any system
with any assembler, so it generally avoids platform-specific features.
One exception to that is C64 PRG files.</p>
@ -98,16 +103,16 @@ can add a label or reformat the bytes. This feature is currently only
enabled for 64tass.</p>
<h2><a name="assemble">Cross-Assembling Generated Code</a></h2>
<h2 id="assemble">Cross-Assembling Generated Code</h2>
<p>After generating sources, if you have a cross-assembler executable
configured, you can run it by clicking the "Run Assembler" button. The
command-line output will be displayed, with stdout and stderr separated.
configured, you can run it by clicking the <samp>Run Assembler</samp> button.
The command-line output will be displayed, with stdout and stderr separated.
(I'd prefer them to be interleaved, but that's not what the system
provides.)</p>
<p>The output will show the assembler's exit code, which will be zero
on success (note: sometimes they lie.) If it appeared to succeed,
on success (note: sometimes they lie). If it appeared to succeed,
SourceGen will then compare the assembler's output to the original file,
and report any differences.</p>
<p>Failures here may be due to bugs in the cross-assembler or in
@ -115,7 +120,7 @@ SourceGen. However, SourceGen can generally work around assembler bugs,
so any failure is an opportunity for improvement.</p>
<h2><a name="supported">Supported Assemblers</a></h2>
<h2 id="supported">Supported Assemblers</h2>
<p>SourceGen currently supports the following cross-assemblers:</p>
<ul>
@ -125,7 +130,7 @@ so any failure is an opportunity for improvement.</p>
<li><a href="#merlin32">Merlin 32</a></li>
</ul>
<h3><a name="version">Version-Specific Code Generation</a></h3>
<h3 id="version">Version-Specific Code Generation</h3>
<p>Code generation must be tailored to the specific version of the
assembler. This is most easily understood with an example.</p>
@ -141,15 +146,16 @@ be generated for all versions of the assembler by just outputting raw hex
bytes, but that's ugly and annoying, so we don't want to be stuck doing
that forever. We want to detect which version of the assembler is in
use, and output actual <code>MVN</code>/<code>MVP</code> instructions
when producing code for newer versions of the assembler.</p>
when producing code for versions of the assembler that don't have the bug.</p>
<p>When you configure a cross-assembler, SourceGen runs the executable with
version query args, and extracts the version information from the output
stream. This is used by the generator to ensure that the output will compile.
If no assembler is configured, SourceGen will produce code optimized
for the latest version of the assembler.</p>
version query arguments, and extracts the version information from the output
stream. This is used by the generator to ensure that the output will work
correctly with the installed assembler.
If the assembler is present on the system, SourceGen will produce code
optimized for the latest supported version of the assembler.</p>
<h3><a name="quirks">Assembler-Specific Bugs &amp; Quirks</a></h3>
<h3 id="quirks">Assembler-Specific Bugs &amp; Quirks</h3>
<p>This is a list of bugs and quirky behavior in cross-assemblers that
SourceGen works around when generating code.</p>
@ -163,8 +169,21 @@ to halt with an error message. The code generator needs
to understand expression syntax and operator precedence to generate correct
code, but also needs to know how to handle the corner cases.</p>
<h4>Undocumented Opcodes</h4>
<h3><a name="64tass">64tass</a></h3>
<p>The data sheet for the 6502 does not define all 256 possible opcodes.
Analysis and experimentation have found that many of these "undocumented"
operations actually do useful things. The people who did the research
didn't always use the same mnemonic names for them, which led to a bit
of confusion in assemblers.</p>
<p>The most authoritative source is
<a href="https://csdb.dk/release/download.php?id=229739"><i>NMOS 6510 Unintended Opcodes</i> (PDF)</a>.
The document defines a primary mnemonic and lists common aliases for
each operation. SourceGen will output the primary mnemonic unless the
target assembler doesn't handle it.</p>
<h3 id="64tass">64tass</h3>
<p>Tested versions: v1.53.1515, v1.54.1900, v1.55.2176, v1.56.2625
<a href="https://sourceforge.net/projects/tass64/">[web site]</a></p>
@ -199,9 +218,9 @@ code, but also needs to know how to handle the corner cases.</p>
character ('`') rather than the caret ('^'). (There's a note in the
docs to the effect that they plan to move to carets.)</li>
<li>Instructions whose argument is formed by combining with the
65816 Program Bank Register (16-bit JMP/JSR) must be specified
as 24-bit values for code that lives outside bank 0. This is
true for both symbols and raw hex (e.g. <code>JSR $1234</code>
65816 Program Bank Register (16-bit <code>JMP</code>/<code>JSR</code>)
must be specified as 24-bit values for code that lives outside bank 0.
This is true for both symbols and raw hex (e.g. <code>JSR $1234</code>
is invalid outside bank 0). Attempting to JSR to a label in bank
0 from outside bank 0 causes an error, even though it is technically
a 16-bit operand.</li>
@ -218,7 +237,7 @@ code, but also needs to know how to handle the corner cases.</p>
</ul>
<h3><a name="acme">ACME</a></h3>
<h3 id="acme">ACME</h3>
<p>Tested versions: v0.96.4, v0.97
<a href="https://sourceforge.net/projects/acme-crossass/">[web site]</a></p>
@ -229,7 +248,7 @@ code, but also needs to know how to handle the corner cases.</p>
outside bank zero cannot be assembled. SourceGen currently deals with
this by outputting the entire file as a hex dump.</li>
<li>Undocumented opcode $AB (<code>LAX #imm</code>) generates an error.</li>
<li>BRK and WDM are not allowed to have operands.</li>
<li>BRK is not allowed to have an operand.</li>
</ul>
<p>Quirks:</p>
@ -262,7 +281,7 @@ code, but also needs to know how to handle the corner cases.</p>
</ul>
<h3><a name="cc65">cc65</a></h3>
<h3 id="cc65">cc65</h3>
<p>Tested versions: v2.17, v2.18
<a href="https://cc65.github.io/">[web site]</a></p>
@ -286,8 +305,9 @@ code, but also needs to know how to handle the corner cases.</p>
more common interpretation would be <code>label &gt;&gt; (8 - 16)</code>.
(This is actually somewhat convenient, since none of the expressions
SourceGen currently generates require parenthesis.)</li>
<li>Undocumented opcode <code>SBX</code> ($cb) uses the mnemonic AXS. All
other opcodes match up with the "unintended opcodes" document.</li>
<li>Undocumented opcode <code>SBX</code> ($cb) uses the mnemonic
<code>AXS</code>. All other opcodes match up with the
"unintended opcodes" document.</li>
<li>ca65 is implemented as a single-pass assembler, so label widths
can't always be known in time. For example, if you use some zero-page
labels, but they're defined via <code>.ORG $0000</code> after the point
@ -304,7 +324,7 @@ code, but also needs to know how to handle the corner cases.</p>
</ul>
<h3><a name="merlin32">Merlin 32</a></h3>
<h3 id="merlin32">Merlin 32</h3>
<p>Tested Versions: v1.0
<a href="https://www.brutaldeluxe.fr/products/crossdevtools/merlin/">[web site]</a>
@ -353,7 +373,7 @@ code, but also needs to know how to handle the corner cases.</p>
<h2><a name="export-source">Exporting Source Code</a></h2>
<h2 id="export-source">Exporting Source Code</h2>
<p>The "export" function takes what you see in the code list in the app
and converts it to text or HTML. The options you've set in the app
settings, such as capitalization, text delimiters, pseudo-opcode names,

140
docs/sgmanual/editors.html
View File

@ -1,20 +1,21 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Editors - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Editors - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Editors</h1>
<h1>SourceGen: Editors</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="address">Define Address Region</a></h2>
<h2 id="address">Define Address Region</h2>
<p><a href="intro-details.html#address-regions">Address regions</a>
may be created, edited, resized, or removed. Which
@ -83,11 +84,11 @@ opening the editor.</p>
<p>To see detailed information about an address region in the "Info"
window, select the region start or end directive. You can see the
current arrangement of address regions across your entire
project with Navigate &gt; View Address Map.</p>
project with <samp>Navigate &gt; View Address Map</samp>.</p>
<h2><a name="flags">Override Status Flags</a></h2>
<h2 id="flags">Override Status Flags</h2>
<p>The state of the processor status flags are tracked for every
instruction. Each individual flag is recorded as zero, one, or
@ -99,7 +100,7 @@ register, may also be set in the editor.</p>
is set to 65816.</p>
<h2><a name="label">Edit Label</a></h2>
<h2 id="label">Edit Label</h2>
<p>Sets or clears a label at the selected offset. The label must have the
<a href="intro-details.html#about-symbols">proper form</a>, and not have the same
name as another symbol, unless it's specified to be non-unique. If you
@ -119,14 +120,14 @@ be imported by other projects (see
<a href="advanced.html#multi-bin">Working With Multiple Binaries</a>).</p>
<h2><a name="instruction-operand">Edit Operand (Instruction)</a></h2>
<h2 id="instruction-operand">Edit Operand (Instruction)</h2>
<p>Operands can be formatted explicitly, or you can let the disassembler
select the format for you. By default, immediate constants and
addresses with no matching symbol are formatted as hex. Symbols
defined as address labels, platform/project symbols, and local
variables will be identified and applied automatically.</p>
<h3><a name="explicit-format">Explicit Formats</a></h3>
<h3 id="explicit-format">Explicit Formats</h3>
<p>Operands can be displayed in a variety of numeric formats, or as a
symbol. The character formats are only available for operands
whose value falls into the proper range. The ASCII format handles
@ -162,13 +163,14 @@ branch instructions.</p>
<p>The bottom part of the window has some shortcuts for working with
address references and local variables. These are primarily used to
change the way things work when "Default" is selected. The shortcuts
change the way things work when the <samp>Default</samp> format option
is selected. The shortcuts
don't cause any changes to the recorded format of the instruction
being edited. All of the actions can be performed elsewhere, by
editing the label at the target address, editing the project symbol
set, or editing a local variable table.</p>
<h3><a name="shortcut-nar">Numeric Address References</a></h3>
<h3 id="shortcut-nar">Numeric Address References</h3>
<p>For operands that are 8-bit, 16-bit, or 24-bit addresses, you can
define a symbol for the address as a label or
@ -187,9 +189,10 @@ in the editor.</p>
address or I/O location, you can define a project symbol. If a
match was found in the configured platform definition files, it will be
shown; it can't be edited, but it can be overridden by a project symbol.
You can create or modify a project symbol by clicking on "Create Project
Symbol" or "Edit Project Symbol". You can't delete project symbols
from this editor (use Project Properties instead).</p>
You can create or modify a project symbol by clicking on
<samp>Create Project Symbol</samp> or <samp>Edit Project Symbol</samp>.
You can't delete project symbols
from this editor (use the Project Properties editor instead).</p>
<p>It's possible to have more than one project symbol for the same
address. For example, on the Apple II, reading from the memory-mapped
@ -199,24 +202,26 @@ have two different names for it. If more than one project symbol has the
same address, the first one found will be used, which may not be
what is desired. In such situations, you should create the project
symbol and then copy the symbol name into the operand. You can do this
in one step by clicking the "Copy to Operand" button.
in one step by clicking the <samp>Copy to Operand</samp> button.
(In most cases you don't want to do this, because if the project
symbol is deleted or renamed, you'll have operands that refer to a
nonexistent symbol. Unlike labels, project symbol renames do not
refactor the rest of the project.)
<h3><a name="shortcut-local-var">Local Variable References</a></h3>
<h3 id="shortcut-local-var">Local Variable References</h3>
<p>For zero-page address operands and (65816-only) stack-relative
constant operands, a local variable can be created or modified. This
constant operands, a
<a href="intro-details.html#local-vars">local variable</a>
can be created or modified. This
requires that a local variable table has been defined at or before
the instruction being edited.</p>
<p>If an existing entry is found, you will be able to edit the name
and comment fields. If not, a new entry with a generic name and
pre-filled value field will be created in the nearest table.</p>
pre-filled value field will be prepared in the nearest prior table.</p>
<h2><a name="data-operand">Edit Operand (Data)</a></h2>
<h2 id="data-operand">Edit Operand (Data)</h2>
<p>This dialog offers a variety of choices, and can be used to apply a
format to multiple lines. You must select all of the bytes you want
@ -234,46 +239,48 @@ many regions they have been divided into.</p>
<p>(End-of-line comments do <i>not</i> split a region, and will
disappear if they end up inside a multi-byte data item.)</p>
<p>The "Simple Data" items behave the same as their equivalents in the
Edit Operand dialog. However, because the width is not determined by
an instruction opcode, and multiple items can be selected, you will need
to specify how wide each item is and what its byte order is. For data
you also have the option of setting the format to "Address", which marks
the selected bytes as a numeric reference.</p>
<p>The <samp>Simple Data</samp> items behave the same as their equivalents
in the Edit Operand (Instruction) dialog. However, because the width is
not determined by an instruction opcode, and multiple items can be selected,
you will need to specify how wide each item is and what its byte order is.
For data you also have the option of setting the format to
<samp>Address</samp>, which marks the selected bytes as a
numeric reference.</p>
<p>Consider a simple example: suppose you find a table of 16-bit
addresses in the code. Click on
the first byte, shift-click the last byte, then select the Edit Data menu
item. The number of bytes selected should be even. Select
"16-bit words, little-endian", then over to the right click on
"Address". When you click OK, the selected data will be formatted as a
series of 16-bit address values. If the addresses can be resolved inside
the data file, each address will be assigned a label.</p>
<samp>16-bit words, little-endian</samp>, then over to the right click on
<samp>Address</samp>. When you click <samp>OK</samp>, the selected data
will be formatted as a series of 16-bit address values. If the addresses
can be resolved inside the data file, each address will be assigned
an automatically-generated label.</p>
<p>The "Bulk Data" items can represent large chunks of data compactly.
The "fill" option is only available if all selected bytes have the
same value.</p>
<p>The <samp>Bulk Data</samp> items can represent large chunks of data
compactly. The <samp>Fill</samp> option is only available if all selected
bytes have the same value.</p>
<p>If a region of bytes is used for data storage, but the initial values
don't matter, you can mark it as "uninitialized data". (The code
generated will usually use an initialized bulk data directive rather
than a "leave space" directive, because SourceGen wants to guarantee
that the assembled binary matches the original.)</p>
don't matter, you can mark it as <samp>Uninitialized data</samp>.
(Note that the code generated will usually use an initialized bulk data
directive rather than a "leave space" directive, because SourceGen wants
to guarantee that the assembled binary matches the original.)</p>
<p>If a region of bytes is irrelevant, e.g. dead code or padding,
you can mark it as "junk". If it appears to be adding bytes to reach a
power-of-two address boundary, you can designate it as an alignment
directive. If you have multiple regions selected, only options that
work for all regions will be shown.</p>
you can mark it as <samp>Junk</samp>. If it appears to be adding bytes
to reach a power-of-two address boundary, you can designate it as an alignment
directive. If you have multiple regions selected, only the alignment
options that work for all regions will be shown.</p>
<p>The "String" items are enabled or disabled depending on whether the
data you have selected is in the appropriate format. For example,
"Null-terminated strings" is only enabled if the data regions are
<p>The <samp>String</samp> items are enabled or disabled depending on
whether the data you have selected is in the appropriate format. For example,
<samp>Null-terminated strings</samp> is only enabled if the data regions are
composed entirely of characters followed by $00. Zero-length strings
are allowed.
DCI (Dextral Character Inverted) strings have the high bit on the last
byte flipped; for PETSCII this will usually look like a series of
lower-case letters followed by a capital letter, but may look odd if the
last character is punctuation (e.g. '!' becomes $A1, which is a
rectangle character that SourceGen will only display as hex).</p>
rectangle glyph that will be displayed as a hex value).</p>
<p>The character encoding can be selected, offering a choice between
plain ASCII, low + high ASCII, C64 PETSCII, and C64 screen codes. When
you change the encoding, your available options may change. The
@ -317,7 +324,7 @@ CODE LDA LABEL+2
<p>With the label out of the way, the data can be formatted as desired.</p>
<h2><a name="comment">Edit Comment</a></h2>
<h2 id="comment">Edit Comment</h2>
<p>Enter an end-of-line (EOL) comment, or leave the text field blank to
delete it. EOL comments may be placed on instruction and data lines, but
not on assembler directives.</p>
@ -339,7 +346,7 @@ stored in the project file, and can be edited with the project symbol
editor.</p>
<h2><a name="long-comment">Edit Long Comment</a></h2>
<h2 id="long-comment">Edit Long Comment</h2>
<p>Long comments can be arbitrarily long and span multiple lines. They
will be word-wrapped at a line width of your choosing. They're always
drawn with a fixed-width font, so you can create ASCII-art diagrams.
@ -360,13 +367,14 @@ the length of the line, not just the comment text, an asterisk-boxed
comment will have one fewer character per line in cc65 output.</p>
<p>Clear the text field to delete the comment.</p>
<p>You can use Ctrl+Enter as a keyboard shortcut for "OK".</p>
<p>You can use <kbd class="key">Ctrl+Enter</kbd> as a keyboard shortcut
for <samp>OK</samp>.</p>
<p>The long comment at the very top of the project is special, as it's
not associated with a file offset. If you delete it, you can get it
back by using Edit &gt; Edit Header Comment.</p>
back by using <samp>Edit &gt; Edit Header Comment</samp>.</p>
<h2><a name="data-bank">Edit Data Bank (65816 only)</a></h2>
<h2 id="data-bank">Edit Data Bank (65816 only)</h2>
<p>Sets the Data Bank Register (DBR) value for 65816 code. This is used
when matching 16-bit address operands with labels. The new value is
@ -389,7 +397,7 @@ instructions, double-clicking on a <code>PLB</code> opcode in the
code list will open the editor.</p>
<h2><a name="note">Edit Note</a></h2>
<h2 id="note">Edit Note</h2>
<p>Notes are similar to long comments, in that they can be arbitrarily
long and span multiple lines. However, because they're never included
in generated output, options like line width formatting and boxing
@ -407,10 +415,11 @@ also simply type a color name like "violet" so long as it appears in the
<a href="https://docs.microsoft.com/en-us/dotnet/media/art-color-table.png?view=netframework-4.8">list of Microsoft .NET colors</a>.</p>
<p>Clear the text field to delete the note.</p>
<p>You can use Ctrl+Enter as a keyboard shortcut for "OK".</p>
<p>You can use <kbd class="key">Ctrl+Enter</kbd> as a keyboard shortcut
for <samp>OK</samp>.</p>
<h2><a name="project-symbol">Edit Project Symbol</a></h2>
<h2 id="project-symbol">Edit Project Symbol</h2>
<p>This is used to edit the properties of a project symbol.</p>
<p>Symbols marked as "address" will be applied automatically when an
operand references an address outside the scope of the data file. They
@ -423,7 +432,7 @@ not have the same name as another project symbol. It can overlap
with platform symbols and user labels.</p>
<p>The value may be entered in decimal, hexadecimal, or binary. The numeric
base you choose will be remembered, so that the value will be displayed
the same way when used in a .EQ directive.</p>
the same way when used in a <code>.EQ</code> directive.</p>
<p>You can optionally provide a width for address symbols. For example,
if the address is of a two-byte pointer or a 64-byte buffer, you would
set the width field to cause all references to any location in that range
@ -431,26 +440,27 @@ to be set to the symbol. Widths may be entered in hex or decimal. If
the field is left blank, a width of 1 is assumed. Overlapping symbols
are allowed. The width is ignored for constants.</p>
<p>If you enter a comment, it will be placed at the end of the line of
the .EQ directive.</p>
the <code>.EQ</code> directive.</p>
<p>For address symbols that represent a memory-mapped I/O location, it
can be useful to have different symbols for reads and writes. Use
the Read/Write checkboxes to specify the desired behavior.</p>
the <samp>Read</samp>/<samp>Write</samp> checkboxes to specify the
desired behavior.</p>
<h2><a name="lvtable">Create/Edit Local Variable Table</a></h2>
<h2 id="lvtable">Create/Edit Local Variable Table</h2>
<p><a href="intro-details.html#local-vars">Local variables</a> are arranged in
tables, which are created at a specific file offset. They must be
associated with a line of code, and are usually placed at the start of
a subroutine.
The "Create Local Variable Table" action creates a new table, and
opens the editor. The "Edit Prior Local Variable Table" searches
The <samp>Create Local Variable Table</samp> action creates a new table, and
opens the editor. The <samp>Edit Prior Local Variable Table</samp> searches
for the closest table that appears at or before the selected line,
and edits that.</p>
<p>The editor allows you to create, edit, and delete entries, as well
as move and delete entire tables (though these last two options are not
available when creating a new table). Empty tables are allowed. These
can be useful if the "clear previous" flag is set. If you want to
delete the table, click the "Delete Table" button.</p>
delete the table, click the <samp>Delete Table</samp> button.</p>
<p>Use the buttons to add, edit, or remove individual variables. Each
variable has a name, a value, a width, and an optional comment. The
standard naming rules for symbols apply. Variables are only used for
@ -459,8 +469,8 @@ range 0-255. The width may extend one byte past the end (to address $0100)
to allow 16-bit accesses to $ff (particularly useful on 65816).</p>
<p>You can move a table to any offset that is the start of an instruction
and doesn't already have a local variable table present. Click the
"Move Table" button and enter the new offset in hex. You can also click
on the up/down buttons to move to the next valid offset.</p>
<samp>Move Table</samp> button and enter the new offset in hex. You can
also click on the up/down buttons to move to the next valid offset.</p>
</div>

19
docs/sgmanual/end-notes.html
View File

@ -1,19 +1,20 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>End notes - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>End notes - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: End Notes</h1>
<h1>SourceGen: End Notes</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="origins">Origins</a></h2>
<h2 id="origins">Origins</h2>
<p>The inspiration for SourceGen goes a long way back. While in high
school in the late 1980s, I read Don Lancaster's
<i>Enhancing Your Apple II, Vol. 1</i> (available for download
@ -22,7 +23,7 @@ included a very detailed methodology for disassembling 6502 software
(nicely reformatted
<a href="https://www.tinaja.com/ebooks/tearing_rework.pdf">here</a>).
I wanted to give it a try, so I generated a monitor listing of an
operating system (called "RDOS") that SSI used on their games, and
operating system called "RDOS" that SSI used on their games, and
printed it out on my Epson RX-80 -- tractor feed paper was helpful for
this sort of thing -- then set to work.</p>

21
docs/sgmanual/index.html
View File

@ -1,11 +1,12 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Contents - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Contents - 6502bench SourceGen</title>
</head>
<body>
@ -32,7 +33,7 @@ using the <samp>Help &gt; Help</samp> menu item or by hitting
<ul>
<li><a href="intro.html">Overview</a>
<ul>
<li><a href="intro.html#fundamental-concepts">Fundamentals</a></li>
<li><a href="intro.html#fundamental-concepts">Fundamentals</a>
<ul>
<li><a href="intro.html#begin">About 6502 Code</a>
<li><a href="intro.html#charenc">Character Encoding</a></li>
@ -93,7 +94,7 @@ using the <samp>Help &gt; Help</samp> menu item or by hitting
<li><a href="editors.html">Editors</a>
<ul>
<li><a href="editors.html#address">Define Address Region<a></li>
<li><a href="editors.html#address">Define Address Region</a></li>
<li><a href="editors.html#flags">Override Status Flags</a></li>
<li><a href="editors.html#label">Edit Label</a></li>
<li><a href="editors.html#instruction-operand">Edit Operand (Instruction)</a>
@ -199,9 +200,7 @@ using the <samp>Help &gt; Help</samp> menu item or by hitting
<li><a href="analysis.html#data-analysis">Data Analysis</a></li>
</ul></li>
<li><a href="end-notes.html">End Notes</a> </li>
<br/>
<li><a href="end-notes.html">End Notes</a></li>
<!--
<li><a href="tutorials.html">Tutorials</a>

264
docs/sgmanual/intro-details.html
View File

@ -1,25 +1,26 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>More Details - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>More Details - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Intro Details</h1>
<h1>SourceGen: More Details</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="more-details">More Details</a></h2>
<h2 id="more-details">Intro, Continued</h2>
<p>This section digs a little deeper into how SourceGen works.</p>
<p>This section of the manual digs a little deeper into how SourceGen works.</p>
<h2><a name="about-symbols">All About Symbols</a></h2>
<h2 id="about-symbols">All About Symbols</h2>
<p>A symbol has two essential parts, a label and a value. The label is a short
ASCII string; the value may be an 8-to-24-bit address or a 32-bit numeric
@ -62,7 +63,7 @@ differently from those outside a project. We refer to these as internal
and external addresses, respectively.</p>
<h3><a name="connecting-operands">Connecting Operands with Labels</a></h3>
<h3 id="connecting-operands">Connecting Operands with Labels</h3>
<p>Suppose you have the following code:</p>
<pre>
@ -91,7 +92,7 @@ set arbitrarily. Sometimes it's easy to figure out, sometimes it has
to be specified manually.</p>
<h3><a name="internal-address-symbols">Internal Address Symbols</a></h3>
<h3 id="internal-address-symbols">Internal Address Symbols</h3>
<p>Symbols that represent an address inside the file being disassembled
are referred to as <i>internal</i>. They come in two varieties.</p>
@ -116,7 +117,7 @@ editor will try to prevent you from referring to them explicitly when
editing operands.</p>
<h3><a name="external-address-symbols">External Address Symbols</a></h3>
<h3 id="external-address-symbols">External Address Symbols</h3>
<p>Symbols that represent an address outside the file being disassembled
are referred to as <i>external</i>. These may be ROM entry points,
@ -182,7 +183,7 @@ and 65816 stack-relative instructions. These are explained in more
detail in the next section.</p>
<h4><a name="local-vars">How Local Variables Work</a></h4>
<h4 id="local-vars">How Local Variables Work</h4>
<p>Local variables are applied to instructions that have zero
page operands (<code>op ZP</code>, <code>op (ZP),Y</code>, etc.), or
@ -239,7 +240,7 @@ ways for a table to erase an earlier definition:</p>
<li>Tables have a "clear previous" flag that erases all previous
definitions. This doesn't usually cause anything to be generated in the
assembly sources; instead, it just causes SourceGen to stop using
that label.</li>
those labels.</li>
</ol>
<p>As you might expect, you're not allowed to have duplicate labels or
overlapping values in an individual table.</p>
@ -252,7 +253,7 @@ of <code>PTR</code> becomes <code>PTR_1</code>), and variables will have
global scope.</p>
<h3><a name="unique-local-global">Unique vs. Non-Unique and Local vs. Global</a></h3>
<h3 id="unique-local-global">Unique vs. Non-Unique and Local vs. Global</h3>
<p>Most assemblers have a notion of "local" labels, which have a scope
that is book-ended by global labels. These are handy for generic branch
@ -278,20 +279,21 @@ source generator can modify the output until it works. For example:<p>
DEY
BNE @LOOP
</pre>
<p>This would confuse an assembler. SourceGen already knows which @LOOP
is being branched to, so it can just rename one of them to "@LOOP1".</p>
<p>This would confuse an assembler. SourceGen already knows which
<code>@LOOP</code> is being branched to, so it can just rename one of
them to <code>@LOOP1</code>.</p>
<p>One situation where non-unique labels cause difficulty is with
weak symbolic references (see next section). For example, suppose
the above code then did this:</p>
<pre>
LDA #&lt;@LOOP
</pre>
<p>While it's possible to make an educated guess at which @LOOP was
meant, it's easy to get wrong. In situations like this, it's best to
<p>While it's possible to make an educated guess at which <code>@LOOP</code>
was meant, it's easy to get wrong. In situations like this, it's best to
give the labels different names.</p>
<h3><a name="weak-refs">Weak Symbolic References</a></h3>
<h3 id="weak-refs">Weak Symbolic References</h3>
<p>Symbolic references in operands are "weak references". If the named
symbol exists, the reference is used. If the symbol can't be found, the
@ -313,40 +315,43 @@ following trivial chunk of code:</p>
L1003 NOP
</pre>
<p>The analyzer found the JMP operand, and created an auto label for
address $1003. It then created a weak reference to "L1003" in the JMP
operand.</p>
<p>The analyzer found the <code>JMP</code> operand, and created an auto
label for address $1003. It then created a weak reference to
"<code>L1003</code>" in the <code>JMP</code> operand.</p>
<p>If you edit the JMP instruction's operand to use the symbol "FOO", the
results are probably not what you want:</p>
<p>If you edit the <code>JMP</code> instruction's operand to use the
symbol "<code>FOO</code>", the results are probably not what you want:</p>
<pre>
.ADDRS $1000
JMP $1003
NOP
</pre>
<p>This happened because you added a weak reference to "FOO" in the operand,
but the label doesn't exist. The operand is formatted as hex. Because
there's no longer a reference to L1003, SourceGen removed the auto-label
as well.</p>
<p>This happened because you added a weak reference to "<code>FOO</code>"
in the operand, but the label isn't defined anywhere. With no matching
label found, the operand was formatted as hex. Further, because there's
no longer a numeric reference to the code at $1003, SourceGen removed
the <code>L1003</code> auto-label.</p>
<p>If you set the label "FOO" on the NOP instruction, you'll see what you
probably wanted:</p>
<p>If you set the label "<code>FOO</code>" on the <code>NOP</code>
instruction, you'll see what you probably wanted:</p>
<pre>
.ADDRS $1000
JMP FOO
FOO NOP
</pre>
<p>You don't actually need the explicit reference in the JMP instruction.
If you edit the JMP operand and set it back to "Default", the code will
still look the same. This is because SourceGen identified the numeric
reference, and automatically added a symbolic reference to the label on
the NOP instruction.</p>
<p>Of course, you don't actually need the explicit reference in the
<code>JMP</code> instruction. If you edit the <code>JMP</code> operand
and set the format back to <samp>Default</samp>, removing the weak
symbolic reference, the code will still look the same.
This is because SourceGen identified the numeric reference, and
used that to find the label on the <code>NOP</code> instruction.</p>
<p>However, suppose you didn't actually want FOO as the operand label.
You can create a project symbol, BAR with the value $1003, and then edit
the operand to reference BAR instead. Your code would then look like:</p>
<p>However, suppose you didn't actually want <code>FOO</code> as the
operand label. You can create a project symbol called "<code>BAR</code>"
with the value $1003, and then edit the operand to reference <code>BAR</code>
instead. Your code would then look like:</p>
<pre>
BAR .EQ $1003
.ADDRS $1000
@ -354,9 +359,10 @@ BAR .EQ $1003
FOO NOP
</pre>
<p>If you change the value of BAR in the project symbol file, the operand
will continue to refer to it, but with an adjustment. For example, if
you changed BAR from $1003 to $1007, the code would become:</p>
<p>If you change the value of <code>BAR</code> in the project symbol file,
the operand will continue to refer to it, but with an adjustment. For
example, if you changed <code>BAR</code> from $1003 to $1007,
the code would become:</p>
<pre>
BAR .EQ $1007
.ADDRS $1000
@ -374,7 +380,7 @@ to the symbol will break and be formatted as hex, but will not be
removed. Similarly, removing symbols from a platform or project file
will break the reference but won't modify the operands.</p>
<h3><a name="symbol-parts">Parts and Adjustments</a></h3>
<h3 id="symbol-parts">Parts and Adjustments</h3>
<p>Sometimes you want to use part of a label, or adjust the value slightly.
(I use "adjustment" rather than "offset" to avoid confusing it with file
@ -388,10 +394,10 @@ offsets.) Consider the following example:</p>
1007: 4c3aff JMP $ff3a
</pre>
<p>This pushes the address of the JMP instruction ($1007) onto the stack,
and jumps to it with the RTS instruction. However, RTS requires the
address of the byte before the target instruction, so we actually push
$1006.</p>
<p>This pushes the address of the <code>JMP</code> instruction ($1007)
onto the stack, and jumps to it with the <code>RTS</code> instruction.
However, <code>RTS</code> requires the address of the byte <i>before</i>
the target instruction, so we actually need to push $1006.</p>
<p>The disassembler won't know that offset $1007 is code because nothing
appears to reference it. After tagging $1007 as a code start point, the
@ -406,8 +412,9 @@ project looks like this:</p>
JMP $ff3a
</pre>
<p>We set a label called "NEXT" on the JMP instruction, and then edit
the two LDA instructions to reference the high and low parts, yielding:</p>
<p>We set a label called "<code>NEXT</code>" on the <code>JMP</code>
instruction, and then edit the two <code>LDA</code> instructions to
reference the high and low parts, yielding:</p>
<pre>
.ADDRS $1000
LDA #&gt;NEXT
@ -424,10 +431,11 @@ generate the original value. If the adjustment seems wrong, make sure
you're selecting the right part of the symbol.</p>
<p>Different assemblers use different syntaxes to form expressions. This
is particularly noticeable in 65816 code. You can adjust how it appears
on-screen from the app settings.</p>
is particularly noticeable in 65816 code. You can choose which syntax
to use on-screen from the application settings.</p>
<h3><a name="nearby-targets">Automatic Use of Nearby Targets</a></h3>
<h3 id="nearby-targets">Automatic Use of Nearby Targets</h3>
<p>Sometimes you want to use a symbol that doesn't match up with the
operand. SourceGen tries to anticipate situations where that might be
@ -499,11 +507,11 @@ Self-modifying code will always be adjusted because of the limitation
on mid-instruction labels.</p>
<h2><a name="width-disambiguation">Width Disambiguation</a></h2>
<h2 id="width-disambiguation">Width Disambiguation</h2>
<p>It's possible to interpret certain instructions in multiple ways.
For example, "LDA $0000" might be an absolute load from a 16-bit
address, or it might be a direct page load from an 8-bit address.
For example, "<code>LDA $0000</code>" might be an absolute load from a 16-bit
address, or it might be a zero-page load from an 8-bit address.
Humans can infer from the fact that it was written with a 4-digit address
that it's meant to be absolute, but assemblers often treat operands
purely as numbers, and would just see "LDA 0". Common practice is to
@ -515,8 +523,9 @@ allow both. You can configure how they appear in the
<p>SourceGen will only add width disambiguators to opcodes or operands when
they are needed, with one exception: the opcode suffix for long
(24-bit address) operations is always applied. This is done because some
assemblers require it, insisting on "LDAL" rather than "LDA" for an
absolute long load, and because it can make 65816 code easier to read.</p>
assemblers require it, insisting on "<code>LDAL</code>" rather than
"<code>LDA</code>" for an absolute long load, and because it can
make 65816 code easier to read.</p>
@ -597,17 +606,20 @@ example, suppose something like:</p>
SUB_SRC
.ADDRS $2000
SUB_DST [small routine]
SUB_DST LDY #$00
[...]
RTS
.ADREND
CONT LDA #$12
JSR SUB_DST
</pre>
<p>In this case, a small routine is copied out of the middle of the
code that lives at $1000. We want the code at CONT to pick up where
things left off. If SUB_SRC is at $1009, and is 23 bytes long, then
CONT should be $1020. We could output <code>.ADDRS $1020</code>
directly before CONT, but it's inconvenient to work with the generated
code that lives at $1000. We want the code at <code>CONT</code>
to pick up where things left off. If <code>SUB_SRC</code> is at $1009,
and is 23 bytes long, then <code>CONT</code> should be $1020. We
could output <code>.ADDRS $1020</code> directly before <code>CONT</code>,
but it's inconvenient to work with the generated
code if we want to modify the subroutine (changing its length)
and re-assemble it.</p>
@ -636,11 +648,11 @@ a start offset with another region, because their end point would be
adjusted to match the end of the other region.</p>
<p>The arrangement of regions is particularly important when attempting
to resolve an address operand (such as a JSR) to a location within the
file. The process is straightforward if the address only appears once,
but when overlays cause multiple parts of the file to have the same
address, the operand target may be in different places depending on where
the call is being made from.
to resolve an address operand (such as a <code>JSR</code>) to a location
within the file. The process is straightforward if the address only
appears once, but when overlays cause multiple parts of the file to have
the same address, the operand target may be in different places depending
on where the call is being made from.
The algorithm for resolving addresses is described
in the <a href="advanced.html#overlap">advanced topics</a> section.</p>
@ -656,10 +668,10 @@ to the CPU.</p>
<p>The generated source file must recreate the original binary exactly,
but we don't really want to assign an address to non-addressable data,
because it should never be resolved as the target of a JSR or LDA. To
handle this case, you can set a region's address to "NA". The assembler
needs to have <i>some</i> notion of address, so the start address will
be treated as zero.</p>
because it should never be resolved as the target of a <code>JSR</code>
or <code>LDA</code>. To handle this case, you can set a region's address
to "<kbd>NA</kbd>". The assembler needs to have <i>some</i> notion of
address, so the start address will be treated as zero.</p>
<p>Non-addressable regions cannot include executable code. You may put
labels on data items, but attempting to reference them will cause a
@ -745,7 +757,7 @@ offset cannot be used.</p>
<h2><a name="atags">Directing the Code Analyzer</a></h2>
<h2 id="atags">Directing the Code Analyzer</h2>
<p>Sometimes SourceGen can't automatically find the start or end of an
instruction stream, or gets confused by inline data. These situations
@ -777,9 +789,9 @@ L1009 CLC
<p>SourceGen doesn't see any code that jumps to $1003 or $1006, so it
assumes those are data. Further, the functions at those addresses may
also be considered data unless some bit of code reachable from L1009
calls into them. If you tag $1003 and $1006 as code start points,
you'll get better results:</p>
also be considered data unless some bit of code reachable from
<code>L1009</code> calls into them. If you tag $1003 and $1006 as code
start points, you'll get better results:</p>
<pre>
.ADDRS $1000
JMP L1009
@ -805,9 +817,10 @@ L1009 CLC
The problem is that the bytes in the middle of the instruction have
been tagged as start points, so SourceGen is treating them as
embedded instructions. $EF and $12 aren't valid 6502 opcodes, so
they're being ignored, but $10 is BPL and $30 is BMI. Because tagging
multiple consecutive bytes is rarely useful, SourceGen only applies code
start tags to the first byte in a selected line.</p>
they're being ignored, but $10 is <code>BPL</code> and $30 is
<code>BMI</code>.
Because tagging multiple consecutive bytes is rarely useful, SourceGen
only applies code start tags to the first byte in a selected line.</p>
<p><b>Code stop point</b> tags tell the analyzer when it should stop. For
example, suppose address $ff00 is known to always be nonzero, and the code
@ -819,14 +832,15 @@ uses that fact to get a branch-always on the 6502:</p>
BRK $11
</pre>
<p>By tagging the BRK as a code stop point, you're telling the analyzer that
it should stop trying to execute code when it reaches that point. (Note
that this example would actually be better solved by setting a status flag
override on the BNE that sets Z=0, so the code tracer will know it's a
branch-always and just do the right thing.) As with code start points,
code stop points should only be placed on the opcode byte. Placing a
code stop point in the middle of what SourceGen believes to be instruction
will have no effect.</p>
<p>By tagging the <code>BRK</code> as a code stop point, you're telling the
analyzer that it should stop trying to execute code when it reaches
that point.
(Note that this example would actually be better solved by setting a
status flag override on the <code>BNE</code> that sets Z=0, so the code
tracer will know it's a branch-always and just do the right thing.)
As with code start points, code stop points should only be placed on the
opcode byte. Placing a code stop point in the middle of what SourceGen
believes to be instruction will have no effect.</p>
<p>As with code start points, only the first byte in each selected line will
be tagged.</p>
@ -850,7 +864,7 @@ applying the tag, all bytes in a selected line will be modified.</p>
branch will be ignored.</p>
<h3><a name="scripts">Extension Scripts</a></h3>
<h3 id="scripts">Extension Scripts</h3>
<p>Extension scripts are C# source files that are compiled and
executed by SourceGen. They can be added to a project from SourceGen's
@ -867,9 +881,9 @@ and let the script do the formatting automatically.</p>
<p>To reduce the chances of a script causing problems, all scripts are
executed in a sandbox with severely restricted access. Notably, nothing
in the sandbox can access files, except to read files from the PluginDll
in the sandbox can access files, except to read files from the PluginDllCache
directory.</p>
<p>The PluginDll directory lives next to the SourceGen executable, and
<p>The PluginDllCache directory lives next to the SourceGen executable, and
contains all of the compiled script DLLs, as well as two pre-built
application DLLs that plugins are allowed access to. The contents
are persistent, to avoid recompiling the scripts every time SourceGen
@ -878,7 +892,7 @@ is launched, but may be manually deleted without harm.</p>
<a href="advanced.html#extension-scripts">advanced topics</a> section.</p>
<h2><a name="pseudo-ops">Data and Directive Pseudo-Opcodes</a></h2>
<h2 id="pseudo-ops">Data and Directive Pseudo-Opcodes</h2>
<p>The on-screen code list shows assembler directives that are similar
to what the various cross-assemblers provide. The actual directives
@ -888,54 +902,58 @@ code generator figure out the implementation details.</p>
<p>There are eight assembler directives that appear in the code list:</p>
<ul>
<li>.EQ - defines a symbol's value. These are generated automatically
when an operand that matches a platform or project symbol is found.</li>
<li>.VAR - defines a local variable. These are generated for
<li><code>.EQ</code> - defines a symbol's value. These are generated
automatically when an operand that matches a platform or project
symbol is found.</li>
<li><code>.VAR</code> - defines a local variable. These are generated for
local variable tables.</li>
<li>.ADDRS/.ADREND - specifies the start or end of an
address region.</li>
<li>.RWID - specifies the width of the accumulator and index registers
(65816 only). Note this doesn't change the actual width, just tells
the assembler that the width has changed.</li>
<li>.DBANK - specifies what value the Data Bank Register holds
<li><code>.ADDRS</code>/<code>.ADREND</code> - specifies the start or
end of an address region, respectively.</li>
<li><code>.RWID</code> - specifies the width of the accumulator and
index registers (65816 only). Note this doesn't change the actual
width, just tells the assembler that the width has changed.</li>
<li><code>.DBANK</code> - specifies what value the Data Bank Register holds
(65816 only). Used when matching operands to labels.</li>
<li>.DS - identifies space set aside for variable storage. The storage
is initialized by the program before first use, so the values
<li><code>.DS</code> - identifies space set aside for variable storage.
The storage is initialized by the program before first use, so the values
in the binary don't actually matter.</li>
<li>.JUNK - indicates that the data in a range of bytes is irrelevant.
(When generating sources, this will become .FILL or .BULK
<li><code>.JUNK</code> - indicates that the data in a range of bytes is
irrelevant. (When generating sources, this will become
<code>.FILL</code> or <code>.BULK</code>
depending on the contents of the memory region and the assembler's
capabilities.)</li>
<li>.ALIGN - a special case of .JUNK that indicates the irrelevant
bytes exist to force alignment to a memory boundary (usually a
256-byte page). Depending on the memory contents, it may be possible
to output this as an assembler-specific alignment directive.</li>
<li><code>.ALIGN</code> - a special case of <code>.JUNK</code> that
indicates the irrelevant bytes exist to force alignment to a
memory boundary (usually a 256-byte page). Depending on the
memory contents, it may be possible to output this as an
assembler-specific alignment directive.</li>
</ul>
<p>Every data item is represented by a pseudo-op. Some of them may
represent hundreds of bytes and span multiple lines.</p>
<ul>
<li>.DD1, .DD2, .DD3, .DD4 - basic "define data" op. A 1-4 byte
<li><code>.DD1</code>, <code>.DD2</code>, <code>.DD3</code>,
<code>.DD4</code> - basic "define data" op. A 1-4 byte
little-endian value.</li>
<li>.DBD2, .DBD3, .DBD4 - "define big-endian data". 2-4 bytes of
big-endian data. (The 3- and 4-byte versions are not currently
available in the UI, since they're very unusual and few assemblers
support them.)</li>
<li>.BULK - data packed in as compact a form as the assembler allows.
Useful for chunks of graphics data.</li>
<li>.FILL - a series of identical bytes. The operand
<li><code>.DBD2</code>, <code>.DBD3</code>, <code>.DBD4</code> - "define
big-endian data". 2-4 bytes of big-endian data.
(The 3- and 4-byte versions are not currently available in the UI,
since they're very unusual and few assemblers support them.)</li>
<li><code>.BULK</code> - data packed in as compact a form as the
assembler allows. Useful for things like chunks of graphics data.</li>
<li><code>.FILL</code> - a series of identical bytes. The operand
has two parts, the byte count followed by the byte value.</li>
</ul>
<p>In addition, several pseudo-ops are defined for string constants:</p>
<ul>
<li>.STR - basic character string.</li>
<li>.RSTR - string in reverse order.</li>
<li>.ZSTR - null-terminated string.</li>
<li>.DSTR - Dextral Character Inverted string. The high bit of the
last byte is flipped.</li>
<li>.L1STR - string prefixed with a length byte.</li>
<li>.L2STR - string prefixed with a length word.</li>
<li><code>.STR</code> - basic character string.</li>
<li><code>.RSTR</code> - string in reverse order.</li>
<li><code>.ZSTR</code> - null-terminated string.</li>
<li><code>.DSTR</code> - Dextral Character Inverted string. The
high bit of the last byte is flipped.</li>
<li><code>.L1STR</code> - string prefixed with a length byte.</li>
<li><code>.L2STR</code> - string prefixed with a length word.</li>
</ul>
<p>You can configure the pseudo-operands to look more like what your

27
docs/sgmanual/intro.html
View File

@ -1,19 +1,20 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Intro - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Intro - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Intro</h1>
<h1>SourceGen: Intro</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="overview">Overview</a></h2>
<h2 id="overview">Overview</h2>
<p>SourceGen converts 6502/65C02/65816 machine-language programs to
assembly-language source.</p>
@ -58,7 +59,7 @@ something that people actually want.</p>
the <a href="https://6502bench.com/sgtutorial/">tutorials</a>.</p>
<h2><a name="fundamental-concepts">Fundamentals</a></h2>
<h2 id="fundamental-concepts">Fundamentals</h2>
<p>The next few sections present some general concepts and terminology. The
rest of the documentation assumes you've read and understood this.</p>
@ -68,7 +69,7 @@ other programs is actually a pretty good way to learn how to code in
assembly. You will need to be familiar with hexadecimal numbers and
general programming concepts to make sense of this, however.</p>
<h3><a name="begin">About 6502 Code</a></h3>
<h3 id="begin">About 6502 Code</h3>
<p>For brevity's sake, "6502 code" should be taken to mean "code for
the 6502 CPU or any of its derivatives, including but not limited to
@ -156,7 +157,7 @@ how 80-column display memory is mapped.</p>
<p>On a few systems, such as the Atari 2600, RAM, ROM, and registers can
appear at multiple locations, "mirrored" across the address space.</p>
<h3><a name="charenc">Character Encoding</a></h3>
<h3 id="charenc">Character Encoding</h3>
<p>The American Standard Code for Information Interchange (ASCII) was
developed in the 1960s, and became widely used as the means for representing
@ -184,7 +185,7 @@ bell ($07), linefeed ($0a), and carriage return ($0d) are recognized as
string data, and in C64 PETSCII a number of text color and formatting
control codes are also allowed.</p>
<h3><a name="sgconcepts">SourceGen Concepts</a></h3>
<h3 id="sgconcepts">SourceGen Concepts</h3>
<p>As you work on a disassembled file, formatting operands and adding
comments, everything you do is saved in the project file as "meta data".
@ -247,7 +248,7 @@ can happen to labels. SourceGen will try to prevent this from happening
by splitting formatted data into sub-regions at label boundaries.</p>
<h2><a name="sgintro">How SourceGen Works</a></h2>
<h2 id="sgintro">How SourceGen Works</h2>
<p>SourceGen employs a partial emulation technique that traces the flow
of execution through the program. Most of what a given instruction does

10
docs/sgmanual/main.css
View File

@ -16,3 +16,13 @@ body {
margin: 20px 10px 10px 10px;
/*position: relative;*/
}
/*
* Display of keyboard shortcuts in the <kbd> element.
*/
kbd.key {
border-radius: 5px;
padding: 0px 2px 0;
border: 1px solid black;
background-color: #f7f7f7;
}

304
docs/sgmanual/mainwin.html
View File

@ -1,49 +1,53 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Using SourceGen - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Using SourceGen - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Using SourceGen</h1>
<h1>SourceGen: Using SourceGen</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="starting-new">Starting a New Project</a></h2>
<h2 id="starting-new">Starting a New Project</h2>
<p>Select File &gt; New, or if no project is open, click "Start new project".
This opens the Create New Project window.</p>
<p>Select <samp>File &gt; New</samp>, or if no project is open, you
can click the <samp>Start new project</samp> button.
This opens the <samp>Create New Project</samp> window.</p>
<p>Start by selecting your target system from the tree on the left.
The panel on the right will show the CPU that will be selected, as well
as the symbol files and extension scripts that will be loaded by default.
All of these may be overridden later from the project properties.
(If the description in the panel on the right says "[placeholder]", it
means that the system doesn't yet have a set of symbols defined for it.)</p>
(If the description in the panel on the right says
"<samp>[placeholder]</samp>", it means that the system doesn't yet have
a set of symbols defined for it.)</p>
<p>Next, click the "Select File..." button. Pick the file you wish to
disassemble. The dialog will update with the pathname and some notes
about the file's size. Click "OK" if all looks good to create the
<p>Next, click the <samp>Select File...</samp> button. Pick the file you
wish to disassemble. The dialog will update with the pathname and some notes
about the file's size. Click <samp>OK</samp> if all looks good to create the
project.</p>
<p><strong>NOTE:</strong> Support for very large 65816 programs is
incomplete. The maximum size for a data file is limited to 1 MiB.</p>
<p>The first time you save the project (with File &gt; Save), you will be
prompted for the project name. It's best to use the data file's name
with ".dis65" added, so this will be set as the default. The data
file's name is not stored in the project file, so if you pick a different
name, or save the project in a different directory, you will have to
select the data file manually whenever you open the project.</p>
<p>The first time you save the project (with <samp>File &gt; Save</samp>),
you will be prompted for the project name. It's best to use the
data file's name with "<samp>.dis65</samp>" added, so this will be set as
the default. The data file's name is not stored in the project file,
so if you pick a different name, or save the project in a different
directory, you will have to select the data file manually whenever you
open the project.</p>
<h2><a name="opening">Opening an Existing Project</a></h2>
<h2 id="opening">Opening an Existing Project</h2>
<p>Select File &gt; Open, or if no project is open, click "Open
existing project". Select the .dis65 project file from the standard
file dialog.</p>
<p>Select <samp>File &gt; Open</samp>, or if no project is open, you
can click the <samp>Open existing project</samp> button.
Select the .dis65 project file from the standard file dialog.</p>
<p>SourceGen will try to open a data file with the project's name,
minus the ".dis65". If it can't find a file with that name, or if there's
something wrong with it (e.g. the CRC doesn't match), you will be given
@ -60,11 +64,11 @@ also be given the opportunity to simply cancel loading the project.</p>
<p>The locations of the last few projects you've worked with are saved
in the application settings. You can access them from
File &gt; Recent Projects. If no project is open, links to the two
most-recently-opened projects will be available.</p>
<samp>File &gt; Recent Projects</samp>. If no project is open, buttons
that open the two most-recently-opened projects will be available.</p>
<h2><a name="working">Working With a Project</a></h2>
<h2 id="working">Working With a Project</h2>
<p>The main project window is divided into five areas:</p>
<ol>
@ -89,7 +93,7 @@ code, data, and uninitialized data (variable storage or junk) found
in the program. These values are updated as you work.</p>
<h3><a name="code-list">Code List</a></h3>
<h3 id="code-list">Code List</h3>
<p>The code list provides a view of the code being disassembled. Each
line may be an instruction, data item, long comment, note, or
@ -157,14 +161,14 @@ respectively.</p>
<p>The code list is a standard Windows list view. You can left-click
to select an item, ctrl-left-click to toggle individual items on and
off, and shift-left-click to select a range. You can select all lines
with Edit &gt; Select All. Resize columns by
with <samp>Edit &gt; Select All</samp>. Resize columns by
left-clicking on the divider in the header and dragging it.</p>
<p>Selecting any part of a multi-line item, such as a long comment
or character string, effectively selects the entire item.</p>
<p>Right-clicking opens a menu. The contents are the same as those in
the Actions menu item in the menu bar. The set of options that are
enabled will depend on what you have selected in the main window.</p>
the <samp>Actions</samp> menu item in the menu bar. The set of options
that are enabled will depend on what you have selected in the main window.</p>
<ul>
<li><a href="editors.html#instruction-operand">Edit Operand</a>. Opens the
Edit Instruction Operand or Edit Data Operand window, depending on
@ -231,10 +235,12 @@ enabled will depend on what you have selected in the main window.</p>
</ul>
<h3><a name="undo">Undo &amp; Redo</a></h3>
<h3 id="undo">Undo &amp; Redo</h3>
<p>You can undo a change with Edit &gt; Undo, or Ctrl+Z. You can redo a
change with Edit &gt; Redo, Ctrl+Y, or Ctrl+Shift+Z.</p>
<p>You can undo a change with <samp>Edit &gt; Undo</samp>, or
<kbd class="key">Ctrl+Z</kbd>. You can redo a
change with <samp>Edit &gt; Redo</samp>, <kbd class="key">Ctrl+Y</kbd>,
or <kbd class="key">Ctrl+Shift+Z</kbd>.</p>
<p>All changes to the project, including changes to the project properties,
are added to the undo/redo buffer. This has no fixed size limit, so no
matter how much you change, you can always undo back to the point where
@ -243,7 +249,7 @@ the project was opened.</p>
clears it.</p>
<h3><a name="references">References Window</a></h3>
<h3 id="references">References Window</h3>
<p>When a single instruction or data line is selected in the main window,
all references to that offset will be shown in the References window.
@ -275,10 +281,10 @@ the instruction is using the location as a base address.</p>
(e.g. <code>LDA (dp),Y</code>) will show "ptr". This makes it easy
to identify the locations that are reading or writing through the
pointer from those that are reading or writing the pointer itself.</p>
<p>This will be prefixed with "Sym" or "Oth" to indicate whether or not
the reference used the label at the current address. To understand
this, consider that addresses can be referenced in different ways.
For example:</p>
<p>This will be prefixed with "<samp>Sym</samp>" or "<samp>Oth</samp>"
to indicate whether or not the reference used the label at the current
address. To understand this, consider that addresses can be referenced
in different ways. For example:</p>
<pre>
LDA DATA0
LDX DATA0+1
@ -294,9 +300,9 @@ instructions referenced it. When <code>DATA1</code> is selected, the
references window will show the <code>LDX</code>, because that
instruction accessed <code>DATA1</code>'s location even though it didn't
use the symbol. To make the difference clear, the lines in the references
window will either show "Sym" (to indicate that the symbol at the selected
line was referenced) or "Oth" (to indicate that some other symbol, or no
symbol, was used).</p>
window will either show "<samp>Sym</samp>" (to indicate that the symbol
at the selected line was referenced) or "<samp>Oth</samp>" (to indicate
that some other symbol, or no symbol, was used).</p>
<p>When an equate directive (generated for platform and project
symbols) or local variable assignment is selected, the References
@ -314,18 +320,32 @@ or project symbol, an equate directive will not be generated for it.</p>
reference, and adds the previous selection to the navigation stack.</p>
<h3><a name="notes">Notes Window</a></h3>
<h3 id="notes">Notes Window</h3>
<p>When you add a note, it will also be added to this window.
Double-clicking on a note will jump directly to it, and add the previous
selection to the navigation stack. This makes notes useful as bookmarks.</p>
<h3><a name="symbols">Symbols Window</a></h3>
<h3 id="symbols">Symbols Window</h3>
<p>All known <a href="intro-details.html#about-symbols">symbols</a> are shown
here. The filter buttons allow you to screen out symbols you're not
interested in, such as platform symbols or constants.</p>
interested in, such as platform symbols or constants. The filters are:</p>
<ul>
<li><samp>User</samp> - include "user labels", i.e. labels that
were entered by the user.</li>
<li><samp>NonU</samp> - include non-unique (local) labels.</li>
<li><samp>Proj</samp> - include project symbols.</li>
<li><samp>Plat</samp> - include platform symbols.</li>
<li><samp>PreL</samp> - include address region pre-labels.</li>
<li><samp>Auto</samp> - include auto-generated labels.</li>
<li><samp>Addr</samp> - include symbols for addresses. This
includes all labels, as well as addresses defined in project
and platform symbol tables.</li>
<li><samp>Cnst</samp> - include constants, defined in project
and platform symbol tables.</li>
</ul>
<p>Clicking on one of the column headers will sort the list on that
field. Click a second time to reverse the sort direction.</p>
@ -341,7 +361,7 @@ The second letter is one of N (non-unique local), L (local), G (global),
X (exported), E (external), or C (constant).</p>
<h3><a name="info">Info Window</a></h3>
<h3 id="info">Info Window</h3>
<p>Some additional information about the currently-selected line is
shown, such as the formatting applied to the operand. If the operand
@ -350,9 +370,11 @@ For an instruction,
a summary is shown that includes the cycle count, flags affected, and a
brief description of what the instruction does. The latter can be
especially handy for undocumented instructions.</p>
<p>If multiple lines are selected, the number of selected lines and the
number of bytes spanned by the selection will be shown.</p>
<h3><a name="messages">Messages Window</a></h3>
<h3 id="messages">Messages Window</h3>
<p>Sometimes a change will invalidate an earlier change. For example,
suppose you add a code stop point, and format the data that follows
@ -388,35 +410,38 @@ and the "resolution" column will indicate how it's being handled. In most
cases, the offending item will be ignored.</p>
<p>Double-clicking on an entry will jump to that offset.</p>
<p>The message list will not appear if there are no messages. You can
hide the list by clicking on the "Hide" button to the left of the messages.
Un-hide the list by clicking on the "N messages" button at the bottom-right
corner of the application window.</p>
hide the list by clicking on the <samp>Hide</samp> button to the left of
the messages. Un-hide the list by clicking on the <samp>N messages</samp>
button at the bottom-right corner of the application window.</p>
<h3><a name="navigation">Navigation</a></h3>
<h3 id="navigation">Navigation</h3>
<p>The simplest way to move through the code list is with the scroll wheel
on your mouse, or by left-clicking and dragging the scroll bar. You
can also use PgUp/PgDn and the arrow keys.</p>
can also use <kbd class="key">PgUp</kbd>/<kbd class="key">PgDn</kbd>
and the arrow keys.</p>
<p>Use Navigate &gt; Find to search for text. This performs a case-insensitive
text search on the label, opcode, operand, and comment fields.
Use Navigate &gt; Find Next to find the next match, and
Navigate &gt; Find Previous to find the previous match. Note "next" is
always downward, and "previous" is always upward, regardless of the
direction of the initial search chosen in the Find dialog.</p>
<p>Use <samp>Navigate &gt; Find</samp> to search for text. This performs
a case-insensitive text search on the label, opcode, operand, and comment
fields.
Use <samp>Navigate &gt; Find Next</samp> to find the next match, and
<samp>Navigate &gt; Find Previous</samp> to find the previous match.
Note "next" is always downward, and "previous" is always upward,
regardless of the direction of the initial search chosen in the
Find dialog.</p>
<p>Use Navigate &gt; Go To to jump to an offset, address, or label. Remember
that offsets and addresses are always hexadecimal, and offsets start
with a '+'. If you have a label that is also a valid hexadecimal
address, like "FEED", the label takes precedence. To jump to the address
write "$FEED" instead. If you enter a non-unique label, the selection
will jump to the nearest instance.</p>
<p>Use <samp>Navigate &gt; Go To</samp> to jump to an offset, address,
or label. Remember that offsets and addresses are always hexadecimal,
and offsets start with a '+'. If you have a label that is also a
valid hexadecimal address, like "FEED", the label takes precedence. To
jump to the address write "$FEED" instead. If you enter a non-unique label,
the selection will jump to the nearest instance.</p>
<p>If an instruction or data line has an operand that references an address
in the file, you can navigate to the operand's location with
Navigate &gt; Jump to Operand. You can also do this by double-clicking
in the opcode column.</p>
<samp>Navigate &gt; Jump to Operand</samp>. You can also do this by
double-clicking in the opcode column.</p>
<p>When you edit something, lines throughout the listing can change. This
is different from a source code editor, where editing a line just changes
@ -424,48 +449,62 @@ that line. To allow you to watch the effects changes have, the undo/redo
commands try to keep the listing in the same position.
If you want to go to the place where the last change (i.e. the change
that will be undone by the next Undo operation) was made,
Navigate &gt; Go to Last Change will jump to the first offset
<samp>Navigate &gt; Go to Last Change</samp> will jump to the first offset
associated with the most recent change.
If the last change was to the project properties, it will jump to the
first offset in the file.</p>
<p>When you jump around, e.g. by double-clicking on an opcode or an entry
in one of the side windows, the previously-selected line is added to
a navigation stack. You can use Navigate &gt; Nav Forward and
Navigate &gt; Nav Backward to move forward and backward through the
stack. (The curly arrows on the left side of the toolbar may be more
convenient. You can use Alt+Left/Right Arrow, or
Ctrl+- / Ctrl+Shift+-, as keyboard shortcuts.)</p>
a navigation stack. You can use <samp>Navigate &gt; Nav Forward</samp> and
<samp>Navigate &gt; Nav Backward</samp> to move forward and backward
through the stack. (The curly arrows on the left side of the toolbar may
be more convenient. You can use
<kbd class="key">Alt+LeftArrow</kbd> / <kbd class="key">Alt+RightArrow</kbd>,
or <kbd class="key">Ctrl+-</kbd> / <kbd class="key">Ctrl+Shift+-</kbd>,
as keyboard shortcuts.)</p>
<h3><a name="atags">Adding and Removing Analyzer Tags</a></h3>
<h3 id="atags">Adding and Removing Analyzer Tags</h3>
<p><i>(Note: These were referred to as code/data "hints" in older
versions of SourceGen.)</i></p>
<p>To set code start or stop points, select the desired offsets and
use Actions &gt; Tag Address As Code Start Point (or Stop Point). Because
these indicate a transition between code and data regions, there is rarely
any need to tag multiple consecutive bytes.
For this reason, only the first byte on each selected line will be tagged.</p>
use <samp>Actions &gt; Tag Address As Code Start Point</samp>
(or <samp>Stop Point</samp>). Because these indicate a transition
between code and data regions, there is rarely any need to tag
multiple consecutive bytes. For this reason, only the first byte on
each selected line will be tagged.</p>
<p>For inline data, you need to cover the entire range, so every byte in every
selected line is tagged when you select Tag Bytes As Inline Data. Similarly,
the Remove Analyzer Tags menu item will remove tags from every byte.</p>
<p>For inline data that follows a
<code>JSR</code>/<code>JSL</code>/<code>BRK</code>,
you need to cover the entire range, so every byte
in every selected line is tagged when you select
<samp>Tag Bytes As Inline Data</samp>. Similarly, the
<samp>Remove Analyzer Tags</samp> menu item will remove tags from
every byte.</p>
<p>Tip: while code start points and inline data tagging are both very
important, code <i>stop</i> points are rarely useful. The code
analyzer is pretty good at separating code from data. If you find
yourself using stop points frequently, you're probably Doing It Wrong.</p>
<p>If you're having a hard time selecting just the right bytes because
the instructions are caught up in a multi-byte data item, such as an
auto-detected character string, you can disable uncategorized data analysis
(the thing that creates the .STR and .FILL ops for you). You can do this
from the
(the thing that creates the <code>.STR</code> and <code>.FILL</code>
ops for you). You can do this from the
<a href="settings.html#project-properties">project properties</a> editor,
or simply by hitting Ctrl+D. Hit that, tag the byte or bytes, then hit it
again to re-enable the string &amp; fill analyzer.</p>
<p>Another approach is to use the "Toggle Single-Byte Format"
menu item to "flatten" the item.</p>
or simply by hitting <kbd class="key">Ctrl+D</kbd>. Hit that, tag the
byte or bytes, then hit it again to re-enable the
string &amp; fill analyzer.</p>
<p>Another approach is to use the <samp>Toggle Single-Byte Format</samp>
menu item to "flatten" the item, explicitly formatting everything as
individual hex bytes.</p>
<h3><a name="address-table">Format Address Table</a></h3>
<h3 id="address-table">Format Address Table</h3>
<p>Tables of addresses are fairly common. Sometimes you'll find them as a
series of 16-bit words, like this:</p>
@ -487,12 +526,12 @@ jmptabh .dd1 &gt;func1
</pre>
<p>Sometimes the tables contain <code>address - 1</code>, because the
values are to be pushed onto the stack for an RTS call.</p>
values are to be pushed onto the stack for an <code>RTS</code> call.</p>
<p>While the .dd2 case is easy to format with the data operand editor,
formatting addresses whose components are split into multiple tables can
be tedious. Even in the easy case, you may want to create labels and set
code start points for each item.</p>
<p>While the <code>.dd2</code> case is easy to format with the data
operand editor, formatting addresses whose components are split into
multiple tables can be tedious. Even in the easy case, you may want
to create labels and set code start points for each item.</p>
<p>The Address Table Formatter helps you associate symbols with the
addresses in the table. It works for simple and "split" tables.</p>
@ -503,45 +542,47 @@ bytes. If the number of bytes selected can't be evenly divided by the
number of parts -- two parts for 16-bit data, three parts for 24-bit data --
the formatter will report an error.</p>
<p>With the data selected, open the format dialog with
Actions &gt; Format Split-Address Table. The rather complicated dialog
is split into sections.</p>
<samp>Actions &gt; Format Split-Address Table</samp>. The rather
complicated dialog is split into sections.</p>
<ul>
<li>Address Characteristics: select whether the table has 16-bit
addresses or 24-bit addresses. (24-bit addresses are disabled if you
don't have the CPU set to 65816.) If the table is split into individual
sub-tables for low bytes and high bytes, check the "Parts are split
across sub-tables" box. If the address parts are being pushed
on the stack for an RTS/RTL, check the "Adjusted for RTS/RTL" box to
adjust them by 1.</li>
sub-tables for low bytes and high bytes, check the <samp>Parts are split
across sub-tables</samp> box. If the address parts are being pushed
on the stack for an <code>RTS</code>/<code>RTL</code>,
check the <samp>Adjusted for RTS/RTL</samp> box to adjust them by 1.</li>
<li>Low Byte Source: indicate which part of the table or word holds the
low bytes. For common little-endian words, the low bytes come first. In
the split-table example above, the low bytes came first, followed by the
high bytes, so you would select "first part of selection". If they were
stored the other way around, you would click "second part" instead.</li>
high bytes, so you would select <samp>first part of selection</samp>.
If they were stored the other way around, you would click
<samp>second part</samp> instead.</li>
<li>High Byte Source: indicate which part of the table or word holds
the high bytes. For a 16-bit address this will be the part you didn't
pick for the low bytes.
Sometimes, if all addresses land on the same 256-byte page, the high byte
will be a constant in the code, and only the low bytes will be stored in
a table. If that's the case, select "Constant", and enter the high byte
in the text box. (Decimal, hex, and binary are accepted.)</li>
<li>Bank Byte Source: for 24-bit addresses, you can select "Nth part of
selection", which will just use whichever part you didn't specify for
a table. If that's the case, select <samp>Constant</samp>, and enter
the high byte in the text box.
(Decimal, hex, and binary are accepted.)</li>
<li>Bank Byte Source: for 24-bit addresses, you can select <samp>Nth part of
selection</samp>, which will just use whichever part you didn't specify for
the low and high bytes. If the table holds 16-bit addresses, you can
use the "Constant" field to specify the data bank.</li>
use the <samp>Constant</samp> field to specify the data bank.</li>
<li>Options: if the table holds the addresses of executable code, check
the "Tag targets as code start points" box. If the target address
hasn't been identified by the code analyzer through some other execution
path, it will be tagged as a code start point.</li>
the <samp>Tag targets as code start points</samp> box. If the target
address hasn't been identified by the code analyzer through some
other execution path, it will be tagged as a code start point.</li>
<li>Generated Addresses: this shows the full list of addresses that are
generated with the current set of parameters. Each address is shown with
a file offset and a symbol. If the address can't be mapped within the
file, the offset is shown as dashes instead. If the address can be
mapped, and it already has a user-specified label, the label will be
shown. If no label was found, the table will show "(+)", indicating
that a permanent label will be added at the target offset. If everything
is set up correctly, and the addresses fall entirely within the program,
you shouldn't see any unknown entries here.</li>
shown. If no label was found, the table will show "<code>(+)</code>",
indicating that a permanent label will be added at the target offset. If
everything is set up correctly, and the addresses fall entirely within
the program, you shouldn't see any unknown entries here.</li>
</ul>
<p>For a 16-bit address, you have three choices: low byte first, high byte
@ -564,18 +605,18 @@ does everything as a single undoable action, so if it comes out looking
wrong, just hit "undo" and try something else.</p>
<h3><a name="toggle-single">Toggle Single-Byte Format</a></h3>
<h3 id="toggle-single">Toggle Single-Byte Format</h3>
<p>The "Toggle Single-Byte Format" feature provides a quick way to
change a range of bytes to single bytes
<p>The <samp>Toggle Single-Byte Format</samp> feature provides a quick
way to change a range of bytes to single bytes
or back to their default format. It's equivalent to opening the Edit
Data Operand dialog and selecting "Single bytes" displayed as hex, or
selecting "Default".</p>
Data Operand dialog and selecting <samp>Single bytes</samp> displayed
as hex, or selecting <samp>Default</samp>.</p>
<p>This can be handy if the default format for a range of bytes is a
string, but you want to see it as bytes or set a label in the middle.</p>
<h3><a name="format-as-word">Format As Word</a></h3>
<h3 id="format-as-word">Format As Word</h3>
<p>This is a quick way to format pairs of bytes as 16-bit words. It's
equivalent to opening the Edit Data Operand dialog and selecting
@ -585,7 +626,7 @@ equivalent to opening the Edit Data Operand dialog and selecting
single-byte values. This means, for example, that you can't select a
10-byte string and have it turn into five 16-bit words. You can select as
many bytes as you want, but they must come in pairs. (Remember that you
can turn off auto-generation of strings and .FILLs with
can turn off auto-generation of strings and <code>.FILL</code>s with
<a href="#toggle-data">Toggle Data Scan</a>.)</p>
<p>As a special case, if you select a single byte, the following byte will
also be selected. This won't work if the following byte is part of a
@ -594,7 +635,7 @@ multi-byte data item, is the start of a new region (see
what splits a region), or is the last byte in the file.</p>
<h3 id="remove-formatting">Remove Formatting</a></h3>
<h3 id="remove-formatting">Remove Formatting</h3>
<p>Removes instruction and data operand formatting from the selected lines.
This removes the visible formatting as well as any formatting instructions
@ -605,23 +646,24 @@ such things in the <a href="#messages">message list</a>.)</p>
without removing visible labels.</p>
<h3><a name="toggle-data">Toggle Data Scan</a></h3>
<h3 id="toggle-data">Toggle Data Scan</h3>
<p>This menu item is in the Edit menu, and acts as a shortcut to opening
the Project Properties editor, and clicking on the "Analyze Uncategorized
Data" checkbox. When enabled, SourceGen will look for character strings and
regions of identical bytes, and generate .STR and .FILL directives. When
the Project Properties editor, and clicking on the <samp>Analyze
Uncategorized Data</samp> checkbox. When enabled, SourceGen will look
for character strings and regions of identical bytes, and generate
<code>.STR</code> and <code>.FILL</code> directives. When
disabled, uncategorized data is presented as one byte per line, which can
be handy if you're trying to get at a byte in the middle of a string.</p>
<p>As with all other project property changes, this is an undoable
action.</p>
<h3><a name="clipboard">Copying to Clipboard</a></h3>
<h3 id="clipboard">Copying to Clipboard</h3>
<p>When you use Edit &gt; Copy, all lines selected in the code list are
copied to the system clipboard. This can be a convenient way to post
code snippets into forum postings or documentation. The text is
<p>When you use <samp>Edit &gt; Copy</samp>, all lines selected in the
code list are copied to the system clipboard. This can be a convenient
way to post code snippets into forum postings or documentation. The text is
copied from the data shown on screen, so your chosen capitalization
and pseudo-ops will appear in the copy.</p>
<p>Long comments are included, but notes are not.</p>
@ -631,8 +673,8 @@ included. From the
alternative formats that include additional columns.</p>
<p>A copy of all of the fields is also written to the clipboard in CSV
format. If you have a spreadsheet like Excel, you can use Paste Special
to put the data into individual cells.</p>
format. If you have a spreadsheet like Excel, you can use
<samp>Paste Special</samp> to put the data into individual cells.</p>
</div>

238
docs/sgmanual/settings.html
View File

@ -1,25 +1,26 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Properties &amp; Settings - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Properties &amp; Settings - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Properties &amp; Settings</h1>
<h1>SourceGen: Properties &amp; Settings</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="overview">Settings Overview</a></h2>
<h2 id="overview">Settings Overview</h2>
<p>There are two kinds of settings: application settings, and
project properties.</p>
<h2><a name="app-settings">Application Settings</a></h2>
<h2 id="app-settings">Application Settings</h2>
<p>Application settings are stored in a file called "SourceGen-settings"
in the SourceGen installation directory. If the file is missing or
@ -30,15 +31,15 @@ affect the way the project analyzes code and data, though they may affect
the way generated assembly sources look.</p>
<p>The settings editor is divided into four tabs. Changes don't take
effect until you hit Apply or OK.</p>
effect until you hit <samp>Apply</samp> or <samp>OK</samp>.</p>
<h3><a name="appset-codeview">Code View</a></h3>
<h3 id="appset-codeview">Code View</h3>
<p>These settings change the way the code looks on screen.</p>
<p>Click the Column Visibility buttons to hide columns. Click them
again to restore the column to a width appropriate for the current font.
<p>Click the <samp>Column Visibility</samp> buttons to hide columns. Click
them again to restore the column to a width appropriate for the current font.
A "hidden" column just has a width of zero, so with careful mouse
positioning you can show and hide columns by dragging the column headers.
The buttons may be more convenient though.</p>
@ -53,35 +54,35 @@ to set all values. These settings are also used for generated assembly
code, unless the assembler has specific case-sensitivity requirements. There
is no setting for labels, which are always case-sensitive.</p>
<p>The Clipboard drop-down list lets you choose the format for text
<a href="mainwin.html#clipboard">copied to the clipboard</a>. The
"Assembler Source" format includes the rightmost columns (label,
<p>The <samp>Clipboard</samp> drop-down list lets you choose the format
for text <a href="mainwin.html#clipboard">copied to the clipboard</a>. The
<samp>Assembler Source</samp> format includes the rightmost columns (label,
opcode, operand, and comment), like assembly source code does. The
"Disassembly" format adds the address and bytes on the left. Use
the "All Columns" format to get all columns.</p>
<samp>Disassembly</samp> format adds the address and bytes on the left. Use
the <samp>All Columns</samp> format to get all columns.</p>
<p>When "show cycle counts for instructions" is checked, every instruction
line will have an end-of-line comment that indicates the number of cycles
required for that instruction. If the cycle count can't be determined
solely from a static analysis, e.g. an extra cycle is required if
<code>LDA (dp),Y</code> crosses a page boundary, a '+' will be shown.
In some cases the variability can be factored out if the state of
certain status flags is known, e.g. 65C02 instructions that take longer
in decimal mode won't be shown as variable if the analyzer can determine
that D=0 or D=1. This checkbox enables display in the on-screen list, but
does not affect generated source code, which can be configured independently
on the Asm Config tab.</p>
<p>When <samp>show cycle counts for instructions</samp> is checked,
every instruction line will have an end-of-line comment that indicates
the number of cycles required for that instruction. If the cycle count
can't be determined solely from a static analysis, e.g. an extra cycle
is required if <code>LDA (dp),Y</code> crosses a page boundary, a '+'
will be shown. In some cases the variability can be factored out if the
state of certain status flags is known, e.g. 65C02 instructions that take
longer in decimal mode won't be shown as ambiguous if the analyzer can
determine that D=0 or D=1. This checkbox enables display in the
on-screen list, but does not affect generated source code, which can
be configured independently on the <samp>Asm Config</samp> tab.</p>
<p>Check "use 'dark' color scheme" to change the main disassembly list
to use white text on a black background, and mute the Note highlight
colors.
<p>Check <samp>use 'dark' color scheme</samp> to change the main
disassembly list to use white text on a black background, and mute
the Note highlight colors.
(Most of the GUI uses standard Windows controls that take their colors
from the system theme, but the disassembly list uses a custom style. You
can change the rest of the UI from the Windows display "personalization"
controls.)</p>
<h3><a name="appset-textdelim">Text Delimiters</a></h3>
<h3 id="appset-textdelim">Text Delimiters</h3>
<p>Character and string operands are shown surrounded by quotes, e.g.
<code>LDA #'*'</code> or <code>.STR "Hello, world!"</code>. It's
@ -97,8 +98,9 @@ don't look very good at smaller font sizes.)</p>
the character will be output as hex to avoid confusion. For this
reason, it's generally wise to use delimiter characters that aren't
part of the ASCII character set, such as "curly" quotes. The
"Sample Characters" box holds some characters that you can copy and
paste (with Ctrl+C / Ctrl+V) into the delimiter fields.</p>
<samp>Sample Characters</samp> box holds some characters that you can
copy and paste (with <kbd class="key">Ctrl+C</kbd> /
<kbd class="key">Ctrl+V</kbd>) into the delimiter fields.</p>
<p>For character operands, the prefix and suffix are added to the start
and end of the operand. For string operands, the prefix is added to the
start of the first line, and suffixes aren't allowed.</p>
@ -113,7 +115,7 @@ double-quote characters. "Merlin" uses a format similar to what the
Merlin assembler expects.</p>
<h3><a name="appset-displayformat">Display Format</a></h3>
<h3 id="appset-displayformat">Display Format</h3>
<p>These options change the way the code list looks on screen. They
do not affect generated code.</p>
@ -135,10 +137,10 @@ but that's a valid label start character, and so isn't allowed here.)
The setting affects label editing as well as display.</p>
<p>If you would like your local variables to be shown with a prefix
character, you can set it in the "local variable prefix" box.</p>
character, you can set it in the <samp>local variable prefix</samp> box.</p>
<p>The "comma-separated format for bulk data" determines whether large
blocks of hex look like <code>ABC123</code> or
<p>The <samp>comma-separated format for bulk data</samp> determines
whether large blocks of hex look like <code>ABC123</code> or
<code>$AB,$C1,$23</code>. The former reduces the number of lines
required, the latter is more readable.</p>
@ -149,10 +151,10 @@ automatically switches to "custom" when you edit a field.
(64tass and ACME use the "common"
expression style, cc65 and Merlin 32 have their own unique styles.)</p>
<p>The "add spaces in Bytes column" checkbox changes the format of the
hex data in the code list "bytes" column from dense (<code>20edfd</code>)
to spaced (<code>20 ed fd</code>). This also affects the format of
clipboard copies and exports.</p>
<p>The <samp>add spaces in Bytes column</samp> checkbox changes the format
of the hex data in the code list "bytes" column from dense
(<code>20edfd</code>) to spaced (<code>20 ed fd</code>). This also
affects the format of clipboard copies and exports.</p>
<p>Long operands, such as strings and bulk data, are wrapped to a new
line after a certain number of characters. Use the pop-up to configure
@ -161,7 +163,7 @@ values allow you to shrink the width of the operand column in the
on-screen listing, moving the comment field closer in.</p>
<h3><a name="appset-pseudoop">Pseudo-Op</a></h3>
<h3 id="appset-pseudoop">Pseudo-Op</h3>
<p>These options change the way the code list looks on screen. Assembler
directives and data pseudo-opcodes will use these values. This does
@ -178,7 +180,7 @@ in the combo box to set the fields. The setting automatically switches to
<h3><a name="appset-asmconfig">Asm Config</a></h3>
<h3 id="appset-asmconfig">Asm Config</h3>
<p>These settings configure cross-assemblers and modify assembly source
generation in various ways.</p>
@ -195,25 +197,25 @@ executable.</p>
with all configuration files and libraries
<li>Merlin 32: <code>Merlin32.exe</code>
</ul>
<p>The "column widths" section allows you to specify the minimum
<p>The <samp>column widths</samp> section allows you to specify the minimum
width of the label, opcode, operand, and comment fields. If the width
is less than 1, or isn't a valid number, 1 will be used. These are
not hard stops: if the contents of a field are too wide, the contents
of the next column will be pushed over. (The comment field width is
not currently being used, but may be used to fold lines in the future.)</p>
<p>When "show cycle counts in comments" is checked, cycle counts are
inserted into end-of-line comments. This works the same as the option
in the Code View tab, but applies to generated source code rather than
the on-screen display.</p>
<p>When <samp>show cycle counts in comments</samp> is checked, cycle
counts are inserted into end-of-line comments. This works the same as
the option in the <samp>Code View</samp> tab, but applies to generated
source code rather than the on-screen display.</p>
<p>If "put long labels on separate line" is checked, labels that are
longer than the label column are placed on their own line. This looks
a bit nicer because otherwise the opcode gets pushed out of alignment.
<p>If <samp>put long labels on separate line</samp> is checked, labels
that are longer than the label column are placed on their own line. This
looks a bit nicer because otherwise the opcode gets pushed out of alignment.
(Some assemblers get bent out of shape if you split an equate
directive, so those might stay on one line.)</p>
<p>If you enable "identify assembler in output", a comment will be
<p>If you enable <samp>identify assembler in output</samp>, a comment will be
added to the top of the generated assembly output that identifies the
target assembler and version. It also shows the command-line options
passed to the assembler. This can be very helpful if the source
@ -222,7 +224,7 @@ the source file what the intended target assembler is, or what options
are required to process the file correctly.</p>
<h2><a name="project-properties">Project Properties</a></h2>
<h2 id="project-properties">Project Properties</h2>
<p>Project properties are stored in the .dis65 project file.
They specify which CPU to use, which extension scripts to load, and a
@ -232,12 +234,13 @@ the project properties are made through the undo/redo buffer,
which means you hit "undo" to revert a property change.</p>
<p>The properties editor is divided into four tabs. Changes aren't pushed
out to the main application until you close the dialog. Clicking Apply
will capture the current changes, ensuring that they're applied even if
you later hit Cancel, but the changes are not applied immediately.</p>
out to the main application until you close the dialog. Clicking
<samp>Apply</samp> will capture the current changes, ensuring that
they're applied even if you later hit Cancel, but the changes are not
applied to the project immediately.</p>
<h3><a name="projprop-general">General</a></h3>
<h3 id="projprop-general">General</h3>
<p>The choice of CPU determines the set of available instructions, as
well as cycle costs and register widths. There are many variations
@ -259,89 +262,92 @@ treated as one of these four:</p>
similar, but they have additional instructions and some fundamental
architectural changes. These are not currently supported by SourceGen.</p>
<p>If "enable undocumented instructions" is checked, some additional
opcodes are recognized on the 6502 and 65C02. These instructions are
not part of the chip specification, but most of them have consistent
behavior and can be used. If the box is not checked, the instructions
are treated as invalid and cause the code analyzer to assume that it
has run into a data area. This option has no effect on the 65816.</p>
<p>The "treat BRK as two-byte instruction" checkbox determines whether
BRK instructions should be handled as if they have an operand.</p>
<p>If <samp>enable undocumented instructions</samp> is checked, some
additional opcodes are recognized on the 6502 and 65C02. These
instructions are not part of the chip specification, but most of them
have consistent behavior and can be used. If the box is not checked,
the instructions are treated as invalid and cause the code analyzer to
assume that it has run into a data area. This option has no effect on
the 65816.</p>
<p>The <samp>treat BRK as two-byte instruction</samp> checkbox determines
whether <code>BRK</code> instructions should be handled as if they have
an operand.</p>
<p>The entry flags determine the initial value for the processor status
flag register. Code that is unreachable internally (requiring a code
start point tag) will use this value. This is chiefly of value for
65816 code, where the initial value of the M/X/E flags has a significant
impact on how instructions are disassembled.</p>
<p>The <samp>entry flags</samp> determine the initial value for the
processor status flag register. Code that is unreachable internally
(requiring a code start point tag) will use this value. This is chiefly
of value for 65816 code, where the initial value of the M/X/E flags has
a significant impact on how instructions are disassembled.</p>
<p>If "analyze uncategorized data" is checked, SourceGen will attempt to
identify character strings and regions that are filled with a repeated
value. If it's not checked, anything that isn't detected as code or
explicitly formatted as data will be shown as individual byte values.</p>
<p>If "seek nearby targets" is checked, the analyzer will try to use
nearby labels for data loads and stores, adjusting them to fit
<p>If <samp>analyze uncategorized data</samp> is checked, SourceGen
will attempt to identify character strings and regions that are filled
with a repeated value. If it's not checked, anything that isn't detected
as code or explicitly formatted as data will be shown as individual
byte values.</p>
<p>If <samp>seek nearby targets</samp> is checked, the analyzer will try to
use nearby labels for data loads and stores, adjusting them to fit
(e.g. <code>LDA LABEL+1</code>). If not enabled, labels are not applied
unless they match exactly. Note that references into the middle of an
instruction or formatted data area are always adjusted, regardless of
how this is set. This setting has no effect on local variables, and
only enables a 1-byte backward search on project/platform symbols.</p>
<p>The "use relocation data" checkbox is only available if the project
was created from a relocatable source, e.g. by the OMF Converter tool.
If checked, information from the relocation dictionary will be used to
improve automatic operand formatting.</p>
<p>If "smart PLP handling" is checked, the analyzer will try to use
the processor status flags from a nearby <code>PHP</code> when a
<p>The <samp>use relocation data</samp> checkbox is only available if
the project was created from a relocatable source, e.g. by the OMF Converter
tool. If checked, information from the relocation dictionary will be
used to improve automatic operand formatting.</p>
<p>If <samp>smart PLP handling</samp> is checked, the analyzer will try
to use the processor status flags from a nearby <code>PHP</code> when a
<code>PLP</code> is encountered. If not enabled, all flags are set to
"indeterminate" following a <code>PLP</code>, except for the M/X
flags on the 65816, which are left unmodified. (In practice this
approach doesn't seem to work all that well, so the setting is
un-checked by default.)</p>
<p>If "smart PLB handling" is checked, the analyzer will watch for
<p>If <samp>smart PLB handling</samp> is checked, the analyzer will watch for
code patterns like <code>PLB</code> preceded by <code>PHK</code>,
and generate appropriate Data Bank Register changes. If not enabled,
the DBR is set to the bank of the address of the start of the file,
and does not change unless explicitly set. Only useful for 65816 code.</p>
<p>The "default text encoding" setting has two effects. First, it
<p>The <samp>default text encoding</samp> setting has two effects. First, it
specifies which character encoding to use when searching for strings in
uncategorized data. Second, if an assembler has a notion of preferred
character encoding (e.g. you can default string operands to PETSCII),
this setting will determine which encoding is preferred.</p>
<p>The "min chars for string detection" setting determines how many
ASCII characters need to appear consecutively for the data analyzer to
this setting will determine which encoding is preferred in generated
sources.</p>
<p>The <samp>min chars for string detection</samp> setting determines how
many ASCII characters need to appear consecutively for the data analyzer to
declare it a string. Shorter values are prone to false-positive
identifications, longer values miss out on short strings. You can also
set it to "none" to disable automatic string identification.</p>
<p>The auto-label style setting determines the format for labels that are
generated automatically. By default the label will be the letter 'L'
followed by the hexadecimal address, but the label can be annotated based
on usage. For example, addresses that are the target of branch instructions
can be labeled with the letter 'B'.</p>
<p>The <samp>auto-label style</samp> setting determines the format for
labels that are generated automatically. By default the label will be
the letter 'L' followed by the hexadecimal address, but the label can
be annotated based on usage. For example, addresses that are the target
of branch instructions can be labeled with the letter 'B'.</p>
<h3><a name="projprop-projsym">Project Symbols</a></h3>
<h3 id="projprop-projsym">Project Symbols</h3>
<p>You can add, edit, and delete individual symbols and constants.
See the <a href="intro-details.html#about-symbols">symbols</a> section for an
explanation of how project symbols work.</p>
<p>The Edit Symbol button opens the
<p>The <samp>Edit Symbol</samp> button opens the
<a href="editors.html#project-symbol">Edit Project Symbol</a> dialog, which
allows changing any part of a symbol definition. You're not allowed to
create two symbols with the same label.</p>
<p>The Import button allows you to import symbols from another project.
Only labels that have been tagged as global and exported will be imported.
Existing symbols with identical labels will be replaced, so it's okay to
run the importer multiple times. Labels that aren't found will not be
removed, so you can safely import from multiple projects, but will need
to manually delete any symbols that are no longer being exported.</p>
<p>The <samp>Import</samp> button allows you to import symbols from
another project. Only labels that have been tagged as global and
exported will be imported. Existing symbols with identical labels will
be replaced, so it's okay to run the importer multiple times. Labels
that aren't found will not be removed, so you can safely import from
multiple projects, but will need to manually delete any symbols that are
no longer being exported.</p>
<p>Shortcut: you can open the project properties window with the
Project Symbols tab selected by hitting F6 from the main code list.</p>
<h3><a name="projprop-symfiles">Symbol Files</a></h3>
<h3 id="projprop-symfiles">Symbol Files</h3>
<p>From here, you can add and remove platform symbol files, or change
the order in which they are loaded.
See the <a href="intro-details.html#about-symbols">symbols</a> section for an
@ -356,11 +362,11 @@ other people, but also acts as a minor security check, to prevent a
wayward project from trying to open files it shouldn't.</p>
<p>Click one of the "Add Symbol Files" buttons to include one or more
symbol files in the project.
The "Add Symbol Files from Runtime" button sets the directory
to the SourceGen RuntimeData directory, while "Add Symbol Files from Project"
starts in the project directory. If you haven't yet saved the project,
the latter button will be disabled. The only difference between the
buttons is the initial directory.</p>
The <samp>Add Symbol Files from Runtime</samp> button sets the directory
to the SourceGen RuntimeData directory, while
<samp>Add Symbol Files from Project</samp> starts in the project directory.
If you haven't yet saved the project, the latter button will be disabled.
The only difference between the buttons is the initial directory.</p>
<p>In the list, files loaded from the RuntimeData directory will be
prefixed with <code>RT:</code>. Files loaded from the project directory
will be prefixed with <code>PROJ:</code>.</p>
@ -368,7 +374,7 @@ will be prefixed with <code>PROJ:</code>.</p>
you will receive a warning.</p>
<h3><a name="projprop-extscripts">Extension Scripts</a></h3>
<h3 id="projprop-extscripts">Extension Scripts</h3>
<p>From here, you can add and remove extension script files.
See the <a href="advanced.html#extension-scripts">extension scripts</a>
section for details on how extension scripts work.</p>
@ -379,11 +385,11 @@ is mostly to keep things manageable when projects are distributed to
other people, but also acts as a minor security check, to prevent a
wayward project from trying to open files it shouldn't.</p>
<p>Click one of the "Add Scripts" buttons to include one more scripts in
the project. The "Add Scripts from Runtime" button sets the directory
to the SourceGen RuntimeData directory, while "Add Scripts from Project"
starts in the project directory. If you haven't yet saved the project,
the latter button will be disabled. The only difference between the
buttons is the initial directory.</p>
the project. The <samp>Add Scripts from Runtime</samp> button sets
the directory to the SourceGen RuntimeData directory, while
<samp>Add Scripts from Project</samp> starts in the project directory.
If you haven't yet saved the project, the latter button will be disabled.
The only difference between the buttons is the initial directory.</p>
<p>In the list, files loaded from the RuntimeData directory will be
prefixed with <code>RT:</code>. Files loaded from the project directory
will be prefixed with <code>PROJ:</code>.</p>

102
docs/sgmanual/tools.html
View File

@ -1,18 +1,23 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Tools - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Tools - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Tools</h1>
<h1>SourceGen: Tools</h1>
<h2><a name="instruction-chart">Instruction Chart</a></h2>
<p>The <samp>Tools</samp> menu offers a selection of useful tools that
operate independently of the current project (if any).</p>
<h2 id="instruction-chart">Instruction Chart</h2>
<p>This opens a window with a summary of all 256 opcodes. The CPU can
be chosen from the pop-up list at the bottom. Undocumented opcodes for
@ -20,10 +25,11 @@ be chosen from the pop-up list at the bottom. Undocumented opcodes for
by unchecking the box at the bottom.</p>
<p>The status flags affected by each instruction reflect their behavior
on the 65816. The only significant difference between 65816 and
6502/65C02 is the way the BRK instruction affects the D and B/X flags.</p>
6502/65C02 is the way the <code>BRK</code> instruction affects the
D and B/X flags.</p>
<h2><a name="ascii-chart">ASCII Chart</a></h2>
<h2 id="ascii-chart">ASCII Chart</h2>
<p>This opens a window with the ASCII character set. Each character is
displayed next to its numeric value in decimal and hexadecimal. The
@ -31,7 +37,7 @@ pop-up list at the bottom allows you to flip between standard and "high"
ASCII.</p>
<h2><a name="apple2-screen-chart">Apple II Screen Chart</a></h2>
<h2 id="apple2-screen-chart">Apple II Screen Chart</h2>
<p>The Apple II text and hi-res screens are mapped to memory in a way
that makes sense to computers but is a little confusing for humans. This
@ -39,61 +45,63 @@ chart maps line numbers to addresses and vice-versa. Select different
screens and sort orders from the list at the bottom.</p>
<h2><a name="hexdump">Hex Dump Viewer</a></h2>
<h2 id="hexdump">Hex Dump Viewer</h2>
<p>You can use this to view the contents of the project data file
by double-clicking the "bytes" column, or with Actions &gt; Show Hex Dump.
by double-clicking the values in the "Bytes" column, or with
<samp>Actions &gt; Show Hex Dump</samp>.
The viewer is displayed in a "modeless" dialog that does not
prevent you from continuing to work with the project. If you
double-click a different line in the project, the viewer will automatically
highlight those bytes.</p>
<p>You can also use this to view the contents of arbitrary files by
using Tools &gt; Hex Dump. There is no fixed limit on the number of
<p>You can also view the contents of arbitrary files by using
<samp>Tools &gt; Hex Dump</samp>. There is no fixed limit on the number of
viewers you can have open simultaneously. (Be aware that the viewer
currently loads the entire file into memory, and you will run out of room
eventually. Not coincidentally, the viewer has a size limit of 16MiB
per file.)</p>
<p>You can select lines with the mouse as you would in any other list
view. Ctrl+A selects all lines. Ctrl+C copies the selected lines to
view. <kbd class="key">Ctrl+A</kbd> selects all lines.
<kbd class="key">Ctrl+C</kbd> copies the selected lines to
the system clipboard.</p>
<p>The "character conversion" selector allows you to choose how the
bytes are converted to characters for the Text column. Choose from
the usual set of encodings.</p>
<p>If "ASCII-only dump" is not checked, non-printable bytes are shown in
the ASCII dump as a middle dot ('&#183;'). If the box is checked,
non-printable bytes are represented by a period ('.') instead. The
use of non-ASCII characters makes the dump unambiguous when unprintable
<p>If <samp>ASCII-only dump</samp> is not checked, non-printable bytes
are shown in the ASCII dump as a middle dot ('&#183;'). If the option is
checked, non-printable bytes are represented by a period ('.') instead.
The use of non-ASCII characters makes the dump unambiguous when unprintable
characters are mixed with periods, but the lines may be unsuitable for
pasting in some forums.</p>
<p>If "always on top" is checked, the window will stay above all other
windows that don't also declare that they should always be on top. By
default this box is checked when displaying project data, and not checked for
external files.</p>
<p>If <samp>always on top</samp> is checked, the window will stay above
all other windows that don't also declare that they should always be on
top. By default this box is checked when displaying project data, and
not checked for external files.</p>
<h2><a name="file-concat">File Concatenator</a></h2>
<h2 id="file-concat">File Concatenator</h2>
<p>The File Concatenator combines multiple files into a single file.
Select the files to add, arrange them in the proper order, then hit
"Save". CRC-32 values are shown for reference.</p>
<samp>Save</samp>. CRC-32 values are shown for reference.</p>
<h2><a name="file-slicer">File Slicer</a></h2>
<h2 id="file-slicer">File Slicer</h2>
<p>The File Slicer allows you to "slice" a piece out of a file, saving
it to a new file. Specify the start and length in decimal or hex. If
you leave a field blank, they will default to offset 0 and the remaining
length of the file, respectively.</p>
<p>The hex dumps show the area just before and after the chunk to be
sliced, allowing you to confirm the placement.</p>
sliced, allowing you to confirm the positions.</p>
<h2><a name="omf-converter">OMF Converter</a></h2>
<h2 id="omf-converter">OMF Converter</h2>
<p>This tool allows you to view Apple IIgs Object Module Format (OMF)
executables, and convert them for disassembly.</p>
@ -107,34 +115,34 @@ The loaded image is saved to a new file, and a SourceGen project file is
created with some basic attributes filled in.</p>
<p>Only "Load" files (S16, PIF, TOL, etc) may be converted. Compiler object
files and libraries contain references that must be resolved by
files and libraries (OBJ, LIB) contain references that must be resolved by
a IIgs linker, and are not supported.</p>
<p>Before you can examine or convert a file, you must first extract
it from the Apple II disk image, using a mode that does not modify the
original (e.g. extract with "configure to preserve Apple II formats"
in CiderPress). Then, open it with the "Tools &gt; Convert OMF".</p>
in CiderPress). Then, open it with <samp>Tools &gt; Convert OMF</samp>.</p>
<p>The initial view shows all of the OMF segments in the file. Double-clicking
on an entry opens a detailed view that shows the segment header and a
list of all the OMF records. For load files, the relocation dictionary is
also shown.</p>
<p>To convert the file, click "Generate" to create a modified binary and a
SourceGen project file.</p>
<p>To convert the file, click <samp>Generate</samp> to create a
modified binary and a SourceGen project file.</p>
<p>If "offset segment start by $0100" is checked, the converter will try
to shift the segment's load address from <code>$xx/0000</code> to
<code>$xx/0100</code>. This can make the generated code a little nicer
to work with because it removes potential ambiguity with direct page
addresses. For example, <code>LDA $56</code> and <code>LDA $0056</code>
may be interpreted as the same thing by the assembler, requiring
generation of operand width disambiguators. By shifting the initial
address we avoid the potential ambiguity.</p>
<p>Check "add comments and notes for each segment" to add a long comment
and a note at the start of each segment. The comments include the
segment name, type, and optional flags. The notes just provide a quick
way to jump to a segment.</p>
<p>If <samp>offset segment start by $0100</samp> is checked, the
converter will try to shift the segment's load address from
<code>$xx/0000</code> to <code>$xx/0100</code>. This can make the
generated code a little nicer to work with because it removes potential
ambiguity with direct page addresses. For example, <code>LDA $56</code>
and <code>LDA $0056</code> may be interpreted as the same thing by the
assembler, requiring generation of operand width disambiguators. By
shifting the initial address we avoid the potential ambiguity.</p>
<p>Check <samp>add comments and notes for each segment</samp> to add a
long comment and a note at the start of each segment. The comments
include the segment name, type, and optional flags. The notes just
provide a quick way to jump to a segment.</p>
<p>The binary generated by the tool is not in OMF format and will not
execute on an Apple IIgs. To be functional, the generated sources must be
@ -142,8 +150,8 @@ assembled by a program capable of generating OMF output, such as Merlin.</p>
<p>The <a href="advanced.html#reloc-data">relocation dictionaries</a> from
the executable are included in the project file, and can be used to guide
the disassembler's analysis. The "use reloc data" setting in the project
properties controls this feature.</p>
the disassembler's analysis. The <samp>use reloc data</samp> setting in
the project properties controls this feature.</p>
<p>A full explanation of the structure of OMF is beyond the scope of this
manual. For more information on OMF, see Appendix F of the GS/OS Reference

17
docs/sgmanual/tutorials.html
View File

@ -1,18 +1,19 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Tutorials - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Tutorials - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Tutorials</h1>
<h1>SourceGen: Tutorials</h1>
<p><strong>NOTE:</strong> this tutorial has been replaced by
<p><strong>NOTE:</strong> this page has been replaced by
content on the 6502bench web site. Visit
<a href="https://6502bench.com/sgtutorial/">https://6502bench.com/sgtutorial/</a>.</p>
</div>

82
docs/sgmanual/visualization.html
View File

@ -1,19 +1,20 @@
<!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">
<!DOCTYPE html>
<html lang="en">
<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>Visualizations - 6502bench SourceGen</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="main.css"/>
<title>Visualizations - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Visualizations</h1>
<h1>SourceGen: Visualizations</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="overview">Overview</a></h2>
<h2 id="overview">Overview</h2>
<p>Programs are generally a combination of code and data. Sometimes
the data is graphical in nature, e.g. a bitmap used as a font or
@ -48,7 +49,7 @@ write a script that generates random flowers, and use it to make your
source listings more cheerful.</p>
<h2><a name="vis-and-sets">Visualizations and Visualization Sets</a></h2>
<h2 id="vis-and-sets">Visualizations and Visualization Sets</h2>
<p>Visualizations are essentially decorative: they do not affect the
assembled output, and do not change how code is analyzed. They are
@ -60,17 +61,17 @@ You can display a visualization near the data or near the instructions
that perform the drawing. Or both.</p>
<p>To create a visualization set, select a code or data line, and use
Actions &gt; Create/Edit Visualization Set. To edit a visualization set,
select it and use the same menu item, or just double-click on it. This
opens the Visualization Set Editor window.</p>
<samp>Actions &gt; Create/Edit Visualization Set</samp>. To edit
a visualization set, select it and use the same menu item, or just
double-click on it. This opens the Visualization Set Editor window.</p>
<p>The visualization set editor shows a list of visualizations associated
with the selected file offset. You can create a new visualization, edit
or remove an existing entry, or rearrange them.
If you select "New Bitmap" or edit an existing bitmap entry, the
If you select <samp>New Bitmap</samp> or edit an existing bitmap entry, the
Bitmap Visualization Editor window will open.
Similarly, if you select "New Bitmap Animation" or edit an existing
bitmap animation, the Bitmap Animation Editor will open.</p>
Similarly, if you select <samp>New Bitmap Animation</samp> or edit an
existing bitmap animation, the Bitmap Animation Editor will open.</p>
<h4>Visualization Editor</h4>
@ -79,7 +80,7 @@ generator defined by an active extension script. Select the one that is
appropriate for the data you're trying to visualize. Every visualizer may
have different parameters, so as you select different entries the set of
input parameters below the preview window may change.</p>
<p>There are two categorizes of visualization generator: bitmap, and
<p>There are two categories of visualization generator: bitmap, and
wireframe. Bitmaps are simple 2D images, but wireframes are 2D or 3D
meshes that can be viewed from different angles. When you select a
wireframe generator, additional view controls will be added at the bottom.
@ -101,8 +102,8 @@ the former a text entry field that accepts decimal and hexadecimal values.
The range of allowable values is shown to the right of the entry field.
If you enter an invalid value, the parameter description will turn red.</p>
<p>The "Export" button at the top right can be used to save a copy of
the bitmap or wireframe rendering with the current parameters.</p>
<p>The <samp>Export</samp> button at the top right can be used to save a
copy of the bitmap or wireframe rendering with the current parameters.</p>
<h5>Wireframe View Controls</h5>
@ -122,12 +123,13 @@ about which rotations are performed points toward the viewer. The
rotations are performed with a matrix using Euler angles, and are
subject to gimbal lock (e.g. if you set Y to 90 degrees, X and Z rotate
about the same axis).</p>
<p>If you check the "Animated" box, you can add a simple spin. Choose
the number of degrees to rotate per frame, how many frames to generate before
resetting, and the delay between each frame. Clicking the "Auto" button
will automatically select the number of frames needed to display the
animation in an unbroken loop (useful for animated GIFs). Click
the "Test Animation" button to see it in action.</p>
<p>If you check the <samp>Animated</samp> box, you can add a simple spin.
Choose the number of degrees to rotate per frame, how many frames to
generate before resetting, and the delay between each frame. Clicking
the <samp>Auto</samp> button will automatically select the number of
frames needed to display the animation in an unbroken loop (useful
for animated GIFs). Click the <samp>Test Animation</samp> button to
see it in action.</p>
<h4>Bitmap Animation Editor</h4>
@ -137,15 +139,15 @@ stores animated graphics as a series of frames.</p>
<p>The "tag" is a unique string that will be shown in the display list.
The same rules apply as for bitmap visualizations.</p>
<p>The list at the top left holds all visualizations. Select items on
the left and use the "Add" button to add them to the list on the right,
which has the set that is included in the animation. You can reorder
the list with the up/down buttons. Adding the same frame multiple times
is allowed.</p>
<p>The "frame delay" field lets you specify how long each frame is shown
on screen, in milliseconds. Some animation formats may use a different
time resolution; for example, animated GIFs use units of 1/100th of a
second. The closest value will be used. Note also that some viewers
(notably web browsers) will cap the update rate.</p>
the left and use the <samp>Add</samp> button to add them to the list on
the right, which has the set that is included in the animation. You
can reorder the list with the up/down buttons. Adding the same frame
multiple times is allowed.</p>
<p>The <samp>frame delay</samp> field lets you specify how long each
frame is shown on screen, in milliseconds. Some animation formats may
use a different time resolution; for example, animated GIFs use units
of 1/100th of a second. The closest value will be used. Note also
that some viewers (notably web browsers) will cap the update rate.</p>
<p>When you have one or more frames in the animation list, you can preview
the result in the window at the bottom. The actual appearance may be
slightly different, especially if the frames are different sizes. For
@ -153,7 +155,7 @@ example, the preview window scales individual frames, but animated GIFs
will be scaled to the size of the largest frame.</p>
<h2><a name="runtime">Scripts Included with SourceGen</a></h2>
<h2 id="runtime">Scripts Included with SourceGen</h2>
<p>A number of visualization generation scripts are included with
SourceGen, in the platform-specific runtime data directories.</p>
@ -184,7 +186,7 @@ results do not need to be perfectly accurate to be useful when disassembling
code.</p>
<h3>Apple II - Apple/VisHiRes and Apple/VisShapeTable</h3>
<h3>Apple II : Apple/VisHiRes and Apple/VisShapeTable</h3>
<p>There is no standard format for small hi-res bitmaps, but certain
arrangements are common. The VisHiRes script defines four generators:</p>
@ -227,7 +229,7 @@ have multiple vector shapes. The only parameter other than the offset
is the shape number.</p>
<h3>Atari 2600 - Atari/Vis2600</h3>
<h3>Atari 2600 : Atari/Vis2600</h3>
<p>The Atari 2600 graphics system has registers that determine the
appearance of a sprite or playfield on a single row. The register
@ -249,7 +251,7 @@ straightforward fashion.</p>
repeated as-is or flipped.</li>
</ul>
<h3>Atari Arcade - Atari/VisAVG </h3>
<h3>Atari Arcade : Atari/VisAVG</h3>
<p>Different versions of Atari's Analog Vector Graphics were used in
several games, notably Battlezone, Tempest, and Star Wars. The commands
@ -260,9 +262,9 @@ well as lines, but works fine for annotating a disassembly.</p>
the commands to visualize, and the base address of vector RAM. The latter
is necessary to convert AVG JMP/JSR commands into offsets.</p>
<h3>Commodore 64 - Commodore/VisC64</h3>
<h3>Commodore 64 : Commodore/VisC64</h3>
<p>The Commodore 64 has a 64-bit sprite format defined by the hardware.
<p>The Commodore 64 has a 64-byte sprite format defined by the hardware.
It comes in two basic varieties:</p>
<ul>
<li><b>High-resolution sprite</b> - 24x21 monochrome. Pixels are either
@ -295,7 +297,7 @@ It comes in two basic varieties:</p>
a sprite that is doubled in both width and height will look exactly like
a sprite that is not doubled at all.</p>
<h3>Nintendo Entertainment System - Nintendo/VisNES</h3>
<h3>Nintendo Entertainment System : Nintendo/VisNES</h3>
<p>NES PPU pattern tables hold 8x8 tiles with 2 bits of color per pixel.
Converting the full collection to a reference bitmap is straightforward.