6502bench SourceGen: Main Window

Back to index

Starting a New Project

Select File > New, or if no project is open, click "Start new project". This opens the Create New Project window.

Start by selecting your target system from the tree on the left. The panel on the right will show the CPU that will be selected, as well as the symbol files and extension scripts that will be loaded by default. All of these may be overridden later from the project properties.

Next, click the "Select File..." button. Pick the file you wish to disassemble. The dialog will update with the pathname and some notes about the file's size. Click "OK" if all looks good to create the project.

NOTE: Support for large 65816 programs is incomplete. The maximum size for a data file is currently 1 MiB.

The first time you save the project (with File > Save), you will be prompted for the project name. It's best to use the data file's name with ".dis65" added. This will be configured automatically. The data file's name is not stored in the project file, so if you pick a different name, or save the project in a different directory, you will have to select the data file manually whenever you open the project.

Opening an Existing Project

Select File > Open, or if no project is open, click "Open existing project". Select the .dis65 project file from the standard file dialog.

SourceGen will try to open a data file with the project's name, minus the ".dis65". If it can't find a file with that name, or if there's something wrong with it (e.g. the CRC doesn't match), you will be given the opportunity to specify the location of the data file to use.

If non-fatal problems with the file are detected, a warning will be shown. If it's something simple, like a missing .sym65 or extension script file, you'll be notified. If it's something more complicated, e.g. the project has a comment on an offset that doesn't exist, you will be warned that the problematic data has been deleted, and will be lost if the project is saved. You will also be given the opportunity to cancel the loading of the project.

The locations of the last few projects you've worked with are saved in the application settings. You can access them from File > Recent Projects. If no project is open, links to the two most-recently opened projects will be available.

Working With a Project

The main project window is divided into five areas:

  1. Center: the code list. If no project is open, this will instead have clickable links to open a new or existing project.
  2. Top left: cross-reference list.
  3. Bottom left: notes list.
  4. Top right: symbols list.
  5. Bottom right: line info.

Most of the action takes place in the center code list.

Code List

The code list provides a view of the code being disassembled. Each line may be an instruction, data item, long comment, note, or assembler directive.

The list is divided into columns:

Double-clicking anywhere on a line with a note or long comment will open the Edit Note or Edit Long Comment dialog, respectively.

The code list is a standard Windows list view. You can left-click to select an item, ctrl-left-click to toggle individual items on and off, and shift-left-click to select a range. You can select all lines with Edit > Select All. Resize columns by left-clicking on the divider in the header and dragging it.

Multi-line items, such as long comments or ASCII strings, are selected as a whole when any part is selected.

Right-clicking opens a menu. The contents are the same as those in the Actions menu item in the menu bar. The set of options that are enabled will depend on what you have selected in the main window.

Undo & Redo

You can undo a change with Edit > Undo, or Ctrl+Z. You can redo a change with Edit > Redo, Ctrl+Y, or Ctrl+Shift+Z.

All changes to the project, including changes to the project properties, are added to the undo/redo buffer. This has no fixed size limit, so no matter how much you change, you can always undo back to the point where the project was opened.

The undo buffer is not saved as part of the project, so closing and reopening the project resets the buffer.

References Window

When a single instruction or data line is selected in the main window, all references to that offset will be shown in the References window. For each reference, the file offset, address, and some details about the type of reference will be shown.

The reference type indicates whether the origin is an instruction or data operand. Branch instructions are called out separately. In addition, it will be identified as a numeric or symbolic reference. Symbolic references may be offset from the actual operand value; if this is the case, the adjustment will be shown as well.

Double-clicking on a reference moves the code list selection to that reference, and adds the previous selection to the navigation stack.

Notes Window

When you add a note, it will also be added to this window. Double-clicking on a note will jump directly to it, and add the previous selection to the navigation stack. This makes notes useful as bookmarks.

Symbols Window

All known symbols are shown here. The filter buttons allow you to screen out symbols you're not interested in, such as platform symbols or constants.

Clicking on one of the column headers will sort the list on that field. Click a second time to reverse the sort direction.

Double-clicking on an auto or user label will jump to that label, and add the previous selection to the navigation stack. This can be a handy way to move around the file, jumping from label to label.

Info Window

Some additional information about the currently-selected line is shown, such as the formatting applied to the operand. If the operand has a default format, any automatically-generated format will be noted. For an instruction, a summary is shown that includes the cycle count, flags affected, and a brief description of what the instruction does. The latter can be especially handy for undocumented instructions.

Navigation

The simplest way to move through the code list is with the scroll wheel on your mouse, or by left-clicking and dragging the scroll bar. You can also use PgUp/PgDn and the arrow keys.

Use Edit > Find to search for text. This performs a case-insensitive text search on the label, opcode, operand, and comment fields. Use Edit > Find Next to find the next match.

Use Edit > Go To to jump to an offset, address, or label. Remember that offsets and addresses are always hexadecimal, and offsets start with a '+'.

When you jump around, by double-clicking on an opcode or an entry in one of the side windows, the currently-selected line is added to a navigation stack. You can use the arrows on the toolbar to navigate forward or backward. (You can use Alt+Left/Right Arrow, or Ctrl+- / Ctrl+Shift+-, as keyboard shortcuts.)

Adding and Removing Hints

To add code entry or data hints, select the offsets with the instruction opcodes, and then use the "Hint as Code Entry Point" or "Hint as Data" menu item. Remember to avoid hinting additional bytes, especially with code entry points, as that can lead to unwanted embedded instructions.

For inline data, select all of the data that the code analyzer should skip, and use the "Hint as Inline Data" menu item.

If you're having a hard time selecting just the right bytes because the instructions are caught up in a multi-byte data item, such as an auto-detected ASCII string, you can use the "Toggle Single-Byte Format" menu item to "flatten" the item. Apply the hint, then toggle the bytes back to default format. You can also disable uncategorized data analysis entirely from the project properties editor.

Copying to Clipboard

When you use Edit > Copy, all lines selected in the code list are copied to the system clipboard. This can be a convenient way to post code snippets into forum postings or documentation. The text is copied from the data shown on screen, so your chosen capitalization and pseudo-ops will appear in the copy.

A copy of all of the fields is also written to the clipboard, in CSV format. If you open a program like Excel, you can use Paste Special to put the data into individual cells.

By default, the label, opcode, operand, and comment fields are included in the text form. From the app settings you can select a different format that also includes the address and byte columns.