[next] [tail] [up]

Chapter 13
“Client OS” Library: liboskit_clientos.a

13.1 Introduction

The “clientos” library is responsible for initializing certain portions of the client operating system in an OSKit kernel. Specifically, the default memory object, the global registry, the C/POSIX library environment, and the default console, must all be initialized in order for the application to work properly. These interfaces are then available to the various OSKit libraries and components, without requiring linktime dependencies on them. The C library in particular is dependent on many external interfaces, which are accessed through its services database. That services database is given to the C library by the clientos initialization function once it has finished creating all the necessary objects. For example, before the application can call the malloc routine in the C library, the default memory object must be created (see Section 13.4), the global registry must be created (see Section 5.2), the memory object registered in the global registry, and a reference to the global registry (an instance of a services database) given to the C library so that it can request a reference to the memory object. At this point, malloc can now ask the memory object to allocate the requested amount of memory. Many other interfaces must also be installed. As the OSKit kernel continues to initialize devices and interfaces, it will hand those objects to the clientos, or in some cases the objects will be registered in the global registry directly. This approach enables the separation of the kernel intialization from the application itself.

13.2 Initialization

The clientos is the first library that must be initialized in the application’s main program. Any attempts to allocate memory prior to this initialization will fail, and the kernel will most likely panic. To initialize the clientos library:

13.2.1 oskit_clientos_init: Initialize the client operating system library

SYNOPSIS

#include <oskit/clientos.h>

oskit_error_t oskit_clientos_init(void);
oskit_error_t oskit_clientos_init_pthreads(void);

DESCRIPTION

Initialize the Client Operating System library. This routine must be called immediately in the application’s main program. In multi threaded applications, use the oskit_clientos_init_pthreads interface instead. As an example, consider the trivial “Hello World” program: 

         void main()
         {
                 oskit_clientos_init();
 
                 printf("Hello, World\n");
         }
         
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

Several convenience functions are exported from the clientos library that make it easy to initialize the oskit_libcenv object as the application continues to initialize devices and interfaces. They are:

13.2.2 oskit_clientos_sethostname: Set the hostname

SYNOPSIS

#include <oskit/clientos.h>

oskit_error_t oskit_clientos_sethostname(char *hostname, int len);

DESCRIPTION

Set the operating system hostname. This is typically called from the network initialization code, once the hostname has been determined.

RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.2.3 oskit_clientos_setfsnamespace: Set the filesystem namespace

SYNOPSIS

#include <oskit/clientos.h>

oskit_error_t oskit_clientos_setfsnamespace(oskit_fsnamespace_t *fsn);

DESCRIPTION

Set the filesystem namespce object. This is typically called from the filesystem initialization code, once the root filesystem has been initialized, and the filesystem namespace object created.

RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3 C Library Environment

One of the many COM interfaces that are installed in the services database received by the C/POSIX library, is the oskit_libcenv COM interface. The oskit_libcenv encapsulates a number of external interfaces that only the C library needs. For example, before the application can use any of the filesystem interface calls, it must request a reference to the filesystem namespace object (see Section 23), which handles translation from multi component pathnames to oskit_file COM objects. The oskit_libcenv COM interface can be described as an ad-hoc collection of interfaces that do not belong anyplace else since only the C/POSIX libraries require them.

The oskit_libcenv COM interface inherits from IUnknown, and has the following additional methods:

getfsnamespace:
Return a reference to the filesystem namespace object.
setfsnamespace:
Set the filesystem namespace object.
gethostname:
Return the system hostname.
sethostname:
Set the hostname.
exit:
Call the exit function.
setexit:
Set the exit function.
getconsole:
Return a reference to the console interface object.
setconsole:
Set the console interface object.
signals_init:
Call the signal initialization function.
setsiginit:
Set the signal initialization function.
sleep_init:
Initial a sleep record for a future sleep.
sleep:
Go to sleep until awakened.
wakeup:
Wakeup a sleeping thread.

In the descriptions that follow, it should be noted that the accessor function are intended to be used by the C/POSIX libraries, while the the functions to modify the object are intended to be used by the clientos library when setting up the object.

