www.kamkow1lair.pl/content/blog/MOP2/intro.adoc

= Intro to MOP2 programming
Kamil Kowalczyk
2025-10-14
:jbake-type: post
:jbake-tags: MOP2 osdev
:jbake-status: published

This is an introductory post into MOP2 (my-os-project2) user application programming.

All source code (kernel, userspace and other files) are available at https://git.kamkow1lair.pl/kamkow1/my-os-project2.

Let's start by doing the most basic thing ever: quitting an application.

== AMD64 assembly

.Hello program in AMD64 assembly
[source,asm]
----
.section .text

.global _start
_start: // our application's entry point
  movq $17, %rax    // select proc_kill() syscall
  movq $-1, %rdi    // -1 means "self", so we don't need to call proc_getpid()
  int $0x80         // perform the syscall
  // We are dead!!
----

As you can see, even though we're on AMD64, we use `int $0x80` to perform a syscall.

The technically correct and better way would be to implement support for `syscall/sysret`, but `int $0x80` is
just easier to get going and requires way less setup. Maybe in the future the ABI will move towards
`syscall/sysret`.

`int $0x80` is not ideal, because it's a software interrupt and these come with a lot of interrupt overhead.
Intel had tried to solve this before with `sysenter/sysexit`, but they've fallen out of fasion due to complexity.

For purposes of a silly hobby OS project, `int $0x80` is completely fine. We don't need to have world's best
performance (yet ;) ).

=== "Hello world" and the `debugprint()` syscall

Now that we have our first application, which can quit at a blazingly fast speed, let's try to print something.
For now, we're not going to discuss IPC and pipes, because that's a little complex.

The `debugprint()` syscall came about as the first syscall ever (it even has an ID of 1) and it was used for
printing way before pipes were added into the kernel. It's still useful for debugging purposes, when we want to
literally just print a string and not go through the entire pipeline of printf-style formatting and only then
writing something to a pipe.

.Usage of `debugprint()` in AMD64 assembly
[source,asm]
----
.section .data

STRING:
  .string "Hello world!!!"

.section .text

.global _start
_start: 
  movq $1, %rax     // select debugprint()
  lea STRING(%rip),     %rdi    // load STRING
  int $0x80

  // quit
  movq $17, %rax
  movq $-1, %rdi
  int $0x80
----

Why are we using `lea` to load stuff? Why not `movq`? Because we can't...

We can't just `movq`, because the kernel doesn't support relocatable code - everything is loaded at a fixed
address in a process' address space. Because of this, we have to address everything relatively to `%rip` 
(the instruction pointer). We're essentially writing position independent code (PIC) by hand. This is what
the `-fPIC` GCC flag does, BTW.

== Getting into C and some bits of `ulib`

Now that we've gone overm how to write some (very) basic programs in assembly, let's try to untangle, how we get
into C code and understand some portions of `ulib` - the userspace programming library.

This code snippet should be understandable by now:
._start.S
[source,asm]
----
.extern _premain

.global _start
_start:
  call _premain
----

Here `_premain()` is a C startup function that gets executed before running `main()`. `_premain()` is also
responsible for quitting the application.

._premain.c
[source,c]
----
// Headers skipped.

extern void main(void);
extern uint8_t _bss_start[];
extern uint8_t _bss_end[];

void clearbss(void) {
  uint8_t *p = _bss_start;
  while (p < _bss_end) {
    *p++ = 0;
  }
}

#define MAX_ARGS 25
static char *_args[MAX_ARGS];

size_t _argslen;

char **args(void) {
  return (char **)_args;
}

size_t argslen(void) {
  return _argslen;
}

// ulib initialization goes here
void _premain(void) {
  clearbss();

  for (size_t i = 0; i < ARRLEN(_args); i++) {
    _args[i] = umalloc(PROC_ARG_MAX);
  }

  proc_argv(-1, &_argslen, _args, MAX_ARGS);

  main();
  proc_kill(proc_getpid());
}
----

First, in order to load our C application without UB from the get go, we need to clear the `BSS` section of an
ELF file (which MOP2 uses as it's executable format). We use `_bss_start` and `_bss_end` symbols for that, which
come from a linker script defined for user apps:

.link.ld - linker script for user apps
[source]
----
ENTRY(_start)

SECTIONS {
  . = 0x400000;

  .text ALIGN(4K):
  {
    *(.text .text*)
  }
  
  .rodata (READONLY): ALIGN(4K)
  {
    *(.rodata .rodata*)
  }

  .data ALIGN(4K):
  {
    *(.data .data*)
  }

  .bss ALIGN(4K):
  {
    _bss_start = .;
    *(.bss .bss*)
    . = ALIGN(4K);
    _bss_end = .;
  }
}
----

After that, we need to collect our application's commandline arguments (like argc and argv in UNIX-derived
systems). To do that we use a `proc_argv()` syscall, which fills out a preallocated memory buffer with. The main
limitation of this approach is that the caller must ensure that enough space withing the buffer was allocated.
25 arguments is enough for pretty much all appliations on this system, but this is something that may be a little
problematic in the future.

After we've exited from `main()`, we just gracefully exit the application.

=== "Hello world" but from C this time

Now we can program our applications the "normal"/"human" way. We've gone over printing in assembly using the
`debugprint()` syscall, so let's now try to use it from C. We'll also try to do some more advanced printing
with (spoiler) `uprintf()`.

.Calling `debugprint()` from C
[source,c]
----
// Import `ulib`
#include <ulib.h>

void main(void) {
  debugprint("hello world");
}
----

That's it! We've just printed "hello world" to the terminal! How awesome is that?

.`uprintf()` and formatted printing
[source,c]
----
#include <ulib.h>

void main(void) {
  uprintf("Hello world %d %s %02X\n", 123, "this is a string literal", 0xBE);
}
----

`uprintf()` is provided by Eyal Rozenberg (eyalroz), which originates from Macro Paland's printf. This printf
library is super easily portable and doesn't require much in terms of standard C functions and headers. My main
nitpick and a dealbreaker with other libraries was that they advertise themsevles as "freestanding" or "made for
embedded" or something along those lines, but in reality they need so much of the C standard library, that you
migh as well link with musl or glibc and use printf from there. And generally speaking, this is an issue with
quite a bit of "freestanding" libraries that you can find online ;(.

Printf rant over...

=== Error codes in MOP2

You might've noticed is that `main()` looks a little different from standard C `main()`. There's
no return/error code, because MOP2 simply does not implement such feature. This is because MOP2 doesn't follow the
UNIX philosophy.

The UNIX workflow consists of combining many small/tiny programs into a one big commandline, which transforms text
into some more text. For eg.:

.Example bash command (Linux) to get a name of /proc/meminfo field
[source,shell]
----
cat /proc/meminfo | awk 'NR==20 {print $1}' | rev | cut -c 2- | rev
----

Personally, I dislike this type of workflow. I prefer to have a few programs that perform tasks groupped by topic,
so for eg. in MOP2, we have `$fs` for working with the filesystem or `$pctl` for working with processes. When we
approach things the MOP2 way, it turns out error codes are kind of useless (or at least they wouldn't get much
use), since we don't need to connect many programs together to get something done.