#x86-interrupts #teaching-os

nightly no-std bin+lib pluggable_interrupt_os

Enables user to create a simple x86 OS by supplying interrupt handlers

3 unstable releases

0.2.0 Jan 24, 2021
0.1.1 Jan 7, 2021
0.1.0 Jan 7, 2021

#346 in Hardware support

40 downloads per month

MIT license

37KB
512 lines

Overview

This crate enables the user to create a simple operating system by supplying interrupt handlers for the timer and the keyboard. As time and energy permits, I may add other interrupt handlers that seem useful.

I developed this crate to support assignments in my operating systems course at Hendrix College. It provides a nice introduction to bare-metal programming. It has not been "battle-tested" in a production domain.

The code is heavily derivative of the examples from the outstanding resource Writing an Operating System in Rust. I would like to gratefully acknowledge Philipp Oppermann's efforts to create this resource. Comments in each source file specify which code elements I have adopted from him.

Before attempting to use this crate:

Having read and understood the ideas from the above tutorials, you can use this crate to create your own Pluggable Interrupt Operating System (PIOS).

Here is a very basic example (found in main.rs in this crate):

#![no_std]
#![no_main]

use pc_keyboard::DecodedKey;
use pluggable_interrupt_os::HandlerTable;

fn tick() {
    print!(".");
}

fn key(key: DecodedKey) {
    match key {
        DecodedKey::Unicode(character) => print!("{}", character),
        DecodedKey::RawKey(key) => print!("{:?}", key),
    }
}

#[no_mangle]
pub extern "C" fn _start() -> ! {
    HandlerTable::new()
        .keyboard(key)
        .timer(tick)
        .start()
}

In this example, we begin with our interrupt handlers. The tick() handler prints a period on every timer event, and the key() handler displays the character typed whenever the key is pressed. The _start() function kicks everything off by placing references to these two functions in a HandlerTable object. Invoking .start() on the HandlerTable starts execution. The PIOS sits back and loops endlessly, relying on the event handlers to perform any events of interest or importance.

I have created a simple but more elaborate example that you can use as a template for your own projects. It includes the .cargo/config, Cargo.toml, and x86_64-blog_os.json files described in the tutorials. Once the other components are installed, it should be ready to run.

It demonstrates a simple interactive program that uses both keyboard and timer interrupts. When the user types a viewable key, it is added to a string in the middle of the screen. When the user types an arrow key, the string begins moving in the indicated direction. Here is its main.rs:

#![no_std]
#![no_main]

use lazy_static::lazy_static;
use spin::Mutex;
use pc_keyboard::DecodedKey;
use pluggable_interrupt_template::LetterMover;
use pluggable_interrupt_os::HandlerTable;

#[no_mangle]
pub extern "C" fn _start() -> ! {
    HandlerTable::new()
        .keyboard(key)
        .timer(tick)
        .start()
}

lazy_static! {
    static ref LETTERS: Mutex<LetterMover> = Mutex::new(LetterMover::new());
}


fn tick() {
    LETTERS.lock().tick();
}

fn key(key: DecodedKey) {
    LETTERS.lock().key(key);
}

I created the LetterMover struct to represent the application state. It is wrapped in a Mutex and initialized using lazy_static! to ensure safe access. Nearly any nontrivial program will need to make use of this design pattern.

The tick() function calls the LetterMover::tick() method after unlocking the object. Similarly, the key() function calls the LetterMover::key() method, again after unlocking the object.

Here is the rest of its code, found in its lib.rs file:

#![cfg_attr(not(test), no_std)]

use bare_metal_modulo::{ModNum, ModNumIterator};
use pluggable_interrupt_os::vga_buffer::{BUFFER_WIDTH, BUFFER_HEIGHT, plot, ColorCode, Color, is_drawable};
use pc_keyboard::{DecodedKey, KeyCode};
use num::traits::SaturatingAdd;

