Finish support for .BANK.

git-svn-id: svn://svn.cc65.org/cc65/trunk@5384 b7a2c559-68d2-44c3-8de9-860c34a00d81

doc/ca65.sgml

@@ -1275,6 +1275,49 @@ Pseudo functions expect their arguments in parenthesis, and they have a result,
 either a string or an expression.
 
 
+<sect1><tt>.BANK</tt><label id=".BANK"><p>
+
+  The <tt/.BANK/ function is used to support systems with banked memory. The
+  argument is an expression with exactly one segment reference - usually a
+  label. The function result is the value of the <tt/bank/ attribute assigned
+  to the run memory area of the segment. Please see the linker documentation
+  for more information about memory areas and their attributes.
+
+  The value of <tt/.BANK/ can be used to switch memory so that a memory bank
+  containing specific data is available.
+
+  The <tt/bank/ attribute is a 32 bit integer and so is the result of the
+  <tt/.BANK/ function. You will have to use <tt><ref id=".LOBYTE"
+  name=".LOBYTE"></tt> or similar functions to address just part of it.
+
+  Please note that <tt/.BANK/ will always get evaluated in the link stage, so
+  an expression containing <tt/.BANK/ can never be used where a constant known
+  result is expected (for example with <tt/.RES/).
+
+  Example:
+
+  <tscreen><verb>
+        .segment "BANK1"
+        .proc   banked_func_1
+                ...
+        .endproc
+
+        .segment "BANK2"
+        .proc   banked_func_2
+                ...
+        .endproc
+
+        .proc   bank_table
+  	        .addr   banked_func_1
+                .byte   <.BANK (banked_func_1)
+
+                .addr   banked_func_2
+                .byte   <.BANK (banked_func_2)
+        .endproc
+  </verb></tscreen>
+
+
+
 <sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p>
 
   The function returns the bank byte (that is, bits 16-23) of its argument.
@@ -2229,7 +2272,7 @@ Here's a list of all control commands and a description, what they do:
   is a symbol that is already defined somewhere in the source file up to the
   current position. Otherwise the function yields false. As an example, the
   <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by
-           
+
   <tscreen><verb>
   	.if	.defined(a)
   </verb></tscreen>

doc/ld65.sgml

@@ -713,7 +713,7 @@ This will define some external symbols that may be used in your code:
         __STACK_FILEOFFS__      The binary offset in the output file. This
                                 is not defined for relocatable output file
                                 formats (o65).
-</verb></tscreen>                             
+</verb></tscreen>
 
 A memory section may also have a type. Valid types are
 
@@ -736,6 +736,13 @@ the one defined in the <ref id="FEATURES" name="FEATURES"> section, or the
 value given on the command line with the <tt><ref id="option-S" name="-S"></tt>
 option).
 
+To support systems with banked memory, a special attribute named <tt/bank/ is
+available. The attribute value is an arbitrary 32 bit integer. The assembler
+has a builtin function named <tt/.BANK/ which may be used with an argument
+that has a segment reference (for example a symbol). The result of this
+function is the value of the bank attribute for the run memory area of the
+segment.
+
 
 <sect1>Other SEGMENT attributes<p>