8 Libraries

There are some libraries implemented to make the live of the programmer a little bit easier. These libraries are not directly associated with system functionality like system calls, therefore they are listed in a seperate chapter.

The mentioned libraries handle

• Terminal IO (in a very simple manner),
• Debug output to the associated debug screen,
• Some debugging support like stack checking and a core dump facility.

The L3 terminal functionality is provided at a very low level. You can write a number of arbitrary characters to the screen and you can read a distinct number of characters from the keyboard. This is done by two functions,

• TermWrite(char *text, int count);
• TermRead(char *text, int max);
• TermPrint(char *text) (#define TermPrint(x) TermWrite((x), _strlen(x)))

These functions handle the protcol used to access the terminal. If you attach your task to the terminal, the terminal manager tries to communicate with your task to establish the terminal connection. Your task has to respond with a given sequence. If it doesn't do so, the terminal manager rejects the requested connection. Therefore you have to call TermRead or TermWrite before trying to attach your task to the terminal.

A simple Hello World program could look like follows.

#include <l3/l3term>

void main(void)
{
   TermPrint("Hello, World!\n");
}

There is a special task responsible for managing the debug terminal. The library function void HercPrint(char *text); provides access to this task. To use this function you have to do two things:

• Enable debug output

  Normally the responsible task doesn't put anything to the debug terminal. To to enable this function you execute the following steps:

  1. enter the kernel using Scroll Lock
  2. press T+ to enable tracing
  3. press g to leave the kernel debugger
• Initialize debug output

  A call to HercInit() will initalize the debug output. It will mainly ask the kernel for the thread id of the log task, which is responsible for the debug terminal.

A simple Hello World program could look like follows.

#include <l3/herclog.h>

void main(void)
{
   HercInit();
   HercPrint("Hello, World!\n");
}

The log task doesn't understand a normal '\n' so you have to use ,,\n\r''.

8.3 Server Library

There is one library providing support for ,,server'' development, but it isn't restricted to this area. This library provides:

• default exception handling routines

  L3 mirrors the processor exception, therefore Every thread has to do its own exception handling. The default exception handling routines try to contact a distinct task given at initialization time (default ,,core'') and provide it with the necessary information to create a core task. If a thread tries to create a core dump it puts a message to the debug screen and waits for the core task. You switch to the core task and issue a ccd(/,,<name of thread trying to create a core dump>''). After a successful dump you will find a file named <name of core dumped tread>.core.

• stack check

  The libary will set up a fire wall at the bottom of the stack resulting in a stack exception if the stack overflows.

• ,,code check''

  The library will set the code segment to read only to allow detection of write access to the code segment. The library creates a core dump if this happens.

• argument handling

  The library provides the normal calling convention for main, main(int argc, char **argv). It take the parameters given by runx, prepares a character array and calls main.

Normaly it is enough to call DefaultInit() to do all the necessary initialization. DefaultInit() does the following things:

• Initialize Supervisor Protocol (call SVProtInit())
• Initialize Debug Output (call HercInit())
• Initialize default exception handling
• Initialize core dump (call CoreInit(,,core''))
• Initialize stack and code check (call InitStackCheck() and SetTextReadOnly())
• Set up MainThreadIDV2, a variable used by l3term

If this doesn't meet your requirements, you have to do the initialization by yourself.