Serial Tube Host ================ J.G.Harston -- 23-Feb-2018 70 Camm Street, Walkley, Sheffield, S6 3TR mdfs.net/Tube/Serial TubeHost is a Serial Tube Host that uses the Serial Tube protocol to communicate with a client for filing system functions, such as with HostFS on the BBC/Master, or coprocessor client functions such as the SerialTube clients. TubeHost will run on RISC OS or Windows. TubeHost.exe is a precompiled Windows binary. You are free to implement Serial Tube Host on other platforms, and are free to use this TubeHost code as its basis. Configuration ------------- The default configuration can be overridden by a local choices file. On RISC OS: Firstly, a file 'Choices' in the same directory as TubeHost Then, a file 'Choices:JGHarston.TubeHost.Choices' On Windows: Firstly, a file 'TubeHost.ini' in the same directory as TubeHost Then, a file pointed to by the Registry key: User\Software\J.G.Harston\TubeHost\Settings The configuration file is a text file containing any of the following in any order: BAUD: DEBUG: COM: INF: MTU: PFX: RST: for instance: BAUD:19200 (defaults to 19200) DEBUG:-2 (defaults to 0) COM:1 (defaults to 1) INF:1 (defaults to 1) MTU:32K (defaults to 32K) PFX:&9B (defaults to &9B) RST:0 (defaults to 0) BAUD is the transmission speed. A BBC Client divides the serial clock by 16, so the Client speed needs to be set to the Host speed divided by 4, ie client speed 4800 with for instance *FX7,6 and *FX8,6 for host speed 19,200. DEBUG is a binary bitmap, displaying the following transactions: b0 - OSBPUT, OSBGET b1 - RDLINE, OSWORD, OSBYTE b2 - File I/O b3 - Data transfer DEBUG can be changed dynamically by a client filing system with *OPT5. COM is the serial port to use. This setting is only used on Windows, on RISC OS the on-board serial port is always used. If RST is nonzero, then when TubeHost starts up it sends a Client Reset command to the client. If INF is zero then .inf files are not created on non-RISC OS platforms. The INF setting can be selectively turned on or off by prefixing pathnames with :INF: or :NOINF:. The INF setting can be permanently set (until the host is next run) by prefixing a *DIR pathname with :INF: or :NOINF:. MTU is the maximum transmission unit, the largest block size to send and receive data in kilobytes. After each block the transmission pauses, flushes the serial buffers and resynchronises. If omitted or set to 0, data is transfered in a continuous stream. The client can use *OPT3 to change this, *OPT3,0 selects the configured MTU. PFX is the Serial Tube protocol escape character to use to embed command and data sequences in the character stream. It is normally &9B. A BBC satisfactorily works with the Host at 19,200 baud. Although the BBC can go up to 76,800, the maximum speed possible is 38,400 as Windows jumps from 38,400 to 115,200. Transmission errors start to occur with the speed at 38,400 with an infinite MTU. Reducing the MTU reduces transmission errors. An MTU of 32K has been found to be a good balance. Filing system notes ------------------- TubeHost 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 TubeHost 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 and debug 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 is currently not implemented, and Shift-Break will return Boot=Off. *OPT5 can be used to change the DEBUG setting. This can be useful if using HostFS on a BBC to see the full detail of filing system transactions. BGET#0 and BPUT#0 will read and write to OSRDCH and OSWRCH. Code with an Acorn ROM header is examined to work out its load address if there is no .inf file. Update history -------------- 06-Jul-2011 v0.10 06-Jan-2012 v0.22 v0.23 Bugfix in host OSCLI, *HELP, *GO. v0.24 Running executable files, OSCLI does not echo to the Client. 19-Aug-2012 v0.25 *LOAD, *SAVE implemented, *RUN fixed. 19-Aug-2012 v0.26 Host personality can be specified by client. v0.26a gbpb8 (directory scanning) and gbpb6 (read current directory name) implemented on Windows. v0.26b FileInfo on "$" (or a path that resolves to "$", eg "^") correctly returns type=2. 05-Nov-2016 v0.27 *Delete also deletes any .inf file, INF configurable and selectable. v0.27a Null string is a Bad filename, eg LOAD "". v0.28 File header information is read, */command and *command correctly loads files with extension, *RENAME implemented. v0.29 Data is able to be transfered in blocks, *RUN checks for files with .bin extension. *EX fully implemented. 02-Dec-2017 v0.29a COM port configurable. 06-Mar-2018 v0.29b Uses Win/BBCKBD translation, RDCH sends Escape change, *OPT5,n sets debug level, *OPT3,n sets MTU. 07-Mar-2018 v0.29c Avoids closing handles on errors that shouldn't be closed. 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.