8.8 KiB
libkernaux
)
Auxiliary library for kernel development.
Table of contents
API
Headers
We use semantic versioning for stable APIs. Stable APIs may only change when major version number is increased (or minor while major is zero). Work-in-progress APIs can change at any time.
- Basic features
- Feature macros (work in progress)
- Runtime environment (non-breaking since 0.7.0)
- Macros (non-breaking since 0.6.0)
- Stack trace (planned)
- Generic types
- Algorithms
- Free list memory allocator (non-breaking since 0.5.0)
- Simple command line parser (non-breaking since 0.2.0)
- Page Frame Allocator (work in progress)
- Data formats
- ELF (work in progress)
- MBR (work in progress)
- Multiboot 2 (GRUB 2) (non-breaking since 0.7.0)
- Utilities
- Measurement units utils (work in progress)
- Memory map (non-breaking since 0.7.0)
- printf format parser (non-breaking since 0.6.0)
- Usual functions
- itoa/ftoa replacement (non-breaking since 0.4.0)
- printf replacement (non-breaking since 0.5.0)
- libc replacement (work in progress)
- Architecture-specific code (work in progress)
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_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.KERNAUX_BITFIELDS- enable bitfields in packed structs. It doesn't follow the C standard and may be incompatible with some compilers.
Global variables
// in <kernaux/runtime.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 assertions are 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-checks- enable usual tests and examples--enable-checks-all- enable all checks--enable-checks-cppcheck- enable cppcheck--enable-checks-pthreads- enable tests that require pthreads--enable-checks-python- enable tests that require Python 3 with YAML and Jinja2--enable-fixtures- enable fixtures for tests and bindings--enable-pkg-config[=PATH]- install pkg-config files [PATH='${libdir}/pkgconfig']
Packages
--with-libc- provides the replacement for some standard C functions. Useful in freestanding environment, where no libc is present.
Default options
Features
--(enable|disable)-assert- assertions--(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]-multiboot2- Multiboot 2 utils--with[out]-ntoa- itoa/ftoa--with[out]-printf- printf
Tips
Installation
./autogen.sh # if present
./configure
make
sudo make install
sudo ldconfig # on GNU/Linux
This is just a usual library. You can use most of it's APIs in hosted environment.
Development
./autogen.sh # if present
./configure --enable-fixtures --enable-checks # or --enable-checks-all, but see prerequisites
make
You can test with make check.
See also
- GitHub Actions for GNU/Linux build environment
- Cirrus CI for FreeBSD build environment
- sourcehut CI for OpenBSD build environment
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' \
--disable-shared \
--enable-freestanding \
--with-libc \
CC="$(which i386-elf-gcc)"
The variables include AR, AS, CC, CCAS, LD, NM, OBJDUMP, RANLIB,
STRIP. See the generated config.log for more information.
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