                                                                        ..
                                                                    .......
     _________________                                          ...........
     PPPPPPPPPPPPPPPPPPPPP=.%                               ................
     |PPPPPPPPPPPPPPPPPPPPPPPP.#.                       ....................  ______
     |PPPPPPPPPPPPPPPPPPPPPPPPPP.#.                 ......................_.OOOOOOOOOO._
     PPPPPPPP/######PPPPPPPPPPP.#.            ......................_.OOOOOOOOOOOOOOOO%#.
     'PPPPPPPP|##       PPPPPPPPP##        .........................OOOOOOOOOOOOOOOOOOOOO#%
      PPPPPPPP|##        "PPPPPPPP|#|   ...........................OOOOOOOOOOO%###%OOOOOOOO##.
      PPPPPPPP|##         PPPPPPPPP##............................OOOOOOOOOO"##"     '"OOOOOO|#.
      PPPPPPPP|##         "PPPPPPPP##...........................OOOOOOOOO"##...       'OOOOOO##
      PPPPPPPP|##          PPPPPPPP##..........................OOOOOOOOO"#......       "OOOOO|#.
      PPPPPPPP|##        ..PPPPPPPP r|......___...............|OOOOOOOO##.......        OOOOOO##
      PPPPPPPP|##    .....PPPPPPPPP r|## .rrrrrrr.#..____.....OOOOOOOO|#.........       'OOOOO##__
      PPPPPPPP|## ........PPPPPPPP'rr|#rrrrrrrrrrr eeeeeeeee.#OOOOOOOO##.........       _.%%SSSSSSSSSS'
      PPPPPPPP|##     ../PPPPPPPPP rr.rrrrrrrrrrrrr eeeeeeeeeee.OOOOOO##.......... _.SSSSSSSSSSSSSSS'##
      PPPPPPPP\##  _.=PPPPPPPPPPP'rrrrrrrrrrrrrrrr eeeeeeeeeeeeee.OOOO##..........SSSSSSSSSSSSSSSSS'##
      PPPPPPPPPPPPPPPPPPPPPPPPP'rrrrrrrr"##'"rrrr ee"'#####"eeeee.OOO|#........SSSSSSSSSSSSSSSSSS'##
      PPPPPPPPPPPPPPPPPPPPPP"|rrrrrrrr"##...| r eeeeeer#.__  eeeeee.OOO##......SSSSSSSSS"OOOO#######
      PPPPPPPPPPPPPPPPP""####rrrrrrrr"##....eeeeeeeeeeeeeeeeeeeeeeee OO.#.....SSSSSSSS'OOOOO|##"
      PPPPPPPP#"########"'  |rrrrrrr'##   .eeeeeeeeeeeeeeeeeeeeeeeee OOO.##...SSSSSSS|OOOOOO##'
      PPPPPPPP|##          rrrrrrr|##     eeeee"#######%eeeeeeeeeee OOOOO.##.SSSSS|OOOOOOO'##.
     .PPPPPPPP|##          |rrrrrrr'#      eeeee|##...""########OOOOOOOOOOOOO#.S|OOOOOOOOO|SS%##.
     |PPPPPPPP|##          rrrrrrrr##      eeeeee.##  ...........OOOOOOOOOOOOOOOOOOOOOOOO|SSSSS%##.
     |PPPPPPPPP##         |rrrrrrr|#       'eeeeeee.##.__ .........'"OOOOOOOOOOOOOOOOOO"'SSSSSSSS##
     |PPPPPPPPP##         rrrrrrrr'#        "eeeeeeeeeeeeeeeeeeeee.....'"OOOOOOOOOOO"'.   "SSSSSS|#|
     PPPPPPPPPP.##       |rrrrrrrr##          eeeeeeeeeeeeeeeeeee'##........SS. __.....    |SSSSS|#|
     PPPPPPPPPP|##       rrrrrrrrr##           ''"eeeeeeeeeeee"'##     ....SSSSSS\##...._.SSSSSSS##
     PPPPPPPPPPP##      |rrrrrrrrr##              __""#########"         .SSSSSSSSSSSSSSSSSSSSSS'#|
     PPPPPPPPPPP##      rrrrrr"'  __...########################.._   'SSSSSSSSSSSSSSSSSSSS'#'
     PPPPPPPPPPP.##    |rr"' _.########################################._ "SSSSSSSSSSSSSSSS'##'
     PPPPPPPPPPP|##      ###################################################._'"SSSSSSSS"###"
    .PPPPPPPPPPPP##   .#########################@@%=""''""=%@@@###############.########"
    |PPPPPPPPPPPP.##.###################%""''            ''""%############.
    |PPPPPPPPPPPP|.################%"'___          _____      _   _'"#########.
    PPPPPPPPPPPPPP.%############"'   ###\\        #####\\    #|   #|      '"########.
      ##''"%%%%%%%%###########"       #|_#| _  _   #|   #|    #|   #|    _      '"#####\.
      .#####################"          ###\\#| #|   #|   #|    #|___#|   #|          '"####.
     #####################"            #|_#|#|_#|   #####/ ___ ######|   #|              '"##%
      "#################"              ###/ ###|   #|    ###\\#|   #| ###|                  "##.
      "#############"                      __#|   #|    #| #|#|   #|#|_#|_                    ".
        "##########                       ###/    #'    ###/ #'   #' ##'#'                      '_
          "######"                                      #|
            "###                                        #'
              "             
                
                                      Logo by SBibi






       Title: PreOs
     Version: 0.62
 Platform(s): TI-89, TI-92+, V200
      Author: PpHd (and some routines by Kevin Kofler)
    Web Site: http://www.timetoteam.fr.st
      E-Mail: ppelissi@caramail.com
