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

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 a saved project. A file with the same name plus a ".dis65" extension will
be opened as the project file. 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 ### ### Execution ###
With debug features enabled, you can open the test runner from the menu 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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <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> <link rel="stylesheet" href="main.css"/>
<title>Advanced Topics - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <div id="content">
<h1>6502bench SourceGen: Advanced Topics</h1> <h1>SourceGen: Advanced Topics</h1>
<p><a href="index.html">Back to index</a></p> <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 <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 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 <p>If there are multiple masked values for a given address, the precedence
is undefined.</p> is undefined.</p>
<p>To disable the MULTI_MASK and resume normal declarations, write the <p>To disable the MULTI_MASK and resume normal declarations, write the
tag without arguments: tag without arguments:</p>
<pre> *MULTI_MASK</pre></p> <pre> *MULTI_MASK</pre>
<h3>Creating a Project-Specific Symbol File</h3> <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> 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 <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 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 <li><code>InNR_</code> : non-returning call (i.e. the JSR acts like
a JMP)</li> a JMP)</li>
</ul> </ul>
</p>
<p>Anything more complicated will require a custom script.</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> 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 <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 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 the best way to deal with this is to concatenate the files into a single
file, and operate on that.</p> 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 <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 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, 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> 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, <p><i>This feature is considered experimental. Some features,
like cross-reference tracking, may not work correctly with it.</i></p> 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> independent 16-bit addresses, and the immediate values as constants:</p>
<pre> <pre>
.dbank $02 .dbank $02
02/317c: f4 02 00 L2317C pea L20002 & $ffff 02/317c: f4 02 00 L2317C pea L20002 &amp; $ffff
02/317f: f4 54 32 pea L23254 & $ffff 02/317f: f4 54 32 pea L23254 &amp; $ffff
02/3182: a2 0c 20 ldx #WriteCString 02/3182: a2 0c 20 ldx #WriteCString
02/3185: 22 00 00 e1 jsl Toolbox 02/3185: 22 00 00 e1 jsl Toolbox
02/3189: a9 00 00 L23189 lda #$0000 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/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> </pre>
<p>Worse yet, those <code>STA</code> instruction operands would have been <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. 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 immediate values are addresses rather than constants. And we can do this
even without setting the DBR.</p> even without setting the DBR.</p>
<pre> <pre>
02/317c: f4 02 00 L2317C pea L23254 >> 16 02/317c: f4 02 00 L2317C pea L23254 &gt;&gt; 16
02/317f: f4 54 32 pea L23254 & $ffff 02/317f: f4 54 32 pea L23254 &amp; $ffff
02/3182: a2 0c 20 ldx #WriteCString 02/3182: a2 0c 20 ldx #WriteCString
02/3185: 22 00 00 e1 jsl Toolbox 02/3185: 22 00 00 e1 jsl Toolbox
02/3189: a9 00 00 L23189 lda #L30000 & $ffff 02/3189: a9 00 00 L23189 lda #L30000 &amp; $ffff
02/318c: 8d 78 3f sta L23F78 & $ffff 02/318c: 8d 78 3f sta L23F78 &amp; $ffff
02/318f: a9 03 00 lda #L30000 >> 16 02/318f: a9 03 00 lda #L30000 &gt;&gt; 16
02/3192: 8d 7a 3f sta L23F78 & $ffff +2 02/3192: 8d 7a 3f sta L23F78 &amp; $ffff +2
</pre> </pre>
<p>The absence of relocation data can be a useful signal as well. For <p>The absence of relocation data can be a useful signal as well. For
example, when pushing arguments for a toolbox call, the disassembler example, when pushing arguments for a toolbox call, the disassembler
@ -449,10 +449,10 @@ relocated. Consider this bit of source code:</p>
<pre> <pre>
02/0aa8: a5 42 lda $42 02/0aa8: a5 42 lda $42
02/0aaa: 48 pha 02/0aaa: 48 pha
02/0aab: f4 02 00 pea L20002 & $ffff 02/0aab: f4 02 00 pea L20002 &amp; $ffff
02/0aae: f4 03 31 pea L23103 & $ffff 02/0aae: f4 03 31 pea L23103 &amp; $ffff
02/0ab1: f4 05 00 pea L20005 & $ffff 02/0ab1: f4 05 00 pea L20005 &amp; $ffff
02/0ab4: f4 00 00 pea L20000 & $ffff 02/0ab4: f4 00 00 pea L20000 &amp; $ffff
02/0ab7: a2 0b 26 ldx #Int2Dec 02/0ab7: a2 0b 26 ldx #Int2Dec
02/0aba: 22 00 00 e1 jsl Toolbox 02/0aba: 22 00 00 e1 jsl Toolbox
</pre> </pre>
@ -460,8 +460,8 @@ relocated. Consider this bit of source code:</p>
<pre> <pre>
02/0aa8: a5 42 lda $42 02/0aa8: a5 42 lda $42
02/0aaa: 48 pha 02/0aaa: 48 pha
02/0aab: f4 02 00 pea L230C2 >> 16 02/0aab: f4 02 00 pea L230C2 &gt;&gt; 16
02/0aae: f4 03 31 pea L23103 & $ffff 02/0aae: f4 03 31 pea L23103 &amp; $ffff
02/0ab1: f4 05 00 pea $0005 02/0ab1: f4 05 00 pea $0005
02/0ab4: f4 00 00 pea $0000 02/0ab4: f4 00 00 pea $0000
02/0ab7: a2 0b 26 ldx #Int2Dec 02/0ab7: a2 0b 26 ldx #Int2Dec
@ -469,7 +469,7 @@ relocated. Consider this bit of source code:</p>
</pre> </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 <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 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> <p>Features:</p>
<ul> <ul>
<li>Re-analyze (F5). Causes a full re-analysis. Useful if you think <li>Re-analyze (<kbd class="key">F5</kbd>). Causes a full re-analysis.
the display is out of sync.</li> Useful if you think the display is out of sync.</li>
<li>Source Generation Tests. Opens the regression test harness. See <li>Source Generation Tests. Opens the regression test harness. See
<code>README.md</code> in the SGTestData directory for more information. <code>README.md</code> in the SGTestData directory for more information.
If the regression tests weren't included in the SourceGen distribution, 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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <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> <link rel="stylesheet" href="main.css"/>
<title>Instruction and Data Analysis - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <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><a href="index.html">Back to index</a></p>
<p><i>This section discusses the internal workings of SourceGen. It is <p><i>This section discusses the internal workings of SourceGen. It is
not necessary to understand this to use the program.</i></p> 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 <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 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> 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 <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 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> 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 <p>The analysis pass always considers the current state of the user
data structures. Whether you're adding a label or removing one, the 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> 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 <p>The code tracer walks through the instructions, examining them to
determine where execution will proceed next. There are five possibilities 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> 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 <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 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> 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 <p>The data analyzer performs two tasks. It matches operands with
offsets, and it analyzes uncategorized data. This behavior can be offsets, and it analyzes uncategorized data. This behavior can be
modified in the 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> if they're associated with the first (opcode) byte of an instruction.</p>
<p>The uncategorized data analyzer tries to find character strings and <p>The uncategorized data analyzer tries to find character strings and
opportunities to use the ".FILL" operation. It breaks the file into opportunities to use the "<code>.FILL</code>" operation. It breaks the file
pieces, where contiguous regions hold nothing but data, are not split into pieces where contiguous regions hold nothing but data, are not split
across address region start/end directives, are not interrupted by data, across address region start/end directives, are not interrupted by labels,
and do not contain anything that the user has chosen to format. Each 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 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 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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <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> <link rel="stylesheet" href="main.css"/>
<title>Code Generation &amp; Assembly - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <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><a href="index.html">Back to index</a></p>
<p>SourceGen can generate an assembly source file that, when fed into <p>SourceGen can generate an assembly source file that, when fed into
the target assembler, will recreate the original data file exactly. the target assembler, will recreate the original data file exactly.
Every assembler is different, so support must be added to SourceGen Every assembler is different, so support must be added to SourceGen
for each.</p> 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 <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. 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>. 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 <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 generators may produce multiple source files, perhaps a link script or
symbol definition header to go with the assembly source. To avoid symbol definition header to go with the assembly source. To avoid
spreading files across the filesystem, SourceGen does all of its work 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 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> 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 <p>The <samp>Generate and Assemble</samp> dialog has a drop-down list near
that lets you pick which assembler to target. The name of the assembler the top that lets you pick which assembler to target. The name of the
will be shown with the detected version number. If the assembler assembler will be shown with the detected version number. If the assembler
executable isn't configured, "[latest version]" will be shown instead executable isn't configured, "<samp>[latest version]</samp>" will be
of a version number.</p> shown instead of a version number.</p>
<p>The Settings button will take you directly to the assembler configuration <p>The <samp>Settings</samp> button will take you directly to the
tab in the application settings dialog.</p> 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>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 The file will use the project name, with the <code>.dis65</code> extension
replaced by <code>_&lt;assembler&gt;.S</code>.</p> replaced by <code>_&lt;assembler&gt;.S</code>.</p>
<p>The first 64KiB of each generated file will be shown in the preview <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 <p>The label localizer is an optional feature that automatically converts
some labels to an assembler-specific less-than-global label format. Local some labels to an assembler-specific less-than-global label format. Local
labels may be reusable (e.g. using "]LOOP" for multiple consecutive labels may be reusable (e.g. using "<code>@LOOP</code>" for multiple
loops is easier to understand than giving each one a unique label) or consecutive loops is easier to understand than giving each one a unique
reduce the size of a generated link table. There are usually restrictions label) or reduce the size of a generated link table. There are usually
on local labels, e.g. references to them may not be allowed to cross a restrictions on local labels, e.g. references to them may not be allowed
global label definition, which the localizer factors in automatically.</p> 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 <p>Some label names aren't allowed. For example, 64tass reserves the
use of labels that begin with two underscores. Most assemblers will use of labels that begin with two underscores. Most assemblers will
also prevent you from using opcode mnemonics as labels (which means 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 <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> 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 <p>SourceGen needs to be able to assemble binaries for any system
with any assembler, so it generally avoids platform-specific features. with any assembler, so it generally avoids platform-specific features.
One exception to that is C64 PRG files.</p> 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> 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 <p>After generating sources, if you have a cross-assembler executable
configured, you can run it by clicking the "Run Assembler" button. The configured, you can run it by clicking the <samp>Run Assembler</samp> button.
command-line output will be displayed, with stdout and stderr separated. 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 (I'd prefer them to be interleaved, but that's not what the system
provides.)</p> provides.)</p>
<p>The output will show the assembler's exit code, which will be zero <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, SourceGen will then compare the assembler's output to the original file,
and report any differences.</p> and report any differences.</p>
<p>Failures here may be due to bugs in the cross-assembler or in <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> 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> <p>SourceGen currently supports the following cross-assemblers:</p>
<ul> <ul>
@ -125,7 +130,7 @@ so any failure is an opportunity for improvement.</p>
<li><a href="#merlin32">Merlin 32</a></li> <li><a href="#merlin32">Merlin 32</a></li>
</ul> </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 <p>Code generation must be tailored to the specific version of the
assembler. This is most easily understood with an example.</p> 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 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 that forever. We want to detect which version of the assembler is in
use, and output actual <code>MVN</code>/<code>MVP</code> instructions 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 <p>When you configure a cross-assembler, SourceGen runs the executable with
version query args, and extracts the version information from the output version query arguments, and extracts the version information from the output
stream. This is used by the generator to ensure that the output will compile. stream. This is used by the generator to ensure that the output will work
If no assembler is configured, SourceGen will produce code optimized correctly with the installed assembler.
for the latest version of the assembler.</p> 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 <p>This is a list of bugs and quirky behavior in cross-assemblers that
SourceGen works around when generating code.</p> 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 to understand expression syntax and operator precedence to generate correct
code, but also needs to know how to handle the corner cases.</p> 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 <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> <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 character ('`') rather than the caret ('^'). (There's a note in the
docs to the effect that they plan to move to carets.)</li> docs to the effect that they plan to move to carets.)</li>
<li>Instructions whose argument is formed by combining with the <li>Instructions whose argument is formed by combining with the
65816 Program Bank Register (16-bit JMP/JSR) must be specified 65816 Program Bank Register (16-bit <code>JMP</code>/<code>JSR</code>)
as 24-bit values for code that lives outside bank 0. This is must be specified as 24-bit values for code that lives outside bank 0.
true for both symbols and raw hex (e.g. <code>JSR $1234</code> 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 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 0 from outside bank 0 causes an error, even though it is technically
a 16-bit operand.</li> a 16-bit operand.</li>
@ -218,7 +237,7 @@ code, but also needs to know how to handle the corner cases.</p>
</ul> </ul>
<h3><a name="acme">ACME</a></h3> <h3 id="acme">ACME</h3>
<p>Tested versions: v0.96.4, v0.97 <p>Tested versions: v0.96.4, v0.97
<a href="https://sourceforge.net/projects/acme-crossass/">[web site]</a></p> <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 outside bank zero cannot be assembled. SourceGen currently deals with
this by outputting the entire file as a hex dump.</li> this by outputting the entire file as a hex dump.</li>
<li>Undocumented opcode $AB (<code>LAX #imm</code>) generates an error.</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> </ul>
<p>Quirks:</p> <p>Quirks:</p>
@ -262,7 +281,7 @@ code, but also needs to know how to handle the corner cases.</p>
</ul> </ul>
<h3><a name="cc65">cc65</a></h3> <h3 id="cc65">cc65</h3>
<p>Tested versions: v2.17, v2.18 <p>Tested versions: v2.17, v2.18
<a href="https://cc65.github.io/">[web site]</a></p> <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>. more common interpretation would be <code>label &gt;&gt; (8 - 16)</code>.
(This is actually somewhat convenient, since none of the expressions (This is actually somewhat convenient, since none of the expressions
SourceGen currently generates require parenthesis.)</li> SourceGen currently generates require parenthesis.)</li>
<li>Undocumented opcode <code>SBX</code> ($cb) uses the mnemonic AXS. All <li>Undocumented opcode <code>SBX</code> ($cb) uses the mnemonic
other opcodes match up with the "unintended opcodes" document.</li> <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 <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 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 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> </ul>
<h3><a name="merlin32">Merlin 32</a></h3> <h3 id="merlin32">Merlin 32</h3>
<p>Tested Versions: v1.0 <p>Tested Versions: v1.0
<a href="https://www.brutaldeluxe.fr/products/crossdevtools/merlin/">[web site]</a> <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 <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 and converts it to text or HTML. The options you've set in the app
settings, such as capitalization, text delimiters, pseudo-opcode names, 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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Editors - 6502bench SourceGen</title> <link rel="stylesheet" href="main.css"/>
<title>Editors - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <div id="content">
<h1>6502bench SourceGen: Editors</h1> <h1>SourceGen: Editors</h1>
<p><a href="index.html">Back to index</a></p> <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> <p><a href="intro-details.html#address-regions">Address regions</a>
may be created, edited, resized, or removed. Which 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" <p>To see detailed information about an address region in the "Info"
window, select the region start or end directive. You can see the window, select the region start or end directive. You can see the
current arrangement of address regions across your entire 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 <p>The state of the processor status flags are tracked for every
instruction. Each individual flag is recorded as zero, one, or 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> 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 <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 <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 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> <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 <p>Operands can be formatted explicitly, or you can let the disassembler
select the format for you. By default, immediate constants and select the format for you. By default, immediate constants and
addresses with no matching symbol are formatted as hex. Symbols addresses with no matching symbol are formatted as hex. Symbols
defined as address labels, platform/project symbols, and local defined as address labels, platform/project symbols, and local
variables will be identified and applied automatically.</p> 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 <p>Operands can be displayed in a variety of numeric formats, or as a
symbol. The character formats are only available for operands symbol. The character formats are only available for operands
whose value falls into the proper range. The ASCII format handles 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 <p>The bottom part of the window has some shortcuts for working with
address references and local variables. These are primarily used to 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 don't cause any changes to the recorded format of the instruction
being edited. All of the actions can be performed elsewhere, by being edited. All of the actions can be performed elsewhere, by
editing the label at the target address, editing the project symbol editing the label at the target address, editing the project symbol
set, or editing a local variable table.</p> 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 <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 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 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 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. 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 You can create or modify a project symbol by clicking on
Symbol" or "Edit Project Symbol". You can't delete project symbols <samp>Create Project Symbol</samp> or <samp>Edit Project Symbol</samp>.
from this editor (use Project Properties instead).</p> 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 <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 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 same address, the first one found will be used, which may not be
what is desired. In such situations, you should create the project 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 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 (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 symbol is deleted or renamed, you'll have operands that refer to a
nonexistent symbol. Unlike labels, project symbol renames do not nonexistent symbol. Unlike labels, project symbol renames do not
refactor the rest of the project.) 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 <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 requires that a local variable table has been defined at or before
the instruction being edited.</p> the instruction being edited.</p>
<p>If an existing entry is found, you will be able to edit the name <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 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 <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 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 <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> 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 <p>The <samp>Simple Data</samp> items behave the same as their equivalents
Edit Operand dialog. However, because the width is not determined by in the Edit Operand (Instruction) dialog. However, because the width is
an instruction opcode, and multiple items can be selected, you will need not determined by an instruction opcode, and multiple items can be selected,
to specify how wide each item is and what its byte order is. For data you will need to specify how wide each item is and what its byte order is.
you also have the option of setting the format to "Address", which marks For data you also have the option of setting the format to
the selected bytes as a numeric reference.</p> <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 <p>Consider a simple example: suppose you find a table of 16-bit
addresses in the code. Click on addresses in the code. Click on
the first byte, shift-click the last byte, then select the Edit Data menu the first byte, shift-click the last byte, then select the Edit Data menu
item. The number of bytes selected should be even. Select item. The number of bytes selected should be even. Select
"16-bit words, little-endian", then over to the right click on <samp>16-bit words, little-endian</samp>, then over to the right click on
"Address". When you click OK, the selected data will be formatted as a <samp>Address</samp>. When you click <samp>OK</samp>, the selected data
series of 16-bit address values. If the addresses can be resolved inside will be formatted as a series of 16-bit address values. If the addresses
the data file, each address will be assigned a label.</p> 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. <p>The <samp>Bulk Data</samp> items can represent large chunks of data
The "fill" option is only available if all selected bytes have the compactly. The <samp>Fill</samp> option is only available if all selected
same value.</p> bytes have the same value.</p>
<p>If a region of bytes is used for data storage, but the initial values <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 don't matter, you can mark it as <samp>Uninitialized data</samp>.
generated will usually use an initialized bulk data directive rather (Note that the code generated will usually use an initialized bulk data
than a "leave space" directive, because SourceGen wants to guarantee directive rather than a "leave space" directive, because SourceGen wants
that the assembled binary matches the original.)</p> to guarantee that the assembled binary matches the original.)</p>
<p>If a region of bytes is irrelevant, e.g. dead code or padding, <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 you can mark it as <samp>Junk</samp>. If it appears to be adding bytes
power-of-two address boundary, you can designate it as an alignment 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 directive. If you have multiple regions selected, only the alignment
work for all regions will be shown.</p> options that work for all regions will be shown.</p>
<p>The "String" items are enabled or disabled depending on whether the <p>The <samp>String</samp> items are enabled or disabled depending on
data you have selected is in the appropriate format. For example, whether the data you have selected is in the appropriate format. For example,
"Null-terminated strings" is only enabled if the data regions are <samp>Null-terminated strings</samp> is only enabled if the data regions are
composed entirely of characters followed by $00. Zero-length strings composed entirely of characters followed by $00. Zero-length strings
are allowed. are allowed.
DCI (Dextral Character Inverted) strings have the high bit on the last DCI (Dextral Character Inverted) strings have the high bit on the last
byte flipped; for PETSCII this will usually look like a series of 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 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 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 <p>The character encoding can be selected, offering a choice between
plain ASCII, low + high ASCII, C64 PETSCII, and C64 screen codes. When plain ASCII, low + high ASCII, C64 PETSCII, and C64 screen codes. When
you change the encoding, your available options may change. The 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> <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 <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 delete it. EOL comments may be placed on instruction and data lines, but
not on assembler directives.</p> not on assembler directives.</p>
@ -339,7 +346,7 @@ stored in the project file, and can be edited with the project symbol
editor.</p> 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 <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 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. 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> comment will have one fewer character per line in cc65 output.</p>
<p>Clear the text field to delete the comment.</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 <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 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 <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 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> 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 <p>Notes are similar to long comments, in that they can be arbitrarily
long and span multiple lines. However, because they're never included long and span multiple lines. However, because they're never included
in generated output, options like line width formatting and boxing 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> <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>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>This is used to edit the properties of a project symbol.</p>
<p>Symbols marked as "address" will be applied automatically when an <p>Symbols marked as "address" will be applied automatically when an
operand references an address outside the scope of the data file. They 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> with platform symbols and user labels.</p>
<p>The value may be entered in decimal, hexadecimal, or binary. The numeric <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 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, <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 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 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 the field is left blank, a width of 1 is assumed. Overlapping symbols
are allowed. The width is ignored for constants.</p> 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 <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 <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 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 <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 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 associated with a line of code, and are usually placed at the start of
a subroutine. a subroutine.
The "Create Local Variable Table" action creates a new table, and The <samp>Create Local Variable Table</samp> action creates a new table, and
opens the editor. The "Edit Prior Local Variable Table" searches opens the editor. The <samp>Edit Prior Local Variable Table</samp> searches
for the closest table that appears at or before the selected line, for the closest table that appears at or before the selected line,
and edits that.</p> and edits that.</p>
<p>The editor allows you to create, edit, and delete entries, as well <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 as move and delete entire tables (though these last two options are not
available when creating a new table). Empty tables are allowed. These 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 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 <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 variable has a name, a value, a width, and an optional comment. The
standard naming rules for symbols apply. Variables are only used for 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> 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 <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 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 <samp>Move Table</samp> button and enter the new offset in hex. You can
on the up/down buttons to move to the next valid offset.</p> also click on the up/down buttons to move to the next valid offset.</p>
</div> </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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <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> <link rel="stylesheet" href="main.css"/>
<title>End notes - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <div id="content">
<h1>6502bench SourceGen: End Notes</h1> <h1>SourceGen: End Notes</h1>
<p><a href="index.html">Back to index</a></p> <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 <p>The inspiration for SourceGen goes a long way back. While in high
school in the late 1980s, I read Don Lancaster's school in the late 1980s, I read Don Lancaster's
<i>Enhancing Your Apple II, Vol. 1</i> (available for download <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 (nicely reformatted
<a href="https://www.tinaja.com/ebooks/tearing_rework.pdf">here</a>). <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 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 printed it out on my Epson RX-80 -- tractor feed paper was helpful for
this sort of thing -- then set to work.</p> 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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Contents - 6502bench SourceGen</title> <link rel="stylesheet" href="main.css"/>
<title>Contents - 6502bench SourceGen</title>
</head> </head>
<body> <body>
@ -32,7 +33,7 @@ using the <samp>Help &gt; Help</samp> menu item or by hitting
<ul> <ul>
<li><a href="intro.html">Overview</a> <li><a href="intro.html">Overview</a>
<ul> <ul>
<li><a href="intro.html#fundamental-concepts">Fundamentals</a></li> <li><a href="intro.html#fundamental-concepts">Fundamentals</a>
<ul> <ul>
<li><a href="intro.html#begin">About 6502 Code</a> <li><a href="intro.html#begin">About 6502 Code</a>
<li><a href="intro.html#charenc">Character Encoding</a></li> <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> <li><a href="editors.html">Editors</a>
<ul> <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#flags">Override Status Flags</a></li>
<li><a href="editors.html#label">Edit Label</a></li> <li><a href="editors.html#label">Edit Label</a></li>
<li><a href="editors.html#instruction-operand">Edit Operand (Instruction)</a> <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> <li><a href="analysis.html#data-analysis">Data Analysis</a></li>
</ul></li> </ul></li>
<li><a href="end-notes.html">End Notes</a> </li> <li><a href="end-notes.html">End Notes</a></li>
<br/>
<!-- <!--
<li><a href="tutorials.html">Tutorials</a> <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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <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> <link rel="stylesheet" href="main.css"/>
<title>More Details - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <div id="content">
<h1>6502bench SourceGen: Intro Details</h1> <h1>SourceGen: More Details</h1>
<p><a href="index.html">Back to index</a></p> <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 <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 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> 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> <p>Suppose you have the following code:</p>
<pre> <pre>
@ -91,7 +92,7 @@ set arbitrarily. Sometimes it's easy to figure out, sometimes it has
to be specified manually.</p> 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 <p>Symbols that represent an address inside the file being disassembled
are referred to as <i>internal</i>. They come in two varieties.</p> 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> 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 <p>Symbols that represent an address outside the file being disassembled
are referred to as <i>external</i>. These may be ROM entry points, 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> 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 <p>Local variables are applied to instructions that have zero
page operands (<code>op ZP</code>, <code>op (ZP),Y</code>, etc.), or 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 <li>Tables have a "clear previous" flag that erases all previous
definitions. This doesn't usually cause anything to be generated in the definitions. This doesn't usually cause anything to be generated in the
assembly sources; instead, it just causes SourceGen to stop using assembly sources; instead, it just causes SourceGen to stop using
that label.</li> those labels.</li>
</ol> </ol>
<p>As you might expect, you're not allowed to have duplicate labels or <p>As you might expect, you're not allowed to have duplicate labels or
overlapping values in an individual table.</p> 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> 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 <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 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 DEY
BNE @LOOP BNE @LOOP
</pre> </pre>
<p>This would confuse an assembler. SourceGen already knows which @LOOP <p>This would confuse an assembler. SourceGen already knows which
is being branched to, so it can just rename one of them to "@LOOP1".</p> <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 <p>One situation where non-unique labels cause difficulty is with
weak symbolic references (see next section). For example, suppose weak symbolic references (see next section). For example, suppose
the above code then did this:</p> the above code then did this:</p>
<pre> <pre>
LDA #&lt;@LOOP LDA #&lt;@LOOP
</pre> </pre>
<p>While it's possible to make an educated guess at which @LOOP was <p>While it's possible to make an educated guess at which <code>@LOOP</code>
meant, it's easy to get wrong. In situations like this, it's best to was meant, it's easy to get wrong. In situations like this, it's best to
give the labels different names.</p> 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 <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 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 L1003 NOP
</pre> </pre>
<p>The analyzer found the JMP operand, and created an auto label for <p>The analyzer found the <code>JMP</code> operand, and created an auto
address $1003. It then created a weak reference to "L1003" in the JMP label for address $1003. It then created a weak reference to
operand.</p> "<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 <p>If you edit the <code>JMP</code> instruction's operand to use the
results are probably not what you want:</p> symbol "<code>FOO</code>", the results are probably not what you want:</p>
<pre> <pre>
.ADDRS $1000 .ADDRS $1000
JMP $1003 JMP $1003
NOP NOP
</pre> </pre>
<p>This happened because you added a weak reference to "FOO" in the operand, <p>This happened because you added a weak reference to "<code>FOO</code>"
but the label doesn't exist. The operand is formatted as hex. Because in the operand, but the label isn't defined anywhere. With no matching
there's no longer a reference to L1003, SourceGen removed the auto-label label found, the operand was formatted as hex. Further, because there's
as well.</p> 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 <p>If you set the label "<code>FOO</code>" on the <code>NOP</code>
probably wanted:</p> instruction, you'll see what you probably wanted:</p>
<pre> <pre>
.ADDRS $1000 .ADDRS $1000
JMP FOO JMP FOO
FOO NOP FOO NOP
</pre> </pre>
<p>You don't actually need the explicit reference in the JMP instruction. <p>Of course, you don't actually need the explicit reference in the
If you edit the JMP operand and set it back to "Default", the code will <code>JMP</code> instruction. If you edit the <code>JMP</code> operand
still look the same. This is because SourceGen identified the numeric and set the format back to <samp>Default</samp>, removing the weak
reference, and automatically added a symbolic reference to the label on symbolic reference, the code will still look the same.
the NOP instruction.</p> 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. <p>However, suppose you didn't actually want <code>FOO</code> as the
You can create a project symbol, BAR with the value $1003, and then edit operand label. You can create a project symbol called "<code>BAR</code>"
the operand to reference BAR instead. Your code would then look like:</p> with the value $1003, and then edit the operand to reference <code>BAR</code>
instead. Your code would then look like:</p>
<pre> <pre>
BAR .EQ $1003 BAR .EQ $1003
.ADDRS $1000 .ADDRS $1000
@ -354,9 +359,10 @@ BAR .EQ $1003
FOO NOP FOO NOP
</pre> </pre>
<p>If you change the value of BAR in the project symbol file, the operand <p>If you change the value of <code>BAR</code> in the project symbol file,
will continue to refer to it, but with an adjustment. For example, if the operand will continue to refer to it, but with an adjustment. For
you changed BAR from $1003 to $1007, the code would become:</p> example, if you changed <code>BAR</code> from $1003 to $1007,
the code would become:</p>
<pre> <pre>
BAR .EQ $1007 BAR .EQ $1007
.ADDRS $1000 .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 removed. Similarly, removing symbols from a platform or project file
will break the reference but won't modify the operands.</p> 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. <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 (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 1007: 4c3aff JMP $ff3a
</pre> </pre>
<p>This pushes the address of the JMP instruction ($1007) onto the stack, <p>This pushes the address of the <code>JMP</code> instruction ($1007)
and jumps to it with the RTS instruction. However, RTS requires the onto the stack, and jumps to it with the <code>RTS</code> instruction.
address of the byte before the target instruction, so we actually push However, <code>RTS</code> requires the address of the byte <i>before</i>
$1006.</p> the target instruction, so we actually need to push $1006.</p>
<p>The disassembler won't know that offset $1007 is code because nothing <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 appears to reference it. After tagging $1007 as a code start point, the
@ -406,8 +412,9 @@ project looks like this:</p>
JMP $ff3a JMP $ff3a
</pre> </pre>
<p>We set a label called "NEXT" on the JMP instruction, and then edit <p>We set a label called "<code>NEXT</code>" on the <code>JMP</code>
the two LDA instructions to reference the high and low parts, yielding:</p> instruction, and then edit the two <code>LDA</code> instructions to
reference the high and low parts, yielding:</p>
<pre> <pre>
.ADDRS $1000 .ADDRS $1000
LDA #&gt;NEXT 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> you're selecting the right part of the symbol.</p>
<p>Different assemblers use different syntaxes to form expressions. This <p>Different assemblers use different syntaxes to form expressions. This
is particularly noticeable in 65816 code. You can adjust how it appears is particularly noticeable in 65816 code. You can choose which syntax
on-screen from the app settings.</p> 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 <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 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> 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. <p>It's possible to interpret certain instructions in multiple ways.
For example, "LDA $0000" might be an absolute load from a 16-bit For example, "<code>LDA $0000</code>" might be an absolute load from a 16-bit
address, or it might be a direct page load from an 8-bit address. 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 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 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 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 <p>SourceGen will only add width disambiguators to opcodes or operands when
they are needed, with one exception: the opcode suffix for long they are needed, with one exception: the opcode suffix for long
(24-bit address) operations is always applied. This is done because some (24-bit address) operations is always applied. This is done because some
assemblers require it, insisting on "LDAL" rather than "LDA" for an assemblers require it, insisting on "<code>LDAL</code>" rather than
absolute long load, and because it can make 65816 code easier to read.</p> "<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 SUB_SRC
.ADDRS $2000 .ADDRS $2000
SUB_DST [small routine] SUB_DST LDY #$00
[...]
RTS
.ADREND .ADREND
CONT LDA #$12 CONT LDA #$12
JSR SUB_DST JSR SUB_DST
</pre> </pre>
<p>In this case, a small routine is copied out of the middle of the <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 code that lives at $1000. We want the code at <code>CONT</code>
things left off. If SUB_SRC is at $1009, and is 23 bytes long, then to pick up where things left off. If <code>SUB_SRC</code> is at $1009,
CONT should be $1020. We could output <code>.ADDRS $1020</code> and is 23 bytes long, then <code>CONT</code> should be $1020. We
directly before CONT, but it's inconvenient to work with the generated 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) code if we want to modify the subroutine (changing its length)
and re-assemble it.</p> 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> adjusted to match the end of the other region.</p>
<p>The arrangement of regions is particularly important when attempting <p>The arrangement of regions is particularly important when attempting
to resolve an address operand (such as a JSR) to a location within the to resolve an address operand (such as a <code>JSR</code>) to a location
file. The process is straightforward if the address only appears once, within the file. The process is straightforward if the address only
but when overlays cause multiple parts of the file to have the same appears once, but when overlays cause multiple parts of the file to have
address, the operand target may be in different places depending on where the same address, the operand target may be in different places depending
the call is being made from. on where the call is being made from.
The algorithm for resolving addresses is described The algorithm for resolving addresses is described
in the <a href="advanced.html#overlap">advanced topics</a> section.</p> 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, <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, 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 because it should never be resolved as the target of a <code>JSR</code>
handle this case, you can set a region's address to "NA". The assembler or <code>LDA</code>. To handle this case, you can set a region's address
needs to have <i>some</i> notion of address, so the start address will to "<kbd>NA</kbd>". The assembler needs to have <i>some</i> notion of
be treated as zero.</p> address, so the start address will be treated as zero.</p>
<p>Non-addressable regions cannot include executable code. You may put <p>Non-addressable regions cannot include executable code. You may put
labels on data items, but attempting to reference them will cause a 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 <p>Sometimes SourceGen can't automatically find the start or end of an
instruction stream, or gets confused by inline data. These situations 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 <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 assumes those are data. Further, the functions at those addresses may
also be considered data unless some bit of code reachable from L1009 also be considered data unless some bit of code reachable from
calls into them. If you tag $1003 and $1006 as code start points, <code>L1009</code> calls into them. If you tag $1003 and $1006 as code
you'll get better results:</p> start points, you'll get better results:</p>
<pre> <pre>
.ADDRS $1000 .ADDRS $1000
JMP L1009 JMP L1009
@ -805,9 +817,10 @@ L1009 CLC
The problem is that the bytes in the middle of the instruction have The problem is that the bytes in the middle of the instruction have
been tagged as start points, so SourceGen is treating them as been tagged as start points, so SourceGen is treating them as
embedded instructions. $EF and $12 aren't valid 6502 opcodes, so 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 they're being ignored, but $10 is <code>BPL</code> and $30 is
multiple consecutive bytes is rarely useful, SourceGen only applies code <code>BMI</code>.
start tags to the first byte in a selected line.</p> 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 <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 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 BRK $11
</pre> </pre>
<p>By tagging the BRK as a code stop point, you're telling the analyzer that <p>By tagging the <code>BRK</code> as a code stop point, you're telling the
it should stop trying to execute code when it reaches that point. (Note analyzer that it should stop trying to execute code when it reaches
that this example would actually be better solved by setting a status flag that point.
override on the BNE that sets Z=0, so the code tracer will know it's a (Note that this example would actually be better solved by setting a
branch-always and just do the right thing.) As with code start points, status flag override on the <code>BNE</code> that sets Z=0, so the code
code stop points should only be placed on the opcode byte. Placing a tracer will know it's a branch-always and just do the right thing.)
code stop point in the middle of what SourceGen believes to be instruction As with code start points, code stop points should only be placed on the
will have no effect.</p> 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 <p>As with code start points, only the first byte in each selected line will
be tagged.</p> 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> 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 <p>Extension scripts are C# source files that are compiled and
executed by SourceGen. They can be added to a project from SourceGen's 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 <p>To reduce the chances of a script causing problems, all scripts are
executed in a sandbox with severely restricted access. Notably, nothing 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> 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 contains all of the compiled script DLLs, as well as two pre-built
application DLLs that plugins are allowed access to. The contents application DLLs that plugins are allowed access to. The contents
are persistent, to avoid recompiling the scripts every time SourceGen 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> <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 <p>The on-screen code list shows assembler directives that are similar
to what the various cross-assemblers provide. The actual directives 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> <p>There are eight assembler directives that appear in the code list:</p>
<ul> <ul>
<li>.EQ - defines a symbol's value. These are generated automatically <li><code>.EQ</code> - defines a symbol's value. These are generated
when an operand that matches a platform or project symbol is found.</li> automatically when an operand that matches a platform or project
<li>.VAR - defines a local variable. These are generated for symbol is found.</li>
<li><code>.VAR</code> - defines a local variable. These are generated for
local variable tables.</li> local variable tables.</li>
<li>.ADDRS/.ADREND - specifies the start or end of an <li><code>.ADDRS</code>/<code>.ADREND</code> - specifies the start or
address region.</li> end of an address region, respectively.</li>
<li>.RWID - specifies the width of the accumulator and index registers <li><code>.RWID</code> - specifies the width of the accumulator and
(65816 only). Note this doesn't change the actual width, just tells index registers (65816 only). Note this doesn't change the actual
the assembler that the width has changed.</li> width, just tells the assembler that the width has changed.</li>
<li>.DBANK - specifies what value the Data Bank Register holds <li><code>.DBANK</code> - specifies what value the Data Bank Register holds
(65816 only). Used when matching operands to labels.</li> (65816 only). Used when matching operands to labels.</li>
<li>.DS - identifies space set aside for variable storage. The storage <li><code>.DS</code> - identifies space set aside for variable storage.
is initialized by the program before first use, so the values The storage is initialized by the program before first use, so the values
in the binary don't actually matter.</li> in the binary don't actually matter.</li>
<li>.JUNK - indicates that the data in a range of bytes is irrelevant. <li><code>.JUNK</code> - indicates that the data in a range of bytes is
(When generating sources, this will become .FILL or .BULK 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 depending on the contents of the memory region and the assembler's
capabilities.)</li> capabilities.)</li>
<li>.ALIGN - a special case of .JUNK that indicates the irrelevant <li><code>.ALIGN</code> - a special case of <code>.JUNK</code> that
bytes exist to force alignment to a memory boundary (usually a indicates the irrelevant bytes exist to force alignment to a
256-byte page). Depending on the memory contents, it may be possible memory boundary (usually a 256-byte page). Depending on the
to output this as an assembler-specific alignment directive.</li> memory contents, it may be possible to output this as an
assembler-specific alignment directive.</li>
</ul> </ul>
<p>Every data item is represented by a pseudo-op. Some of them may <p>Every data item is represented by a pseudo-op. Some of them may
represent hundreds of bytes and span multiple lines.</p> represent hundreds of bytes and span multiple lines.</p>
<ul> <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> little-endian value.</li>
<li>.DBD2, .DBD3, .DBD4 - "define big-endian data". 2-4 bytes of <li><code>.DBD2</code>, <code>.DBD3</code>, <code>.DBD4</code> - "define
big-endian data. (The 3- and 4-byte versions are not currently big-endian data". 2-4 bytes of big-endian data.
available in the UI, since they're very unusual and few assemblers (The 3- and 4-byte versions are not currently available in the UI,
support them.)</li> since they're very unusual and few assemblers support them.)</li>
<li>.BULK - data packed in as compact a form as the assembler allows. <li><code>.BULK</code> - data packed in as compact a form as the
Useful for chunks of graphics data.</li> assembler allows. Useful for things like chunks of graphics data.</li>
<li>.FILL - a series of identical bytes. The operand <li><code>.FILL</code> - a series of identical bytes. The operand
has two parts, the byte count followed by the byte value.</li> has two parts, the byte count followed by the byte value.</li>
</ul> </ul>
<p>In addition, several pseudo-ops are defined for string constants:</p> <p>In addition, several pseudo-ops are defined for string constants:</p>
<ul> <ul>
<li>.STR - basic character string.</li> <li><code>.STR</code> - basic character string.</li>
<li>.RSTR - string in reverse order.</li> <li><code>.RSTR</code> - string in reverse order.</li>
<li>.ZSTR - null-terminated string.</li> <li><code>.ZSTR</code> - null-terminated string.</li>
<li>.DSTR - Dextral Character Inverted string. The high bit of the <li><code>.DSTR</code> - Dextral Character Inverted string. The
last byte is flipped.</li> high bit of the last byte is flipped.</li>
<li>.L1STR - string prefixed with a length byte.</li> <li><code>.L1STR</code> - string prefixed with a length byte.</li>
<li>.L2STR - string prefixed with a length word.</li> <li><code>.L2STR</code> - string prefixed with a length word.</li>
</ul> </ul>
<p>You can configure the pseudo-operands to look more like what your <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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Intro - 6502bench SourceGen</title> <link rel="stylesheet" href="main.css"/>
<title>Intro - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <div id="content">
<h1>6502bench SourceGen: Intro</h1> <h1>SourceGen: Intro</h1>
<p><a href="index.html">Back to index</a></p> <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 <p>SourceGen converts 6502/65C02/65816 machine-language programs to
assembly-language source.</p> assembly-language source.</p>
@ -58,7 +59,7 @@ something that people actually want.</p>
the <a href="https://6502bench.com/sgtutorial/">tutorials</a>.</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 <p>The next few sections present some general concepts and terminology. The
rest of the documentation assumes you've read and understood this.</p> 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 assembly. You will need to be familiar with hexadecimal numbers and
general programming concepts to make sense of this, however.</p> 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 <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 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 <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> 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 <p>The American Standard Code for Information Interchange (ASCII) was
developed in the 1960s, and became widely used as the means for representing 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 string data, and in C64 PETSCII a number of text color and formatting
control codes are also allowed.</p> 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 <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". 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> 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 <p>SourceGen employs a partial emulation technique that traces the flow
of execution through the program. Most of what a given instruction does 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; margin: 20px 10px 10px 10px;
/*position: relative;*/ /*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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <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> <link rel="stylesheet" href="main.css"/>
<title>Using SourceGen - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <div id="content">
<h1>6502bench SourceGen: Using SourceGen</h1> <h1>SourceGen: Using SourceGen</h1>
<p><a href="index.html">Back to index</a></p> <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". <p>Select <samp>File &gt; New</samp>, or if no project is open, you
This opens the Create New Project window.</p> 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. <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 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. as the symbol files and extension scripts that will be loaded by default.
All of these may be overridden later from the project properties. All of these may be overridden later from the project properties.
(If the description in the panel on the right says "[placeholder]", it (If the description in the panel on the right says
means that the system doesn't yet have a set of symbols defined for it.)</p> "<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 <p>Next, click the <samp>Select File...</samp> button. Pick the file you
disassemble. The dialog will update with the pathname and some notes 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 about the file's size. Click <samp>OK</samp> if all looks good to create the
project.</p> project.</p>
<p><strong>NOTE:</strong> Support for very large 65816 programs is <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> 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 <p>The first time you save the project (with <samp>File &gt; Save</samp>),
prompted for the project name. It's best to use the data file's name you will be prompted for the project name. It's best to use the
with ".dis65" added, so this will be set as the default. The data data file's name with "<samp>.dis65</samp>" added, so this will be set as
file's name is not stored in the project file, so if you pick a different the default. The data file's name is not stored in the project file,
name, or save the project in a different directory, you will have to so if you pick a different name, or save the project in a different
select the data file manually whenever you open the project.</p> 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 <p>Select <samp>File &gt; Open</samp>, or if no project is open, you
existing project". Select the .dis65 project file from the standard can click the <samp>Open existing project</samp> button.
file dialog.</p> 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, <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 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 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 <p>The locations of the last few projects you've worked with are saved
in the application settings. You can access them from in the application settings. You can access them from
File &gt; Recent Projects. If no project is open, links to the two <samp>File &gt; Recent Projects</samp>. If no project is open, buttons
most-recently-opened projects will be available.</p> 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> <p>The main project window is divided into five areas:</p>
<ol> <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> 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 <p>The code list provides a view of the code being disassembled. Each
line may be an instruction, data item, long comment, note, or 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 <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 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 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> 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 <p>Selecting any part of a multi-line item, such as a long comment
or character string, effectively selects the entire item.</p> or character string, effectively selects the entire item.</p>
<p>Right-clicking opens a menu. The contents are the same as those in <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 the <samp>Actions</samp> menu item in the menu bar. The set of options
enabled will depend on what you have selected in the main window.</p> that are enabled will depend on what you have selected in the main window.</p>
<ul> <ul>
<li><a href="editors.html#instruction-operand">Edit Operand</a>. Opens the <li><a href="editors.html#instruction-operand">Edit Operand</a>. Opens the
Edit Instruction Operand or Edit Data Operand window, depending on 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> </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 <p>You can undo a change with <samp>Edit &gt; Undo</samp>, or
change with Edit &gt; Redo, Ctrl+Y, or Ctrl+Shift+Z.</p> <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, <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 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 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> 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, <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. 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 (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 to identify the locations that are reading or writing through the
pointer from those that are reading or writing the pointer itself.</p> 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 <p>This will be prefixed with "<samp>Sym</samp>" or "<samp>Oth</samp>"
the reference used the label at the current address. To understand to indicate whether or not the reference used the label at the current
this, consider that addresses can be referenced in different ways. address. To understand this, consider that addresses can be referenced
For example:</p> in different ways. For example:</p>
<pre> <pre>
LDA DATA0 LDA DATA0
LDX DATA0+1 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 references window will show the <code>LDX</code>, because that
instruction accessed <code>DATA1</code>'s location even though it didn't 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 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 window will either show "<samp>Sym</samp>" (to indicate that the symbol
line was referenced) or "Oth" (to indicate that some other symbol, or no at the selected line was referenced) or "<samp>Oth</samp>" (to indicate
symbol, was used).</p> that some other symbol, or no symbol, was used).</p>
<p>When an equate directive (generated for platform and project <p>When an equate directive (generated for platform and project
symbols) or local variable assignment is selected, the References 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> 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. <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 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> 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 <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 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 <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> 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> 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 <p>Some additional information about the currently-selected line is
shown, such as the formatting applied to the operand. If the operand 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 a summary is shown that includes the cycle count, flags affected, and a
brief description of what the instruction does. The latter can be brief description of what the instruction does. The latter can be
especially handy for undocumented instructions.</p> 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, <p>Sometimes a change will invalidate an earlier change. For example,
suppose you add a code stop point, and format the data that follows 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> cases, the offending item will be ignored.</p>
<p>Double-clicking on an entry will jump to that offset.</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 <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. hide the list by clicking on the <samp>Hide</samp> button to the left of
Un-hide the list by clicking on the "N messages" button at the bottom-right the messages. Un-hide the list by clicking on the <samp>N messages</samp>
corner of the application window.</p> 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 <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 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 <p>Use <samp>Navigate &gt; Find</samp> to search for text. This performs
text search on the label, opcode, operand, and comment fields. a case-insensitive text search on the label, opcode, operand, and comment
Use Navigate &gt; Find Next to find the next match, and fields.
Navigate &gt; Find Previous to find the previous match. Note "next" is Use <samp>Navigate &gt; Find Next</samp> to find the next match, and
always downward, and "previous" is always upward, regardless of the <samp>Navigate &gt; Find Previous</samp> to find the previous match.
direction of the initial search chosen in the Find dialog.</p> 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 <p>Use <samp>Navigate &gt; Go To</samp> to jump to an offset, address,
that offsets and addresses are always hexadecimal, and offsets start or label. Remember that offsets and addresses are always hexadecimal,
with a '+'. If you have a label that is also a valid hexadecimal and offsets start with a '+'. If you have a label that is also a
address, like "FEED", the label takes precedence. To jump to the address valid hexadecimal address, like "FEED", the label takes precedence. To
write "$FEED" instead. If you enter a non-unique label, the selection jump to the address write "$FEED" instead. If you enter a non-unique label,
will jump to the nearest instance.</p> the selection will jump to the nearest instance.</p>
<p>If an instruction or data line has an operand that references an address <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 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 <samp>Navigate &gt; Jump to Operand</samp>. You can also do this by
in the opcode column.</p> double-clicking in the opcode column.</p>
<p>When you edit something, lines throughout the listing can change. This <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 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. 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 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, 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. associated with the most recent change.
If the last change was to the project properties, it will jump to the If the last change was to the project properties, it will jump to the
first offset in the file.</p> first offset in the file.</p>
<p>When you jump around, e.g. by double-clicking on an opcode or an entry <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 in one of the side windows, the previously-selected line is added to
a navigation stack. You can use Navigate &gt; Nav Forward and a navigation stack. You can use <samp>Navigate &gt; Nav Forward</samp> and
Navigate &gt; Nav Backward to move forward and backward through the <samp>Navigate &gt; Nav Backward</samp> to move forward and backward
stack. (The curly arrows on the left side of the toolbar may be more through the stack. (The curly arrows on the left side of the toolbar may
convenient. You can use Alt+Left/Right Arrow, or be more convenient. You can use
Ctrl+- / Ctrl+Shift+-, as keyboard shortcuts.)</p> <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 <p><i>(Note: These were referred to as code/data "hints" in older
versions of SourceGen.)</i></p> versions of SourceGen.)</i></p>
<p>To set code start or stop points, select the desired offsets and <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 use <samp>Actions &gt; Tag Address As Code Start Point</samp>
these indicate a transition between code and data regions, there is rarely (or <samp>Stop Point</samp>). Because these indicate a transition
any need to tag multiple consecutive bytes. between code and data regions, there is rarely any need to tag
For this reason, only the first byte on each selected line will be tagged.</p> 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 <p>For inline data that follows a
selected line is tagged when you select Tag Bytes As Inline Data. Similarly, <code>JSR</code>/<code>JSL</code>/<code>BRK</code>,
the Remove Analyzer Tags menu item will remove tags from every byte.</p> 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 <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 the instructions are caught up in a multi-byte data item, such as an
auto-detected character string, you can disable uncategorized data analysis 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 (the thing that creates the <code>.STR</code> and <code>.FILL</code>
from the ops for you). You can do this from the
<a href="settings.html#project-properties">project properties</a> editor, <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 or simply by hitting <kbd class="key">Ctrl+D</kbd>. Hit that, tag the
again to re-enable the string &amp; fill analyzer.</p> byte or bytes, then hit it again to re-enable the
<p>Another approach is to use the "Toggle Single-Byte Format" string &amp; fill analyzer.</p>
menu item to "flatten" the item.</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 <p>Tables of addresses are fairly common. Sometimes you'll find them as a
series of 16-bit words, like this:</p> series of 16-bit words, like this:</p>
@ -487,12 +526,12 @@ jmptabh .dd1 &gt;func1
</pre> </pre>
<p>Sometimes the tables contain <code>address - 1</code>, because the <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, <p>While the <code>.dd2</code> case is easy to format with the data
formatting addresses whose components are split into multiple tables can operand editor, formatting addresses whose components are split into
be tedious. Even in the easy case, you may want to create labels and set multiple tables can be tedious. Even in the easy case, you may want
code start points for each item.</p> to create labels and set code start points for each item.</p>
<p>The Address Table Formatter helps you associate symbols with the <p>The Address Table Formatter helps you associate symbols with the
addresses in the table. It works for simple and "split" tables.</p> 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 -- number of parts -- two parts for 16-bit data, three parts for 24-bit data --
the formatter will report an error.</p> the formatter will report an error.</p>
<p>With the data selected, open the format dialog with <p>With the data selected, open the format dialog with
Actions &gt; Format Split-Address Table. The rather complicated dialog <samp>Actions &gt; Format Split-Address Table</samp>. The rather
is split into sections.</p> complicated dialog is split into sections.</p>
<ul> <ul>
<li>Address Characteristics: select whether the table has 16-bit <li>Address Characteristics: select whether the table has 16-bit
addresses or 24-bit addresses. (24-bit addresses are disabled if you 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 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 sub-tables for low bytes and high bytes, check the <samp>Parts are split
across sub-tables" box. If the address parts are being pushed across sub-tables</samp> box. If the address parts are being pushed
on the stack for an RTS/RTL, check the "Adjusted for RTS/RTL" box to on the stack for an <code>RTS</code>/<code>RTL</code>,
adjust them by 1.</li> 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 <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 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 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 high bytes, so you would select <samp>first part of selection</samp>.
stored the other way around, you would click "second part" instead.</li> 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 <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 the high bytes. For a 16-bit address this will be the part you didn't
pick for the low bytes. pick for the low bytes.
Sometimes, if all addresses land on the same 256-byte page, the high byte 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 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 a table. If that's the case, select <samp>Constant</samp>, and enter
in the text box. (Decimal, hex, and binary are accepted.)</li> the high byte in the text box.
<li>Bank Byte Source: for 24-bit addresses, you can select "Nth part of (Decimal, hex, and binary are accepted.)</li>
selection", which will just use whichever part you didn't specify for <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 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 <li>Options: if the table holds the addresses of executable code, check
the "Tag targets as code start points" box. If the target address the <samp>Tag targets as code start points</samp> box. If the target
hasn't been identified by the code analyzer through some other execution address hasn't been identified by the code analyzer through some
path, it will be tagged as a code start point.</li> 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 <li>Generated Addresses: this shows the full list of addresses that are
generated with the current set of parameters. Each address is shown with 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 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 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 mapped, and it already has a user-specified label, the label will be
shown. If no label was found, the table will show "(+)", indicating shown. If no label was found, the table will show "<code>(+)</code>",
that a permanent label will be added at the target offset. If everything indicating that a permanent label will be added at the target offset. If
is set up correctly, and the addresses fall entirely within the program, everything is set up correctly, and the addresses fall entirely within
you shouldn't see any unknown entries here.</li> the program, you shouldn't see any unknown entries here.</li>
</ul> </ul>
<p>For a 16-bit address, you have three choices: low byte first, high byte <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> 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 <p>The <samp>Toggle Single-Byte Format</samp> feature provides a quick
change a range of bytes to single bytes way to change a range of bytes to single bytes
or back to their default format. It's equivalent to opening the Edit or back to their default format. It's equivalent to opening the Edit
Data Operand dialog and selecting "Single bytes" displayed as hex, or Data Operand dialog and selecting <samp>Single bytes</samp> displayed
selecting "Default".</p> as hex, or selecting <samp>Default</samp>.</p>
<p>This can be handy if the default format for a range of bytes is a <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> 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 <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 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 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 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 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> <a href="#toggle-data">Toggle Data Scan</a>.)</p>
<p>As a special case, if you select a single byte, the following byte will <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 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> 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. <p>Removes instruction and data operand formatting from the selected lines.
This removes the visible formatting as well as any formatting instructions 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> 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 <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 the Project Properties editor, and clicking on the <samp>Analyze
Data" checkbox. When enabled, SourceGen will look for character strings and Uncategorized Data</samp> checkbox. When enabled, SourceGen will look
regions of identical bytes, and generate .STR and .FILL directives. When 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 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> 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 <p>As with all other project property changes, this is an undoable
action.</p> 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 <p>When you use <samp>Edit &gt; Copy</samp>, all lines selected in the
copied to the system clipboard. This can be a convenient way to post code list are copied to the system clipboard. This can be a convenient
code snippets into forum postings or documentation. The text is way to post code snippets into forum postings or documentation. The text is
copied from the data shown on screen, so your chosen capitalization copied from the data shown on screen, so your chosen capitalization
and pseudo-ops will appear in the copy.</p> and pseudo-ops will appear in the copy.</p>
<p>Long comments are included, but notes are not.</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> alternative formats that include additional columns.</p>
<p>A copy of all of the fields is also written to the clipboard in CSV <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 format. If you have a spreadsheet like Excel, you can use
to put the data into individual cells.</p> <samp>Paste Special</samp> to put the data into individual cells.</p>
</div> </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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <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> <link rel="stylesheet" href="main.css"/>
<title>Properties &amp; Settings - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <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> <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 <p>There are two kinds of settings: application settings, and
project properties.</p> 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" <p>Application settings are stored in a file called "SourceGen-settings"
in the SourceGen installation directory. If the file is missing or 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> the way generated assembly sources look.</p>
<p>The settings editor is divided into four tabs. Changes don't take <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>These settings change the way the code looks on screen.</p>
<p>Click the Column Visibility buttons to hide columns. Click them <p>Click the <samp>Column Visibility</samp> buttons to hide columns. Click
again to restore the column to a width appropriate for the current font. 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 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. positioning you can show and hide columns by dragging the column headers.
The buttons may be more convenient though.</p> 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 code, unless the assembler has specific case-sensitivity requirements. There
is no setting for labels, which are always case-sensitive.</p> is no setting for labels, which are always case-sensitive.</p>
<p>The Clipboard drop-down list lets you choose the format for text <p>The <samp>Clipboard</samp> drop-down list lets you choose the format
<a href="mainwin.html#clipboard">copied to the clipboard</a>. The for text <a href="mainwin.html#clipboard">copied to the clipboard</a>. The
"Assembler Source" format includes the rightmost columns (label, <samp>Assembler Source</samp> format includes the rightmost columns (label,
opcode, operand, and comment), like assembly source code does. The opcode, operand, and comment), like assembly source code does. The
"Disassembly" format adds the address and bytes on the left. Use <samp>Disassembly</samp> format adds the address and bytes on the left. Use
the "All Columns" format to get all columns.</p> the <samp>All Columns</samp> format to get all columns.</p>
<p>When "show cycle counts for instructions" is checked, every instruction <p>When <samp>show cycle counts for instructions</samp> is checked,
line will have an end-of-line comment that indicates the number of cycles every instruction line will have an end-of-line comment that indicates
required for that instruction. If the cycle count can't be determined the number of cycles required for that instruction. If the cycle count
solely from a static analysis, e.g. an extra cycle is required if can't be determined solely from a static analysis, e.g. an extra cycle
<code>LDA (dp),Y</code> crosses a page boundary, a '+' will be shown. is required if <code>LDA (dp),Y</code> crosses a page boundary, a '+'
In some cases the variability can be factored out if the state of will be shown. In some cases the variability can be factored out if the
certain status flags is known, e.g. 65C02 instructions that take longer state of certain status flags is known, e.g. 65C02 instructions that take
in decimal mode won't be shown as variable if the analyzer can determine longer in decimal mode won't be shown as ambiguous if the analyzer can
that D=0 or D=1. This checkbox enables display in the on-screen list, but determine that D=0 or D=1. This checkbox enables display in the
does not affect generated source code, which can be configured independently on-screen list, but does not affect generated source code, which can
on the Asm Config tab.</p> be configured independently on the <samp>Asm Config</samp> tab.</p>
<p>Check "use 'dark' color scheme" to change the main disassembly list <p>Check <samp>use 'dark' color scheme</samp> to change the main
to use white text on a black background, and mute the Note highlight disassembly list to use white text on a black background, and mute
colors. the Note highlight colors.
(Most of the GUI uses standard Windows controls that take their 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 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" can change the rest of the UI from the Windows display "personalization"
controls.)</p> 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. <p>Character and string operands are shown surrounded by quotes, e.g.
<code>LDA #'*'</code> or <code>.STR "Hello, world!"</code>. It's <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 the character will be output as hex to avoid confusion. For this
reason, it's generally wise to use delimiter characters that aren't reason, it's generally wise to use delimiter characters that aren't
part of the ASCII character set, such as "curly" quotes. The part of the ASCII character set, such as "curly" quotes. The
"Sample Characters" box holds some characters that you can copy and <samp>Sample Characters</samp> box holds some characters that you can
paste (with Ctrl+C / Ctrl+V) into the delimiter fields.</p> 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 <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 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> 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> 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 <p>These options change the way the code list looks on screen. They
do not affect generated code.</p> 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> The setting affects label editing as well as display.</p>
<p>If you would like your local variables to be shown with a prefix <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 <p>The <samp>comma-separated format for bulk data</samp> determines
blocks of hex look like <code>ABC123</code> or whether large blocks of hex look like <code>ABC123</code> or
<code>$AB,$C1,$23</code>. The former reduces the number of lines <code>$AB,$C1,$23</code>. The former reduces the number of lines
required, the latter is more readable.</p> 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" (64tass and ACME use the "common"
expression style, cc65 and Merlin 32 have their own unique styles.)</p> 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 <p>The <samp>add spaces in Bytes column</samp> checkbox changes the format
hex data in the code list "bytes" column from dense (<code>20edfd</code>) of the hex data in the code list "bytes" column from dense
to spaced (<code>20 ed fd</code>). This also affects the format of (<code>20edfd</code>) to spaced (<code>20 ed fd</code>). This also
clipboard copies and exports.</p> affects the format of clipboard copies and exports.</p>
<p>Long operands, such as strings and bulk data, are wrapped to a new <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 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> 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 <p>These options change the way the code list looks on screen. Assembler
directives and data pseudo-opcodes will use these values. This does 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 <p>These settings configure cross-assemblers and modify assembly source
generation in various ways.</p> generation in various ways.</p>
@ -195,25 +197,25 @@ executable.</p>
with all configuration files and libraries with all configuration files and libraries
<li>Merlin 32: <code>Merlin32.exe</code> <li>Merlin 32: <code>Merlin32.exe</code>
</ul> </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 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 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 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 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> 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 <p>When <samp>show cycle counts in comments</samp> is checked, cycle
inserted into end-of-line comments. This works the same as the option counts are inserted into end-of-line comments. This works the same as
in the Code View tab, but applies to generated source code rather than the option in the <samp>Code View</samp> tab, but applies to generated
the on-screen display.</p> source code rather than the on-screen display.</p>
<p>If "put long labels on separate line" is checked, labels that are <p>If <samp>put long labels on separate line</samp> is checked, labels
longer than the label column are placed on their own line. This looks that are longer than the label column are placed on their own line. This
a bit nicer because otherwise the opcode gets pushed out of alignment. 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 (Some assemblers get bent out of shape if you split an equate
directive, so those might stay on one line.)</p> 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 added to the top of the generated assembly output that identifies the
target assembler and version. It also shows the command-line options target assembler and version. It also shows the command-line options
passed to the assembler. This can be very helpful if the source 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> 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. <p>Project properties are stored in the .dis65 project file.
They specify which CPU to use, which extension scripts to load, and a 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> which means you hit "undo" to revert a property change.</p>
<p>The properties editor is divided into four tabs. Changes aren't pushed <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 out to the main application until you close the dialog. Clicking
will capture the current changes, ensuring that they're applied even if <samp>Apply</samp> will capture the current changes, ensuring that
you later hit Cancel, but the changes are not applied immediately.</p> 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 <p>The choice of CPU determines the set of available instructions, as
well as cycle costs and register widths. There are many variations 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 similar, but they have additional instructions and some fundamental
architectural changes. These are not currently supported by SourceGen.</p> architectural changes. These are not currently supported by SourceGen.</p>
<p>If "enable undocumented instructions" is checked, some additional <p>If <samp>enable undocumented instructions</samp> is checked, some
opcodes are recognized on the 6502 and 65C02. These instructions are additional opcodes are recognized on the 6502 and 65C02. These
not part of the chip specification, but most of them have consistent instructions are not part of the chip specification, but most of them
behavior and can be used. If the box is not checked, the instructions have consistent behavior and can be used. If the box is not checked,
are treated as invalid and cause the code analyzer to assume that it the instructions are treated as invalid and cause the code analyzer to
has run into a data area. This option has no effect on the 65816.</p> assume that it has run into a data area. This option has no effect on
<p>The "treat BRK as two-byte instruction" checkbox determines whether the 65816.</p>
BRK instructions should be handled as if they have an operand.</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 <p>The <samp>entry flags</samp> determine the initial value for the
flag register. Code that is unreachable internally (requiring a code processor status flag register. Code that is unreachable internally
start point tag) will use this value. This is chiefly of value for (requiring a code start point tag) will use this value. This is chiefly
65816 code, where the initial value of the M/X/E flags has a significant of value for 65816 code, where the initial value of the M/X/E flags has
impact on how instructions are disassembled.</p> a significant impact on how instructions are disassembled.</p>
<p>If "analyze uncategorized data" is checked, SourceGen will attempt to <p>If <samp>analyze uncategorized data</samp> is checked, SourceGen
identify character strings and regions that are filled with a repeated will attempt to identify character strings and regions that are filled
value. If it's not checked, anything that isn't detected as code or with a repeated value. If it's not checked, anything that isn't detected
explicitly formatted as data will be shown as individual byte values.</p> as code or explicitly formatted as data will be shown as individual
<p>If "seek nearby targets" is checked, the analyzer will try to use byte values.</p>
nearby labels for data loads and stores, adjusting them to fit <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 (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 unless they match exactly. Note that references into the middle of an
instruction or formatted data area are always adjusted, regardless of instruction or formatted data area are always adjusted, regardless of
how this is set. This setting has no effect on local variables, and 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> only enables a 1-byte backward search on project/platform symbols.</p>
<p>The "use relocation data" checkbox is only available if the project <p>The <samp>use relocation data</samp> checkbox is only available if
was created from a relocatable source, e.g. by the OMF Converter tool. the project was created from a relocatable source, e.g. by the OMF Converter
If checked, information from the relocation dictionary will be used to tool. If checked, information from the relocation dictionary will be
improve automatic operand formatting.</p> used to improve automatic operand formatting.</p>
<p>If "smart PLP handling" is checked, the analyzer will try to use <p>If <samp>smart PLP handling</samp> is checked, the analyzer will try
the processor status flags from a nearby <code>PHP</code> when a 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 <code>PLP</code> is encountered. If not enabled, all flags are set to
"indeterminate" following a <code>PLP</code>, except for the M/X "indeterminate" following a <code>PLP</code>, except for the M/X
flags on the 65816, which are left unmodified. (In practice this flags on the 65816, which are left unmodified. (In practice this
approach doesn't seem to work all that well, so the setting is approach doesn't seem to work all that well, so the setting is
un-checked by default.)</p> 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>, code patterns like <code>PLB</code> preceded by <code>PHK</code>,
and generate appropriate Data Bank Register changes. If not enabled, 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, 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> and does not change unless explicitly set. Only useful for 65816 code.</p>
<p>The <samp>default text encoding</samp> setting has two effects. First, it
<p>The "default text encoding" setting has two effects. First, it
specifies which character encoding to use when searching for strings in specifies which character encoding to use when searching for strings in
uncategorized data. Second, if an assembler has a notion of preferred uncategorized data. Second, if an assembler has a notion of preferred
character encoding (e.g. you can default string operands to PETSCII), character encoding (e.g. you can default string operands to PETSCII),
this setting will determine which encoding is preferred.</p> this setting will determine which encoding is preferred in generated
<p>The "min chars for string detection" setting determines how many sources.</p>
ASCII characters need to appear consecutively for the data analyzer to <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 declare it a string. Shorter values are prone to false-positive
identifications, longer values miss out on short strings. You can also identifications, longer values miss out on short strings. You can also
set it to "none" to disable automatic string identification.</p> set it to "none" to disable automatic string identification.</p>
<p>The <samp>auto-label style</samp> setting determines the format for
<p>The auto-label style setting determines the format for labels that are labels that are generated automatically. By default the label will be
generated automatically. By default the label will be the letter 'L' the letter 'L' followed by the hexadecimal address, but the label can
followed by the hexadecimal address, but the label can be annotated based be annotated based on usage. For example, addresses that are the target
on usage. For example, addresses that are the target of branch instructions of branch instructions can be labeled with the letter 'B'.</p>
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. <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 See the <a href="intro-details.html#about-symbols">symbols</a> section for an
explanation of how project symbols work.</p> 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 <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 allows changing any part of a symbol definition. You're not allowed to
create two symbols with the same label.</p> create two symbols with the same label.</p>
<p>The Import button allows you to import symbols from another project. <p>The <samp>Import</samp> button allows you to import symbols from
Only labels that have been tagged as global and exported will be imported. another project. Only labels that have been tagged as global and
Existing symbols with identical labels will be replaced, so it's okay to exported will be imported. Existing symbols with identical labels will
run the importer multiple times. Labels that aren't found will not be be replaced, so it's okay to run the importer multiple times. Labels
removed, so you can safely import from multiple projects, but will need that aren't found will not be removed, so you can safely import from
to manually delete any symbols that are no longer being exported.</p> 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 <p>Shortcut: you can open the project properties window with the
Project Symbols tab selected by hitting F6 from the main code list.</p> 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 <p>From here, you can add and remove platform symbol files, or change
the order in which they are loaded. the order in which they are loaded.
See the <a href="intro-details.html#about-symbols">symbols</a> section for an 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> 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 <p>Click one of the "Add Symbol Files" buttons to include one or more
symbol files in the project. symbol files in the project.
The "Add Symbol Files from Runtime" button sets the directory The <samp>Add Symbol Files from Runtime</samp> button sets the directory
to the SourceGen RuntimeData directory, while "Add Symbol Files from Project" to the SourceGen RuntimeData directory, while
starts in the project directory. If you haven't yet saved the project, <samp>Add Symbol Files from Project</samp> starts in the project directory.
the latter button will be disabled. The only difference between the If you haven't yet saved the project, the latter button will be disabled.
buttons is the initial directory.</p> The only difference between the buttons is the initial directory.</p>
<p>In the list, files loaded from the RuntimeData directory will be <p>In the list, files loaded from the RuntimeData directory will be
prefixed with <code>RT:</code>. Files loaded from the project directory prefixed with <code>RT:</code>. Files loaded from the project directory
will be prefixed with <code>PROJ:</code>.</p> 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> 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. <p>From here, you can add and remove extension script files.
See the <a href="advanced.html#extension-scripts">extension scripts</a> See the <a href="advanced.html#extension-scripts">extension scripts</a>
section for details on how extension scripts work.</p> 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 other people, but also acts as a minor security check, to prevent a
wayward project from trying to open files it shouldn't.</p> 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 <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 the project. The <samp>Add Scripts from Runtime</samp> button sets
to the SourceGen RuntimeData directory, while "Add Scripts from Project" the directory to the SourceGen RuntimeData directory, while
starts in the project directory. If you haven't yet saved the project, <samp>Add Scripts from Project</samp> starts in the project directory.
the latter button will be disabled. The only difference between the If you haven't yet saved the project, the latter button will be disabled.
buttons is the initial directory.</p> The only difference between the buttons is the initial directory.</p>
<p>In the list, files loaded from the RuntimeData directory will be <p>In the list, files loaded from the RuntimeData directory will be
prefixed with <code>RT:</code>. Files loaded from the project directory prefixed with <code>RT:</code>. Files loaded from the project directory
will be prefixed with <code>PROJ:</code>.</p> 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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Tools - 6502bench SourceGen</title> <link rel="stylesheet" href="main.css"/>
<title>Tools - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <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 <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 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> by unchecking the box at the bottom.</p>
<p>The status flags affected by each instruction reflect their behavior <p>The status flags affected by each instruction reflect their behavior
on the 65816. The only significant difference between 65816 and 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 <p>This opens a window with the ASCII character set. Each character is
displayed next to its numeric value in decimal and hexadecimal. The 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> 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 <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 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> 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 <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 The viewer is displayed in a "modeless" dialog that does not
prevent you from continuing to work with the project. If you prevent you from continuing to work with the project. If you
double-click a different line in the project, the viewer will automatically double-click a different line in the project, the viewer will automatically
highlight those bytes.</p> highlight those bytes.</p>
<p>You can also use this to view the contents of arbitrary files by <p>You can also view the contents of arbitrary files by using
using Tools &gt; Hex Dump. There is no fixed limit on the number of <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 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 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 eventually. Not coincidentally, the viewer has a size limit of 16MiB
per file.)</p> per file.)</p>
<p>You can select lines with the mouse as you would in any other list <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> the system clipboard.</p>
<p>The "character conversion" selector allows you to choose how the <p>The "character conversion" selector allows you to choose how the
bytes are converted to characters for the Text column. Choose from bytes are converted to characters for the Text column. Choose from
the usual set of encodings.</p> the usual set of encodings.</p>
<p>If "ASCII-only dump" is not checked, non-printable bytes are shown in <p>If <samp>ASCII-only dump</samp> is not checked, non-printable bytes
the ASCII dump as a middle dot ('&#183;'). If the box is checked, are shown in the ASCII dump as a middle dot ('&#183;'). If the option is
non-printable bytes are represented by a period ('.') instead. The checked, non-printable bytes are represented by a period ('.') instead.
use of non-ASCII characters makes the dump unambiguous when unprintable The use of non-ASCII characters makes the dump unambiguous when unprintable
characters are mixed with periods, but the lines may be unsuitable for characters are mixed with periods, but the lines may be unsuitable for
pasting in some forums.</p> pasting in some forums.</p>
<p>If "always on top" is checked, the window will stay above all other <p>If <samp>always on top</samp> is checked, the window will stay above
windows that don't also declare that they should always be on top. By all other windows that don't also declare that they should always be on
default this box is checked when displaying project data, and not checked for top. By default this box is checked when displaying project data, and
external files.</p> 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. <p>The File Concatenator combines multiple files into a single file.
Select the files to add, arrange them in the proper order, then hit 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 <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 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 you leave a field blank, they will default to offset 0 and the remaining
length of the file, respectively.</p> length of the file, respectively.</p>
<p>The hex dumps show the area just before and after the chunk to be <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) <p>This tool allows you to view Apple IIgs Object Module Format (OMF)
executables, and convert them for disassembly.</p> 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> created with some basic attributes filled in.</p>
<p>Only "Load" files (S16, PIF, TOL, etc) may be converted. Compiler object <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> a IIgs linker, and are not supported.</p>
<p>Before you can examine or convert a file, you must first extract <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 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" 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 <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 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 list of all the OMF records. For load files, the relocation dictionary is
also shown.</p> also shown.</p>
<p>To convert the file, click "Generate" to create a modified binary and a <p>To convert the file, click <samp>Generate</samp> to create a
SourceGen project file.</p> modified binary and a SourceGen project file.</p>
<p>If "offset segment start by $0100" is checked, the converter will try <p>If <samp>offset segment start by $0100</samp> is checked, the
to shift the segment's load address from <code>$xx/0000</code> to converter will try to shift the segment's load address from
<code>$xx/0100</code>. This can make the generated code a little nicer <code>$xx/0000</code> to <code>$xx/0100</code>. This can make the
to work with because it removes potential ambiguity with direct page generated code a little nicer to work with because it removes potential
addresses. For example, <code>LDA $56</code> and <code>LDA $0056</code> ambiguity with direct page addresses. For example, <code>LDA $56</code>
may be interpreted as the same thing by the assembler, requiring and <code>LDA $0056</code> may be interpreted as the same thing by the
generation of operand width disambiguators. By shifting the initial assembler, requiring generation of operand width disambiguators. By
address we avoid the potential ambiguity.</p> shifting the initial address we avoid the potential ambiguity.</p>
<p>Check "add comments and notes for each segment" to add a long comment <p>Check <samp>add comments and notes for each segment</samp> to add a
and a note at the start of each segment. The comments include the long comment and a note at the start of each segment. The comments
segment name, type, and optional flags. The notes just provide a quick include the segment name, type, and optional flags. The notes just
way to jump to a segment.</p> 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 <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 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 <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 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 the disassembler's analysis. The <samp>use reloc data</samp> setting in
properties controls this feature.</p> the project properties controls this feature.</p>
<p>A full explanation of the structure of OMF is beyond the scope of this <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 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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Tutorials - 6502bench SourceGen</title> <link rel="stylesheet" href="main.css"/>
<title>Tutorials - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <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 content on the 6502bench web site. Visit
<a href="https://6502bench.com/sgtutorial/">https://6502bench.com/sgtutorial/</a>.</p> <a href="https://6502bench.com/sgtutorial/">https://6502bench.com/sgtutorial/</a>.</p>
</div> </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"> <!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"> <html lang="en">
<head> <head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> <meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Visualizations - 6502bench SourceGen</title> <link rel="stylesheet" href="main.css"/>
<title>Visualizations - 6502bench SourceGen</title>
</head> </head>
<body> <body>
<div id="content"> <div id="content">
<h1>6502bench SourceGen: Visualizations</h1> <h1>SourceGen: Visualizations</h1>
<p><a href="index.html">Back to index</a></p> <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 <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 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> 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 <p>Visualizations are essentially decorative: they do not affect the
assembled output, and do not change how code is analyzed. They are 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> that perform the drawing. Or both.</p>
<p>To create a visualization set, select a code or data line, and use <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, <samp>Actions &gt; Create/Edit Visualization Set</samp>. To edit
select it and use the same menu item, or just double-click on it. This a visualization set, select it and use the same menu item, or just
opens the Visualization Set Editor window.</p> double-click on it. This opens the Visualization Set Editor window.</p>
<p>The visualization set editor shows a list of visualizations associated <p>The visualization set editor shows a list of visualizations associated
with the selected file offset. You can create a new visualization, edit with the selected file offset. You can create a new visualization, edit
or remove an existing entry, or rearrange them. 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. Bitmap Visualization Editor window will open.
Similarly, if you select "New Bitmap Animation" or edit an existing Similarly, if you select <samp>New Bitmap Animation</samp> or edit an
bitmap animation, the Bitmap Animation Editor will open.</p> existing bitmap animation, the Bitmap Animation Editor will open.</p>
<h4>Visualization Editor</h4> <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 appropriate for the data you're trying to visualize. Every visualizer may
have different parameters, so as you select different entries the set of have different parameters, so as you select different entries the set of
input parameters below the preview window may change.</p> 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 wireframe. Bitmaps are simple 2D images, but wireframes are 2D or 3D
meshes that can be viewed from different angles. When you select a meshes that can be viewed from different angles. When you select a
wireframe generator, additional view controls will be added at the bottom. 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. 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> 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 <p>The <samp>Export</samp> button at the top right can be used to save a
the bitmap or wireframe rendering with the current parameters.</p> copy of the bitmap or wireframe rendering with the current parameters.</p>
<h5>Wireframe View Controls</h5> <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 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 subject to gimbal lock (e.g. if you set Y to 90 degrees, X and Z rotate
about the same axis).</p> about the same axis).</p>
<p>If you check the "Animated" box, you can add a simple spin. Choose <p>If you check the <samp>Animated</samp> box, you can add a simple spin.
the number of degrees to rotate per frame, how many frames to generate before Choose the number of degrees to rotate per frame, how many frames to
resetting, and the delay between each frame. Clicking the "Auto" button generate before resetting, and the delay between each frame. Clicking
will automatically select the number of frames needed to display the the <samp>Auto</samp> button will automatically select the number of
animation in an unbroken loop (useful for animated GIFs). Click frames needed to display the animation in an unbroken loop (useful
the "Test Animation" button to see it in action.</p> for animated GIFs). Click the <samp>Test Animation</samp> button to
see it in action.</p>
<h4>Bitmap Animation Editor</h4> <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. <p>The "tag" is a unique string that will be shown in the display list.
The same rules apply as for bitmap visualizations.</p> The same rules apply as for bitmap visualizations.</p>
<p>The list at the top left holds all visualizations. Select items on <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, the left and use the <samp>Add</samp> button to add them to the list on
which has the set that is included in the animation. You can reorder the right, which has the set that is included in the animation. You
the list with the up/down buttons. Adding the same frame multiple times can reorder the list with the up/down buttons. Adding the same frame
is allowed.</p> multiple times is allowed.</p>
<p>The "frame delay" field lets you specify how long each frame is shown <p>The <samp>frame delay</samp> field lets you specify how long each
on screen, in milliseconds. Some animation formats may use a different frame is shown on screen, in milliseconds. Some animation formats may
time resolution; for example, animated GIFs use units of 1/100th of a use a different time resolution; for example, animated GIFs use units
second. The closest value will be used. Note also that some viewers of 1/100th of a second. The closest value will be used. Note also
(notably web browsers) will cap the update rate.</p> 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 <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 the result in the window at the bottom. The actual appearance may be
slightly different, especially if the frames are different sizes. For 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> 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 <p>A number of visualization generation scripts are included with
SourceGen, in the platform-specific runtime data directories.</p> 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> 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 <p>There is no standard format for small hi-res bitmaps, but certain
arrangements are common. The VisHiRes script defines four generators:</p> 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> 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 <p>The Atari 2600 graphics system has registers that determine the
appearance of a sprite or playfield on a single row. The register 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> repeated as-is or flipped.</li>
</ul> </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 <p>Different versions of Atari's Analog Vector Graphics were used in
several games, notably Battlezone, Tempest, and Star Wars. The commands 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 the commands to visualize, and the base address of vector RAM. The latter
is necessary to convert AVG JMP/JSR commands into offsets.</p> 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> It comes in two basic varieties:</p>
<ul> <ul>
<li><b>High-resolution sprite</b> - 24x21 monochrome. Pixels are either <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 doubled in both width and height will look exactly like
a sprite that is not doubled at all.</p> 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. <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. Converting the full collection to a reference bitmap is straightforward.