** @name stub.txt Description of "stub" programs.
* 
* @section Copyright (c) 2005, CD-i Fan.
* The stub programs are licensed under the GNU Library General Public License,
* version 2 or (at your option) any later version. The full terms of
* the license can be found in the file LCOPYING that you should have
* received with this file. You can also refer to the on-line version that
* can be found at http://www.fsf.org/licensing/licenses/lgpl.txt.
*
* @author CD-i Fan
*
* @version 0.5.1
*
* @history
* @rev 2005/04/01 cdifan Created

The files in this directory implement "stub" programs for various
CD-i player environments. They are, in order of increasing portability:

a605stub - stub program using CD-i 605 player 68681 UART port A (Input 3)
b605stub - stub program using CD-i 605 player 68681 UART port B (Input 4)
k70stub - stub program using 68070 processor on-chip UART (Input 2)
os9stub - stub program using OS-9 serial i/o on standard input/output
cdistub - stub program using OS-9 serial i/o on first CD-i serial port
cdi_stub - same as cdistub but named correctly for mastering a CD-i disc

The stub programs implement the "stub" protocol described in the
stubdefs.d header file. The protocol is a means to exchange control and
data information between a "stub" program and a "host" program.

The protocol allows downloading, uploading and remote execution; at
present only a limited form of remote debugging is supported.

Most Philips CD-i players support a subset of the "stub" protocol called
the download subset, consisting of just the messages needed to download
data and/or programs into the player and execute programs or continue
the player start process.

This subset can be used to download one of the full "stub" programs;
for CD-i players without a download subset implementation an actual CD-i
disc containing "cdi_stub" will have to be used. A disc image of such
a disc should also be available where you got this file; it should work on
any CD-i player with a serial port.

The first three "stub" program implementations use direct hardware
access on the specified UART port for their character i/o. They
can be used without an operating system environment but are
somewhat limited in functionality. The "k70stub" program should
work on any Philips CD-i player with an 68070 processor.

The last three "stub" program implementations use the OS-9 SCF
file manager for their character i/o; they differ in how the
path to the SCF device is opened. All of them should work
on most CD-i players with a serial port, but only the first
two are useful as boot-time downloads.

The "cdi_stub" program implementation is identical to "cdistub"
except for the internal module name; this makes it suitable for
mastering a CD-i disc (all OS-9 modules on a CD-i must have
module names starting with "cdi_").

The "cdilink" program provides the "host" part of the "stub" protocol;
a Windows executable is included (the sources will be available later).
See the file cdilink.txt for more information about this program.

To build the "stub" program binaries you need the Microware OS-9 assembler
"r68" and linker "l68"; a Makefile using these tools is provided.

But even if you don't have those tools, studying the source may be
instructive as it provides a sample of a real (albeit very small)
CD-i application.

All of the "stub" programs are built from common sources, the only
difference being the startup and i/o modules. For historical reasons,
all sources expect tabs to be set every three (3) character positions.

The stub*.s files are the sources for the stub programs; definitions
for these are in the stub*.d files.

The *stub.rsp files are response files for the linker to build the
various binaries.

The stub.dsp file is a Microsoft Visual C++ 6.0 project file that
includes all the source files for easy editing.

The Makefile contains build rules for the binaries. Some trickery with
batch files is required because there to be some kind of incompatibility
between the Cygwin version of GNU make and the Microware C compiler
for MS-DOS. See the comments in make.bat for more information.

The buildcd directory contains the source files used to make the
cdi_stub CD-i disc. The Makefile uses various tools that I am
unable to distribute at this time, sorry. The finished product
should be available from where you got this file.

The various *.txt files provide documentation.

If you have questions or suggestions, I would like to hear from you.
You can reach me via email using cdifan (at) gmail (dot) com.

