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

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. This is explained in more detail below.

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

Reserved Label Names

Some label names aren't allowed. For example, 64tass reserves the use of labels that begin with two underscores. Most assemblers will also prevent you from using opcode mnemonics as labels (which means you can't assemble the infinite loop jmp jmp jmp).

If a label doesn't appear to be legal, the generated code will use a suitable replacement (e.g. jmp_1 jmp jmp_1).

Platform-Specific Features

SourceGen needs to be able to assemble binaries for any system with any assembler, so it generally avoids platform-specific features. One exception to that is C64 PRG files.

PRG files start with a 16-bit value that tells the OS where the rest of the file should be loaded. The value is not usually part of the source code, but instead is generated by the assembler, based on the address of the first byte output. If SourceGen detects that a file is PRG, the source generators for some assemblers will suppress the first 2 bytes, and instead pass appropriate meta-data (such as an additional command-line option) to the assembler.

A file is treated as a PRG if:

• it is between 3 and 65536 bytes long (inclusive)
• the format at offset +000000 is a 16-bit numeric data item (not executable code, not two 8-byte values, not the first part of a 24-bit value, etc.)
• there is an address region start directive at +000002
• the 16-bit value at +000000 is equal to the address of the byte at +000002
• there is no label at offset +000000 (explicit or auto-generated)

The definition is sufficiently narrow to avoid most false-positives. If a file is being treated as PRG and you'd rather it weren't, you can add a label or reformat the bytes. This feature is currently only enabled for 64tass.

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.

Supported Assemblers

SourceGen currently supports the following cross-assemblers:

• 64tass
• ACME
• cc65
• Merlin 32

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 the code has a statement like MVN #$01,#$02, the assembler is expected to output 54 02 01, with the arguments reversed. cc65 v2.17 got it backward; the behavior was fixed in v2.18. The bug means we can't generate the same MVN/MVP instructions for both versions of the assembler.

