libannwyn

Experimental userspace system library for Annwyn applications.

═════════════════════════════════════════════════════════

◉ What is libannwyn?

libannwyn provides the interface between userspace applications and the Annwyn microkernel.

All interactions with the kernel ultimately go through system calls.

The library currently provides:

✓ Syscall wrappers

✓ Process control

✓ Debug logging

✓ IPC primitives

✓ Endpoint management

✓ Capability operations

✓ Panic handling

Its purpose is to expose a simple and stable API while hiding low-level syscall details.

═════════════════════════════════════════════════════════

◉ Design Philosophy

⟦ Thin Abstraction Layer ⟧

libannwyn intentionally remains minimal.

Responsibilities include:

• Safe wrappers around syscalls

• Userspace convenience functions

• Kernel ABI definitions

• Basic runtime support

Responsibilities intentionally excluded:

• Filesystems

• Networking

• Allocators

• Collections

• Async runtimes

• High-level frameworks

Higher-level libraries belong in separate repositories.

═════════════════════════════════════════════════════════

◉ Project Status

⟦ Early Development ⟧

Current functionality focuses on exposing the kernel ABI.

The API should be considered unstable and will evolve together with the microkernel.

This repository is currently intended for experimentation rather than long-term compatibility.

═════════════════════════════════════════════════════════

◉ Current Progress

Implemented

• Syscall wrappers
• Process exit
• Yield
• Serial logging
• Endpoint creation
• IPC send
• IPC receive
• Capability revocation
• Panic handler

In Progress

• Memory mapping API
• Exec support
• Error codes
• Safer abstractions

Planned

• Capability objects
• IPC message structures
• Allocator support
• Thread API
• Async primitives

═════════════════════════════════════════════════════════

◉ Usage

Logging

use libannwyn::log;

log("Hello from userspace!");

Yielding the CPU

use libannwyn::yield_now;

yield_now();

Exiting

use libannwyn::exit;

exit(0);

Endpoint Creation

use libannwyn::endpoint_create;

let endpoint = endpoint_create();

Sending IPC Messages

use libannwyn::ipc_send;

ipc_send(cap_id, endpoint_id, b"hello");

═════════════════════════════════════════════════════════

◉ Syscall Interface

Current syscall numbers:

ID	Name
0	SYS_LOG
1	SYS_YIELD
2	SYS_EXIT
3	SYS_IPC_SEND
4	SYS_IPC_RECV
6	SYS_CAP_REVOKE
7	SYS_MEM_MAP
8	SYS_ENDPOINT_CREATE
9	SYS_EXEC

These definitions must remain synchronized with the kernel syscall table.

═════════════════════════════════════════════════════════

◉ Panic Handling

⟦ Fail Fast ⟧

The default panic handler:

1. Logs "PANIC".

2. Terminates the process.

This behavior may evolve as the userspace runtime becomes more sophisticated.

═════════════════════════════════════════════════════════

◉ Contributing

Contributions, discussions, ideas, criticism, and questions are welcome.

Please keep in mind that:

• ABI stability is more important than features.

• Simplicity is preferred over abstraction.

• Syscall definitions must remain synchronized with the kernel.

• Unsafe code should be carefully justified.

═════════════════════════════════════════════════════════

◉ Related Repositories

• annwyn-kernel

• annwyn-runtime

• annwyn-sdk

• annwyn-docs

═════════════════════════════════════════════════════════

◉ License

Licensed under either of:

• MIT License

• Apache License 2.0

at your option.