A Freestanding Rust Binary

[utterances-bot]

This is a general purpose comment thread for the “A Freestanding Rust Binary” post.

[sunjay]

There is a broken link which isn't actually formatted as a link: [name mangling][mangling]

[tifandotme]

test

[phil-opp]

Thanks! Fixed in 8bd66bf.

[memoryruins]

Both the first and second editions of these series are invaluable. Thank you for every bit of clearly written information you’ve shared ✨

[phil-opp]

@memoryruins Thanks so much!

[CornedBee]

The Windows subsystem information link is outdated. The page behind it is pretty much unreadable and suggests to link to here instead:

https://docs.microsoft.com/en-us/cpp/build/reference/entry-entry-point-symbol

[phil-opp]

@CornedBee Thanks for the hint! Fixed in 6599a69.

[AleVul]

In the windows part of the post, the CONSOLE subsystem entry points are used as an example, then immediately the Windows subsystems entry points are referenced, i got a feeling that some explication is missing there.

[phil-opp]

@AleVul Thanks for reporting! We used to define the Windows subsystem entry points and then switched to console subsystem entry points. Seems like we missed some references. Fixed in 5f12cd8.

[sepiropht]

Is the final code sample is supposed to build wihtout errors ? Compilator ask me to import PanicInfo

[phil-opp]

@sepiropht Thanks for reporting. Seems like we forgot to add the imports in the latest update. I opened #440 to fix this.

[dodikk]

@phil-opp , thanks for a great series. Really well written and well explained (so much beginner-friendly).

What do you think about adding the platform annotations for the trampoline functions?

#[cfg(target_os = "windows")]
#[no_mangle]
pub extern "C" fn mainCRTStartup() -> ! {
    main();
}

[phil-opp]

@dodikk

thanks for a great series. Really well written and well explained (so much beginner-friendly).

Thanks a lot!

What do you think about adding the platform annotations for the trampoline functions?

These functions are just used to get a compiling no_std executable on existing operating systems in the first post. It wouldn't make sense to keep them for the subsequent posts because our OS kernel won't ever run on top of Windows or macOS. Only adding the conditional compilation for the first post would be possible, but I don't think that it's worth it because it makes things more complicated and the functions are removed in the second post anyway.

[AregevDev]

But you have two main() functions, one for Windows and one for MacOS.
It errors on it, am I missing something?

[phil-opp]

@AregevDev You should only use one of the three variants, depending on your host OS. So if you're on Windows, only add the Windows-style entry point and not the Linux and macOS entry points.

[andre-richter]

@AregevDev An alternative approach to having os-specific entrypoints would be the introduction of a custom linker script. There, you can define the entry-point function via ENTRY().

I think the first edition of the blog talked about it.

One way or the other, you have a little piece of inconvenience. When writing a kernel, though, in the long run you will probably end up with a custom linker script at some point anyways.

[ghost]

عالی

[letto4135]

There is a linking issue with mac, not sure if it is M1 specific, but
rustc --version --verbose
returns x86_64-apple-darwin as the host
rustup target add x86_64-apple-darwin && cargo build --target x86_64-apple-darwin
ends in
ld: entry point (_main) undefined. for architecture x86_64 clang: error: linker command failed with exit code 1 (use -v to see invocation)

[bjorn3]

See https://os.phil-opp.com/freestanding-rust-binary/#linker-errors, this is expected.

[snowmang1]

This blog is amazing, thank you so much for the concise walk through and explanations!

[phil-opp]

Thanks!

[Cerber-Ursi]

@phil-opp, is it intentional that under the original English post there's not this thread, but the thread for Russian translation instead?..

[phil-opp]

That's not intentional, thanks for reporting this! Let me try to fix it...

[phil-opp]

Should be fixed now.

[Cerber-Ursi]

Thanks. Btw, in that discussion I've added a question (before noticing the thread was wrong), did you see it?

[UncleScientist]

I'm streaming my walkthrough of this blog series; would it be appropriate for me to share a link?

[XieGuochao]

