2020-11-27 04:28:13 -05:00
libkernaux
==========
2022-01-31 04:27:39 -05:00
[![Build status ](https://github.com/tailix/libkernaux/actions/workflows/main.yml/badge.svg )](https://github.com/tailix/libkernaux/actions/workflows/main.yml)
2022-01-31 10:39:41 -05:00
[![Build status (FreeBSD) ](https://api.cirrus-ci.com/github/tailix/libkernaux.svg?task=Main%20(FreeBSD ))](https://cirrus-ci.com/github/tailix/libkernaux)
2021-12-13 17:36:06 -05:00
2020-11-27 04:28:13 -05:00
Auxiliary library for kernel development.
2020-11-27 08:38:58 -05:00
2022-01-20 16:39:56 -05:00
[Topic on OSDev.org forum ](https://forum.osdev.org/viewtopic.php?f=1&t=37958 ).
2020-11-27 08:38:58 -05:00
2020-11-28 18:52:51 -05:00
Table of contents
-----------------
* [Overview ](#libkernaux )
* [Table of contents ](#table-of-contents )
2020-11-29 20:21:22 -05:00
* [API ](#api )
2022-06-15 07:24:42 -04:00
* [Headers ](#headers )
2022-06-13 12:28:00 -04:00
* [Definitions ](#definitions )
* [Global variables ](#global-variables )
2022-01-22 12:18:18 -05:00
* [Configuration ](#configuration )
2021-12-17 20:47:01 -05:00
* [Non-default options ](#non-default-options )
2022-01-10 11:03:37 -05:00
* [Default options ](#default-options )
2022-01-22 12:18:18 -05:00
* [Tips ](#tips )
2021-12-16 03:14:39 -05:00
* [Installation ](#installation )
* [Development ](#development )
2022-06-07 01:19:14 -04:00
* [Cross ](#cross )
2020-11-28 18:52:51 -05:00
2020-11-29 20:21:22 -05:00
API
---
2022-06-15 07:24:42 -04:00
### Headers
2022-01-20 07:40:18 -05:00
We use [semantic versioning ](https://semver.org ) 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.
2021-12-15 06:03:14 -05:00
* Runtime environment
2022-06-14 06:44:35 -04:00
* [Feature macros ](/include/kernaux/version.h.in ) (*work in progress*)
2022-06-16 11:27:48 -04:00
* [Assertions ](/include/kernaux/assert.h ) (*non-breaking since* **0.4.0** )
2022-06-16 13:37:19 -04:00
* [Example: Assert ](/examples/assert.c )
* [Example: Panic ](/examples/panic.c )
2022-01-12 05:56:39 -05:00
* Stack trace *(planned)*
2022-06-14 08:03:17 -04:00
* [Input/output ](/include/kernaux/io.h ) (*work in progress*)
2022-06-13 04:52:31 -04:00
* Architecture-specific code (*work in progress*)
* [Declarations ](/include/kernaux/arch/ )
* [Functions ](/include/kernaux/asm/ )
2022-06-20 17:28:35 -04:00
* Generic types
2022-06-21 04:37:52 -04:00
* [Memory allocator ](/include/kernaux/generic/malloc.h ) (*non-breaking since* ** ?.?.?**)
* [Example ](/examples/generic_malloc.c )
2022-06-20 17:28:35 -04:00
* [Mutex ](/include/kernaux/generic/mutex.h ) (*non-breaking since* ** ?.?.?**)
2022-06-21 02:46:23 -04:00
* [Example ](/examples/generic_mutex.c )
2021-12-15 06:03:14 -05:00
* Algorithms
2022-06-22 05:39:53 -04:00
* [Free list memory allocator ](/include/kernaux/free_list.h ) (*non-breaking since* ** ?.?.?**)
2022-06-15 07:31:19 -04:00
* [Simple command line parser ](/include/kernaux/cmdline.h ) (*non-breaking since* **0.2.0** )
2021-12-15 06:03:14 -05:00
* [Example ](/examples/cmdline.c )
2022-01-20 07:40:18 -05:00
* [Page Frame Allocator ](/include/kernaux/pfa.h ) (*work in progress*)
2021-12-15 06:03:14 -05:00
* [Example ](/examples/pfa.c )
* Data formats
2022-01-20 07:40:18 -05:00
* [ELF ](/include/kernaux/elf.h ) (*work in progress*)
* [Master Boot Record ](/include/kernaux/mbr.h ) (*work in progress*)
* [Multiboot 2 (GRUB 2) ](/include/kernaux/multiboot2.h ) (*work in progress*)
2021-12-15 06:03:14 -05:00
* Utilities
2022-01-20 07:40:18 -05:00
* [Measurement units utils ](/include/kernaux/units.h ) (*work in progress*)
2022-06-16 13:37:19 -04:00
* [Example: To human ](/examples/units_human.c )
2022-06-16 11:27:48 -04:00
* [Memory map ](/include/kernaux/memmap.h.in ) (*non-breaking since* **0.4.0** )
2022-06-15 03:58:14 -04:00
* [Example ](/examples/memmap.c )
2022-06-03 21:37:25 -04:00
* [printf format parser ](/include/kernaux/printf_fmt.h ) (*work in progress*)
* Code from [https://github.com/mpaland/printf ](https://github.com/mpaland/printf ). Thank you!
* [Example ](/examples/printf_fmt.c )
2021-12-15 06:03:14 -05:00
* Usual functions
2022-06-16 11:27:48 -04:00
* [itoa/ftoa replacement ](/include/kernaux/ntoa.h ) (*non-breaking since* **0.4.0** )
2022-05-30 16:43:58 -04:00
* [Example ](/examples/ntoa.c )
2022-06-16 11:27:48 -04:00
* [printf replacement ](/include/kernaux/printf.h.in ) (*non-breaking since* **0.4.0** )
2022-01-19 17:56:58 -05:00
* Code from [https://github.com/mpaland/printf ](https://github.com/mpaland/printf ). Thank you!
2022-06-16 13:37:19 -04:00
* [Example: fprintf ](/examples/fprintf.c )
* [Example: vfprintf ](/examples/fprintf_va.c )
* [Example: snprintf ](/examples/snprintf.c )
* [Example: vsnprintf ](/examples/snprintf_va.c )
2022-06-13 04:52:31 -04:00
* libc replacement (*work in progress*)
2022-06-07 23:20:08 -04:00
* [ctype.h ](/libc/include/ctype.h )
2022-06-13 04:52:31 -04:00
* [inttypes.h ](/libc/include/inttypes.h )
2022-06-15 10:23:52 -04:00
* [setjmp.h ](/libc/include/setjmp.h )
2022-06-07 23:20:08 -04:00
* [stdlib.h ](/libc/include/stdlib.h )
* [string.h ](/libc/include/string.h )
2022-06-13 04:52:31 -04:00
* [sys/types.h ](/libc/include/sys/types.h )
2022-06-23 06:43:53 -04:00
* Device drivers (for debugging only)
* [Serial console ](/include/kernaux/drivers/console.h ) (*work in progress*)
* [Framebuffer ](/include/kernaux/drivers/framebuffer.h ) (*planned*)
* [Intel 8259 PIC ](/include/kernaux/drivers/intel_8259_pic.h ) (*planned*)
* USB (*planned*)
2020-11-29 20:21:22 -05:00
2022-06-13 12:28:00 -04:00
### Definitions
2022-06-21 05:42:31 -04:00
`#define` the following C preprocessor macros before including `<kernaux.h>` and
2022-06-13 12:28:00 -04:00
`<kernaux/*.h>` files. They have effect on your code, not the library code.
2022-06-20 17:28:35 -04:00
* `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
2022-06-21 05:42:31 -04:00
in a file where you implement an inherited type.
2022-06-13 12:28:00 -04:00
### Global variables
```c
// 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.
2020-11-29 20:21:22 -05:00
2022-01-22 12:18:18 -05:00
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 ](https://semver.org )
2022-01-22 16:37:53 -05:00
scheme and are split into stable and work-in-progress ones. Here we cover only
2022-01-22 12:18:18 -05:00
stable options.
2020-11-27 08:38:58 -05:00
2021-12-17 20:47:01 -05:00
### Non-default options
2022-05-24 13:46:19 -04:00
#### 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
2022-06-07 01:19:14 -04:00
#### Packages
2022-06-23 06:43:53 -04:00
* `--with-drivers` - device drivers
2022-06-07 01:35:14 -04:00
* `--with-libc` - provides the replacement for some standard C functions.
Useful in freestanding environment, where no libc is present.
2022-06-07 01:19:14 -04:00
2022-01-10 11:03:37 -05:00
### Default options
2022-01-20 07:25:58 -05:00
#### Features
2022-01-20 07:22:34 -05:00
2022-06-13 12:28:00 -04:00
* `--(enable|disable)-debug` - debugging
2022-05-24 14:47:10 -04:00
* `--(enable|disable)-float` - floating-point arithmetic
* `--(enable|disable)-werror` - fail on warning (`CFLAGS+='-Werror'`)
2022-01-19 06:40:12 -05:00
2022-01-20 07:25:58 -05:00
#### Packages
2022-05-24 21:57:28 -04:00
All packages are included by default. To exclude all packages except those
2022-01-20 07:25:58 -05:00
explicitly included, use `--without-all` .
2022-01-20 07:22:34 -05:00
2022-02-01 22:23:33 -05:00
* `--with[out]-cmdline` - command line parser
2022-06-22 05:39:53 -04:00
* `--with[out]-free-list` - free list memory allocator
2022-06-16 11:27:48 -04:00
* `--with[out]-io` - input/output
2022-06-15 07:29:49 -04:00
* `--with[out]-memmap` - memory map
2022-02-01 22:23:33 -05:00
* `--with[out]-ntoa` - itoa/ftoa
* `--with[out]-printf` - printf
2022-01-22 12:18:18 -05:00
Tips
----
2022-01-10 11:03:37 -05:00
2021-12-16 03:14:39 -05:00
### Installation
2021-12-12 11:29:39 -05:00
```
2022-05-24 15:12:50 -04:00
./autogen.sh # if present
2022-02-01 21:26:35 -05:00
./configure
2021-12-12 11:29:39 -05:00
make
sudo make install
```
2021-12-13 17:26:53 -05:00
This is just a usual library. You can use most of it's APIs in hosted
environment.
2021-12-12 11:29:39 -05:00
2021-12-16 03:14:39 -05:00
### Development
```
2022-05-24 15:12:50 -04:00
./autogen.sh # if present
2022-05-24 13:46:19 -04:00
./configure --enable-tests # or --enable-tests-all, but see prerequisites
2021-12-16 03:14:39 -05:00
make
```
You can test with `make check` .
2022-06-07 01:19:14 -04:00
### Cross
2021-12-12 11:29:39 -05:00
2022-05-24 15:12:50 -04:00
Create configuration script with `./autogen.sh` (if present).
2020-11-29 10:49:12 -05:00
2021-12-14 19:10:40 -05:00
Let's assume that your target triplet is `i386-elf` . Configure with
2022-01-12 00:07:53 -05:00
[cross-compiler ](https://wiki.osdev.org/GCC_Cross-Compiler ) in `$PATH` to make
without it in `$PATH` :
2020-11-27 08:38:58 -05:00
```
./configure \
2021-12-14 19:10:40 -05:00
--host='i386-elf' \
2022-06-04 09:01:02 -04:00
--enable-freestanding \
2022-06-23 06:43:53 -04:00
--with-drivers \
2022-06-07 01:35:14 -04:00
--with-libc \
2021-12-14 19:10:40 -05:00
AR="$(which i386-elf-ar)" \
CC="$(which i386-elf-gcc)" \
2022-06-04 09:01:02 -04:00
RANLIB="$(which i386-elf-ranlib)"
2020-11-27 08:38:58 -05:00
```
2021-12-12 11:29:39 -05:00
You can see the following messages. It's
2020-12-06 06:41:36 -05:00
[a bug ](https://savannah.gnu.org/support/index.php?110393 ) in **autoconf** , just
ignore it.
2020-12-06 05:27:55 -05:00
```
checking for _Bool... no
2020-12-06 19:11:55 -05:00
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
2021-12-12 07:13:52 -05:00
configure: WARNING: ## ---------------------------------------------------------- ##
configure: WARNING: ## Report this to https://github.com/tailix/libkernaux/issues ##
configure: WARNING: ## ---------------------------------------------------------- ##
2020-12-06 19:11:55 -05:00
checking for stdarg.h... no
2020-12-06 05:27:55 -05:00
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
2021-12-12 07:13:52 -05:00
configure: WARNING: ## ---------------------------------------------------------- ##
configure: WARNING: ## Report this to https://github.com/tailix/libkernaux/issues ##
configure: WARNING: ## ---------------------------------------------------------- ##
2020-12-06 06:22:56 -05:00
checking for stddef.h... no
2020-12-06 05:27:55 -05:00
```
2022-01-17 07:33:28 -05:00
To install into specific directory use full path: `DESTDIR="$(pwd)/dest" make
install` instead of `DESTDIR=dest make install` .
2020-11-29 11:01:11 -05:00
2021-12-20 01:14:40 -05:00
Check if compilation targets i386: `objdump -d src/asm/i386.o` . It should output
something like this:
2020-11-27 08:38:58 -05:00
```
2021-12-20 01:14:40 -05:00
src/asm/i386.o: file format elf32-i386
2020-11-27 08:38:58 -05:00
Disassembly of section .text:
2022-01-15 05:42:13 -05:00
00000000 < kernaux_asm_i386_read_cr0 > :
0: 0f 20 c0 mov %cr0,%eax
3: c3 ret
2020-11-27 08:38:58 -05:00
2022-01-15 05:42:13 -05:00
00000004 < kernaux_asm_i386_read_cr4 > :
4: 0f 20 e0 mov %cr4,%eax
2020-11-27 08:38:58 -05:00
7: c3 ret
2022-01-15 05:42:13 -05:00
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
2020-11-27 08:38:58 -05:00
2022-01-15 05:42:13 -05:00
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
2020-11-27 08:38:58 -05:00
2022-01-15 05:42:13 -05:00
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
2020-11-27 08:38:58 -05:00
```