Doors OS Beta 2

by the Doors Team
for TI-89 and TI-92+

E-mail: xvassor@mail.dotcom.fr
Website: http://start.at/doors


 TABLE OF CONTENTS
  I. Introduction
 II. Installing Doors OS
III. Installing the Explorer 'Doors'
 IV. Programming for Doors OS
  V. Planned Features
 VI. How to Contact Us
VII. History


 I. Introduction

Doors OS is a kernel which will allow the execution of assembly programs on your TI 89 or TI 92 Plus. In fact it actually extends the built-in assembly support.

Its main features:

  • Library support
  • ROM Calls relocation
  • BSS support
  • Anti Crash protection! What's more, you can press ESC+ON at any time to exit programs.
  • Runs on both, TI 89 and 92 Plus
  • much more, of course :)

    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

    Return to Top


    II. Installing and Using Doors

    Requirements

    To install Doors OS you need:

  • A Graph-Link (TM) cable, or any working cable and the appropriate software (the GraphLink software (you can download it at http://www.ti.com/calc/)
  • A TI 89 or a TI 92 Plus :)

    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

    Return to Top


    III. Installing the Explorer 'Doors'

    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

    Return to Top


    IV. Programming for Doors

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

  • An optional comment
  • A main entry point

    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.

    Return to Top


    V. Planned Features

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

    Return to Top


    VI. How to Contact Us

    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.

    Return to Top


    VII. History

    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 !

    Return to Top


    Last Modified: 07/16/99
    Copyright 1998-99 Xavier VASSOR and Cedric COUFFIGNAL
    All rights reserved.