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:
- Select Actions > Edit Long Comment from the menu bar.
- Right click, and select Edit Long Comment from the pop-up menu. (This menu is exactly the same as the Actions menu.)
- 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:
- You can't pick their line width, but you can pick their color.
- They don't appear in generated assembly sources, making them useful for leaving notes to yourself as you work.
- 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.