From 22c47e1d0b885e1f3577ff00ceb58fe9a4233e3d Mon Sep 17 00:00:00 2001 From: Andy McFadden Date: Mon, 18 Oct 2021 17:56:08 -0700 Subject: [PATCH] Update reference manual formatting Switched from XHTML to HTML5. Added formatting for menu items and keyboard shortcuts. Made various minor edits to the text. --- SourceGen/SGTestData/README.md | 15 ++ docs/sgmanual/advanced.html | 68 +++---- docs/sgmanual/analysis.html | 33 ++-- docs/sgmanual/codegen.html | 120 +++++++----- docs/sgmanual/editors.html | 140 +++++++------- docs/sgmanual/end-notes.html | 19 +- docs/sgmanual/index.html | 21 +-- docs/sgmanual/intro-details.html | 264 ++++++++++++++------------- docs/sgmanual/intro.html | 27 +-- docs/sgmanual/main.css | 10 + docs/sgmanual/mainwin.html | 304 ++++++++++++++++++------------- docs/sgmanual/settings.html | 238 ++++++++++++------------ docs/sgmanual/tools.html | 102 ++++++----- docs/sgmanual/tutorials.html | 17 +- docs/sgmanual/visualization.html | 82 +++++---- 15 files changed, 797 insertions(+), 663 deletions(-) diff --git a/SourceGen/SGTestData/README.md b/SourceGen/SGTestData/README.md index 807993a..2bf8417 100644 --- a/SourceGen/SGTestData/README.md +++ b/SourceGen/SGTestData/README.md @@ -31,6 +31,21 @@ If the leading number is 20000 or greater, the test file will be loaded as a saved project. A file with the same name plus a ".dis65" extension will be opened as the project file. +### Overriding Settings ### + +All tests are run with a fixed set of app settings, so that the tests look +the same regardless of how the assemblers are configured. For example, +upper-case conversion is disabled, and cycle counts are not shown. + +Sometimes a test will want to exercise one of these settings, so we need +a way to tell the test harness to override the default. We do this by +creating project symbols. + +| Name | Value | Description +| ---------------------- | ----- | -------------------------------------------| +| __ENABLE_LABEL_NEWLINE | any | Puts long labels on their own line | +| __ENABLE_CYCLE_COUNTS | any | Adds cycle count to end-of-line comments | + ### Execution ### With debug features enabled, you can open the test runner from the menu diff --git a/docs/sgmanual/advanced.html b/docs/sgmanual/advanced.html index aeadf36..79e8804 100644 --- a/docs/sgmanual/advanced.html +++ b/docs/sgmanual/advanced.html @@ -1,20 +1,21 @@ - - + + - - - -Advanced Topics - 6502bench SourceGen + + + + + Advanced Topics - 6502bench SourceGen
-

6502bench SourceGen: Advanced Topics

+

SourceGen: Advanced Topics

Back to index

-

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:

    -

    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 be label >> (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 $0000 after 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

    -

    6502bench SourceGen: Editors

    +

    SourceGen: Editors

    Back to index

    -

    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 PLB opcode 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 .EQ directive.

    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 .EQ directive.

    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.

    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 @@ - - + + - - - -End notes - 6502bench SourceGen + + + + + End notes - 6502bench SourceGen
    -

    6502bench SourceGen: End Notes

    +

    SourceGen: End Notes

    Back to index

    -

    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