feat: drop userland dependency from kernel (#742)

* feat: userland is bin crate; awkernel is lib crate

* feat(x86): compile mpboot with kernel/build.rs

* Add template external userland as example

* feat(aarch64): add assembly via global_asm!

* feat(userland_extern): add support for Aarch64

Author: romancardenas

.cargo/config.toml

@@ -1,9 +1,9 @@
 [alias]
-x86 = "build --package awkernel --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-aarch64 = "build --package awkernel --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-rv32 = "build --package awkernel --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-rv64 = "build --package awkernel --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-std = "build --package awkernel --no-default-features --features std"
+x86 = "build --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+aarch64 = "build --package userland --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+rv32 = "build --package userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+rv64 = "build --package userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+std = "build --package userland --no-default-features --features std"
 
 test_awkernel_lib = "test --package awkernel_lib --no-default-features --features std"
 test_awkernel_async_lib = "test --package awkernel_async_lib --no-default-features --features std"
@@ -12,25 +12,25 @@ test_smoltcp = "test --package smoltcp --no-default-features --features std --fe
 test_affinity_btree_queue = "test --package affinity_btree_queue"
 test_rd_gen_to_dags = "test --package rd_gen_to_dags --no-default-features --features std --features milliseconds"
 
-clippy_x86 = "clippy --package awkernel --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_raspi = "clippy --package awkernel --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_raspi5 = "clippy --package awkernel --no-default-features --features raspi5 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_aarch64_virt = "clippy --package awkernel --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_std = "clippy --package awkernel --no-default-features --features std"
-clippy_rv32 = "clippy --package awkernel --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-clippy_rv64 = "clippy --package awkernel --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_x86 = "clippy --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_raspi = "clippy --package userland --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_raspi5 = "clippy --package userland --no-default-features --features raspi5 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_aarch64_virt = "clippy --package userland --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_std = "clippy --package userland --no-default-features --features std"
+clippy_rv32 = "clippy --package userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+clippy_rv64 = "clippy --package userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
 clippy_rd_gen_to_dags = "clippy --package rd_gen_to_dags --no-default-features  --features std --features milliseconds"
 
-check_aarch64 = "check --package awkernel --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_x86 = "check --package awkernel --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_rv32 = "check --package awkernel --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_rv64 = "check --package awkernel --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-check_no_std = "check --package awkernel -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem --quiet --message-format=json -Zjson-target-spec"
-check_std = "check --package awkernel --no-default-features --features std"
+check_aarch64 = "check --package userland --no-default-features --features aarch64 --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_x86 = "check --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_rv32 = "check --package userland --no-default-features --features rv32 --target riscv32imac-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_rv64 = "check --package userland --no-default-features --features rv64 --target riscv64gc-unknown-none-elf -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+check_no_std = "check --package userland -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem --quiet --message-format=json -Zjson-target-spec"
+check_std = "check --package userland --no-default-features --features std"
 
-doc_raspi = "doc --package awkernel --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-doc_aarch64_virt = "doc --package awkernel --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
-doc_x86 = "doc --package awkernel --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+doc_raspi = "doc --package userland --no-default-features --features raspi --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+doc_aarch64_virt = "doc --package userland --no-default-features --features aarch64_virt --target targets/aarch64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
+doc_x86 = "doc --package userland --no-default-features --features x86 --target targets/x86_64-kernel.json -Zbuild-std=core,alloc,compiler_builtins -Zbuild-std-features=compiler-builtins-mem -Zjson-target-spec"
 
 udeps_x86 = "udeps --package awkernel --no-default-features --features x86 --target x86_64-unknown-linux-gnu"
 udeps_raspi = "udeps --package awkernel --no-default-features --features x86 --target x86_64-unknown-linux-gnu"

.vscode/settings.json

@@ -2,18 +2,22 @@
     "rust-analyzer.showUnlinkedFileNotification": false,
     "tlaplus.tlc.modelChecker.options": "-workers auto",
     "editor.formatOnSave": true,
+    // The cargo aliases build `--package userland`, which has no default
+    // architecture: pass it explicitly (the features are forwarded to `awkernel`).
     // For AArch64 Virt
     // "rust-analyzer.cargo.buildScripts.overrideCommand": [
     //     "cargo",
     //     "+nightly-2026-07-20",
     //     "check_no_std",
     //     "--target=targets/aarch64-kernel.json",
+    //     "--features=aarch64_virt",
     // ],
     // "rust-analyzer.check.overrideCommand": [
     //     "cargo",
     //     "+nightly-2026-07-20",
     //     "check_no_std",
     //     "--target=targets/aarch64-kernel.json",
+    //     "--features=aarch64_virt",
     // ],
     // "rust-analyzer.cargo.features": [
     //     "aarch64_virt"
@@ -24,12 +28,14 @@
         "+nightly-2026-07-20",
         "check_no_std",
         "--target=targets/x86_64-kernel.json",
+        "--features=x86",
     ],
     "rust-analyzer.check.overrideCommand": [
         "cargo",
         "+nightly-2026-07-20",
         "check_no_std",
         "--target=targets/x86_64-kernel.json",
+        "--features=x86",
     ],
     "rust-analyzer.cargo.features": [
         "x86"
@@ -39,17 +45,19 @@
     //     "cargo",
     //     "+nightly-2026-07-20",
     //     "check_std",
+    //     "--features=std",
     //     "--quiet",
     //     "--message-format=json"
     // ],
     // "rust-analyzer.check.overrideCommand": [
     //     "cargo",
     //     "+nightly-2026-07-20",
     //     "check_std",
+    //     "--features=std",
     //     "--quiet",
     //     "--message-format=json"
     // ],
     // "rust-analyzer.cargo.features": [
     //     "std"
     // ],
-}
+}

