From 4aee3af089134e840ec4785e3a574d900507e6ca Mon Sep 17 00:00:00 2001 From: Andy McFadden Date: Mon, 29 Jul 2019 13:20:03 -0700 Subject: [PATCH] Various doc fixes --- SourceGen/RuntimeData/Help/analysis.html | 41 ++++++++++++++---------- SourceGen/RuntimeData/Help/intro.html | 15 +++++---- SourceGen/WpfGui/AboutBox.xaml | 2 +- 3 files changed, 33 insertions(+), 25 deletions(-) diff --git a/SourceGen/RuntimeData/Help/analysis.html b/SourceGen/RuntimeData/Help/analysis.html index 8cd91b2..54950a3 100644 --- a/SourceGen/RuntimeData/Help/analysis.html +++ b/SourceGen/RuntimeData/Help/analysis.html @@ -13,7 +13,11 @@

6502bench SourceGen: Instruction and Data Analysis

Back to index

+

This section discusses the internal workings of SourceGen. It is +not necessary to understand this to use the program.

+

Analysis Process

+

Analysis of the file data is a complex multi-step process. Some changes to the project, such as adding a code entry point hint or changing the CPU selection, require a full re-analysis of instructions @@ -42,16 +46,16 @@ method in DisasmProject.cs):

attributes, or "anattribs", with one entry per byte in the file. The Anattrib array tracks most of the state from here on. If we're doing a partial re-analysis, this step will just clone a copy of the - Anattrib array that was made at this point in a previous run. (This - step is described in more detail below.) + Anattrib array that was made at this point in a previous run. (The + code analysis pass is described in more detail below.)
  • Apply user-specified labels to Anattribs.
  • Apply user-specified format descriptors. These are the instruction 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 - stored in the Anattribs array. (This step is described in more - detail below.)
    • + 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 labels that have been placed on offsets that are in the middle of an instruction or multi-byte data item. They can't be referenced, so we @@ -105,12 +109,12 @@ fill out the Anattribs.

    L1003 NOP -

    We haven't formatted anything yet. The data analyzer sees that the -JMP operand is inside the file, and has no label, so it creates an +

    We haven't explicitly formatted anything yet. The data analyzer sees +that the JMP operand is inside the file, and has no label, so it creates an auto-label at offset +000003 and a format descriptor with a symbolic operand reference to "L1003" at +000000.

    -

    Now we edit the label, changing L1003 to "FOO". This goes into the -project's "user label" list. The analyzer is +

    Suppose we now edit the label, changing L1003 to "FOO". This goes into +the project's "user label" list. The analyzer is run, and applies the new "user label" to the Anattrib array. The data analyzer finds the numeric reference in the JMP operand, and finds a label at the target address, so it creates a symbolic operand reference @@ -119,8 +123,9 @@ in both places.

    Even though the JMP operand changed from "L1003" to "FOO", the only change actually written to the project file is the label edit. The contents of the Anattrib array are disposable, so it can be used to -add labels and "fix up" numeric references. Generated labels and -format descriptors are never added to the project file.

    +hold auto-generated labels and "fix up" numeric references. Labels and +format descriptors generated by SourceGen are never added to the +project file.

    If the JMP operand were edited, a format descriptor would be added to the user-specified descriptor list. During the analysis pass it would @@ -167,9 +172,10 @@ reformat them:

    Each entry in the change set has "before" and "after" states for the format descriptor at a specific offset. Only the state for the affected -offsets is included -- the program doesn't take a complete state snapshot -(even with the RAM on a modern system that would add up quickly). When -undoing a change, before and after are simply reversed.

    +offsets is included -- the program doesn't record the state of the full +project after each change (even with the RAM on a modern system that would +add up quickly). When undoing a change, before and after are simply +reversed.

    Code Analysis

    @@ -222,9 +228,9 @@ performed, we assume a transition to emulation mode (E=1).

    There are three ways in which code can set a flag to a definite value:

      -
    1. By explicit instructions, like SEC or +
    2. With explicit instructions, like SEC or CLD.
      3. -
    3. By immediate-operand instructions. LDA #$00 sets Z=1 +
    4. With immediate-operand instructions. LDA #$00 sets Z=1 and N=0. ORA #$80 sets Z=0 and N=1.
    5. By inference. For example, if we see a BCC instruction, we know that the carry will be clear at the branch target address, and @@ -274,8 +280,9 @@ time a JSR/JSL instruction is encountered, all loaded extension scripts are offered a chance to act.

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

      +instructions or data that has already been formatted will fail. This rule +ensures that anything explicitly formatted by the user will not be +overridden by a script.

      If code jumps into a region that is marked as inline data, the branch will be ignored. If an extension script tries to flag bytes diff --git a/SourceGen/RuntimeData/Help/intro.html b/SourceGen/RuntimeData/Help/intro.html index eaa252b..b8cd289 100644 --- a/SourceGen/RuntimeData/Help/intro.html +++ b/SourceGen/RuntimeData/Help/intro.html @@ -82,8 +82,8 @@ rather than generated by a compiler, which means it won't conform to a standard set of conventions. However, most programmers will use subroutines, which can be identified and analyzed in isolation. Subroutines are often interspersed with variable storage, referred to as a "stash". -Variables may be single-byte or multi-byte, the latter typically -in little-endian byte order.

      +Variables and constants may be single-byte or multi-byte, the latter +typically in little-endian byte order.

      Much of the data in a typical program is read-only, often in the form of graphics or ASCII string data. Graphics can be difficult @@ -100,14 +100,15 @@ data ends and code resumes: 6502 instructions are variable-length, so if the last byte of the data area appears to be a three-byte instruction, the first two bytes of the next instruction area will be gobbled up.

      -

      Some programmers will use a trick where they "embed" an instruction +

      To make things even more difficult (sometimes deliberately), programmers +will sometimes use a trick where they "embed" an instruction inside another instruction. This allows code to branch to two different entry points, one of which will set a flag or load a register, and then continue on to common code.

      Another trick is to embed "inline data" after a JSR or JSL instruction. -The caller pulls the calling address off the stack, uses it to access -the parameters, then pushes the address back on after modifying it to +The called subroutine pulls the caller's address off the stack, uses it to +access the parameters, then pushes the address back on after modifying it to point to an address past the inline data. This can be very confusing for the disassembler, which will try to interpret the inline data as instructions.

      @@ -293,7 +294,7 @@ is the ProDOS 8 call interface on the Apple II, which looks like this:

      The three bytes following the JSR $bf00 should be hinted as inline data, so that the code analyzer skips them and continues the -analysis at the BCS. Because you need to hint *every* byte +analysis at the BCS. Because you need to hint every byte of inline data, all bytes in a selected line will receive hints.

      If code branches into a region that is marked as inline data, the branch will be ignored.

      @@ -660,7 +661,7 @@ use the shortest instruction possible.

      way. Some use opcode suffixes, others use operand prefixes, some allow both. You can configure how they appear in the application settings.

      -

      SourcGen will only add width disambiguators to opcodes or operands when +

      SourceGen will only add width disambiguators to opcodes or operands when they are needed, with one exception: the opcode suffix for long (24-bit address) operations is always applied. This is done because some assemblers require it, insisting on "LDAL" rather than "LDA" for an diff --git a/SourceGen/WpfGui/AboutBox.xaml b/SourceGen/WpfGui/AboutBox.xaml index 01536a3..8e85ec8 100644 --- a/SourceGen/WpfGui/AboutBox.xaml +++ b/SourceGen/WpfGui/AboutBox.xaml @@ -45,7 +45,7 @@ limitations under the License. - +