Having version-dependent source code is a bad idea. If we generated reversed operands (MVN #$02,#$01), we'd get the correct output with v2.17, but the wrong output for v2.18. Unambiguous code can 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 that forever. We want to detect which version of the assembler is in use, and output actual MVN/MVP instructions when producing code for versions of the assembler that don't have the bug.

When you configure a cross-assembler, SourceGen runs the executable with version query arguments, and extracts the version information from the output stream. This is used by the generator to ensure that the output will work correctly with the installed assembler. If the assembler is present on the system, SourceGen will produce code optimized for the latest supported version of the assembler.

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 alternate (and non-existent) form of PEA with indirect addressing, causing the assembler to halt with an error message. 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.

Undocumented Opcodes

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.

The most authoritative source is NMOS 6510 Unintended Opcodes (PDF). 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.

64tass

Tested versions: v1.53.1515, v1.54.1900, v1.55.2176, v1.56.2625 [web site]

Bugs:

• [Fixed in v1.55.2176] Undocumented opcode SHA (ZP),Y ($93) is not supported; the assembler appears to be expecting SHA ABS,X instead.
• [Fixed in v1.55.2176] WDM is not supported.

Quirks:

• The underscore character ('_') is allowed as a character in labels, but when used as the first character in a label it indicates the label is local. If you create labels with leading underscores that are not local, the labels must be altered to start with some other character, and made unique.
• Labels starting with two underscores are "reserved". Trying to use them causes an error.
• By default, 64tass sets the first two bytes of the output file to the load address. The --nostart flag is used to suppress this.
• By default, 64tass is case-insensitive, but SourceGen treats labels as case-sensitive. The --case-sensitive flag must be passed to the assembler.
• If you set the --case-sensitive flag, all opcodes and operands must be lower-case. Most of the SourceGen options that cause things to appear in upper case must be disabled.
• For 65816, selecting the bank byte is done with the grave accent character ('`') rather than the caret ('^'). (There's a note in the docs to the effect that they plan to move to carets.)
• Instructions whose argument is formed by combining with the 65816 Program Bank Register (16-bit JMP/JSR) must be specified as 24-bit values for code that lives outside bank 0. This is true for both symbols and raw hex (e.g. JSR $1234 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 a 16-bit operand.
• The arguments to COP and BRK require immediate-mode syntax (COP #$03 rather than COP $03).
• For historical reasons, the default behavior of the assembler is to assume that the source file is PETSCII, and the desired encoding for strings is also PETSCII. No character conversion is done, so anybody assembling ASCII files will get ASCII strings (which works out pretty well if you're assembling code for a non-Commodore target). However, the documentation says you're required to pass the "--ascii" flag when the input is ASCII/UTF-8, so to build files that want ASCII operands an explicit character encoding definition must be provided.

ACME

Tested versions: v0.96.4, v0.97 [web site]

Bugs:

• The "pseudo PC" is only 16 bits, so any 65816 code targeted to run outside bank zero cannot be assembled. SourceGen currently deals with this by outputting the entire file as a hex dump.
• Undocumented opcode $AB (LAX #imm) generates an error.
• BRK is not allowed to have an operand.

Quirks:

• The assembler shares some traits with one-pass assemblers. In particular, if you forward-reference a zero-page label, the reference generates a 16-bit absolute address instead of an 8-bit zero-page address. Unlike other one-pass assemblers, the width is "sticky", and backward references appearing later in the file also use absolute addressing even though the proper width is known at that point. This is worked around by using explicit "force zero page" annotations on all references to zero-page labels.
• Undocumented opcode ALR ($4b) uses mnemonic ASR instead.
• Does not allow the accumulator to be specified explicitly as an operand, e.g. you can't write LSR A.
• [Fixed in v0.97.] Syntax for MVN/MVP doesn't allow '#' before 8-bit operands.
• Officially, the preferred file extension for ACME source code is ".a", but this is already used on UNIX systems for static libraries (which means shell filename completion tends to ignore them). Since ".S" is pretty universally recognized as assembly source, code generated by SourceGen for ACME also uses ".S".
• Version 0.97 started interpreting '\' in strings as an escape character, to allow C-style escapes like "\n". This requires escaping all occurrences of '\' in data strings as "\\". Compiling an older source file with a newer version of ACME may fail unless you pass a backward-compatibility command-line argument.

cc65

Tested versions: v2.17, v2.18 [web site]

Bugs:

• PC relative branches don't wrap around at bank boundaries.
• BRK can only be given an argument in 65816 mode.
• [Fixed in v2.18] The arguments to MVN/MVP are reversed.
• [Fixed in v2.18] BRK <arg> is assembled to opcode $05 rather than $00.
• [Fixed in v2.18] WDM is not supported.

Quirks:

• Operator precedence is unusual. Consider label >> 8 - 16. cc65 puts shift higher than subtraction, whereas languages like C and assemblers like 64tass do it the other way around. So cc65 regards the expression as (label >> 8) - 16, while the more common interpretation would be label >> (8 - 16). (This is actually somewhat convenient, since none of the expressions SourceGen currently generates require parenthesis.)
• Undocumented opcode SBX ($cb) uses the mnemonic AXS. All other opcodes match up with the "unintended opcodes" document.
• 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 labels, but they're defined via .ORG $0000 after the point where the labels are used, the assembler will already have generated them as absolute values. Width disambiguation must be applied to operands that wouldn't be ambiguous to a multi-pass assembler.
• Assignment of constants and variables (= and .set) ends local label scope, so the label localizer has to take variable assignment into account.
• The assembler is geared toward generating relocatable code with multiple segments (it is, after all, an assembler for a C compiler). A linker configuration script is expected to be provided for anything complex. SourceGen generates a custom config file for each project.

Merlin 32

Tested Versions: v1.0 [web site] [bug tracker]

Bugs:

• PC relative branches don't wrap around at bank boundaries.
• For some failures, an exit code of zero is returned.
• Immediate operands with a comma (e.g. LDA #',') or curly braces (e.g. LDA #'{') cause an error.
• Some DP indexed store instructions cause errors if the label isn't unambiguously DP (e.g. STX $00,X vs. STX $0000,X). This isn't a problem with project/platform symbols, which are output as two-digit hex values when possible, but causes failures when direct page locations are included in the project and given labels.
• The check for 64KiB overflow appears to happen before instructions that might be absolute or direct page are resolved and reduced in size. This makes it unlikely that a full 64KiB bank of code can be assembled.

Quirks:

• Operator precedence is unusual. Expressions are generally processed from left to right. The byte-selection operators have a lower precedence than all of the others, and so are always processed last.
• The byte selection operators ('<', '>', '^') are actually word-selection operators, yielding 16-bit values when wide registers are enabled on the 65816.
• Values loaded into registers are implicitly mod 256 or 65536. There is no need to explicitly mask an expression.
• The assembler tracks register widths when it sees SEP/REP instructions, but doesn't attempt to track the emulation flag. So if you issue a REP #$20 while in emulation mode, the assembler will incorrectly assume long registers. Ideally it would be possible to configure that off, but there's no way to do that, so instead we occasionally generate additional width directives.
• Non-unique local labels should cause an error, but don't.
• No undocumented opcodes are supported, nor are the Rockwell 65C02 instructions.

Exporting Source Code

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 settings, such as capitalization, text delimiters, pseudo-opcode names, operand expression style, and display of cycle counts are all taken into account. The file generated is not expected to work with an actual assembler.

The text output is similar to what you'd get by copying lines to the clipboard and pasting them into a text file, except that you have greater control over which columns are included. The HTML version is augmented with links and (optionally) images.

Use File > Export to open the export dialog. You have several options:

• Include only selected lines. This allows you to choose between exporting all or part of a file. If no lines are selected, the entire file will exported. This setting does not affect link generation for HTML output, so you may have some dead internal links if you don't export the entire file.
• Include notes. Notes are normally excluded from generated sources. Check this to include them.
• Show <Column>. The leftmost five columns are optional, and will not appear in the output unless the appropriate option is checked.
• Column widths. These determine the minimum widths of the rightmost four columns. These are not hard limits: if the contents of the column are too wide, the next column will start farther over. The widths are not used at all for CSV output.
• Text vs. CSV. For text generation, you can choose between plain text and Comma-Separated Value format. The latter is useful for importing source code into another application, such as a spreadsheet.
• Generate image files. When exporting to HTML, selecting this will cause GIF images to be generated for visualizations.
• Overwrite CSS file. Some aspects of the HTML output's format are defined by a file called "SGStyle.css", which may be shared between multiple HTML files and customized. The file is copied out of the RuntimeData directory without modification. It will be created if it doesn't exist, but will not be overwritten unless this box is checked. The setting is not sticky, and will revert to unchecked. (Think of this as a proactive alternative to "are you sure you wish to overwrite SGStyle.css?")

Once you've picked your options, click either "Generate HTML" or "Generate Text", then select an output file name from the standard file dialog. Any additional files generated, such as graphics for HTML pages, will be written to the same directory.

All output uses UTF-8 encoding. Filenames of HTML files will have '#' replaced with '_' to make linking easier.

Generating Label Files

Some debuggers allow the import of labels associated with addresses. To generate such a file, use File > Generate Label File.

Select the desired output format (currently only VICE label commands are supported), and whether or not to include auto-generated labels.

Back to index