       Title: PedroM
     Version: 0.80
 Platform(s): TI-92+, TI-89, V200
      Author: PpHd
    Web Site: http://www.timetoteam.fr.st
      E-Mail: ppelissi@caramail.com
Release Date: 2003/12/01

---------
0.Licence
---------

  PedroM -Open Source ROM for Ti-92+, Ti-89 & V200 systems- 
  Copyright (C) 2003 PpHd
  
  This program is free software ; you can redistribute it and/or modify it under the
  terms of the GNU General Public License as published by the Free Software Foundation;
  either version 2 of the License, or (at your option) any later version. 
  
  This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  See the GNU General Public License for more details. 
  
  You should have received a copy of the GNU General Public License along with this program;
  if not, write to the 
  Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 

  PedroM uses also some non-GPL extra code which are distribute under their own licence.
  Thanks to the authors of theses original programs for letting me distributing it:
  
  Side                                  Copyright (c) 2002 Clement Vasseur.
  MD5                                   Copyright (C) 1999, 2000, 2002 Aladdin Enterprises.

--------------
I.Introduction
--------------

        PedroM is a complete new Operating System (OS) for Ti-68k calculators. It doesn't use any code from Texas Instruments OS, Advanced Math Software (AMS). The goal was to create an OS useable on real calcs, which can run safely 95% of the assembly programs designed for AMS 1.0x. So that, I was obbliged to rewrite many romcalls of the original OS. The rewritten romcalls are often faster, but always smaller: only 192K of Flash Rom are reserved for the system (64K for the boot, 8+8K reserved by the hardware, 48K+64K for PedroM itself). As a consequence, there is plenty of Flash memory available (228 Kbytes of RAM and 1900 Kbytes of Archive) and there is no Computer Algebra System (CAS). Of course, this OS sets the hardware protection (in RAM and in ROM) off. But all the assembly programs use either self modifing code, or data in code segment. So only the PedroM programs would be able to be executed in ROM. AMS Flash Application won't never be supported.
        
        The Ti link protocol is not complete: you can't send a Product Code, neither receive/send backup. Other things should work (Prefer Ti-GraphLink or tilp to TiConnect).

        PedroM has a modified version of PreOS core as built-in, so you don't need to install a kernel extender. It uses the latest version of PreOS. PedroM can also run natively PPG programs (See http://tict.ticalc.org for more infos about PPG programs). In conclusion, you can run at the moment :
                - Nostub Programs.
                - Kernel Programs (version 2, 3, 4 & 5) -See "Kernel History" in PreOS.txt.
                - PPG Programs.
                - Pack Archive Programs.
        Kernel v1 programs can be converted using 'ck1tok2' program to kernel v2 so you can even use kernel v1 with PedroM (Sorbo Quest! Lovely.) (on HW1 only).
        
        Many romcalls have been rewritten (>400). Many program work. TSR programs won't work since EV-hook doesn't work (In fact, EV_hook works but there is no AMS like application installed, so it does nothing since there is no event). PedroM is detected as AMS 1.01 by nostub programs but kernel programs will detect AMS 1.48.
        'stdlib' is also a built-in library (But you can update it!)
        
-------------------------------------
II.The command line prompt: the shell
-------------------------------------

        Contrary to AMS, PedroM looks like a unix shell. You can receive any files (sent throught the link port) in this shell, just like in the AMS Home application.
        
        A. SPECIAL KEY LIST:
        --------------------

        ENTER:  
                You enter a command in the line prompt, and you validate it by pressing ENTER.
        UP/DOWN:
                There is an history of the last used commands.
                Press Up/Down to select a previous command (Up to 10 previous commands).
        LEFT/RIGHT:
                Select current character.
        ON:     
                Auto completion of the current command.
                It will search in the internal commands, in the folders and in the files of the path. If there are more than one command which can complete the line, it will put as much char as possible, and it won't put the final char (' ' or '\'). It no char can be put, it will display a menu with all the possible commands. Nevertheless, if you are under very low memory conditions, it shouldn't display the menu.
        F1-F8:
                Paste the memorised command (See Environnement variables).
        ON-ESC:
                Abort current program.
        [2ND] + [APPS]:
                Restart another Shell Command (Switch current task).
	[DIAMOND] + F1-F8:
		Go to background process # 0-7 (Process must have been created using [SWITCH]).
                        
        B - INTERNAL COMMANDS:  
        ----------------------

        They are built-in commands:

