diff --git a/docs/footer-incl.html b/docs/footer-incl.html new file mode 100644 index 0000000..8d8dc1f --- /dev/null +++ b/docs/footer-incl.html @@ -0,0 +1,9 @@ +
+

Copyright 2021 faddenSoft

+ diff --git a/docs/index.html b/docs/index.html index 40f9e05..4a6a410 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,145 +1,171 @@ - - - - - - - - - 6502bench Tools - - - -
-

6502bench SourceGen

- -

6502bench is a code development "workbench" for the 65xx family -of processors, including the 6502, 65C02, and 65802/65816. It currently -features one tool, the SourceGen disassembler.

- -

Quick links:

- - -
- -

SourceGen is an industrial-strength disassembler for 6502, -65C02, and 65816 programs. It runs on Windows 7 or later. Key features include:

- - -

-Main Window Screenshot -Gen/Asm Dialog Screenshot -Gen/Asm Dialog Screenshot -

- -

Features in Detail:

- - -

SourceGen is written in C# .NET, using the (free to download) Visual -Studio Community 2019 IDE as the primary development environment. -The user interface uses the Windows Presentation Foundation (WPF) API. -The full source code for the project is available on GitHub, licensed under Apache 2.0.

- -
- - - - + + + + + + + + + + + 6502bench Tools + + + + +
+ + + +
+ +
+ + + +
+ +
+ +

6502bench is a code development "workbench" for the 65xx family +of processors, including the 6502, 65C02, and 65802/65816. It currently +features one tool, the SourceGen disassembler.

+ +

SourceGen is an industrial-strength disassembler for 6502, +65C02, and 65816 programs. It runs on Windows 7 or later.

+ +

Quick links:

+ + +

Key features include:

+ + +

+ Main Window Screenshot + Gen/Asm Dialog Screenshot + Gen/Asm Dialog Screenshot +

+ +

Features in Detail:

+ + +
+ +

6502bench is written in C# .NET, using the (free to download) Visual +Studio Community 2019 IDE as the primary development environment. +The user interface uses the Windows Presentation Foundation (WPF) API. +6502bench is an open-source project, licensed under Apache 2.0. +The full source code is available on +GitHub.

+ +
+ + + + + diff --git a/docs/main.css b/docs/main.css index 871b318..2f9a4bd 100644 --- a/docs/main.css +++ b/docs/main.css @@ -1,18 +1,311 @@ -/* +/* +Responsive web design layout for 6502bench site. + +All pages define elements with these IDs: + masthead (site logo / title) + topnav (top items, menu button) (consider "sticky" navbar?); contents + reduce to home/menu for XS + sidenav (large: float on left; medium/small: "collapsed sidepanel" or toggle) + main (80% for large, 100% for medium/small) + footer (with prev/next) + +"main" section of tutorial pages: + 2-column grid for large/medium, 1-column grid for small/XS +*/ + +* { + box-sizing: border-box; +} + +/* * Overall look and feel. - */ + */ +html { + /* always show scrollbar, so centered masthead doesn't shift */ + overflow-y: scroll; +} body { - font-family: Arial, Helvetica, sans-serif; + font-family: "Segoe UI", Arial, Helvetica, sans-serif; padding: 0px; margin: 0px; -} -#content { - /* top right bottom left */ - margin: 20px 10px 10px 10px; - /*position: relative;*/ + background-color: #ffffff; } +/*code { + font-size: 125%; +}*/ + +/* + * Display of keyboard shortcuts in the element. + */ +kbd.key { + border-radius: 5px; + padding: 0px 2px 0; + border: 1px solid black; + background-color: #f7f7f7; +} + +/* + * ========================================================================== + * Extra small devices (phones) - DEFAULT: + * - Main content grid is single-column. + * - For top nav, show only the first link and menu icon. + */ + +/* + * Masthead. + */ +#masthead { + /* background-color: #202020; + color: #ffffff; */ + background-color: #e0e0e0; + color: #101010; + position: relative; +} +#masthead .masthead-title { + text-align: center; + font-size: 4em; + font-weight: bolder; + padding: 10px; + margin: 0px; +} +#masthead .masthead-titleZZZ { + /* place text */ + position: absolute; + top: 50%; + left: 50%; + transform: translate(-50%, -50%); + + bottom: 0; + background: rgb(0, 0, 0); /* fallback color */ + background: rgba(0, 0, 0, 0.5); /* black, 50% opacity */ + color: #f1f1f1; + width: 100%; + padding: 20px; +} +#masthead img { + /* fill space with image */ + background-position: center; + background-repeat: no-repeat; + background-size: cover; + background-attachment: fixed; + width: 100%; + height: auto; +} + +/* + * Top navigation bar. Home on the left, primary links next to it, + * sidenav menu icon on the right for smaller screens. + */ +#topnav { + border-style: none; + border-width: thin; + padding: 10px; + background-color: #5f5f5f; +} + +/* inline-block seems to help keep the text and icon consistent when + expanding and collapsing (vs. inline) */ +#topnav a {display:inline-block;} +#topnav a:not(:first-child) {display:none;} +#topnav a.icon { + float: right; + display: block; +} +#topnav button { + float: right; + display: block; + color: #ffffff; + background-color: #5f5f5f; + text-decoration: none; + padding: .2em 1em .2em 1em; +} + +#topnav nav { + text-align: left; + padding: 0px; +} +#topnav nav a { + color: #ffffff; + background-color: #5f5f5f; + padding: .2em 1em .2em 1em; + text-decoration: none; +} +#topnav nav a:hover { + border-style: none; + color: #ffffff; + background-color: #000000; +} + +#topnav nav a.active { + color: #8bc349; +} + +/* + * Side navigation bar. Always visible on large screens, pops out when + * the hamburger icon is clicked on smaller screens. + */ +#sidenav { + display: none; + width: 180px; + margin: 0 8px 0 0; + padding: 5px; +} +#sidenav ul { + list-style-type: none; + padding: 0; + margin: 0; +} +#sidenav li { + padding: 0 0px 1px 0; /* top right bottom left */ +} +#sidenav ul ul li { + padding: 0 0 1px 10px; /* top right bottom left */ +} +#sidenav a { + color: #ffffff; + display: block; + background-color: #5f5f5f; + padding: 5px 5px 5px 8px; /* top right bottom left */ + text-decoration: none; +} +#sidenav a:hover { + color: #ffffff; + background-color: #000000; +} +#sidenav .active a { + color: #8bc349; +} + +/* + * Main content area. + */ +#main { + margin: 8px; + display: block; +} + +/* + * Grid layout for tutorial. Each grid has two items, forming a {text,image} + * pair, either of which may be absent. The document is a series of grids. + * + * We can have images come before or after the related text by adjusting + * the grid-row values. + */ +.grid-container { + display: grid; + grid-template-rows: auto auto; + /*margin-bottom: 4px;*/ +} + +.grid-item-text { + /* background-color: #e0e0ff; */ + grid-row: 1; +} +.grid-item-text p { + /* items in grids don't collapse margins */ + /* cf. https://stackoverflow.com/q/18963421/294248 */ + margin-block-start: 0; +} + +.grid-item-image { + /* background-color: #ffe0e0; */ + grid-row: 2; + justify-self: center; /* center narrow images, mostly for 1-col layout */ +} +.grid-item-image img { + width: 100%; + height: auto; + /* don't expand image beyond original size */ + max-height: max-content; + max-width: max-content; + border: 1px solid #e0e0e0; + margin-top: 5px; /* align closer to top of text */ +} + +/* + * Previous/next buttons. + */ +#prevnext { + /* clear: both; */ + margin: 8px; + margin-top: 30px; + text-align: center; +} + +#prevnext a { + text-decoration: none; + display: inline-block; + padding: 8px 16px; + border-radius: 5px; + background-color: #f1f1f1; + color: black; +} +#prevnext a:hover { + background-color: #ddd; +} + +/* + * Footer. + */ #footer { - /* top right bottom left */ - margin: 20px 10px 10px 10px; - /*position: relative;*/ + /* top margin gets eaten up by sidenav on short pages */ + clear: both; + margin: 8px; +} + +/* + * ========================================================================== + * Small devices (portrait tablets, large phones): + * - For top nav, want to show all links in the top nav bar, as well + * as the menu icon. + */ +@media only screen and (min-width: 600px) { + #topnav a:not(:first-child) {display:inline-block;} +} + +/* + * ========================================================================== + * Medium devices (landscape tablets): + * - Switch to two-column layout, text on the left, image on the right. + */ +@media only screen and (min-width: 768px) { + .grid-container { + grid-template-columns: 50% 50%; + grid-template-rows: initial; + grid-column-gap: 8px; + } + .grid-item-text { + grid-row: 1; + grid-column: 1; + } + .grid-item-image { + grid-row: 1; + grid-column: 2; + } +} + +/* + * ========================================================================== + * Large devices (laptops/desktops): + * - Show sidenav on the side. + * - Don't show menu icon in the topnav bar. + */ + @media only screen and (min-width: 992px) { + #sidenav { + display: block; + float: left; + } + + #main { + /* make room for sidenav */ + margin-left: 188px; + } + #main.no-sidenav { + /* ...or not */ + margin-left: 8px; + } + + #topnav a.icon { + display: none; + } } diff --git a/docs/masthead-incl.html b/docs/masthead-incl.html new file mode 100644 index 0000000..bc5e119 --- /dev/null +++ b/docs/masthead-incl.html @@ -0,0 +1,4 @@ + +
+ 6502bench +
diff --git a/docs/sgtutorial/about-disasm.html b/docs/sgtutorial/about-disasm.html new file mode 100644 index 0000000..0634d37 --- /dev/null +++ b/docs/sgtutorial/about-disasm.html @@ -0,0 +1,161 @@ + + + + + + + + + + + About Disassembly - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

About Disassembly

+ +
+
+

Well-written assembly-language source code has meaningful + comments and labels, so that humans can read and understand it. + For example:

+
+          .org  $2000
+          sec                         ;set carry
+          ror   A                     ;shift into high bit
+          bmi   CopyData              ;branch always
+
+          .asciiz "first string"
+          .asciiz "another string"
+          .asciiz "string the third"
+          .asciiz "last string"
+
+CopyData  lda   #<addrs               ;get pointer into
+          sta   ptr                   ; address table
+          lda   #>addrs
+          sta   ptr+1
+
+ +

Computers operate at a much lower level, so a piece of software + called an assembler is used to convert the source code to + object code that the CPU can execute. + Object code looks more like this:

+
+38 6a 30 39 66 69 72 73 74 20 73 74 72 69 6e 67
+00 61 6e 6f 74 68 65 72 20 73 74 72 69 6e 67 00
+73 74 72 69 6e 67 20 74 68 65 20 74 68 69 72 64
+00 6c 61 73 74 20 73 74 72 69 6e 67 00 a9 63 85
+02 a9 20 85 03
+
+ +

This arrangement works perfectly well until somebody needs to + modify the software and nobody can find the original sources. + Disassembly is the act of taking a raw hex + dump and converting it to source code.