Cargo.toml

@@ -19,6 +19,7 @@ members = [
     "applications/tests/*",
     "smoltcp",
     "awkernel_futures_macro",
+    "awkernel_macros",
 ]
 
 resolver = "2"

Makefile

@@ -6,39 +6,22 @@ else
 	OPT = --features debug
 endif
 
-# 2MiB Stack
-STACKSIZE = 1024 * 1024 * 2
-
 ifeq ($(BSP),raspi3)
 	RUSTC_MISC_ARGS = -C target-cpu=cortex-a53
-	INITADDR = 0x80000
 	AARCH64_OPT = $(OPT) --features raspi
 else ifeq ($(BSP),raspi4)
 	RUSTC_MISC_ARGS = -C target-cpu=cortex-a72
-	INITADDR = 0x80000
 	AARCH64_OPT = $(OPT) --features raspi
 else ifeq ($(BSP),raspi5)
 	RUSTC_MISC_ARGS = -C target-cpu=cortex-a76
-	INITADDR = 0x80000
 	AARCH64_OPT = $(OPT) --features raspi5
 else ifeq ($(BSP),aarch64_virt)
 	RUSTC_MISC_ARGS = -C target-cpu=cortex-a72
-	INITADDR = 0x40080000
 	AARCH64_OPT = $(OPT) --features aarch64_virt
 endif
 
 RUSTC_MISC_ARGS += -C panic=unwind
 
-ASM_FILE_DEP_AARCH64=kernel/asm/aarch64/exception.S
-ASM_FILE_AARCH64=kernel/asm/aarch64/boot.S
-ASM_OBJ_AARCH64=boot_aarch64.o
-
-X86ASM=kernel/asm/x86
-
-ifndef $(CC)
-	CC = clang
-endif
-
 ifndef $(LD)
 	LD = rust-lld -flavor gnu
 	# LD = ld.gold
@@ -49,8 +32,6 @@ QEMUPORT=5556
 
 # Link scripts
 LINKERDIR=kernel/ld
-AARCH64_LD=$(LINKERDIR)/aarch64-link.lds
-AARCH64_BSP_LD=$(LINKERDIR)/aarch64-link-bsp.lds
 X86_64_LD=$(LINKERDIR)/x86_64-link.lds
 RV32_LD=$(LINKERDIR)/rv32-link.lds
 RV64_LD=$(LINKERDIR)/rv64-link.lds