13.3.1 getfsnamespace: Get the filesystem namespace

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_getfsnamespace(oskit_libcenv_t *c, oskit_fsnamespace_t **out_fsn);

DESCRIPTION

Get the oskit_fsnamespace COM object from the oskit_libcenv COM object. The application initialization code will typically set the oskit_fsnamespace object when it initializes the root filesystem (see oskit_clientos_setfsnamespace above). The POSIX library then requests a reference to namespace object when the application first tries to use one of the filesystem interface calls in the POSIX library.

PARAMETERS
c:
The oskit_libcenv object to operate on.
out_fsn:
The oskit_fsnamespace object to return.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.2 setfsnamespace: Set the filesystem namespace

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_setfsnamespace(oskit_libcenv_t *c, oskit_fsnamespace_t *fsn);

DESCRIPTION

Set the oskit_fsnamespace COM object associated with the oskit_libcenv COM object. The application initialization code will typically set the oskit_fsnamespace object when it initializes the root filesystem (see oskit_clientos_setfsnamespace above). The POSIX library then requests a reference to namespace object when the application first tries to use one of the filesystem interface calls in the POSIX library.

PARAMETERS
c:
The oskit_libcenv object to operate on.
fsn:
The oskit_fsnamespace object to set.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.3 gethostname: Get the system hostname

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_gethostname(oskit_libcenv_t *c, char *hostname, int len);

DESCRIPTION

Get the system hostname from the oskit_libcenv COM object. The application initialization code will typically set the hostname when it initializes the network. The POSIX library will then request the hostname as needed by the C library or the application program.

PARAMETERS
c:
The oskit_libcenv object to operate on.
hostname:
The returned hostname buffer.
len:
The maximum length of the buffer.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.4 sethostname: Set the system hostname

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_sethostname(oskit_libcenv_t *c, char *hostname, int len);

DESCRIPTION

Set the system hostname associated with the oskit_libcenv COM object. The application initialization code will typically set the hostname when it initializes the network. The POSIX library will then request the hostname as needed by the C library or the application program.

PARAMETERS
c:
The oskit_libcenv object to operate on.
hostname:
The hostname to set.
len:
The length of the hostname buffer.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.5 exit: Call the exit function

SYNOPSIS

#include <oskit/com/libcenv.h>

void oskit_libcenv_exit(oskit_libcenv_t *c, oskit_u32_t status);

DESCRIPTION

Call the exit function for the application. This function is default to the OSKit kernel exit routine, which causes a reboot.

PARAMETERS
c:
The oskit_libcenv object to operate on.
status:
The exit value.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.6 setexit: Set the exit function

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_setexit(oskit_libcenv_t *c, void (*exitfunc)(int));

DESCRIPTION

Set the exit function for the application.

PARAMETERS
c:
The oskit_libcenv object to operate on.
exitfunc:
The new exit function.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.7 getconsole: Get and the console stream object

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_getconsole(oskit_libcenv_t *c, oskit_ttystream_t **out_ttystream);

DESCRIPTION

Get the system console object. The system console object defaults to a trivial stream implementation that uses the kernel console routines.

PARAMETERS
c:
The oskit_libcenv object to operate on.
out_ttystream:
The oskit_ttystream object to return.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.8 setconsole: Set the console stream object

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_setconsole(oskit_libcenv_t *c, oskit_ttystream_t *ttystream);

DESCRIPTION

Set the system console object. Because the console is in use from the moment the kernel starts running, changing the console is more complicated than just using the setconsole method. The reader is encouraged to look at the example kernel in examples/x86/extended/console_tty, and the support code in startup/start_console.c.

PARAMETERS
c:
The oskit_libcenv object to operate on.
ttystream:
The oskit_ttystream object to set.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.9 signals_init: Call the signal initialization function

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_signals_init(oskit_libcenv_t *c, int (*func)(int, int, void *));

DESCRIPTION