DANGEROUS:
        + 'install product code': Install a signed Product Code using the Boot code (ie reinstall AMS). This command isn't fully displayed in the help. This command should be 99% safe (See maxmem doc to understand why it is not 100% safe).
        + 'install tib'		: Install an unsigned Product Code. This command isn't fully displayed in the help. It uses an internal function to reinstall a new tib. This function is the only way to update PedroM. It may delete some archived files.
        + 'install format'	: Bad name for such a command (It is too avoid auto-completion). Nevertheless this command erases all the archived files of your calculator and does a reset. Original version of 'stdlib' is reinstalled.

MISC:
        + 'help'        : display all the internal commands.
        + 'cls'         : Clear the screen.
        + 'echo'        : Display the string (Very usefull with scripts).
                        Ex: echo "Hello world !"
        + 'more'        : Display else stdin or the given file, stopping itself every 14 lines.
			Ex: ls -l|more
	+ 'cat'		: Display the given files (in stdout). '-' is the stdin file.
			Ex: echo Hello >toto
			Ex: echo World |cat toto - toto
	
SYSTEM:
        + 'flags'       : Set the internal flags of Pedrom.
                        Use:    flags   optionA=1 optionB=0 [...]
                        Options may be:
                        - AutoArc:	The sent files are automaticly archived or not.
                        - OffSwitch:	Instead of turning off the launched program, it will switch and starts another Shell Command.
                        - GetKeySwitch:	If you press [2nd]+[APPS] in ngetchx/GKeyIn, it will switch and starts another Shell Command.
        + 'clean'       : Clean the system (Unrealloc Kernel files, delete Twin Files, and free all handles which are not in the VAT). May crash if the VAT is corrupted (Reset). Erase all background process too!
        + 'reset'       : Reset PedroM (Archive won't be lost).
        + 'mem'         : Display the remaining memory.

FILES:
        + 'cd'          : Change the current directory.
                        Ex: cd toto
        + 'arc'         : Archive a file (Put a file from RAM to Flash Rom). 
                        Ex: arc sma
        + 'unarc'       : Unarchive a file.
                        Ex: unarc sma
        + 'ls'          : List the current directory. Options : 
                        '-l' : to have some details.
                        '-h' : to see the 'home' directory.
        + 'mkdir'       : Create a new directory.
                        Ex: mkdir toto
        + 'rmdir'       : Delete a directory. All the files in the directory are deleted.
                        Ex: rmdir toto
        + 'rm'          : Delete a file.
                        Ex: rm temp
        + 'rmarc'       : Delete an archived file. (It is deleted even if there isn't enought memory to copy it in RAM).
                        Ex: rmarc temp
        + 'mv'          : Move/Rename a file (SrcName DestName).
                        Ex: mv tictex shell
        + 'cp'          : Copy a file (Srcname DestName).
                        Ex: cp main\tictex system\shell
        + 'sendcalc'    : Send a file to another calc. Works even with AMS calcs!
                        Ex: sendcalc tictex
        + 'getcalc'     : Get a file from another calc. Works even with AMS calcs!
                        Ex: getcalc tictex
        + 'read'        : Read from the keyboard (stdin) and put the chars in variables. [DEL] is supported even if it isn't clear.
                        Ex:     :>read x y z
                                Hello world !
                        Now x = "Hello", y = "world" and z = "!".
        + 'unppg'       : Extract a PPG file and add the extracted program to the VAT.
                        Ex: unppg db92ppg db92

PROCESS:
        + 'ps'          : Display all the background processs. The current process is not listed. It displays the PID (The number to give to kill/go command), the size used by the system to save the process and its name (May be wrong).
        + 'kill'        : Kill a background process, given its PID (See ps for PID).
                        Ex:     kill 1
        + 'go'          : Stops the current process and restore a background process.
                        Syntax:         go      [PID]
                        If you don't specify the PID, it will restore the latest process.

APPS:
        + 'side'        : Starts SIDE (Built-in application).
                It is a text editor. Here are the keys :
                  [2nd]+[LEFT]  : jump to beginning of line
                  [2nd]+[RIGHT] : jump to end of line
                  [<>]+[LEFT]   : Next left word
                  [<>]+[RIGHT]  : Next right word
                  [2nd]+[UP]    : page up
                  [2nd]+[DOWN]: page down
                  [<>]+[UP]: jump to first line
                  [<>]+[DOWN]: jump to last line
                  [SHIFT] + arrow keys: select text
                  [CLEAR]: clear to end of line
                  [2nd]+[CHAR]: characters table
                  [APPS]: Display secondary screen (See config)
                  [ESC]: close file and prompt for a new one
                  [2nd]+[QUIT]: exit
                  [2nd]+[OFF] or [<>]+[ON]: power off
                  [<>]+[x] : cut
                  [<>]+[c](Ti-92+) OR [<>]+[y](Ti-89): copy
                  [<>]+[v](Ti-92+) OR [<>]+[z](Ti-89): paste
                  F1 - Build - save the file and launch the compiler.
                  F2 - Exec - save the file and executes the compiled program.
                  F3 - Goto - go to the given line
                  F4 - Find - prompt for a string to be searched for
                  F5 - Replace - prompt for a string to be replaced for
                  F6 - Config - open the config screen
                  F7 - About - show the about screen
		  And also [2nd]+[Switch] and [diamond]+F1-F8: See the shell keys for details.
                -- Config --
                Build: name of the program that runs with F1 (build) '!' is the text filename.
                Exec: name of the program that runs with F2 (Exec) '!' is the text filename.
                2nd text: name of the text file to open with APPS.
                Auto insert closing brackets: Yes/No
                Auto indent: insert spaces when [ENTER] is pressed
                Key repeat delay and rate let you configure the cursor speed. 

EXTRA:
        Wildcards '*' and '?' are supported for the extra arguments: use 'arc *lib' to archive all the libraries.
        Variables are supported just like in Unix Script (But replacing vars may throw errors):
                {"Hello","world"}->x
                echo "${x[1]} ${x[2]}"
                "ls -l"->ls
                $ls
        Redirection is supported just like in Unix Shell:
                ls -l >dummy 2>error
                mem >>dummy
                ls -l | more
                read x y <hello
        Warning: It must be the last parameters, put a space before >, and no space after!
        
        There are also an extra command I have added only for debugging reasons:
        
        + 'hexdump'     : Do a dump of the memory. Usefull for debugging.
                        Ex: hexdump 0x400000
                        
        C - PROGRAMS:
        -------------

        If you want to run a program (designed for PedroM or AMS), just enter its name, and press ENTER. It cans run ASM programs (_nostub, kernel or Pack Archive) directly. You don't need to install a kernel (By the way, no kernel can be installed!). It cans also run the PPG directly (It supports all the PPG formats natively). So you can delete the launcher.
        
        C - CALCULATOR:
        ---------------

        Even if PedroM isn't designed to be a calculator, it would be quite annoying if you can't do any calcul with it. So you can enter a math calcul in the command line prompt, and it evaluates it:
        Example:
                2+2
                2E145*145
                -1452.3         ("ans - 1452.3")
                1452.23*256.32->x
                x*25.236->y
                x
                y
                1->x
                y
                1+x->x
                x
        For the moment, only + / * - -> exp ln are defined (and external fonctions).
        As a consequence, you can call a program like with AMS: "shl()" works, but it returns a random float since it doesn't support the PedroM convention.
        
        dim(LIST) returns the size of the list. dim(STRING) returns the size of the string.
        getkey() pauses the system waiting for a key. It returns the Key code.
        time()	returns the current time (from the boot of the calc).
	testd(string) returns true if string exists as a directory.
	testf(string) returns true if string exists as a file.
	        
        NOTE(1): "tictex()" won't work since it doesn't create a twin entry.
        NOTE(2): If an error arrived, some variables may be locked (ie can't be used). You can unlock them by calling 'clean'.
        NOTE(3): Func arg '25*x->f(x)' is not yet supported.

        D - Script:
        -----------
                
        A script is a text file which contains a list of commands to execute.
        The first line must be " #!PedroM ". All lines which begins with # are comments. Other lines are commands, just like in the shell. The script arguments are stored in a created variable: system\args, which is a list var.
        A special script is launched when PedroM starts: its name is 'system\start'.

	A script supports also some extra commands:
		+ exit:	Exit from the script.
		+ if/else/elif: Execute block if condition is true:
			if CONDITION
			 <
			  CODE
			 >
			elif CONDITION
			 <
			  CODE
			 >
			else
			 <
			  CODE
			 >
		+ while: Execute block until condition is false:
			while CONDITION
			 <
			  CODE
			 >

	E - System variables
        --------------------
	
	Environnement variables are string variables stored in system folder.
	They are:
		+ system\start	:	Script to execute when the system boots.
		+ system\apd	:	Apd value (String Number). Set the current value for the Auto Power Down timer (in seconds). Valid values are from 10 to 1000 (Other values won't be accepted). Warning: It is a string!
		+ system\path	:	Set the current PATH. If a file is not found inside the current (and if there isn't any given folder), it will search in the path. It is a list of strings.
		+ system\home	:	Folder where to create initialisation files, save files, etc. It is a string.
		+ system\args	:	List of the arguments given to a script. It is a list of strings. It is a local file to a script (ie it is different for each script).
		+ system\fkey[n]:	String to put if F[n] is pressed.
		                        Ex: '"stdlib"->system\fkey1' : When you press F1, "stdlib" is pushed instead.
	                	        Ex: '"ls -l;"->system\fkey2' : With F2, "ls -l" is executed. Putting ';' as the laste key means auto-execute.
		+ system\temp	:	Folder where to create temp files. It is a string.
		
----------------
III.Installation
----------------

        I don't want to explain how to send a non-certified TIB to a Ti-92+/Ti-89. It may be be dangerous, and you may dommage your calculator: unexperiment users may do dangerous things. You can nevertheless test PedroM on VTi.
        Nevertheless it works fine on my TI-92+ HW1, on some Ti-92+ HW2, on some Ti-89 HW2 and on some Ti-89 HW1. So I don't think it is dangerous.


----------------
IV.Build PedroM
----------------

        Warning: since A68k bugs if the source is bigger than 32766 lines, and since PedroM sources are about 36000 lines, you may have some problems when rebuilding it.
        
        1. You need to have:
                + PedroM sources.		(See http://www.timetoteam.fr.st).
                + a68k 2.73.f3k-pre1.  		(See http://tigcc.ticalc.org).
                + maketib.			(See http://www.timetoteam.fr.st).
                + ttstrip v1.04.		(See http://tict.ticalc.org).
                + PreOS v0.68 sources.		(See http://www.timetoteam.fr.st).
                + 'stdlib.9xz'.			(See http://www.timetoteam.fr.st).
                
        2. If you don't have a WINDOWS/DOS Operating System, I assume you can recompile the necessary programs for your system.
        
        3. Compile PedroM:
                a. Go to the PedroM directory.
                b. Extract the bin file from 'stdlib.9xz':
                        ttstrip ..\Preos\stdlib.9xz stdlib.bin
                c. Assemble PedroM and create the object file:
                        a68k -t -i..\Preos\Src -iC pedrom.asm
                where "..\Preos\Src" is the directory of the sources of PreOS.
                d. Create the TIB:
                        maketib pedrom.o
        Or use directly the script 'make.bat'. It assumes the directories are like :
                +PedroM +
                |       |Doc
                |       |C
                |       |Tools
                |
                +PreOS  +
                        |Doc
                        |Src
        (ie you have extracted the archives PedroM and Preos zip inside a common directory).
        

--------------
V.Boot & Reset
--------------

        In PedroM, there are 2 kinds of reset:
                + soft reset which doesn't destroy your RAM : 'Address Error', 'Protected Memory', ... do such kind of reset. I recommended highly to do a 'clean' command before continuing. PedroM can't do it itself because this command may crash the calculator.
                + hard reset : the RAM is totally reset. Only the archive files are kept.

        If you press ON during the end of the booting process (between the black screen and the white screen), PedroM will do a hard reset which doesn't start the script 'start'. Do no kept ON pressed during the second reset, otherwise, it will do a 3rd reset, and so on.
                
-------
VI.FAQ
-------

Q: How can I send PedroM to my calc?
A: The only thing I will say is that you have to look for a program which can receive a TIB.
   If you read this doc carrefully, you will find some usefull infos :)

Q: Is there a V200 version? 
A: The V200 version should work (compile the sources with V200 flag), but you can't send a non-certified TIB to a V200. So it is useless.
   Moreover the V200 doesn't work on VTI since the emulator doesn't really support this calculator.

Q: Why should I use PedroM instead of AMS?
A: For 3 main reasons: 
        + PedroM is open-source.
        + There is plenty memory free (Both Flash and RAM).
        + There are less dramatical bugs than AMS (ie you can't overpass the Hardware Protection by software.).

Q: Why should I use AMS instead of PedroM?
A: For 3 main reasons: 
        + You use your calculator for Math.
        + AMS is less buggy.
        + AMS is the reference: it should be compatible with all programs.

Q: Is there a Window Like environnement?
A: Some window'like environnements are being developped for PedroM.

Q: Some programs don't work under PedroM. A program tells me 'Romcall xxx not available'. What can I do?
A: Nothing. Just report me the program, and maybe I can fix it.

Q: Some programs crash under PedroM. What can I do?
A: Report me the program. If it is a kernel program, it is certainly a bug in PedroM. PedroM should be compatible with all kernel programs (on HW1, at least)... If you have a HW2, you may have some problems with GrayScales with old programs. TiGb can't be run because it uses a dirty hack to get a 70K page. 

Q: A program crashes, and I can't run it anymore.
Q: The calculator don't have any memory left.
A: Call 'clean' command. Then retry it. If it crashes again, it has been corrupted. Resend it to PedroM.

Q: I change the batteries, and PedroM resets.
A: Yes. I don't have written the code for avoiding this!

Q: I can't install unios/preos/doorsos/teos!
A: There is already a kernel in PedroM! You don't need to install a new one. Moreover kernels use many dirty hacks which are not compatible with PedroM.

Q: What is 'stdlib'?
A: Lock at PreOS documentation.

Q: Why don't you do a multi-tasking OS? Why not Linux?
A: I personnaly think that if you want to do a multi-tasking OS, you should have at least a MMU to protect the tasks. Ti-92+ doesn't have a MMU, so a single-tasting OS is more suitable. Install Prosit if you still want such a program. Moreover the RAM is too small to create a good multi-tasking OS.

Q: I send a file and it seems to work fine, but when I list the files, I can't see it.
A: Check if the file hasn't been added to another folder.

Q: Why a TIB and not a 9xu?
A: 9xu files have some secrets I don't know. I know the format of the TIB files enought to create a good TIB. I may change this.
 
Q: I have a lot of problems with the Link!
A: Indeed, there are some remaining problems with the link protocol.
 Try using another link program (Like send92p by Rusty).
 The last version of TiGl does a lot of overchecking.

Q: Your completion algorithm is quite good, but I want to add my own words to the list.
A: You can do it by creating some dummy files in a dummy folder.
   For example, your words are: toto, titi, tutu.
   In the shell, enter this:
        :>1->dummy\toto
        :>1->dummy\tutu
        :>1->dummy\titi
   to create some dummy vars (You can archive them). Then, add dummy folder to the path:
        :>setpath dummy [...]
   When you press, [t] then [ON], you will have your own words in the list. Magic, no?
   
Q: What is PedRhum?
A: PedRhum is a modified version of PedroM by Extended. It allows you to use PedroM without replacing AMS (Just like running Linux from DOS), so you can test PedroM. It uses some dirty hacks so the bugs must be returned to Extended himself, who may forward me if needed.
   
Q: Your program is awesome. I want to pay you for it.
A: No problem. Send donation to smeeter@caramail.com (PayPal Address).

-------------------
VII.Special Thanks
-------------------
        
        - Johan  <johei804@student.liu.se> for his precious hardware doc.
        - Rusty Wagner <river@gte.net> for Vti emulator.
        - Zeljko Juric <Zeljko@tigcc.ticalc.org> for tigcclib.
        - Julien Muchembled <Julien.Muchembled@netcourrier.com> for his tools.
        - Olivier Armand (ExtendeD) <ola.e-ml@wanadoo.fr> for checking (often!) my code.
        - WORMHOLE <ti_crackers@hotmail.com> for OpenOS.
        - Thomas Nussbaumer <thomas.nussbaumer@gmx.net at http://tict.ticalc.org> for the PPG extract function and the original Bitmap functions.
        - Clement Vasseur <nitro@epita.fr> for Side (Built-in editor).

        - And a billions of thanks to all the beta testers!
         