Would it be interesting to create a version that can run on Mac M1's qemu-system-aarch64 ?

[bjorn3]

While the most of the basic concepts are similar between x86_64 and aarch64, the actual implementation is significantly different between the two to the point that blog os would likely have to be rewritten entirely from scratch. Additionally while x86_64 is mostly standardized, the same is not the case for aarch64. There are significant differences between aarch64 processors. Even something as basic as the interrupt controller differs between processors. While most aarch64 processors nowadays use GIC (generic interrupt controller), apple uses their own AIC (generic interrupt controller), except in VM's where they have a partial GIC implementation in hardware and emulate the rest in the vm software. And even for GIC there are several versions: https://developer.arm.com/Architectures/Generic%20Interrupt%20Controller And that is not even talking about the boot process for which there is pretty much no standardization outside of the systems that use UEFI (mostly server aarch64 processors, but U-Boot also supports emulating a UEFI subset).

[andre-richter]

Shameless plug: For AArch64, you can take a look at https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials

[XieGuochao]

Thank you for the explanation and interesting resources! What about other architectures like RISC-V?

[bjorn3]

RISC-V has less fragmentation with respect to booting. Basically everything with support for user mode uses either SBI or UEFI afaik. There are also microcontrollers which only support machine mode (equivalent to SMM on x86) and no supervisor mode or user mode.

https://osblog.stephenmarz.com/ seems to be a good tutorial for writing a RISC-V OS in Rust.

[ochudi]

Thank you!

Just followed the first post to the end. You were recommended by my lecturer. Learning OS Dev.

[ghost]

I am getting an error is vscode

found duplicate lang item `panic_impl`
the lang item is first defined in crate `std` (which `test` depends on)
first definition in `std` loaded from /home/chakra/.rustup/toolchains/1.70-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libstd-8389830094602f5a.rlib

Any idea how to solve this ?

[testingapisname]

Just did the below and get a different error now :D

PS C:\RustOS\blog_os> rustup override set nightly
info: using existing install for 'nightly-x86_64-pc-windows-msvc'
info: override toolchain for 'C:\RustOS\blog_os' set to 'nightly-x86_64-pc-windows-msvc'

  nightly-x86_64-pc-windows-msvc unchanged - rustc 1.76.0-nightly (503e12932 2023-12-07)

PS C:\RustOS\blog_os> cargo build    
warning: unused manifest key: build
warning: unused manifest key: target.cfg(target_os = "none").runner
warning: unused manifest key: toolchain
warning: unused manifest key: unstable
   Compiling blog_os v0.1.0 (C:\RustOS\blog_os)
error: linking with `link.exe` failed: exit code: 1561
  |
  = note: "C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\VC\\Tools\\MSVC\\14.38.33130\\bin\\HostX64\\x64\\link.exe" "/NOLOGO" "C:\\Users\\user01\\AppData\\Local\\Temp\\rustcMHK8pp\\symbols.o" "C:\\RustOS\\blog_os\\target\\debug\\deps\\blog_os.roew4aiqx0ug0ap.rcgu.o" "/LIBPATH:C:\\RustOS\\blog_os\\target\\debug\\deps" "/LIBPATH:C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib" "C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib\\librustc_std_workspace_core-747897f502f49f1a.rlib" "C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib\\libcore-0a7d9524c210bd3d.rlib" "C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib\\libcompiler_builtins-54ca2f8628761f08.rlib" "/NXCOMPAT" "/LIBPATH:C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib" "/OUT:C:\\RustOS\\blog_os\\target\\debug\\deps\\blog_os.exe" "/OPT:REF,NOICF" "/DEBUG" "/NATVIS:C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\etc\\intrinsic.natvis" "/NATVIS:C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\etc\\liballoc.natvis" "/NATVIS:C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\etc\\libcore.natvis" "/NATVIS:C:\\Users\\user01\\.rustup\\toolchains\\nightly-x86_64-pc-windows-msvc\\lib\\rustlib\\etc\\libstd.natvis"
  = note: LINK : fatal error LNK1561: entry point must be defined