+
+
+ +
+
+ t0-bad-disasm +
+
+

Disassembling a blob of data can be tricky. A simple + disassembler can format instructions, but can't generally tell + the difference between instructions and data. Many 6502 programs + intermix code and data freely, so simply dumping everything as + an instruction stream can result in sections with nonsensical output.

+
+
+ +
+
+

One way to separate code from data is to try to execute all + possible data paths. There are a number of reasons why it's difficult + or impossible to do this perfectly, but you can get pretty good + results by identifying execution entry points and just walking through + the code. When a conditional branch is encountered, both paths are + traversed. When all code has been traced, every byte that hasn't + been visited is either + data used by the program, or dead space not used by anything.

+ +

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. + 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 + certain instructions is determined by the values of the processor + status flags.)

+ +

Once the instructions and data are separated and formatted + nicely, it's still up to a human to figure out what it all means. + Comments and meaningful labels are needed to make sense of it. + These should be added to the disassembly listing.

+
+
+ +
+
+ t0-sourcegen +
+
+

SourceGen performs the instruction tracing, and makes it easy + to format operands and add labels and comments. + When the disassembled code is ready, SourceGen can generate source code + for a variety of modern cross-assemblers, and produce HTML listings + with embedded graphic visualizations.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/address-tables.html b/docs/sgtutorial/address-tables.html new file mode 100644 index 0000000..72867fe --- /dev/null +++ b/docs/sgtutorial/address-tables.html @@ -0,0 +1,267 @@ + + + + + + + + + + + Address Tables - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Address Tables

+ +
+
+

Code often contains tables of addresses to code or data. + Formatting them one at a time can be tedious, so SourceGen + provides a faster way. For this tutorial we'll start by labeling + and tagging a single entry by hand, then do the rest in one shot.

+ +

Start a new project. Select the Apple //e platform, click + 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.

+
+
+ +
+
+ t3-initial +
+
+

Not a lot to see here -- just half a dozen lines of loads and stores, + then nothing but data. + This particular program interfaces with Applesoft BASIC, so we can make it + a bit more meaningful by loading an additional platform + symbol file.

+
+
+ +
+
+ t3-a2-props +
+
+

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 "Applesoft.sym65", + and click Open. Click OK to close + the project properties window.

+
+
+ +
+
+ t3-amperv +
+
+

The STA instructions now reference BAS_AMPERV, + which is noted as a code vector. We can see the code setting up a jump + (opcode $4C) to $1D70.

+
+
+ +
+
+ t3-1d70 +
+
+

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, + and change it from $2000 to $1D60. We can now see that $1D70 starts + right after this initial chunk of code.

+
+
+ +
+
+ t3-1d70-code +
+
+

Select the line with address $1D70, then + Actions > Tag Address As Code Start Point. + More code appears, but not much -- if you scroll down you'll see that most + of the file is still data.

+ +

The code at $1D70 searches through a table at + $1D88 for a match with the contents of the accumulator. If it finds a match, + it loads bytes from tables at $1DA6 and $1D97, pushes them on the stack, + and then JMPs away. This code is pushing a return address onto the stack. + When the code at BAS_CHRGET returns, it'll return to that + address. Because of a quirk of the 6502 architecture, the address pushed + must be the desired address minus one.

+
+
+ +
+
+ t3-1d97 +
+
+

The first byte in the first address table at $1D97 (which + has the auto-label L1D97) is $B4. + The first byte in the second table is $1D. So the first + address we want is $1DB4 + 1 = $1DB5.

+
+
+ +
+
+ t3-1d97-edit.png +
+
+

Select the line at $1DB5, and use + Actions > Tag Address As Code Start Point. + More code appears, but again it's only a few lines. Let's dress this one + up a bit. Set a label on the code at $1DB5 called "FUNC". + Then, at $1D97, edit the data item (double-click on "$B4"), + click Single bytes, then type "FUNC" + (note the text field gets focus immediately, and the radio button + automatically switches to symbolic reference when you start typing). + Click OK.

+
+
+ +
+
+ t3-1d97-post.png +
+
+

