/usrman/trunk/running/running.tex |
---|
0,0 → 1,147 |
\chapter{Running HelenOS} |
\section{Kernel Start} |
When the HelenOS kernel starts up, it configures its output device |
and starts booting. During the boot process it writes out some some |
lines regarding memory size and available CPUs. The userspace |
drivers and tasks take over the console as soon as the start-up activities are finished. |
When kernel tests are compiled in, the userspace layer is not started. |
The console driver provides 12 virtual consoles, 11 are used |
for applications, console 12 is reserved for kernel console. Pressing |
function keys F1-F12 switches between the consoles. |
If the architecture supports framebuffer device with |
at least 800x600 resolution, a nice graphical console is shown. At the top |
of the screen, a row of buttons for the virtual console is drawn. If |
the button contains console number, an application is connected to it. |
The red button means that there was an activity on the terminal |
since it was last shown to the user. |
\section{Kernel Console} |
{\em kconsole} is a kernel thread operating completely in priviledged mode. |
It allows the user to interact directly with the kernel and even start directly |
functions inside the kernel. |
The kernel console is shown by switching to console number 12. On some platforms |
the kconsole screen is not restored to its previous contents. Press |
enter to see {\em kconsole}'s prompt. The function keys for switching terminals |
do not work in the console. In order to switch back to other consoles, use |
the {\em continue} command. After executing the command, press a function key |
to switch to the console of your choice. |
The basic editing facilities are very similar to {\em readline} conventions. |
The left and right arrows, backspace and delete keys allow convenient |
editing of text. The history of last ten commands can be retrieved |
using up and down arrows. The kernel console supports tab completion, double tab |
shows a list of available commands. |
The first class of commands prints useful statistics from the running |
operating systems. The commands are: |
\begin{description} |
\item[zones] --- Prints a list of memory zones. |
\item[zone $<$zone number$>$] --- Prints a detailed statistics about the frame allocator. |
\item[slabs] --- Prints detailed statistics about the slab allocator. |
\item[scheduler] --- Prints out the contents of scheduler run queues for all cpus. |
\item[threads] --- Prints list of existing threads, including information about |
their state. |
\item[tasks] --- Prints list of tasks along with some basic IPC information. |
\item[ipc\_task $<$taskid$>$] --- Prints detailed information about IPC queues of a particular task. |
\item[tlb] --- Prints contents of the Translation Lookaside Buffer on a processor (supported only on some platforms). |
\item[exc] --- Prints table of registered exception handlers. |
\end{description} |
The kernel contains a searchable version of its symbol table. This is used |
in error processing as well as for extending functionality of the kernel console. |
The following commands are supported: |
\begin{description} |
\item[symaddr $<$address$>$] --- Finds an address in symbol table and prints the appropriate |
symbol name. |
\item[call0, call1... $<$function$>$ $<$args...$>$] --- Calls a C function {\em function(args...)}. |
Note that the tab-completion also works for function names. Because |
of architecture calling convention, this command does not work correctly |
on the ia64 platform. The arguments can be specified |
\begin{itemize} |
\item as a number or hexadecimal number: call1 task\_kill 8 |
\item as a string: call1 printf "Hello world" |
\item as a hexadecimal number preceeded by '*'. The argument is then read from |
the given address: call2 printf "%X" *0x8000000 |
\item as a symbol name. In such case, the value located in the memory |
location corresponding to the symbol name is used: call2 printf "%d" task_counter |
\item as a symbol name preceeded by '\&'. The address is used. |
\item as a symbol name preceeded by '*'. In such case, the symbol is dereferenced. |
\end{itemize} |
\item[set4 <address|symbol name>] --- Stores a 4-byte value into a given address. |
\end{description} |
The mips32, ia32 and amd64 platforms provide additional commands regarding |
debugging facility - set and clear hardware breakpoints and watchpoints. |
\section{Kernel Console Task Control} |
The kconsole {\em call} commands can be used to start and kill tasks. |
To repeatably start a task, the following procedure should be used: |
\begin{verbatim} |
.... kernel boot data .... |
init[8].addr=0x8027b000, init[8].size=86016 |
.... rest of boot data ... |
kconsole> call2 task_run_program 0x8027b000 0 |
Calling f(0x8027b000,0): 0x80119283: generic/src/proc/task.o:task_run_program |
Result: 0x80086500 |
\end{verbatim} |
To kill a task, use of the function {\em task\_kill} is appropriate. The {\em taskid} |
parameter is a 64-bit number on all platforms, thus on the 32-bit platforms |
call2 should be used with 2 32-bit parameters instead. |
\begin{verbatim} |
kconsole> call2 task_kill 8 0 |
Calling f(0x8,0x0): 0x801197e8: generic/src/proc/task.o:task_kill |
Result: 0x0 |
\end{verbatim} |
\section{Emergency Functions} |
It may happen that the IPC communication dies or that some |
problems arise in the communication chain |
{\em keboard driver} - {\em console} - {\em output driver}. |
As long as at least the keyboard driver works, pressing Escape key three |
times transfers control to the kernel console immediately. Because the screen is not |
updated, the user should press Enter to see the kconsole prompt. |
If a kernel panic occurs, the error handling automatially switches control |
to the KConsole and allows users to inspect the failed kernel online. |
On the SMP system the other processors are halted immediately. The kernel |
contains its symbol table, so you can probably read some useful information |
about the exact place where the panic occured. |
\section{How to Do a Kernel Panic} |
Kernel panic is extremely rare in HelenOS. However, if the user wishes to |
simulate it, the kernel console contains proper commands. For example, the following |
command simulates a write to the unmapped address 0x4: |
\begin{verbatim} |
kconsole> set4 4 0 |
\end{verbatim} |
To test the autodebugging possibilities of the ia32 platform, the following |
sequence can be executed: |
\begin{verbatim} |
kconsole> bkpts |
0. 0x80032010 in (NULL) |
Count(0) |
kconsole> set4 0x80032010 0 |
**** Found ZERO on address 0x0 **** |
Reached breakpoint 0:0x8011552a(generic/src/console/cmd.o:cmd_set4) |
***Type 'exit' to exit kconsole. |
debug> |
\end{verbatim} |
\section{KLog} |
In order to avoid disturbing the framebuffer driver with kernel messages, a circular |
buffer communication between the kernel and the userspace area is established. |
Non-critical messages are sent to the KLog application. The user can see messages about |
task faults and task cleanup completion. |
\section{IPCC - testing application} |
For the sake of thourough testing of some aspects of task activities, IPCC application |
allows the user to generate faulting behaviour such as page faults and unaligned references\footnote{Some architectures |
do not fault on an unaligned memory reference.}. |
/usrman/trunk/usrman.tex |
---|
0,0 → 1,27 |
\documentclass[onecolumn,twoside,12pt]{report} |
\usepackage[colorlinks=true, pdfstartview=FitV, linkcolor=blue, |
citecolor=blue, urlcolor=blue]{hyperref} |
\usepackage{a4} |
\usepackage{fancyhdr} |
%\pagestyle{fancy} |
\title{ |
\Huge{\bf HelenOS project}\\ |
\LARGE{\it user manual} |
} |
\date{} |
\begin{document} |
\maketitle |
\newpage |
\setcounter{page}{2} |
\newpage |
\addcontentsline{toc}{chapter}{Contents} |
\tableofcontents |
\newpage |
\include{intro/intro} |
\include{building/building} |
\include{boot/boot} |
\include{running/running} |
\end{document} |
/usrman/trunk/intro/intro.tex |
---|
0,0 → 1,24 |
\chapter{Introduction} |
HelenOS is a development operating system intended to |
be a testbed for research in the field of operating |
systems and system-level programming. This manual is |
a guide for building, running and enhancing HelenOS. |
The system, as any other operating system, can be divided |
into platform independent and platform dependent parts. |
A user space program could be written in such |
a way that it can be compiled and executed on any |
of the platforms HelenOS supports without any modifications. |
However it might work as a device driver or perform |
other special tasks and thus become platform dependent. |
\section{Structure of HelenOS} |
The HelenOS operating system consists of three major parts: |
\begin{itemize} |
\item Kernel |
\item User space layer |
\item Boot infrastructure |
\end{itemize} |
/usrman/trunk/building/building.tex |
---|
0,0 → 1,25 |
\chapter{Building HelenOS} |
\section{Requirements} |
To build HelenOS, the following build tools must be installed: |
\begin{itemize} |
\item GCC 4.1.1 + binutils 2.16.1 cross compiler environment for target platform |
\item python 2.3 or higher |
\item GNU make |
\item mkisofs |
\end{itemize} |
The GNU build environment is best downloaded, compiled and installed |
automatically using the shell scripts located in the |
{\em kernel/contrib/toolchain} directory. |
\section{Building} |
HelenOS features a user friendly configuration system. Once |
a {\em make} command is run from the {\em boot/} directory, a |
{\em dialog} driven application is started and the developer is asked several |
questions regarding build configuration parameters. The answers are saved |
in the file {\em Makefile.config} in the boot/, kernel/ and uspace/ |
directories and are automatically used for each subsequent build. |
In order to modify the parameters, the user should change to the particular subsystem |
directory and type {\em make config}. When the build configuration parameters |
are changed, the whole subsystem should be completely rebuilt. The |
configuration system offers to do this automatically for the user. |
/usrman/trunk/boot/boot.tex |
---|
0,0 → 1,133 |
\chapter{Boot Loading Process} |
The startup of HelenOS happens in several steps. |
Depending on the platform, these steps can be either |
described as \textit{piggybacker loading}: |
\begin{enumerate} |
\item Platform boot loader loads the piggybacker image |
and jumps to its entry point. |
\item The piggybacker unwraps the kernel image and |
the images of the initial user space tasks, creates |
a boot information structure and jumps to the |
entry point of the kernel. |
\item The kernel initializes and runs the initial tasks |
according the boot information structure from the |
piggybacker. |
\end{enumerate} |
If the platform supports a more sophisticated native boot loader, |
the \textit{multiboot loading} consists of the following steps: |
\begin{enumerate} |
\item Platform boot loader loads the kernel image and initial |
user space tasks, creates a boot information structure |
and jumps to the entry point of the kernel. |
\item The kernel initializes and runs the initial tasks |
according the the boot information structure from the |
boot loader. |
\end{enumerate} |
A third kind of boot loading occurs on platforms with no support |
from boot loader. It is called \textit{image loading} and is |
used mostly on simulated architectures. |
\begin{enumerate} |
\item The kernel and initial user space images are placed |
on well-known physical memory locations (usually |
by a simulator configuration file). The execution |
starts directly on the kernel entry point. |
\item The kernel initializes and spawns compiled-in |
number of initial user space tasks. |
\end{enumerate} |
The following sections describe the particular features of the |
boot loading process on the supported platforms. Sample |
configuration files for all simulators are in the directory |
{\em kernel/contrib/conf}. |
\section{IA-32 and AMD64} |
On both platforms, HelenOS depends on a boot loader which |
supports the Multiboot Specification (e.g. GRUB). The kernel |
image (usually called \texttt{image.iso}) is loaded by the |
boot loader just above the 1st megabyte of the physical |
memory (the exact location is 1081344 bytes). Modules loaded by |
GRUB are automatically detected by the kernel and after initialization |
they are started as userspace tasks. The GRUB loading is the |
easiest in terms of using userspace tasks. |
An example GRUB configuration file {\em menu.lst}: |
\begin{verbatim} |
title=HelenOS |
root (cd) |
kernel /boot/kernel.bin |
module /boot/ns |
module /boot/init |
module /boot/pci |
module /boot/fb |
module /boot/kbd |
module /boot/console |
module /boot/tetris |
module /boot/ipcc |
module /boot/klog |
\end{verbatim} |
\section{32-bit MIPS} |
The MIPS port is fully supported in the {\em msim} and {\em gxemul} simulators. |
These simulators allow to specify a memory contents of the simulated |
computer. Unfortunately, the autodetection of loaded modules does |
not work. In order to change number of loaded modules, the file |
kernel/arch/mips32/src/mips32.c must be modified. |
Sample msim configuration file: |
\begin{verbatim} |
add dcpu mips1 |
add rwm mainmem 0x0 8M load "/dev/zero" |
add rom startmem 0x1fc00000 1024k load "image.boot" |
add rwm ns 0x01000000 1M load "ns" |
add rwm kbd 0x01100000 1M load "fb" |
add rwm fb 0x01200000 1M load "kbd" |
add rwm console 0x01300000 1M load "console" |
add rwm init 0x01400000 1M load "init" |
add rwm tetris 0x01500000 1M load "tetris" |
\end{verbatim} |
Sample gxemul command line arguments: |
\begin{verbatim} |
gxemul -E testmips -X 0x81800000:../uspace/ns/ns 0x81900000:../uspace/kbd/kbd \ |
0x81a00000:../uspace/fb/fb 0x81b00000:../uspace/init/init \ |
0x81c00000:../uspace/console/console 0x81d00000:../uspace/tetris/tetris kernel.bin |
\end{verbatim} |
The kernel can boot on the SGI Indy (and probably other SGI computers |
with 32-bit ARC firmware). It uses ARC for output and input. When |
the kernel is compiled to be loaded on the SGI Indy, an ECOFF image |
is created which can be later loaded directly with ARC boot loader |
e.g. using BOOTP protocol. |
\section{IA-64} |
The IA-64 port is supported on the Ski simulator. The situation is very similar |
to the MIPS loader - the loaded modules must be loaded on correct addresses in |
the Ski configuration file and specified in the file |
kernel/arch/ia64/src/ia64.c. |
Sample IA-64 configuration file: |
\begin{verbatim} |
load kernel.bin |
romload ../uspace/ns/ns 0x400000 |
romload ../uspace/init/init 0x800000 |
romload ../uspace/console/console 0xc00000 |
romload ../uspace/fb/fb 0x1000000 |
romload ../uspace/kbd/kbd 0x1400000 |
romload ../uspace/tetris/tetris 0x1800000 |
romload ../uspace/klog/klog 0x1c00000 |
romload ../uspace/ipcc/ipcc 0x2000000 |
\end{verbatim} |
\section{Power PC} |
The PowerPC boot image contains complete kernel with user tasks. |
The loader build system automatically creates such image using information |
residing in boot/arch/ppc32/loader/Makefile.inc. The variable COMPONENTS |
specifies, which tasks will be loaded into the image. |
/usrman/trunk/enhancing/enhancing.tex |
---|
0,0 → 1,3 |
\chapter{Enhancing HelenOS} |
HelenOS .. |
/usrman/trunk/Makefile |
---|
0,0 → 1,10 |
# Makefile |
# ----------------------------------------------- |
source=usrman |
all: |
pdflatex $(source).tex |
clean: |
-rm $(source).pdf *.log *.aux *.out *.dvi |