mirror of https://github.com/fadden/6502bench.git
394 lines
19 KiB
HTML
394 lines
19 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<link href="main.css" rel="stylesheet" type="text/css" />
|
|
<title>Properties & Settings - 6502bench SourceGen</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="content">
|
|
<h1>6502bench SourceGen: Properties & Settings</h1>
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
<h2><a name="overview">Settings Overview</a></h2>
|
|
|
|
<p>There are two kinds of settings: application settings, and
|
|
project properties.</p>
|
|
|
|
|
|
<h2><a name="app-settings">Application Settings</a></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 Apply or OK.</p>
|
|
|
|
|
|
<h3><a name="appset-codeview">Code View</a></h3>
|
|
|
|
<p>These settings change the way the code looks on screen.</p>
|
|
|
|
<p>Click the Column Visibility buttons to hide columns. Click them
|
|
again to restore the column to a width appropriate for the current font.
|
|
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 Clipboard drop-down list lets you choose the format for text
|
|
<a href="mainwin.html#clipboard">copied to the clipboard</a>. The
|
|
"Assembler Source" format includes the rightmost columns (label,
|
|
opcode, operand, and comment), like assembly source code does. The
|
|
"Disassembly" format adds the address and bytes on the left. Use
|
|
the "All Columns" format to get all columns.</p>
|
|
|
|
<p>When "show cycle counts for instructions" is checked, every instruction
|
|
line will have an end-of-line comment that indicates the number of cycles
|
|
required for that instruction. If the cycle count can't be determined
|
|
solely from a static analysis, e.g. an extra cycle is required if
|
|
<code>LDA (dp),Y</code> crosses a page boundary, a '+' will be shown.
|
|
In some cases the variability can be factored out if the state of
|
|
certain status flags is known, e.g. 65C02 instructions that take longer
|
|
in decimal mode won't be shown as variable if the analyzer can determine
|
|
that D=0 or D=1. This checkbox enables display in the on-screen list, but
|
|
does not affect generated source code, which can be configured independently
|
|
on the Asm Config tab.</p>
|
|
|
|
<p>Check "use 'dark' color scheme" to change the main disassembly list
|
|
to use white text on a black background, and mute the Note highlight
|
|
colors.
|
|
(Most of the GUI uses standard Windows controls that take their colors
|
|
from the system theme, but the disassembly list uses a custom style. You
|
|
can change the rest of the UI from the Windows display "personalization"
|
|
controls.)</p>
|
|
|
|
|
|
<h3><a name="appset-textdelim">Text Delimiters</a></h3>
|
|
|
|
<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. The "Sample Characters" box holds some
|
|
characters that you can copy and paste (with Ctrl+C / Ctrl+V) 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>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>
|
|
|
|
|
|
<h3><a name="appset-displayformat">Display Format</a></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 "local variable prefix" box.</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 "add spaces in Bytes column" checkbox changes the format of the
|
|
hex data in the code list "bytes" column from dense (<code>20edfd</code>)
|
|
to spaced (<code>20 ed fd</code>). This also affects the format of
|
|
clipboard copies and exports.</p>
|
|
|
|
<p>The "comma-separated format for bulk data" 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>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 easier to read, 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><a name="appset-pseudoop">Pseudo-Op</a></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><a name="appset-asmconfig">Asm Config</a></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 "column widths" section allows you to specify the minimum
|
|
width of the label, opcode, operand, and comment fields. If the width
|
|
is less than 1, or isn't a valid number, 1 will be used. These are
|
|
not hard stops: if the contents of a field are too wide, the contents
|
|
of the next column will be pushed over. (The comment field width is
|
|
not currently being used, but may be used to fold lines in the future.)</p>
|
|
|
|
<p>When "show cycle counts in comments" is checked, cycle counts are
|
|
inserted into end-of-line comments. This works the same as the option
|
|
in the Code View tab, but applies to generated source code rather than
|
|
the on-screen display.</p>
|
|
|
|
<p>If "put long labels on separate line" is checked, labels that are
|
|
longer than the label column are placed on their own line. This looks
|
|
a bit nicer because otherwise the opcode gets pushed out of alignment.
|
|
(Some assemblers get bent out of shape if you split an equate
|
|
directive, so those might stay on one line.)</p>
|
|
|
|
<p>If you enable "identify assembler in output", a comment will be
|
|
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>
|
|
|
|
|
|
<h2><a name="project-properties">Project Properties</a></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 Apply
|
|
will capture the current changes, ensuring that they're applied even if
|
|
you later hit Cancel, but the changes are not applied immediately.</p>
|
|
|
|
|
|
<h3><a name="projprop-general">General</a></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 "enable undocumented instructions" is checked, some additional
|
|
opcodes are recognized on the 6502 and 65C02. These instructions are
|
|
not part of the chip specification, but most of them have consistent
|
|
behavior and can be used. If the box is not checked, the instructions
|
|
are treated as invalid and cause the code analyzer to assume that it
|
|
has run into a data area. This option has no effect on the 65816.</p>
|
|
<p>The "treat BRK as two-byte instruction" checkbox determines whether
|
|
BRK instructions should be handled as if they have an operand.</p>
|
|
|
|
<p>The entry flags determine the initial value for the processor status
|
|
flag register. Code that is unreachable internally (requiring a code
|
|
start point tag) will use this value. This is chiefly of value for
|
|
65816 code, where the initial value of the M/X/E flags has a significant
|
|
impact on how instructions are disassembled.</p>
|
|
|
|
<p>If "analyze uncategorized data" is checked, SourceGen will attempt to
|
|
identify character strings and regions that are filled with a repeated
|
|
value. If it's not checked, anything that isn't detected as code or
|
|
explicitly formatted as data will be shown as individual byte values.</p>
|
|
<p>If "seek nearby targets" is checked, the analyzer will try to use
|
|
nearby labels for data loads and stores, adjusting them to fit
|
|
(e.g. <code>LDA LABEL+1</code>). If not enabled, labels are not applied
|
|
unless they match exactly. Note that references into the middle of an
|
|
instruction or formatted data area are always adjusted, regardless of
|
|
how this is set. This setting has no effect on local variables, and
|
|
only enables a 1-byte backward search on project/platform symbols.</p>
|
|
<p>The "use relocation data" checkbox is only available if the project
|
|
was created from a relocatable source, e.g. by the OMF Converter tool.
|
|
If checked, information from the relocation dictionary will be used to
|
|
improve automatic operand formatting.</p>
|
|
<p>If "smart PLP handling" is checked, the analyzer will try to use
|
|
the processor status flags from a nearby <code>PHP</code> when a
|
|
<code>PLP</code> is encountered. If not enabled, all flags are set to
|
|
"indeterminate" following a <code>PLP</code>, except for the M/X
|
|
flags on the 65816, which are left unmodified. (In practice this
|
|
approach doesn't seem to work all that well, so the setting is
|
|
un-checked by default.)</p>
|
|
<p>If "smart PLB handling" is checked, the analyzer will watch for
|
|
code patterns like <code>PLB</code> preceded by <code>PHK</code>,
|
|
and generate appropriate Data Bank Register changes. If not enabled,
|
|
the DBR is set to the bank of the address of the start of the file,
|
|
and does not change unless explicitly set. Only useful for 65816 code.</p>
|
|
|
|
<p>The "default text encoding" setting has two effects. First, it
|
|
specifies which character encoding to use when searching for strings in
|
|
uncategorized data. Second, if an assembler has a notion of preferred
|
|
character encoding (e.g. you can default string operands to PETSCII),
|
|
this setting will determine which encoding is preferred.</p>
|
|
<p>The "min chars for string detection" setting determines how many
|
|
ASCII characters need to appear consecutively for the data analyzer to
|
|
declare it a string. Shorter values are prone to false-positive
|
|
identifications, longer values miss out on short strings. You can also
|
|
set it to "none" to disable automatic string identification.</p>
|
|
|
|
<p>The auto-label style setting determines the format for labels that are
|
|
generated automatically. By default the label will be the letter 'L'
|
|
followed by the hexadecimal address, but the label can be annotated based
|
|
on usage. For example, addresses that are the target of branch instructions
|
|
can be labeled with the letter 'B'.</p>
|
|
|
|
|
|
<h3><a name="projprop-projsym">Project Symbols</a></h3>
|
|
<p>You can add, edit, and delete individual symbols and constants.
|
|
See the <a href="intro-details.html#about-symbols">symbols</a> section for an
|
|
explanation of how project symbols work.</p>
|
|
|
|
<p>The Edit Symbol button opens the
|
|
<a href="editors.html#project-symbol">Edit Project Symbol</a> dialog, which
|
|
allows changing any part of a symbol definition. You're not allowed to
|
|
create two symbols with the same label.</p>
|
|
|
|
<p>The Import button allows you to import symbols from another project.
|
|
Only labels that have been tagged as global and exported will be imported.
|
|
Existing symbols with identical labels will be replaced, so it's okay to
|
|
run the importer multiple times. Labels that aren't found will not be
|
|
removed, so you can safely import from multiple projects, but will need
|
|
to manually delete any symbols that are no longer being exported.</p>
|
|
|
|
<p>Shortcut: you can open the project properties window with the
|
|
Project Symbols tab selected by hitting F6 from the main code list.</p>
|
|
|
|
|
|
<h3><a name="projprop-symfiles">Symbol Files</a></h3>
|
|
<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 "Add Symbol Files from Runtime" button sets the directory
|
|
to the SourceGen RuntimeData directory, while "Add Symbol Files from Project"
|
|
starts in the project directory. If you haven't yet saved the project,
|
|
the latter button will be disabled. The only difference between the
|
|
buttons is the initial directory.</p>
|
|
<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><a name="projprop-extscripts">Extension Scripts</a></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 "Add Scripts from Runtime" button sets the directory
|
|
to the SourceGen RuntimeData directory, while "Add Scripts from Project"
|
|
starts in the project directory. If you haven't yet saved the project,
|
|
the latter button will be disabled. The only difference between the
|
|
buttons is the initial directory.</p>
|
|
<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>
|