TitaniK (Titanium Kernel) 0.12 by Kevin Kofler
==============================================

This is a fork of Patrick Plissier's PreOs which targets the TI-89 Titanium
WITHOUT any patches (HW2Patch or the like). It is NOT a TSR, but a launcher. It
also adds code to (temporary copies of) the programs it executes, so it won't
work for programs which are excessively close to the file size limit (more than
56 KB in this implementation).

Usage: titanik("yourprog")

See PreOs.txt for details about PreOs.

List of known unsupported PreOs features in TitaniK:
* Support for non-Titanium calculators
* Everything requiring a TSR: SHIFT+ON support, AMS error intercepting,
  automatic nostub crash protection, ...
* Crash protection
* Passing command-line parameters to the programs.
* Running _nostub programs through kernel::exec.
* Programs >56 KB.
* Programs/libraries which would require >8 KB of stubs/callers/receivers.
* Programs which require all the RAM. (The stubs take away part of it.)
* Programs which require all the stack. (The stubs need lots of it.)
* The (un)reloc(2) functions won't work if you don't reserve enough room for the
  stubs at the end of the handle (NOT counted in the file size).
* Read-only libraries. (The relocation code adds at least a receiver to all
  libraries. For read-only libraries to work, this has to be skipped for them.)
* Indirect function calls to libraries or to RAM_CALLs.
* Nonstandard or excessive (>60 bytes) stack parameters to libraries or
  RAM_CALLs.
* Archive packs. (Uncompressed files need to be copied to add the stubs,
  compressed ones need TitaniK to call the uncompressor through a receiver.)
* Custom interrupt handlers that survive over a libcall or return-from-lib.
  Anything using interrupt handlers needs to be ported to use the graphlib hack.
* Programs relying on libcalls keeping the keyboard mask instact. (Could be
  fixed by saving/restoring it in the stubs.)

List of programs supposed to work with TitaniK:
* Patched version of SMQ

List of programs known to work with TitaniK:
(empty)


Technical:

All non-internal function calls (including the call to _main in kernel::exec)
have to go through a client-side stub, a client-side caller and a server-side
receiver. The stubs look like:
 pea [target]
 pea [server_receiver]
 pea [server_base]
 bra caller
The callers and receivers are copied from stubs.h.

Unlike PreOs, kernel::exec calls kernel programs through a direct call to
kernel::start_kernel_prgm, not through a stub call to $34.

The problem is that library references and RAM_CALLs can be to both variables
and functions. TitaniK uses a simple (improvable) heuristic to detect function
calls: a jsr or jmp is a function call, everything else is a variable reference.

Interrupt handlers are even more annoying: they can move the control flow from
one file to another completely unpredictably. We need to update the interrupt
vectors whenever the control changes from one file to another, and route them
through the caller/receiver mechanism.


History:
0.10  Kevin Kofler  2004-02-14
* First release. Forked from PreOs 0.67. All files modified.
0.11  Kevin Kofler  2004-04-07
* Changed version number identifier from $FF00 to $0011 (PreOs.asm).
* Updated graphlib and userlib with a hack to make interrupt handlers work.
0.12  Kevin Kofler  2004-04-11
* Updated version number identifier (PreOs.asm).
* Using ROM_CALL instead of hack to get tios::Heap (PreOs.asm). Use another hack
  to put it into an address which fits in a word (!"$%&/()=? SMQ ...).
* Removed the error frame saving/restoring hack (Preos.asm, exec.asm). Using
  ER_success instead.