Merge branch 'master' into ca65_long_jsr_jmp_rts

doc/ca65.sgml

@@ -125,6 +125,7 @@ Long options:
   --target sys                  Set the target system
   --verbose                     Increase verbosity
   --version                     Print the assembler version
+  --warnings-as-errors          Treat warnings as errors
 ---------------------------------------------------------------------------
 </verb></tscreen>
 
@@ -359,6 +360,13 @@ Here is a description of all the command line options:
   warning level is 1, and it would probably be silly to set it to
   something lower.
 
+
+  <label id="option--warnings-as-errors">
+  <tag><tt>--warnings-as-errors</tt></tag>
+
+  An error will be generated if any warnings were produced.
+
+
 </descrip>
 <p>
 
@@ -2019,7 +2027,7 @@ Here's a list of all control commands and a description, what they do:
 
 <sect1><tt>.A16</tt><label id=".A16"><p>
 
-  Valid only in 65816 mode. Switch the accumulator to 16 bit.
+  Valid only in 65816 mode. Assume the accumulator is 16 bit.
 
   Note: This command will not emit any code, it will tell the assembler to
   create 16 bit operands for immediate accumulator addressing mode.
@@ -2029,7 +2037,7 @@ Here's a list of all control commands and a description, what they do:
 
 <sect1><tt>.A8</tt><label id=".A8"><p>
 
-  Valid only in 65816 mode. Switch the accumulator to 8 bit.
+  Valid only in 65816 mode. Assume the accumulator is 8 bit.
 
   Note: This command will not emit any code, it will tell the assembler to
   create 8 bit operands for immediate accu addressing mode.
@@ -2112,15 +2120,15 @@ Here's a list of all control commands and a description, what they do:
   </verb></tscreen>
 
   the assembler will force a segment alignment to the least common multiple of
-  15, 18 and 251 - which is 22590. To protect the user against errors, the
-  assembler will issue a warning when the combined alignment exceeds 256. The
-  command line option <tt><ref id="option--large-alignment"
-  name="--large-alignment"></tt> will disable this warning.
+  15, 18 and 251 - which is 22590. To protect the user against errors, when the
+  combined alignment is larger than the explicitly requested alignments,
+  the assembler will issue a warning if it also exceeds 256. The command line
+  option <tt><ref id="option--large-alignment" name="--large-alignment"></tt>
+  will disable this warning.
 
-  Please note that with alignments that are a power of two (which were the
-  only alignments possible in older versions of the assembler), the problem is
-  less severe, because the least common multiple of powers to the same base is
-  always the larger one.
+  Please note that with only alignments that are a power of two, a warning will
+  never occur, because the least common multiple of powers to the same base is
+  always simply the larger one.
 
 
 
@@ -3053,7 +3061,7 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".CHARMAP" name=".CH
 
 <sect1><tt>.I16</tt><label id=".I16"><p>
 
-  Valid only in 65816 mode. Switch the index registers to 16 bit.
+  Valid only in 65816 mode. Assume the index registers are 16 bit.
 
   Note: This command will not emit any code, it will tell the assembler to
   create 16 bit operands for immediate operands.
@@ -3064,7 +3072,7 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".CHARMAP" name=".CH
 
 <sect1><tt>.I8</tt><label id=".I8"><p>
 
-  Valid only in 65816 mode. Switch the index registers to 8 bit.
+  Valid only in 65816 mode. Assume the index registers are 8 bit.
 
   Note: This command will not emit any code, it will tell the assembler to
   create 8 bit operands for immediate operands.

doc/cc65-intern.sgml

@@ -6,7 +6,8 @@
 
 <abstract>
 Internal details of cc65 code generation,
-such as calling assembly functions from C.
+such as the expected linker configuration,
+and calling assembly functions from C.
 </abstract>
 
 <!-- Table of contents -->
@@ -16,6 +17,76 @@ such as calling assembly functions from C.
 
 
 
+<sect>Linker configuration<p>
+
+The C libraries and code generation depend directly on a suitable linker configuration.
+There are premade configuration files in the <tt/cfg&sol;/ directory, normally chosen by the
+linker's selected target. These can be used as a template for customization.
+
+The C libraries depend on several special segments to be defined in your linker configuration.
+Generated code will also use some of them by default.
+Some platform libraries have additional special segments.
+
+Memory areas are free to be defined in a way that is appropriate to each platform,
+and the segments they contain are used as a layer of semantics and abstraction,
+to allow much of the reorganization to be done with the linker config,
+rather than requiring platform-specific code source changes.
+
+<sect1><tt/ZEROPAGE/ segment<p>
+
+Used by the C library and generated code for efficient internal and temporary state storage,
+also called "pseudo-registers".
+
+<sect1><tt/STARTUP/ segment<p>
+
+Used by each platform instance of the C library in <tt/crt0.s/ to contain the entry point
+of the program.
+
+The startup module will export <tt/__STARTUP__ : absolute = 1/ to force the linker to
+always include <tt/crt0.s/ from the library.
+
+<sect1><tt/CODE/ segment<p>
+
+The default segment for generated code, and most C library code will be located here.
+
+Use <tt/#pragma code-name/ to redirect generated code to another segment.
+
+<sect1><tt/BSS/ segment<p>
+
+Used for uninitialized variables.
+Originally an acronym for "Block Started by Symbol", but the meaning of this is now obscure.
+
+Use <tt/#pragma bss-name/ to redirect uninitialized variables to another segment.
+
+<sect1><tt/DATA/ segment<p>
+
+Used for initialized variables.
+
+On some platforms, this may be initialized as part of the program loading process,
+but on others it may have a separate <tt/LOAD/ and <tt/RUN/ address,
+allowing <tt/copydata/ to copy the initialization from the loaded location
+into their run destination in RAM.
+
+Use <tt/#pragma data-name/ to redirect initialized variables to another segment.
+
+<sect1><tt/RODATA/ segment<p>
+
+Used for read-only (constant) data.
+
+Use <tt/#pragma rodata-name/ to redirect constant data to another segment.
+
+<sect1><tt/FEATURES/ table<p>
+
+This currently defines table locations for the <tt/CONDES/
+constructor, destructor, and interruptor features.
+Some platform libraries use these.
+
+The constructors will be called with <tt/initlib/ at startup,
+and the destructors with <tt/donelib/ at program exit.
+Interruptors are called with <tt/callirq/.
+
+
+
 <sect>Calling assembly functions from C<p>
 
 <sect1>Calling conventions<p>

doc/index.sgml

@@ -59,7 +59,7 @@
   Contains hints on creating the most effective code with cc65.
 
   <tag><htmlurl url="cc65-intern.html" name="cc65-intern.html"></tag>
-  Describes internal details of cc65, such as calling conventions.
+  Describes internal details of cc65: linker configuration, calling conventions, etc.
 
   <tag><htmlurl url="using-make.html" name="using-make.html"></tag>
   Build programs, using the GNU Make utility.

doc/ld65.sgml

@@ -90,6 +90,7 @@ Long options:
   --start-group                 Start a library group
   --target sys                  Set the target system
   --version                     Print the linker version
+  --warnings-as-errors          Treat warnings as errors
 ---------------------------------------------------------------------------
 </verb></tscreen>
 
@@ -330,6 +331,13 @@ Here is a description of all of the command-line options:
   directory, in the list of directories specified using <tt/--obj-path/, in
   directories given by environment variables, and in a built-in default directory.
 
+
+  <label id="option--warnings-as-errors">
+  <tag><tt>--warnings-as-errors</tt></tag>
+
+  An error will be generated if any warnings were produced.
+
+
 </descrip>