[Main]
Title=Making Kernel-Based Programs
Index=USE_KERNEL, USE_PREOS_COMPRESSED_TABLES, _comment, _exit, _library
See Also=doors.h/

[Top]
To produce a kernel-based program, i.e. a program which will need PreOS,
DoorsOS, UniversalOS, TeOS, etc. for executing, simply define the global
preprocessor symbol <CODE>USE_KERNEL</CODE> at the begining of your program,
before including any other header files from the library. Alternatively, the
old method (including the <A HREF="$$LINK(doors.h/)">doors.h</A> header file
before including any other header files from the library) still works. In
fact, if <CODE>USE_KERNEL</CODE> is defined, including any header file from
the library will include <CODE>doors.h</CODE> automatically (if it is not
included explicitely before). So, explicitely including <CODE>doors.h</CODE>
is really necessary only if your program does not include any other header
file from the library (which is extremely unlikely).
<BR><BR>
Here is a Kernighan &amp; Ritchie "Hello world" example (kernel version, called "Hello World 4"),
which works exactly like the example given in the previous section
(<A HREF="$$LINK(nostub)">Making Kernel-Less Programs</A>):
$$EXAMPLE(Hello World 4.c)
Note that the directive <CODE><A HREF="$$LINK(advanced_savescreen)">SAVE_SCREEN</A></CODE> is not included like in the NoStub version.
DoorsOS saves and restores the screen content by default, so no extra intervention
is necessary.
<BR><BR>
Of course, it is better again to use TIOS specific functions than ANSI C console
functions, so an extended "Hello world" TI-specific example (kernel-based
version), which does the same as in the NoStub case, follows (called "Hello World 5"):
$$EXAMPLE(Hello World 5.c)
See <A HREF="$$LINK(graph.h/)">graph.h</A> and <A HREF="$$LINK(kbd.h/)">kbd.h</A> for
detailed descriptions of the used functions and data types. Be aware of the slight difference between
<A HREF="$$LINK(graph.h/ClrScr)">ClrScr</A> defined in <A HREF="$$LINK(graph.h/)">graph.h</A> and
<A HREF="$$LINK(stdio.h/clrscr)">clrscr</A> defined in <A HREF="$$LINK(stdio.h/)">stdio.h</A>.
<BR><BR>
To compile this program, you can use the
<A HREF="$$INFOLINK(ide)">TIGCC Integrated Environment</A>, or you can type from the command line
(if the file is named "hello.c"):
<BR><BR>
<B>tigcc -O2 hello.c</B>
<BR><BR>
Always include the <B>'-O2'</B> or <B>'-Os'</B> switch: it will turn on optimization
(click <A HREF="$$INFOLINK(comopts)">here</A> to see much more about compiler command line options).
See also the notes given with the example in the previous section.
<BR><BR>
If you make programs spread in more than one file, you must define
<CODE>USE_KERNEL</CODE> (or include <A HREF="$$LINK(doors.h/)">doors.h</A>) in each file!
<BR><BR>
The advantage of kernel-based programs lies in the fact that they are
often (but not always) shorter than NoStub programs if the
program contains a lot of ROM calls. Kernel-based programs can also call
routines from external files (often called "libraries") without special
library support inside the program. Any other features supported
with this library of header files work in both kernel and
NoStub mode, so if the difference in the program size is not
too large, and if no external libraries are needed, NoStub mode
is recommended. Note that routines defined in these header files
contain most of the routines which are seen in various external
libraries, sometimes maybe with different name and syntax.
<BR><BR>
Additionally, if you want to make your program even smaller but only want to support
new versions of the PreOS kernel, you can define <CODE>USE_PREOS_COMPRESSED_TABLES</CODE>.
This will create compressed versions of the relocation tables, which are not
available in older kernels. If you try to run the program with an old kernel
installed, you will get an error message.
<BR><BR>
If you make a kernel-based program, knowing the following facts may be useful:
<UL>
<LI>
You can produce an external library file by defining the global symbol
<CODE>_library</CODE>, i.e. by putting <CODE>int&nbsp;_library</CODE>
in your program. If the name of your library is for example <I>MyLib</I>,
all symbols with names like <I>MyLib__nnnn</I> will be exported as public. To make
life easier, use the <CODE>#define</CODE> directive. For example, if you
want to export function named <I>MyFunc</I>, you can, for example, put the directive
<CODE>#define&nbsp;MyFunc&nbsp;MyLib__0005</CODE> at the beginning of
your library. The same directive must be included in the program which wants
to use the function <I>MyFunc</I> from the library <I>MyLib</I>. Also, the prototype
of the imported function also needs to be defined.
<BR><BR>
</LI>
<LI>
Kernel-based programs may have an exit point. The function with name
<CODE>_exit</CODE> will be executed if and only if the program is terminated
in an abnormal way, for example if there was an error, or if the user pressed
STO+ON.
</LI>
</UL>