The operand at $1D97 should now say <FUNC-1. + Repeat the process at $1DA6, this time clicking the High + part radio button below the symbol entry text box, + to make the operand there say >FUNC. (If it says + <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 + 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.

+
+
+ +
+
+ t3-format-dialog +
+
+

Click on the line at address $1D97, then shift-click the line at + address $1DA9 (which should be .FILL 12,$1e). Select + Actions > Format Address Table.

+ +

Contrary to first impressions, this imposing dialog does not allow you + to launch objects into orbit. There are a variety of common ways to + structure an address table, all of which are handled here. You can + configure the various parameters and see the effects as you make + each change.

+
+
+ +
+
+ t3-format-cfg +
+
+

The message at the top should indicate that there are 30 bytes + selected. In Address Characteristics, click the + Parts are split across sub-tables checkbox and the + Adjusted for RTS/RTL checkbox. + As soon as you do, the first line of the Generated Addresses + list should show the symbol "FUNC". + The rest of the addresses will look like + "(+) T1DD0". The "(+)" means that a label was not found at + that location, so a new global label will be generated automatically.

+ +

Down near the bottom, check the + Tag targets as code start points checkbox. + Because we saw the table contents being pushed onto the stack for + RTS, we know that they're all code entry points.

+

Click OK.

+
+
+ +
+
+ t3-format-done +
+
+

The table of address bytes at $1D97 should now all be + references to symbols -- 15 low parts followed by 15 high parts. If you + scroll down, you should see nothing but instructions until you get to the + last dozen bytes at the end of the file. (If this isn't the case, use + Edit > Undo, then work through the steps again.)

+
+
+ +
+
+

The formatter did the same series of actions you went through earlier, + + but applied them to multiple locations in one shot. The next step in + the disassembly process would be to rename the "Tnnnn" labels to + something more meaninful.

+ +

We don't want to save this project, so select + File > Close. When SourceGen asks for confirmation, + click Discard & Continue.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/advanced-topics.html b/docs/sgtutorial/advanced-topics.html new file mode 100644 index 0000000..cc0e74b --- /dev/null +++ b/docs/sgtutorial/advanced-topics.html @@ -0,0 +1,80 @@ + + + + + + + + + + + Advanced Topics - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Advanced Topics

+ +

This section has tutorials for three subjects:

+ + + +

These features are not essential, but they can make your life easier. +All of the tutorials assume you are already familiar with SourceGen.

+ +

 

+ +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/digging-deeper.html b/docs/sgtutorial/digging-deeper.html new file mode 100644 index 0000000..a3a7e5e --- /dev/null +++ b/docs/sgtutorial/digging-deeper.html @@ -0,0 +1,167 @@ + + + + + + + + + + + Digging Deeper - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

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.

+

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

+
+
+ +
+
+ t2-tutorial-top +
+
+

Looking at the code list, the first thing you'll notice is that we + immediately ran into a + BRK, which is a pretty reliable sign that we're not in + a code section. This particular file begins with 00 20, which + could be a load address (e.g. some C64 binaries look like this). So let's start + with that assumption.

+
+
+ +
+
+

As discussed in the introductory material, SourceGen separates code + from data by tracing all possible execution paths from declared entry + points. The generic profiles mark the first byte of the file as an entry + point, but that's wrong here. We want to change the entry point to + be after the 16-bit load address, at offset +000002.

+
+
+ +
+
+ t2-1000-edit1 +
+
+

Click on the first line of code at address $1000, and select + Actions > Remove Analyzer Tags + (Ctrl+H Ctrl+R). + This removes the "code entry point" tag. + Unfortunately the $20 is still auto-detected as being part of a string + directive.

+
+
+ +
+
+ t2-1000-edit2 +
+
+

The string is making it hard to manipulate the next few bytes, + so let's fix that by selecting Edit > Toggle Data Scan + (Ctrl+D). This turns off the feature that + automatically generates string and .FILL directives, + so now each uncategorized byte is on its own line.

+
+
+ +
+
+ t2-1000-fmt-word +
+
+

You could select the first two lines and use + Actions > Edit Operand to format them as a 16-bit + little-endian hex value, but there's a shortcut: select the first + line with data (address $1000), then Actions > Format As Word + (Ctrl+W). + It automatically grabbed the following byte and combined them.

+
+
+ +
+
+ t2-1000-setcode +
+
+

Since we believe $2000 is the load address for everything that follows, + click on the line with address $1002, select + Actions > Set Address, and enter "2000". With that line + still selected, use Actions > Tag Address As Code Start Point + (Ctrl+H Ctrl+C) to + tell the analyzer to start looking for code there.

+
+
+ +
+
+ t2-1000-ready +
+
+

That looks better, but the branch destination ($203D) is off the bottom of the + screen (unless you have a really tall screen or small fonts) because of + all the intervening data. Use Edit > Toggle Data Scan + (Ctrl+D) + to turn the string-finder back on. Now it's easier to read.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/editing-data.html b/docs/sgtutorial/editing-data.html new file mode 100644 index 0000000..5f04905 --- /dev/null +++ b/docs/sgtutorial/editing-data.html @@ -0,0 +1,204 @@ + + + + + + + + + + + Editing Data - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Editing Data

+ +
+
+ t1-data-stringblob +
+
+

There's some string and numeric data down at the bottom of the file. The + final string appears to be multiple strings stuck together. (You may need + to increase the width of the Operand column to see the whole thing.) Notice + that the opcode for the very last line is '+', which means the operand + is a continuation of the previous line. Long data items can span multiple + lines, split every 64 characters (including delimiters), but they are + still single items: selecting any part selects the whole.

+
+
+ +
+
+ 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 + items, or various things in between. For now, select Single bytes, + and then on the right, select ASCII (low or high) character. + Click OK.

+
+
+ +
+
+ t1-data-edited-1 +
+
+

Each character is now on its own line. The selection still spans the + same set of addresses.

+
+
+ +
+
+ t1-data-editdlg-2 +
+
+

Select address $203D on its own, then Actions > Edit Label. Set the + label to "STR1". Move up a bit and select address $2030, then scroll to + the bottom and shift-click address $2070. Select + Actions > Edit Operand. + At the top it should now say, "65 bytes selected in 2 groups". + There are two groups because the presence of a label split the data into + two separate regions. From the Character encoding pop-up down + in the "String" section, make sure Low or High ASCII encoding + is selected, then select the Mixed character and non-character + string type and click OK.

+
+
+ +
+
+ t1-data-edited-2 +
+
+

We now have two .STR lines, one for "string zero ", + and one with the "STR1" label and the rest of the string data. + This is okay, + but it's not really what we want. The code at $200B appears to be loading + a 16-bit address from data at $2025, so we want to use that if we can.

+

Select Edit > Undo three times. You should be back to the + state where there's a single .STR line at the bottom of + the file, split across two lines with a '+'.

+
+
+ +
+
+ t1-data-string-bytes +
+
+

Select the line at $2026. This is currently formatted as a string, + but that appears to be incorrect, so let's format it as individual bytes + instead. There's an easy way to do that: use + Actions > Toggle Single-Byte Format + (or hit Ctrl+B).

+
+
+ +
+
+

The data starting at $2025 appears to be 16-bit little-endian + addresses that point into the table of strings, so let's format + them appropriately.

+ +
+
+ +
+
+ t1-data-editdlg-3 +
+
+

Select the line at $2025, then shift-click the line at $202E. Right-click + and select Edit Operand. If you selected the correct set of bytes, + the top line in the dialog should now say, "10 bytes selected". + Because 10 is a multiple of two, the 16-bit formats are enabled. It's not a multiple + of 3 or 4, so the 24-bit and 32-bit options are not enabled. Click the + 16-bit words, little-endian radio button, then over to the right, + click the Address radio button. Click OK.

+
+
+ +
+
+ t1-data-edited-3 +
+
+

We just told SourceGen that those 10 bytes are actually five 16-bit numeric + references. SourceGen determined that the addresses are contained in the + file, and generated labels for each of them. Labels only work if they're + on their own line, so the long string was automatically split into five + separate .STR statements.

+
+
+ +
+
+

Note we didn't explicitly format the string data. We formatted + the addresses at $2025, which placed labels at the start of the strings, + but the strings themselves were automatically detected and formatted + by SourceGen. By default, SourceGen looks for ASCII strings, but this + can be changed in the project properties. You can even disable the + string auto-detection entirely if you want.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/extension-scripts.html b/docs/sgtutorial/extension-scripts.html new file mode 100644 index 0000000..a5c6942 --- /dev/null +++ b/docs/sgtutorial/extension-scripts.html @@ -0,0 +1,191 @@ + + + + + + + + + + + Extension Scripts - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Extension Scripts

+ +
+
+

Some repetitive formatting tasks can be handled with automatic scripts. + 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 the Generic 6502 profile, and + in the SourceGen 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").

+
+
+ +
+
+ t4-add-inlinel1 +
+
+

Take a look at the disassembly listing. The file starts with a + JSR followed by a string that begins with a small number. + This appears to be a string with a leading length byte. We want to load + a script that 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.

+
+
+ +
+
+ t4-inlinel1-src +
+
+

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 opcode on line $1000 + to jump to address $1026. The only thing there is an RTS. + It's supposed to be a routine that prints a string with a leading length + byte, but for the sake of keeping the example code short it's just a + place-holder. Use the curly toolbar arrow + (or Alt+LeftArrow) to jump back to $1026.

+
+
+ +
+
+ t4-inlinel1-edit +
+
+

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

+
+
+ +
+
+ t4-inlinel1-done +
+
+

If all went well, address $1003 + should now be an L1 string "How long?", and address $100D + should be another JSR.

+
+
+ +
+
+

The next JSR appears to be followed by a null-terminated string, so + we'll need something that handles that.

+
+
+ +
+
+ t4-inlinenull-src +
+
+

Go back into Project Properties + and add the script called "InlineNullTermString.cs" from the project directory. + This script is slightly different, in that it handles any JSR to a label + that starts with PrintInlineNullString. So let's give it a couple of + those.

+
+
+ +
+
+ t4-inlinenull-done +
+
+

Double-click the operand on line $100D ("L1027"), + click Create Label, + and set the label to "PrintInlineNullStringOne". + Hit OK twice. That formatted the first one and got us + to the next JSR. Repeat the process on line $1019 + ("L1028"), setting the label to "PrintInlineNullStringTwo".

+
+
+ +
+
+

The entire project is now nicely formatted. In a real project the + "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. 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 SourceGen manual for more details.

+
+
+ +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/generating-code.html b/docs/sgtutorial/generating-code.html new file mode 100644 index 0000000..3230fb6 --- /dev/null +++ b/docs/sgtutorial/generating-code.html @@ -0,0 +1,131 @@ + + + + + + + + + + + Generating Code - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Generating Code

+ +
+
+ t1-asmgen-dlg +
+
+

You can generate assembly source code from the disassembled data. + Select File > Assemble (or hit Ctrl+Shift+A) + to open the source generation and assembly dialog.

+
+
+ +
+
+ t1-asmgen-preview +
+
+

Pick your favorite assembler from the drop list at the top right, + then click Generate. An assembly source file will be generated in the + directory where your project files lives, named after a combination of the + project name and the assembler name. A preview of the assembled code + appears in the top window. (It's called a "preview" because it has line numbers + added and is cut off after a certain limit.)

+
+
+ +
+
+ t1-asmgen-asmout +
+
+

If you have a cross-assembler installed and configured, you can run + it by clicking Run Assembler. The output from the assembler will appear + in the lower window, along with an indication of whether the assembled + file matches the original. (Unless there are bugs in SourceGen or the assembler, + it should always match exactly.)

+ +

Click Close to close the window.

+
+
+ +
+
+

If you want to output source code for display on a web site or + posting in an online forum, you have a couple of options. The easiest + way to do this is to select the lines and use Edit > Copy + to copy them to the system clipboard, and then simply paste it elsewhere. + The format will match what's on the screen, and will not be tailored to + any specific assembler. The set of columns included in the copy can be + configured in the application settings editor, e.g. you can limit it to + just the columns typically found in source code.

+
+
+ +
+
+ t1-export-dlg +
+
+

To export some or all of the project as text or HTML, use + File > Export (Ctrl+Shift+E). + This is an easy way to share a disassembly listing with people who + don't have access to SourceGen. The feature is primarily useful in + situations where you want to show the disassembly data (Address + and Bytes), or want to embed visualizations (explained later).

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/images/t0-bad-disasm.png b/docs/sgtutorial/images/t0-bad-disasm.png new file mode 100644 index 0000000..7ac3bbe Binary files /dev/null and b/docs/sgtutorial/images/t0-bad-disasm.png differ diff --git a/docs/sgtutorial/images/t0-sourcegen.png b/docs/sgtutorial/images/t0-sourcegen.png new file mode 100644 index 0000000..f9eef5d Binary files /dev/null and b/docs/sgtutorial/images/t0-sourcegen.png differ diff --git a/docs/sgtutorial/images/t1-2003-done.png b/docs/sgtutorial/images/t1-2003-done.png new file mode 100644 index 0000000..6e4dcbe Binary files /dev/null and b/docs/sgtutorial/images/t1-2003-done.png differ diff --git a/docs/sgtutorial/images/t1-addr-chg-1017.png b/docs/sgtutorial/images/t1-addr-chg-1017.png new file mode 100644 index 0000000..9fa1f42 Binary files /dev/null and b/docs/sgtutorial/images/t1-addr-chg-1017.png differ diff --git a/docs/sgtutorial/images/t1-all-columns.png b/docs/sgtutorial/images/t1-all-columns.png new file mode 100644 index 0000000..d34cdd7 Binary files /dev/null and b/docs/sgtutorial/images/t1-all-columns.png differ diff --git a/docs/sgtutorial/images/t1-asmgen-asmout.png b/docs/sgtutorial/images/t1-asmgen-asmout.png new file mode 100644 index 0000000..836bf88 Binary files /dev/null and b/docs/sgtutorial/images/t1-asmgen-asmout.png differ diff --git a/docs/sgtutorial/images/t1-asmgen-dlg.png b/docs/sgtutorial/images/t1-asmgen-dlg.png new file mode 100644 index 0000000..eed6271 Binary files /dev/null and b/docs/sgtutorial/images/t1-asmgen-dlg.png differ diff --git a/docs/sgtutorial/images/t1-asmgen-preview.png b/docs/sgtutorial/images/t1-asmgen-preview.png new file mode 100644 index 0000000..df3e40f Binary files /dev/null and b/docs/sgtutorial/images/t1-asmgen-preview.png differ diff --git a/docs/sgtutorial/images/t1-click-1002.png b/docs/sgtutorial/images/t1-click-1002.png new file mode 100644 index 0000000..b8b24d5 Binary files /dev/null and b/docs/sgtutorial/images/t1-click-1002.png differ diff --git a/docs/sgtutorial/images/t1-click-1017.png b/docs/sgtutorial/images/t1-click-1017.png new file mode 100644 index 0000000..d47093d Binary files /dev/null and b/docs/sgtutorial/images/t1-click-1017.png differ diff --git a/docs/sgtutorial/images/t1-data-editdlg-1.png b/docs/sgtutorial/images/t1-data-editdlg-1.png new file mode 100644 index 0000000..9b4103e Binary files /dev/null and b/docs/sgtutorial/images/t1-data-editdlg-1.png differ diff --git a/docs/sgtutorial/images/t1-data-editdlg-2.png b/docs/sgtutorial/images/t1-data-editdlg-2.png new file mode 100644 index 0000000..1b65280 Binary files /dev/null and b/docs/sgtutorial/images/t1-data-editdlg-2.png differ diff --git a/docs/sgtutorial/images/t1-data-editdlg-3.png b/docs/sgtutorial/images/t1-data-editdlg-3.png new file mode 100644 index 0000000..91f9645 Binary files /dev/null and b/docs/sgtutorial/images/t1-data-editdlg-3.png differ diff --git a/docs/sgtutorial/images/t1-data-edited-1.png b/docs/sgtutorial/images/t1-data-edited-1.png new file mode 100644 index 0000000..a40e610 Binary files /dev/null and b/docs/sgtutorial/images/t1-data-edited-1.png differ diff --git a/docs/sgtutorial/images/t1-data-edited-2.png b/docs/sgtutorial/images/t1-data-edited-2.png new file mode 100644 index 0000000..1191fec Binary files /dev/null and b/docs/sgtutorial/images/t1-data-edited-2.png differ diff --git a/docs/sgtutorial/images/t1-data-edited-3.png b/docs/sgtutorial/images/t1-data-edited-3.png new file mode 100644 index 0000000..976044f Binary files /dev/null and b/docs/sgtutorial/images/t1-data-edited-3.png differ diff --git a/docs/sgtutorial/images/t1-data-string-bytes.png b/docs/sgtutorial/images/t1-data-string-bytes.png new file mode 100644 index 0000000..69ef962 Binary files /dev/null and b/docs/sgtutorial/images/t1-data-string-bytes.png differ diff --git a/docs/sgtutorial/images/t1-data-stringblob.png b/docs/sgtutorial/images/t1-data-stringblob.png new file mode 100644 index 0000000..79b3983 Binary files /dev/null and b/docs/sgtutorial/images/t1-data-stringblob.png differ diff --git a/docs/sgtutorial/images/t1-edit-2000-done.png b/docs/sgtutorial/images/t1-edit-2000-done.png new file mode 100644 index 0000000..d1c03e6 Binary files /dev/null and b/docs/sgtutorial/images/t1-edit-2000-done.png differ diff --git a/docs/sgtutorial/images/t1-edit-label.png b/docs/sgtutorial/images/t1-edit-label.png new file mode 100644 index 0000000..7f1ecbd Binary files /dev/null and b/docs/sgtutorial/images/t1-edit-label.png differ diff --git a/docs/sgtutorial/images/t1-edit-long-comment.png b/docs/sgtutorial/images/t1-edit-long-comment.png new file mode 100644 index 0000000..f4b81e2 Binary files /dev/null and b/docs/sgtutorial/images/t1-edit-long-comment.png differ diff --git a/docs/sgtutorial/images/t1-edit-note.png b/docs/sgtutorial/images/t1-edit-note.png new file mode 100644 index 0000000..27e054e Binary files /dev/null and b/docs/sgtutorial/images/t1-edit-note.png differ diff --git a/docs/sgtutorial/images/t1-edit-sym-2000.png b/docs/sgtutorial/images/t1-edit-sym-2000.png new file mode 100644 index 0000000..25283a8 Binary files /dev/null and b/docs/sgtutorial/images/t1-edit-sym-2000.png differ diff --git a/docs/sgtutorial/images/t1-export-dlg.png b/docs/sgtutorial/images/t1-export-dlg.png new file mode 100644 index 0000000..15baa74 Binary files /dev/null and b/docs/sgtutorial/images/t1-export-dlg.png differ diff --git a/docs/sgtutorial/images/t1-fresh-install.png b/docs/sgtutorial/images/t1-fresh-install.png new file mode 100644 index 0000000..56cca6c Binary files /dev/null and b/docs/sgtutorial/images/t1-fresh-install.png differ diff --git a/docs/sgtutorial/images/t1-fullscreen.png b/docs/sgtutorial/images/t1-fullscreen.png new file mode 100644 index 0000000..65d2616 Binary files /dev/null and b/docs/sgtutorial/images/t1-fullscreen.png differ diff --git a/docs/sgtutorial/images/t1-goto-box.png b/docs/sgtutorial/images/t1-goto-box.png new file mode 100644 index 0000000..f48f17e Binary files /dev/null and b/docs/sgtutorial/images/t1-goto-box.png differ diff --git a/docs/sgtutorial/images/t1-local-loop-edit.png b/docs/sgtutorial/images/t1-local-loop-edit.png new file mode 100644 index 0000000..6b5cf49 Binary files /dev/null and b/docs/sgtutorial/images/t1-local-loop-edit.png differ diff --git a/docs/sgtutorial/images/t1-local-loop1.png b/docs/sgtutorial/images/t1-local-loop1.png new file mode 100644 index 0000000..db86bf8 Binary files /dev/null and b/docs/sgtutorial/images/t1-local-loop1.png differ diff --git a/docs/sgtutorial/images/t1-local-loop2.png b/docs/sgtutorial/images/t1-local-loop2.png new file mode 100644 index 0000000..5dba59c Binary files /dev/null and b/docs/sgtutorial/images/t1-local-loop2.png differ diff --git a/docs/sgtutorial/images/t1-multi-disab.png b/docs/sgtutorial/images/t1-multi-disab.png new file mode 100644 index 0000000..95cbfc4 Binary files /dev/null and b/docs/sgtutorial/images/t1-multi-disab.png differ diff --git a/docs/sgtutorial/images/t1-new-project.png b/docs/sgtutorial/images/t1-new-project.png new file mode 100644 index 0000000..ca9ed55 Binary files /dev/null and b/docs/sgtutorial/images/t1-new-project.png differ diff --git a/docs/sgtutorial/images/t1-new-tutorial1.png b/docs/sgtutorial/images/t1-new-tutorial1.png new file mode 100644 index 0000000..79776bd Binary files /dev/null and b/docs/sgtutorial/images/t1-new-tutorial1.png differ diff --git a/docs/sgtutorial/images/t1-pre-sym-2000.png b/docs/sgtutorial/images/t1-pre-sym-2000.png new file mode 100644 index 0000000..464d90e Binary files /dev/null and b/docs/sgtutorial/images/t1-pre-sym-2000.png differ diff --git a/docs/sgtutorial/images/t1-set-addr-1017.png b/docs/sgtutorial/images/t1-set-addr-1017.png new file mode 100644 index 0000000..b625d99 Binary files /dev/null and b/docs/sgtutorial/images/t1-set-addr-1017.png differ diff --git a/docs/sgtutorial/images/t1-settings.png b/docs/sgtutorial/images/t1-settings.png new file mode 100644 index 0000000..9fba40b Binary files /dev/null and b/docs/sgtutorial/images/t1-settings.png differ diff --git a/docs/sgtutorial/images/t1-simple-instr-edit.png b/docs/sgtutorial/images/t1-simple-instr-edit.png new file mode 100644 index 0000000..1d850f9 Binary files /dev/null and b/docs/sgtutorial/images/t1-simple-instr-edit.png differ diff --git a/docs/sgtutorial/images/t1-sym-2005-adjust.png b/docs/sgtutorial/images/t1-sym-2005-adjust.png new file mode 100644 index 0000000..3ac633e Binary files /dev/null and b/docs/sgtutorial/images/t1-sym-2005-adjust.png differ diff --git a/docs/sgtutorial/images/t1-sym-2005-before.png b/docs/sgtutorial/images/t1-sym-2005-before.png new file mode 100644 index 0000000..07103e8 Binary files /dev/null and b/docs/sgtutorial/images/t1-sym-2005-before.png differ diff --git a/docs/sgtutorial/images/t1-sym-2005-edit.png b/docs/sgtutorial/images/t1-sym-2005-edit.png new file mode 100644 index 0000000..d3f89c2 Binary files /dev/null and b/docs/sgtutorial/images/t1-sym-2005-edit.png differ diff --git a/docs/sgtutorial/images/t1-sym-2005-explicit.png b/docs/sgtutorial/images/t1-sym-2005-explicit.png new file mode 100644 index 0000000..b4932d6 Binary files /dev/null and b/docs/sgtutorial/images/t1-sym-2005-explicit.png differ diff --git a/docs/sgtutorial/images/t1-sym-2005-labeled.png b/docs/sgtutorial/images/t1-sym-2005-labeled.png new file mode 100644 index 0000000..63f8982 Binary files /dev/null and b/docs/sgtutorial/images/t1-sym-2005-labeled.png differ diff --git a/docs/sgtutorial/images/t1-sym-2005-msg-window.png b/docs/sgtutorial/images/t1-sym-2005-msg-window.png new file mode 100644 index 0000000..7ac41da Binary files /dev/null and b/docs/sgtutorial/images/t1-sym-2005-msg-window.png differ diff --git a/docs/sgtutorial/images/t1-sym-2005-nosym.png b/docs/sgtutorial/images/t1-sym-2005-nosym.png new file mode 100644 index 0000000..bed4518 Binary files /dev/null and b/docs/sgtutorial/images/t1-sym-2005-nosym.png differ diff --git a/docs/sgtutorial/images/t1-symbol-filters.png b/docs/sgtutorial/images/t1-symbol-filters.png new file mode 100644 index 0000000..70da856 Binary files /dev/null and b/docs/sgtutorial/images/t1-symbol-filters.png differ diff --git a/docs/sgtutorial/images/t1-toolbar.png b/docs/sgtutorial/images/t1-toolbar.png new file mode 100644 index 0000000..e44d97a Binary files /dev/null and b/docs/sgtutorial/images/t1-toolbar.png differ diff --git a/docs/sgtutorial/images/t2-1000-edit1.png b/docs/sgtutorial/images/t2-1000-edit1.png new file mode 100644 index 0000000..00316a4 Binary files /dev/null and b/docs/sgtutorial/images/t2-1000-edit1.png differ diff --git a/docs/sgtutorial/images/t2-1000-edit2.png b/docs/sgtutorial/images/t2-1000-edit2.png new file mode 100644 index 0000000..6f6a0a3 Binary files /dev/null and b/docs/sgtutorial/images/t2-1000-edit2.png differ diff --git a/docs/sgtutorial/images/t2-1000-fmt-word.png b/docs/sgtutorial/images/t2-1000-fmt-word.png new file mode 100644 index 0000000..c9a8daf Binary files /dev/null and b/docs/sgtutorial/images/t2-1000-fmt-word.png differ diff --git a/docs/sgtutorial/images/t2-1000-ready.png b/docs/sgtutorial/images/t2-1000-ready.png new file mode 100644 index 0000000..bb9eb77 Binary files /dev/null and b/docs/sgtutorial/images/t2-1000-ready.png differ diff --git a/docs/sgtutorial/images/t2-1000-setcode.png b/docs/sgtutorial/images/t2-1000-setcode.png new file mode 100644 index 0000000..561f56b Binary files /dev/null and b/docs/sgtutorial/images/t2-1000-setcode.png differ diff --git a/docs/sgtutorial/images/t2-203d-after-edit2.png b/docs/sgtutorial/images/t2-203d-after-edit2.png new file mode 100644 index 0000000..f66d16a Binary files /dev/null and b/docs/sgtutorial/images/t2-203d-after-edit2.png differ diff --git a/docs/sgtutorial/images/t2-203d-edit1.png b/docs/sgtutorial/images/t2-203d-edit1.png new file mode 100644 index 0000000..9ecb231 Binary files /dev/null and b/docs/sgtutorial/images/t2-203d-edit1.png differ diff --git a/docs/sgtutorial/images/t2-203d-start.png b/docs/sgtutorial/images/t2-203d-start.png new file mode 100644 index 0000000..0391a53 Binary files /dev/null and b/docs/sgtutorial/images/t2-203d-start.png differ diff --git a/docs/sgtutorial/images/t2-2048.png b/docs/sgtutorial/images/t2-2048.png new file mode 100644 index 0000000..53f47e7 Binary files /dev/null and b/docs/sgtutorial/images/t2-2048.png differ diff --git a/docs/sgtutorial/images/t2-204e-lv.png b/docs/sgtutorial/images/t2-204e-lv.png new file mode 100644 index 0000000..971c9ad Binary files /dev/null and b/docs/sgtutorial/images/t2-204e-lv.png differ diff --git a/docs/sgtutorial/images/t2-2055.png b/docs/sgtutorial/images/t2-2055.png new file mode 100644 index 0000000..0f1a5f1 Binary files /dev/null and b/docs/sgtutorial/images/t2-2055.png differ diff --git a/docs/sgtutorial/images/t2-206b.png b/docs/sgtutorial/images/t2-206b.png new file mode 100644 index 0000000..ba54e41 Binary files /dev/null and b/docs/sgtutorial/images/t2-206b.png differ diff --git a/docs/sgtutorial/images/t2-2078-done.png b/docs/sgtutorial/images/t2-2078-done.png new file mode 100644 index 0000000..19c13fd Binary files /dev/null and b/docs/sgtutorial/images/t2-2078-done.png differ diff --git a/docs/sgtutorial/images/t2-2078.png b/docs/sgtutorial/images/t2-2078.png new file mode 100644 index 0000000..97bf608 Binary files /dev/null and b/docs/sgtutorial/images/t2-2078.png differ diff --git a/docs/sgtutorial/images/t2-2081-stuff.png b/docs/sgtutorial/images/t2-2081-stuff.png new file mode 100644 index 0000000..b0e7152 Binary files /dev/null and b/docs/sgtutorial/images/t2-2081-stuff.png differ diff --git a/docs/sgtutorial/images/t2-2086.png b/docs/sgtutorial/images/t2-2086.png new file mode 100644 index 0000000..34ca9da Binary files /dev/null and b/docs/sgtutorial/images/t2-2086.png differ diff --git a/docs/sgtutorial/images/t2-2092.png b/docs/sgtutorial/images/t2-2092.png new file mode 100644 index 0000000..dd8da18 Binary files /dev/null and b/docs/sgtutorial/images/t2-2092.png differ diff --git a/docs/sgtutorial/images/t2-20a7.png b/docs/sgtutorial/images/t2-20a7.png new file mode 100644 index 0000000..f58a28b Binary files /dev/null and b/docs/sgtutorial/images/t2-20a7.png differ diff --git a/docs/sgtutorial/images/t2-20ab-1.png b/docs/sgtutorial/images/t2-20ab-1.png new file mode 100644 index 0000000..524c50a Binary files /dev/null and b/docs/sgtutorial/images/t2-20ab-1.png differ diff --git a/docs/sgtutorial/images/t2-20ab-2.png b/docs/sgtutorial/images/t2-20ab-2.png new file mode 100644 index 0000000..f36a90f Binary files /dev/null and b/docs/sgtutorial/images/t2-20ab-2.png differ diff --git a/docs/sgtutorial/images/t2-after-ptr-entry.png b/docs/sgtutorial/images/t2-after-ptr-entry.png new file mode 100644 index 0000000..e1924a8 Binary files /dev/null and b/docs/sgtutorial/images/t2-after-ptr-entry.png differ diff --git a/docs/sgtutorial/images/t2-create-ptr-entry.png b/docs/sgtutorial/images/t2-create-ptr-entry.png new file mode 100644 index 0000000..4779326 Binary files /dev/null and b/docs/sgtutorial/images/t2-create-ptr-entry.png differ diff --git a/docs/sgtutorial/images/t2-enable-counts.png b/docs/sgtutorial/images/t2-enable-counts.png new file mode 100644 index 0000000..939742f Binary files /dev/null and b/docs/sgtutorial/images/t2-enable-counts.png differ diff --git a/docs/sgtutorial/images/t2-fmt-xdata-done.png b/docs/sgtutorial/images/t2-fmt-xdata-done.png new file mode 100644 index 0000000..4d9b4b2 Binary files /dev/null and b/docs/sgtutorial/images/t2-fmt-xdata-done.png differ diff --git a/docs/sgtutorial/images/t2-fmt-xdata.png b/docs/sgtutorial/images/t2-fmt-xdata.png new file mode 100644 index 0000000..7ee740a Binary files /dev/null and b/docs/sgtutorial/images/t2-fmt-xdata.png differ diff --git a/docs/sgtutorial/images/t2-inline-after.png b/docs/sgtutorial/images/t2-inline-after.png new file mode 100644 index 0000000..2090013 Binary files /dev/null and b/docs/sgtutorial/images/t2-inline-after.png differ diff --git a/docs/sgtutorial/images/t2-inline-tag.png b/docs/sgtutorial/images/t2-inline-tag.png new file mode 100644 index 0000000..fc03a45 Binary files /dev/null and b/docs/sgtutorial/images/t2-inline-tag.png differ diff --git a/docs/sgtutorial/images/t2-override-status.png b/docs/sgtutorial/images/t2-override-status.png new file mode 100644 index 0000000..5fc784a Binary files /dev/null and b/docs/sgtutorial/images/t2-override-status.png differ diff --git a/docs/sgtutorial/images/t2-seek-nearby.png b/docs/sgtutorial/images/t2-seek-nearby.png new file mode 100644 index 0000000..dafd6e7 Binary files /dev/null and b/docs/sgtutorial/images/t2-seek-nearby.png differ diff --git a/docs/sgtutorial/images/t2-show-cycle-counts.png b/docs/sgtutorial/images/t2-show-cycle-counts.png new file mode 100644 index 0000000..fb0943e Binary files /dev/null and b/docs/sgtutorial/images/t2-show-cycle-counts.png differ diff --git a/docs/sgtutorial/images/t2-str-null-term-bad.png b/docs/sgtutorial/images/t2-str-null-term-bad.png new file mode 100644 index 0000000..fdca86a Binary files /dev/null and b/docs/sgtutorial/images/t2-str-null-term-bad.png differ diff --git a/docs/sgtutorial/images/t2-str-null-term-good.png b/docs/sgtutorial/images/t2-str-null-term-good.png new file mode 100644 index 0000000..20800b1 Binary files /dev/null and b/docs/sgtutorial/images/t2-str-null-term-good.png differ diff --git a/docs/sgtutorial/images/t2-str-null-term-start.png b/docs/sgtutorial/images/t2-str-null-term-start.png new file mode 100644 index 0000000..8b09fb0 Binary files /dev/null and b/docs/sgtutorial/images/t2-str-null-term-start.png differ diff --git a/docs/sgtutorial/images/t2-tutorial-top.png b/docs/sgtutorial/images/t2-tutorial-top.png new file mode 100644 index 0000000..20134d6 Binary files /dev/null and b/docs/sgtutorial/images/t2-tutorial-top.png differ diff --git a/docs/sgtutorial/images/t3-1d70-code.png b/docs/sgtutorial/images/t3-1d70-code.png new file mode 100644 index 0000000..c676f02 Binary files /dev/null and b/docs/sgtutorial/images/t3-1d70-code.png differ diff --git a/docs/sgtutorial/images/t3-1d70.png b/docs/sgtutorial/images/t3-1d70.png new file mode 100644 index 0000000..790eeb9 Binary files /dev/null and b/docs/sgtutorial/images/t3-1d70.png differ diff --git a/docs/sgtutorial/images/t3-1d97-edit.png b/docs/sgtutorial/images/t3-1d97-edit.png new file mode 100644 index 0000000..89ccaef Binary files /dev/null and b/docs/sgtutorial/images/t3-1d97-edit.png differ diff --git a/docs/sgtutorial/images/t3-1d97-post.png b/docs/sgtutorial/images/t3-1d97-post.png new file mode 100644 index 0000000..7544b1c Binary files /dev/null and b/docs/sgtutorial/images/t3-1d97-post.png differ diff --git a/docs/sgtutorial/images/t3-1d97.png b/docs/sgtutorial/images/t3-1d97.png new file mode 100644 index 0000000..e474198 Binary files /dev/null and b/docs/sgtutorial/images/t3-1d97.png differ diff --git a/docs/sgtutorial/images/t3-a2-props.png b/docs/sgtutorial/images/t3-a2-props.png new file mode 100644 index 0000000..a75e5c3 Binary files /dev/null and b/docs/sgtutorial/images/t3-a2-props.png differ diff --git a/docs/sgtutorial/images/t3-amperv.png b/docs/sgtutorial/images/t3-amperv.png new file mode 100644 index 0000000..5cfc860 Binary files /dev/null and b/docs/sgtutorial/images/t3-amperv.png differ diff --git a/docs/sgtutorial/images/t3-format-cfg.png b/docs/sgtutorial/images/t3-format-cfg.png new file mode 100644 index 0000000..37abc69 Binary files /dev/null and b/docs/sgtutorial/images/t3-format-cfg.png differ diff --git a/docs/sgtutorial/images/t3-format-dialog.png b/docs/sgtutorial/images/t3-format-dialog.png new file mode 100644 index 0000000..a4d8eb6 Binary files /dev/null and b/docs/sgtutorial/images/t3-format-dialog.png differ diff --git a/docs/sgtutorial/images/t3-format-done.png b/docs/sgtutorial/images/t3-format-done.png new file mode 100644 index 0000000..cce9e99 Binary files /dev/null and b/docs/sgtutorial/images/t3-format-done.png differ diff --git a/docs/sgtutorial/images/t3-initial.png b/docs/sgtutorial/images/t3-initial.png new file mode 100644 index 0000000..2ed9768 Binary files /dev/null and b/docs/sgtutorial/images/t3-initial.png differ diff --git a/docs/sgtutorial/images/t4-add-inlinel1.png b/docs/sgtutorial/images/t4-add-inlinel1.png new file mode 100644 index 0000000..06078f2 Binary files /dev/null and b/docs/sgtutorial/images/t4-add-inlinel1.png differ diff --git a/docs/sgtutorial/images/t4-inlinel1-done.png b/docs/sgtutorial/images/t4-inlinel1-done.png new file mode 100644 index 0000000..c426bc0 Binary files /dev/null and b/docs/sgtutorial/images/t4-inlinel1-done.png differ diff --git a/docs/sgtutorial/images/t4-inlinel1-edit.png b/docs/sgtutorial/images/t4-inlinel1-edit.png new file mode 100644 index 0000000..4cd3c80 Binary files /dev/null and b/docs/sgtutorial/images/t4-inlinel1-edit.png differ diff --git a/docs/sgtutorial/images/t4-inlinel1-src.png b/docs/sgtutorial/images/t4-inlinel1-src.png new file mode 100644 index 0000000..85686d3 Binary files /dev/null and b/docs/sgtutorial/images/t4-inlinel1-src.png differ diff --git a/docs/sgtutorial/images/t4-inlinenull-done.png b/docs/sgtutorial/images/t4-inlinenull-done.png new file mode 100644 index 0000000..25ec1fb Binary files /dev/null and b/docs/sgtutorial/images/t4-inlinenull-done.png differ diff --git a/docs/sgtutorial/images/t4-inlinenull-src.png b/docs/sgtutorial/images/t4-inlinenull-src.png new file mode 100644 index 0000000..3b00ad2 Binary files /dev/null and b/docs/sgtutorial/images/t4-inlinenull-src.png differ diff --git a/docs/sgtutorial/images/t5-101a-good.png b/docs/sgtutorial/images/t5-101a-good.png new file mode 100644 index 0000000..f41d590 Binary files /dev/null and b/docs/sgtutorial/images/t5-101a-good.png differ diff --git a/docs/sgtutorial/images/t5-101a-mess.png b/docs/sgtutorial/images/t5-101a-mess.png new file mode 100644 index 0000000..6269dda Binary files /dev/null and b/docs/sgtutorial/images/t5-101a-mess.png differ diff --git a/docs/sgtutorial/images/t5-add-vis.png b/docs/sgtutorial/images/t5-add-vis.png new file mode 100644 index 0000000..f5ec291 Binary files /dev/null and b/docs/sgtutorial/images/t5-add-vis.png differ diff --git a/docs/sgtutorial/images/t5-addvis1.png b/docs/sgtutorial/images/t5-addvis1.png new file mode 100644 index 0000000..6f2d549 Binary files /dev/null and b/docs/sgtutorial/images/t5-addvis1.png differ diff --git a/docs/sgtutorial/images/t5-addvis2.png b/docs/sgtutorial/images/t5-addvis2.png new file mode 100644 index 0000000..d819a92 Binary files /dev/null and b/docs/sgtutorial/images/t5-addvis2.png differ diff --git a/docs/sgtutorial/images/t5-bitmap-anim-editor.png b/docs/sgtutorial/images/t5-bitmap-anim-editor.png new file mode 100644 index 0000000..d81c83e Binary files /dev/null and b/docs/sgtutorial/images/t5-bitmap-anim-editor.png differ diff --git a/docs/sgtutorial/images/t5-fmt-dense.png b/docs/sgtutorial/images/t5-fmt-dense.png new file mode 100644 index 0000000..9d76fa9 Binary files /dev/null and b/docs/sgtutorial/images/t5-fmt-dense.png differ diff --git a/docs/sgtutorial/images/t5-list-xanim.png b/docs/sgtutorial/images/t5-list-xanim.png new file mode 100644 index 0000000..9f38bbd Binary files /dev/null and b/docs/sgtutorial/images/t5-list-xanim.png differ diff --git a/docs/sgtutorial/images/t5-new-vis.png b/docs/sgtutorial/images/t5-new-vis.png new file mode 100644 index 0000000..b9f54cd Binary files /dev/null and b/docs/sgtutorial/images/t5-new-vis.png differ diff --git a/docs/sgtutorial/images/t5-set-height-8.png b/docs/sgtutorial/images/t5-set-height-8.png new file mode 100644 index 0000000..f322197 Binary files /dev/null and b/docs/sgtutorial/images/t5-set-height-8.png differ diff --git a/docs/sgtutorial/images/t5-set-height-80.png b/docs/sgtutorial/images/t5-set-height-80.png new file mode 100644 index 0000000..25b32a2 Binary files /dev/null and b/docs/sgtutorial/images/t5-set-height-80.png differ diff --git a/docs/sgtutorial/images/t5-set-height-800.png b/docs/sgtutorial/images/t5-set-height-800.png new file mode 100644 index 0000000..a5503a5 Binary files /dev/null and b/docs/sgtutorial/images/t5-set-height-800.png differ diff --git a/docs/sgtutorial/images/t5-wireframe-sample.png b/docs/sgtutorial/images/t5-wireframe-sample.png new file mode 100644 index 0000000..63f9fe9 Binary files /dev/null and b/docs/sgtutorial/images/t5-wireframe-sample.png differ diff --git a/docs/sgtutorial/images/t5-xo-anim.png b/docs/sgtutorial/images/t5-xo-anim.png new file mode 100644 index 0000000..24dce66 Binary files /dev/null and b/docs/sgtutorial/images/t5-xo-anim.png differ diff --git a/docs/sgtutorial/index.html b/docs/sgtutorial/index.html new file mode 100644 index 0000000..989b2b4 --- /dev/null +++ b/docs/sgtutorial/index.html @@ -0,0 +1,86 @@ + + + + + + + + + + + SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

SourceGen Tutorial

+ +

This tutorial demonstrates many of the features of SourceGen. It will not +teach you 6502 assembly language, nor reveal any tricks for working with a +specific system.

+ +

The tutorial is divided into four broad sections:

+ + +

The tutorials work best if you follow along.

+ +

The 6502bench software distribution comes with a full manual. Launch +SourceGen and hit F1 to access it. + +

+ +
+ + + + + diff --git a/docs/sgtutorial/inline-data.html b/docs/sgtutorial/inline-data.html new file mode 100644 index 0000000..facadfb --- /dev/null +++ b/docs/sgtutorial/inline-data.html @@ -0,0 +1,136 @@ + + + + + + + + + + + Inline Data - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Inline Data

+ +
+
+ t2-206b +
+
+

Consider the code at address $206B. It's a JSR followed by some + ASCII text, then a $00 byte, and then what might be code.

+
+
+ +
+
+ t2-20ab-1 +
+ ... +
+ t2-20ab-2 +
+
+

Double-click on the JSR opcode + to jump to $20AB to see the function. It pulls the + call address off the stack, and uses it as a pointer. When it encounters + a zero byte, it breaks out of the loop, pushes the adjusted pointer + value back onto the stack, and returns.

+
+
+ +
+
+

This is an example of "inline data", where a function uses the return + address to get a pointer to data. The return address is adjusted to + point past the inline data before returning (technically, it points at + the very last byte of the inline data, because + RTS jumps to address + 1).

+
+
+ +
+
+ t2-inline-tag +
+
+

To format the data, we first need to tell SourceGen that there's data + in line with the code. Select the line at address $206E, then + shift-click the line at address $2077. Use + Actions > Tag Bytes As Inline Data + (Ctrl+HCtrl+I).

+
+
+ +
+
+ t2-inline-after +
+
+

The data turns to single-byte values, and we now see the code + continuing at address $2078. We can format the data as a string by + using Actions > Edit Operand, + setting the Character Encoding to Low or High ASCII, + and selecting null-terminated strings.

+
+
+ +
+
+

That's pretty straightforward, but this could quickly become tedious if + there were a lot of these. SourceGen allows you to define scripts to + automate common formatting tasks. This is covered in the "Extension + Scripts" tutorial.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/labels-symbols.html b/docs/sgtutorial/labels-symbols.html new file mode 100644 index 0000000..c424ead --- /dev/null +++ b/docs/sgtutorial/labels-symbols.html @@ -0,0 +1,352 @@ + + + + + + + + + + + Labels & Symbols - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Labels & Symbols

+ +
+
+

Suppose you want to call some code at address $1000. CPUs + fundamentally deal with numeric values, so the machine code to + call it would be JSR $1000. Humans tend to work better with + words, so associating a meaningful symbol with address $1000 + 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.

+ +

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.

+
+
+ +
+
+ t1-edit-label +
+
+

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 which lines refer to address $2000, + select line $2000 and check the list in the References window.)

+
+
+ +
+
+

Sometimes the target address falls outside the data file. Examples + include calls to ROM routines, use of zero-page storage, and access to + memory-mapped I/O locations. SourceGen classifies these as external, + and does not generate a symbol. In an assembler source file, symbols + for these would be expressed as equates (e.g. FOO = $8000), + usually at the top of the file or in an "include file". SourceGen + allows you to specify symbols for addresses and numeric constants within + the project ("project symbols"), or in a symbol file that can be + included in multiple projects ("platform symbols"). The SourceGen + distribution includes platform symbol files with ROM addresses for + several common systems.

+
+
+ +
+
+ t1-pre-sym-2000 +
+
+

For an example, consider the code at address $2000, which is + LDA $3000. We want to assign the symbol "INPUT" to address + $3000, but we can't do that by editing a label because it's not inside + the file bounds. We can open the project symbol editor from the project + properties editor, or we can use a shortcut.

+
+
+ +
+
+ t1-edit-sym-2000 +
+
+

With the line at $2000 selected, use Actions > Edit Operand, + or double-click on the value in the Operand column + ("$3000"). This opens the + Edit Instruction Operand dialog. In the bottom left, click + Create Project Symbol. Set the Label field to + "INPUT", and + click OK, then OK in the operand editor.

+
+
+ +
+
+ t1-edit-2000-done +
+
+

The instruction at $2000 now uses the symbol "INPUT" + as its operand. If you scroll to the top of the file, you will see a + ".EQ" line for the symbol.

+
+
+ +
+ +

Numeric v. Symbolic

+ +
+
+

When SourceGen sees a reference to an address, such as the operand of an + absolute JSR or LDA, it recognizes it + as a numeric reference. You can edit the instruction's operand + to use a symbol instead, changing to a symbolic reference. + Sometimes the way these are handled can be confusing.

+
+
+ +
+
+ t1-sym-2005-before +
+
+

Let's use the branch statement at $2005 to illustrate the difference. + It performs a branch to $2009, which was automatically assigned the + label "L2009".

+
+
+ +
+
+ t1-sym-2005-labeled +
+
+

Edit the label at $2009 (double-click on "L2009" there), + and change it to "IN_RANGE". Line $2005 changes to match. + This works because SourceGen + is auto-formatting line $2005's operand based on the label it finds when it + chases the numeric reference to $2009. + The Info window shows this as Format (auto): symbol "IN_RANGE".

+

Use Edit > Undo to revert the label change.

+
+
+ +
+
+ t1-sym-2005-edit +
+
+

Edit the instruction operand at $2005 (double-click on + "L2009" there). Change the format to Symbol, + and type "IN_RANGE" in the symbol box. + The preview shows BCC IN_RANGE (?), which hints at a + problem. Click OK.

+
+
+ +
+
+ t1-sym-2005-nosym +
+
+

Some things changed, but not the things we wanted. Line $2005 now + says BCC $2009, instead of BCC L2009, and the + label at $2009 has disappeared entirely. What went wrong?

+
+
+ +
+
+

The problem is that we edited the operand to use a symbol that isn't + defined anywhere. Because "IN_RANGE" isn't defined, the operand was + given the default format, and displayed as a hex value. + The numeric reference to $2009 was replaced by the symbol, and nothing + else refers to that address, + so SourceGen no longer had any reason to put an auto-generated label + on line $2009, which is why that disappeared.

+
+
+ +
+
+ t1-sym-2005-msg-window +
+
+

The missing symbol is called out in a message window that popped up + at the bottom of the code list window. The message window only appears + when there are messages to read. You can hide the window with the + Hide button, and make it re-appear with the button in the + bottom right of the main window that currently says 1 message.

+
+
+ +
+
+ t1-sym-2005-explicit +
+
+

We can resolve this issue by providing the desired symbol. As you + did earlier, edit the label on line $2009 (double-click in the label column) + and set it to "IN_RANGE". When you do, the operand on line $2005 + is updated appropriately. + If you select line $2005, the Info window shows the format as + Format: symbol "IN_RANGE", indicating that the symbol + was set explicitly rather than automatically.

+
+
+ +
+
+ t1-sym-2005-adjust +
+
+

Symbolic references always link to the symbol, even when the symbol + doesn't match the numeric reference. To see this, remove the label from + line $2009 by undoing that change with Edit > Undo, + so the symbol is again undefined. Now set the label on the following line, + $200A, to "IN_RANGE".

+
+
+ +
+
+

Line $2005 now says "BCC IN_RANGE-1". Earlier you set + the operand to be a symbolic reference to "IN_RANGE", but the symbol + doesn't quite match, so SourceGen automatically adjusted the operand by + one byte to point to the correct address. Generally speaking, SourceGen + will do its best to use the symbols that you tell it to, and will adjust the + symbolic references so that the code assembles correctly.

+
+
+ +
+
+

Edit the label on line $200A, and change it to "NIFTY". + Note how the reference on line $2005 also changed. This is an example + of a "refactoring rename": when you changed the label, SourceGen + automatically found everything that referred to it and updated it. + If you edit the operand on line $2005, you can confirm that the + symbol has changed.

+ +

(If you want to clean this up before continuing on to the next + section, put the label back on line $2009.)

+
+
+ +
+ +

Non-Unique Label

+ +
+
+

Most assemblers have a notion of "local" labels, which go out of + scope when a non-local (global) label is encountered. The actual + definition of "local" is assembler-specific, but SourceGen allows you + to create labels that serve the same purpose.

+
+
+ +
+
+ t1-local-loop-edit +
+
+

By default, newly-created labels have global scope and must be + 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" + radio button. + Click OK.

+
+
+ +
+
+ t1-local-loop1 +
+
+

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.

+
+
+ +
+
+ t1-local-loop2 +
+
+

At address $2019, double-click to edit the label ("L2019"). If + 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" radio + 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 + rename them to make them unique, depending on what your preferred assembler + allows.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/local-variables.html b/docs/sgtutorial/local-variables.html new file mode 100644 index 0000000..b583384 --- /dev/null +++ b/docs/sgtutorial/local-variables.html @@ -0,0 +1,270 @@ + + + + + + + + + + + Local Variables - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Local Variables

+ +
+
+ t2-203d-start +
+
+

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 + pointer to $2063, which is a data area inside the file. So let's make it + official.

+
+
+ +
+
+ t2-203d-edit1 +
+
+

Select the line at address $2063, and use + Actions > Edit Label to + give it the label "XDATA?". The question mark on the end is there to + remind us that we're not entirely sure what this is. Now edit the + operand on line $203D, and set it to the symbol "XDATA", + with the part "low". The question mark isn't really part of the label, + so you don't need to type it here.

+
+
+ +
+
+ t2-203d-after-edit2 +
+
+

Edit the operand on line $2041, + and set it to "XDATA" with the part "high". (The symbol text box + gets focus immediately, so you can start typing the symbol name as soon + as the dialog opens; you don't need to click around first.) If all + went well, the operands should now read LDA #<XDATA? + and LDA #>XDATA?.

+
+
+ +
+
+ t2-create-ptr-entry +
+
+

Let's give the pointer a name. Select line $203D, and use + Actions > Create Local Variable Table + to create an empty table. Click New Symbol on the right side. + Leave the Address button selected. Set the Label field to "PTR1", + the Value field to "$02", and the width to "2" (it's a 2-byte pointer). + Click "OK" to create the entry, and then + "OK" to update the table.

+
+
+ +
+
+ t2-after-ptr-entry +
+
+

There's now a .VAR statement + (similar to a .EQU) above line $203D, + and the stores to $02/$03 have changed to + "PTR1" and "PTR1+1".

+
+
+ +
+
+ t2-20a7 +
+
+

Double-click on the JSR opcode on line $2045 to jump 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.

+
+
+ +
+
+ t2-2048 +
+
+

The next bit of code masks the accumulator so it holds a value between + 0 and 3, then doubles it and uses it as an index into PTR1. + We know PTR1 points to XDATA, + which looks like it has some 16-bit addresses. The + values loaded are stored in two more zero-page locations, $04-05. + Let's make these a pointer as well.

+
+
+ +
+
+ t2-204e-lv +
+
+

Double-click the operand on line $204E ("$04"), + and click Create Local Variable. Set the Label + to "PTR2" and the width to 2. Click OK + to create the symbol, then OK + to close the operand editor, which should still be set to Default format -- + we didn't actually edit the operand, we just used the operand edit + dialog as a convenient way to create a local variable table entry. All + accesses to $04/$05 now use PTR2, and there's a new entry in the local + variable table we created earlier.

+
+
+ +
+
+ t2-2055 +
+
+

The next section of code, at $2055, copies bytes from PTR2 + to $0400, stopping when it hits a zero byte. + It looks like this is copying null-terminated strings.

+
+
+ +
+
+ t2-fmt-xdata +
+
+

This confirms our idea that XDATA holds 16-bit addresses, + so let's format it. Select lines $2063 to $2066, and + Actions > Edit Operand. + The editor window should say "8 bytes selected" at the top. + Click the 16-bit words, little-endian radio button, + and then in the Display As box, click Address. + Click OK.

+
+
+ +
+
+ t2-fmt-xdata-done +
+
+

The values at XDATA should now be four + .DD2 16-bit addresses. + If you scroll up, you'll see that the .ZSTR strings + near the top now have labels that match the operands in XDATA.

+
+
+ +
+
+

Now that we know what XDATA holds, let's rename it. + Change the label to STRADDR. The symbol parts in the + operands at $203D and $2041 update automatically.

+
+
+ +
+ +
+
+ t2-enable-counts +
+
+

Let's take a quick look at the cycle-count feature. Use + 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.)

+
+
+ +
+
+ t2-show-cycle-counts +
+
+

Every line with an instruction now has a cycle count on it. The cycle + counts are adjusted for everything SourceGen can figure out. For example, + the BEQ on line $205A shows "2+" cycles, meaning that + it takes at least two 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 and doesn't cross a page boundary.

+
+
+ +
+
+

(If you want to see why it's always taken, + look at the value of the 'Z' flag in the "flags" column, which indicates + the state of the flags before the instruction on that line is executed. + Lower-case 'z' means the zero-flag is clear (0), upper-case 'Z' means it's + set (1). The analyzer determined that the flag was clear for instructions + following the BEQ because we're on the branch-not-taken path. + 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.

+

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

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/moving-around.html b/docs/sgtutorial/moving-around.html new file mode 100644 index 0000000..ec9e165 --- /dev/null +++ b/docs/sgtutorial/moving-around.html @@ -0,0 +1,201 @@ + + + + + + + + + + + Moving Around - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Moving Around

+ +
+
+ t1-fullscreen +
+
+

The display is divided into five main areas:

+
    +
  1. Code listing. Disassembled code and data is shown here.
    2. +
  2. References. Shows a list of the places in the file that + reference the currently selected line.
    3. +
  3. Notes. A list of notes in the project. Useful as bookmarks.
    4. +
  4. Symbols. All known symbols. The buttons at the top allow you + to filter out symbol types that you're not interested in.
    5. +
  5. Info. Information about the selected line. For code, this + will have a summary of the instruction.
    6. +
+
+
+ +
+
+

The center code list window is divided into rows, one per line of disassembled + code or data. This is a standard "list view" control, so you can select a + row by left-clicking anywhere in it. Use Ctrl+click + to toggle the selection on individual lines, and + Shift+click to select a range of lines. You can move + the selection around with the up/down arrow keys and + PgUp/PgDn. Scroll the window + with the mouse wheel, or by dragging the scroll bar thumb.

+

Each row is divided into nine columns. You can adjust the column + widths by clicking and dragging the column dividers in the header

+
+
+ +
+
+ t1-all-columns +
+
+

The columns on the right side of the window are similar to + what you'd find in assembly source code: label, opcode, operand, + comment. The columns on the left are what you'd find in a disassembly + (file offset, address, raw bytes), plus some information about + processor status flags and line attributes that may or may not be + useful to you. If you find any of these distracting, collapse the + column. (Many of the screen shots captured here will omit the + "Attr" column for the sake of compactness.)

+
+
+ +
+
+ t1-click-1002 +
+
+

Click on the fourth line down, which has address 1002. The + line has a label, "L1002", and is performing an indexed load from + L1017. Both of these labels were automatically generated, and are + named for the address at which they appear. When you clicked on + the line, a few things happened:

+
    +
  • The line was highlighted in the system selection color (usually + blue).
    • +
  • 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.
    • +
  • The Info window filled with a bunch of text that describes the + line format and some details about the LDA instruction.
    • +
+

Click some other lines, such as address $100B and $1014. Note how the + highlights and contents of other windows change.

+
+
+ +
+
+ t1-click-1017 +
+
+

Click on L1002 again, then double-click on the opcode ("LDA"). The + selection jumps to L1017. When an operand references an in-file address, + double-clicking on the opcode will take you to it. (Double-clicking on + the operand itself opens a format editor; more on that later.)

+

With line L1017 selected, double-click on the line that appears in the + References window. Note the selection jumps to L1002. You can immediately + jump to any reference.

+
+
+ +
+
+ t1-symbol-filters +
+
+

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" + 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 + Navigate > Find Next to try to find the next occurrence (there isn't one). You + can search for any text that appears in the rightmost columns (label, opcode, + operand, comment).

+
+
+ +
+
+ t1-goto-box +
+
+

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

+
+
+ +
+
+ t1-toolbar +
+
+

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 + it again. Then click the curly right-arrow a couple of times. Whenever + you jump around in the file by using the Go To feature, or by double-clicking + 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.

+
+
+ +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/odds-ends.html b/docs/sgtutorial/odds-ends.html new file mode 100644 index 0000000..aba6528 --- /dev/null +++ b/docs/sgtutorial/odds-ends.html @@ -0,0 +1,197 @@ + + + + + + + + + + + Odds & Ends - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Odds & Ends

+ +
+
+

The rest of the code isn't really intended to do anything useful. It + just exists to illustrate some odd situations.

+
+
+ +
+
+ t2-2078 +
+
+

Look at the code starting at $2078. It ends with a BRK + at $2081, which as noted earlier is a bad sign. If you look two lines + above the BRK, you'll see that it's loading the accumulator + with zero, then doing a BNE, which should never be + taken (note the cycle count for the BNE is 2). + The trick is in the two lines before that, which use self-modifying code to + change the LDA immediate operand from $00 to $ff. + The BNE is actually a branch-always.

+
+
+ +
+
+ t2-override-status.png +
+
+

We can fix this by correcting the status flags. Select line $207F, + and then Actions > Override Status Flags. This lets us specify what + the flags should be before the instruction is executed. For each flag, + we can override the default behavior and specify that the flag is + clear (0), set (1), or indeterminate (could be 0 or 1). In this case, + we know that the self-modified code will be loading a non-zero value, so + in the "Z" column click on the button in the "Zero" row. + Click "OK".

+
+
+ +
+
+ t2-2078-done +
+
+

The BNE is now an always-taken branch, and the code + list rearranges itself appropriately (and the cycle count is now 3).

+
+
+ +
+
+ t2-2086 +
+
+

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.

+
+
+ +
+
+ t2-seek-nearby +
+
+

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

+
+
+ +
+
+

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 + 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.)

+
+
+ +
+
+ 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.

+
+
+ +
+
+

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.

+

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 + on.

+
+
+ +
+ +
+
+

This is the end of the basic tutorial (congratulations!). + The next sections explore some advanced topics.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/sidenav-incl.html b/docs/sgtutorial/sidenav-incl.html new file mode 100644 index 0000000..23691f7 --- /dev/null +++ b/docs/sgtutorial/sidenav-incl.html @@ -0,0 +1,26 @@ + + diff --git a/docs/sgtutorial/simple-edits.html b/docs/sgtutorial/simple-edits.html new file mode 100644 index 0000000..7650e08 --- /dev/null +++ b/docs/sgtutorial/simple-edits.html @@ -0,0 +1,204 @@ + + + + + + + + + + + Simple Edits - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Simple Edits

+ +
+
+

Click the very first line of the file, which is a comment that says + something like "6502bench SourceGen vX.Y.Z". There are three ways to + open the comment editor:

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

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.

+
+
+ +
+
+ t1-edit-long-comment +
+
+

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.

+ +
+
+ +
+
+ t1-edit-note +
+
+

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. +
  2. They don't appear in generated assembly sources, making them + useful for leaving notes to yourself as you work.
    3. +
  3. They're listed in the Notes window. Double-clicking them jumps + the selection to the note, making them useful as bookmarks.
    4. +
+ +
+
+ +
+
+ t1-set-addr-1017 +
+
+

It's time to do something with the code. If you look at what the code + does you'll see that it's copying several dozen bytes from $1017 + to $2000, then jumping to $2000. It appears to be relocating the next + part of the code before + executing it. We want to let the disassembler know what's going on, so + select the line at address $1017 and then + Actions > Set Address. (Or double-click on + "1017" in the Addr column.) + In the Set Address dialog, type "2000", and hit Enter.)

+
+
+ +
+
+ t1-addr-chg-1017 +
+
+

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.

+
+
+ +
+
+

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.)

