C++

For a quick tutorial on getting a C++ kernel running see C++ bare bones

One thing up front: you can do a kernel in C++. It has been done before. This page will not discuss the pros and cons, just tell you about the things you have to be aware of when doing it.

Most features of C++ come "for free", i.e. require no additional supporting work to be used in kernel space. Templates, for example, do not require any additional logic; neither do classes, even when inheritance and virtual functions are involved. Other things do require runtime support. This document will first explain how to turn these features off, and then, gradually, how to implement the required support so you can turn them on again.

Features requiring run time support

Startup code

By default, G++ attempts to link in startup code - the stuff usually done before main() is called, and after it exits / returns. This is all fine in a hosted environment, but you don't want to have it in your kernel (and it would not compile, either). Disable this by setting -nostartfiles.

Why?

It's for the very same reason of C. The startup code needed for C is OS-specific, and some times compiler specific. In a freestanding environment, you'll need to implement your own startup code to configure the stack and other language specific features. Then, your boot loader has to know where this startup code begins and jump to that address if it hopes to successfully run your kernel.

There is a bit more work to do than in C before calling main. For more information see C++ Bare Bones.

Pure virtual functions

If you want to use pure virtual functions, your compiler needs one support function. It is only called in case a pure virtual function call cannot be made (e.g. if you have overridden the virtual function table of an object). But nonetheless your linker will complain about unresolved symbols, if you use pure virtual functions and don't provide that support routine.

Why?

It is a requirement of C++ to provide a backup function to call when a virtual function cannot be called.

Enabling pure virtual functions

To enable the use of virtual functions in GCC, you simply need the following function in one of your .cpp files. You do not need to place a prototype or anything in any of your headers. The contents of the function itself does not need to print an error message or do anything at all, since most implementations simply do nothing if the pure virtual function call cannot be made.

The following code applies to GCC:

extern "C" void __cxa_pure_virtual()
{
    // print error message
}

The following code applies to Visual C++:

int __cdecl _purecall()
{
    // print error message
}

If during runtime your kernel detects that a call to a pure virtual function couldn't be made, it calls the above functions. These functions should actually never be called, because without hacks (or through undefined behaviour of your kernel) it is not possible to instantiate a class that doesn't define all pure virtual functions. But nonetheless you have to define these functions or your linker will complain about unresolved symbols.

Global objects

Global objects must have their constructors called before they are used... and they would usually be called by the startup code you just disabled. So, stay away from global objects until you have set up your own kernel startup code.

Why?

All objects have constructor and deconstructor code. When an executable code is loaded into memory, and the program jumps straight into main, the constructor code for each global object has not be run. You could do this manually, by calling in the top of main():

object1.object1();
object2.object2();
object3.object3();
// etc

Enabling global objects

Global or static objects have to be constructed by the environment before they are available for C++ code. Care should be taken if global/static objects need new and delete in their constructors. In this case it is best to construct global/static objects only after your kernel heap is ready for use. Not doing so can cause an object to attempt to allocate memory via the non-working new operator. This also simplifies the storing of the destructor functions in __cxa_atexit, because you don't have to use a static and fixed-size structure.

According to the Itanium C++ Application Binary Interface, which G++ follows, (and MSVC does not, so see further down for the MSVC example) the function __cxa_atexit is used to register a destructor to be called when a shared library is to be unloaded. This function should insert a function pointer, with (max) one accompanying argument, and the handle of the object or shared resource to be destroyed, into a table. In the source example for an implementation of __cxa_atexit, the __atexit_funcs[ATEXIT_MAX_FUNCS]; array acts as the table.

This is why, below, the function __cxa_atexit is defined as:

int __cxa_atexit(void (*destructor_func)(void *), void *arg, void *__dso_handle);

Such that, as explained above, 'destructor_func' is the handle for a destructor function, 'arg' as defined by the ABI is the single argument it may take, and __dso_handle is a handle for the DSO (Dynamic Shared Object).

In summary: the Itanium C++ ABI requires that you define two functions, and one symbol:

