6502bench SourceGen: Tools

Instruction Chart

This opens a window with a summary of all 256 opcodes. The CPU can be chosen from the pop-up list at the bottom. Undocumented opcodes for 6502/65C02 are shown in italics, and can be excluded from the list by unchecking the box at the bottom.

The status flags affected by each instruction reflect their behavior on the 65816. The only significant difference between 65816 and 6502/65C02 is the way the BRK instruction affects the D and B/X flags.

ASCII Chart

This opens a window with the ASCII character set. Each character is displayed next to its numeric value in decimal and hexadecimal. The pop-up list at the bottom allows you to flip between standard and "high" ASCII.

Apple II Screen Chart

The Apple II text and hi-res screens are mapped to memory in a way that makes sense to computers but is a little confusing for humans. This chart maps line numbers to addresses and vice-versa. Select different screens and sort orders from the list at the bottom.

Hex Dump Viewer

You can use this to view the contents of the project data file by double-clicking the "bytes" column, or with Actions > Show Hex Dump. The viewer is displayed in a "modeless" dialog that does not prevent you from continuing to work with the project. If you double-click a different line in the project, the viewer will automatically highlight those bytes.

You can also use this to view the contents of arbitrary files by using Tools > Hex Dump. There is no fixed limit on the number of viewers you can have open simultaneously. (Be aware that the viewer currently loads the entire file into memory, and you will run out of room eventually. Not coincidentally, the viewer has a size limit of 16MiB per file.)

You can select lines with the mouse as you would in any other list view. Ctrl+A selects all lines. Ctrl+C copies the selected lines to the system clipboard.

The "character conversion" selector allows you to choose how the bytes are converted to characters for the Text column. Choose from the usual set of encodings.

If "ASCII-only dump" is not checked, non-printable bytes are shown in the ASCII dump as a middle dot ('·'). If the box is checked, non-printable bytes are represented by a period ('.') instead. The use of non-ASCII characters makes the dump unambiguous when unprintable characters are mixed with periods, but the lines may be unsuitable for pasting in some forums.

If "always on top" is checked, the window will stay above all other windows that don't also declare that they should always be on top. By default this box is checked when displaying project data, and not checked for external files.

File Concatenator

The File Concatenator combines multiple files into a single file. Select the files to add, arrange them in the proper order, then hit "Save". CRC-32 values are shown for reference.

File Slicer

The File Slicer allows you to "slice" a piece out of a file, saving it to a new file. Specify the start and length in decimal or hex. If you leave a field blank, they will default to offset 0 and the remaining length of the file, respectively.

The hex dumps show the area just before and after the chunk to be sliced, allowing you to confirm the placement.

OMF Converter

This tool allows you to view Apple IIgs Object Module Format (OMF) executables, and convert them for disassembly.

OMF executables have multiple segments with relocatable code. References to addresses aren't filled in until the program is loaded into memory, which makes it difficult to disassemble the file. The conversion tool loads the OMF file in roughly the same way the GS/OS System Loader would, placing each segment at the start of a bank unless otherwise directed. The loaded image is saved to a new file, and a SourceGen project file is created with some basic attributes filled in.

Only "Load" files (S16, PIF, TOL, etc) may be converted. Compiler object files and libraries contain references that must be resolved by a IIgs linker, and are not supported.

Before you can examine or convert a file, you must first extract it from the Apple II disk image, using a mode that does not modify the original (e.g. extract with "configure to preserve Apple II formats" in CiderPress). Then, open it with the "Tools > Convert OMF".

The initial view shows all of the OMF segments in the file. Double-clicking on an entry opens a detailed view that shows the segment header and a list of all the OMF records. For load files, the relocation dictionary is also shown.

To convert the file, click "Generate" to create a modified binary and a SourceGen project file.

If "offset segment start by $0100" is checked, the converter will try to shift the segment's load address from $xx/0000 to $xx/0100. This can make the generated code a little nicer to work with because it removes potential ambiguity with direct page addresses. For example, LDA $56 and LDA $0056 may be interpreted as the same thing by the assembler, requiring generation of operand width disambiguators. By shifting the initial address we avoid the potential ambiguity.

Check "add comments and notes for each segment" to add a long comment and a note at the start of each segment. The comments include the segment name, type, and optional flags. The notes just provide a quick way to jump to a segment.

The binary generated by the tool is not in OMF format and will not execute on an Apple IIgs. To be functional, the generated sources must be assembled by a program capable of generating OMF output, such as Merlin.

The relocation dictionaries from the executable are included in the project file, and can be used to guide the disassembler's analysis. The "use reloc data" setting in the project properties controls this feature.

A full explanation of the structure of OMF is beyond the scope of this manual. For more information on OMF, see Appendix F of the GS/OS Reference Manual.

Back to index