Subversion Repositories shark

\documentclass[a4paper,10pt]{report}

%\usepackage{html}

\title{The S.Ha.R.K. Quick Guide}

\author{Tullio Facchinetti\\

\textit{tullio.facchinetti at unipv.it}\\ \\

Version 1.11}

\begin{document}

\maketitle

\tableofcontents

% \begin{abstract}

% \end{abstract}

%------------------------------------------------------------

\chapter{Introduction}

\label{ch:introduction}

%------------------------------------------------------------

This document has been written for helping the beginner to start

using the S.Ha.R.K. (\textbf{S}oft \textbf{HA}rd \textbf{R}eal-time

\textbf{K}ernel) kernel. The S.Ha.R.K. kernel source code is

available at

\begin{center}

\underline{http://shark.sssup.it}

\end{center}

The S.Ha.R.K. Quick Guide is intended to be as an ongoing document,

since new topics will be added if needed.

%------------------------------------------------------------

\section{What S.Ha.R.K. is}

\label{sec:what-is}

%------------------------------------------------------------

S.Ha.R.K. is a set of libraries that are statically linked into a

multiboot image, that is the application. Then, the application is

run through a DOS memory extender (X.EXE) or directly launched at

boot time using the GRUB.

S.Ha.R.K. makes available to the application all the primitives to

create, activate and run real-time tasks using state of the art

scheduling algorithms (EDF, RM, etc.). It also allows to share data

among the tasks by chosing between several resource reservation

algorithms like Priority Ceiling, Priority Inheritance, SRP

\cite{But97}.

S.Ha.R.K. supports drivers for a huge amount of hardware, like video

and network cards, frame-grabbers, multi-purpose cards and custom

boards.

Shark is a compiling kernel with memory protection, not a kernel like

Linux. You will not find any main() routine into the kernel tree

because the tree only contains the set of libraries required to build

the application. The main() function is called by the kernel, and is

contained into the application files as specified by the C language

standard.

%------------------------------------------------------------

\chapter{Getting started}

\label{ch:getting-started}

%------------------------------------------------------------

This Section covers the S.Ha.R.K. installation and system building

from the sources available on the website. As will be introduced in

Section \ref{sec:platforms}, S.Ha.R.K. can be used under Linux,

Windows$^{TM}$ or xDOS (preferably the free version of DOS, FreeDOS).

%------------------------------------------------------------

\section{Supported platforms}

\label{sec:platforms}

%------------------------------------------------------------

S.Ha.R.K. application, as well as the Shark kernel, modules and

drivers, can be developed under three main platforms: DOS (either

MS-DOS$^{TM}$ or FreeDOS\footnote{In the rest of the document, we

will only refer to FreeDOS while addressing the xDOS platform. Most

of the topics  hold for other DOS systems; specific indications for

other platforms will be given if necessary.}), Windows$^{TM}$ or

Linux. Table \ref{t:platforms-comparison} shows some characteristics

of using Shark under the three systems.

\begin{table}[ht]

\centering

\begin{tabular}{|l|c|c|c|}

\hline

                                & DOS           & Linux                 &

Windows         \\ \hline

Graphical interface             & no            & \textbf{yes}          &

\textbf{yes}            \\

Good editors                    & it depends    & \textbf{yes}          &

\textbf{yes}           

\\

Compilation speed               & slow          & \textbf{fast}         &

\textbf{fast}           \\

Native compiler                 & no            & \textbf{yes}          & no   

        \\

Programming/debug tools         & no            & \textbf{yes}          & no   

        \\

Dealing with long filenames     & TSRs          & \textbf{native}       &

\textbf{native} \\

Native execution                & \textbf{yes}  & no                    & no   

        \\ \hline

\end{tabular}

\caption{Quick comparison among the different supported platforms.}

\label{t:platforms-comparison}

\end{table}

A quick consideration about the item "Good editors" for DOS. Someone

may consider RHIDE, the DOS editor distributed with S.Ha.R.K. a good

editor: I don't. But I also hate EDIT. Usually, I use an old editor

called AURORA. More information at

\begin{center}

\underline{http://www-personal.umich.edu/~knassen/aurora.html}

\end{center}

Linux and Windows$^{TM}$ are quite similar, in terms of programming

facilities. The main advantage on using FreeDOS platforms is that it

does not require to reboot the machine to execute the application,

while when developing under Linux or Windows$^{TM}$ it does.

Cygwin or other Linux console for Windows$^{TM}$ are not currently

and directly supported. However, the support to such platforms is not

mandatory in the current version, since a Windows$^{TM}$ user can

easily build the system and develop application directly from the

Windows$^{TM}$ platform.

%------------------------------------------------------------

\section{Installation}

\label{sec:platform-install}

%------------------------------------------------------------

The installation changes a little bit from platform to platform.

%------------------------------------------------------------

\subsection{Linux}

\label{sec:install-linux}

%------------------------------------------------------------

\begin{enumerate}

\item \label{linux-step1} download \texttt{shark-1.5.tar.bz2} from the S.Ha.R.K.

web site (\underline{http://shark.sssup.it})

\item \label{linux-step2} type \texttt{tar xvjf shark-1.5.tar.bz2}

\item \label{linux-step3} type \texttt{cd shark}

\item \label{linux-step4} edit the S.Ha.R.K. configuration file,

\texttt{shark.cfg}

\item \label{linux-step5} type \texttt{make all}

\item \label{linux-step6} type \texttt{cd demos}

\item \label{linux-step7} type \texttt{make}

\end{enumerate}

Some tips:

\begin{itemize}

\item Step \ref{linux-step4} is needed to setup the compiler options and

optimize the kernel for speed and precision.

\item Step \ref{linux-step5} builds the S.Ha.R.K. kernel, libraries, modules and

device drivers.

\item Finally, step \ref{linux-step7} builds the demo programs.

\end{itemize}

%------------------------------------------------------------

\subsection{DOS}

\label{sec:install-DOS}

%------------------------------------------------------------

The installation for the xDOS platform follows:

\begin{enumerate}

\item \label{DOS-step1} download \texttt{unzip32.exe}, \texttt{mindj333.zip}

and

\texttt{shark15.zip} from the S.Ha.R.K. web site.

\item \label{DOS-step2} type \texttt{unzip32 -o mindj333.zip -d c:}

\item \label{DOS-step3} type \texttt{cd c:$\backslash$djgpp}

\item \label{DOS-step4} type \texttt{install.bat}

\item \label{DOS-step5} type \texttt{setvar.bat}

\item \label{DOS-step6} type \texttt{unzip32 -o shark15.zip -d c:}

\item \label{DOS-step7} type \texttt{cd c:$\backslash$shark}

\item \label{DOS-step8} edit \texttt{shark.cfg}

\item \label{DOS-step9} type \texttt{make}

\item \label{DOS-step10} type \texttt{cd demos}

\item \label{DOS-step11} type \texttt{make}

\item \label{DOS-step12} type \texttt{cd $<$demo dir$>$}

\item \label{DOS-step13} type \texttt{x $<$demo name$>$}

\end{enumerate}

Some tips:

\begin{itemize}

\item If you already have \texttt{PkZip}, at step \ref{DOS-step2} you may

also type \texttt{pkunzip -d -o mindj333.zip c:$\backslash$}

\item If you change the DJGPP directory name or position,

\texttt{install.bat} and \texttt{setvar.bat} need also to be changed.

\item The \texttt{setvar.bat} script automatically set the environement

variables for DJGPP; you must run \texttt{install.bat} and

\texttt{setvar.bat} every time you reboot and start a compile

session.

\item After step \ref{DOS-step5}, DJGPP is installed and ready to compile

shark.

\item If you already have PkZip, at step \ref{DOS-step6} you may also type

\texttt{pkunzip -d -o shark15.zip c:$\backslash$}

\item Step \ref{DOS-step8} is needed to setup the compiler options and

optimize the kernel for speed and precision.

\item Step \ref{DOS-step9} builds the S.Ha.R.K. kernel, libraries, modules

and device drivers.

\item Finally, step \ref{DOS-step11} builds the demo programs.

\end{itemize}

In DOS real mode we suggest, even though it is not mandatory, to load

the smartdrive utility (\texttt{smartdrv 16000 /x}) to speedup the

disk access during all the previous steps. The \texttt{smartdrv}

utility is available for MS-DOS$^{TM}$. For the FreeDOS environemnt

you can use the lbacache instead.

\textbf{IMPORTANT:} You need DOSLFN.ZIP

(\underline{http://shark.sssup.it/distrib/doslfn.zip}), a TSR to use

long file names under DOS real mode. You have to run the doslfn

command before starting to work with S.Ha.R.K. every time the machine

is re-booted. You don't need it only if you are inside a DOS

emulation window (see Windows Millennium/NT/2000/XP paragraph).

In real DOS environement, you can compile and run a demos without

reboot, directly running the demo programs through the \texttt{X.EXE}

extender from the FreeDOS command line.

%------------------------------------------------------------

\subsection{Windows Millennium/NT/2000/XP}

\label{sec:install-win}

%------------------------------------------------------------

\begin{enumerate}

\item download unzip32.exe,mindj333.zip and shark15.zip from the S.Ha.R.K. web

site;

\item go in a DOS emulation window (DOS prompt);

\item follow the previous procedure for normal DOS environment.

\end{enumerate}

\textbf{Reminder:} YOU CAN NOT EXECUTE A S.Ha.R.K. APPLICATION

THROUGH THE X.EXE EXTENDER WITHIN A DOS EMULATION WINDOW. So, to test

a compiled demo programs you need  to reboot with the FreeDOS

bootdisk or something similar.

%------------------------------------------------------------

\section{How to partition the hard-disk for using with S.Ha.R.K.}

\label{sec:hd-installation}

%------------------------------------------------------------

Even though it is often not needed and it may be unconfortable to

setup an already partitioned machine, it may be very useful to setup

a machine to host the S.Ha.R.K. kernel in school and university

laboratories for teaching purposes.

This section is dedicated to the setup of an hard-disk for dedicating

a partition to the installation of S.Ha.R.K. It will explain how to

partition and format an hard-disk in order to install a multi-boot

environment allowing to choose between three operating systems:

FreeDOS and S.Ha.R.K., Linux and Windows$^{TM}$. The five basic steps

to setup the installation are:

\begin{enumerate}

\item partition the hard disk;

\item install Windows$^{TM}$;

\item install FreeDOS;

\item install Linux;

\item setup the boot loader.

\end{enumerate}

The tools needed to perform the installation are:

\begin{itemize}

\item Linux fdisk utility;

\item a copy of Linux installation CD;

\item a copy of Windows$^{TM}$ installation CD;

\item some FreeDOS utilities;

\item a copy of S.Ha.R.K.

\end{itemize}

To accomplish all the operation related to the hard-disk partition, I

suggest to use a Linux LiveCD distribution. My favourite one is

Knoppix, by Mark Knopper, downloadable from

\begin{center}

\underline{http://www.knoppix.org}.

\end{center}

Linux LiveCD distribution allow to use all the powerful Linux tools

without the need of installing anything on the hard-disk.

Boot the PC from the CD drive after inserting the Knoppix LiveCD into

the drive and open a shell. You must be the root user to have the

permissions for the next steps, so type

\begin{center}

\texttt{su}

\end{center}

with an empty password at the console prompt. Then launch the Linux

\texttt{fdisk}, typing

\begin{center}

\texttt{fdisk /dev/hdXXX}

\end{center}

where XXX identifies your hard-drive. Typically, the command

\begin{center}

\texttt{fdisk /dev/hda}

\end{center}

will work fine. To use the \texttt{fdisk} commands do refer to the

program help: you will need the commands to delete and create

partition as well as to change the partition ID and write the

partition table on the disk.

I suggest to partition your HD like something as described in Table

\ref{t:hd-partitioning}.

\begin{table}[ht]

\centering

\begin{tabular}{|c|c|c|c|}

\hline

                        & Partition number      & Dedicated to  & Type         

\\ \hline

                        & 1st                   & FreeDOS       & FAT32        

\\

primary partitions      & 2nd                   & Windows       & FAT32/NTFS   

\\

                        & 3rd                   & Linux         &

extX/Reiser/... \\ \hline

                        & 4th                   & Data 1        & any          

\\

extended partition      & ...                   & ...           & ...          

\\

                        & last but one          & Data n        & any          

\\

                        & last                  & Linux swap    & (if needed)  

\\

\hline

\end{tabular}

\caption{Example of hard-disk partitioning.}

\label{t:hd-partitioning}

\end{table}

\textbf{IMPORTANT:} The FreeDOS partition must be the FIRST partition

on your disk or you should experience some problems while booting

FreeDOS.

Since \texttt{fdisk} creates all the partitions as Linux partitions,

you must toggle the partition type of the 2nd partition to make it a

FAT32 (LBA) or NTFS.

\textbf{SUGGESTION:} Do leave all the other partition as Linux type,

so that Windows$^{TM}$ will put all the booting stuff into the only

partition that it can see at installation time.

Now, reboot and install Windows$^{TM}$ into the only partition that

is available for it. I only tested the 2000 and XP versions of

Windows. If you want to install previous Windows$^{TM}$ versions (98

or 95) I'm not sure that they will be able to boot if they are not

installed into the first partition. However if you want to use them,

you can skip the installation of FreeDOS, since you can use the

MS-DOS shell to run Shark programs.

After the installation of Windows$^{TM}$, boot Knoppix again and use

\texttt{fdisk} to change the partition type of the 1st partition:

toggle it as FAT32 (LBA) - suggested - or FAT16 if you want to test

the filesystem capabilities of Shark.

Do format the 1st partition using the Windows formatting program.

Install FreeDOS. You can download all the packages from

\begin{center}

\underline{http://www.freedos.org}.

\end{center}

I suggest to download the packages and to copy them manually into the

partition, avoiding the Installation CD or floppy. You can also use a

S.Ha.R.K. boot CD to copy the whole FreeDOS tree onto the disk.

Make a FreeDOS boot floppy using the \texttt{sys} command, executing

a command like

\begin{center}

\texttt{sys a:}

\end{center}

Copy also the \texttt{sys.com} FreeDOS program on the floppy.

Reboot the machine leaving the floppy into the drive and launch the

command

\begin{center}

\texttt{sys x: x:$\backslash$fdosboot.img}   % check the backslash

\end{center}

\textbf{ATTENTION:} "x:" refers to the drive letter of the partion in

which FreeDOS has been installed, as seen by FreeDOS after the boot

from floppy (check which is the right drive letter by listing the

content of the drives with "dir x:").

What you did is to created an image of the boot sector which is able

to boot FreeDOS, but instead of overwriting the Master Boot Record

(MBR), you writed it onto the disk.

Now insert the Linux intallation disk, reboot the PC and install

Linux. After the installation, the GRUB boot manager should be

installed in your MBR (I did not tested other boot managers, like

LILO).

Look for the configuration file of the GRUB, \texttt{grub.conf}, that

is

often placed into the \texttt{/boot/grub} directory. The lines to

boot Linux are usually added automatically by the installer. The

lines to boot Windows$^{TM}$ look like the following

\begin{verbatim}

title Win2000

rootnoverify (hd0,1)

chainloader +1

\end{verbatim}

Then, add the lines to boot FreeDOS:

\begin{verbatim}

title FreeDOS - Shark

rootnoverify (hd0,0)

makeactive

chainloader /fdosboot.img

boot

\end{verbatim}

Now you are ready to install the S.Ha.R.K. distribution following the

instructions of Section \ref{sec:platform-install}.

%------------------------------------------------------------

\section{Kernel and applications}

\label{sec:kernel-apps}

%------------------------------------------------------------

S.Ha.R.K. currently supports the PC platform (Intel$^{TM}$ or

AMD$^{TM}$ processors, etc.). Using the S.Ha.R.K. kernel is easy. Few

tools are required to build the kernel, to develop new applications

and to run existing or new applications.

%------------------------------------------------------------

\subsection{Building kernel and applications}

\label{sec:build-kernel}

%------------------------------------------------------------

S.Ha.R.K. is written in C, so it requires a C compiler to build the

system from the source code. Currently, S.Ha.R.K. supports the

\texttt{GCC version 3.3}, which is the standard compiler and is

already present in most of the Linux distributions.

\textbf{ATTENTION:} the \texttt{GCC version 3.4} does not properly

work while building the system or compiling user programs. You can

check your GCC version by typing

\begin{center}

\texttt{gcc -v}

\end{center}

into a Linux console.

Windows$^{TM}$ or FreeDOS come without their own C compiler. There

exist a version of the GCC which runs under FreeDOS, and

Windows$^{TM}$ too, called DJGPP and available at

\begin{center}

\underline{http://www.delorie.com/djgpp}.

\end{center}

However, the DJGPP version downloadable from the DJ Delorie website

it is not suitable to be used with S.Ha.R.K. since it produces the

COFF\footnote{See

\underline{http://www.theparticle.com/cs/bc/os/elfpecoff.html}

for some information on executable file formats.} executable file

format only. S.Ha.R.K. needs a compiler which has to be able to

produce the ELF file format. This is why the DJGPP has been rebuilt

in order to produce the ELF format.

\textbf{ATTENTION:} you must download the correct DJGPP version from

the S.Ha.R.K. website.

%------------------------------------------------------------

\subsection{Executing applications}

\label{sec:execute-app}

%------------------------------------------------------------

There are two options to run a new application or one of the demos

distributed with S.Ha.R.K.:

\begin{itemize}

\item using the X.EXE DOS memory extender;

\item loading the application from the GRUB boot manager.

\end{itemize}

Using X.EXE, which is available on the S.Ha.R.K. website, requires an

xDOS platform. Supported platforms are FreeDOS and MS-DOS$^{TM}$. In

the latter case, however, an application can be run using X.EXE only

from a Windows$^{TM}$ 95, Windows$^{TM}$ 98 and Windows$^{TM}$ 95SE

DOS console.

\textbf{ATTENTION:} Windows$^{TM}$ Millennium/ NT/2000/ XP consoles

can not be used to run S.Ha.R.K. applications.

Using the GRUB is more complicated and, since it is particularly

useful

for the remote execution of S.Ha.R.K. programs, this topic will be

covered in a dedicated section.

%------------------------------------------------------------

\subsection{Getting a DOS environment for executing S.Ha.R.K.

applications}

\label{sec:environment}

%------------------------------------------------------------

To execute a S.Ha.R.K. application a DOS environment is required, and

several options are available to get it:

\begin{itemize}

\item

an hard-disk can be partitioned and formatted for multi-boot, and a

partition can be reserved to FreeDOS. This may be a tricky way, and

it is suggested only if the users has a good knowledge of the

involved operations. It is particularly useful to setup the

workstations in school and university laboratories.

\item

re-booting a machine every time an execution of a S.Ha.R.K.

application is needed with the S.Ha.R.K. boot CD or the boor floppy

available on the S.Ha.R.K. website.

The second option needs some more indications. When the machine

restarts, a FreeDOS environment is made available. This means that it

is possible to launch the X.EXE extender to run a S.Ha.R.K.

application. The application itself should be put on the floppy or,

anyway, it MUST be put on a partition with a filesystem reachable by

the FreeDOS kernel. At the best of my knowledge, FreeDOS currently

supports FAT16 and FAT32 filesystems only. So that, an application

which is stored that resides on a NTFS (Windows$^{TM}$), ext2, ext3,

ReiserFS or other Linux filesystems can not be executed using the

boot from floppy or CD.

\end{itemize}

%------------------------------------------------------------

\chapter{Using S.Ha.R.K.}

\label{ch:using}

%------------------------------------------------------------

%------------------------------------------------------------

\section{Your first S.Ha.R.K. application}

\label{sec:first-app}

%------------------------------------------------------------

A typical S.Ha.R.K. application is composed by 3 main components: the

\texttt{program} source file, the initialization source file

(\texttt{initfile}) and the \texttt{makefile}.

%------------------------------------------------------------

\subsection{The makefile}

\label{sec:makefile}

%------------------------------------------------------------

The makefile is the script used by the \texttt{make} command to build

the application. Typically, the makefile is named "makefile", and you

can build the application by simply launching the command

\texttt{make} from the command line. However, the makefile may be

named differently in order, for example, to maintain different make

settings into the same directory. With a makefile named "myapp.mak",

the application can be built typing the command \texttt{make -f

myapp.mak}.

\textbf{IMPORTANT:} To build an application, you can not launch the

compiler directly without using the makefile, since the makefile sets

several variables and calls several sub-routines before invoking the

compiler.

\begin{figure}

\noindent

\newcounter{alines}

\begin{list}{\arabic{alines}}{\usecounter{alines}}

\addtolength{\parskip}{-8pt}

\hrule

\item ifndef BASE \label{l1:ifndef}

\item BASE=../.. \label{l1:def-base}

\item endif \label{l1:endif}

\item include \$(BASE)/config/config.mk \label{l1:inc-config}

\item PROGS = myapp \label{l1:prog-name}

\item include \$(BASE)/config/example.mk \label{l1:inc-example}

\item myapp: \label{l1:build-cmd}

\item \ \ \ \ make -f \$(SUBMAKE) APP=myapp INIT=

OTHEROBJS="initfile.o source2.o source3.o" OTHERINCL=

SHARKOPT="\_\_LINUXC26\_\_ \_\_PCI\_\_ \_\_INPUT\_\_ \_\_FB\_\_"  

\label{l1:make-instr}

\end{list}

\hrule

\caption{Example of makefile.}

\label{f:ex-makefile}

\end{figure}

The makefile contains some directives to specify the application

name, source file names and libraries needed for building the

application. Figure \ref{f:ex-makefile} shows an example of makefile

for building an application called \texttt{myapp}, thus contained

into the source file \texttt{myapp.c}. The application code is also

contained into two source files: \texttt{source1.c},

\texttt{source2.c}. For each of those files, the compiler produces an

\texttt{object file}, with the ".o" extension. The object files

required for making the application must be specified with the

OTHEROBJS directive into the instruction at line \ref{l1:make-instr}.

Notice that, since also the initfile contains the application source

code (Section \ref{sec:initfile}), you must include the related

object file name into the OTHEROBJS directive.

To customize the makefile in order to build your own application, you

must supply the program name at lines \ref{l1:prog-name} and

\ref{l1:make-instr}, and the same name should be used for the

instruction at line \ref{l1:build-cmd}.

At line \ref{l1:def-base}, you specify the path where the S.Ha.R.K.

kernel has been installed. Althought you can specify an absolute path

like \texttt{/home/username/shark} for Linux or \texttt{c:$\backslash$shark},

typically a relative path is used. In Figure \ref{f:ex-makefile}, the

instruction at line \ref{l1:def-base} says that the base S.Ha.R.K.

directory is located two levels before the application directory. For

example, if S.Ha.R.K. has been installed into

\begin{center}

\texttt{/home/toolleeo/shark},

\end{center}

the application is located into

\begin{center}

\texttt{/home/toolleeo/shark/projects/apps}.

\end{center}

The BASE directory in the example is relative to the current

application directory. This works fine if the application directory

is under the S.Ha.R.K. derictory tree. If the application stays

outside the system tree, you can use an absolute indication of the

S.Ha.R.K. base directory, such as \texttt{/home/toolleeo/shark} instead of

\texttt{../..}.

Finally, the instruction at line \ref{l1:make-instr} specifies also

the libraries that must be linked together the object code to build

the whole application. In the example, the application uses the Linux

2.6 compatibility layer, which is always required when the drivers

are used, the PCI driver, the Input driver (to manage the input

devices like keyboard, mouse, etc.) and the Frame Buffer driver for

the graphical display. The list of all the available libraries can be

found into the \texttt{\$(BASE)/lib} directory, where

\texttt{\$(BASE)} is the S.Ha.R.K. installation directory.

\textbf{ATTENTION:} when modifying the makefile, be sure to use a

text editor which saves the TAB character and avoids editors (often

you can configure this option into the editor preferences) which

substitute TAB characters with spaces. This is important because

instruction \ref{l1:make-instr} MUST be indented with a TAB

character. Otherwise, the \texttt{make} command will not be able to

interpret the makefile correctly.

%------------------------------------------------------------

\subsection{The initfile}

\label{sec:initfile}

%------------------------------------------------------------

The initfile is a normal source file which contains the instruction

for the program initialization. Initfiles include the system

headers, initialize modules regarding the scheduling policies for

tasks and shared resources, the graphical mode if needed, the

keyboard and all the required devices.

When the application is launched, before starting the multitasking

mode the program must initialize the devices, the resources and the

schedulers which will be used by the application. For doing so, the

kernel calls the \texttt{\_\_kernel\_register\_levels\_\_} function, that

usually registers the following modules (see the S.Ha.R.K. Kernel

architecture Manual for more details):

\begin{itemize}

\item scheduling modules: a scheduling module implements a particular scheduling

algorithm, for example EDF, RM, Round Robin, etc.;

\item resource Modules: a resource module implements a shared resource access

protocol (for example the semaphores, the mutexes, etc.);

\item other devices, such for example the file system, and other devices that

has to be initialized before entering the multitasking mode.

\end{itemize}

%------------------------------------------------------------

\subsection{The program}

\label{sec:program}

%------------------------------------------------------------

The program file is the source file containing the \texttt{main}

function

\begin{center}

\texttt{int main(int argc, char **argv)}

\end{center}

The main function is automatically called by the kernel when the application is

launched through the X memory extender or the GRUB. The main functions contains

the declarations for - or calls the routine to initialize - the user tasks, the

keyboard handler and all the components required by the application.

%------------------------------------------------------------

\section{Tips and tricks}

\label{sec:tips}

%-----------------------------------------------------------

%------------------------------------------------------------

\subsection{The BASE directory}

\label{sec:base-dir}

%------------------------------------------------------------

S.Ha.R.K. uses the BASE variable to identify the directory where the

system directory tree starts. For example, a typical installation

under Linux may be under \texttt{/home/username/shark}; under FreeDOS the

path would be ``c:$\backslash$shark''.

Unfortunately, the OSLib component of S.Ha.R.K., which is developed

separately from S.Ha.R.K., also requires to set a variable named BASE

when building. Recalling the previous examples, the BASE values for

the OSLib will be \texttt{/home/username/shark/oslib} and

\texttt{c:$\backslash$shark$\backslash$oslib}.

A problem during the kernel compilation arises if the BASE variable

is set into the OS environment\footnote{At the FreeDOS command line,

type ``\texttt{set}'' to get the content of the environment.}.

\textbf{IMPORTANT}: when compiling S.Ha.R.K., be sure that BASE is

not set environment variable to get no problem\footnote{At the

FreeDOS command line, type ``\texttt{set BASE=}'' to remove an

already set BASE variable.}.

During the application development, thus when S.Ha.R.K. is already

built and you do not need to rebuild the kernel, you may set BASE to

point to the S.Ha.R.K. base directory. In this sistuation, you can

move the application source code around your filesystem without

changing the BASE definition into the makefile. See Section

\ref{sec:makefile} for an overview on the S.Ha.R.K. makefiles.

However, you should avoid this practice; you should prefer to set

correctly the BASE directory into the makefile for each project you

are working at.

%------------------------------------------------------------

\subsection{Text output}

\label{sec:text-output}

%------------------------------------------------------------

There are few things to know for using the S.Ha.R.K.'s functions to

display text. Four functions should be used for a safe text output

management:

\begin{itemize}

\item

\texttt{sprintf()} to write a formatted string into a generic text

buffer (e.g., an array of chars);

\item

\texttt{cprintf()} for the regular text output while the application is in

text mode;

\item

\texttt{grx\_text()} for the text output when the application is in

graphical mode (to be used together with \texttt{sprintf()}, which generates

the string to be displayed);

\item

\texttt{printk()} for displaying strings in text mode into the kernel

and modules for debug purposes.

\end{itemize}

%------------------------------------------------------------

\subsection{I/O to the filesystems}

\label{sec:filesystem}

%------------------------------------------------------------

S.Ha.R.K. currently supports only FAT16 filesystems on IDE drivers.

This means that, while the kernel is running, only FAT16 filesystems

could be accessed from the application.