Doors OS Beta 2

Programmers may use the following distributed libraries:
- userlib   -> common & password functions
- graphlib  -> graphical functions
- filelib   -> file operation functions
- ziplib    -> Compression / Extraction (made by Marc Teyssier)
- hufflib   -> Extraction (added for anterior compatibility, use preferably ziplib)
- hexlib    -> Display Hexa numbers

Doors OS is a freeware. The distribution of Doors is encouraged, as long as all the files are kept together, and unmodified from the form in which they were originally released.

This is the Beta2 Final Version of DoorsOS. However, when TI will release assembly info, the docs will be updated.

DOORSOS WON'T RUN ON A TI92+ WITH ROM VERSION 1.00. PEOPLE WHO USE IT MUST UPGRADE TO 1.01 TO INSTALL DOORSOS. FREE ROM UPGRADES ARE AVAILABLE AT WWW.TI.COM

Requirements

To install Doors OS you need:

Installation

1. First, unzip all files contained in DoorsOS.zip into the folder of your choice.

2. Use the Graph-Link software to transfer the program, 'doorsos.89z' or 'doorsos.9xz' to your calculator.

3. Run doorsos from your calculator (type 'doorsos()' at the home screen and press Enter). This will install the Doors kernel on the calculator. You can delete the 'doorsos' file from your calculator after that.

4. Now you may run any assembly program: Just type it in the home screen like you would a basic program. Libraries can be in any folder, and they can be stored in RAM or in Archive, although I would recommend that you keep them in RAM for speed and battery purposes.

5. If you press Shift-ON at any time, it will run the program named 'doors', which MUST be in the current folder. If it is archived, it will be temporarily unarchived.

6. You can exit all assembly programs at any time, pressing ON+ESC

NOTE: Use this program at you own risk. We can't be held responsible for any damage done to your calculator.

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

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

After having installed Doors OS:
Be sure to transfer the following files to your calculator:

doors     | The explorer
filelib   | File management library
graphlib  | Gfx functions
userlib   | Password and common functions (all of these by the Doors Team)

ziplib    | Compression library by Marc Teyssier

You can launch the Doors Explorer pressing 'Shift-On'.
Of course it can also be executed from the Home screen.
Please read Doors-Explorer.txt for more info about it

First of all, there are 2 different types of programs: programs and libraries. The only differences between them is that programs have:

Those are the only differences, so programs AND libraries can export functions, BSS blocks, import functions from others programs and libraries, and have an exit point.

How to Compile a Program or a Library

Suppose that you unzipped Doors in the folder C:\Doors. The first thing to do is to add these lines in your autoexec.bat:

SET DOORSOS=C:\DOORS
SET PATH=%PATH%;%DOORSOS%\BIN

Now you can compile a program or library from the DOS command line:

C:\DOORS>Doors <prog>

With "prog" being the name of the *.asm file without its extension.

General

Every program should include the header file "doorsos.h" at the beginning. To define which calculator the program is designed to run under, the programmer adds the following lines:

xdef    _ti89           to compile a .89z file
xdef    _ti92plus       to compile a .9xz file

Both lines can be written so that the file is compiled for both calcs. To learn programming, you should read all documents in the doc directory.

The Exit Point

The Anti Crash protection is activated when an error such as an Address error, Illegal instruction, etc.. occurs. It allows you to keep your memory intact. But the program can maybe have some things to do before exiting. Our kernel calls the exit point of each program when a crash occurs, so that the program do what it wants before ending.

Note that the exit point is optional.

The exit point is defined with;
       xdef _exit
       (...)
_exit:

At _exit: you will write your exit code. Here is a small example: It will free memory supposed to be used by the program

       xdef _exit
       (...)
_exit:
       tst.w handle ;tests if handle was allocated when the crash occurred
       beq \notalloc
       move.w handle,-(a7)
       jsr doorsos::HeapFree ;Frees the memory
       addq.l #2,a7
\notalloc
       rts ;IMPORTANT ! This code must end with an rts

       (...)
       handle dc.w 0 ;variable supposed to contain a handle number

NOTE: It is important that this code is totally bug-free! If it crashes, there would be a recursive and endless call to the Anti Crash protection and the user would have to reset his/her calculator.

How to Export Functions