+

As you make alterations to the addresses, 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.)

+
+
+ +
+
+ t1-simple-instr-edit +
+
+

Select the line with address $2003 ("CMP #$04"), 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 + "Binary", then "OK". It now appears as a binary value.

+
+
+ +
+
+ t1-2003-done +
+
+

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

+
+
+ +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/string-formatting.html b/docs/sgtutorial/string-formatting.html new file mode 100644 index 0000000..a81069c --- /dev/null +++ b/docs/sgtutorial/string-formatting.html @@ -0,0 +1,121 @@ + + + + + + + + + + + String Formatting - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

String Formatting

+ +
+
+

Programs can encode strings, such as human-readable text or + filenames, in a variety of ways. Assemblers generally support one + or more of these. SourceGen allows you to choose from a number of + different formats, and automatically generates appropriate assembler + directives.

+

The most popular formats are null-terminated (string data followed + by $00), length-delimited (first byte or two holds the string length), + and dextral character inverted (the high bit on the last byte is + flipped). Sometimes strings are stored in reverse, so the output + routine can decrement a register to zero.

+
+
+ +
+
+ t2-str-null-term-start +
+
+

Looking at the Tutorial2 code, there are four strings starting + at address $2004, each of which is followed by $00. These look like + null-terminated strings, so let's make it official.

