oro+examples: add initial noop example, along with build infra

.cargo/config.toml

@@ -22,3 +22,5 @@ oro-test = "test -p oro-boot -p oro-boot-protocol -p oro-mem -p oro-debug -p oro
 oro-ra-x86_64 = "check --quiet --message-format=json --keep-going --target ./oro-arch-x86_64/x86_64-unknown-oro.json --bin oro-kernel-x86_64 --bin oro-limine-x86_64 -Zunstable-options -Zbuild-std=core,compiler_builtins,alloc -Zbuild-std-features=compiler-builtins-mem"
 
 oro-ra-aarch64 = "check --quiet --message-format=json --keep-going --target ./oro-arch-aarch64/aarch64-unknown-oro.json --bin oro-kernel-aarch64 --bin oro-limine-aarch64 -Zunstable-options -Zbuild-std=core,compiler_builtins,alloc -Zbuild-std-features=compiler-builtins-mem"
+
+oro-examples = "build --target=x86_64-unknown-none --target=aarch64-unknown-none -p exmod-noop"

.github/workflows/push.yml

@@ -127,3 +127,15 @@ jobs:
           ORO_BUILD_PROTOCOL_HEADER: 1
       - name: Check
         run: bash ./oro-boot-protocol/test-boot-header.sh
+  examples:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        profile: ["dev", "release"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'true'
+      - uses: ./.github/actions/rust
+      - name: Build
+        run: cargo oro-examples --profile ${{ matrix.profile }}

Cargo.toml

@@ -30,6 +30,9 @@ members = [
 	"oro-sync",
 	"oro-sysabi",
 	"oro",
+
+	# Examples
+	"examples/noop",
 ]
 
 [workspace.dependencies]

examples/noop/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "exmod-noop"
+description = "Example module that spins endlessly"
+version = "0.0.0"
+publish = false
+edition = "2021"
+
+build = "build.rs"
+
+[dependencies.oro]
+path = "../../oro"
+features = ["runtime"]
+
+[build-dependencies.oro]
+path = "../../oro"
+features = ["build"]
+default-features = false

examples/noop/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+	::oro::build();
+}

examples/noop/src/main.rs

@@ -0,0 +1,12 @@
+#![no_std]
+#![no_main]
+
+#[allow(unused_imports)]
+use oro;
+
+#[no_mangle]
+fn main() {
+	loop {
+		::core::hint::spin_loop();
+	}
+}

oro/Cargo.toml

@@ -17,5 +17,13 @@ doctest = false
 [lints]
 workspace = true
 
-# NOTE(qix-): This crate MUST NOT have any workspace dependencies
+[features]
+default = ["panic_handler"]
+runtime = []
+build = []
+panic_handler = []
+
+# NOTE(qix-): This crate MUST NOT have any workspace (only) dependencies
 # NOTE(qix-): as it is published publicly.
+[dependencies]
+oro-sysabi = { version = "0.0.0", path = "../oro-sysabi" }

oro/aarch64.ld

@@ -0,0 +1,42 @@
+OUTPUT_FORMAT(elf64-aarch64)
+OUTPUT_ARCH(aarch64)
+
+ENTRY(_oro_start)
+
+PHDRS {
+	text     PT_LOAD    FLAGS((1 << 0) | (1 << 2)); /* rx */
+	rodata   PT_LOAD    FLAGS((1 << 2)           ); /* r  */
+	data     PT_LOAD    FLAGS((1 << 1) | (1 << 2)); /* rw */
+}
+
+SECTIONS {
+	. = 0x3000000000;
+
+	.text : {
+		*(.text .text.*)
+	} :text
+
+	. = ALIGN(4096);
+
+	.rodata : {
+		*(.rodata .rodata.*)
+	} :rodata
+
+	. = ALIGN(4096);
+
+	.data : {
+		*(.data .data.*)
+	} :data
+
+	. = ALIGN(4096);
+
+	.bss : {
+		*(COMMON)
+		*(.bss .bss.*) /* MUST be last allocated to :data */
+	} :data
+
+	/DISCARD/ : {
+		*(.eh_frame)
+		*(.note .note.*)
+	}
+}

oro/src/build.rs

