libkernaux/README.md

libkernaux

Auxiliary library for kernel development.

Table of contents

• Overview
• Table of contents
• API
• Tips
  • Non-default options
  • Default options
  • Installation
  • Development
  • Cross
• Summary
  • Pure code size
  • Used header files
• Portability
• Discussion

API

• Runtime environment
  • Architecture-specific code
    • Declarations
    • Functions
  • Assertions
    • Simple
    • Guards
• Device drivers (for debugging only)
  • Serial console
  • Framebuffer (planned)
• Algorithms
  • Simple command line parser
    • Example
  • Page Frame Allocator
    • Example
• Data formats
  • Multiboot 2 (GRUB 2) information parser
  • ELF utils (work in progress)
• Utilities
  • Measurement units utils (work in progress)
    • To human
• Usual functions
  • libc replacement
    • memset
    • strcpy
    • strlen
  • itoa replacement (work in progress)
  • printf replacement (work in progress)
    • printf
    • printf_va

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 behabior 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

Default options

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

Installation

./autogen.sh
./configure
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-assert --enable-guard
make

You can test with make check.

Cross

The library depends on stdint.h header. According to the standards it must be present in freestanding environment. However when you build GCC cross-compiler using instructions from OSDev Wiki the header is missing. To fix this issue you may add use_gcc_stdint=provide to the end of gcc/config.gcc in your GCC source code extracted from tarball:

echo 'use_gcc_stdint=provide' >> gcc-11.2.0/gcc/config.gcc

---

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

When configured with cross-compiler, library can't be build and installed with just make && sudo make install. Instead use the following commands:

• make libkernaux.a
• sudo make install-exec install-data

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

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_hang>:
   0:   fa                    cli
   1:   f4                    hlt
   2:   eb fc                 jmp    0 <kernaux_asm_i386_hang>

00000004 <kernaux_asm_i386_read_cr0>:
   4:   0f 20 c0              mov    %cr0,%eax
   7:   c3                    ret

00000008 <kernaux_asm_i386_read_cr4>:
   8:   0f 20 e0              mov    %cr4,%eax
   b:   c3                    ret

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

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

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

Summary

This information is updated from time to time.

Pure code size

cloc --vcs=git include/ src/

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
C                               12            236             19           1548
C/C++ Header                    14            179             64            597
Assembly                         2              7              6             28
make                             1              0              0             13
-------------------------------------------------------------------------------
SUM:                            29            422             89           2186
-------------------------------------------------------------------------------

Used header files

git grep '#include <' -- include/ src/ | grep -v '#include <kernaux' | awk '{ print $2; }' | sort | uniq

• stdarg.h
• stdbool.h
• stddef.h
• stdint.h

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

Discussion

• Topic on OSDev.org forum
• Thread on r/osdev