int __cxa_atexit(void (*f)(void *), void *objptr, void *dso);
void __cxa_finalize(void *f);
void *__dso_handle

Before you can define global objects in your C++ files.

GCC (version < 3.2)

GCC inserts an array of pointers into the object file: Look for the ELF sections called "ctors*". Each pointer indicates the constructor of a global / static object. Your ASM startup code should call them in turn before passing control to your C++ kernel code.

There also is a "dtors*" list of destructors; if your kernel returns, the exit / cleanup code should also call them in turn. Remember to destruct your objects in the opposite order you have constructed them.

GCC >= 3.2

GCC 4.0.2 seems to follow the same convention as GCC versions below 3.2. This seems to be independent of what is given with -fabi-version. I do get a dtors section.

The construction of global/static objects is the same as of older versions of GCC. After you have called the objects constructor GCC automatically calls the function

int __cxa_atexit(void (* f)(void *), void *p, void *d);

f is a function-pointer to the destructor, p is the parameter for the destructor and d is the "home DSO" (DSO = dynamic shared object). This function should save all three parameters and if successful return zero, on failure nonzero. When your kernel exits you should call __cxa_finalize(0). According to the ABI specification, calling this with (int) 0 as the parameter instead of the address of a function to be called and removed from the list causes all destructors in the list to be called and removed from the list.

Since you will be calling this function from your assembly source, right after your kernel exits, you could use the following code to do so:

; This is NASM source, mind you.
sub esp, 4
mov [esp], dword 0x0

call __cxa_finalize

add esp, 4

The following is tested, working, fully commented source that gives a more detailed explanation than the source previously found here. It also hilights what improvements can be implemented on itself, where they can be inserted.

To use, just include icxxabi.h in any ONE file of your C++ kernel source. Preferable the file where your kernel's main statements begin.

File: icxxabi.h

#ifndef _ICXXABI_H
	#define _ICXXABI_H

	#define ATEXIT_MAX_FUNCS	128
	
	#ifdef __cplusplus
	extern "C" {
	#endif
	
typedef unsigned uarch_t;

struct atexit_func_entry_t
{
	/*
	* Each member is at least 4 bytes large. Such that each entry is 12bytes.
	* 128 * 12 = 1.5KB exact.
	**/
	void (*destructor_func)(void *);
	void *obj_ptr;
	void *dso_handle;
};

int __cxa_atexit(void (*f)(void *), void *objptr, void *dso);
void __cxa_finalize(void *f);

	#ifdef __cplusplus
	};
	#endif

#endif

File: icxxabi.cpp

