6502bench SourceGen: Properties & Settings

Settings Overview

There are two classes of settings: application settings, and project properties.

Application settings are stored in a file called "SourceGen-settings" in the SourceGen installation directory. If the file is missing or corrupted, some 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.

Project properties are stored in each individual .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.

Application Settings

The settings editor is divided into four tabs. Changes aren't pushed out to the main application until you hit Apply or OK.

Code View

These settings change the way the code looks on screen.

Click the Column Visibility buttons to hide columns. Click them again to restore the column to a default width. A "hidden" column just has a width of zero, so with careful mouse positioning you can show and hide columns from the code list. The buttons may be more convenient though.

You can select a different font for the code list. Make it as large or small as you want. Mono-space fonts like Courier or Consolas are recommended.

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 values are also used for generated assembly code. Note that labels are case-sensitive and can't be forced one way or the other.

The Clipboard drop-down menu lets you choose the format for text copied to the clipboard. 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.

Asm Config

These settings configure cross-assemblers and modify assembly source generation in various ways.

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.

The "executable" box holds the full path to the cross-assembler executable. For cc65 this is bin/cl65.exe, for Merlin32 you need Merlin32.exe. (On non-Windows platforms, you won't need the ".exe".) For cc65 you need a full installation, with the configuration files and libraries, not just the cl65 binary itself.

The "column widths" section allows you to specify the 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. (Note: the comment width isn't used at this time.)

When "show cycle counts" is checked, every instruction line will have an end-of-line comment that indicates the number of cycles required for that instruction. This is shown in the code list and included in generated assembly output. If the cycle count can't be determined solely from a static analysis, e.g. an extra cycle is required if LDA (dp),Y 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.

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.)

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. 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.

"Disable label localization" turns off the label localizer.

Display Format

These options change the way the code list looks on screen. They do not affect generated code.

The operand width disambiguator strings are used when the width of an instruction operand is unclear. You may specify values for all of them or none of them.

The Merlin assembler uses an expression syntax that is compact but different from many other cross-assemblers. Notably, the byte-selection operators ('<', '>', '^') act like shift operators, yielding 16-bit values when wide registers are enabled on the 65816.

The "quick set" buttons configure the fields on this tab to match the conventions of the specified assembler. Select your preferred assembler with the combox box, then click "set" to set the fields.

Pseudo-Op

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.

Enter the string you want to use for the various data formats. If a field is left blank, a default value is used.

The "quick set" buttons configure the fields on this tab to match the conventions of the specified assembler. Select your preferred assembler with the combox box, then click "set" to set the fields.

Project Properties

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 "latch" the current changes, ensuring that they're applied even if you later hit Cancel, but the changes are not applied immediately.

All changes are subject to undo/redo.

General

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 three:

MOS 6502. The original 8-bit instruction set.
WDC W65C02S. Expanded the instruction set and smoothed some rough edges.
WDC W65C816S. Expanded instruction set, 24-bit address space, and 16-bit registers.

The Rockwell R65C02, Hudson Soft HuC6280, and Commodore CSG 4510 / 65CE02 have instruction sets that expand on the 6502/65C02, but aren't compatible with the 65816. These are not yet supported by SourceGen.

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.

The entry flags determine the initial value for the processor status flag register. Code that is unreachable internally (requiring a code entry point hint) will use this value. This is chiefly of use for 65816 code, where the initial value of the M/X/E flags is significant.

If "analyze uncategorized data" is checked, SourceGen will attempt to identify strings and regions filled with a single byte value. If it's not checked, anything that isn't detected as code or explicitly formatted will simply be shown as a byte value.

If "seek nearby targets" is checked, the analyzer will try to use nearby labels for data loads and stores.

The "minimum characters for string" 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.

Project Symbols

You can add, edit, and delete individual symbols and constants. See the symbols section for an explanation of how project symbols work.

The Edit Symbol button opens the Edit Project Symbol dialog, which allows changing any part of a symbol definition. You're not allowed to create two symbols with the same label.

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.

Symbol Files

From here, you can add and remove platform symbol files, or change the order in which they are loaded. See the symbols section for an explanation of how platform symbols work, and the advanced topics section for a description of the file syntax.

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.

In the list, files loaded from the RuntimeData directory will be prefixed with RT:. Files loaded from the project directory will be prefixed with PROJ:.

If a platform symbol file can't be found when the project is opened, you will receive a warning.

Extension Scripts

From here, you can add and remove extension script files. See the extension scripts section for an overview of how extension scripts work. There's a more detailed document in the RuntimeData directory ("ExtensionScripts.md").

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.

In the list, files loaded from the RuntimeData directory will be prefixed with RT:. Files loaded from the project directory will be prefixed with PROJ:.

If an extension script file can't be found when the project is opened, you will receive a warning.