Release Date: 2002/09/15

--------------
I-Introduction
--------------

	PreOS is a kernel extender which allows the execution of assembly kernel programs on your TI 89 or TI 92 Plus. It actually extends the built-in assembly support which is very poor (It just does some relocation...).
	This version of PreOS is compatible with DoorsOs, UniOs and TeOs. It is a complete re-write of the sources of TeOs (Well, 99% of the source have changed...). I intend to make it as stable as I can, but it is very hard without a MMU...

	This program uses and includes the TI-89/92+/V200 Hardware 2.00 AMS 2.0x TSR support v.1.11 by Kevin Kofler in its installation routine. See h220xtsr.txt for details about it.
	
----------------
II. INSTALLATION
----------------

	+ Send Preos.89z / stdlib.89z / shrnklib.89z (or .9xz files) to your calculator.
	(You can send preos-tictex instead of preos if you want that tictEx is your default shell - See http://tict.ticalc.org for info about tictex).
	+ Archive these files in 'main' or 'system folder.
	+ Press 'Preos()' to install it. If a kernel is already installed, PreOs won't do anything (Even an outdate version of preos). You should uninstall it before (Does a reset).
	+ PreOs will save a lot of information about the calc, check if the libraries are outdated, install a crash handler and install itself as a TSR (Terminate Stay Resident).
	+ Install now all your TSR
	+ You have to reinstall it as soon as you reset your calc (run 'preos()').

	+ You can browse your calculator and run asm programs by pressing SHIFT+ON.
	
--------------------
III. UNINSTALLATION
--------------------

	The uninstall program can only uninstall Preos.
	It will restore the Vector table, and will free the allocated handle for the TSR.
	WARNING: If you have installed TSR which use others vectors in the vector table than the traps, either they won't work anymore (and you will lose some memory), either your calculator will crash. You should be able to uninstall Preos without uninstalling Hw2Tsr.
	WARNING: Use uninst programs from the same version as the installed one !
	Well, another way and the best way, if you want to uninstall PreOs, is to do a real reset. It is clear, and you will have a very stable calculator.
	
----------
IV. F.A.Q.
----------

YOU:	I am an expert and I want a personnal version of Preos !
ME:	Ok, no problem ! Just download Preos Developper Release and extract it.
	Go to src folder, and open preos.asm in a text editor (notepad, emacs, ...).
	Select the different options you want.
	Create the program in a DOS command by :
		tigcc preos.asm hw2tsr\h220xtsr.a
	Or if you don't want an h220xtsr version, you can use :
		a68k -g -t preos.asm
		makeprgm preos

YOU:	Where are the libraries ?
ME:	Libraries (exept shrnklib) are packed and compressed in one file : 'stdlib'.
	This Pack Archive contains :
		+ Preos Browser (It will run it when you run the Pack Archive).
		+ filelib/genlib/genalib/genclib/graphlib/userlib/ziplib /pk92lib/brwselib/ugplib /fargray/gray4lib/gray7lib/util/triglib/linelib/hufflib/hexlib.

	So you don't need to have theses libraries anymore.
	
YOU:	I want to change of Shell !
ME:	No problem !
	If your new shell is :
		+ a kernel program :
			- Rename your new shell to 'shell'
		+ a nostub program :
			- Send Preos-tictex instead of preos.
			- Rename your shell to 'tictex' and it should be in the 'main' folder.

YOU:	It says 'Wrong library version', and I have sent the newest version of 'stdlib'.
ME:	Check if you don't have old versions of the libraries in your VAT.
	Preos won't look inside Pack Archives if he found a non-compressed library with the same name.
	
YOU:	Preos says 'Extracting' every time but I don't call a compressed program !
ME:	Yes. But the libraries are compressed !
	So it needs to uncompress them before running it.
	Moreover, Preos Browser will free the used libraries during the running of a program. So if you call a program under it, when you return to it, you'll see 'Extracting' again : it extracts the libaries (again) to allow browing.

YOU:	I didn't see any error message when I press SHIFT+On and it won't work.
	Or, it says lib 'xxxlib' is needed but I have it !
ME:	As you will see in the 'bugs list', Preos lost sometimes the error message...
	99% you'll have theses messages if you don't have the MOST recent version
	of shrnklib (or the used compressing library).

YOU:	Does preos still delete home entry handles for kernel programs?
ME:	Yes, but you can avoid this by calling kernel::HdKeep.

If your TI89 freezes, press 2nd - Right - Left - ON to reset it.
If this doesn't work remove the 4 batteries + the Lithium battery
	
If your TI92+ freezes, press 2nd - Lock - ON to reset it.
If this doesn't work remove the 4 batteries + the Lithium battery

----------------------
V: Using Preos Browser
----------------------

	It is a tiny launcher of ASM programs. It supports nostub / kernel programs. It doesn't support PPG programs. You can run it by pressing SHIFT+ON or by running it directly from home ('stdlib()'). If a program you attempt to execute fails, Preos Browser will display an error. You may bypass the shell by launching programs directly from TI-BASIC.

	When you start Preos Browser, it displays a menu of the folders on your TI-92+/Ti-89/V200. There are two modes of operation; one is the folder view, which is the default upon startup, and the second is the program view.
	The main (and only) advantage of Preos Browser compared to doors/enstein/pct/tictex/... is that is is VERY small : when you run a program from this browser, only 298 bytes of RAM are used by the browser ! 
	Use the following keys to navigate through Preos Browser:

	 [Up]         - move cursor up
	 [Down]       - move cursor down
	 [2nd] [Up]   - page up
	 [2nd] [Down] - page down
	 [ENTER]      - execute program / enter folder
	 [ESC]        - quit



-----------
VI. FEATURES
-----------

	- Runs on TI 89, TI 92 Plus & V200.
	- Runs on all known AMS version (1.00, 1.01, 1.05, 2.01, 2.03, 2.04, 2.05, 2.07 & 2.08).
	- Runs on hardware version 1, 2 (& 3 ?).
	- Uses either HW2Patch or HW2Tsr on not HW1 calcs.
	- "Kernel format" relocations : ROM_CALLS, RAM_CALLS, EXTRA_RAM_CALLS, RELOCATION, BSS, DYNAMIC LIBRARIES.
	- Anti Crash protection for nostub and kernel programs (even if the kernel programs have a real better protection) -protected exit mode-.
	- If the Kernel AntiCrash failed (It could), it will use the nostub Anti-Crash. There are 3 ways that the kernel protection failed : if the windows list is corrupted (Nostub protection works), if the Error frame is corrupted (Nostub protection works) and finaly if the handle table or the VAT is corrupted (Nostub protection doesn't work).
	- Terminate all programs at any time with [ESC]+[ON] (Nostub or Kernel programs).
	- Uses ON + ESC at any time to have an Hot-Reset : you will restart your calc, without losing your files. But you will lose some memory (~200b). If the Window List is corrupted, Preos may fail to recover some memory (But it should not crash).
	- [SHIFT] + ON calls 'shell' program as soon as tios::idle is called. It will save the screen into a handle (You need 4Kb more than if you run it under the home entry, but you can interrupt some quite long calcul !)
	- You can even call 'ticTex' with SHIFT+ON !
	- Can detect if the ROM or the kernel is outdated.
	- Archived Library support (temp copied).
	- An unused library is freed as soon as you don't need it
	- The libraries have now an internal version number so that a program won't run if the library is outdated (With other Kernels, it just checks if the required function exists in the library . But PreOs checks if the internal version number is greater than the required version of the library, mentionned by the program). The new libraries with a version number are still compatible with other Kernels.
	- Rewriten versions of the standard libs.
	- Support of compressed libraries.
	- Support of auto extratible Pack Archive.
	- Support of auto-run kernel programs (kernel programs can install the kernel before running).
	- Breaks the software program size limit imposed on AMS 2.0x calculators.
	- Automatically frees unused blocs of memory for kernel programs.
	- Auto clean-up of all the relocated kernel programs before exiting.
	- Fix Crash Bug when you change your batteries on HW2 if no Hw2Tsr (By JM) : that is to say, trap #4 in an asm program (RAM) won't crash anymore on HW2 if you change the batteries.
	- 92+ emulation on V200 : if the program is not designed to run on V200, Preos will tell to the program that it is a 92+, instead of a V200. Of course, if the program is designed to work on V200 (Bit 5 set), then Preos tells to it that it is a V200 ! It allows some programs (Txtrider for example) to run fine on V200.

	- Under Kernel programs, all the vectors and EV_hook are restored like the ports $600010 and $600017.
	- Don't save the screen, but redraw it (You gain 4Kb of memory !) exept if you run it with SHIFT+ON (Save_screen flag doesn't work also under SHIFT+ON call).
	- A kernel program cannot be recalled 255 times (It should never happen).
	- Check if the stub of a program is valid !
	- Support for BSS blocks (for programmers).
	- Virtual Ti is detected as an HW1.
	- Supports for HW_VERSION, & EMULATOR RAM_CALLS.
	- Supports programs which return expressions to the TIOS / RetValue works (Exept with nostub launchers : RetVal is disabled, since PreOs can't fix the return address).
	- ROM_THROW support on AMS < 2.04, and ROM_THROW support even in supervisor mode on all AMS (AMS 2.05 doesn't support ROM_THROW under Supervisor mode).
	- No more 'Illegal Program Reference'.
	- ER_throw works fine.
	- As small as possible / the most complete kernel you can found (in 2002 june) :)
	- Don't use tios::EV_hook, so it is 95% compatible with TSR (See below for the 5%) (But saves it like an auto-int).
	- New MakePrgm :
		+ MiStub programs (Mix between nostub and kernel programs)
		+ Libs Versions
		+ Small Stub
		+ Fix a bugs in the calcul of the offset in case of ExtraRamCalls
		+ Better error messages
		+ _readonly / _debug / _donotsavescreen
		+ install_preos
	- Create a saved copy of the new auto-ints and EV_hook each time preos is called : if you have installed a TSR which changes the auto-ints, you should run preos after so that PreOs reload a new right configuration of the auto-ints and EV_hook (It will restore them when nostub programs crash).
	- Install its own vectors :
		+ Address Error
		+ Illegal Instruction
		+ Divide By Zero
		+ CHK Instruction
		+ TRAPV Instruction
		+ Privilege Violation
		+ Auto Int 6
		+ Line 1111 Emulator
		+ Line 1010 Emulator
	Spurius Error and Bus Error are NOT intercepted since they are very important (If such a vectors occurs, it means that your calc has a very dangerous bug).
	The Line 1111 Emulator vector is a VERY important vector for Preos. It won't allow that another program, like a TSR, changes it.
	- Add 11 usefull RAM_CALLS :
		+ kernel::exec
		+ kernel::Ptr2Hd
		+ kernel::Hd2Sym
		+ kernel::LibsBegin
		+ kernel::LibsEnd
		+ kernel::LibsCall
		+ kernel::LibsPtr
		+ kernel::LibsExec
		+ kernel::HdKeep
		+ kernel::ExtractFromPack
		+ kernel::ExtractFile
	- Add 8 new RAM_CALLS to improve compatibility.
	- (un)reloc(2) are installed : ProSit will work ;)
	- Save_Screen flag is supported !
	- Read_Only flag is supported !
	- The userlib::exec function supports zipped programs : it uses conditionnal libs so that, if it isn't a zipped program, you don't need ziplib. But it is useless, since even 'Doors explorer' doesn't use this feature (It uncompresses the program by itself). kernel::exec and util::exec don't support zipped programs.
	- The original contrast value is restored in case of a crash (Nostub or kernel).
	- ROM_THROW supports special value $FFF0 (Long jsr offset) and $FFF2 (Word RomThrow)
	- Restore original AMS auto-int in case saved auto-ints are corrupted.
	- much more, of course :)


