6502bench SourceGen: Code Generation & Assembly

Back to index

SourceGen can generate an assembly source file that, when fed into the target assembler, will recreate the original data file exactly. Every assembler is different, so support must be added to SourceGen for each.

The generation / assembly dialog can be opened with File > Assemble.

Supported Assemblers

SourceGen currently supports the following cross-assemblers:

Version-Specific Code Generation

Code generation must be tailored to the specific version of the assembler. This is most easily understood with an example.

If you write MVN $01,$02, the assembler is expected to output 54 02 01, with the arguments reversed. cc65 v2.17 doesn't do that; this is a bug that was fixed in a later version. So if you're generating code for v2.17, you want to create source code with the arguments the wrong way around.

Having version-dependent source code is a bad idea, so SourceGen just outputs raw hex bytes for MVN/MVP instructions. This yields the correct code for all versions of the assembler, but is ugly and annoying. So we want to output actual MVN/MVP instructions when producing code for newer versions of the assembler.

When you configure a cross-assembler, SourceGen runs the executable with version query args, and extracts the version information from the output stream. This is used by the generator to ensure that the output will compile. If no assembler is configured, SourceGen will produce code optimized for the latest version of the assembler.

Generating Source Code

Cross assemblers tend to generate additional files, either compiler intermediaries ("file.o") or metadata ("_FileInformation.txt"). Some generators may produce multiple source files, perhaps a link script or symbol definition header to go with the assembly source. To avoid spreading files across the filesystem, SourceGen does all of its work in the same directory where the project lives. Before you can generate code, you have to have assigned your project a directory. This is why you can't assemble a project until you've saved it for the first time.

The Generate and Assemble dialog has a drop-down list near the top that lets you pick which assembler to target. The name of the assembler will be shown with the detected version number. If the assembler executable isn't configured, "[latest version]" will be shown instead of a version number.

The Settings button will take you directly to the assembler configuration tab in the application settings dialog.

Hit the Generate button to generate the source code into a file on disk. The file will use the project name, with the ".dis65" replaced by "_<assembler>.S".

The first 64KiB of each generated file will be shown in the preview window. If multiple files were generated, you can use the "preview file" drop-down to select between them. Line numbers are prepended to each line to make it easier to track down errors.

Label Localizer

The label localizer is an optional feature that automatically converts some labels to an assembler-specific less-than-global label format. Local labels may be reusable (e.g. using "]LOOP" for multiple consecutive loops is easier to understand than giving each one a unique label) or reduce the size of a generated link table. There are usually restrictions on local labels, e.g. references to them may not be allowed to cross a global label definition, which the localizer factors in automatically.

The localizer is somewhat experimental at this time, and can be disabled from the application settings.

Cross-Assembling Generated Code

After generating sources, if you have a cross-assembler executable configured, you can run it by clicking the "Run Assembler" button. The command-line output will be displayed, with stdout and stderr separated. (I'd prefer them to be interleaved, but that's not what the system provides.)

The output will show the assembler's exit code, which will be zero on success (note: sometimes they lie.) If it appeared to succeed, SourceGen will then compare the assembler's output to the original file, and report any differences.

Failures here may be due to bugs in the cross-assembler or in SourceGen. However, SourceGen can generally work around assembler bugs, so any failure is an opportunity for improvement.

Assembler-Specific Bugs & Quirks

This is a list of bugs and quirky behavior in cross-assemblers that SourceGen works around when generating code.

Every assembler seems to have a different way of dealing with expressions. Most of them will let you group expressions with parenthesis, but that doesn't always help. For example, PEA label >> 8 + 1 is perfectly valid, but writing PEA (label >> 8) + 1 will cause most assemblers to assume you're trying to use an alterate form of PEA with indirect addressing (which doesn't exist). The code generator needs to understand expression syntax and operator precedence to generate correct code, but also needs to know how to handle the corner cases.

64tass

Code is generated for 64tass v1.53.1515.

Bugs:

Quirks:

cc65

Code is generated for cc65 v2.27.

Bugs:

Quirks:

Merlin 32

Code is generated for Merlin 32 v1.0.

Bugs:

Quirks: