%----------------------------------------------------------------------------
\chapter{Utility functions}
%----------------------------------------------------------------------------
S.Ha.R.K. provides a set of utility functions aimed at getting information
about the kernel state. Mainly, they allow a user to get the actual
system time and some information concerning the tasks' state. Moreover,
it allows to set exception handlers and to manage interrupts.
%----------------------------------------------------------------------------
\section{Reading time}
%----------------------------------------------------------------------------
The S.Ha.R.K. Kernel does not have the concept of tick. Every time
interval and every absolute time in the system is measured usin the
Real-Time Clock available on the PC. To read the current time you
can use the following function:
%----------------------------------------------------------------------------
\begin{intest}
SYS\_GETTIME\index{sys\_gettime()}
\end{intest}
\begin{description}
\item [\texttt{TIME sys\_gettime(struct timespec *t);}]
\item [Description:]It returns the number of microseconds elapsed from
system's initialization, that is from the end of the \texttt{\_\_kernel\_register\_levels\_\_}
function. If the \texttt{t} value is not equal \texttt{NULL}, the
function fills also the timespec structure passed as parameter.
\end{description}
%----------------------------------------------------------------------------
\section{Getting information on tasks}
%----------------------------------------------------------------------------
Since all the tasks are handled by a Module, it is a responsibility of each
Module to hide or not hide informations about the tasks handled by the system.
However, at the moment S.Ha.R.K. provides a function that simply prints the
tasks state on the console
\footnote{Old versions of the kernel supported a
\texttt{void sys\_status(DWORD cw);} \index{sys\_status()}primitive. That
primitive is currently unsupported.}.
\pagebreak
%----------------------------------------------------------------------------
\begin{intest}
PERROR\index{perror()}
\end{intest}
\begin{description}
\item [\texttt{void perror (const char *s);}]
\item [Description:]This is the POSIX \texttt{perror()} funcion, that prints
on the console (using \texttt{kern\_printf}) a message that explain
the meaning of the \texttt{errno} \index{errno} variable. Note that
each task has its own \texttt{errno} variable, as specified by the
\texttt{POSIX} standard.
\end{description}
%----------------------------------------------------------------------------
\begin{intest}
exec\_shadow\index{exec\_shadow}
\end{intest}
\begin{description}
\item [\texttt{PID exec\_shadow;}]
\item [Description:]This is the internal variable used by the Kernel to
track the running task. You can read its value to know the PID of
the current task. You CAN NOT modify this variable.
\end{description}
%----------------------------------------------------------------------------
\section{Printing messages on the console}
%----------------------------------------------------------------------------
To print a simple message on the console, please use the c* functions
(cprintf
\index{cprintf}, cputs\index{cputs}, \ldots{}) described
in Volume II. If tou are debugging \emph{the kernel}, you can use
kern\_printf \index{kern\_printf} to print very simple messages without
floating point arithmetic.
%----------------------------------------------------------------------------
\chapter{Signals and Exception Handling}
%----------------------------------------------------------------------------
%----------------------------------------------------------------------------
\section{Signals}
%----------------------------------------------------------------------------
S.Ha.R.K. implements the specification of the signals and of the real-time
signald provided by the standard IEEE 1003.13 POSIX PSE51/PSE52. In
particular, you can use all the functions described into the IEEE
1003.1
\{a,b\} standards, except that:
\begin{itemize}
\item all the \texttt{pid\_t} parameters and in general all parameters related
with processes should be ignored;
\item when in POSIX a signal cause the termination of the process, it causes
in S.Ha.R.K. the termination of the whole system (you can think S.Ha.R.K.
as a single process multithread kernel);
\item The \texttt{siginfo\_t} structure contains an additional parameter
called \texttt{si\_task} of type \texttt{PID}. It contains the \texttt{PID}
of the task that queued a particular real-time signal.
\end{itemize}
In particular, you can use these functions for signal handling: \texttt{kill},
\texttt{sigemptyset}, \texttt{sigfillset}, \texttt{sigaddset},
\texttt{sigdelset}, \texttt{sigismember}, \texttt{sigaction},
\texttt{pthread\_sigmask} \footnote{If you are not using the POSIX scheduling
modules please use \texttt{task\_sigmask}}, \texttt{sigprocmask},
\texttt{sigpending}, \texttt{sigsuspend}, \texttt{sigwait},
\texttt{sigwaitinfo}, \texttt{sigtimedwait}, \texttt{sigqueue},
\texttt{pthread\_kill} \footnote{If you are not using the POSIX scheduling
modules please use \texttt{task\_signal} (Note that \texttt{task\_kill} does not
send any signal, but issue a cancellation request on a task!)}, \texttt{alarm},
\texttt{pause}, \texttt{sleep} (note the difference between \texttt{sleep},
\texttt{task\_sleep} and \texttt{nanosleep}!), \texttt{raise}, \texttt{signal}.
%----------------------------------------------------------------------------
\section{Exception handling\label{ch:except}}
%----------------------------------------------------------------------------
S.Ha.R.K. provides a flexible mechanism to handle the exceptions of the Kernel.
The mechanism is based on the POSIX signals. In fact, S.Ha.R.K. exceptions are
remapped on the real-time signal
\texttt{SIGHEXC} \footnote{see
\texttt{include/signal.h}.} (9). Every time something goes wrong, the system
calls the primitive \texttt{kern\_raise}, that simply queue a real-time signal
of number SIGHEXC.
The user can define its own exception handler simply remapping the SIGHEXC
signal using the POSIX primitive \texttt{sigaction}. To fullfil the typical
usage of an exception handler (exit the system after printing a message), the
default behavior of the signal handler has been redefined to print a text
message on system shutdown. \footnote{Older versions of the Kernel supported two
functions to be used for standard redefinition of the kernel signal handler.
These functions, called SET\_EXCHANDLER\_TXT\index{set\_exchandler\_txt()} and
SET\_EXCHANDLER\_GRX\index{set\_exchandler\_grx()}, are no more supported, and
can be removed from your code without problems.}
Here is a sample code that explain how to redefine a signal handler:
\begin{verbatim}
#include <kernel/kern.h>
void thehandler(int signo, siginfo_t *info, void *extra) {
/* the signal handler:
info.sivalue.sival_int contains the exception number
(see include/bits/errno.h)
info.si_task is the task that raised the exception
extra is not used
*/
...
}
...
int myfunc(...) {
struct sigaction action;
...
action.sa_flags = SA_SIGINFO;
action.sa_sigaction = thehandler;
action.sa_handler = 0;
sigfillset(&action.sa_mask);
sigaction(SIGHEXC, &action, NULL);
...
}
\end{verbatim}
%----------------------------------------------------------------------------
\begin{intest}
KERN\_RAISE\index{kern\_raise()}
\end{intest}
\begin{description}
\item [\texttt{void kern\_raise(int n, PID p);}]
\item [Description:]This function uses the POSIX function sigqueue to put
a signal SIGHEXC into the signal queue. The parameter n is used as
the exception number, and it is passed into the siginfo\_t parameter
(into the sivalue.sival\_int field). The signal appears to be queued
by the task p (the p value is stored into the si\_task field of the
siginfo\_t structure passed as parameter).
\end{description}
%----------------------------------------------------------------------------
\chapter{Interrupt and HW Ports handling}
\label{ch:interr}
%----------------------------------------------------------------------------
Generally speaking, I/O to and from an external peripheral device
can be handled in three different ways depending on the peripheral
type and on the application:
\begin{itemize}
\item \textbf{Polling}: the program cyclically checks the status of the
I/O port, waiting for a input data to be ready or an output data to
be transmittable;
\item \textbf{Interrupt}: the program enables the I/O interface to send
a hardware interrupt every time an input data is available or an output
data is transmittable;
\item \textbf{DMA}: the program enables the interface to use DMA mechaninsm
for directly transferring data to/from memory.
\end{itemize}
\noindent In this chapter we will analyse the support that the S.Ha.R.K.
kernel provides for using the second method (interrupt).
When an interrupt arrives, a code for the hand-shake with the interface
and for transferring data has to be executed. This code can run in
two different modes:
\begin{itemize}
\item it can be entirely encapsulated in a function to be executed immediately
on the interrupt arrival, in the context of the executing task (\textit{fast
handler});
\item it can be entirely encapsulated in a task (\textit{safe handler})
which is activated on the interrupt arrival and scheduled with its
own priority together with the other tasks.
\end{itemize}
\noindent The first method is appropriate when the interrupt needs
a fast response time. Its potential drawback is that if its computation
time is not low, the overall schedulabuility can be severly affected.
This is because the guarantee algorithm does not take into account
the execution time of the interrupt handlers. The second method, on
the contrary, is perfectly integrated with the kernel's scheduling
mechanism, but can cause considerable delays in transferring data.
S.Ha.R.K. provides great flexibility in interrupt handling, since
it allows each interrupt to be associated with a \textit{fast handler},
a \texttt{safe handler}, or both.
On an interrupt's arrival the following operations are performed by
the kernel:
\begin{itemize}
\item The system checks whether a fast handler is associated with the interrupt.
If so, the interrupts are enabled and the handler is invoked. This
method allows a handler to be interrupted by a higher priority handler.
As an example, the keyboard handler (interrupt 1) can be interrupted
be the timer handler (interrupt 0).
\item The system checks whether a sporadic task (\emph{safe handler}) is
associated with the interrupt. If so, the task is activated and is
eligible to run with enabled interrupts.
\end{itemize}
\noindent The system provides a set of functions for accessing the
hardaware interfaces' ports. In the drivers directory you can find
examples of a S.Ha.R.K. device driver.
%----------------------------------------------------------------------------
\section{Setting an interrupt handler}
%----------------------------------------------------------------------------
%----------------------------------------------------------------------------
\begin{intest}
HANDLER\_SET\index{handler\_set()}
\end{intest}
\begin{description}
\item [\texttt{int handler\_set(int no, void (*fast)(int), PID
pi, BYTE lock);}]
\item [Description:]It installs function \texttt{fast} (fast handler) and
the sporadic task \texttt{p} (safe handler) on the interrupt identified
by \texttt{no}. The \texttt{no} parameter must belong to the range
1\ldots{}15 (interrupt 0 is associated to the timer and cannot be
intercepted). On the interrupt's arrival, function \texttt{fast} is
invoked and runs. Depending on the \texttt{lock} flag, the interrupts
are disabled (\texttt{lock} = TRUE) or enabled (\texttt{lock} = FALSE)
during handler execution. Furthermore, on the interrupt's arrival,
task \texttt{p} is activated.
\end{description}
%----------------------------------------------------------------------------
\begin{intest}
HANDLER\_REMOVE\index{handler\_remove()}
\end{intest}
\begin{description}
\item [\texttt{void handler\_remove(int no);}]
\item [Description:]It removes the handler of the interrupt number \texttt{intno};
the interrupt is masked.
\end{description}
%----------------------------------------------------------------------------
\section{Reading and writing from I/O ports}
%----------------------------------------------------------------------------
%----------------------------------------------------------------------------
\begin{intest}
INP, INPW, INPD \index{inp()} \index{inpw()} \index{inpd()}
\end{intest}
\begin{description}
\item [\texttt{unsigned char inp(unsigned short \_port);}]
\item [\texttt{unsigned short inpw (unsigned short \_port);}]
\item [\texttt{unsigned long inpd(unsigned short \_port);}]
\item [Description:]They return the data read on port \texttt{\_port}.
\end{description}
%----------------------------------------------------------------------------
\begin{intest}
OUTP, OUTPW, OUTPD \index{outp()} \index{outpw()} \index{outpd()}
\end{intest}
\begin{description}
\item [\texttt{void outp(unsigned short \_port, unsigned char \_data);}]
\item [\texttt{void outpw(unsigned short \_port, unsigned short \_data);}]
\item [\texttt{void outpd(unsigned short \_port, unsigned long \_data)}]
\item [Description:]It writes the data \texttt{\_data} into the port \texttt{\_port}.
\end{description}
%----------------------------------------------------------------------------
\section{Disabling/Enabling interrupts}
%----------------------------------------------------------------------------
%----------------------------------------------------------------------------
\begin{intest}
KERN\_CLI\index{kern\_cli()}
\end{intest}
\begin{description}
\item [\texttt{void kern\_cli(void);}]
\item [Description:]It disables interrupts (as the x86 \texttt{cli} instruction).
\end{description}
%----------------------------------------------------------------------------
\begin{intest}
KERN\_STI\index{kern\_sti()}
\end{intest}
\begin{description}
\item [\texttt{void kern\_sti(void);}]
\item [Description:]It enables interrupts (as the x86 \texttt{sti} instruction).
\end{description}
%----------------------------------------------------------------------------
\section{Saving/Restoring interrupts}
%----------------------------------------------------------------------------
%----------------------------------------------------------------------------
\begin{intest}
KERN\_FSAVE\index{kern\_fsave()}\index{SYS\_FLAGS}
\end{intest}
\begin{description}
\item [\texttt{SYS\_FLAGS kern\_fsave(void);}]
\item [Description:]It disables interrupts (as the x86 \texttt{cli} instruction).
The CPU flags are returned by the function; in that way they can be
restored using kern\_frestore
\end{description}
%----------------------------------------------------------------------------
\begin{intest}
KERN\_FRESTORE\index{kern\_frestore()}
\end{intest}
\begin{description}
\item [\texttt{void kern\_frestore(SYS\_FLAGS f);}]
\item [Description:]It restores the interrupt state as it was when the
correspondent \texttt{kern\_fsave} was called.
\end{description}
%----------------------------------------------------------------------------
\section{Masking/Unmasking PIC interrupts}
%----------------------------------------------------------------------------
%----------------------------------------------------------------------------
\begin{intest}
IRQ\_MASK\index{irq\_mask()}
\end{intest}
\begin{description}
\item [\texttt{void irq\_mask(WORD irqno);}]
\item [Description:]It mask the interrupt number \texttt{irqno} on the
PC PIC. \texttt{irqno} must be in the interval {[}1..15{]}.
\end{description}
%----------------------------------------------------------------------------
\begin{intest}
IRQ\_UNMASK\index{irq\_unmask()}
\end{intest}
\begin{description}
\item [\texttt{void irq\_unmask(WORD irqno);}]
\item [Description:]It unmask the interrupt number \texttt{irqno} on the
PC PIC. \texttt{irqno} must be in the interval {[}1..15{]}.
\end{description}
%----------------------------------------------------------------------------
\chapter{Memory Management Functions}
%----------------------------------------------------------------------------
The S.Ha.R.K. Kernel provides the standard set of memory allocations
functions provided by the Standard C libraries. In particular, the
functions listed in figure
\ref{fig:malloc} can be used.
\begin{figure}
\begin{center} \fbox{\tt{ \begin{minipage}{6cm} \begin{tabbing}
123\=123\=123\=\kill
\#include <stdlib.h>\\
void *calloc(size\_t nmemb, size\_t size);\\
void *malloc(size\_t size);\\
void free(void *ptr);\\
void *realloc(void *ptr, size\_t size);\\
\end{tabbing} \end{minipage} }} \end{center}
\caption{\label{fig:malloc}Memory allocation functions.}
\end{figure}
In particular \footnote{These descriptions came directly from the Linux man pages...}:
\begin{itemize}
\item calloc() allocates memory for an array of nmemb elements of size bytes
each and returns a pointer to the allocated memory. The memory is
set to zero. The value returned is a pointer to the allocated memory,
which is suitably aligned for any kind of variable, or NULL if the
request fails.
\item malloc() allocates size bytes and returns a pointer to the allocated
memory. The memory is not cleared. The value returned is a pointer
to the allocated memory, which is suitably aligned for any kind of
variable, or NULL if the request fails.
\item free() frees the memory space pointed to by ptr, which must have been
returned by a previous call to malloc(), calloc() or realloc(). Otherwise,
or if free(ptr) has already been called before, undefined behaviour
occurs. If ptr is NULL, no operation is performed.
\item realloc() changes the size of the memory block pointed to by ptr to
size bytes. The contents will be unchanged to the minimum of the old
and new sizes; newly allocated memory will be uninitialized. If ptr
is NULL, the call is equivalent to malloc(size); if size is equal
to zero, the call is equivalent to free(ptr). Unless ptr is NULL,
it must have been returned by an earlier call to malloc(), calloc()
or realloc(). It returns a pointer to the newly allocated memory,
which is suitably aligned for any kind of variable and may be different
from ptr, or NULL if the request fails or if size was equal to 0.
If realloc() fails the original block is left untouched - it is not
freed or moved.
\end{itemize}
The S.Ha.R.K. Kernel also provides a set of low-level memory management
functions that can be used to allocate memory with particular requirements
(for example, they are useful for getting memory blocks aligned to
a page (4 Kb) boundary or with addresses under 1/16 Mb). Description
of these functions is given in Chapter 3 of the S.Ha.R.K. Architecture
Manual.