IT DOESN'T DO :
---------------

	+ It doesn't copy the program each time you want to run it, so it is less stable than UniOs (In my opinion).
	+ Doe not intercept the reset vector (Use UniOs if you want it).
	+ kernel::Idle does nothing under Vti (Use UniOs if you want it).
	+ The uninstall program may uninstall other TSR since it just copies the original vector tables (exept the traps).
	+ userlib::KbdMgr is not defined :(
	+ It assumes than the stack address is < 32Ko for the first kernel call. (It works fine, exepct under multi-tasking nostub program).
	+ The current version of userlib doesn't work on AMS 1.00 (Ti-92+)
	+ If you do SHIFT+ON with a nostub program (renamed tictex) which crashes, you will have a Hot-Reset, and you will lose about 4Kb of memory (because it doesn't recover the LCD save).
	+ If you do SHIFT+ON with very few memory (~5K) and if the Expression Stack should be resized by 1 more and it can't, a Hot Reset will occurs (and you will lose 4Kb) (I think this case is very unprobably).

----------
VII-Future
----------
	
	+ Much more flags for the program.
	+ kernel::exec_from_scrach
	+ An archived DataBase, like the Register base for windows.
		- kernel::LoadDataBase(char *keys_string, size_t size, void *data);
		- kernel::SaveDataBase(char *keys_string, size_t size, void *data);
	+ Auto complete expressions (Like under Unix console).
	+ Fix bugs ?
	
---------------
VIII-Known Bugs
---------------

	+ Hot-Reset with ON+ESC creates some leaks of memory.
	+ If you do a Hot-Reset when you are in the VAR-LINK, you cannot access it anymore.
	+ If you do SHIFT+ON under the Unit Menu, with a dropdown, on Ti-89, when you return from the Doors Explorer, there is a bug in the font size in the Unit Menu (The small font appears to have the size of the medium font).
	+ Error messages are lost sometimes with SHIFT+ON (It won't work and you don't see an error message).

------------
IX-Thanks to
------------

	- Zeljko Juric <Zeljko@tigcc.ticalc.org>for TIGCClib.
	- Julien Muchembled <Julien.Muchembled@netcourrier.com> for HW2Patch and many other things (Wonderfull Man !).
	- Kevin Kofler <kevin.kofler@chello.at> for its advises and HW2TSR.
	- Johan  <johei804@student.liu.se> for its 'TI-89 HARDWARE INFORMATION'.
	- Rusty Wagner <river@gte.net> for Virtual TI and MakePrgm.
	- Olivier Lesteven <b.lesteven@wanadoo.fr> for TeOs.
	- Olivier Armand (ExtendeD) <ola.e-ml@wanadoo.fr> for its advices and bugfixes. 
	