diff --git a/SourceGen/DisasmProject.cs b/SourceGen/DisasmProject.cs index d092381..dbb96f1 100644 --- a/SourceGen/DisasmProject.cs +++ b/SourceGen/DisasmProject.cs @@ -2111,7 +2111,6 @@ public ChangeSet PopUndoSet() { /// /// Returns the next redo operation, and moves the pointer to the next item. /// - /// public ChangeSet PopRedoSet() { if (!CanRedo) { throw new Exception("Can't redo"); diff --git a/docs/sgtutorial/about-disasm.html b/docs/sgtutorial/about-disasm.html index 4817428..6dd87d7 100644 --- a/docs/sgtutorial/about-disasm.html +++ b/docs/sgtutorial/about-disasm.html @@ -152,13 +152,13 @@

About Disassembly

The process can be improved by keeping track of the flags in the 6502 status register. For example, in the code fragment shown - earlier, BMI conditional branch instruction is used. + earlier, the BMI conditional branch instruction is used. A simple tracing algorithm would both follow the branch and fall through to the following instruction. However, the code that precedes the BMI ensures that the branch is always taken, so a clever disassembler would only trace that path.

-

(The situation is worse on the 65816, because the length of +

(This is even more important on the 65816, because the length of certain instructions is determined by the values of the processor status flags.)

diff --git a/docs/sgtutorial/address-tables.html b/docs/sgtutorial/address-tables.html index caf1dbb..e0bc058 100644 --- a/docs/sgtutorial/address-tables.html +++ b/docs/sgtutorial/address-tables.html @@ -96,7 +96,8 @@

Address Tables

Select File and navigate to the 6502bench Examples directory. In the "A2-Amper-fdraw" directory, select the file "AMPERFDRAW#061d60" (just ignore the existing .dis65 file). - Click OK to create the project.

+ Click OK to create the project. Click Cancel + to skip saving the project file.

@@ -145,7 +146,7 @@

Address Tables

As it happens, the start address of the code is $1D60 -- the last four digits of the filename -- so let's make that - change. Double-click the initial .ORG statement, + change. Double-click the initial .ADDRS statement, and change it from $2000 to $1D60. We can now see that $1D70 starts right after this initial chunk of code.

@@ -212,7 +213,7 @@

Address Tables

<FUNC-152, you forgot to select the high part.)

We've now changed the first entry in the address table to a - symbolic reference, which is helps someone reading the code to + symbolic reference, which will help someone reading the code to understand what is being referenced. You could repeat these steps (tag as code, set label, change address bytes to symbols) for the remaining items, but there's an easier way.

diff --git a/docs/sgtutorial/digging-deeper.html b/docs/sgtutorial/digging-deeper.html index 47e532a..5faff06 100644 --- a/docs/sgtutorial/digging-deeper.html +++ b/docs/sgtutorial/digging-deeper.html @@ -87,9 +87,10 @@

Digging Deeper

-

This tutorial will walk you through some of the fancier things SourceGen - can do. We assume you've already finished the basic features tutorial, - and know how to create projects and move around in them.

+

This part of the tutorial will walk you through some of the + fancier things SourceGen can do. We assume you've already finished + the basic features tutorial, and know how to create projects and move + around in them.

Start a new project. Select Generic 6502. For the data file, navigate to the Examples directory, then from the Tutorial directory select "Tutorial2".

diff --git a/docs/sgtutorial/editing-data.html b/docs/sgtutorial/editing-data.html index 620e5df..d6acc67 100644 --- a/docs/sgtutorial/editing-data.html +++ b/docs/sgtutorial/editing-data.html @@ -105,10 +105,11 @@

Editing Data

t1-data-editdlg-1
-

Select the last line in the file, then Actions > Edit Operand. - You'll notice that this dialog is much different from the one you got when editing - the operand of an instruction. At the top it will say "65 bytes - selected". You can format this as a single 65-byte string, as 65 individual +

Select the last line of data in the file ($2030), then + Actions > Edit Operand. You'll notice that this dialog + is much different from the one you got when editing the operand of an + instruction. At the top it will say "65 bytes selected". + You can format this as a single 65-byte string, as 65 individual items, or various things in between. For now, select Single bytes, and then on the right, select ASCII (low or high) character. Click OK.

diff --git a/docs/sgtutorial/extension-scripts.html b/docs/sgtutorial/extension-scripts.html index bf7c3bc..20f98a6 100644 --- a/docs/sgtutorial/extension-scripts.html +++ b/docs/sgtutorial/extension-scripts.html @@ -93,7 +93,9 @@

Extension Scripts

An earlier tutorial demonstrated how to manually mark bytes as inline data. We're going to do it a faster way. For this tutorial, start a new project with the Generic 6502 profile, and - in the SourceGen Examples/Tutorial directory select "Tutorial4".

+ in the SourceGen Examples/Tutorial directory select "Tutorial4" as + the data file. + You can choose to save the project file or not.

@@ -125,9 +127,10 @@

Extension Scripts

Nothing happened. If you look at the script with an editor (and you - know some C#), you'll see that it's looking for a JSR to a - function that begins with certain prefixes. For ASCII length-delimited - strings, the prefix is InA1_. So let's set a label.

+ know some C#), you'll see that it's looking for JSR + instructions that call functions whose names begin with certain strings. + For ASCII strings prefixed with a 1-byte length, the appropriate + function name prefix is InA1_. So let's set a label.

@@ -149,9 +152,9 @@

Extension Scripts

This time, double-click the JSR operand ("L1036") to edit the operand. - Click Create Label, and enter InA1_PrintString. - Remember that labels are case-sensitive; - you must enter it exactly as shown. Hit OK to accept the label, + Click Create Label, and enter "InA1_PrintString". + Remember that labels are case-sensitive; you must enter it exactly + as shown (note the lower-case 'n'). Hit OK to accept the label, and OK to close the operand editor.

@@ -177,9 +180,9 @@

Extension Scripts

Double-click the operand on line $100D ("L1037"), click Create Label, and set the label to "InAZ_PrintString1". - Hit OK twice. That formatted the first one and got us - to the next JSR, at $1019. Repeat the process on line $1019 - ("L1038"), setting the label to + Hit OK twice. That formatted the string that followed, + and got us to the next JSR, at $1019. Repeat the + process on line $1019 ("L1038"), setting the label to "InAZ_PrintString2".

@@ -192,14 +195,14 @@

Extension Scripts

The last JSR, at $1025, is followed by a 16-bit pointer. Edit the operand, and use Create Label to set the label at the target address to "InWA_StringPtr". - Because the bytes were formatted as an address and not a just a - 16-bit value, a label was generated automatically.

- -

What we'd really like to do in this case is to have it format the - 16-bit address as a pointer, and format the data it points to as - a null-terminated string. The StdInline script doesn't know how to - do that though, so you'd need to write a custom script. (Scripts - can format multiple data items, add symbolic references to labels + This causes the two bytes to be formatted as a 16-bit address, + rather than just a 16-bit value, so a label was generated + automatically at the target address ("L102B").

+ +

It would be even more helpful if it formatted the data at $102B + as a null-terminated string. The basic StdInline script doesn't + happen to do that, but it's possible to do it with a custom script. + (Scripts can format multiple data items, add symbolic references to labels and constants, and chase pointers around.)

The entire project is now nicely formatted. In a real project the @@ -207,7 +210,9 @@

Extension Scripts

instructions. There would likely be multiple JSRs to the print function, so labeling a single function entry point could format dozens of inline strings and clean up the disassembly automatically. The reason for - allowing wildcard names is that some functions may have multiple + using name prefixes like InAZ_, rather than full function + names, is that there may be more than one function with the same stack + mechanics. Also, some functions may have multiple entry points or chain through different locations.

diff --git a/docs/sgtutorial/labels-symbols.html b/docs/sgtutorial/labels-symbols.html index 7f87c95..65d1017 100644 --- a/docs/sgtutorial/labels-symbols.html +++ b/docs/sgtutorial/labels-symbols.html @@ -94,13 +94,13 @@

Labels & Symbols

can greatly improve the readability of the code: something like JSR DrawSprite is far more helpful for human readers. Further, once the code has been disassembled to source code, using symbols - instead of fixed addresses makes it easier to alter the program or re-use - the code.

+ instead of fixed addresses makes it easier to alter the program or reuse + the code in another project.

When the target address of instructions like JSR and LDA falls within the scope of the data file, SourceGen classifies the reference as internal, and automatically adds a generic - symbolic label (e.g. L1000). This can be edited if desired.

+ symbolic label (e.g. L1000). The label can be edited if desired.

@@ -367,7 +367,7 @@

Non-Unique Labels

button is selected automatically if you start a label with '@' (or whatever character you have configured). Click OK.

You now have two lines with the same label. In some cases the - assembly source generator need to may "promote" them to globals, or + assembly source generator may need to "promote" them to globals, or rename them to make them unique, depending on what your preferred assembler allows.

diff --git a/docs/sgtutorial/local-variables.html b/docs/sgtutorial/local-variables.html index c17acd2..4893437 100644 --- a/docs/sgtutorial/local-variables.html +++ b/docs/sgtutorial/local-variables.html @@ -91,7 +91,7 @@

Local Variables

Let's move on to the code at $203D. It starts by storing a couple of - values into direct page address $02/03. This appears to be setting up a + values into zero page addresses $02/03. This appears to be setting up a pointer to $2063, which is a data area inside the file. So let's make it official.

@@ -158,8 +158,8 @@

Local Variables

t2-20a7
-

Double-click on the JSR opcode on line $2045 to jump to - L20A7. +

Double-click on the JSR opcode on line $2045 to jump + way down to L20A7. The code here just loads a value from $3000 into the accumulator and returns, so not much to see here. Hit the back-arrow in the toolbar to jump back to the JSR.

@@ -256,7 +256,8 @@

Showing Cycle Counts

Edit > Settings to open the app settings panel. In the Miscellaneous group on the right side, click the Show cycle counts for instructions checkbox, then click - OK. (There's also a toolbar button for this.)

+ OK. (There's also a toolbar button that toggles it + on and off.)

@@ -287,7 +288,8 @@

Showing Cycle Counts

The following instruction, ORA #$80, cleared the 'Z' flag and set the 'N' flag, so a BMI would also be an always-taken branch.)

-

The cycle-count comments can be added to generated source code as well.

+

The cycle-count comments can be added to generated source code as well, + with an application setting in the Asm Config tab.

If you add an end-of-line comment, it appears after the cycle count. (Try it.)

diff --git a/docs/sgtutorial/making-edits.html b/docs/sgtutorial/making-edits.html index 0dbf8ec..8e88a05 100644 --- a/docs/sgtutorial/making-edits.html +++ b/docs/sgtutorial/making-edits.html @@ -146,7 +146,7 @@

Making Edits

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. +
  2. You can't really format the text, but you can pick their color.
  3. They don't appear in generated assembly sources, making them useful for leaving notes to yourself as you work.
  4. They're listed in the Notes window. Double-clicking them jumps diff --git a/docs/sgtutorial/moving-around.html b/docs/sgtutorial/moving-around.html index e5765e6..66e4a58 100644 --- a/docs/sgtutorial/moving-around.html +++ b/docs/sgtutorial/moving-around.html @@ -99,7 +99,7 @@

    Moving Around

  5. Symbols. All known symbols. The buttons at the top allow you to filter out symbol types that you're not interested in.
  6. Info. Information about the selected line. For code, this - will have a summary of the instruction.
    7. + will include a summary of the instruction's behavior.
@@ -151,8 +151,9 @@

Moving Around

  • Address 1017 and label L1017 were highlighted. When you select a line with an operand that targets an in-file address, the target address is highlighted.
    • -
  • An entry appeared in the References window. This tells you that the - only reference to L1002 is a branch from address $100B.
    • +
  • An entry appeared in the References window. This tells you + that the only reference to L1002 is a branch from address $1009. The + branch operand on line $1009 was also highlighted.
  • The Info window filled with a bunch of text that describes the line format and some details about the LDA instruction.
    • @@ -224,9 +225,10 @@

    Moving Around

    on opcodes or lines in the side windows, the locations are added to a navigation history. The arrows let you move forward and backward through it.

    -

    The "Nav Backward" feature is bound to the 4th button found on some - mice (usually found on the side, activated with the thumb). This can - be used to navigate quickly through a project using only the mouse.

    +

    The "Nav Backward" feature is usually bound to the 4th button found + on some mice (generally found on the side, activated with the thumb). + This can be used to navigate quickly through a project using only the + mouse.

    diff --git a/docs/sgtutorial/odds-ends.html b/docs/sgtutorial/odds-ends.html index f015a46..b15957b 100644 --- a/docs/sgtutorial/odds-ends.html +++ b/docs/sgtutorial/odds-ends.html @@ -141,17 +141,11 @@

    Odds & Ends

    Continuing on, the code at $2086 touches a few consecutive locations that have auto-generated labels.

    -
    - - -
    -
    - t2-2081-stuff -

    Edit the label on line $2081, setting it to STUFF. - Notice how the references to $2081 through $2084 have changed from - auto-generated labels to references to STUFF.

    + The operand label on line $2086 also changed. But what if we want + to treat these as a single four-byte item?

    +
    @@ -160,25 +154,34 @@

    Odds & Ends

    t2-seek-nearby
    -

    For some projects this may be undesirable. Use - Edit > Project Properties, then in the - Analysis Parameters box un-check +

    Use Edit > Project Properties, then in the + Analysis Parameters box check Seek nearby targets, and click OK.

    +
    + t2-2081-stuff +
    +
    -

    You'll notice that the references to $2081 and later have switched - back to auto labels. If you scroll up, you'll see that the references to +

    You'll notice that the references to $2081 and later are now + also references to STUFF. The nearby-target behavior + is often useful, because it lets you avoid explicitly labeling every + part of a multi-byte data item. References to the byte before + a string or array are automatically resolved to LABEL-1. + You can use Edit > Undo to turn it back off: + changes to project properties are added to the undo/redo buffer + just like any other change to the project.

    +

    (This feature used to be enabled by default, but is now + disabled for new projects because it can be more distracting than + helpful for some types of code.) + +

    If you scroll up, you'll see that the references to PTR1+1 and PTR2+1 were not affected, because local variables use explicit widths rather - than the "nearby" logic.

    -

    The nearby-target behavior is generally desirable, because it lets you - avoid explicitly labeling every part of a multi-byte data item. For now, - use Edit > Undo to switch it back on. - (Changes to project properties are added to the undo/redo buffer - just like any other change to the project.)

    + than the "nearby target" logic.

    @@ -187,10 +190,11 @@

    Odds & Ends

    t2-2092
    -

    The code at $2092 looks a bit strange. LDX, then a - BIT with a weird symbol, then another LDX. If - you look at the "bytes" column, you'll notice that the three-byte - BIT instruction has only one byte on its line.

    +

    While we're here, the code at $2092 looks a bit strange. + LDX, then a BIT with a weird symbol, then + another LDX. If you look at the "Bytes" column, you'll + notice that the three-byte BIT instruction has only one + byte on its line.

    @@ -199,9 +203,9 @@

    Odds & Ends

    The trick here is that the LDX #$01 is embedded inside the BIT instruction. When the code runs through here, X is set to $00, then the BIT instruction sets some flags, then the - STA runs. Several lines down there's a BNE - to $2095, which is in the middle of the BIT instruction. - It loads X with $01, then also continues to the STA.

    + following STA runs. Several lines down at $20A4 there's a + BNE to $2095, which is in the middle of the BIT + instruction. It loads X with $01, then also continues to the STA.

    Embedded instructions are unusual but not unheard-of. (This trick is used extensively in Microsoft BASICs, such as Applesoft.) When you see the extra symbol in the opcode field, you need to look closely at what's going diff --git a/docs/sgtutorial/suggestions.html b/docs/sgtutorial/suggestions.html index d42efe8..8aef512 100644 --- a/docs/sgtutorial/suggestions.html +++ b/docs/sgtutorial/suggestions.html @@ -93,12 +93,14 @@

    A Few Suggestions

    disassembled code before, this is the time to play with different conventions, like whether to use MixedCase or underscore_separated or SCREAMING_CAPS for labels. -
  • Use the program thoroughly. Understand all of what it does.
    • +
  • Use the program you're disassembling thoroughly before you start. + Understand all of what it does.
  • Start with easily identifiable subroutines. If a chunk of code is reading from the keyboard, you can make reasonable guesses about the purpose of the code that interacts with it. The start of the program is often the hardest place to begin, because it - usually just initializes a bunch of stuff you haven't identified.
    • + usually just initializes a bunch of stuff you haven't identified. + Work bottom-up.
  • Expect to figure out little pieces. Use what you learn from these to figure out other little pieces. It's a jigsaw puzzle, not a book.
  • Don't get discouraged if there's a ton of code that you can't make @@ -114,8 +116,8 @@

    A Few Suggestions

    entry points, format tables of addresses, and find JSRs that are followed by inline data. Use an extension script to handle the inlines so you won't keep tripping over them. If parts of the program -are relocated to a different address, set the appropriate address -overrides.

    +are relocated to a different address, create the appropriate address +regions.

    Code start tags are rarely needed, and code end tags are almost never needed. You shouldn't have to spend a lot of time manually tagging things. If a piece of code isn't being found, it's usually diff --git a/docs/sgtutorial/using-sourcegen.html b/docs/sgtutorial/using-sourcegen.html index 65623c6..c1db342 100644 --- a/docs/sgtutorial/using-sourcegen.html +++ b/docs/sgtutorial/using-sourcegen.html @@ -176,11 +176,12 @@

    Using SourceGen

    -

    The first thing you should do after creating a new project is save it. +

    You will be asked to save the project file. Some features create or load files from the directory where the project - file lives, so we want to establish that. Use File > Save - or Ctrl+S to save it, with the default name - (Tutorial1.dis65), in the directory where the data file lives.

    + file lives, so we want to establish where that is. It also enables the + optional auto-save feature. Save it with the default name + (Tutorial1.dis65), in the directory where the tutorial data + file lives.

    (It's okay to create the project in the installation directory. You don't need to work off of a copy of the data file; SourceGen doesn't modify it, so you don't have to worry about trashing the example data.)

    @@ -210,7 +211,8 @@

    Using SourceGen

    (The settings that affect projects are accessed through a different screen, via Edit > Project Properties.)

    -

    For now, you can leave everything set to default values.

    +

    For now, click Cancel to leave everything set to + default values.

    diff --git a/docs/sgtutorial/visualizations.html b/docs/sgtutorial/visualizations.html index 65e005a..45d9e86 100644 --- a/docs/sgtutorial/visualizations.html +++ b/docs/sgtutorial/visualizations.html @@ -96,14 +96,14 @@

    Visualizations

    Start a new project with the Generic 6502 profile, and from the SourceGen Tutorial directory select "Tutorial5". We'll need to load an extension script from - the project directory, so immediately save the project, using the + the project directory, so go ahead and save the project, using the default name ("Tutorial5.dis65").

    Normally a project will give you some sort of hint as to the data format, e.g. the graphics might be a platform-specific sprite. For non-standard formats you can glean dimensions from the drawing code. For the purposes of this tutorial we're just using a simple monochrome bitmap - format, with 8 pixels per byte, and we'll know that our images are for + format, with 8 pixels per byte, and we know that our images are for a Tic-Tac-Toe game. The 'X' and the 'O' are 8x8, the game board is 40x40. The bitmaps are sprites with transparency, so pixels are either solid or transparent.

    @@ -147,7 +147,7 @@

    Visualizations

    (that way, if you change the address, your visualizations don't break). This is followed by the bitmap's width in bytes, and the bitmap's height. Because we have 8 pixels per byte, we're currently showing an 8x1 image. - We'll come back to row stride.

    + (We'll come back to look at row stride in a bit.)