mirror of https://github.com/fadden/6502bench.git
417 lines
20 KiB
HTML
417 lines
20 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
|
|
<link rel="stylesheet" href="main.css"/>
|
|
<title>Properties & Settings - 6502bench SourceGen</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="content">
|
|
<h1>SourceGen: Properties & Settings</h1>
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
<h2 id="overview">Settings Overview</h2>
|
|
|
|
<p>There are two kinds of settings: application settings, and
|
|
project properties.</p>
|
|
|
|
|
|
<h2 id="app-settings">Application Settings</h2>
|
|
|
|
<p>Application settings are stored in a file called "SourceGen-settings"
|
|
in the SourceGen installation directory. If the file is missing or
|
|
corrupted, default settings will be used. These settings are local
|
|
to your system, and include everything from window sizes to whether or not
|
|
you prefer hexadecimal values to be shown in upper case. None of them
|
|
affect the way the project analyzes code and data, though they may affect
|
|
the way generated assembly sources look.</p>
|
|
|
|
<p>The settings editor is divided into four tabs. Changes don't take
|
|
effect until you hit <samp>Apply</samp> or <samp>OK</samp>.</p>
|
|
|
|
|
|
<h3 id="appset-codeview">Code View</h3>
|
|
|
|
<p>These settings change the way the code looks on screen.</p>
|
|
|
|
<p>Click the <samp>Column Visibility</samp> buttons to hide columns. Click
|
|
them again to restore the column to a width appropriate for the current font.
|
|
A "hidden" column just has a width of zero, so with careful mouse
|
|
positioning you can show and hide columns by dragging the column headers.
|
|
The buttons may be more convenient though.</p>
|
|
|
|
<p>You can select a different font for the code list, and make it as large
|
|
or as small as you want. Mono-space fonts like Courier or Consolas are
|
|
recommended (and will be the only ones shown).</p>
|
|
|
|
<p>You can choose to display different parts of the display in upper or
|
|
lower case, using the "all lower" and "all upper" buttons as a quick way
|
|
to set all values. These settings are also used for generated assembly
|
|
code, unless the assembler has specific case-sensitivity requirements. There
|
|
is no setting for labels, which are always case-sensitive.</p>
|
|
|
|
<p>The <samp>Clipboard</samp> drop-down list lets you choose the format
|
|
for text <a href="mainwin.html#clipboard">copied to the clipboard</a>. The
|
|
<samp>Assembler Source</samp> format includes the rightmost columns (label,
|
|
opcode, operand, and comment), like assembly source code does. The
|
|
<samp>Disassembly</samp> format adds the address and bytes on the left. Use
|
|
the <samp>All Columns</samp> format to get all columns.</p>
|
|
|
|
<p>When <samp>show cycle counts for instructions</samp> is checked,
|
|
every instruction line will have an end-of-line comment that indicates
|
|
the number of cycles required for that instruction. If the cycle count
|
|
can't be determined solely from a static analysis, e.g. an extra cycle
|
|
is required if <code>LDA (dp),Y</code> crosses a page boundary, a '+'
|
|
will be shown. In some cases the variability can be factored out if the
|
|
state of certain status flags is known, e.g. 65C02 instructions that take
|
|
longer in decimal mode won't be shown as ambiguous if the analyzer can
|
|
determine that D=0 or D=1. This checkbox enables display in the
|
|
on-screen list, but does not affect generated source code, which can
|
|
be configured independently on the <samp>Asm Config</samp> tab.</p>
|
|
|
|
<p>Check <samp>use 'dark' color scheme</samp> to change the main
|
|
disassembly list to use white text on a black background, and mute
|
|
the Note highlight colors.
|
|
(Most of the GUI uses standard Windows controls that take their colors
|
|
from the system theme, but the disassembly list uses a custom style. You
|
|
can change the rest of the UI from the Windows display "personalization"
|
|
controls.)</p>
|
|
|
|
|
|
<h3 id="appset-textdelim">Text Delimiters</h3>
|
|
|
|
<p>Character and string operands are shown surrounded by quotes, e.g.
|
|
<code>LDA #'*'</code> or <code>.STR "Hello, world!"</code>. It's
|
|
handy to be able to tell at a glance how characters are encoded, so
|
|
SourceGen allows you to set the delimiters independently for every
|
|
supported character encoding.</p>
|
|
<p>String operands may contain a mixture of text and hexadecimal values.
|
|
For example, in ASCII data, the control characters for linefeed and
|
|
carriage return ($0a and $0d) are considered part of the string, but
|
|
don't have a printable symbol. (Unicode defines some glpyhs, but they
|
|
don't look very good at smaller font sizes.)</p>
|
|
<p>If one of the delimiter characters appears in the string itself,
|
|
the character will be output as hex to avoid confusion. For this
|
|
reason, it's generally wise to use delimiter characters that aren't
|
|
part of the ASCII character set, such as "curly" quotes. The
|
|
<samp>Sample Characters</samp> box holds some characters that you can
|
|
copy and paste (with <kbd class="key">Ctrl+C</kbd> /
|
|
<kbd class="key">Ctrl+V</kbd>) into the delimiter fields.</p>
|
|
<p>For character operands, the prefix and suffix are added to the start
|
|
and end of the operand. For string operands, the prefix is added to the
|
|
start of the first line, and suffixes aren't allowed.</p>
|
|
<p>These options change the way the code list looks on screen. They
|
|
do not affect generated code, which must use the delimiter characters
|
|
specified by the chosen assembler.</p>
|
|
|
|
<p>The "quick set" pop-up can be used to set the fields for a few
|
|
common configurations. The default set uses curly quotes with a few
|
|
prefixes and suffixes, while "straight" uses the ASCII apostrophe and
|
|
double-quote characters. "Merlin" uses a format similar to what the
|
|
Merlin assembler expects.</p>
|
|
|
|
|
|
<h3 id="appset-displayformat">Display Format</h3>
|
|
|
|
<p>These options change the way the code list looks on screen. They
|
|
do not affect generated code.</p>
|
|
|
|
<p>The
|
|
<a href="intro-details.html#width-disambiguation">operand width disambiguator</a>
|
|
strings are used when the width of an instruction operand is unclear.
|
|
You may specify values for all of them or none of them.</p>
|
|
|
|
<p>Different assemblers have different ways of forming expressions.
|
|
Sometimes the rules allow expressions to be written simply, other times
|
|
explicit grouping with parenthesis is required. Select whichever style
|
|
you are most comfortable with.</p>
|
|
|
|
<p>Non-unique labels are identified with a prefix character, typically
|
|
'@' or ':'. The default is '@', but you can configure it to any character
|
|
that isn't valid for the start of a label. (64tass uses '_' for locals,
|
|
but that's a valid label start character, and so isn't allowed here.)
|
|
The setting affects label editing as well as display.</p>
|
|
|
|
<p>If you would like your local variables to be shown with a prefix
|
|
character, you can set it in the <samp>local variable prefix</samp> box.</p>
|
|
|
|
<p>The <samp>comma-separated format for bulk data</samp> determines
|
|
whether large blocks of hex look like <code>ABC123</code> or
|
|
<code>$AB,$C1,$23</code>. The former reduces the number of lines
|
|
required, the latter is more readable.</p>
|
|
|
|
<p>The "quick set" pop-up configures the fields on the left side of the
|
|
tab to match the conventions of the specified assembler. Select your
|
|
preferred assembler in the combo box to set the fields. The setting
|
|
automatically switches to "custom" when you edit a field.
|
|
(64tass and ACME use the "common"
|
|
expression style, cc65 and Merlin 32 have their own unique styles.)</p>
|
|
|
|
<p>The <samp>add spaces in Bytes column</samp> checkbox changes the format
|
|
of the hex data in the code list "bytes" column from dense
|
|
(<code>20edfd</code>) to spaced (<code>20 ed fd</code>). This also
|
|
affects the format of clipboard copies and exports.</p>
|
|
|
|
<p>Long operands, such as strings and bulk data, are wrapped to a new
|
|
line after a certain number of characters. Use the pop-up to configure
|
|
the value. Larger values can make the code display more compact, but smaller
|
|
values allow you to shrink the width of the operand column in the
|
|
on-screen listing, moving the comment field closer in.</p>
|
|
|
|
|
|
<h3 id="appset-pseudoop">Pseudo-Op</h3>
|
|
|
|
<p>These options change the way the code list looks on screen. Assembler
|
|
directives and data pseudo-opcodes will use these values. This does
|
|
not affect generated source code, which always matches the conventions
|
|
of the target assembler.</p>
|
|
|
|
<p>Enter the string you want to use for the various data formats. If
|
|
a field is left blank, a default value is used.</p>
|
|
|
|
<p>The "quick set" pop-up configures the fields on this tab to match
|
|
the conventions of the specified assembler. Select your preferred assembler
|
|
in the combo box to set the fields. The setting automatically switches to
|
|
"custom" when you edit a field.</p>
|
|
|
|
|
|
|
|
<h3 id="appset-asmconfig">Asm Config</h3>
|
|
|
|
<p>These settings configure cross-assemblers and modify assembly source
|
|
generation in various ways.</p>
|
|
<p>To configure an assembler, select it in the pop-up menu. The fields
|
|
will initially contain assembler-specific default values. All of
|
|
the values in the Assembler Configuration box may be configured
|
|
differently for each assembler.</p>
|
|
<p>The "executable" box holds the full path to the cross-assembler
|
|
executable.</p>
|
|
<ul>
|
|
<li>64tass: <code>64tass.exe</code>
|
|
<li>ACME: <code>acme.exe</code>
|
|
<li>cc65: <code>bin/cl65.exe</code> -- full installation required,
|
|
with all configuration files and libraries
|
|
<li>Merlin 32: <code>Merlin32.exe</code>
|
|
</ul>
|
|
<p>The <samp>column widths</samp> section allows you to specify the minimum
|
|
width of the label, opcode, operand, and comment fields. If the width
|
|
is less than 1, or isn't a valid number, 1 will be used. These are
|
|
not hard stops: if the contents of a field are too wide, the contents
|
|
of the next column will be pushed over. (The comment field width is
|
|
not currently being used, but may be used to fold lines in the future.)</p>
|
|
|
|
<p>When <samp>show cycle counts in comments</samp> is checked, cycle
|
|
counts are inserted into end-of-line comments. This works the same as
|
|
the option in the <samp>Code View</samp> tab, but applies to generated
|
|
source code rather than the on-screen display.</p>
|
|
|
|
<p>If you enable <samp>identify assembler in output</samp>, a comment will be
|
|
added to the top of the generated assembly output that identifies the
|
|
target assembler and version. It also shows the command-line options
|
|
passed to the assembler. This can be very helpful if the source
|
|
file is sent to other people, since it may not otherwise be obvious from
|
|
the source file what the intended target assembler is, or what options
|
|
are required to process the file correctly.</p>
|
|
|
|
<p>Labels can generally be placed either on the same line as a code or data
|
|
operand, or on the line before it. Placing them on the same line makes
|
|
the output a bit more compact, but if the label is longer than the label
|
|
column is wide, the subsequent fields can be pushed out of alignment.
|
|
The placement is configurable. Labels can be output on their own line:</p>
|
|
<ol>
|
|
<li>Only when required - labels will not be placed on a separate line
|
|
unless the assembler requires them to be.</li>
|
|
<li>When the label is wider than the field - labels will only be
|
|
placed on a separate line when they don't fit in the label column.</li>
|
|
<li>Whenever possible - labels are always placed on a separate line
|
|
when they are allowed to be. Most assemblers require that the label
|
|
be on the same line as assignment pseudo-ops,
|
|
e.g. "<code>FOO = $1000</code>".</li>
|
|
</ol>
|
|
|
|
|
|
<h2 id="project-properties">Project Properties</h2>
|
|
|
|
<p>Project properties are stored in the .dis65 project file.
|
|
They specify which CPU to use, which extension scripts to load, and a
|
|
variety of other things that directly impact how SourceGen processes
|
|
the project. Because of the potential impact, all changes to
|
|
the project properties are made through the undo/redo buffer,
|
|
which means you hit "undo" to revert a property change.</p>
|
|
|
|
<p>The properties editor is divided into four tabs. Changes aren't pushed
|
|
out to the main application until you close the dialog. Clicking
|
|
<samp>Apply</samp> will capture the current changes, ensuring that
|
|
they're applied even if you later hit Cancel, but the changes are not
|
|
applied to the project immediately.</p>
|
|
|
|
|
|
<h3 id="projprop-general">General</h3>
|
|
|
|
<p>The choice of CPU determines the set of available instructions, as
|
|
well as cycle costs and register widths. There are many variations
|
|
on the 6502, but from the perspective of a disassembler most can be
|
|
treated as one of these four:</p>
|
|
<ol>
|
|
<li>MOS 6502. The original 8-bit instruction set.</li>
|
|
<li>WDC 65C02. Expanded the instruction set and smoothed
|
|
some rough edges.</li>
|
|
<li>WDC W65C02S. An enhanced version of the 65C02, with some
|
|
additional instructions introduced by Rockwell (R65C02), as well
|
|
as WDC's STP and WAI instructions. The Rockwell additions overlap
|
|
with 65816 instructions, so code that uses them will not work on
|
|
16-bit CPUs.</li>
|
|
<li>WDC W65C816S. Expanded instruction set, 24-bit address space,
|
|
and 16-bit registers.</li>
|
|
</ol>
|
|
<p>The Hudson Soft HuC6280 and Commodore CSG 4510 / 65CE02 are very
|
|
similar, but they have additional instructions and some fundamental
|
|
architectural changes. These are not currently supported by SourceGen.</p>
|
|
|
|
<p>If <samp>enable undocumented instructions</samp> is checked, some
|
|
additional opcodes are recognized on the 6502 and 65C02. These
|
|
instructions are not part of the chip specification, but most of them
|
|
have consistent behavior and can be used. If the box is not checked,
|
|
the instructions are treated as invalid and cause the code analyzer to
|
|
assume that it has run into a data area. This option has no effect on
|
|
the 65816.</p>
|
|
<p>The <samp>treat BRK as two-byte instruction</samp> checkbox determines
|
|
whether <code>BRK</code> instructions should be handled as if they have
|
|
an operand.</p>
|
|
|
|
<p>The <samp>entry flags</samp> determine the initial value for the
|
|
processor status flag register. Code that is unreachable internally
|
|
(requiring a code start point tag) will use this value. This is chiefly
|
|
of value for 65816 code, where the initial value of the M/X/E flags has
|
|
a significant impact on how instructions are disassembled.</p>
|
|
|
|
<p>If <samp>analyze uncategorized data</samp> is checked, SourceGen
|
|
will attempt to identify character strings and regions that are filled
|
|
with a repeated value. If it's not checked, anything that isn't detected
|
|
as code or explicitly formatted as data will be shown as individual
|
|
byte values.</p>
|
|
<p>If <samp>seek nearby targets</samp> is checked, the analyzer will try to
|
|
use nearby labels for data loads and stores, adjusting them to fit
|
|
(e.g. <code>LDA LABEL+1</code>). If not enabled, labels are not applied
|
|
unless they match exactly. Note that references into the middle of an
|
|
instruction or formatted data area are always adjusted, regardless of
|
|
how this is set. This setting has no effect on local variables, and
|
|
only enables a 1-byte backward search on project/platform symbols.</p>
|
|
<p>The <samp>use relocation data</samp> checkbox is only available if
|
|
the project was created from a relocatable source, e.g. by the OMF Converter
|
|
tool. If checked, information from the relocation dictionary will be
|
|
used to improve automatic operand formatting.</p>
|
|
<p>If <samp>smart PLP handling</samp> is checked, the analyzer will try
|
|
to use the processor status flags from a nearby <code>PHP</code> when a
|
|
<code>PLP</code> is encountered. If not enabled, all flags are set to
|
|
"indeterminate" following a <code>PLP</code>, except for the M/X
|
|
flags on the 65816, which are left unmodified. (In practice this
|
|
approach doesn't seem to work all that well, so the setting is
|
|
un-checked by default.)</p>
|
|
<p>If <samp>smart PLB handling</samp> is checked, the analyzer will watch for
|
|
code patterns like <code>PLB</code> preceded by <code>PHK</code>,
|
|
and generate appropriate Data Bank Register changes. If not enabled,
|
|
the DBR is set to the bank of the address of the start of the file,
|
|
and does not change unless explicitly set. Only useful for 65816 code.</p>
|
|
<p>The <samp>default text encoding</samp> setting has two effects. First, it
|
|
specifies which character encoding to use when searching for strings in
|
|
uncategorized data. Second, if an assembler has a notion of preferred
|
|
character encoding (e.g. you can default string operands to PETSCII),
|
|
this setting will determine which encoding is preferred in generated
|
|
sources.</p>
|
|
<p>The <samp>min chars for string detection</samp> setting determines how
|
|
many ASCII characters need to appear consecutively for the data analyzer to
|
|
declare it a string. Shorter values are prone to false-positive
|
|
identifications, longer values miss out on short strings. You can also
|
|
set it to "none" to disable automatic string identification.</p>
|
|
<p>The <samp>auto-label style</samp> setting determines the format for
|
|
labels that are generated automatically. By default the label will be
|
|
the letter 'L' followed by the hexadecimal address, but the label can
|
|
be annotated based on usage. For example, addresses that are the target
|
|
of branch instructions can be labeled with the letter 'B'.</p>
|
|
|
|
|
|
<h3 id="projprop-projsym">Project Symbols</h3>
|
|
<p>You can add, edit, and delete individual symbols and constants.
|
|
See the <a href="intro-details.html#about-symbols">symbols</a> section for an
|
|
explanation of how project symbols work.</p>
|
|
|
|
<p>The <samp>Edit Symbol</samp> button opens the
|
|
<a href="editors.html#project-symbol">Edit Project Symbol</a> dialog, which
|
|
allows changing any part of a symbol definition. You're not allowed to
|
|
create two symbols with the same label.</p>
|
|
|
|
<p>The <samp>Import</samp> button allows you to import symbols from
|
|
another project. Only labels that have been tagged as global and
|
|
exported will be imported. Existing symbols with identical labels will
|
|
be replaced, so it's okay to run the importer multiple times. Labels
|
|
that aren't found will not be removed, so you can safely import from
|
|
multiple projects, but will need to manually delete any symbols that are
|
|
no longer being exported.</p>
|
|
|
|
<p>Shortcut: you can open the project properties window with the
|
|
Project Symbols tab selected by hitting F6 from the main code list.</p>
|
|
|
|
|
|
<h3 id="projprop-symfiles">Symbol Files</h3>
|
|
<p>From here, you can add and remove platform symbol files, or change
|
|
the order in which they are loaded.
|
|
See the <a href="intro-details.html#about-symbols">symbols</a> section for an
|
|
explanation of how platform symbols work, and the
|
|
<a href="advanced.html#platform-symbols">advanced topics</a> section
|
|
for a description of the file syntax.</p>
|
|
|
|
<p>Platform symbol files must live in the RuntimeData directory that comes
|
|
with SourceGen, or in the directory where the project file lives. This
|
|
is mostly to keep things manageable when projects are distributed to
|
|
other people, but also acts as a minor security check, to prevent a
|
|
wayward project from trying to open files it shouldn't.</p>
|
|
<p>Click one of the "Add Symbol Files" buttons to include one or more
|
|
symbol files in the project.
|
|
The <samp>Add Symbol Files from Runtime</samp> button sets the directory
|
|
to the SourceGen RuntimeData directory, while
|
|
<samp>Add Symbol Files from Project</samp> starts in the project directory.
|
|
If you haven't yet saved the project, the latter button will be disabled.
|
|
The only difference between the buttons is the initial directory.</p>
|
|
<p>In the list, files loaded from the RuntimeData directory will be
|
|
prefixed with <code>RT:</code>. Files loaded from the project directory
|
|
will be prefixed with <code>PROJ:</code>.</p>
|
|
<p>If a platform symbol file can't be found when the project is opened,
|
|
you will receive a warning.</p>
|
|
|
|
|
|
<h3 id="projprop-extscripts">Extension Scripts</h3>
|
|
<p>From here, you can add and remove extension script files.
|
|
See the <a href="advanced.html#extension-scripts">extension scripts</a>
|
|
section for details on how extension scripts work.</p>
|
|
|
|
<p>Extension script files must live in the RuntimeData directory that comes
|
|
with SourceGen, or in the directory where the project file lives. This
|
|
is mostly to keep things manageable when projects are distributed to
|
|
other people, but also acts as a minor security check, to prevent a
|
|
wayward project from trying to open files it shouldn't.</p>
|
|
<p>Click one of the "Add Scripts" buttons to include one more scripts in
|
|
the project. The <samp>Add Scripts from Runtime</samp> button sets
|
|
the directory to the SourceGen RuntimeData directory, while
|
|
<samp>Add Scripts from Project</samp> starts in the project directory.
|
|
If you haven't yet saved the project, the latter button will be disabled.
|
|
The only difference between the buttons is the initial directory.</p>
|
|
<p>In the list, files loaded from the RuntimeData directory will be
|
|
prefixed with <code>RT:</code>. Files loaded from the project directory
|
|
will be prefixed with <code>PROJ:</code>.</p>
|
|
<p>If an extension script file can't be found when the project is opened,
|
|
you will receive a warning.</p>
|
|
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p><a href="index.html">Back to index</a></p>
|
|
</div>
|
|
</body>
|
|
<!-- Copyright 2018 faddenSoft -->
|
|
</html>
|