6502bench SourceGen: Advanced Topics
+SourceGen: Advanced Topics
-Platform Symbol Files (.sym65)
+Platform Symbol Files (.sym65)
Platform symbol files contain lists of symbols, each of which has a label and a value. SourceGen comes with a collection of symbols for @@ -124,8 +125,8 @@ the symbol established for the masked value will be used instead.
If there are multiple masked values for a given address, the precedence is undefined.
To disable the MULTI_MASK and resume normal declarations, write the -tag without arguments: -
*MULTI_MASK+tag without arguments: +
*MULTI_MASK
Creating a Project-Specific Symbol File
@@ -151,7 +152,7 @@ not detected automatically. Use File > Reload External Files to import the changes. -Extension Scripts
+Extension Scripts
Extension scripts, also called "plugins", are C# programs with access to the full .NET Standard 2.0 APIs. They're compiled at run time by SourceGen @@ -212,7 +213,6 @@ $1234 InAZ_PrintString PLA
InNR_ : non-returning call (i.e. the JSR acts like
a JMP)Anything more complicated will require a custom script.
@@ -298,7 +298,7 @@ circumstances change, so I'm using app domains as a way to keep the API honest. -Working With Multiple Binaries
+Working With Multiple Binaries
Sometimes a program is split into multiple files on disk. They may be all loaded at once, or some may be loaded into the same place @@ -320,7 +320,7 @@ once, so there's no reason to treat them as separate projects. Currently, the best way to deal with this is to concatenate the files into a single file, and operate on that.
-Overlapping Address Spaces
+Overlapping Address Spaces
Some programs use memory overlays, where multiple parts of the code run in the same address in RAM. Others use bank switching to access parts of the program that reside in separate physical RAM or ROM, @@ -382,7 +382,7 @@ If we hit the top of the tree without finding a match, we conclude that the reference is to an external address.
-OMF Relocation Dictionaries
+OMF Relocation Dictionaries
This feature is considered experimental. Some features, like cross-reference tracking, may not work correctly with it.
@@ -406,14 +406,14 @@ Without context, the disassembler will treat the PEA instruction as two independent 16-bit addresses, and the immediate values as constants:
.dbank $02
-02/317c: f4 02 00 L2317C pea L20002 & $ffff
-02/317f: f4 54 32 pea L23254 & $ffff
+02/317c: f4 02 00 L2317C pea L20002 & $ffff
+02/317f: f4 54 32 pea L23254 & $ffff
02/3182: a2 0c 20 ldx #WriteCString
02/3185: 22 00 00 e1 jsl Toolbox
02/3189: a9 00 00 L23189 lda #$0000
-02/318c: 8d 78 3f sta L23F78 & $ffff
+02/318c: 8d 78 3f sta L23F78 & $ffff
02/318f: a9 03 00 lda #$0003
-02/3192: 8d 7a 3f sta L23F78 & $ffff +2
+02/3192: 8d 7a 3f sta L23F78 & $ffff +2
Worse yet, those STA instruction operands would have been
shown as hex values or incorrect labels if the DBR had been set incorrectly.
@@ -422,14 +422,14 @@ address from which the addresses were formed, and we can tell when
immediate values are addresses rather than constants. And we can do this
even without setting the DBR.
-02/317c: f4 02 00 L2317C pea L23254 >> 16 -02/317f: f4 54 32 pea L23254 & $ffff +02/317c: f4 02 00 L2317C pea L23254 >> 16 +02/317f: f4 54 32 pea L23254 & $ffff 02/3182: a2 0c 20 ldx #WriteCString 02/3185: 22 00 00 e1 jsl Toolbox -02/3189: a9 00 00 L23189 lda #L30000 & $ffff -02/318c: 8d 78 3f sta L23F78 & $ffff -02/318f: a9 03 00 lda #L30000 >> 16 -02/3192: 8d 7a 3f sta L23F78 & $ffff +2 +02/3189: a9 00 00 L23189 lda #L30000 & $ffff +02/318c: 8d 78 3f sta L23F78 & $ffff +02/318f: a9 03 00 lda #L30000 >> 16 +02/3192: 8d 7a 3f sta L23F78 & $ffff +2
The absence of relocation data can be a useful signal as well. For example, when pushing arguments for a toolbox call, the disassembler @@ -449,10 +449,10 @@ relocated. Consider this bit of source code:
02/0aa8: a5 42 lda $42 02/0aaa: 48 pha -02/0aab: f4 02 00 pea L20002 & $ffff -02/0aae: f4 03 31 pea L23103 & $ffff -02/0ab1: f4 05 00 pea L20005 & $ffff -02/0ab4: f4 00 00 pea L20000 & $ffff +02/0aab: f4 02 00 pea L20002 & $ffff +02/0aae: f4 03 31 pea L23103 & $ffff +02/0ab1: f4 05 00 pea L20005 & $ffff +02/0ab4: f4 00 00 pea L20000 & $ffff 02/0ab7: a2 0b 26 ldx #Int2Dec 02/0aba: 22 00 00 e1 jsl Toolbox@@ -460,8 +460,8 @@ relocated. Consider this bit of source code:
02/0aa8: a5 42 lda $42 02/0aaa: 48 pha -02/0aab: f4 02 00 pea L230C2 >> 16 -02/0aae: f4 03 31 pea L23103 & $ffff +02/0aab: f4 02 00 pea L230C2 >> 16 +02/0aae: f4 03 31 pea L23103 & $ffff 02/0ab1: f4 05 00 pea $0005 02/0ab4: f4 00 00 pea $0000 02/0ab7: a2 0b 26 ldx #Int2Dec @@ -469,7 +469,7 @@ relocated. Consider this bit of source code:-
Debug Menu Options
+Debug Menu Options
The DEBUG menu is hidden by default in release builds, but can be exposed by checking the "enable DEBUG menu" box in the application @@ -478,8 +478,8 @@ not help you debug 6502 projects.
Features:
-
-
- Re-analyze (F5). Causes a full re-analysis. Useful if you think - the display is out of sync. +
- Re-analyze (F5). Causes a full re-analysis. + Useful if you think the display is out of sync.
- Source Generation Tests. Opens the regression test harness. See
README.mdin the SGTestData directory for more information. If the regression tests weren't included in the SourceGen distribution, diff --git a/docs/sgmanual/analysis.html b/docs/sgmanual/analysis.html index 28d7084..2c6abfe 100644 --- a/docs/sgmanual/analysis.html +++ b/docs/sgmanual/analysis.html @@ -1,22 +1,23 @@ - - + + - - - -Instruction and Data Analysis - 6502bench SourceGen + + + + +Instruction and Data Analysis - 6502bench SourceGen -6502bench SourceGen: Instruction and Data Analysis
+SourceGen: Instruction and Data Analysis
This section discusses the internal workings of SourceGen. It is not necessary to understand this to use the program.
-Analysis Process
+Analysis Process
Analysis of the file data is a complex multi-step process. Some changes to the project, such as adding a code start point or @@ -87,7 +88,7 @@ many lines it will occupy, so it's done immediately and cached for re-use on subsequent runs.
-Automatic Formatting
+Automatic Formatting
Every offset in the file is marked as an instruction byte, data byte, or inline data byte. Some offsets are also marked as the start of an instruction @@ -142,7 +143,7 @@ to the user-specified descriptor list. During the analysis pass it would be added to the Anattrib array at offset +000000.
-Interaction With Undo/Redo
+Interaction With Undo/Redo
The analysis pass always considers the current state of the user data structures. Whether you're adding a label or removing one, the @@ -189,7 +190,7 @@ add up quickly). When undoing a change, before and after are simply reversed.
-Code Analysis
+Code Analysis
The code tracer walks through the instructions, examining them to determine where execution will proceed next. There are five possibilities @@ -282,7 +283,7 @@ assumes that it's equal to the program bank register ("K"), and provides a way to override the value.
-Extension Scripts
+Extension Scripts
Extension scripts can mark data that follows a JSR, JSL, or BRK as inline data, or change the format of nearby data or instructions. The first @@ -303,7 +304,7 @@ with inline data tags specified by the user, because those are applied before code analysis starts.)
-Data Analysis
+Data Analysis
The data analyzer performs two tasks. It matches operands with offsets, and it analyzes uncategorized data. This behavior can be modified in the @@ -321,9 +322,9 @@ the instruction start. This is necessary because labels are only visible if they're associated with the first (opcode) byte of an instruction.
The uncategorized data analyzer tries to find character strings and -opportunities to use the ".FILL" operation. It breaks the file into -pieces, where contiguous regions hold nothing but data, are not split -across address region start/end directives, are not interrupted by data, +opportunities to use the "
- - - -.FILL" operation. It breaks the file +into pieces where contiguous regions hold nothing but data, are not split +across address region start/end directives, are not interrupted by labels, and do not contain anything that the user has chosen to format. Each region is scanned for matching patterns. If a match is found, a format entry is added to the Anattrib array. Otherwise, data is added as single-byte diff --git a/docs/sgmanual/codegen.html b/docs/sgmanual/codegen.html index 609c33b..968efe7 100644 --- a/docs/sgmanual/codegen.html +++ b/docs/sgmanual/codegen.html @@ -1,32 +1,35 @@ - - + +Code Generation & Assembly - 6502bench SourceGen + + + + +Code Generation & Assembly - 6502bench SourceGen -6502bench SourceGen: Code Generation & Assembly
+SourceGen: Code Generation & Assembly
SourceGen can generate an assembly source file that, when fed into the target assembler, will recreate the original data file exactly. Every assembler is different, so support must be added to SourceGen for each.
-The generation / assembly dialog can be opened with File > Assemble.
+The generation / assembly dialog can be opened with +File > Assemble.
If you want to show code to others, perhaps by adding a page to your web site, you can "export" the formatted code as text or HTML. This is explained in more detail below. -
Generating Source Code
+Generating Source Code
Cross assemblers tend to generate additional files, either compiler -intermediaries ("file.o") or metadata ("_FileInformation.txt"). Some +intermediaries ("file.o") or metadata +("_FileInformation.txt"). Some generators may produce multiple source files, perhaps a link script or symbol definition header to go with the assembly source. To avoid spreading files across the filesystem, SourceGen does all of its work @@ -34,14 +37,15 @@ in the same directory where the project lives. Before you can generate code, you have to have assigned your project a directory. This is why you can't assemble a project until you've saved it for the first time.
-The Generate and Assemble dialog has a drop-down list near the top -that lets you pick which assembler to target. The name of the assembler -will be shown with the detected version number. If the assembler -executable isn't configured, "[latest version]" will be shown instead -of a version number.
-The Settings button will take you directly to the assembler configuration -tab in the application settings dialog.
-Hit the Generate button to generate the source code into a file on disk. +
The Generate and Assemble dialog has a drop-down list near +the top that lets you pick which assembler to target. The name of the +assembler will be shown with the detected version number. If the assembler +executable isn't configured, "[latest version]" will be +shown instead of a version number.
+The Settings button will take you directly to the +assembler configuration tab in the application settings dialog.
+Hit the Generate button to generate the source code into +a file on disk. The file will use the project name, with the
.dis65extension replaced by_<assembler>.S.The first 64KiB of each generated file will be shown in the preview @@ -51,26 +55,27 @@ prepended to each line to make it easier to track down errors.
-Label Localizer
+Label Localizer
The label localizer is an optional feature that automatically converts some labels to an assembler-specific less-than-global label format. Local -labels may be reusable (e.g. using "]LOOP" for multiple consecutive -loops is easier to understand than giving each one a unique label) or -reduce the size of a generated link table. There are usually restrictions -on local labels, e.g. references to them may not be allowed to cross a -global label definition, which the localizer factors in automatically.
+labels may be reusable (e.g. using "@LOOP" for multiple +consecutive loops is easier to understand than giving each one a unique +label) or reduce the size of a generated link table. There are usually +restrictions on local labels, e.g. references to them may not be allowed +to cross a global label definition, which the localizer factors in +automatically. -Reserved Label Names
+Reserved Label Names
Some label names aren't allowed. For example, 64tass reserves the use of labels that begin with two underscores. Most assemblers will also prevent you from using opcode mnemonics as labels (which means -you can't assemble
+you can't assemble the infinite loopjmp jmp jmp).jmp jmp jmp).If a label doesn't appear to be legal, the generated code will use a suitable replacement (e.g.
-jmp_1 jmp jmp_1).Platform-Specific Features
+Platform-Specific Features
SourceGen needs to be able to assemble binaries for any system with any assembler, so it generally avoids platform-specific features. One exception to that is C64 PRG files.
@@ -98,16 +103,16 @@ can add a label or reformat the bytes. This feature is currently only enabled for 64tass. -Cross-Assembling Generated Code
+Cross-Assembling Generated Code
After generating sources, if you have a cross-assembler executable -configured, you can run it by clicking the "Run Assembler" button. The -command-line output will be displayed, with stdout and stderr separated. +configured, you can run it by clicking the Run Assembler button. +The command-line output will be displayed, with stdout and stderr separated. (I'd prefer them to be interleaved, but that's not what the system provides.)
The output will show the assembler's exit code, which will be zero -on success (note: sometimes they lie.) If it appeared to succeed, +on success (note: sometimes they lie). If it appeared to succeed, SourceGen will then compare the assembler's output to the original file, and report any differences.
Failures here may be due to bugs in the cross-assembler or in @@ -115,7 +120,7 @@ SourceGen. However, SourceGen can generally work around assembler bugs, so any failure is an opportunity for improvement.
-Supported Assemblers
+Supported Assemblers
SourceGen currently supports the following cross-assemblers:
-
@@ -125,7 +130,7 @@ so any failure is an opportunity for improvement.
- Merlin 32
Version-Specific Code Generation
+Version-Specific Code Generation
Code generation must be tailored to the specific version of the assembler. This is most easily understood with an example.
@@ -141,15 +146,16 @@ be generated for all versions of the assembler by just outputting raw hex bytes, but that's ugly and annoying, so we don't want to be stuck doing that forever. We want to detect which version of the assembler is in use, and output actualMVN/MVPinstructions -when producing code for newer versions of the assembler. +when producing code for versions of the assembler that don't have the bug.When you configure a cross-assembler, SourceGen runs the executable with -version query args, and extracts the version information from the output -stream. This is used by the generator to ensure that the output will compile. -If no assembler is configured, SourceGen will produce code optimized -for the latest version of the assembler.
+version query arguments, and extracts the version information from the output +stream. This is used by the generator to ensure that the output will work +correctly with the installed assembler. +If the assembler is present on the system, SourceGen will produce code +optimized for the latest supported version of the assembler. -Assembler-Specific Bugs & Quirks
+Assembler-Specific Bugs & Quirks
This is a list of bugs and quirky behavior in cross-assemblers that SourceGen works around when generating code.
@@ -163,8 +169,21 @@ to halt with an error message. The code generator needs to understand expression syntax and operator precedence to generate correct code, but also needs to know how to handle the corner cases. +Undocumented Opcodes
-64tass
+The data sheet for the 6502 does not define all 256 possible opcodes. +Analysis and experimentation have found that many of these "undocumented" +operations actually do useful things. The people who did the research +didn't always use the same mnemonic names for them, which led to a bit +of confusion in assemblers.
+The most authoritative source is +NMOS 6510 Unintended Opcodes (PDF). +The document defines a primary mnemonic and lists common aliases for +each operation. SourceGen will output the primary mnemonic unless the +target assembler doesn't handle it.
+ + +64tass
Tested versions: v1.53.1515, v1.54.1900, v1.55.2176, v1.56.2625 [web site]
@@ -199,9 +218,9 @@ code, but also needs to know how to handle the corner cases. character ('`') rather than the caret ('^'). (There's a note in the docs to the effect that they plan to move to carets.)- Instructions whose argument is formed by combining with the - 65816 Program Bank Register (16-bit JMP/JSR) must be specified - as 24-bit values for code that lives outside bank 0. This is - true for both symbols and raw hex (e.g.
@@ -218,7 +237,7 @@ code, but also needs to know how to handle the corner cases. -JSR $1234+ 65816 Program Bank Register (16-bitJMP/JSR) + must be specified as 24-bit values for code that lives outside bank 0. + This is true for both symbols and raw hex (e.g.JSR $1234is invalid outside bank 0). Attempting to JSR to a label in bank 0 from outside bank 0 causes an error, even though it is technically a 16-bit operand.ACME
+ACME
Tested versions: v0.96.4, v0.97 [web site]
@@ -229,7 +248,7 @@ code, but also needs to know how to handle the corner cases. outside bank zero cannot be assembled. SourceGen currently deals with this by outputting the entire file as a hex dump.- Undocumented opcode $AB (
-LAX #imm) generates an error.- BRK and WDM are not allowed to have operands.
+- BRK is not allowed to have an operand.
Quirks:
@@ -262,7 +281,7 @@ code, but also needs to know how to handle the corner cases. -cc65
+cc65
Tested versions: v2.17, v2.18 [web site]
@@ -286,8 +305,9 @@ code, but also needs to know how to handle the corner cases. more common interpretation would belabel >> (8 - 16). (This is actually somewhat convenient, since none of the expressions SourceGen currently generates require parenthesis.) -- Undocumented opcode
+SBX($cb) uses the mnemonic AXS. All - other opcodes match up with the "unintended opcodes" document.- Undocumented opcode
SBX($cb) uses the mnemonic +AXS. All other opcodes match up with the + "unintended opcodes" document.- ca65 is implemented as a single-pass assembler, so label widths can't always be known in time. For example, if you use some zero-page labels, but they're defined via
.ORG $0000after the point @@ -304,7 +324,7 @@ code, but also needs to know how to handle the corner cases. -Merlin 32
+Merlin 32
Tested Versions: v1.0 [web site] @@ -353,7 +373,7 @@ code, but also needs to know how to handle the corner cases.
-Exporting Source Code
+Exporting Source Code
The "export" function takes what you see in the code list in the app and converts it to text or HTML. The options you've set in the app settings, such as capitalization, text delimiters, pseudo-opcode names, diff --git a/docs/sgmanual/editors.html b/docs/sgmanual/editors.html index 5abb2f9..5282a61 100644 --- a/docs/sgmanual/editors.html +++ b/docs/sgmanual/editors.html @@ -1,20 +1,21 @@ - - + +
- - - -Editors - 6502bench SourceGen + + + + +Editors - 6502bench SourceGen -diff --git a/docs/sgmanual/end-notes.html b/docs/sgmanual/end-notes.html index 7ace0fd..145c755 100644 --- a/docs/sgmanual/end-notes.html +++ b/docs/sgmanual/end-notes.html @@ -1,19 +1,20 @@ - - + + - - - -6502bench SourceGen: Editors
+SourceGen: Editors
-Define Address Region
+Define Address Region
Address regions may be created, edited, resized, or removed. Which @@ -83,11 +84,11 @@ opening the editor.
To see detailed information about an address region in the "Info" window, select the region start or end directive. You can see the current arrangement of address regions across your entire -project with Navigate > View Address Map.
+project with Navigate > View Address Map. -Override Status Flags
+Override Status Flags
The state of the processor status flags are tracked for every instruction. Each individual flag is recorded as zero, one, or @@ -99,7 +100,7 @@ register, may also be set in the editor.
is set to 65816. -Edit Label
+Edit Label
Sets or clears a label at the selected offset. The label must have the proper form, and not have the same name as another symbol, unless it's specified to be non-unique. If you @@ -119,14 +120,14 @@ be imported by other projects (see Working With Multiple Binaries).
-Edit Operand (Instruction)
+Edit Operand (Instruction)
Operands can be formatted explicitly, or you can let the disassembler select the format for you. By default, immediate constants and addresses with no matching symbol are formatted as hex. Symbols defined as address labels, platform/project symbols, and local variables will be identified and applied automatically.
-Explicit Formats
+Explicit Formats
Operands can be displayed in a variety of numeric formats, or as a symbol. The character formats are only available for operands whose value falls into the proper range. The ASCII format handles @@ -162,13 +163,14 @@ branch instructions.
The bottom part of the window has some shortcuts for working with address references and local variables. These are primarily used to -change the way things work when "Default" is selected. The shortcuts +change the way things work when the Default format option +is selected. The shortcuts don't cause any changes to the recorded format of the instruction being edited. All of the actions can be performed elsewhere, by editing the label at the target address, editing the project symbol set, or editing a local variable table.
-Numeric Address References
+Numeric Address References
For operands that are 8-bit, 16-bit, or 24-bit addresses, you can define a symbol for the address as a label or @@ -187,9 +189,10 @@ in the editor.
address or I/O location, you can define a project symbol. If a match was found in the configured platform definition files, it will be shown; it can't be edited, but it can be overridden by a project symbol. -You can create or modify a project symbol by clicking on "Create Project -Symbol" or "Edit Project Symbol". You can't delete project symbols -from this editor (use Project Properties instead). +You can create or modify a project symbol by clicking on +Create Project Symbol or Edit Project Symbol. +You can't delete project symbols +from this editor (use the Project Properties editor instead).It's possible to have more than one project symbol for the same address. For example, on the Apple II, reading from the memory-mapped @@ -199,24 +202,26 @@ have two different names for it. If more than one project symbol has the same address, the first one found will be used, which may not be what is desired. In such situations, you should create the project symbol and then copy the symbol name into the operand. You can do this -in one step by clicking the "Copy to Operand" button. +in one step by clicking the Copy to Operand button. (In most cases you don't want to do this, because if the project symbol is deleted or renamed, you'll have operands that refer to a nonexistent symbol. Unlike labels, project symbol renames do not refactor the rest of the project.) -
Local Variable References
+Local Variable References
For zero-page address operands and (65816-only) stack-relative -constant operands, a local variable can be created or modified. This +constant operands, a +local variable +can be created or modified. This requires that a local variable table has been defined at or before the instruction being edited.
If an existing entry is found, you will be able to edit the name and comment fields. If not, a new entry with a generic name and -pre-filled value field will be created in the nearest table.
+pre-filled value field will be prepared in the nearest prior table. -Edit Operand (Data)
+Edit Operand (Data)
This dialog offers a variety of choices, and can be used to apply a format to multiple lines. You must select all of the bytes you want @@ -234,46 +239,48 @@ many regions they have been divided into.
(End-of-line comments do not split a region, and will disappear if they end up inside a multi-byte data item.)
-The "Simple Data" items behave the same as their equivalents in the -Edit Operand dialog. However, because the width is not determined by -an instruction opcode, and multiple items can be selected, you will need -to specify how wide each item is and what its byte order is. For data -you also have the option of setting the format to "Address", which marks -the selected bytes as a numeric reference.
+The Simple Data items behave the same as their equivalents +in the Edit Operand (Instruction) dialog. However, because the width is +not determined by an instruction opcode, and multiple items can be selected, +you will need to specify how wide each item is and what its byte order is. +For data you also have the option of setting the format to +Address, which marks the selected bytes as a +numeric reference.
Consider a simple example: suppose you find a table of 16-bit addresses in the code. Click on the first byte, shift-click the last byte, then select the Edit Data menu item. The number of bytes selected should be even. Select -"16-bit words, little-endian", then over to the right click on -"Address". When you click OK, the selected data will be formatted as a -series of 16-bit address values. If the addresses can be resolved inside -the data file, each address will be assigned a label.
+16-bit words, little-endian, then over to the right click on +Address. When you click OK, the selected data +will be formatted as a series of 16-bit address values. If the addresses +can be resolved inside the data file, each address will be assigned +an automatically-generated label. -The "Bulk Data" items can represent large chunks of data compactly. -The "fill" option is only available if all selected bytes have the -same value.
+The Bulk Data items can represent large chunks of data +compactly. The Fill option is only available if all selected +bytes have the same value.
If a region of bytes is used for data storage, but the initial values -don't matter, you can mark it as "uninitialized data". (The code -generated will usually use an initialized bulk data directive rather -than a "leave space" directive, because SourceGen wants to guarantee -that the assembled binary matches the original.)
+don't matter, you can mark it as Uninitialized data. +(Note that the code generated will usually use an initialized bulk data +directive rather than a "leave space" directive, because SourceGen wants +to guarantee that the assembled binary matches the original.)If a region of bytes is irrelevant, e.g. dead code or padding, -you can mark it as "junk". If it appears to be adding bytes to reach a -power-of-two address boundary, you can designate it as an alignment -directive. If you have multiple regions selected, only options that -work for all regions will be shown.
+you can mark it as Junk. If it appears to be adding bytes +to reach a power-of-two address boundary, you can designate it as an alignment +directive. If you have multiple regions selected, only the alignment +options that work for all regions will be shown. -The "String" items are enabled or disabled depending on whether the -data you have selected is in the appropriate format. For example, -"Null-terminated strings" is only enabled if the data regions are +
The String items are enabled or disabled depending on +whether the data you have selected is in the appropriate format. For example, +Null-terminated strings is only enabled if the data regions are composed entirely of characters followed by $00. Zero-length strings are allowed. DCI (Dextral Character Inverted) strings have the high bit on the last byte flipped; for PETSCII this will usually look like a series of lower-case letters followed by a capital letter, but may look odd if the last character is punctuation (e.g. '!' becomes $A1, which is a -rectangle character that SourceGen will only display as hex).
+rectangle glyph that will be displayed as a hex value).The character encoding can be selected, offering a choice between plain ASCII, low + high ASCII, C64 PETSCII, and C64 screen codes. When you change the encoding, your available options may change. The @@ -317,7 +324,7 @@ CODE LDA LABEL+2
With the label out of the way, the data can be formatted as desired.
-Edit Comment
+Edit Comment
Enter an end-of-line (EOL) comment, or leave the text field blank to delete it. EOL comments may be placed on instruction and data lines, but not on assembler directives.
@@ -339,7 +346,7 @@ stored in the project file, and can be edited with the project symbol editor. -Edit Long Comment
+Edit Long Comment
Long comments can be arbitrarily long and span multiple lines. They will be word-wrapped at a line width of your choosing. They're always drawn with a fixed-width font, so you can create ASCII-art diagrams. @@ -360,13 +367,14 @@ the length of the line, not just the comment text, an asterisk-boxed comment will have one fewer character per line in cc65 output.
Clear the text field to delete the comment.
-You can use Ctrl+Enter as a keyboard shortcut for "OK".
+You can use Ctrl+Enter as a keyboard shortcut +for OK.
The long comment at the very top of the project is special, as it's not associated with a file offset. If you delete it, you can get it -back by using Edit > Edit Header Comment.
+back by using Edit > Edit Header Comment. -Edit Data Bank (65816 only)
+Edit Data Bank (65816 only)
Sets the Data Bank Register (DBR) value for 65816 code. This is used when matching 16-bit address operands with labels. The new value is @@ -389,7 +397,7 @@ instructions, double-clicking on a
-PLBopcode in the code list will open the editor.Edit Note
+Edit Note
Notes are similar to long comments, in that they can be arbitrarily long and span multiple lines. However, because they're never included in generated output, options like line width formatting and boxing @@ -407,10 +415,11 @@ also simply type a color name like "violet" so long as it appears in the list of Microsoft .NET colors.
Clear the text field to delete the note.
-You can use Ctrl+Enter as a keyboard shortcut for "OK".
+You can use Ctrl+Enter as a keyboard shortcut +for OK.
-Edit Project Symbol
+Edit Project Symbol
This is used to edit the properties of a project symbol.
Symbols marked as "address" will be applied automatically when an operand references an address outside the scope of the data file. They @@ -423,7 +432,7 @@ not have the same name as another project symbol. It can overlap with platform symbols and user labels.
The value may be entered in decimal, hexadecimal, or binary. The numeric base you choose will be remembered, so that the value will be displayed -the same way when used in a .EQ directive.
+the same way when used in a.EQdirective.You can optionally provide a width for address symbols. For example, if the address is of a two-byte pointer or a 64-byte buffer, you would set the width field to cause all references to any location in that range @@ -431,26 +440,27 @@ to be set to the symbol. Widths may be entered in hex or decimal. If the field is left blank, a width of 1 is assumed. Overlapping symbols are allowed. The width is ignored for constants.
If you enter a comment, it will be placed at the end of the line of -the .EQ directive.
+the.EQdirective.For address symbols that represent a memory-mapped I/O location, it can be useful to have different symbols for reads and writes. Use -the Read/Write checkboxes to specify the desired behavior.
+the Read/Write checkboxes to specify the +desired behavior. -Create/Edit Local Variable Table
+Create/Edit Local Variable Table
Local variables are arranged in tables, which are created at a specific file offset. They must be associated with a line of code, and are usually placed at the start of a subroutine. -The "Create Local Variable Table" action creates a new table, and -opens the editor. The "Edit Prior Local Variable Table" searches +The Create Local Variable Table action creates a new table, and +opens the editor. The Edit Prior Local Variable Table searches for the closest table that appears at or before the selected line, and edits that.
The editor allows you to create, edit, and delete entries, as well as move and delete entire tables (though these last two options are not available when creating a new table). Empty tables are allowed. These can be useful if the "clear previous" flag is set. If you want to -delete the table, click the "Delete Table" button.
+delete the table, click the Delete Table button.Use the buttons to add, edit, or remove individual variables. Each variable has a name, a value, a width, and an optional comment. The standard naming rules for symbols apply. Variables are only used for @@ -459,8 +469,8 @@ range 0-255. The width may extend one byte past the end (to address $0100) to allow 16-bit accesses to $ff (particularly useful on 65816).
You can move a table to any offset that is the start of an instruction and doesn't already have a local variable table present. Click the -"Move Table" button and enter the new offset in hex. You can also click -on the up/down buttons to move to the next valid offset.
+Move Table button and enter the new offset in hex. You can +also click on the up/down buttons to move to the next valid offset.End notes - 6502bench SourceGen + + + + +End notes - 6502bench SourceGen -6502bench SourceGen: End Notes
+SourceGen: End Notes
-Origins
+Origins
The inspiration for SourceGen goes a long way back. While in high school in the late 1980s, I read Don Lancaster's Enhancing Your Apple II, Vol. 1 (available for download @@ -22,7 +23,7 @@ included a very detailed methodology for disassembling 6502 software (nicely reformatted here). I wanted to give it a try, so I generated a monitor listing of an -operating system (called "RDOS") that SSI used on their games, and +operating system called "RDOS" that SSI used on their games, and printed it out on my Epson RX-80 -- tractor feed paper was helpful for this sort of thing -- then set to work.
diff --git a/docs/sgmanual/index.html b/docs/sgmanual/index.html index d0c2d25..f63731e 100644 --- a/docs/sgmanual/index.html +++ b/docs/sgmanual/index.html @@ -1,11 +1,12 @@ - - + + - - - -Contents - 6502bench SourceGen + + + + +Contents - 6502bench SourceGen @@ -32,7 +33,7 @@ using the Help > Help menu item or by hitting- Overview
-
-
- Fundamentals +
- Fundamentals
- About 6502 Code
- Character Encoding @@ -93,7 +94,7 @@ using the Help > Help menu item or by hitting
- Editors
-
-
- Define Address Region +
- Define Address Region
- Override Status Flags
- Edit Label
- Edit Operand (Instruction) @@ -199,9 +200,7 @@ using the Help > Help menu item or by hitting
- Data Analysis
- - End Notes - -
- End Notes
+