Call the signal initialization function for the POSIX library. The signal initialization function defaults to the OSKit kernel library signal initialization routine (see Section 15.21). The POSIX library will call this routine if the application uses any of the POSIX signal interface functions, passing in a function pointer to the callback in the POSIX library that should be invoked when a hardware trap should be passed to the application as a signal. The signal initialization function can be changed with the setsiginit method, although that should be done with caution.

PARAMETERS
c:
The oskit_libcenv object to operate on.
func:
The callback routine for the kernel trap code.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.10 setsiginit: Set the signal initialization function

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_setsiginit(oskit_libcenv_t *c, void (*sigfunc)(int (*func)(int,int,void *)));

DESCRIPTION

Set the signal initialization function for the POSIX library. The signal initialization function defaults to the OSKit kernel library signal initialization routine (see Section 15.21). The POSIX library will call this routine if the application uses any of the POSIX signal interface functions, passing in a function pointer to the callback in the POSIX library that should be invoked when a hardware trap should be passed to the application as a signal. Changing the signal initialization function should be done with caution.

PARAMETERS
c:
The oskit_libcenv object to operate on.
sigfunc:
The new signal initialization function.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.3.11 sleep_init: Initialize a sleep record for the sleep/wakeup interface

SYNOPSIS

#include <oskit/com/libcenv.h>

void oskit_libcenv_sleep_init(oskit_libcenv_t *c, osenv_sleeprec_t *sleeprec);

DESCRIPTION

The sleep/wakeup interface is provided so that the C/POSIX library uses a standard mechanism for giving up control of the CPU, in both single and multi threaded applications. The sleep_init method initializes a “sleep record” structure in preparation for the going to sleep waiting for some event to occur. The sleep record is used to avoid races between actually going to sleep and the event of interest, and to provide a “handle” on the current activity by which wakeup can indicate which process to awaken.

PARAMETERS
c:
The oskit_libcenv object to operate on.
sleeprec:
A pointer to a sleep record, allocated by the caller.

13.3.12 sleep: Sleep until awakened

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_sleep(oskit_libcenv_t *c, osenv_sleeprec_t *sleeprec, struct oskit_timespec *timeout);

DESCRIPTION

The sleep method is used to put the caller to sleep. The specified sleep record must have been initialized with sleep_init. An optional timeout value may be supplied. The caller will be woken if the timeout expires, and OSKIT_ETIMEDOUT will be returned to indicate timeout.

PARAMETERS
c:
The oskit_libcenv object to operate on.
sleeprec:
A pointer to a sleep record, allocated by the caller.
timeout:
A timeout value used to bound the length of the sleep interval.
RETURNS

The sleep function returns 0 if woken up normally, otherwise OSKIT_ETIMEDOUT is returned if the timeout expires.

13.3.13 wakeup: Wakeup a sleeping thread

SYNOPSIS

#include <oskit/com/libcenv.h>

void oskit_libcenv_wakeup(oskit_libcenv_t *c, osenv_sleeprec_t *sleeprec);

DESCRIPTION

The wakeup methods is used to initiate a wakeup of any thread which has previously called sleep with the indicated sleep record.

PARAMETERS
c:
The oskit_libcenv object to operate on.
sleeprec:
A pointer to a sleep record, allocated by the caller.

13.3.14 clone: Make a copy of an oskit_libcenv object

SYNOPSIS

#include <oskit/com/libcenv.h>

oskit_error_t oskit_libcenv_clone(oskit_libcenv_t *c, oskit_libcenv_t **out_intf);

DESCRIPTION

Make a copy of the oskit_libcenv object in c. All of the reference counts on the internal objects are adjusted, and a new oskit_libcenv object is returned in out_intf. The new object may then modified without affecting the original object.

PARAMETERS
c:
The oskit_libcenv object to operate on.
out_intf :
The new oskit_libcenv object to return.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

13.4 Memory Interface

