Update doc (how telestrat works), tgi_outtext doc added

diff --git a/doc/telestrat.sgml b/doc/telestrat.sgml
index fe9efcfdb73a10fb2fb22797000cb306fb1cd6dd..97229db00beb94b24114175505936e978424bcb3 100644 (file)
--- a/doc/telestrat.sgml
+++ b/doc/telestrat.sgml
@@ -16,9 +16,9 @@ An overview over the Telestrat (Telemon 2.4 & Telemon 3.x : http://orix.oric.org
 
 <sect>Overview<p>
 
-This file contains an overview of the Telestrat runtime system as it comes with the
-cc65 C compiler. It describes the memory layout, Telestrat-specific header files,
-available drivers, and any pitfalls specific to that platform.
+This file contains an overview of the Telestrat runtime system as it comes 
+with the cc65 C compiler. It describes the memory layout, Telestrat-specific 
+header files, available drivers, and any pitfalls specific to that platform.
 
 Please note that Telestrat-specific functions are just mentioned here, they are
 described in detail in the separate <url url="funcref.html" name="function
@@ -26,17 +26,56 @@ reference">. Even functions marked as "platform dependent" may be available on
 more than one platform. Please see the function reference for more
 information.
 
+Oric Telestrat is the last Oric computer (Released in 1986, mainly in France).
+This computer is an Atmos with extra hardware : RS232, cardridge (banking system),
+joysticks (2 ports) or mouse (on joystick port), FDC.
+
+Video chip, CPU, keyboard management, tape hardware are the same than Atmos.
+
+Telestrat can start in Atmos mode with Atmos Cardridge (which is only the atmos 
+Basic 1.1 ROM). 
+
+Telestrat can start in Sedoric (Atmos OS) and Atmos mode with Stratoric Cardridge.
+This Cardridge is a Sedoric ROM, Basic 1.1 ROM (Atmos), Basic 1.0 ROM (Oric-1).
+
+The main Telestrat's configuration is the Telemon/Hyperbasic Cardridge inserted 
+with Stratsed in floppy drive.
+
+Anyway, there is no way to load a tape file in Telemon/Hyperbasic mode without 
+alternative program.
+
+There is also no software to write a Stratsed dsk file on PC.
+
+This Telestrat target build an Orix binary file. But, in the future, it will be possible 
+to build a Stratsed disk. Orix uses the same systems calls than Telemon mode.
+
+That is why if you need to do software for telestrat target, you have the choice to :
+<itemize>
+<item>use cc65 Atmos target and start Telestrat in Atmos mode : a tape file is required
+<item>use cc65 Atmos target and start Telestrat in Stratoric mode : a dsk file or tape file is required
+<item>use cc65 Telestrat target and start Telestrat in Orix mode (see <url
+name="here" url="http://orix.oric.org/download/">)
+<item>use cc65 Telestrat target, remove Orix header from binary, code a dsk tool for Stratsed, 
+add Stratsed header on your binary, insert your binary on floppy disk (this solution will be possible is the future)
+</itemize>
+
+Telestrat (from cardridge) can handle 8 banks (from $C000 to $FFFF): Bank 0 is the overlay ram. Others banks can be ROM or RAM.
+
 <sect>Binary format<p>
 
 The standard binary output format generated the linker for the Telestrat
 target is a machine language program with a 20 bytes header described <url
-name="here" url="http://orix.oric.org/doku.php?id=orix:header">
+name="here" url="http://orix.oric.org/orix-header/">
 
 This header is used for Telemon 3.0.
 
-Anyway, for Telemon 2.4, there is no file management, there is no TAPE routine in Telemon, there is no way to load a binary easily.
+Anyway, for Telemon 2.4, there is no file management, there is no TAPE routine 
+in Telemon, there is no way to load a binary easily.
 
-Stratsed (the Telestrat operating system) handles files management. Stratsed is loaded to memory from floppy disk.
+Stratsed (the Telestrat operating system) handles files management. Stratsed 
+is loaded to memory from floppy disk. Stratsed vector are declared in asminc/telestrat.inc.
+But, reverse engineering is required to find how theses vectors works. Please, note that 
+Stratsed is located in overlay memory (bank 0)
 
 There is no tool to insert a binary in a Stratsed floppy disk.
 
@@ -44,7 +83,9 @@ The only way to load a binary (for Telemon 2.4) is to:
 <itemize>
 <item>remove the 20 bytes header
 <item>download <url name="osdk" url="http://osdk.defence-force.org/index?page=download">
-<item>use Floppybuilder in OSDK to insert the binary with the tool (please read FloppyBuilder manual to insert your binary, and to start microdisc boot sector when Telestrat starts)
+<item>use Floppybuilder in OSDK to insert the binary with the tool (please read 
+FloppyBuilder manual to insert your binary, and to start microdisc boot sector 
+when Telestrat starts)
 </itemize>
 
 Please note also, that the binary converted into TAP file, will not produce
@@ -58,7 +99,7 @@ If you know the Stratsed disk format, please contact the author of this doc.
 
 In the standard setup, cc65-generated programs use the memory from
 &dollar;0801 to &dollar;9800; so, nearly 37K of memory (including the stack) is
-available. ROM calls are possible without further precautions.
+available. ROM calls are possible with BRK feature.
 
 
 Special locations:
@@ -109,6 +150,22 @@ structures; accessing the struct fields will access the chip registers.
 
 </descrip><p>
 
+<descrip>
+
+  <tag><tt/VIA2/</tag>
+  Access to the VIA2 (Versatile Interface Adapter) chip is available via the
+  <tt/VIA2/ variable. The structure behind this variable is explained in <tt/_6522.h/.
+
+</descrip><p>
+
+<descrip>
+
+  <tag><tt/6551/</tag>
+  Access to the 6551 ACIA chip is available via the
+  <tt/6551/ variable. The structure behind this variable is explained in <tt/_6551.h/.
+
+</descrip><p>
+
 
 <sect>Loadable drivers<p>
 
@@ -117,25 +174,31 @@ structures; accessing the struct fields will access the chip registers.
 TGI drivers is available on Oric Telestrat with some functions :
 
 <itemize>
+<item>tgi_clear
 <item>tgi_done
-<item>tgi_install
 <item>tgi_init
-<item>tgi_clear
+<item>tgi_install
 <item>tgi_line
+<item>tgi_outtext
 <item>tgi_setpixel
 </itemize>
 
 
 <sect1>Extended memory drivers<p>
 
-No extended memory drivers are currently available for the Telestrat.
-
+No extended memory drivers are currently available for the Telestrat. 
+This feature could be done because telestrat can manage RAM inserted in his 
+port cardridge. 
 
 <sect1>Joystick drivers<p>
 
 <descrip>
 
-telemon 2.4 & 3.0 manages joysticks but it had been handled yet.
+Telemon 2.4 & 3.0 manages joysticks but it had been handled yet. This means that 
+joysticks driver could be written easily.
+
+Telemon 2.4 returns in keyboard buffer the direction of the joysticks. This means that
+if you get input from keyboard by conio cgetc function, you will get direction from joysticks.
 
 </descrip>
 
@@ -144,7 +207,8 @@ telemon 2.4 & 3.0 manages joysticks but it had been handled yet.
 
 <descrip>
 
-Telestrat manages also mouse, but it had been no handled yet in this version.
+Telestrat manages also mouse, but it had been no handled yet in this version. 
+Telestrat mouse is really difficult to find.
 
 </descrip>
 
@@ -152,7 +216,8 @@ Telestrat manages also mouse, but it had been no handled yet in this version.
 
 <descrip>
 
-Telestrat has a RS232 port, but it's not usable in cc65.
+Telestrat has a RS232 port, but it's not usable in cc65. It is possible to use 
+RS232 port with Telemon calls (see XSOUT primitive for example)
 
 </descrip>