diff --git a/SourceGen/Examples/Tutorial/InlineL1String.cs b/SourceGen/Examples/Tutorial/InlineL1String.cs index 508aa90..1e5e7f5 100644 --- a/SourceGen/Examples/Tutorial/InlineL1String.cs +++ b/SourceGen/Examples/Tutorial/InlineL1String.cs @@ -33,6 +33,11 @@ namespace ExtensionScriptSample { AppDomain.CurrentDomain.Id + "): prepare()"); } + public void Unprepare() { + mAppRef = null; + mFileData = null; + } + public void UpdateSymbolList(List plSyms) { // reset this every time, in case they remove the symbol mInlineL1StringAddr = -1; diff --git a/SourceGen/Examples/Tutorial/InlineNullTermString.cs b/SourceGen/Examples/Tutorial/InlineNullTermString.cs index d568331..3c6d3c2 100644 --- a/SourceGen/Examples/Tutorial/InlineNullTermString.cs +++ b/SourceGen/Examples/Tutorial/InlineNullTermString.cs @@ -33,6 +33,11 @@ namespace ExtensionScriptSample { AppDomain.CurrentDomain.Id + "): prepare()"); } + public void Unprepare() { + mAppRef = null; + mFileData = null; + } + public void UpdateSymbolList(List plSyms) { mNullStringAddrs.Clear(); diff --git a/SourceGen/RuntimeData/Help/tutorials.html b/SourceGen/RuntimeData/Help/tutorials.html index 7811bfa..b528c43 100644 --- a/SourceGen/RuntimeData/Help/tutorials.html +++ b/SourceGen/RuntimeData/Help/tutorials.html @@ -44,7 +44,7 @@ provides some details on whichever platform is selected. The bottom window will have some information about the data file, once we choose one.

Scroll down in the list, and select "Generic 6502". Then click "Select File...", navigate to the SourceGen installation directory, -open the Examples folder, then open the "Tutorial" folder. Select the +open the "Examples" folder, then open the "Tutorial" folder. Select the file named "Tutorial1", and click "Open".

The filename now appears in the bottom window, along with an indication of the file's size.

@@ -105,8 +105,8 @@ References window. Note the selection jumps to L1002. You can immediately jump to any reference.

At the top of the Symbols window on the right side of the screen is a row of buttons. Make sure "Auto" and "Addr" are selected. You should see -three labels in the window (L1002, L1014, L1017). Double-click on L1014. The -selection jumps to the appropriate line.

+three labels in the window (L1002, L1014, L1017). Double-click on "L1014" +in the Symbols list. The selection jumps to the appropriate line.

Select Navigate > Find. Type "hello", and hit Enter. The selection will move to address $100E, which is a string that says "hello!". You can use @@ -114,7 +114,7 @@ Navigate > Find Next to try to find the next occurrence (there isn't one). Y can search for any text that appears in the rightmost columns (label, opcode, operand, comment).

Select Navigate > Go To. You can enter a label, address, or file offset. -Enter "100b" to set the selection to $100B.

+Enter "100b" to set the selection to the line at address $100B.

Near the top-left of the SourceGen window is a set of toolbar icons. Click the curly left-pointing arrow, and watch the selection move. Click @@ -152,8 +152,8 @@ 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 editors are -only enabled when a single instance of a relevant item is selected, so +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.

@@ -194,8 +194,8 @@ so you'll be forgiven if you reduce the offset column width to zero.)

On the line at address $2000, select Actions > Edit Label, or double-click on the label "L2000". Change the label to "MAIN", and hit Enter. The label changes on that line, and on the two lines that refer -to address $2000. (If you're not sure what refers to address $2000, select -that line and check the References window.)

+to address $2000. (If you're not sure which lines refer to address $2000, +select line $2000 and look at the References window.)

On that same line, select Actions > Edit Comment. Type a short comment, and hit Enter. Your comment appears in the "comment" column.

@@ -280,16 +280,18 @@ unique. You can change these attributes when you edit the label. Up near the top of the file, at address $1002, double-click on the label ("L1002"). Change the label to "LOOP" and click the "non-unique local" button. Click OK.

-

The label at line $1002 should now be "@LOOP". By default, '@' is -used to indicate non-unique labels, though you can change it to a -different character in the application settings.

+

The label at line $1002 (and the operand on line $100B) should now +be "@LOOP". By default, '@' is used to indicate non-unique labels, +though you can change it to a different character in the application +settings.

At address $2019, double-click to edit the label ("L2019"). If -you type "MAIN" or "IS_OK" you'll get an error, but if you type "@LOOP" -it will be accepted. Note the "non-unique local" button is selected -automatically if you start a label with '@'. Click OK.

-

You now have two lines with the same label, separated by global -labels. The assembly source generator may "promote" them to globals or -rename them if your chosen assembler requires it.

+you type "MAIN" or "IS_OK" with Global selected you'll get an error, +but if you type "@LOOP" it will be accepted. Note the "non-unique local" +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. The assembly source +generator may "promote" them to globals or rename them if your chosen +assembler requires it.

Editing Data Operands

@@ -497,7 +499,8 @@ cycles but might take more. That's because conditional branches take an extra cycle if the branch is taken. The BNE on line $2061" shows 3 cycles, because we know that the branch is always taken. (If you want to see why, look at the value of the 'Z' flag in the "flags" column. Lower-case 'z' -means the zero-flag is clear.)

+means the zero-flag is clear. You can see it got set on the +ORA #$80 line.)

The cycle-count comments are included in assembled output as well. If you add an end-of-line comment, it appears after the cycle count.

Hit Ctrl+S to save your project. Make that a habit.

@@ -591,7 +594,7 @@ This particular program interfaces with Applesoft BASIC, so we can make it a bit more meaningful by loading an additional platform symbol file. Select Edit > Project Properties, then the Symbol Files tab. Click Add Symbol Files from Runtime. The file browser starts in -the RuntimeData directory. Open the Apple folder, then select +the RuntimeData directory. Open the "Apple" folder, then select Applesoft.sym65, and click "Open". Click "OK" to close the project properties window.

The STA instructions now reference BAS_AMPERV, @@ -667,12 +670,12 @@ SourceGen asks for confirmation, click Discard & Continue.

This tutorial covers one specific feature.

Some repetitive formatting tasks can be handled with automatic scripts. -This is especially useful for inline data, which confuses the disassembler -because code is expected.

+This is especially useful for inline data, which can confuse the code +analyzer.

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 "Generic 6502", and in the SourceGen -Tutorial directory select "Tutorial4".

+Examples/Tutorial directory select "Tutorial4".

We'll need to load scripts from the project directory, so we have to save the project. File > Save, use the default name ("Tutorial4.dis65").

@@ -683,8 +686,8 @@ can handle that, so use Edit > Project Properties, select the Extension Scripts tab, and click "Add Scripts from Project". The file browser opens in the project directory. Select the file "InlineL1String.cs", click Open, then OK.

-

Nothing happened. If you look at the script (and you know some C#), -you'll see that it's looking for a JSR to a function called +

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 called "PrintInlineL1String". So let's give it one.

Double-click the JSR operand ("L1026"), click "Create Label", and enter "PrintInlineL1String". Remember that labels are case-sensitive; @@ -707,7 +710,9 @@ on line $1019 ("L1028"), setting the label to "PrintInlineNullStringTwo".

"Print Inline" locations would be actual print functions, not just RTS 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.

+strings and clean up the disassembly automatically. The reason for +allowing wildcard names is that some functions may have multiple +entry points or chain through different locations.

Extension scripts can make your life much easier, but they do require some programming experience. See the @@ -745,7 +750,7 @@ select the Extension Scripts tab, and click "Add Scripts from Project". Double-click on "VisTutorial5.cs", then click "OK".

The address of the three bitmaps are helpfully identified by the -load instructions at the top of the file. Select the first one at +load instructions at the top of the file. Select the list at address $100A, then Actions > Create/Edit Visualization Set. In the window that opens, click "New Bitmap".

We're going to ignore most of what's going on and just focus on the @@ -780,7 +785,8 @@ as 8 bytes per row. This is known as the "stride" or "pitch" of the row. To tell the visualizer to skip the last 3 bytes on each row, set the "Row stride (bytes)" field to 8. Now we have a proper Tic-Tac-Toe grid. Note that it fills the preview window just as the 'X' and 'O' did, even -though it's 5x as large. The preview window scales everything up.

+though it's 5x as large. The preview window scales everything up. Hit +"OK" twice to create the visualization.

Let's format the bitmap data. Select line $101A, then shift-click the last line in the file ($1159). Actions > Edit Operand. Select "densely-packed bytes", and click "OK". This is perhaps a little too @@ -807,9 +813,11 @@ the animation speed. You can add the grid to the animation set, but the preview scales the bitmaps up to full size, so it may not look the way you expect.

Hit "OK" to save the animation, then "OK" to update the visualization set. -The code list now shows two entries, one of which has a blue triangle -superimposed. You can have as many bitmaps an animations on a line -as you want.

+The code list now shows two entries in the line: the first is the 'X' +bitmap, the second is the animation, which is shown as the initial frame +with a blue triangle superimposed. (If you go back into the editor and +reverse the order of the frames, the list will show the 'O' instead.) +You can have as many bitmaps and animations on a line as you want.

If you have a lot of bitmaps it can be helpful to give them meaningful names, so that they're easy to identify and sort together in the list. The "tag" field at the top of the editor windows lets you give things @@ -846,7 +854,7 @@ don't be afraid to play around.

If you want to work on something large over a long period, save your progress by putting the .dis65 project into a source code control system like git. Project files are stored in a text format that, while not meant -to be human-readable, will yield reasonable diffs.

+to be human-readable, should yield reasonable diffs.