pub struct LetterMover {
    letters: [char; BUFFER_WIDTH],
    num_letters: ModNum<usize>,
    next_letter: ModNum<usize>,
    col: ModNum<usize>,
    row: ModNum<usize>,
    dx: ModNum<usize>,
    dy: ModNum<usize>
}

impl LetterMover {
    pub fn new() -> Self {
        LetterMover {
            letters: ['A'; BUFFER_WIDTH],
            num_letters: ModNum::new(1, BUFFER_WIDTH),
            next_letter: ModNum::new(1, BUFFER_WIDTH),
            col: ModNum::new(BUFFER_WIDTH / 2, BUFFER_WIDTH),
            row: ModNum::new(BUFFER_HEIGHT / 2, BUFFER_HEIGHT),
            dx: ModNum::new(0, BUFFER_WIDTH),
            dy: ModNum::new(0, BUFFER_HEIGHT)
        }
    }

This data structure represents the letters the user has typed, the total number of typed letters, the position of the next letter to type, the position of the string, and its motion. Initially, the string consists of the letter A, motionless, and situated in the middle of the screen.

The ModNum data type represents an integer (modulo m). It is very useful for keeping all of these values within the constraints of the VGA buffer.

    fn letter_columns(&self) -> impl Iterator<Item=usize> {
        ModNumIterator::new(self.col)
            .take(self.num_letters.a())
            .map(|m| m.a())
    }

Also from the bare_metal_modulo crate, the ModNumIterator data type starts at the specified value and loops around through the ring. In this case, it takes just enough values to represent all of the columns to use when plotting our string. Using ModNum ensures that all the column values are legal and wrap around appropriately.

    pub fn tick(&mut self) {
        self.clear_current();
        self.update_location();
        self.draw_current();
    }

    fn clear_current(&self) {
        for x in self.letter_columns() {
            plot(' ', x, self.row.a(), ColorCode::new(Color::Black, Color::Black));
        }
    }
    
    fn update_location(&mut self) {
        self.col += self.dx;
        self.row += self.dy;
    }
    
    fn draw_current(&self) {
        for (i, x) in self.letter_columns().enumerate() {
            plot(self.letters[i], x, self.row.a(), ColorCode::new(Color::Cyan, Color::Black));
        }
    }

On each tick:

  • Clear the current string.
  • Update its position.
  • Redraw the string in its new location.
    pub fn key(&mut self, key: DecodedKey) {
        match key {
            DecodedKey::RawKey(code) => self.handle_raw(code),
            DecodedKey::Unicode(c) => self.handle_unicode(c)
        }
    }

    fn handle_raw(&mut self, key: KeyCode) {
        match key {
            KeyCode::ArrowLeft => {
                self.dx -= 1;
            }
            KeyCode::ArrowRight => {
                self.dx += 1;
            }
            KeyCode::ArrowUp => {
                self.dy -= 1;
            }
            KeyCode::ArrowDown => {
                self.dy += 1;
            }
            _ => {}
        }
    }

    fn handle_unicode(&mut self, key: char) {
        if is_drawable(key) {
            self.letters[self.next_letter.a()] = key;
            self.next_letter += 1;
            self.num_letters = self.num_letters.saturating_add(&ModNum::new(1, self.num_letters.m()));
        }
    }
}

The keyboard handler receives each character as it is typed. Keys representable as a char are added to the moving string. The arrow keys change how the string is moving.

As we can see from this example, the capabilities of your PIOS will be limited to handling keyboard events and displaying text in the VGA buffer. Within that scope, however, you can achieve quite a lot. I personally enjoyed recreating a version of a well-known 1980s arcade classic.

This is a pedagogical experiment. I would be interested to hear from anyone who finds this useful or has suggestions.

Updates:

  • 0.2
    • Added is_drawable() function to determine whether a given char can be rendered in the VGA buffer.
    • Rewrote README.md to describe the Pluggable Interrupt Template

Dependencies

~710KB
~13K SLoC