From a3b968f0250c17ea495ddbff617c4c07b00762dc Mon Sep 17 00:00:00 2001 From: Andy McFadden Date: Fri, 6 Sep 2019 15:38:49 -0700 Subject: [PATCH] Fix up the manual a bit --- SourceGen/RuntimeData/Help/analysis.html | 43 ++++++++++++++---------- SourceGen/RuntimeData/Help/intro.html | 12 +++++-- 2 files changed, 35 insertions(+), 20 deletions(-) diff --git a/SourceGen/RuntimeData/Help/analysis.html b/SourceGen/RuntimeData/Help/analysis.html index 14c1369..0a706fb 100644 --- a/SourceGen/RuntimeData/Help/analysis.html +++ b/SourceGen/RuntimeData/Help/analysis.html @@ -53,7 +53,8 @@ method in DisasmProject.cs):

and data operand formats.
  • Run the data analyzer. This looks for patterns in uncategorized data, and connects instruction and data operands to target offsets. - The "nearby label" stuff is handled here. All of the results are + The "nearby label" stuff is handled here. Auto-labels are generated + for references to internal addresses. All of the results are stored in the Anattribs array. (The data analysis pass is described in more detail below.)
  • Remove hidden labels from the symbol table. These are user-specified @@ -62,11 +63,16 @@ method in DisasmProject.cs):

    want to pull them out of the symbol table. (Remember, symbolic operands use "weak references", so a missing symbol just means the operand is shown as a hex value.)
    • +
  • Resolve references to local variables. This sets the operand symbol + in Anattrib so we won't try to apply platform/project symbols to + zero-page addresses. If we somehow ended up with a variable that has + the same as a user label, we rename the variable.
  • Resolve references to platform and project external symbols. This sets the operand symbol in Anattrib, and adds the symbol to the list that is displayed in .EQ directives.
    • -
  • Generate cross-reference lists. This is done for file data and - for any platform/project symbols that are referenced.
    • +
  • Generate cross-reference lists. This is done for internal references, + for local variables, and for any platform/project symbols that are + referenced.
  • If annotated auto-labels are enabled, the simple labels are replaced with the annotated versions here. (This can't be done earlier because the annotations are generated from the cross-reference data.)
    • @@ -75,7 +81,8 @@ method in DisasmProject.cs):

    Once analysis is complete, a line-by-line display list is generated by walking through the annotated file data. Most of the actual strings -aren't rendered until they're needed.

    +aren't rendered until they're needed. For complicated multi-line items +like string operands, the formatted text is cached.

    Automatic Formatting

    @@ -84,8 +91,9 @@ aren't rendered until they're needed.

    inline data byte. Some offsets are also marked as the start of an instruction or data area. The start offsets may have a format descriptor associated with them.

    -

    Format descriptors have a format (like "numeric" or "string") a -sub-format (like "hexadecimal" or "null-terminated"), and a length. For +

    Format descriptors have a format (like "numeric" or +"null-terminated string") a sub-format (like "hexadecimal" or +"high ASCII"), and a length. For an instruction operand the length is redundant, but for a data operand it determines the width of the numeric value or length of the string. For this reason, instructions do not need a format descriptor, but all @@ -140,8 +148,9 @@ code runs through the same set of steps. The advantage of this approach is that the act of doing a thing, undoing a thing, and redoing a thing are all handled the same way.

    None of the editors modify the project data structures directly. All -changes are added to a change set, which is processed by a single function. -The change sets are kept in the undo/redo buffer indefinitely. After +changes are added to a change set, which is processed by a single +"apply changes" function. The change sets are kept in the undo/redo +buffer indefinitely. After the changes are made, the Anattrib array and other data structures are regenerated.

    @@ -277,13 +286,13 @@ correctly will require improvements to the user interface.

    Extension Scripts

    -

    Extension scripts can mark data that follows a JSR or JSL as inline +

    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 -time a JSR/JSL instruction is encountered, all loaded extension scripts -are offered a chance to act.

    +time a JSR/JSL/BRK instruction is encountered, all loaded extension scripts +that implement the appropriate interface are offered a chance to act.

    The first script that applies a format wins. Attempts to re-format -instructions or data that has already been formatted will fail. This rule +instructions or data that have already been formatted will fail. This rule ensures that anything explicitly formatted by the user will not be overridden by a script.

    @@ -298,9 +307,9 @@ before code analysis starts.)

    Data Analysis

    The data analyzer performs two tasks. It matches operands with -offsets, and it analyzes uncategorized data. Either or both of -these can be disabled from the -project properties

    +offsets, and it analyzes uncategorized data. This behavior can be +modified in the +project properties.

    The data target analyzer examines every instruction and data operand to see if it's referring to an offset within the data file. If the @@ -319,8 +328,8 @@ pieces, where contiguous regions hold nothing but data, are not split across a ".ORG" directive, are not interrupted by data, 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 independent -byte values.

    +is added to the Anattrib array. Otherwise, data is added as single-byte +values.

    diff --git a/SourceGen/RuntimeData/Help/intro.html b/SourceGen/RuntimeData/Help/intro.html index 7fbf491..2fabc01 100644 --- a/SourceGen/RuntimeData/Help/intro.html +++ b/SourceGen/RuntimeData/Help/intro.html @@ -470,9 +470,12 @@ exported symbols can be pulled directly into other projects.

    instructions or data offsets that are the target of operands. They're formed by appending the hexadecimal address to the letter "L", with additional characters added if some other symbol has already defined -that label. Auto labels are only added where they are needed. Because -auto labels may be redefined or disappear, the editor will try to prevent -you from referring to them when editing operands.

    +that label. Options can be set that change the "L" to a character or +characters based on how the label is referenced, e.g. "B" for branch targets. +Auto labels are only added where they are needed, and are removed when +no longer necessary. Because auto labels may be renamed or vanish, the +editor will try to prevent you from referring to them when editing +operands.

    Local Variables

    @@ -536,6 +539,9 @@ ways for a table to erase an earlier definition:

    As you might expect, you're not allowed to have duplicate labels or overlapping values in an individual table.

    +

    If a platform/project symbol has the same value as a local variable, +the local variable is used. If the local variable definition is cleared, +use of the platform/project symbol will resume.

    Not all assemblers support redefinable variables. In those cases, the symbol names will be modified to be unique (e.g. the second definition of PTR becomes PTR_1), and variables will have