error: could not compile `blog_os` (bin "blog_os") due to 1 previous error
PS C:\RustOS\blog_os> 

[testingapisname]

Tried the build as below and getting this error:

PS C:\RustOS\blog_os> cargo build --target thumbv7em-none-eabihf
warning: unused manifest key: build
warning: unused manifest key: target.cfg(target_os = "none").runner
warning: unused manifest key: toolchain
warning: unused manifest key: unstable
   Compiling blog_os v0.1.0 (C:\RustOS\blog_os)
error[E0463]: can't find crate for `core`
  |
  = note: the `thumbv7em-none-eabihf` target may not be installed
  = help: consider downloading the target with `rustup target add thumbv7em-none-eabihf`
  = help: consider building the standard library from source with `cargo build -Zbuild-std`

error[E0463]: can't find crate for `compiler_builtins`

error[E0463]: can't find crate for `core`
 --> src\main.rs:6:5
  |
6 | use core::panic::PanicInfo;
  |     ^^^^ can't find crate
  |
  = note: the `thumbv7em-none-eabihf` target may not be installed
  = help: consider downloading the target with `rustup target add thumbv7em-none-eabihf`
  = help: consider building the standard library from source with `cargo build -Zbuild-std`

error: requires `sized` lang_item

For more information about this error, try `rustc --explain E0463`.
error: could not compile `blog_os` (bin "blog_os") due to 4 previous errors
PS C:\RustOS\blog_os> 
PS C:\RustOS\blog_os> rustup install core   
error: invalid toolchain name: 'core'
PS C:\RustOS\blog_os>

[testingapisname]

Success!

PS C:\RustOS\blog_os> cargo build --target thumbv7em-none-eabihf
warning: unused manifest key: build
warning: unused manifest key: target.cfg(target_os = "none").runner
warning: unused manifest key: toolchain
warning: unused manifest key: unstable
   Compiling blog_os v0.1.0 (C:\RustOS\blog_os)
    Finished dev [unoptimized + debuginfo] target(s) in 0.12s
PS C:\RustOS\blog_os>

[testingapisname]

Needed to read the error and do the step with help:

PS C:\RustOS\blog_os> rustup target add thumbv7em-none-eabihf

[ghost]

Nice

[cleanwk]

excellent article, thanks to the author🤩

[phil-opp]

Thanks :)

[pooriatgh]

Incase you ran into issue like below:

ound duplicate lang item panic_impl
he lang item is first defined in crate std (which test depends on)

try this from : rust-lang/rust-analyzer#4490 (comment)

works like a charm!

#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
loop {}
}

what I understood is the test crate also depends on some standard library so better to disable it.

[harshithnrao]

thank you !!

[HarshMohanSason]

Excellent. This will boost up my rust skills as well along with OS knowledge. Thanks

[Blindspot22]

Wow! Have had an idea of creating an OS with rust before and have had really tough times. Little did i know this post existed. Thanks to all who made this possible

[ApplePieCodes]

Great Guide!!! Would you consider making an update showing how to interact with the screen aside from plain text(as in writing individual pixels and clearing the screen for a full display system)?

[phil-opp]

Yes, this is planned. I'm not sure when it will be ready yet though.

[jwmurray]

Has anyone installed this onto a Pi Pico or MircoBits or other arm device? I would like to give it a try and wonder which ones were successful.

[bjorn3]

This is a tutorial for writing an OS for x86_64. While the high level things you need to implement for an arm OS are the same, all the low level details are different enough that this tutorial will likely not be of much help apart from introducing the basic concepts.

[hgfernan]

I shall read your text with lots of interest. But there's a question that I'm keeps disturbing my reading: any OS that I know about has parts in assembly language to cope with very specific hardware questions that higher level languages can't cope with.

How will you integrate that with the protected environment that Rust intends to create ?

[AtomicGamer9523]

Rust has an asm! macro, if that's what you are asking. And bootloader has some assembly as part of it, if that is what you are asking