@@ -61,7 +42,7 @@ all: aarch64 x86_64 riscv32 riscv64 std
 
 check: check_aarch64 check_x86_64 check_std check_riscv32 check_riscv64
 
-clippy: $(X86ASM)
+clippy:
 	cargo +$(RUSTV) clippy_x86
 	cargo +$(RUSTV) clippy_raspi
 	cargo +$(RUSTV) clippy_raspi5
@@ -71,7 +52,7 @@ clippy: $(X86ASM)
 	cargo +$(RUSTV) clippy_std
 	cargo +$(RUSTV) clippy_rd_gen_to_dags
 
-udeps: $(X86ASM)
+udeps:
 	cargo +$(RUSTV) udeps_x86
 
 cargo: target/aarch64-kernel/$(BUILD)/awkernel kernel-x86_64.elf std
@@ -84,19 +65,13 @@ aarch64: kernel8.img
 check_aarch64: FORCE
 	cargo +$(RUSTV) check_aarch64 $(AARCH64_OPT)
 
-target/aarch64-kernel/$(BUILD)/awkernel: $(ASM_OBJ_AARCH64) $(AARCH64_BSP_LD) FORCE
+target/aarch64-kernel/$(BUILD)/awkernel: FORCE
 	RUSTFLAGS="$(RUSTC_MISC_ARGS)" cargo +$(RUSTV) aarch64 $(AARCH64_OPT)
 	python3 scripts/embed_debug_info.py $@
 
 kernel8.img: target/aarch64-kernel/$(BUILD)/awkernel
 	rust-objcopy -O binary target/aarch64-kernel/$(BUILD)/awkernel $@
 
-$(ASM_OBJ_AARCH64): $(ASM_FILE_AARCH64) $(ASM_FILE_DEP_AARCH64)
-	$(CC) --target=aarch64-elf -c $< -o $@ -DSTACKSIZE="$(STACKSIZE)"
-
-$(AARCH64_BSP_LD): $(AARCH64_LD)
-	sed "s/#INITADDR#/$(INITADDR)/" $(AARCH64_LD) > $@
-
 QEMU_AARCH64_ARGS= -kernel kernel8.img
 QEMU_AARCH64_ARGS+= -serial stdio
 QEMU_AARCH64_ARGS+= -monitor telnet::$(QEMUPORT),server,nowait # -d int
@@ -139,10 +114,10 @@ gdb-aarch64-virt:
 
 x86_64: x86_64_uefi.img
 
-check_x86_64: $(X86ASM)
+check_x86_64:
 	cargo +$(RUSTV) check_x86
 
-kernel-x86_64.elf: $(X86ASM) FORCE
+kernel-x86_64.elf: FORCE
 	RUSTFLAGS="$(RUSTC_MISC_ARGS)" cargo +$(RUSTV) x86 $(OPT)
 	python3 scripts/embed_debug_info.py $@
 
@@ -152,9 +127,6 @@ x86_64_boot.img: kernel-x86_64.elf
 x86_64_uefi.img: kernel-x86_64.elf
 	RUSTFLAGS="$(RUSTC_MISC_ARGS)" cargo +$(RUSTV) run --release --package x86bootdisk --no-default-features --features uefi -- --kernel $< --output $@ --pxe x86_64_uefi_pxe_boot --boot-type uefi
 
-$(X86ASM): FORCE
-	$(MAKE) -C $@
-
 OVMF_PATH := $(shell cat ${HOME}/.ovmfpath)
 
 QEMU_X86_ARGS= -drive if=pflash,format=raw,readonly=on,file=${OVMF_PATH}/code.fd
@@ -247,7 +219,7 @@ check_std: FORCE
 	cargo +$(RUSTV) check_std
 
 run-std:
-	cargo +$(RUSTV) run --package awkernel --no-default-features --features std $(OPT)
+	cargo +$(RUSTV) run --package userland --no-default-features --features std $(OPT)
 
 # Docs
 docs: FORCE
@@ -271,9 +243,8 @@ fmt: FORCE
 # Clean
 
 clean: FORCE