#include "./icxxabi.h"

	#ifdef __cplusplus
	extern "C" {
	#endif

atexit_func_entry_t __atexit_funcs[ATEXIT_MAX_FUNCS];
uarch_t __atexit_func_count = 0;

void *__dso_handle = 0;

int __cxa_atexit(void (*f)(void *), void *objptr, void *dso)
{
	if (__atexit_func_count >= ATEXIT_MAX_FUNCS) {return -1;};
	__atexit_funcs[__atexit_func_count].destructor_func = f;
	__atexit_funcs[__atexit_func_count].obj_ptr = objptr;
	__atexit_funcs[__atexit_func_count].dso_handle = dso;
	__atexit_func_count++;
	return 0; /*I would prefer if functions returned 1 on success, but the ABI says...*/
};

void __cxa_finalize(void *f)
{
	uarch_t i = __atexit_func_count;
	vga_boot icxxabi;
	if (!f)
	{
		/*
		* According to the Itanium C++ ABI, if __cxa_finalize is called without a
		* function ptr, then it means that we should destroy EVERYTHING MUAHAHAHA!!
		*
		* TODO:
		* Note well, however, that deleting a function from here that contains a __dso_handle
		* means that one link to a shared object file has been terminated. In other words,
		* We should monitor this list (optional, of course), since it tells us how many links to 
		* an object file exist at runtime in a particular application. This can be used to tell 
		* when a shared object is no longer in use. It is one of many methods, however.
		**/
		//You may insert a prinf() here to tell you whether or not the function gets called. Testing
		//is CRITICAL!
		while (--i)
		{
			if (__atexit_funcs[i].destructor_func)
			{
				/* ^^^ That if statement is a safeguard...
				* To make sure we don't call any entries that have already been called and unset at runtime.
				* Those will contain a value of 0, and calling a function with value 0
				* will cause undefined behaviour. Remember that linear address 0, 
				* in a non-virtual address space (physical) contains the IVT and BDA.
				*
				* In a virtual environment, the kernel will receive a page fault, and then probably
				* map in some trash, or a blank page, or something stupid like that.
				* This will result in the processor executing trash, and...we don't want that.
				**/
				(*__atexit_funcs[i].destructor_func)(__atexit_funcs[i].obj_ptr);
			};
		};
		return;
	};

	for ( ; i >= 0; )
	{
		/*
		* The ABI states that multiple calls to the __cxa_finalize(destructor_func_ptr) function
		* should not destroy objects multiple times. Only one call is needed to eliminate multiple
		* entries with the same address.
		*
		* FIXME:
		* This presents the obvious problem: all destructors must be stored in the order they
		* were placed in the list. I.e: the last initialized object's destructor must be first
		* in the list of destructors to be called. But removing a destructor from the list at runtime
		* creates holes in the table with unfilled entries.
		* Remember that the insertion algorithm in __cxa_atexit simply inserts the next destructor
		* at the end of the table. So, we have holes with our current algorithm
		* This function should be modified to move all the destructors above the one currently
		* being called and removed one place down in the list, so as to cover up the hole.
		* Otherwise, whenever a destructor is called and removed, an entire space in the table is wasted.
		**/
		if (__atexit_funcs[i].destructor_func == f)
		{
			/* 
			* Note that in the next line, not every destructor function is a class destructor.
			* It is perfectly legal to register a non class destructor function as a simple cleanup
			* function to be called on program termination, in which case, it would not NEED an
			* object This pointer. A smart programmer may even take advantage of this and register
			* a C function in the table with the address of some structure containing data about
			* what to clean up on exit.
			* In the case of a function that takes no arguments, it will simply be ignore within the
			* function itself. No worries.
			**/
			(*__atexit_funcs[i].destructor_func)(__atexit_funcs[i].obj_ptr);
			__atexit_funcs[i].destructor_func = 0;
			
			/*
			* Notice that we didn't decrement __atexit_func_count: this is because this algorithm
			* requires patching to deal with the FIXME outlined above.
			**/
		};
	};
};

	#ifdef __cplusplus
	};
	#endif

Visual C

Running constructors and destructors is covered in MSDN help and in the C runtime library sources. See #pragma init_seg on MSDN for some more information.

Basically what happens is that pointers to functions are placed in .CRT$XIC, $XIL, $XIU based on the value of init_seg. The linker then merges everything together in the .CRT section, in the order of the letters after the $. The pointers between the XIA (xi_a) and XIZ (xi_z) are then called if nonzero. The .CRT section is merged with the .data section to avoid a whole separate section.

One problem with C++ support is the horrible name-mangling that is impossible to read in the map file. A build script should be set up that runs the map file through the undname.exe tool, so that names like ??2@YAPAXI@Z (operator new - I think...) and others are readable.

Here is some code. Sorry for its length, but it is hard to explain any other way. Simply call runInit() when you want to initialize any static objects and then call runTerm() when static object destructors are to be run.

typedef void (*_PVFV)(void);
typedef int  (*_PIFV)(void);
typedef void (*_PVFI)(int);