+
+
+ +
+
+ t2-str-null-term-bad +
+
+

First, let's do it wrong. Click on the line with + address $2004 to select it. Hold the shift key down, then double-click + on the operand field of the line with address $2031 (i.e. double-click on + the words "last string").

+

The Edit Data Operand dialog opens, but the null-terminated strings + option is not available. This is because we didn't include the null byte + on the last string. To be recognized as one of the "special" string types, + every selected string must match the expected pattern.

+
+
+ +
+
+ t2-str-null-term-good +
+
+

Cancel out of the dialog. Hold the shift key down, and double-click + on the operand on line $203C ($00). + With all 57 bytes selected, + you should now see "Null-terminated strings (4)" as an available + option (make sure the Character Encoding pop-up is set to + "Low or High ASCII"). Click on that, then click OK. + The strings are now shown as .ZSTR operands.

+
+
+ + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/using-sourcegen.html b/docs/sgtutorial/using-sourcegen.html new file mode 100644 index 0000000..65a6c7e --- /dev/null +++ b/docs/sgtutorial/using-sourcegen.html @@ -0,0 +1,174 @@ + + + + + + + + + + + Using SourceGen - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Using SourceGen

+ +
+
+

This first section covers the basics of working with SourceGen: how to + move around, make edits, generate code, and so on. + SourceGen has some unusual features, so it's worth reading through this + even if you've used other disassemblers.

