From e767c8990d07003d9c91a6151cc61f0ea28639ea Mon Sep 17 00:00:00 2001
From: Daniel Serpell <daniel.serpell@gmail.com>
Date: Sat, 1 Dec 2018 21:45:22 -0300
Subject: [PATCH] Adds documentation and a sample config file for the ATARI
 format.

---
 cfg/atari-xex.cfg | 24 ++++++++++++++++++++++++
 doc/atari.sgml    | 12 ++++++++++++
 doc/ld65.sgml     | 26 ++++++++++++++++++++++++--
 3 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 cfg/atari-xex.cfg

diff --git a/cfg/atari-xex.cfg b/cfg/atari-xex.cfg
new file mode 100644
index 000000000..f0a6291db
--- /dev/null
+++ b/cfg/atari-xex.cfg
@@ -0,0 +1,24 @@
+FEATURES {
+    STARTADDRESS: default = $2E00;
+}
+SYMBOLS {
+    __STARTADDRESS__: type = export, value = %S;
+}
+MEMORY {
+    ZP:      file = "", define = yes, start = $0082, size = $007E;
+    MAIN:    file = %O, define = yes, start = %S,    size = $BC20 - %S;
+}
+FILES {
+    %O: format = atari;
+}
+FORMATS {
+    atari: runad = start;
+}
+SEGMENTS {
+    ZEROPAGE: load = ZP,      type = zp,  optional = yes;
+    EXTZP:    load = ZP,      type = zp,  optional = yes; # to enable modules to be able to link to C and assembler programs
+    CODE:     load = MAIN,    type = rw,                  define = yes;
+    RODATA:   load = MAIN,    type = ro   optional = yes;
+    DATA:     load = MAIN,    type = rw   optional = yes;
+    BSS:      load = MAIN,    type = bss, optional = yes, define = yes;
+}
diff --git a/doc/atari.sgml b/doc/atari.sgml
index 80293d82f..346377b36 100644
--- a/doc/atari.sgml
+++ b/doc/atari.sgml
@@ -203,6 +203,18 @@ is <it/left out/, keep this in mind.
 The values you assign to the two symbols <tt/__AUTOSTART__/ and <tt/__EXEHDR__/
 don't matter.
 
+<sect2><tt/atari-xex.cfg/<p>
+
+This config file allows writing multi segment binaries easily, without having to
+write the header explicitly on each segment.
+
+It is similar to the <tt/atari-asm.cfg/ above, but uses the ATARI (xex) file
+format support on LD65 instead of the standard binary output, so it does not
+have the <tt/__AUTOSTART/ nor the <tt/__EXEHDR__/ symbols.
+
+Note that each <tt/MEMORY/ area in the configuration file will have it's own
+segment in the output file with the correct headers.
+
 <sect2><tt/atari-cart.cfg/<p>
 
 This config file can be used to create 8K or 16K cartridges. It's suited both
diff --git a/doc/ld65.sgml b/doc/ld65.sgml
index beb2144bf..0230b517f 100644
--- a/doc/ld65.sgml
+++ b/doc/ld65.sgml
@@ -894,7 +894,7 @@ look like this:
         }
 </verb></tscreen>
 
-The only other available output format is the o65 format specified by Andre
+There are two other available formats, one is the o65 format specified by Andre
 Fachat (see the <url url="http://www.6502.org/users/andre/o65/fileformat.html"
 name="6502 binary relocation format specification">). It is defined like this:
 
@@ -904,7 +904,20 @@ name="6502 binary relocation format specification">). It is defined like this:
         }
 </verb></tscreen>
 
-The necessary o65 attributes are defined in a special section labeled
+The other format available is the Atari (xex) segmented file format, this is
+the standard format used by Atari DOS 2.0 and upward file managers in the Atari
+8-bit computers, and it is defined like this:
+
+<tscreen><verb>
+        FILES {
+            %O: format = atari;
+        }
+</verb></tscreen>
+
+In the Atari segmented file format, the linker will write each <tt/MEMORY/ area
+as a new segment, including a header with the start and end address.
+
+The necessary o65 or Atari attributes are defined in a special section labeled
 <ref id="FORMAT" name="FORMAT">.
 
 
@@ -925,6 +938,15 @@ has several attributes that may be defined here.
     }
 </verb></tscreen>
 
+The Atari file format has only one attribute, <tt/RUNAD/ that allows to specify
+a symbol as the run address of the binary. If the attribute is omiteed, no run
+address is specified.
+
+<tscreen><verb>
+    FORMATS {
+        atari: runad = _start;
+    }
+</verb></tscreen>
 
 
 <sect1>The FEATURES section<label id="FEATURES"><p>
-- 
2.39.2