6502bench

- Introduction
- About Disassembly
- Using SourceGen
  - Moving Around
  - Making Edits
  - Labels & Symbols
  - Editing Data Operands
  - Generating Code
- Digging Deeper
  - String Formatting
  - Local Variables
  - Inline Data
  - Odds & Ends
- Advanced Topics
  - Address Tables
  - Extension Scripts
  - Visualizations
- Suggestions

## Making Edits

Click the very first line of the file, which is a comment that says something like "6502bench SourceGen vX.Y.Z". That's not very inspiring, so let's change it. There are three ways to open the comment editor:

1. Select `Actions > Edit Long Comment` from the menu bar.
2. Right click, and select `Edit Long Comment` from the pop-up menu. (This menu is exactly the same as the Actions menu.)
3. Double-click the comment

Most things in the code list will respond to a double-click. Double-clicking on addresses, flags, labels, operands, and comments will open editors for those things. Double-clicking on a value in the "Bytes" column will open a floating hex dump viewer. This is usually the most convenient way to edit something: point and click.

Double-click the comment to open the editor. Type some words into the upper window, and note that a formatted version appears in the bottom window. Experiment with the maximum line width and "render in box" settings to see what they do. You can hit Enter to create line breaks, or let SourceGen wrap lines for you. When you're done, click `OK`. (Or hit `Ctrl+Enter`.)

When the dialog closes, you'll see your new comment in place at the top of the file. If you typed enough words, your comment will span multiple lines. You can select the comment by selecting any line in it.

Click on the comment, then shift-click on L1014. Right-click, and look at the menu. Nearly all of the menu items are disabled. Most edit features are only enabled when a single instance of a relevant item is selected, so for example `Edit Long Comment` won't be enabled if you have an instruction selected.

Let's add a note. Click on $100E (the line with "hello!"), then select `Actions > Edit Note`. Type a few words, pick a color, and click `OK` (or hit `Ctrl+Enter`). Your note appears in the code, and also in the window on the bottom left. Notes are like long comments, with three key differences:

1. You can't pick their line width, but you can pick their color.
2. They don't appear in generated assembly sources, making them useful for leaving notes to yourself as you work.
3. They're listed in the Notes window. Double-clicking them jumps the selection to the note, making them useful as bookmarks.

#### Operands & End-of-Line Comments

Select the line with address $1000 ("`LDY #$70`"), then `Actions > Edit Operand`. This allows you to pick how you want the operand to look. It's currently set to `Default`, which for an 8-bit immediate argument means it's shown as a hexadecimal value. Click `Decimal`, then `OK`. It now appears as a decimal value.

You can also open the editor by double-clicking the operand.

If you double-click on a data item, such as the string at $100e, you will open the Data Operand Editor instead of the Instruction Operand Editor. (There will be more about this later.)

On the line at $1000, select `Actions > Edit Comment`. Type a short comment, and hit `Enter`. Your comment appears at the end of the line, in the "comment" column.

You can also open the editor by double-clicking in the comment column.

#### Address Regions

Let's take a closer look at the program, which has a short section of code followed by a bunch of data. The initial code segment is reading bytes from $1017 and writing them to $2000, using an index register that starts at 112 ($70) and counts down past zero. That means it's copying 113 ($71) bytes. When the copy is done, execution jumps to the copy of the code at $2000. It appears to be relocating the next part of the code before executing it. The disassembler needs to be told about the address change, which we do with the Address Region Editor.

When defining an address region, there are two ways to go about it. If you know where the region ends, you can select the entire thing, and create it with an explicit size. If you're not sure where it ends, you can create a region with a "floating" end that continues until it runs into another region or the end of the file. Let's try it both ways.

Select the line at address $1017 and then `Actions > Create/Edit Address Region`. (Or double-click on "`1017`" in the `Addr` column.) Since we only have one line selected, the address region editor defaulted to "`Create floating`". It will put the floating end marker $71 bytes after the start, which happens to be what we want. (It turns out the tutorial is copying all data to the end of the file... how convenient.) In the `Address` field, type "`2000`", and click `OK` (or hit `Enter`).

Note the way the code list has changed. When you changed the address, the `JMP $2000` at address $1014 found a home inside the bounds of the file, so the code tracer was able to find the instructions there. We now have all code and data correctly identified automatically, without the need to explicitly tag anything.

From the menu, select `Edit > Undo`. Notice how everything reverts to the way it was. Now, select `Edit > Redo` to restore the changes. You can undo any change you make to the project. (The undo history is not saved in the project file, though, so when you exit the program the history is lost.)

Hit `Edit > Undo` one more time, so we're back to where we were before we added the address region. Let's try creating it the other way.

Click on line $1017, then scroll to the bottom and shift-click on the very last line ("`.adrend`"). (If you prefer to use keyboard navigation, move to line $1017, then hit `Shift+PgDn` until the selection includes the end of the file.) If you look at the Info window in the bottom-right, you should see a line that says, "`Selection spans 113 ($71) bytes`", which is what we want.

Use `Actions > Create/Edit Address Region` to open the editor. This time we have selected more than one line, so "`Create fixed`" is selected by default. Enter "`2000`" in the Address field, and click `OK`.

The results are the same as before. If the region being copied had been a small part of the file, rather than continuing all the way to the end, the outcome would have been slightly different. When an address region with a fixed length ends, the next byte will be assigned an address based on the previous region. So if you created a region that mapped addresses $1017-$1046 to $2000-202f, then the next byte would be at address $1047. This is very useful for code that relocates small parts of itself, or uses memory mapping tricks to execute parts of itself at different locations.

#### Address vs. Offset

As you make alterations to the addresses, you will notice that, while the `Address` column changes, the `Offset` column does not. File offsets never change, which is why they're shown here and in the References and Notes windows. (They can, however, be distracting, so you'll be forgiven if you reduce the offset column width to zero.)

In some cases, such as programs with multiple segments or overlays, the same address may apply to several different areas. SourceGen fully supports binaries with overlapping parts.

« Previous Next »