+ +

You can't do anything useful until you open an existing project or + create a new one, so we'll start there.

+
+
+ +
+
+

A SourceGen project is always associated with a data file, which + holds part or all of the program being disassembled. + For simplicity, the project is given the same name as the data file, with + .dis65 on the end. + No part of the data file is included in the project file, so you need + to keep both files in the same place. + If the program you're disassembling was split into more than one data + file, you'll need a separate project file for each.

+
+
+ +
+
+ t1-fresh-install +
+
+

To start a new project, launch SourceGen, and click on the + "Start New Project" button on + the initial screen, or use File > New. This opens the "New Project" + window, which lets you specify the target system and data file.

+
+
+ +
+
+ t1-new-project +
+
+

Choosing a target system, such as Apple //e or Commodore 64, will + create a project configured with the appropriate CPU and options. + If nothing in the list matches the file you want to work on, + there are "generic" entries for each + of the primary CPU varieties (6502, 65C02, W65C02, and 65816). If + you're unsure, just take your best guess. It's easy to change things after the + project has been started.

+

The area on the right side of the window has a list of the files, scripts, + and optional features that will be enabled for the + selected system. The various items here will be explained in more + detail later on.

+
+
+ +
+
+ t1-new-tutorial1 +
+
+

For this tutorial, we're going to use "Generic 6502", + near the bottom of the list.