At the beginning of your program or library, you can export functions with a 'xdef prog@XXXX' line, XXXX being an hexadecimal number. It indicates the index of the exported function.

But programs and libraries should have their include file whenever they export functions. For example, for a library called "graph", suppose that graph@0000 clears the screen. Then in "graph.h" there should be:

graph::clearscr equ graph@0000

Then if a program or a library wants to use this function, it will just have to include "graph.h" at the beginning, and when it wants to clear the screen, it writes:

       jsr graph::clearscr

Program Example

Let's call it "test".

       include "doorsos.h"     ;aliases for ROM functions and RAM addresses
       include "lib.h"         ;allows the use of functions exported from 'lib'
       xdef    _ti89
       xdef    _ti92plus       ;compiles for both calcs
       xdef    _main   ;tells that there is an entry point, so we know this is a program
       xdef    _comment ;do this only if you want a comment
       xdef    test@0000       ;first exported function
       ...
_main:                  ;label of the beginning code of you program
       ...
test@0000:              ;first exported function
       ...
       rts             ;return from function
       ...
       jsr     lib::function   ;calls a function in 'lib'
       rts     ; return from program
       ...
_comment        dc.b    "Program version 2.0",0

       BSS     ;tells there is a BSS block
;define here all vars you want to be in the BSS block.
;they are not initialized
buffer ds.b 50
       ...

       end ;tells the assembler that the file is finished.

Note: You don't always need to define comment, or to use a BSS block.

Library Example

Let's call this library "lib".

       include "doorsos.h"     ;aliases for ROM functions and RAM addresses
       xdef    _ti89
       xdef    _ti92plus       ;compiles for both calcs
       xdef    _library        ;tells that this is a library.
       xdef    lib@0000
       xdef    lib@0001
       ...
       xdef    lib@XXXX

lib@0000:
       ...
       rts     ;exits

lib@0001:
       ...
       rts     ;exits

       ...

       end     ;the file is finished.

Just to implement TI's info... of course, when they release it.

You can e-mail us at: <xvassor@mail.dotcom.fr>

If you have a question about programming, you would be better off mailing the Assembly-89 mailing list <assembly-89@lists.ticalc.org> or the Assembly-92 mailing list <assembly-92@lists.ticalc.org>

Please report any and all bugs you find using Doors OS, so that we may correct them as quickly as possible !
However, please try to give a precise description of what you did and what happened. Thanks you.

07/16/1999:
    - Doors OS Final Version beta2 released !
    - Now distributed under 2 forms: user and developer versions.
    - To those who haven't had the beta version, have a look at the history below.
    - The Shift-ON hook is now completely stable, but (as a side effect) it can only run Doors if it is in the current folder. This might be improved later.
    - Ziplib now supports archived files (good job Marc :) )
    - Added a 'Ziper' program on PC, you can compress files on your computer and then send them to the TI !
    - Thanx to Johan Eilert, I'm on the way of making Doors OS really compatible w/ future ROM versions. However, this could not be finished yet :(
    - Thanks to Chris Ivarson for converting the docs (yes, the ones you are reading) to HTML  

For the Programmers:
    - Now there is a true linker !
        - can link multiple .o files
        - supports the _nostub directive
        - is much better in general :)
    - you now can use cross references with libraries, ie. lib1 can use lib2 AND lib 2 can use lib1.
    - userlib::exec now supports archived AND zipped programs
    - userlib::runprog is a brand new function that will run any command line program ! (ASM, PRGM, or FUNC). For example you can give him the following

04/20/1999:
    - Doors OS Final Version beta1 released !

For the Users:
    - Total support for archived variables !
    - The Explorer is now in French !
    - Changed the installation pictures (thanks to Etan21 for them)
    - Definitely fixed the addresses of the Font Tables :) (thanks to Fred)
    - Improved a tiny bit of the Anti Crash protection
    - Fixed a bug which caused the calc to freeze sometimes when you pressed ESC-ON (thanks to Mikael Sundberg who found it)
    - Fixed the HeapAlloc bug another way, much better :)
    - Removed the program 'moremem' from the package, because using it caused the garbage collections to be buggy :-(

For the Programmers:
    - Fixed bugs in objtobin.exe (the linker), it now works much better :)
    - Modified filelib::gettype to make it work with the last release of ziplib. What's more, it now recognizes the type: 'OTHER'
    - Added a function graphlib::getlength, and modified userlib::smallmenu a lot. Check out the .h files for more info
    - Added EQUs for ALL rom calls in DoorsOS.h, however they are not documented
    - Added macros in DoorsOS.h to define pseudo instructions: push, pop, pushm, popm, inc, dec
    - Your program can now return values to the TIOS. See RAM&ROM.txt for more info.
    - You may note that this version is internally called 1.01 even if it doesn't much matter..