The oskit_mem COM interface defines an interface for memory allocation and deallocation for oskit libraries. As described above, the C libary malloc routines are implemented in terms of an oskit_mem object that is created when the clientos is initialized. This initial memory object is the lowest level memory allocator that is available to the application. All other memory allocators, such as the malloc library, the memdebug library (see Section 31), and the device memory allocators (see Section 8), are implemented in terms of the oskit_mem object that is created when the clientos is initialized.

The oskit_mem COM interface inherits from IUnknown, and has the following additional methods:

alloc:
Allocate a chunk of memory.
realloc:
Realloc a chunk of memory.
alloc_aligned:
Allocate a chunk of memory, subject to an alignment constraint.
free:
Free a chunk of memory that was allocated with alloc or alloc_aligned.
getsize:
Inquire about the size of a chunk of memory.
alloc_gen:
Allocate memory with general constraints.
avail:
Return the amount of free memory.

13.4.1 alloc: Allocate a chunk of memory

SYNOPSIS

#include <oskit/com/mem.h>

void *oskit_mem_alloc(oskit_mem_t *m, oskit_u32_t size, oskit_u32_t flags);

DESCRIPTION

Allocate a chunk of memory of size bytes, subject to various options specified in flags. If successful, a pointer to the new chunk of memory is returned. Othersize a NULL pointer is returned. The new memory must be deallocated with the free method described below. The options that can be specifed with the flags parameter are:

OSKIT_MEM_AUTO_SIZE:
The memory allocator must keep track of the size of allocated blocks allocated using this flag; in this case, the value size parameter passed in the corresponding free call is meaningless. For blocks allocated without this flag set, the caller promises to keep track of the size of the allocated block, and pass it back to free on deallocation.
OSKIT_MEM_NONBLOCKING:
If set, this flag indicates that the memory allocator must not block during the allocation or deallocation operation. Any calls to the allocation functions from interrupt handlers must specify the OSKIT_MEM_NONBLOCKING flag.
OSKIT_MEM_PHYS_WIRED:
Indicates that the must must be non-pageable. Accesses to the returned memory must not fault.
OSKIT_MEM_PHYS_CONTIG:
Indicates the underlying physical memory must be contiguous.
OSKIT_MEM_VIRT_EQ_PHYS:
Indicates the virtual address must exactly equal the physical address so the driver may use them interchangeably. The OSKIT_MEM_PHYS_CONTIG flag must also be set whenever this flag is set.
OSKIT_MEM_ISADMA_MEM:
This flag applies only to machines with ISA busses or other busses that are software compatible with ISA, such as EISA, MCA, or PCI. It indicates that the memory allocated must be appropriate for DMA access using the system’s built-in DMA controller. In particular, it means that the buffer must be physically contiguous, must be entirely contained in the low 16MB of physical memory, and must not cross a 64KB boundary. (By implication, this means that allocations using this flag are limited to at most 64KB in size.) The OSKIT_MEM_PHYS_CONTIG flag must also be set if this flag is set.
PARAMETERS
m:
The memory object to operate on.
size:
The size (in bytes) of the chunk to allocate.
flags:
Allocation options and constraints.
RETURNS

Returns a pointer to the new chunk of memory on success, or NULL if the request could not be satisfied.

13.4.2 realloc: Reallocate a chunk of memory

SYNOPSIS

#include <oskit/com/mem.h>

void *oskit_mem_realloc(oskit_mem_t *m, void *ptr, oskit_u32_t oldsize, oskit_u32_t newsize, oskit_u32_t flags);

DESCRIPTION

Change the size of the previously allocated memory chunk referenced by ptr, returning a pointer to the memory chunk. The flags must include OSKIT_MEM_AUTO_SIZE if the original allocation did, otherwise oldsize must properly give the size of the original allocation. If the new size is larger, the contents of the newly allocated portion is undefined. Any other flags specified in the original allocation should necessarily be given as well. If the size of the original chunk cannot be changed in place, a new chunk of the proper size will be allocated, and the contents of the original chunk copied to it.

PARAMETERS
m:
The memory object to operate on.
ptr:
The original memory.
oldsize:
The size (in bytes) of the original chunk.
newsize:
The size (in bytes) of the new chunk.
flags:
Allocation options and constraints.
RETURNS

