Chapter 19
OSKit “Quick Start” Library: liboskit_startup.a

19.1 Introduction

The so-called “startup” library, liboskit_startup.a, contains a variety of convenience functions for initializing common subsets of OSKit functionality. For example the most general function, start_world, initializes the threading system, all device drivers, the clock, the network stack and a disk or memory based filesystem. Many of the startup functions can be “fine tuned” using environment variables. These variables are discussed where applicable.

While using the startup library can vastly simplify your kernel code, you should be aware that it can also greatly increase its size by introducing dependencies on many other OSKit libraries. Start up time for the kernel may also be impacted due to potential inclusion of every supported device driver and requisite boot time probe.

Note that oskit_clientos_init or oskit_clientos_init_pthreads must be called before any start_ function.

The following sections briefly describe the available functions and their dependencies.

19.2 General

19.2.1 start_world: initialize everything imaginable

SYNOPSIS

#include <oskit/startup.h>

void start_world(void);
void start_world_pthreads(void);

DESCRIPTION

Sledgehammer of the OSKit world.

Starts the clock and threading system (start_world_pthreads only) and probes all device drivers.

If the “root” environment variable is set to some recognizable device name, that device is used as the root of a filesystem. Any boot modules (BMODs) included in the kernel image are made accessible (mounted) under the /bmod directory unless the environment variable “no-bmod” is set.

If the “root” environment variable is not set, a memory-based filesystem is initialized, using any provided BMODs as the root of the filesystem.

If the “swap” environment variable is set to some recognizable device name, that device is opened and used as a paging device for the SVM component (see Section 27). Otherwise, the SVM component is initialized (providing stack protection for the threading system) but no paging is done, unless the “no-svm” environment variable is set, in which case SVM is not used.

If the “no-network” environment variable is not set, the BSD networking stack is initialized.

If profiling support is compiled in, it is initialized.

oskit_clientos_init_pthreads();

DEPENDENCIES
start_clock:
 19.2.2
start_pthreads:
 19.2.6
start_devices:
 19.2.7
start_fs_on_blkio:
 19.3.2
start_fs_bmod:
 19.3.3
start_svm:
 19.5.1

19.2.2 start_clock: initialize and register a default clock object

SYNOPSIS

#include <oskit/startup.h>

void start_clock(void);

DESCRIPTION

Creates and registers an oskit_clock_t object. A clock object is required by any function that needs the “time of day” or uses a POSIX-style interval timer.

First it initializes generic device support (start_osenv) and creates a default oskit_clock_t object based on the system-wide clock hardware device.

Then it reads the current time from the “real-time clock” hardware and uses the returned value to set the default clock object’s notion of the current time.

Finally it registers the clock object in the global registry so that lookups using oskit_clock_iid will return it.

DEPENDENCIES
start_osenv:
 19.2.5

19.2.3 start_console: initialize a full POSIX console device

SYNOPSIS

#include <oskit/startup.h>

void start_console(void);
void start_console_pthreads(void);

DESCRIPTION

Switch to a “real” tty device for the console. A real tty device is one which support full POSIX features (i.e., termios handling) and is registered as an oskit_ttydev_iid object.

If such a tty driver is found, its termios state is initialized to a reasonable default, the tty object is wrapped in a thread-safe wrapper (start_console_pthreads) and the POSIX code is informed to replace its notion of the console with the new one.

Note that this call is only used if you need full POSIX semantics for your console. The base console, which supports rudimentary input/output editing, is initialized at a lower level via the base_console functions in libkern (see Section  15.13.1).

19.2.4 start_cq_console: initialize a CQ console interface

SYNOPSIS

#include <oskit/startup.h>

void start_cq_console(void);

DESCRIPTION

Note: the following is taken from the source code comment.

Implements some of the methods for ”console” fd’s using the CQ console interface implemented by Roland. That interface does not provide enough to do a complete TTY stream interface, but it does provide true interrupt driven I/O, so the asyncio interface can be properly implemented, and so select on the simple console will work.

We essentially create an oskit_ttystream_t wrapper around an oskit_stream_t, and pass along the stuff that makes sense and don’t bother with the stuff that we know we cannot do at this level. If you need more functonality, use the freebsd TTY stuff.

19.2.5 start_osenv: creates a default “OS environment” object

SYNOPSIS

#include <oskit/startup.h>
#include <oskit/dev/osenv.h>

oskit_osenv_t *start_osenv(void);

DESCRIPTION