#pragma data_seg(".CRT$XIA")
__declspec(allocate(".CRT$XIA")) _PIFV __xi_a[] = {0};
#pragma data_seg(".CRT$XIZ")
__declspec(allocate(".CRT$XIZ")) _PIFV __xi_z[] = {0};
#pragma data_seg(".CRT$XCA")
__declspec(allocate(".CRT$XCA")) _PVFV __xc_a[] = {0};
#pragma data_seg(".CRT$XCZ")
__declspec(allocate(".CRT$XCZ")) _PVFV __xc_z[] = {0};
#pragma data_seg(".CRT$XPA")
__declspec(allocate(".CRT$XPA")) _PVFV __xp_a[] = {0};
#pragma data_seg(".CRT$XPZ")
__declspec(allocate(".CRT$XPZ")) _PVFV __xp_z[] = {0};
#pragma data_seg(".CRT$XTA")
__declspec(allocate(".CRT$XTA")) _PVFV __xt_a[] = {0};
#pragma data_seg(".CRT$XTZ")
__declspec(allocate(".CRT$XTZ")) _PVFV __xt_z[] = {0};
#pragma data_seg()
#pragma comment(linker, "/merge:.CRT=.data")

static _PVFV onexitarray[32];
static _PVFV *onexitbegin, *onexitend;

int __cdecl _purecall()
{
        // print error message
}

int __cdecl atexit(_PVFV fn)
{
        if (32*4 < ((int)onexitend-(int)onexitbegin)+4)
                return 1;
        else
                *(onexitend++) = fn;
        return 0;
}

EXTERN int runInit()
{
        // init the __xi_a to __xi_z:  __initex(__xi_a, __xi_z);
        // init __xc_a to __xc_z
}

static void __init(_PVFV *pfbegin, _PVFV *pfend)
{
    while (pfbegin < pfend)
    {
        if (*pfbegin != 0)
            (**pfbegin)();
        ++pfbegin;
    }
}

static int __initex(_PIFV *pfbegin, _PIFV *pfend)
{
        int ret = 0;

        while (pfbegin < pfend && ret == 0)
        {
            if (*pfbegin != 0)
                ret = (**pfbegin)();
            ++pfbegin;
        }

        return ret;
}

EXTERN void runUninit()
{
        if (onexitbegin)
        {
                while (--onexitend >= onexitbegin)
                        if (*onexitend != 0)
                                (**onexitend)();
        }

        __init(__xp_a, __xp_z);
        __init(__xt_a, __xt_z);
}

EXTERN int onexitinit()
{
        onexitend = onexitbegin = onexitarray;
        *onexitbegin = 0;
        return 0;
}

#pragma data_seg(".CRT$XIB")      // run onexitinit automatically
__declspec(allocate(".CRT$XIB")) static _PIFV pinit = onexitinit;
#pragma data_seg()

Local static variables (GCC only)

When you declare local static variable, at least GCC compiler, puts a guard around the variable's constructor call. This ensures that only one thread can call the constructor at the same time to initialize it.

Why?

TODO: Fill this in.

Enabling local static variables

Note, that these are only stubs to get the code compiled, and you should implement them yourself. Simply add a mutex like guard with test and set primitive.

namespace __cxxabiv1 
{
	/* guard variables */

	/* The ABI requires a 64-bit type.  */
	__extension__ typedef int __guard __attribute__((mode (__DI__)));

	extern "C" int __cxa_guard_acquire (__guard *);
	extern "C" void __cxa_guard_release (__guard *);
	extern "C" void __cxa_guard_abort (__guard *);

	extern "C" int __cxa_guard_acquire (__guard *g) 
	{
		return !*(char *)(g);
	}

	extern "C" void __cxa_guard_release (__guard *g)
	{
		*(char *)g = 1;
	}

	extern "C" void __cxa_guard_abort (__guard *)
	{
	}
}

Actual code, emited by GCC, to call local static variable's constructor looks something like this:

static <type> guard;
if (!guard.first_byte) {
	if (__cxa_guard_acquire (&guard)) {
		bool flag = false;
		try {
			// Do initialization.
			__cxa_guard_release (&guard);
			flag = true;
			// Register variable for destruction at end of program.
		} catch {
			if (!flag) {
				__cxa_guard_abort (&guard);
			}
		}
	}
}

new and delete

Before you can use new and delete, you have to implement some memory management, and the operator new() and operator delete() functions (including their array counterparts).

