Subversion Repositories HelenOS-doc

\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.}.