Creates the default OS environment object (oskit_osenv_iid) and registers it. This osenv object includes default objects for: logging, interrupt control, sleep and wakeup, IRQ control, memory allocation, device driver lookup, device access, and timer and clock functions. See Section  8 for information about specific osenv functions.

The important thing to know is that this function needs to be called before doing anything related to hardware devices. Most other startup library functions call it as necessary, but you can call it to be sure; it is designed to be called multiple times, returning the same object on successive calls. Any call requiring an oskit_osenv_t parameter can be satisfied by calling this function.

19.2.6 start_pthreads: initialize the threading system

SYNOPSIS

#include <oskit/startup.h>

void start_pthreads(void);

DESCRIPTION

Initialize the pthread implementation. Upon return, the caller is running in a pthread context and any pthread call can be made.

Note that when start_pthreads has been called, you will need to use the _pthreads version of startup functions where applicable (e.g., start_network_pthreads).

DEPENDENCIES
pthread_init:
 29.3.2

19.2.7 start_devices: probe and initialize all device drivers

SYNOPSIS

#include <oskit/startup.h>

void start_devices(void);

DESCRIPTION

Convenience function to probe and initialize device drivers, using link-time dependencies to select sets to initialize.

Not intended to be called directly by application code. Used by start_blk_devices and start_net_devices.

DEPENDENCIES
start_osenv:
 19.2.5
oskit_dev_init:
 17.2
oskit_dev_probe:
 17.2

19.2.8 start_foox: the start_foox call

SYNOPSIS

#include <oskit/startup.h>

void start_foox(void);

DESCRIPTION

Here is what I do.

DEPENDENCIES
depends on:
 19

19.3 Disk and Filesystem

19.3.1 start_fs: Initialize the root filesystem for a kernel

SYNOPSIS

#include <oskit/startup.h>

void start_fs(const char *diskname, const char *partname);

DESCRIPTION

Setup up a kernel with its root filesystem on the indicated disk and partition.

DEPENDENCIES
start_fs_on_blkio:
 19.3.2

19.3.2 start_fs_on_blkio: Initialize the root filesystem for a kernel from a blkio

SYNOPSIS

#include <oskit/startup.h>

void start_fs_on_blkio(oskit_blkio_t *part);

DESCRIPTION

Setup up a kernel with its root filesystem on the disk and partition indicated by the given blkio interface.

DEPENDENCIES
oskit_clientos_setfsnamespace:
 13.2.3

19.3.3 start_fs_bmod: Initialize the root filesystem for a kernel from a bmod

SYNOPSIS

#include <oskit/startup.h>

void start_fs_bmod(void);

DESCRIPTION

Setup up a default memory-based filesystem for a kernel using the boot modules included in the kernel’s multiboot image.

DEPENDENCIES
oskit_create_fsnamespace:
 23.1.1
oskit_clientos_setfsnamespace:
 13.2.3
 bmod_populate.c
 create_devdir.c
 start_blk_devices.c
 start_bmod.c
 start_disk.c
 start_fs.c
 start_fs_bmod.c
 start_fs_native.c
 start_fs_native_bmod.c
 start_fs_native_pthreads.c
 start_linux_fs.c

19.4 Network

 start_conf_network.c
 start_conf_network_close_eif.c
 start_conf_network_eif.c
 start_conf_network_eifconfig.c
 start_conf_network_eifdown.c
 start_conf_network_eifname.c
 start_conf_network_host.c
 start_conf_network_init.c
 start_conf_network_open_eif.c
 start_conf_network_router.c
 start_getinfo_network.c
 start_net_devices.c
 start_network.c
 start_network_native.c
 start_network_native_pthreads.c
 start_network_router.c
 start_network_single.c

19.5 Misc

19.5.1 start_svm: Initialize the SVM subsystem

SYNOPSIS

#include <oskit/startup.h>

oskit_error_t start_svm(const char *disk, const char *partition);

DESCRIPTION

Start the SVM system on a disk/partition specification. Device initialization should already have been done.

DEPENDENCIES
start_svm_on_blkio:
 19.5.2

19.5.2 start_svm_on_blkio: Initialize the SVM subsystem from blkio interface

SYNOPSIS

#include <oskit/startup.h>

oskit_error_t start_svm_on_blkio(oskit_blkio_t *bio);

DESCRIPTION

Start the SVM system on a specific oskit_blkio instance. In the pthreads case, the bio should NOT be wrapped; it will be taken care of here.

 start_gprof.c
 start_sound_devices.c
 start_svm.c
 start_tmcp.c