libkernaux

Auxiliary library for kernel development.

Topic on OSDev.org forum.

Table of contents

• Overview
• Table of contents
• API
• Tips
  • Non-default options
  • Default options
  • Installation
  • Development
  • Cross
• Architectures
• Portability

API

We use semantic versioning for stable APIs. Stable APIs can only change when major version number is increased (or minor while major is zero). Work-in-progress APIs can change at any time.

• Runtime environment
  • Architecture-specific code (work in progress)
    • Declarations
    • Functions
  • Assertions (stable since 0.1.0)
    • Assert: simple
    • Assert: guards
    • Panic: simple
    • Panic: guards
  • Stack trace (planned)
• Device drivers (for debugging only)
  • Serial console (work in progress)
  • Framebuffer (planned)
  • USB (planned)
• Algorithms
  • Simple command line parser (work in progress)
    • Example
  • Page Frame Allocator (work in progress)
    • Example
• Data formats
  • ELF (work in progress)
  • Master Boot Record (work in progress)
  • Multiboot 2 (GRUB 2) (work in progress)
  • Stivale 2 (Limine) (planned)
• Utilities
  • Measurement units utils (work in progress)
    • To human
• Usual functions
  • libc replacement (stable since 0.1.0)
  • itoa/ftoa replacement (stable since 0.1.0)
  • printf replacement (stable since 0.1.0)
    • Code from https://github.com/mpaland/printf. Thank you!
    • printf
    • vprintf
    • snprintf
    • vsnprintf

Tips

Non-default options

Because this library has no external dependencies, we use autoconf features to control behavior of the library, and packages to choose it's components. Here are some non-default options:

• --enable-assert - use value of extern variable kernaux_assert_cb as a callback function for internal assertions. You still can use assertions in your own application (kernel) even if this option was not enabled.
• --enable-guard - safely return from functions even when assertions are disabled. This option doesn't have effect if your assetion function was set and ends execution of application (kernel). However it prevents crashes and undefined behavior in other cases. You can also separately enable or disable guards:
  • --(enable|disable)-guard-cond
  • --(enable|disable)-guard-null
• --with-libc - provides the replacement for some standard C functions. Useful in freestanding environment, where no libc is present. You can also separately include or exclude components:
  • --with[out]-libc-memset
  • --with[out]-libc-strcpy
  • --with[out]-libc-strlen
  • --with[out]-libc-strnlen

Default options

Features

• --enable-bloat, disable with --disable-bloat
• --enable-float, disable with --disable-float

Packages

All packages all included by default. To exclude all packages except those explicitly included, use --without-all.

• --with[out]-cmdline
• --with[out]-console
• --with[out]-elf
• --with[out]-framebuffer
• --with[out]-mbr
• --with[out]-multiboot2
• --with[out]-ntoa
• --with[out]-printf
• --with[out]-pfa
• --with[out]-units

Installation

./autogen.sh
./configure CFLAGS='-fPIC'
make
sudo make install

This is just a usual library. You can use most of it's APIs in hosted environment.

Development

./autogen.sh
./configure --enable-tests --enable-assert --enable-guard CFLAGS='-fPIC'
make

You can test with make check.

Cross

Create configuration script with ./autogen.sh.

Let's assume that your target triplet is i386-elf. Configure with cross-compiler in $PATH to make without it in $PATH:

./configure \
  --host='i386-elf' \
  --enable-assert \
  --enable-guard \
  --with-libc \
  AR="$(which i386-elf-ar)" \
  CC="$(which i386-elf-gcc)" \
  RANLIB="$(which i386-elf-ranlib)" \
  CFLAGS='-ffreestanding -nostdlib -fno-builtin -fno-stack-protector'

You can see the following messages. It's a bug in autoconf, just ignore it.

checking for _Bool... no
checking stdarg.h usability... no
checking stdarg.h presence... yes
configure: WARNING: stdarg.h: present but cannot be compiled
configure: WARNING: stdarg.h:     check for missing prerequisite headers?
configure: WARNING: stdarg.h: see the Autoconf documentation
configure: WARNING: stdarg.h:     section "Present But Cannot Be Compiled"
configure: WARNING: stdarg.h: proceeding with the compiler's result
configure: WARNING:     ## ---------------------------------------------------------- ##
configure: WARNING:     ## Report this to https://github.com/tailix/libkernaux/issues ##
configure: WARNING:     ## ---------------------------------------------------------- ##
checking for stdarg.h... no
checking stddef.h usability... no
checking stddef.h presence... yes
configure: WARNING: stddef.h: present but cannot be compiled
configure: WARNING: stddef.h:     check for missing prerequisite headers?
configure: WARNING: stddef.h: see the Autoconf documentation
configure: WARNING: stddef.h:     section "Present But Cannot Be Compiled"
configure: WARNING: stddef.h: proceeding with the compiler's result
configure: WARNING:     ## ---------------------------------------------------------- ##
configure: WARNING:     ## Report this to https://github.com/tailix/libkernaux/issues ##
configure: WARNING:     ## ---------------------------------------------------------- ##
checking for stddef.h... no

To install into specific directory use full path: DESTDIR="$(pwd)/dest" make install instead of DESTDIR=dest make install.

Check if compilation targets i386: objdump -d src/asm/i386.o. It should output something like this:

src/asm/i386.o:     file format elf32-i386


Disassembly of section .text:

00000000 <kernaux_asm_i386_read_cr0>:
   0:   0f 20 c0              mov    %cr0,%eax
   3:   c3                    ret

00000004 <kernaux_asm_i386_read_cr4>:
   4:   0f 20 e0              mov    %cr4,%eax
   7:   c3                    ret

00000008 <kernaux_asm_i386_write_cr0>:
   8:   8b 44 24 04           mov    0x4(%esp),%eax
   c:   0f 22 c0              mov    %eax,%cr0
   f:   c3                    ret

00000010 <kernaux_asm_i386_write_cr3>:
  10:   8b 44 24 04           mov    0x4(%esp),%eax
  14:   0f 22 d8              mov    %eax,%cr3
  17:   c3                    ret

00000018 <kernaux_asm_i386_write_cr4>:
  18:   8b 44 24 04           mov    0x4(%esp),%eax
  1c:   0f 22 e0              mov    %eax,%cr4
  1f:   c3                    ret

Architectures

Architectures should be properly identified. We use the following scheme, but it may change in future:

• x86
  • i386
  • x86_64
• riscv
  • riscv64

Portability

Except GNU/Linux, the library is periodically successfully built (starting with ./autogen.sh) and tested with autoconf, automake, binutils and gcc/clang (depending on what is present) on the following operating systems:

• FreeBSD 13.0
• Minix 3.3.0
• NetBSD 9.2
• OpenBSD 7.0