• nux, nucis : .gen. plur. nucerum for nucum, f. etym. dub., a nut.

For a high-level introduction on NUX and its motivation, check this article.

This branch features a comprehensive transformation to COM-style architecture with NT coding conventions and UEFI documentation.

• COM Infrastructure: Complete IUnknown-based interface system with vtables
• NT Coding Style: PascalCase naming, Hungarian notation, proper parameter annotations
• UEFI Documentation: Professional Doxygen-style comments throughout
• Backward Compatibility: All legacy APIs preserved via inline wrappers

• Interface Segregation: Clean separation of HAL/PLT subsystems into focused interfaces
• Extensibility: QueryInterface support for runtime interface discovery
• Binary Compatibility: Stable vtable-based ABI
• Standard Error Handling: Industry-standard HRESULT return values

See TRANSFORMATION_GUIDE.md for complete details on:

• Transformation rationale and benefits
• COM architecture overview
• Migration guide for developers
• NT coding style conventions
• UEFI commenting standards

Core Infrastructure:

• include/nux/combase.h - COM base types and IUnknown interface
• include/nux/types.h - NT-style type definitions

Interface Layers (22 COM Interfaces Total):

• include/nux/hal.h - Hardware Abstraction Layer (7 COM interfaces)
• include/nux/plt.h - Platform Layer (5 COM interfaces)
• include/nux/nux.h - Main Kernel API (10 COM interfaces)

Utilities and Services:

• include/nux/defs.h - Page size and alignment macros
• include/nux/locks.h - Spinlock and RW-lock primitives
• include/nux/slab.h - Slab allocator API
• include/nux/slabinc.h - Slab allocator internal structures
• include/nux/cpumask.h - CPU mask operations
• include/nux/cache.h - Generic cache with LRU eviction

Boot and Platform:

• include/nux/apxh.h - APXH boot protocol structures

Performance and Debugging:

• include/nux/nuxperf.h - Performance counters and measures
• include/nux/symbol.h - Symbol resolution utilities

Architecture Support:

• include/nux/nmiemul.h - NMI emulation layer

All files maintain 100% backward compatibility through legacy function wrappers and type aliases.

NUX is a framework to prototype kernels and related userspace programs that run on real, modern hardware. Currently supported architectures are x86_64, riscv64 and i386.

A kernel, with NUX, is nothing more than a C file with a main function and other functions that defines how the kernel behaves on certain events:

• main_ap called by a secondary processor when it is booted
• entry_ipi called when an inter-processor interrupt is received by the current CPU
• entry_alarm called when the platform timer expires
• entry_irq called when the platform issues an IRQ.
• entry_sysc to handle user space system calls.
• entry_ex to handle user space exceptions
• entry_pf to handle user space page faults

See the example kernel and exmaple userspace.

NUX also provides libnux, a runtime kernel support library to handle platform and memory, and libec a basic embedded C library based on the NetBSD libc.

On the userspace side, NUX provides libnux_user, that defines the syscall interface of the kernel, and libec, the same embedded C library used by the kernel side.

NUX kernels are booted by APXH (uppercase for αρχη, or beginning in ancient greek). APXH currently supports:

• EFI on i386, amd64 and riscv64
• multiboot on i386 and amd64
• SBI (riscv64).

You need to have and embedded ELF target compiler. If you're building for riscv, be sure to read instructions below.

If you have already your own embedded ELF compiler (such as amd64-unknown-elf-gcc or amd64-elf-gcc), you can skip the following.

gcc_toolchain_build is a super simple Makefile to automate building GCC for embedded targets.

If you want to build at once all the compilers and tools required to build all platforms supported by nux, do the following: (it'll take quite a while)

git clone https://github.com/glguida/gcc_toolchain_build
cd gcc_toolchain_build
make populate
make amd64-unknown-elf-gcc
make i686-unknown-elf-gcc
make riscv64-unknown-elf-gcc
export PATH=$PWD/install/bin
cd ..

Building NUX is as simple as using configure and make.

git clone https://github.com/glguida/nux
cd nux
git submodule update --init --recursive
mkdir build
cd build
../configure ARCH=i386
make -j

Now you can run the demo:

cd example
make qemu

Note if you are using your own compiler:

If you need to specify which compiler to use, pass the TOOLCHAIN and TOOLCHAIN32 parameters to configure.

E.g., suppose you have x86_64-elf-gcc and i686-elf-gcc (AMD64 requires both):

../nux/configure ARCH=amd64 TOOLCHAIN=amd64-elf TOOLCHAIN32=i686-elf

or

../nux/configure ARCH=i386 TOOLCHAIN=i686-elf

Note for RISCV64:

NUX will attempt to build APXH with EFI support on riscv64. This is done using gnu-efi. If you are not using the toolchain built with gcc_toolchain_build, this will fail.

If you still intend to use another toolchain, then you have to edit apxh/Makefile.in, removing 'efi' from the list of SUBDIRS.