Returns a pointer to the chunk of memory on success, or NULL if the request could not be satisfied.

13.4.3 alloc_aligned: Allocate a chunk of memory subject to alignment constraints

SYNOPSIS

#include <oskit/com/mem.h>

oskit_error_t oskit_mem_alloc_aligned(oskit_mem_t *m, oskit_u32_t size, oskit_u32_t flags, oskit_u32_t align);

DESCRIPTION

Allocate a chunk of memory of size bytes, subject to various options specified in flags, and an alignment constraint specifed by align. The alignment constraint is a power of two integer, which indicates the minimum required alignment for the new chunk. If successful, a pointer to the new chunk of memory is returned. Othersize a NULL pointer is returned. The new memory must be deallocated with the free method described below.

PARAMETERS
m:
The memory object to operate on.
size:
The size (in bytes) of the chunk to allocate.
flags:
Allocation options and constraints.
align:
The alignment constraint for the new chunk.
RETURNS

Returns a pointer to the chunk of memory on success, or NULL if the request could not be satisfied.

13.4.4 free: Free a chunk of memory

SYNOPSIS

#include <oskit/com/mem.h>

void oskit_mem_free(oskit_mem_t *m, void *ptr, oskit_u32_t size, oskit_u32_t flags);

DESCRIPTION

Deallocate the chunk of memory pointed to by ptr. The flags must include OSKIT_MEM_AUTO_SIZE if the original allocation did, otherwise size must properly give the size of the original allocation.

PARAMETERS
m:
The memory object to operate on.
ptr:
The chunk to deallocate.
size:
The size (in bytes) of the original allocation request if the chunk was not allocated with OSKIT_MEM_AUTO_SIZE.
flags:
Options and constraints.

13.4.5 getsize: Inquire about the size of a chunk of memory

SYNOPSIS

#include <oskit/com/mem.h>

oskit_u32_t oskit_mem_getsize(oskit_mem_t *m, void *ptr);

DESCRIPTION

Return the size of the chunk of memory pointed to by ptr. The chunk must have been allocated with OSKIT_MEM_AUTO_SIZE for the size to be determined. The returned size may be greater than the original size requested, because of rounding done to satisfy alignment constraints.

PARAMETERS
m:
The memory object to operate on.
ptr:
The chunk to inquire about.
RETURNS

Returns the size of the chunk, or an undefined value if the chunk was not allocated with OSKIT_MEM_AUTO_SIZE.

13.4.6 alloc_gen: Allocate a chunk of memory with general constraints

SYNOPSIS

#include <oskit/com/mem.h>

void *oskit_mem_alloc_gen(oskit_mem_t *m, oskit_u32_t size, oskit_u32_t flags, oskit_u32_t align_bits, oskit_u32_t align_ofs);

DESCRIPTION

Allocate a chunk of memory meeting various alignment and address constraints. It is similar to alloc, but is intended to provide an interface more like lmm_alloc_gen (see Section 25).

PARAMETERS
m:
The memory object to operate on.
size:
The size (in bytes) of the chunk to allocate.
flags:
Allocation options and constraints.
align_bits:
The number of low bits of the returned memory chunk address that must match the corresponding bits in align_ofs.
align_ofs:
The required offset from natural power-of-two alignment. If align_ofs is zero, then the returned memory block will be naturally aligned on a 2alignbits boundary.
RETURNS

Returns a pointer to the chunk of memory on success, or NULL if the request could not be satisfied.

13.4.7 avail: Return the amount of free memory

SYNOPSIS

#include <oskit/com/mem.h>

oskit_size_t oskit_mem_avail(oskit_mem_t *m, oskit_u32_t flags);

DESCRIPTION

Return the amount of free space in the memory object pool. If flags is non-zero, it should be a memory type flag, which indicates that the return value should be the amount of free space of that type.

PARAMETERS
m:
The memory object to operate on.
flags:
Options and constraints.
RETURNS

Returns the amount of memory available on success.

[next] [front] [up]