The <doors.h> header file


  
This header file must be included before any other header file if you want to make a DoorsOS program, i.e. program which needs DoorsOS-like kernel (note that this including will be performed automatically if you define the global preprocessor symbol USE_KERNEL before including any other header file from this library). The advantage of kernel-based programs is in fact that they are shorter than "nostub" programs if the program contains many ROM calls. Kernel-based programs also can call routines from external files (often called "libraries"), which is not possible in "nostub" programs. Any other features supported with this library of header files work in both "DoorsOS" and "nostub" mode, so if the difference in the program size is not enormous, and if no external libraries are needed, "nostub" mode is highly recommended. Note that routines defined in these header files contain the most of routines which are seen in various external libraries, sometimes maybe with different name and syntax.

This header file is much more complex than in releases of TIGCCLIB prior to 2.0, but you need not to call directly anything from it (many tasks will be performed automatically). It first defines one global preprocessor symbol named DOORS which is used in other header files to indicate DoorsOS mode, and redirects main ROM-calling macro _rom_call (which is intensively used in all other header files) to use DoorsOS calling convention (i.e. using absolute calls instead of indirect calls through jump table). More precise, _rom_call is redirected to DoorsOS built-in symbols like _ROM_CALL_nnn, and any additional arguments of _rom_call macro which are needed for "nostub" calling convention are simply ignored. It will be later a job of linker to generate a relocation table for relocation of such calls. This header file also plays some tricks with the machine stack, necessary for supporting exit and atexit functions without overloading the size of the generated code. Finally, this header file implements the necessary protocol for returning values to the TI-Basic (either using the expressions stack or through a variable) if the preprocessor symbol RETURN_VALUE is defined before including this header file.

See also nostub.h header file.

Return to the main index