+

The other thing we need to do here is select the data file to be + disassembled. Click Select File, navigate to the Examples + directory in the SourceGen installation directory, open Tutorial, + and select Tutorial1. +

Click OK to create the project.

+
+
+ +
+
+

The first thing you should do after creating a new project is save it. + 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.

+

(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.)

+
+
+ +
+
+ t1-settings +
+
+

The disassembly display can be tailored to your personal + preferences. Use Edit > Settings to open the + settings editor. You can change fonts, upper/lower case, text + delimiters, line wrapping, pseudo-op names, and more. There + are "quick set" buttons on some screens that allow you to make the + output resemble various popular assemblers.

+
+
+ +
+
+

All app settings are local to your system, and do not affect + the project in any way. If somebody else opens the same project, + they may see entirely different pseudo-ops and upper-case choices, + based on their own personal preferences. + (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.

+
+
+ +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/sgtutorial/visualizations.html b/docs/sgtutorial/visualizations.html new file mode 100644 index 0000000..6dc6438 --- /dev/null +++ b/docs/sgtutorial/visualizations.html @@ -0,0 +1,343 @@ + + + + + + + + + + + Visualizations - SourceGen Tutorial + + + + +
+ + + +
+ +
+ + + +
+ +
+ + + +
+ +
+ +

Visualizations

+ +
+
+

Many programs contain a significant amount of graphical data. This is + especially true for games, where the space used for bitmaps is often + larger than the space required for the code. When disassembling a program + it can be very helpful to be able to see the contents of the data + regions in graphical form.

+ +

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 + 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 + 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.

+
+
+ +
+
+ t5-add-vis +
+
+

The first thing we need to do is load an extension script that can + decode this format. The SourceGen "RuntimeData" directory has a few, + but for this tutorial we're using a custom one. Select + Edit > Project Properties, select the + Extension Scripts tab, and click + Add Scripts from Project. + Double-click on "VisTutorial5.cs", + then click OK.

+
+
+ +
+
+ t5-new-vis +
+
+

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

+
+
+ +
+
+

We're going to ignore most of what's going on and just focus on the + list of parameters at the bottom. The file offset indicates where in + the file the bitmap starts; note this is an offset, not an address + (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.

+
+
+ +
+
+ t5-set-height-8 +
+
+

We happen to know (by playing the game and/or reading the fictitious + drawing code) that the image is 8x8, so change the value in the + Height + field to 8. As soon as you do, the preview window shows a big blue 'X'. + (The 'X' is 7x7; the last row/column of pixels are transparent so adjacent + images don't bump into each other.)

+
+
+ + +
+
+ t5-set-height-80 +
+
+

Let's try doing it wrong. Add a '0' in the Height + field to make the + height 80. You can see some additional bitmap data.

+
+
+ +
+
+ t5-set-height-800 +
+
+

Add another 0 to make it 800. Now you get + a big red X, and the Height parameter is shown in red. + That's because the maximum value for the height is 512, as shown + by "[1,512]" on the right.

+
+
+ +
+
+ t5-addvis1 +
+
+

Change it back to 8, and hit OK. + Hit OK in the Edit Visualization Set + window as well. You should now see the blue 'X' in the code listing + above line $100A.

+
+
+ +
+
+ t5-addvis2 +
+
+

Repeat the process at line $1012: select the line, create a visualization + set, create a new visualization. The height will default to 8 because + that's what you used last time, so you shouldn't have to + make any changes to the initial values. + Click OK in both dialogs to close them.

+
+
+ +
+
+ t5-101a-mess +
+
+

Repeat the process at line $101A, but this time the image is 40x40 + rather than 8x8. Set the width to 5, and the height to 40. This makes + a mess.

+
+
+ +
+
+ t5-101a-good +
+
+

In this case, the bitmap data is 5 bytes wide, but the data is stored + 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. Hit + OK twice to create the visualization.

+
+
+ +
+
+ t5-fmt-dense +
+
+

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 + dense. Open the operand editor again, but this time select the + densely-packed bytes sub-option ...with a limit, and set the limit + to 8 bytes per line. Instead of one very dense statement spread across + a few lines, you get one line of source code per row of bitmap.

+
+
+ +
+
+

To change whether or not commas appear between bytes in the operand, + open Edit > Settings, select the + Display Format tab, and check + Use comma-separated format for bulk data. + This trades off compactness for ease of reading.

+
+
+ +
+ +

Bitmap Animations

+ +
+
+ t5-bitmap-anim-editor +
+
+

Some bitmaps represent individual frames in an animated sequence. + You can convert those as well. Double-click on the blue 'X' to open + the visualization set editor, then click "New Bitmap Animation". This + opens the Bitmap Animation Editor.

+
+
+ +
+
+ t5-xo-anim +
+
+

Let's try it with our Tic-Tac-Toe board pieces. From the list + on the left, select the blue 'X' and click Add, then + click the 'O' and click Add. Below the list, set the + frame delay to 500 msec. Near the bottom, click + Start / Stop. This causes the animation to play in a loop.

+
+
+ +
+
+

You can use the controls to add and remove items, change their order, and change + the animation speed. You can add the grid bitmap 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.

+
+
+ +
+
+ t5-list-xanim +
+
+

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 names. Tags must be unique.

+
+
+ +
+ +

Other Notes

+ +
+
+

The visualization editor is intended to be very dynamic, showing the + results of parameter changes immediately. This can be helpful if you're + not exactly sure what the size or format of a bitmap is. Just keep + tweaking values until it looks right.

+ +

Visualization generators are defined by extension scripts. If you're + disassembling a program with a totally custom way of storing graphics, + you can write a totally custom visualizer and distribute it with the + project. Because the file offset is a parameter, you're not limited to + placing visualizations at the start of the graphic data -- you can put + them on any code or data line.

+ +

Visualizations have no effect on assembly source code generation, + but they do appear in code exported to HTML. Bitmaps are converted to GIF + images, and animations become animated GIFs.

+
+
+ +
+
+ t5-wireframe-sample +
+
+

You can also create animated visualizations of wireframe objects + (vector graphics, 3D shapes), but that's not covered in this tutorial.

+
+
+ + + +
+ +
+ « Previous + Next » +
+ + + + + diff --git a/docs/topnav-incl.html b/docs/topnav-incl.html new file mode 100644 index 0000000..421e74f --- /dev/null +++ b/docs/topnav-incl.html @@ -0,0 +1,23 @@ + + +