-	rm -rf *.o *.elf $(AARCH64_BSP_LD) *.img kernel/asm/x86/*.o x86_64_uefi_pxe_boot
+	rm -rf *.o *.elf *.img x86_64_uefi_pxe_boot
 	cargo clean
-	$(MAKE) -C $(X86ASM) clean
 
 
 ## QEMU Monitor

README.md

@@ -41,6 +41,8 @@ $ cargo binstall mdbook-mermaid
   - verified library for awkernel_async_lib
   - pure Rust (no dependencies on external functions and no inline assembly)
 - [awkernel_futures_macro](./awkernel_futures_macro/)
+- [awkernel_macros](./awkernel_macros/)
+  - `#[awkernel::main]` entry-point macro
 - [awkernel_drivers](./awkernel_drivers/)
 - [awkernel_aarch64](./awkernel_aarch64/)
 - [userland](./userland/)
@@ -60,7 +62,8 @@ graph TD;
     kernel-->awkernel_aarch64;
     kernel-->awkernel_drivers;
     awkernel_drivers-->awkernel_lib;
-    kernel-->userland;
+    userland-->kernel;
+    kernel-->awkernel_macros;
 ```
 
 Applications can use `awkernel_async_lib`, `awkernel_lib`, and `awkernel_drivers`.
@@ -95,7 +98,6 @@ etc
 ### x86_64
 
 ```text
-$ make kernel/asm/x86
 $ cargo doc_x86
 $ ls target/x86_64-kernel/doc/awkernel/index.html
 $ ls target/aarch64-kernel/doc/awkernel_lib/index.html
@@ -120,28 +122,29 @@ Debug build.
 $ make x86_64
 ```
 
-#### Developing for x86_64 on macOS
+#### Building x86_64 on Apple Silicon (or another non-x86_64 host)
 
-`kernel/asm/x86/mpboot.S` mixes 16/32/64-bit code and needs a real GNU assembler and linker.
-By default, Apple systems provide an alias so `gcc` points to `clang`.
-Also, modern Apple Silicon processors are aarch64.
-Therefore, we must install a GNU x86_64 ELF cross toolchain:
+The x86_64 build includes `kernel/asm/x86/mpboot.S`, an assembly file that mixes 16-, 32-, and 64-bit code. The build script assembles and links it with GNU tools, then uses `objcopy` to create a binary image. A Rust target alone does not provide these tools.
+
+On Apple Silicon, install an x86_64 ELF GNU toolchain:
 
 ```text
 $ brew install x86_64-elf-gcc x86_64-elf-binutils
 ```
 
-Then, when building your application, point to this specific cross toolchain:
+The build script automatically uses the `x86_64-elf-` tool prefix if `x86_64-elf-gcc` is available. Otherwise, it tries the host tools (`gcc`, `ld`, and `objcopy`), which may not support this build on a non-x86_64 host.
+
+To select a toolchain with a different prefix, pass that prefix as `CROSS_COMPILE`. For example, if its tools are named `my-x86_64-elf-gcc`, `my-x86_64-elf-ld`, and `my-x86_64-elf-objcopy`, run:
 
 ```text
-$ make x86_64 RELEASE=1 CROSS_COMPILE=x86_64-elf-
+$ make x86_64 RELEASE=1 CROSS_COMPILE=my-x86_64-elf-
 ```
 
 > [!IMPORTANT]
 >
-> Do not remove the trailing `-`
-
-This way, Awkernel will use the `x86_64-elf-gcc` compiler and the `x86_64-elf-ld` linker.
+> `CROSS_COMPILE` is a prefix, not a path to the compiler. Keep the trailing `-` so the build can append `gcc`, `ld`, and `objcopy` to it.
+>
+> For example, `CROSS_COMPILE=x86_64-elf-` selects `x86_64-elf-gcc`, `x86_64-elf-ld`, and `x86_64-elf-objcopy`.
 
 ### Boot
 

awkernel_macros/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "awkernel_macros"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro2 = "1.0.60"
+quote = "1.0"
+syn = { version = "2.0.52", features = ["full"] }