Data Bank Register management, part 5

Update documentation.  Add some information about OMF relocation
data as well.

Fix bug in B=K handling.

SourceGen/CodeAnalysis.cs

@@ -1335,7 +1335,7 @@ namespace SourceGen {
 
                 int bank;
                 if (curVal == DbrValue.USE_PBR) {
-                    bank = mAnattribs[offset].Address >> 16;
+                    bank = mAnattribs[offset].Address & 0x00ff0000;
                 } else {
                     Debug.Assert(curVal >= 0 && curVal < 256);
                     bank = curVal << 16;

SourceGen/RuntimeData/Help/advanced.html

@@ -301,6 +301,57 @@ address chunk, the first chunk that includes that address is used, as
 it is with the <code>JMP $1000</code> at the start of the file.</p>
 
 
+<h2><a name="reloc-data">OMF Relocation Dictionaries</a></h2>
+
+<p>65816 code can be tricky to disassemble for a number of reasons.
+24-bit addresses are formed from 16-bit data-access operands by combining
+with the Data Bank Register, which often requires a bit of manual
+intervention.  But the problems go beyond that.  Consider the following
+bit of source code for the Apple IIgs:</p>
+<pre>
+rsrcmsg    pea   rsrcmsg2|-16
+           pea   rsrcmsg2
+           _WriteCString
+           lda   #buffer
+           sta   pArcRead+$04
+           lda   #buffer|-16
+           sta   pArcRead+$06
+</pre>
+<p>In both cases we're referencing a 24-bit address as two 16-bit values.
+Without context, the disassembler will treat the PEA instruction as two
+independent 16-bit addresses, and the immediate values as constants:</p>
+<pre>
+                               .dbank  $02
+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/318f: a9 03 00              lda     #$0003
+02/3192: 8d 7a 3f              sta     L23F78 & $ffff +2
+</pre>
+<p>Worse yet, those <code>STA</code> instruction operands would have been
+shown as hex values or incorrect labels if the DBR had been set incorrectly.
+However, if we have the relocation data, we know the full
+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.</p>
+<pre>
+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
+</pre>
+<p>This feature is still considered "experimental".  There are some
+issues with it, e.g. the cross-reference table may show an incorrect
+offset.</p>
+
+
 <h2><a name="debug">Debug Menu Options</a></h2>
 
 <p>The DEBUG menu is hidden by default in release builds, but can be

SourceGen/RuntimeData/Help/editors.html

@@ -305,6 +305,28 @@ not associated with a file offset.  If you delete it, you can get it
 back by using Edit &gt; Edit Header Comment.</p>
 
 
+<h2><a name="data-bank">Edit Data Bank (65816 only)</a></h2>
+<p>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
+in effect from the line where it's declared to the end of the file, even
+across bank boundaries.
+If you leave the text field blank, the directive will be removed.</p>
+<p>A hexadecimal value from $00 to $ff can be entered directly.  As
+with other address inputs, a leading '$' is not required.  Entering
+"K" will set the DBR to the current address, and will automatically
+update if you change the address to a different bank.</p>
+<p>The pop-up menu has a list of all banks that hold code or data.
+To make them easier to identify, each is shown with the label on the
+first address in the bank, if any.</p>
+<p>While you can override automatically-generated data bank change
+directives, you can't remove them individually.  You can disable
+automatic generation by un-checking "smart PLB handling" in the project
+properties.</p>
+<p>Because the directive is frequently associated with <code>PLB</code>
+instructions, double-clicking on a <code>PLB</code> opcode in the
+code list will open the editor.</p>
+
+
 <h2><a name="note">Edit Note</a></h2>
 <p>Notes are similar to long comments, in that they can be arbitrarily
 long and span multiple lines.  However, because they're never included

SourceGen/RuntimeData/Help/index.html

@@ -35,6 +35,7 @@ and 65816 code.  The official web site is
     <li><a href="intro.html#sgconcepts">SourceGen Concepts</a></li>
     <li><a href="intro.html#about-symbols">All About Symbols</a>
       <ul>
+        <li><a href="intro.html#connecting-operands">Connecting Operands With Labels</a></li>
         <li><a href="intro.html#internal-address-symbols">Internal Address Symbols</a></li>
         <li><a href="intro.html#external-address-symbols">External Address Symbols</a></li>
         <li><a href="intro.html#unique-local-global">Unique vs. Non-Unique and Local vs. Global</a></li>
@@ -83,6 +84,7 @@ and 65816 code.  The official web site is
     <li><a href="editors.html#data-operand">Edit Data Operand</a></li>
     <li><a href="editors.html#comment">Edit Comment</a></li>
     <li><a href="editors.html#long-comment">Edit Long Comment</a></li>
+    <li><a href="editors.html#data-bank">Edit Data Bank (65816 only)</a></li>
     <li><a href="editors.html#note">Edit Note</a></li>
     <li><a href="editors.html#project-symbol">Edit Project Symbol</a></li>
     <li><a href="editors.html#lvtable">Edit Local Variable Table</a></li>
@@ -151,6 +153,7 @@ and 65816 code.  The official web site is
     <li><a href="advanced.html#extension-scripts">Extension Scripts</a></li>
     <li><a href="advanced.html#multi-bin">Working With Multiple Binaries</a></li>
     <li><a href="advanced.html#overlap">Overlapping Address Spaces</a></li>
+    <li><a href="advanced.html#reloc-data">OMF Relocation Dictionaries</a></li>
     <li><a href="advanced.html#debug">Debug Menu Options</a></li>
   </ul></li>
 

SourceGen/RuntimeData/Help/intro.html

@@ -131,8 +131,8 @@ space, but it's not contiguous -- a branch that extends past the end will
 wrap around to the start of the 64KiB "bank".  For 16-bit instruction
 operands, the bank is identified for instruction and data addresses
 by the program bank register and the data bank register, respectively.
-The disassembler can't generally know the contents of the data bank
+The disassembler can't always discern the value of the data bank
-register, which makes life a bit more interesting.</p>
+register through static analysis, so some user input may be required.</p>
 
 <p>The 6502 has an 8-bit processor status register ("P") with a bunch of flags
 in it.  Some of the flags determine whether a conditional branch is taken
@@ -447,6 +447,35 @@ differently from those outside a project.  We refer to these as internal
 and external addresses, respectively.</p>
 
 
+<h3><a name="connecting-operands">Connecting Operands with Labels</a></h3>
+
+<p>Suppose you have the following code:</p>
+<pre>
+         LDA     $1234
+         JSR     $2345
+</pre>
+<p>If we put that in a source file, it will assemble correctly.
+However, if those addresses are part of the file, the code may break if
+changes are made and things assemble to different addresses.  It would
+be better to generate code that references labels, e.g.:</p>
+<pre>
+         LDA     my_data
+         JSR     nifty_func
+</pre>
+<p>SourceGen tries to establish labels for address operands automatically.
+How this works depends on whether the operand's address is inside the file or
+external, and whether there are existing labels at or near the target
+address.  The details are explored in the next few sections.</p>
+<p>On the 65816 this process is trickier, because addresses are 24 bits
+instead of 16.  For a control-transfer instruction like <code>JSR</code>,
+the high 8 bits come from the Program Bank Register (K).  For a data-access
+instruction like <code>LDA</code>, the high 8 bits come from the Data
+Bank Register (B).  The PBR value is determined by the address in which
+the code is executing, so it's easy to determine.  The DBR value can be
+set arbitrarily.  Sometimes it's easy to figure out, sometimes it has
+to be specified manually.</p>
+
+
 <h3><a name="internal-address-symbols">Internal Address Symbols</a></h3>
 
 <p>Symbols that represent an address inside the file being disassembled
@@ -889,6 +918,8 @@ code generator figure out the implementation details.</p>
   <li>.RWID - specifies the width of the accumulator and index registers
     (65816 only).  Note this doesn't change the actual width, just tells
     the assembler that the width has changed.</li>
+  <li>.DBANK - specifies what value the Data Bank Register holds
+    (65816 only).  Used when matching operands to labels.</li>
   <li>.JUNK - indicates that the data in a range of bytes is irrelevant.
     (When generating sources, this will become .FILL or .BULK
     depending on the contents of the memory region and the assembler's

SourceGen/RuntimeData/Help/tools.html

@@ -105,9 +105,10 @@ files and libraries contain unresolved references and are not supported.</p>
 execute on an Apple IIgs.  To be functional, the sources must be
 assembled by a program capable of generating OMF output, such as Merlin.</p>
 
-<p>The relocation dictionaries from the executable are included in the
+<p>The <a href="advanced.html#reloc-data">relocation dictionaries</a> from
-project file, and can be used to guide the disassembler's analysis.  The
+the executable are included in the project file, and can be used to guide
-"use reloc data" setting in the project properties controls this feature.</p>
+the disassembler's analysis.  The "use reloc data" setting in the project
+properties controls this feature.</p>
 
 <p>A full explanation of the structure of OMF is beyond the scope of this
 manual.  For more information on OMF, see Appendix F of the GS/OS Reference

SourceGen/WpfGui/EditDataBank.xaml

@@ -22,7 +22,7 @@ limitations under the License.
         xmlns:local="clr-namespace:SourceGen.WpfGui"
         xmlns:system="clr-namespace:System;assembly=mscorlib"
         mc:Ignorable="d"
-        Title="Set Data Bank"
+        Title="Edit Data Bank Register"
         SizeToContent="WidthAndHeight" ResizeMode="NoResize"
         ShowInTaskbar="False" WindowStartupLocation="CenterOwner"
         ContentRendered="Window_ContentRendered">