\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.
However, typically, read/write operations to the filesystem can be
done at the beginning or at the end of the application, to load
initial parameters or data and to save the results (which could be
contained in a memory buffer filled during the application
execution). To do so, do use the functions listed into
\texttt{include/ll/i386/x-dos.h}, and allow the user to read and
write binary and text files.
The difference between the full support of FAT16 filesystems and the
functions of the \texttt{x-dos} library is that, while the former is
a true driver which accesses the hard-disk hardware, the latter are
hooks to DOS INT 21h functions. Since DOS INT 21h are not reentrant
(basically, they can not be interrupted by the kernel), they can not
be used while real-time tasks are running.
% For more informations, see demos/dosfs/README.
% Tool: wait till demos are ok
%
%------------------------------------------------------------
\subsection{DJGPP and DOS utils}
\label{sec:dos-utils}
%------------------------------------------------------------
The DJGPP, the compiler used by S.Ha.R.K. under DOS, does not include
any replacement for some Unix commands required to build S.Ha.R.K.,
like
\texttt{cp}, \texttt{rm}, \texttt{mv}, etc. Those comands can be
found easily in the Internet, but it is safer to use the ones
included into the S.Ha.R.K. package.
Someone may already have its own set of command replacements. This
may produce several problems, since different implementations manages
differently the special command options. This is why S.Ha.R.K. is
guaranteed to correctly build with the tested commands only (the
Linux versions are all right).
Short anecdote\footnote{I add this anecdote since it may help in
solving similar problems.}. The first version of the S.Ha.R.K.
bootable CD included the correct commands got from the S.Ha.R.K.
distribution package. It also included another version that is put
into the ``
$\backslash$fdos
$\backslash$bin'' directory. Both the
versions of the commands were reacheable through the PATH environment
variable. However, for a mistake, the FreeDOS path was inserted into
the PATH variable before the correct S.Ha.R.K. path, making S.Ha.R.K.
using the wrong commands. Results: the makefiles were invoking the
wrong command versions, producing several problems while building
kernel and applications.
%------------------------------------------------------------
\section{From version 1.4 to 1.5}
\label{sec:from14to15}
%------------------------------------------------------------
From the user point of view, few things are changed from the
S.Ha.R.K. 1.4 version to the current 1.5 version. The changes that
make an application developed for version 1.4 incompatible with the
1.5 version are only two:
\begin{enumerate}
\item
to make the new version compatible with the POSIX standard, functions
\texttt{sys\_end()} and \texttt{sys\_abort()} have been replaced by
the \texttt{exit(.)} function, which accepts an integer exit code
parameter.
\item
the S.Ha.R.K. directory tree has been slightly changed.
\end{enumerate}
The main effect of the changes to the tree are that an application
initfile now requires slightly different instructions to include the
needed modules. A comparison of the instructions required for the two
S.Ha.R.K. versions is depicted in Table \ref{t:initfile}.
\begin{table}[ht]
\centering
\begin{tabular}{|l|l|}
\hline
Version 1.4 & Version 1.5
\\
\hline
\#include "kernel/kern.h" & \#include "kernel/kern.h"
\\
\#include "modules/intdrive.h" & \#include
"intdrive/intdrive/intdrive.h" \\
\#include "modules/edf.h" & \#include "edf/edf/edf.h"
\\
\#include "modules/cbs.h" & \#include "cbs/cbs/cbs.h"
\\
\#include "modules/rr.h" & \#include "rr/rr/rr.h"
\\
\#include "modules/dummy.h" & \#include "dummy/dummy/dummy.h"
\\
\#include "modules/sem.h" & \#include "sem/sem/sem.h"
\\
\#include "modules/hartport.h" & \#include
"hartport/hartport/hartport.h" \\
\#include "modules/cabs.h" & \#include "cabs/cabs/cabs.h"
\\
\#include "modules/pi.h" & \#include "pi/pi/pi.h"
\\
\hline
\end{tabular}
\caption{The differences between inifiles in S.Ha.R.K. 1.4 and 1.5.}
\label{t:initfile}
\end{table}
%------------------------------------------------------------
\section{Remote execution of S.Ha.R.K. applications}
\label{sec:remote-execution}
%------------------------------------------------------------
S.Ha.R.K. supports the Multiboot
\footnote{See
\underline{http://www.gnu.org/software/grub/manual/multiboot/} for
more information.} standard. This means that it is possible to launch
remotely a S.Ha.R.K. application from, for example, the
GRUB\footnote{See \underline{http://www.gnu.org/software/grub/} for
more information.} boot loader.
Since this Section will describe how to boot a S.Ha.R.K. application
using the GRUB, let's say something more about it, and boot loaders
in general.
In very simple words, boot loaders are programs that, taking the
control of the machine after the system start-up, launch the
operative system kernels. Boot loaders are particularly useful
because they let you choose between different operative systems to
start. Section \ref{sec:hd-installation} illustrated how to partition
an hard-disk
to install more than one OS. This Section will describe how to load a
kernel (in our case, a S.Ha.R.K. application) from the network and
run it on a remote machine.
An example will explain the installation procedure and how to use
this mechanism.
%------------------------------------------------------------
\subsection{General setup}
\label{sec:remote-setup}
%------------------------------------------------------------
Suppose that there are two machines: computer A, where you develop
your S.Ha.R.K. applications using the Linux platform, and computer B,
where you want to execute the application.
Computer A needs:
\begin{itemize}
\item an Ethernet connection with B;
\item Linux;
\item an installed and properly configured version of S.Ha.R.K.;
\item a TFTP server.
\end{itemize}
Computer B needs:
\begin{itemize}
\item an Ethernet connection with A;
\item an installation of the GRUB with network support.
\end{itemize}
%------------------------------------------------------------
\subsection{Computer A setup}
\label{sec:A-setup}
%------------------------------------------------------------
There are two important things to setup on machine A. First of all,
the S.Ha.R.K. kernel must be compiled with the option BIOS set to
VM86 (Virtual Memory for x86) into the shark.cfg configuration file.
This ensures that the application will be compiled with the support
for the multiboot.
\textbf{ATTENTION}: as stated in the configuration file, the VM86
mode is not compatible with some VGA cards (like Matrox).
A TFTP server must be installed on computer A, to let B download the
application. TFTP means Trivial File Transfer Protocol; it is a
simplified version of FTP which permits only basic operations like
download and upload (no directory management, etc.). Moreover, it
works over the UDP protocol, while FTP works over TCP. Almost all
Linux distribution have a TFTP server. I will not discuss how to
install and run it. The only important thing to know is that,
typically, the server lets a remote machine to download a program
from a specific directory (e.g., /tftpboot/). The compiled S.Ha.R.K.
program will be put into that directory.
%------------------------------------------------------------
\subsection{Computer B setup}
\label{sec:B-setup}
%------------------------------------------------------------
First of all, let's build the GRUB for supporting the network.
Currently, the GRUB 2 is under development. I only tested the remote
execution with S.Ha.R.K. using the so called the GRUB Legacy, which
is still available.
Download the GRUB Legacy from
\begin{center}
\underline{ftp://alpha.gnu.org/gnu/grub/}
\end{center}
Since I only tested the behavior of the \texttt{grub-0.97.tar.gz}
package, I suggest to use this version.
After unpacking the sources on a Linux machine with
\begin{center}
\texttt{tar -xvzf grub-0.97.tar.gz}
\end{center}
you will get the \texttt{grub-0.97} directory. Do get into it using
\begin{center}
\texttt{cd grub-0.97}
\end{center}
and configure the GRUB with a command like
\begin{center}
\texttt{./configure --enable-via-rhine --disable-ffs --disable-minix
--disable-reiserfs --disable-xfs --disable-ufs2 --disable-vstafs}
\end{center}
This instruction simply configures the GRUB to support a VIA network
board (Rhine model) and turned off the support for many filesystems,
like FFS, Minix, XFS and others.
Of course, if you have a different network board, you need to enable
the correct one. You can find a list of the supported network boards
under the directory \texttt{grub-0.97/netboot}, into the
\texttt{README.netboot} file. The GRUB developers sugget to not
enable too many network cards all together for stability
problems\footnote{This may be the reason because it is not safe to
build a copy of the GRUB with the native support of all the available
network cards.}. For the same reason, all the unused filesystems have
been disabled. The above configuration assume that the GRUB files
stay into a directory called \texttt{/boot/grub}, which is into an
ext2/ext3 filesystem. If your \texttt{/boot/grub} directory on a
filesystem of different type, you must enable the support for that
specific filesystem.
After the GRUB configuration has been correctly performed, type
\begin{center}
\texttt{make}
\end{center}
to launch the build of the GRUB.
After the compilation, you will find two files, \texttt{stage1} and
\texttt{stage2}, into two separate directories with the same name.
You must copy the two files into the \texttt{/boot/grub} directory of
computer B. Before copying the files, do make a backup copy of the
existing \texttt{stage1} and \texttt{stage2}. This step assumes that
the GRUB is already installed on computer B, which is typically done
when you install Linux on a PC: we only want to enhance the GRUB to
support the network boot.
Then, add the following lines to the \texttt{menu.lst} script file
into the \texttt{/boot/grub} directory:
\begin{verbatim}
ifconfig --address=192.168.0.2 --mask=255.255.255.0
tftpserver 192.168.0.1
rootnoverify (nd)
kernel /shark
boot
\end{verbatim}
Where 192.168.0.2 is the IP address assigned to computer B and
192.168.0.1 is the IP address of computer A. Change those values to
accomplish with the need of your local network\footnote{For example,
avoiding duplicated IP addresses.}.
Finally, reboot the machine and, at the GRUB prompt, type
\texttt{c} to get the commad line of the GRUB, and type the
command
\begin{center}
\texttt{install (hd0,2)/boot/grub/stage1 (hd0)
(hd0,2)/boot/grub/stage2 0x8000 (hd0,2)/boot/grub/menu.lst}
\end{center}
This instruction install the GRUB into the Master Boot Record of your
hard-disk. Typing \texttt{(hd0,2)} you specify that the
\texttt{/boot/grub/} directory stays into the 3rd partition of your
first hard-disk. You must change this value if the directory is into
another partition or another disk\footnote{While \texttt{hd1}
identifies the 2nd disk, \texttt{hd2} the 3rd, etc., \texttt{(hd0,0)}
is the 1st partition of the 1st disk, \texttt{(hd0,1)} is the 2nd
partition of the 1st disk and so on. This is a convention of the
GRUB.}.
%------------------------------------------------------------
\subsection{Executing S.Ha.R.K. application}
\label{sec:execution}
%------------------------------------------------------------
After the setup of the GRUB and the TFTP server, you are able to run
a S.Ha.R.K. application by compiling the application and copying it
into the TFTP base directory (e.g.,
\texttt{/tftpboot}) and calling
it \texttt{shark}. This is required because, after the configuration
of \texttt{menu.lst} described in Section \ref{sec:B-setup}, the GRUB
will look for a Multiboot kernel named \texttt{shark}.
Every time you reboot computer B, it will automatically look for the
\texttt{shark} multiboot image to run it. To speed up the GRUB
operations, you should set the remote S.Ha.R.K. application execution
as the default option and, optionally, do set a low number of seconds
for the GRUB initial waiting time.
There are some drawbacks of the previous installation. First, the
S.Ha.R.K. application name must be \texttt{shark}; you may change
that name, however the point is that you must change the
\texttt{menu.lst} to use different names. Second, the S.Ha.R.K.
application can not use the filesystem to read and write data, so do
not put any I/O command to file into an application remotely
executed. Finally, the S.Ha.R.K. application can not accept command
line parameters.
%------------------------------------------------------------
\subsection{Accepting command line parameters}
\label{sec:command-line-parameters}
%------------------------------------------------------------
To make a remotely executed S.Ha.R.K. application to accept command
line parameters you can exploit a feature of the GRUB which allows to
remotely load a configuration file from the TFTP server.
To obtain this result, put the following instruction into the
\texttt{menu.lst} file on computer B:
\begin{verbatim}
ifconfig --address=192.168.0.2 --mask=255.255.255.0
tftpserver 192.168.0.1
rootnoverify (nd)
configfile /menu-remote.lst
\end{verbatim}
The last instruction tells to the GRUB to download the
\texttt{menu-remote.lst} configuration file from the TFTP server.
Put a file named \texttt{menu-remote.lst} into the TFTP base
directory of computer A (\texttt{/tftpboot/}). Put the following
instructions unto the \texttt{menu-remote.lst}:
\begin{verbatim}
kernel /shark-app param1 param2 param3
boot
\end{verbatim}
In this way, by editing the \texttt{menu-remote.lst} on the machine
where you are developing your S.Ha.R.K. applications, you are able to
change the name of the S.Ha.R.K. application that will be looked for
by the GRUB. Moreover, you can use as many command line parameters as
needed when the S.Ha.R.K. application starts.
\bibliographystyle{alpha}
\bibliography{../common/biblio}
\end{document}