Why?

new() and delete() allocate memory and free memory, respectively. For your kernel to allocate memory, it must somehow store what part of memory is used and what part of memory is free to be divided and allocated.

Enabling new and delete

Every time you call one of the operators new(), new[](), delete(), or delete[](), the compiler inserts a call to them. The most simple implementation would be to map them to kmalloc() / kfree(): (or malloc() and free() depending on your implementation)

//overload the operator "new"
void * operator new (uint_t size)
{
    return kmalloc(size);
}

//overload the operator "new[]"
void * operator new[] (uint_t size)
{
    return kmalloc(size);
}

//overload the operator "delete"
void operator delete (void * p)
{
    kfree(p);
}

//overload the operator "delete[]"
void operator delete[] (void * p)
{
    kfree(p);
}

An easy malloc implementation you can port to your OS is liballoc. It only requires basic page management (that is, store a list of used and free pages, and have a function to find the next free page) to work.

Other things you can try: Allocate and initialise memory

New can use kcalloc (allocate and zero) instead of kalloc to allocate memory and intialise it (that is, fill it with '\0's) otherwise the variables will be filled with garbage which you will then need to clear manually. (The standard implementations of operator new() and operator new[]() do not initialize the memory returned.)

Other things you can try: Placement new

In C++, and especially in OS code where structures can be found at fixed addresses, it can be useful to construct an object in memory obtained elsewhere. This is accomplished through a technique known as placement new. As an example, say you wanted to create an APIC object at address 0x09fff0000. This snippet of code will use placement new to do the trick:

 void* apic_address = reinterpret_cast<void*>(0x09fff0000);
 APIC* apic = new (apic_address) APIC;

In order to use placement new, you need special overloads of the new and delete operators defined in scope. Fortunately, the required definitions are simple and can be inlined in a header file (the C++ standard puts them in a header called <new>).

 inline void* operator new(uint_t, void* p)   throw() { return p; }
 inline void* operator new[](uint_t, void* p) throw() { return p; }
 inline void  operator delete  (void*, void*) throw() { };
 inline void  operator delete[](void*, void*) throw() { };

The above implementation can be potentially unsafe for allocating memory, since your kernel does not mark the memory that was allocated as being used. Placement new is hardly ever used, and if you wish to read an object from a specified address in memory, it is usually easier to create a pointer to that address. liballoc does not support placement new.

