blog_os Documentation

Technical Documentation: phil-opp/blog_os

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Blog OS

This repository contains the source code for the Writing an OS in Rust series at os.phil-opp.com.

If you have questions, open an issue or chat with us on Gitter.

Where is the code? Copy Chapter

The code for each post lives in a separate git branch. This makes it possible to see the intermediate state after each post.

The code for the latest post is available here.

You can find the branch for each post by following the (source code) link in the post list below. The branches are named post-XX where XX is the post number, for example post-03 for the VGA Text Mode post or post-07 for the Hardware Interrupts post. For build instructions, see the Readme of the respective branch.

You can check out a branch in a subdirectory using git worktree:

git worktree add code post-10

The above command creates a subdirectory named code that contains the code for the 10th post ("Heap Allocation").

Posts Copy Chapter

The goal of this project is to provide step-by-step tutorials in individual blog posts. We currently have the following set of posts:

Bare Bones:

• A Freestanding Rust Binary
  (source code)
• A Minimal Rust Kernel
  (source code)
• VGA Text Mode
  (source code)
• Testing
  (source code)

Interrupts:

• CPU Exceptions
  (source code)
• Double Faults
  (source code)
• Hardware Interrupts
  (source code)

Memory Management:

• Introduction to Paging
  (source code)
• Paging Implementation
  (source code)
• Heap Allocation
  (source code)
• Allocator Designs
  (source code)

Multitasking:

• Async/Await
  (source code)

First Edition Posts Copy Chapter

The current version of the blog is already the second edition. The first edition is outdated and no longer maintained, but might still be useful. The posts of the first edition are:

Click to expand

Bare Bones:

• A Minimal x86 Kernel
  (source code)
• Entering Long Mode
  (source code)
• Set Up Rust
  (source code)
• Printing to Screen
  (source code)

Memory Management:

• Allocating Frames
  (source code)
• Page Tables
  (source code)
• Remap the Kernel
  (source code)
• Kernel Heap
  (source code)

Exceptions:

• Handling Exceptions
  (source code)
• Double Faults
  (source code)

Additional Resources:

• Cross Compile Binutils
• Cross Compile libcore
• Set Up GDB
• Handling Exceptions using Naked Functions
  • Catching Exceptions
    (source code)
  • Better Exception Messages
    (source code)
  • Returning from Exceptions
    (source code)

License Copy Chapter

This project, with exception of the blog/content folder, is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or
  https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

For licensing of the blog/content folder, see the blog/content/README.md.

Contribution Copy Section

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Overview (`docker/README.md`) Copy Section

Building Blog OS using Docker

Inspired by redox.
You just need git, make, and docker.
It is better to use a non-privileged user to run the docker command, which is usually achieved by adding the user to the docker group.

Run the container to build Blog OS Copy Chapter

You can build the docker image using make docker_build and run it using make docker_run.

Run the container interactively Copy Chapter

You can use the make target docker_interactive to get a shell in the container.

Clear the toolchain caches (Cargo & Rustup) Copy Chapter

To clean the docker volumes used by the toolchain, you just need to run make docker_clean.

License Copy Chapter

The source code is dual-licensed under MIT or the Apache License (Version 2.0). This excludes the blog directory.

Overview (`blog/content/README.md`) Copy Section

Blog Content

This folder contains the content for the "Writing an OS in Rust" blog.

License Copy Chapter

This folder is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License, available in LICENSE-CC-BY-NC or under https://creativecommons.org/licenses/by-nc/4.0/.

All code examples between markdown code blocks denoted by three backticks (\```) are additionally licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or
  https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution Copy Section

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.

--- METRICS ---

• Files Extracted: 3
• Estimated Token Budget: ~2051 tokens
• Canonical Reference: https://codewiki.google/github.com/phil-opp/blog_os