@@ -0,0 +1,56 @@
+//! Houses the build configurator for Oro modules.
+//!
+//! # Usage
+//! In the module crate's `build.rs` script, call the `build` function to configure the linker to
+//! generate a valid Oro module that can be loaded by the Oro kernel.
+//!
+//! ```no_run
+//! fn main() {
+//! 	::oro::build();
+//! }
+//! ```
+
+use std::path::PathBuf;
+
+/// To be called by the module crate's `build.rs` script.
+///
+/// This function configures the linker to generate a valid
+/// Oro module that can be loaded by the Oro kernel.
+pub fn build() {
+	let target = std::env::var("TARGET").unwrap();
+
+	match target.as_str() {
+		"aarch64-unknown-none" => {
+			let linker_script = PathBuf::from(file!())
+				.parent()
+				.unwrap()
+				.parent()
+				.unwrap()
+				.join("aarch64.ld");
+
+			println!("cargo:rustc-link-arg=-static");
+			println!("cargo:rustc-link-arg=--relax");
+			println!("cargo:rustc-link-arg=-T");
+			println!("cargo:rustc-link-arg={}", linker_script.display());
+		}
+		"x86_64-unknown-none" => {
+			let linker_script = PathBuf::from(file!())
+				.parent()
+				.unwrap()
+				.parent()
+				.unwrap()
+				.join("x86_64.ld");
+
+			println!("cargo:rustc-link-arg=-static");
+			println!("cargo:rustc-link-arg=--relax");
+			println!("cargo:rustc-link-arg=-T");
+			println!("cargo:rustc-link-arg={}", linker_script.display());
+		}
+		_ => {
+			panic!(
+				"unsupported target when building Oro module: {target}; run with \
+				 `--target=<arch>-unknown-none` instead"
+			);
+		}
+	}
+}

oro/src/lib.rs

@@ -1,2 +1,44 @@
 //! # Oro Module High Level API and Build Tooling
-#![no_std]
+//!
+//! # Usage
+//! Declare the `oro` crate as a dependency in your `Cargo.toml` file.
+//! You must also specify that you want Cargo to use a `build.rs` script.
+//!
+//! ```toml
+//! [package]
+//! build = "build.rs"
+//!
+//! [dependencies]
+//! oro = { version = "<version>", features = ["runtime"] }
+//!
+//! [build-dependencies]
+//! oro = { version = "<version>", features = ["build"] }
+//! ```
+//!
+//! The `oro` crate *must* be `use`d by the module, even if no APIs are
+//! called, in order to properly link the panic handler, etc.
+//!
+//! ```no_run
+//! #[allow(unused_imports)]
+//! use oro;
+//! ```
+//!
+//! Finally, in your `build.rs`, call the `build` function to configure the linker to
+//! generate a valid Oro module that can be loaded by the Oro kernel.
+//!
+//! ```no_run
+//! fn main() {
+//! 	::oro::build();
+//! }
+//! ```
+#![cfg_attr(not(feature = "build"), no_std)]
+
+#[cfg(feature = "build")]
+mod build;
+#[cfg(feature = "build")]
+pub use build::*;
+
+#[cfg(not(feature = "build"))]
+mod runtime;
+#[cfg(not(feature = "build"))]
+pub use runtime::*;

oro/src/runtime.rs

@@ -0,0 +1,28 @@
+//! High-level runtime support for Oro modules.
+
+#[cfg(feature = "panic_handler")]
+#[panic_handler]
+#[doc(hidden)]
+fn panic(_info: &core::panic::PanicInfo) -> ! {
+	// TODO(qix-): Implement panic handler
+	loop {
+		core::hint::spin_loop();
+	}
+}
+
+extern "C" {
+	fn main();
+}
+
+#[doc(hidden)]
+#[no_mangle]
+pub extern "C" fn _oro_start() -> ! {
+	unsafe {
+		main();
+	}
+
+	// TODO(qix-): Implement exit routine
+	loop {
+		core::hint::spin_loop();
+	}
+}

oro/x86_64.ld

@@ -0,0 +1,42 @@
+OUTPUT_FORMAT(elf64-x86-64)
+OUTPUT_ARCH(i386:x86-64)
+
+ENTRY(_oro_start)
+
+PHDRS {
+	text     PT_LOAD    FLAGS((1 << 0) | (1 << 2)); /* rx */
+	rodata   PT_LOAD    FLAGS((1 << 2)           ); /* r  */
+	data     PT_LOAD    FLAGS((1 << 1) | (1 << 2)); /* rw */
+}
+
+SECTIONS {
+	. = 0x3000000000;
+
+	.text : {
+		*(.text .text.*)
+	} :text
+
+	. = ALIGN(4096);
+
+	.rodata : {
+		*(.rodata .rodata.*)
+	} :rodata
+
+	. = ALIGN(4096);
+
+	.data : {
+		*(.data .data.*)
+	} :data
+
+	. = ALIGN(4096);
+
+	.bss : {
+		*(COMMON)
+		*(.bss .bss.*) /* MUST be last allocated to :data */
+	} :data
+
+	/DISCARD/ : {
+		*(.eh_frame)
+		*(.note .note.*)
+	}
+}