You never call placement delete explicitly (it's only required for certain implementation detail reasons). Instead, you simply invoke your object's destructor explicitly.

 apic->~APIC();

Builtins

GCC provides several standard library functions as builtins, which you most likely do not want in your kernel binary either. Disable them with -nostdlib

Note: the option -ffreestanding, usually recommended in kernel tutorials, cannot be used with G++.

Why?

Library routines are almost always OS-dependent. You can't mix code for two operating systems in a single operating system — it wouldn't work.

TODO: why -ffreestanding/--freestanding do not work.

Run-time type information

Run-time type information is used for typeid and dynamic_cast, and requires run-time support as well. Disable it with -fno-rtti.

Note that RTTI is required for some C++ features. If you disable it, you won't be able to use typeid or dynamic_cast. Virtual functions should work without RTTI, though.

Why?

RTTI stands for Run-Time Type Identification. A kernel has no access to run-time features, which are most likely operating system-dependent.

Exceptions

Another feature that requires run-time support. Disable them with -fno-exceptions.

Why?

Exceptions require code to unwind the stack while looking for an appropriate exception handler to handle the exception. Usually, this code is linked in with your C++ application, but in a freestanding kernel the code must be provided manually.

Enabling exceptions

TODO: Fill this in, rather than just dump links.

• http://www.codesourcery.com/cxx-abi/abi-eh.html (sounds like being Itanium specific, but that's actually the base for the common C++ ABI)
• http://www.codeproject.com/cpp/exceptionhandler.asp (explaining the stuff, but for VC++. Note that, on x86, VC++ and most other PC compilers use a stack-based unwinding and handling mechanism known as SEH, common to OS/2, Windows and Windows NT and described in detail in a famous MSJ article, http://www.microsoft.com/msj/0197/Exception/Exception.aspx. GCC and most other UNIX compilers, instead, use the same table-based mechanism that is the rule on RISC architectures on x86 too. Also note that any use of stack-based SEH may or may not be covered by USPTO patent #5,628,016, held by Borland International, Inc. SEH on RISC architectures is table-based, thus unaffected by the patent)
• http://www.kuzbass.ru:8086/docs/isocpp/except.html

Note that there is a standard header <exception>, declaring several support functions.

Standard Template Library

You cannot use Standard Template Library (or STL for short) functions and classes without porting a Standard Template Library implementation. These include std::vector, std::list, std::cin, std::cout, etc.

Why?

C++ classes and templates such as std::vector, std::list, std::cout, std::string, to name a few, are not actually part of the C++ language. They are part of a library called the Standard Template Library. A lot of the code depending on STL is OS-dependent, so you must port an STL implementation to your OS.

Porting a Standard Template Library

TODO: Create an article on porting STLport.

To gain access to the STL in your OS you can do either of the following: - Write your own implementation of a few of the required templates classes (std::string, std::list, std::cout, etc). - Port an STL implementation to your OS (e.g. STLport).

A lot of the STD classes require new and delete implemented in your OS. File access requires your OS to support reading and wrapping. Console functions require your OS to already have working console input/output.

Porting STL, the same with the C Standard Library, do not automatically make your OS to be able to read from and write to the disk, or to get data straight from the keyboard. These are simply wrappers around your OS's functions, and must be implemented by you.

Note that it is generally not a good idea to port the entire STL to your kernel, although it is reasonable to port a few classes, such as std::list and std::string if you wish to. As for your user applications; the more the merrier! :)

Standard Template Library Implementations

Here is a list of a the most commonly used STL implementations:

• STDCXX (a.k.a Apache C++ Standard Library, formally Rogue Wave C++ Standard Library)
• Dinkumware C++ Standard Library
• Microsoft C++ Standard Library (closed source)
• libstdc++ (a.k.a. GNU Standard C++ Library)
• STLport
• uSTL

Full C++ Runtime support with libgcc and libsupc++

The following description is true for i386, gcc 3.2 and libgcc/libsupc++ compiled for Linux/glibc (you can use the static gcc/supc++ libraries compiled for your Linux for your kernel).

If you want Exceptions, RTTI, nice new and delete operators altogether, you also could use libgcc and libsupc++. libgcc contains the unwinder (for exceptions), while libsupc++ contains the C++ support.

These functions look very complex (gcc_sources/gcc/unwind*, gcc_sources/libstdc++-v3/libsupc++/*), so maybe you shouldn't try to write an own unwinder or such, since there would be no benefit...

To get full C++ support, you only have to do the following:

• provide some libc functions like abort, malloc, free (and some more, maybe). libsupc++ needs them. There are even more functions you could support, like pthread_*, but since these are weak symbols, you don't need to define them.
• there's also a strange function dl_iterate_phdrs; you don't need this, let it simply return -1. It's normally used to find exception frames for dynamical linked objects... You also could compile libsupc++ in such a way, that this function isn't called anymore.
• To make use of exception handling, you also have to tell libsupc++ where the .eh_frames section begins, before you throw any exception: <verbatim> __register_frame(address_of_eh_frames); </verbatim>.
• Terminate the .eh_frame section with 4 bytes of zeros, somehow. If you forget this, libsupc++ will never find the end of .eh_frame and generate stupid pagefaults.

That's all. Please note that you still have to call the constructors/destructors by yourself.

Additionally, this sadly enlarges your kernel by ca. 50K (or even more).

You could also cross compile libsupc++ for your kernel.

Things you should know about optimizations

There are things you should know about optimizations that also affect C++ because it is an extension of the C language. You should know about them even if you don't plan to to use the optimizer of your C++ compiler in the near future.