02/13/1999:
    - Doors OS 1.0 released !
    - Fixed a small bug
    - Added a picture when installation is successful (thanks to Pierre Henninger for his pics)
    - Added a 7 grayscale example program from Miles Raymond (thanks to him)
    - userlib::exec can now run *only* programs compiled with the new format. This prevents the TI from crashing sometimes.
    - Fixed a TI bug. The HeapAlloc function could crash sometimes, this is fixed by DoorsOS :)
    - Fixed the addresses of the Font Tables
    - Fixed a bug with graphlib::gray7
    - Fixed all bugs ?? I really hope so.. :) That is why this version is no more called 'beta'. It should be the final release.

12/29/1998:
    - Doors OS 0.96 beta released !
    - Fixed a big bug in the previous version. This one is now stable :-) There is still maybe ONE bug left, that make the Explorer do an Address Error. Anyway I can't have it again. If the explorer has an Address Error bug, please mail me !
    - Now automatically recovers any memory left unfreed by a program ! (Thanks to David Kuhling)
    - Still improved a little the Shift-ON Combo with the help of David Ellsworth.
    - Corrected the address of doorsos::ST_flags in doorsos.h

12/26/1998:
    - Doors OS 0.95 beta released !
    - Improved the Anti Crash protection ! It now recovers better from a crash.
    - Improved the Shift-ON Combo ! It is cleaner !
    - added Font table addresses in DoorsOS.h
    - added Handles.txt in the doc
    - added function getfreearchive in userlib
    - improved filelib::hdltoindex, it will now recognize when you look for a folder
    - improved filelib::search, it could only return the first file it found, now you can get the file found after <d1> searches
    - This version should be the last beta version since it is supposed to be really stable now.

12/06/1998:
    - Doors OS 0.91 beta released !
    - fixed a bug in the Shift-ON combo

11/28/1998:
    - Doors OS 0.9 beta released !
    - Ported the explorer to TI 89 ! Read Doors-Explorer.txt
    - Libraries can be in any folder now !
    - Added the "Shift-ON" combo which launches the program named "doors" at any time.
        For now, it can't display anything if there is an error
        - now automatically replaces the old kernel
        - added an 'uninstall' program
        - added functions:
    filelib::search
    filelib::createfile
    filelib::resizefile
    filelib::readfile
    filelib::writefile
    graphlib::erase_rect
    graphlib::frame_rect
    graphlib::line

        - enlarged the smallbox in graphlib on the 89.
        - added Macros in doorsos.h : WriteStr, WriteStrA, SetFont, GetKeyStat.
        - fixed bugs in: doorsos::FolderListHandle,doorsos::MainHandle,
                doorsos::DefTempHandle, Anti Crash protection,
                userlib::getfreeRAM

10/25/1998:
    - Doors OS 0.85 beta released !
    - Added password functions, InputStr and smallmenu in userlib
    - Included the filelib library: file operation functions
    - Ported hexlib and hufflib to Doors OS.
    - Ported our TI92 explorer to Doors OS! (for the TI92+ only)
    - Added doorsos::ST_flags and KEY_SHIFT aliases in doorsos.h
    - fixed bugs in:
        graphlib::scrtomem & graphlib::memtoscr
        userlib::FindSymEntry
        Anti Crash protection
        KEY_RIGHT,KEY_LEFT,KEY_UP,KEY_DOWN aliases
        1st EXTRA RAM TABLE entry (thanks to Rusty Wagner

10/18/1998:
    - Doors OS 0.8 beta released !
    - A new file format has been chosen and implemented.
    - Anti Crash protection implemented !
    - Released the graphlib library and added some functions in userlib.
    - Some bugs were fixed in the compiler.
    - Many more docs even if they aren't complete yet.
    - More sample progs

9/20/1998:
    - Doors OS 0.7 beta released !