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.