Auxiliary library for kernel development
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Alex Kotov 123bddd19c
File input (#107)
3 months ago
.github Move drivers to separate subdirectory (#91) 3 months ago
bindings Improve cmdline file API (#103) 3 months ago
build Create "dev" configs 8 months ago
common Improve cmdline file API (#103) 3 months ago
config Move drivers to separate subdirectory (#91) 3 months ago
dest Create "dev" configs 8 months ago
examples File input (#107) 3 months ago
include File input (#107) 3 months ago
libc Maintenance (#98) 3 months ago
m4 Split Make file into subdirectories (#48) 4 months ago
src File input (#107) 3 months ago
tests Remove cmdline file API (#105) 3 months ago
vendor Common: upgrade "vendor/cross" 4 months ago
.cirrus.yml Add debug mode and rewrite assertions (#52) 3 months ago
.gitignore Add macros `KERNAUX_BITS[8|16|32|64]` (#106) 3 months ago
.gitmodules Test mruby package 8 months ago
AUTHORS Fix AUTHORS 8 months ago
CONTRIBUTING.md Maintenance (#98) 3 months ago
COPYING Main: COPYING: add Embedded Artistry LLC 3 months ago
ChangeLog Add macros `KERNAUX_BITS[8|16|32|64]` (#106) 3 months ago
Makefile.am Remove cmdline file API (#105) 3 months ago
NEWS Fix: Bump version (0.2.0) 8 months ago
NEWS.md Bump version (0.4.0) [1/2] 3 months ago
README Initial commit 2 years ago
README.md Add macros `KERNAUX_BITS[8|16|32|64]` (#106) 3 months ago
VERSION Bump version (0.4.0) [1/2] 3 months ago
autogen.sh Main: autogen.sh: enable warnings 4 months ago
configure.ac Async cmdline (#104) 3 months ago
sha256sums.txt Bump version (0.4.0) [2/2] 3 months ago
shared.am Main: libm/: Remove 4 months ago
test-suite-log Main: fix script "test-suite-log" 4 months ago

README.md

libkernaux

Build status Build status (FreeBSD)

Auxiliary library for kernel development.

Topic on OSDev.org forum.

Table of contents

API

Headers

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.

Definitions

#define the following C preprocessor macros before including <kernaux.h> and <kernaux/*.h> files. They have effect on your code, not the library code.

  • KERNAUX_DEBUG - enable assertions.
  • KERNAUX_ACCESS_PRIVATE - disable access modifier "private". Don't do this!
  • KERNAUX_ACCESS_PROTECTED - disable access modifier "protected". Only do this in a file where you implement an inherited type.

Global variables

// in <kernaux/assert.h>
void (*kernaux_assert_cb)(const char *file, int line, const char *msg)

Assertion callback. It's better to always set it to some function which always interrupts the execution, even when debugging is disabled. It may for example call abort() in hosted environment, raise an exception in Ruby, panic in Rust or power off the machine in freestanding environment. It may also log the error location and message.

Configuration

Because this library has no external dependencies, we use autoconf features to control behavior of the library, and packages to choose it's components. Configuration options also follow the semantic versioning scheme and are split into stable and work-in-progress ones. Here we cover only stable options.

Non-default options

Features

  • --enable-tests - enable usual tests and examples
  • --enable-tests-all - enable all tests
  • --enable-tests-python - enable tests that require Python 3 with YAML and Jinja2

Packages

  • --with-drivers - device drivers
  • --with-libc - provides the replacement for some standard C functions. Useful in freestanding environment, where no libc is present.

Default options

Features

  • --(enable|disable)-debug - debugging
  • --(enable|disable)-float - floating-point arithmetic
  • --(enable|disable)-werror - fail on warning (CFLAGS+='-Werror')

Packages

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

  • --with[out]-arch-all - all architectures
  • --with[out]-arch-i386 - architecture i386
  • --with[out]-arch-riscv64 - architecture riscv64
  • --with[out]-arch-x86-64 - architecture x86-64
  • --with[out]-asm - kernel assembler helpers
  • --with[out]-cmdline - command line parser
  • --with[out]-free-list - free list memory allocator
  • --with[out]-memmap - memory map
  • --with[out]-ntoa - itoa/ftoa
  • --with[out]-printf - printf

Tips

Installation

./autogen.sh # if present
./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 # if present
./configure --enable-tests # or --enable-tests-all, but see prerequisites
make

You can test with make check.

Cross

Create configuration script with ./autogen.sh (if present).

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-freestanding \
  --with-drivers \
  --with-libc \
  AR="$(which i386-elf-ar)" \
  CC="$(which i386-elf-gcc)" \
  RANLIB="$(which i386-elf-ranlib)"

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