Serial Tube HostFS
                            ==================
         J.G.Harston, 70 Camm Street, Walkley, Sheffield, S6 3TR
                       http://mdfs.net/Tube/Serial
                            Date: 23-Feb-2018


Serial Tube HostFS is a Host Filing System that uses the Serial Tube
protocol to communicate with a host system for filing system functions.

The filing system is selected with *HOSTFS, with the filing system prefix
-HOSTFS- or with TAB-Break. It uses filing system number &09 and file
handles &80 to &9F.

All other filing system functions and capabilities are entirely and
utterly whatever the host at the other end of the serial link provides.

The communication link uses the onboard 6850 serial port, with the clock
set to divide-by-16 instead of divide-by-64, so speeding up transfers by a
factor of 4. Consequently, the host system's serial port speed must be set
to four times that of the BBC. For instance, with the BBC set to 4800 baud
with *FX7,6 and *FX8,6 (or *Configure Baud 6), transfers will actually
occur at 19,200 baud, and the host must be set to that same speed.

HostFS has been tested with TubeHost running on Windows and RISC OS at
19,200 baud (with the BBC set nominally to 4800 baud) with fewer than one
error in 60M of data transfered. Transfers at 38,400 baud (with the BBC
nominally at 9600 baud) have resulted in at least one error in every 5K of
data transfered, but with no dropped bytes - only corrupted bytes.

The transfer speed could theoretically be set to 76,800 baud by setting
the BBC to a nominal speed of 19,200 baud (*FX7,8 and *FX8,8), but 76,800
baud is not a normally available baud rate on other computer systems.

Filing system notes
-------------------
All filing system functionality is defined by and provided by the Host at
the other end of the serial connection.

The Host presents the host filing system to the client with the filing
system environment (pathname characters, etc.) translated to the client
system. So, A BBC talking to a Serial Tube Host running on Windows will
see the Windows filing system presented with '.' directory seperators and
'/' extension seperators.

On non-RISC OS systems .inf files can be used to store Acorn metadata -
load and execution address. Prefixing a filename with :INF: or :NOINF:
will temporarily enable or disable the creation of .inf files. Using :INF:
or :NOINF: with a *DIR command will enable or disable .inf files from that
point on.

*OPT0 reselects the default MTU (*OPT3) and debug (*OPT5) options.

*OPT3 selects the transmission block size in multiples of 1024 bytes.
*OPT3,0 selects the default or configured MTU, *OPT3,255 selects unlimited
blocks.

*OPT4 will set the boot option if the Host supports it. This is actioned
on Shift-Break and is returned by OSGBPB 5.

*OPT5 can be used to change the DEBUG setting. This can be useful to see
the full detail of filing system transactions.

If the Host supports it, BGET#0 and BPUT#0 will read and write to OSRDCH
and OSWRCH.

The Host will examine code with an Acorn ROM header to work out its load
address if there is no file metadata.

History
-------
09-Apr-1995 v0.10 Z80 Serial Tube client written.
15-May-1995 v0.10 6502 Serial Tube client written.
22-Oct-1995 v0.11 HostFS filing system written using Serial Tube client.
16-Nov-2010 v0.12 Tube transfer and screen memory access added.
10-Jul-2011 v0.13 Sets serial port to baud*4.
13-Jan-2012 v0.14 Sends a Soft Reset when using single communication port.
16-Jan-2012 v0.15 Pauses after an error to let Host resync.
09-Mar-2013 v0.16 *RUN, etc. correctly returns to calling code, was
                  previously using contents of A from called code as Tube
                  status code. CLOSE#0 asks MOS to close EXEC and SPOOL.
12-Mar-2013 v0.17 Added more Tube entry points to Tube Client.
                  EXECUTE enters code with A=0/1, SEC/CLC.
07-Apr-2013 v0.18 Moved some code that overlapped I/O area.
11-Nov-2016 v0.19 Added conditionals for sideways ROM code.
18-Mar-2017 v0.20 Added option for local RDLINE, optimised OSCLI.
23-Feb-2018 v0.21 Fixed *HOSTFS ON setting WRCHV/RDCHV. Serv3 responds to
                  returned boot option.

Bugs
----
Host: Quoted filenames with spaces aren't scanned correctly, eg *LOAD "A B"
      fails as it is scanned as *LOAD "A giving a Bad string error.