From the Linux Kernel to Git

Git’s origins trace back to the early development of the Linux kernel, which started as a personal project by Linus Torvalds in the early 1990s. As the kernel community expanded, the need for an efficient, distributed version control system became increasingly urgent. Earlier tools were centralized, slow, or proprietary, none suited the rapid development the project required.

Git Branches : credits to deepAI

By 2005, after the Linux community lost access to BitKeeper (their then-primary tool), Torvalds created Git. It was designed in days but engineered with long-term principles that still define it today. It can easily,

• Handle massive, fast-moving projects like the Linux kernel.
• Use a distributed model so every developer has the full history.
• Ensure integrity using cryptographic hashing (SHA-1).
• Make branching and merging extremely fast, encouraging experimentation.

Git’s design made it not just a replacement for existing tools but a revolutionary new approach to version control.

Evolving Into an Ecosystem

While Git itself is purely a command-line tool, hosting platforms transformed it into a global collaboration system. These platforms add issue trackers, pull requests, continuous integration, and social features, turning code repositories into complete development hubs. GitHub, launched in 2008, popularized “social coding” by introducing pull requests for structured code review, issues and project boards for lightweight project management, and community-driven features like forks and stars, along with integrated services such as GitHub Pages and Actions, helping it become the dominant open-source platform. GitLab took a more open and automation-focused approach, offering a fully open-source, self-hostable Git server with built-in CI/CD pipelines and DevSecOps tooling designed for full lifecycle control. Bitbucket differentiated itself through early support for free private repositories and deep integration with Atlassian tools like Jira, Confluence, and Trello, while also providing both cloud and on-premise hosting. Together, these platforms illustrate how Git’s flexible design enabled a diverse and extensible ecosystem of collaboration tools.

GitHub Classroom

My main objective with this post is to introduce the GitHub Classroom. This extends GitHub for educational use, making it easier for instructors to distribute, manage, and grade programming assignments. Instead of manually creating repositories for each student, Classroom automates the entire workflow. Specially it has lot of very good features like,

• Exposes students to industrial workflows, preparing them for internships and industry work.
• Automatically generates private student repositories with one link.
• Supports starter code, allowing uniform project scaffolds.
• Autograding, using tests instructors provide.
• Simplifies feedback, since instructors can comment directly in PRs.

It brings professional tooling into the classroom with minimal overhead.

Setting Up a GitHub Classroom

Before getting started, you’ll need an active GitHub account. If you register using your university email address, you may be eligible for a free GitHub Pro or GitHub Education account, which provides additional features useful for teaching.

• Teachers – GitHub Education
• GitHub Student Developer Pack

The steps below provide a high-level overview of how to set up GitHub Classroom effectively. This isn’t an exhaustive guide, but it covers the essential actions required to create and manage a functional course environment.

Create or Choose a GitHub Organization

A GitHub Organization acts as a container for all student repositories. Keeping course repositories organized in an organization avoids clutter in your personal GitHub account.

Steps to create an organization:

1. Visit github.com/organizations
2. Select a proper name for your class room
3. Choose the free plan (GitHub upgrades education orgs automatically)
4. Add co-instructors as owners or members

This enables GitHub Classroom to automatically create student repos inside the organization .

Create a Classroom

The classroom provides a dashboard where assignments, student progress, and settings live.

To create a classroom:

1. Go to classroom.github.com
2. Click New Classroom
3. Select your organization
4. Name your classroom (e.g., CPEN4700 – Fall 2025)

This will create a classroom dash board where you can add a class rooster. You can easily download the class rooster an CSV file and add it to your classroom.

Create an Assignment

Assignments are the core of GitHub Classroom. They can be configured as individual or group-based tasks and may include starter code, test suites, or autograding setups. Before you create an assignment, you’ll first need a template repository, this is the code scaffold that Classroom will copy into each student’s private repository.

In my classes, I typically provide a small sample project (such as a simple calculator) that students can complete in 5-10 minutes. This helps them get comfortable with the environment, the workflow, and the submission process.

If you’re interested, you’re welcome to use my sample project template repository to test your own assignment setup.

Steps to create an assignment:

1. In your classroom, click New Assignment.
2. Choose either an Individual or Group assignment.
3. Select the template repository for your starter code, such as
   “ArchitectLab/calculator”, or create your own.
4. Configure the assignment settings, including:
   • Deadlines
   • Autograding tests
   • Visibility
5. Generate the student invitation link.

You can share this invitation link through Canvas announcements or within your project description. When students click the link for the first time, they will be prompted to select their name from the roster, which links their Canvas identity to their GitHub account. After this step, GitHub Classroom automatically creates a private repository for each student (or team). From the Classroom dashboard, you can easily monitor all student repositories and track their submissions in one place.

GitHub Classroom includes lightweight tools to help instructors keep track of submissions and performance.

Monitoring features include:

• A list showing who has accepted the assignment
• Quick links to each student’s repository
• Autograding results (when enabled)
• Ability to leave inline comments or review pull requests

This makes it easy to scale beyond small classes while maintaining feedback quality.

Complex AutoGrading Scripts

By default, the autograding feature in GitHub Classroom allows you to test student submissions using predefined test cases and assign grades automatically. However, for more complex assignments, you can create custom workflows using GitHub Actions. These workflows let you automate the execution environment (including containerized setups) and evaluate student submissions with custom scripts.

For example, the following GitHub Actions workflow is used in my sample project to check the output produced by students’ programs:

name: Autograding Tests

on:
  push:
  repository_dispatch:

permissions:
  contents: read

jobs:
  run-autograding-tests:
    runs-on: ubuntu-latest
    if: github.actor != 'github-classroom[bot]'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Prep
        run: |
          rm -f output.txt
          chmod +x run.sh

      - name: Run student script
        id: runscript
        shell: bash
        run: ./run.sh

      - name: Check output with diff
        id: check-diff
        run: |
          echo "Comparing output.txt with expected_output.txt..."
          if diff -wB output.txt expected_output.txt; then
            echo "Output matches expected (0)"
          else
            echo "Output does not match (X)"
            exit 1
          fi

      - name: Upload output artifact if output does not match
        if: failure()   
        uses: actions/upload-artifact@v4
        with:
          name: student-output
          path: |
            output.txt
            expected_output.txt
          retention-days: 7

This workflow can be easily extended to support more complex grading scenarios. Instead of running on the default ubuntu-latest runner, the job can be configured to execute inside a custom Docker container by specifying a container image, ensuring a consistent runtime environment across all submissions. The testing logic can also be customized by replacing run.sh with language-specific scripts, test frameworks (such as JUnit, pytest, or custom bash scripts), or multiple test stages. Additional steps can be added to install dependencies, run static analysis, or evaluate performance constraints. Together, these modifications allow instructors to tailor the autograding process to match real-world development environments and more advanced assignment requirements.

Final Thoughts

Git was originally created to meet the fast-paced demands of early Linux kernel development, but it has since grown into a universal tool that underpins nearly all modern software engineering workflows. Platforms like GitHub expanded Git into a collaborative ecosystem, and GitHub Classroom builds on that foundation to support teaching and learning.

In summary, GitHub Classroom provides:

• Professional-grade tools for students and exposure to CICD workflows
• Automated workflows that significantly reduce overhead
• A scalable, organized system for managing assignments

Whether you’re teaching an introductory programming course or an upper-level computer engineering or computer science class, GitHub Classroom offers a simple yet powerful way to integrate real-world development practices into your curriculum. And based on student feedback, I can confidently say, they enjoy working with it just as much as we do.

Features

Let’s start with the features first.

• Full router functionalities with dual-band (2.4GHz and 5GHz) with gigabit ethernet
• WiFi repeater capabilities (WiFi Client mode and AP mode at once)
• Ability to host VPN, adblocking, and Tailscale
• Ability to run media servers and other containers with Docker
• Efficient on power consumption (less than 10W)
• Smallest possible size

Hardware Part of the Story

For my build, I wanted the smallest form factor possible while still satisfying my requirements. So I opted to use standalone hardware with some modifications. I am outlining here the components I used for this project and the modifications I did for them, however, if you don’t want to do hardware modifications you can change the components based on your liking.

Components

• Processing Unit : Raspberry Pi CM4 board without onboard wifi. Since the Raspberry Pi onboard wifi is not powerful enough, we will be using a separate wifi module. Therefore, opting for the CM4 without onboard wifi will save some power.
• Wifi Module : Intel BE200NGW dual band wifi card
• Case and Motherboard: GeeekPi DeskPi Mini Cube which has Gigabit ethernet and M.2 M-Key PCI-E interface.
• Adaptor Card: Since our Motherboard only has a M.2 M-Key Slot, we have to convert this to M.2 E-Key Slot so that we can use our wifi card.

Modifications

For the CM4 I had a low-spec one lying around that I bought for a previous experiment which had 1GB RAM and 8GB EMMC. Since I wanted the Docker support, I upgraded the RAM and EMMC to 8GB and 128GB respectively (Yes, it is a tedious process that requires a lot of patience). GeeekPi Mini Cube is packed very much within a very tiny space. For this reason, the adaptor card and the wifi module do not fit within the available space without modifying M.2 M-Key Slot on the motherboard. I had to desolder the original M.2 connector, which was 8.5MM in height, to a connector with 6.5MM. Then I had to find a suitable pair of antennas with dual-band support. Note that BE200 antenna connections use MHF4 connectors, not UHF. Other than that, no major changes were required.

Soft(Firm)ware Part of the Story

I think this is the most important part of the building process for several reasons. I could not find good enough documentation to make everything work as I wanted. So after a lot of trial and error, I found the configurations that supported all the features that I wanted.

• Debian Bookworm (64bit) without GUI
• RaspAP is a powerful platform that supports all the fancy features that I wanted from my router.
• Intel BE200 firmware Driver.

I am not going to talk about installing each of the above components since there is information about installing each of the components in their corresponding documentation pages.

By default, RaspAP supports wifi repeater mode (both in the community edition + insider edition) as long as you have two physical adaptors with two separate interfaces. But the interesting thing is that BE200 supports multiple bands and multiple channels. This means we should be able to create multiple interfaces in theory. This is where I had to do several experiments to figure out the components.

Virtual wlan Interfaces

This process elaborates on the process of creating the virtual WLAN interface. I am giving the name wlan0_ap for this interface. You can create the interface with the following command.

sudo iw dev wlan0 interface add wlan0_ap type managed

You can check whether the new interface is available with the ifconfig command. Next, we have to set a static IP for the interface. You can use your favorite private network IP for this.

sudo ip addr add 10.4.141.1/24 dev wlan0_ap
sudo ip link set wlan0_ap up

You can verify the assignment of IP with the following command

ip addr show wlan0_ap

Next, we have to restart the socket related to the iwlan0.

#reinitialize socket
sudo wpa_supplicant -B -Dnl80211,wext -c/etc/wpa_supplicant/wpa_supplicant.conf -iwlan0

To make the interface available permanently, create a file /etc/systemd/system/wifiap-setup.service and place the following components inside the file.

[Unit]
Description=Setup wlan0_ap and wpa_supplicant on boot
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/sbin/iw dev wlan0 interface add wlan0_ap type managed
ExecStart=/usr/sbin/wpa_supplicant -B -Dnl80211,wext -c/etc/wpa_supplicant/wpa_supplicant.conf -iwlan0
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Next, we have to reload systemd, enable, and start the service with the following commands.

sudo systemctl daemon-reload
sudo systemctl enable wifiap-setup
sudo systemctl start wifiap-setup

Hotspot and Configuring DHCP

Once you have the interface up and running, you can use the newly created interface as the access point. To do that, login to the RaspAP admin panel and use the Hotspot tab. Select the newly created wlan0_ap interface. Configure the rest of the settings to your liking. After saving the settings and restarting the AP, you will see the SSID of your network. If you try to connect, it will fail due to an invalid (unavailable) DHCP.

Let’s configure the DHCP for the interface. Go to the DHCP server tab from the RaspAP admin panel. Remember the static IP (10.4.141.1 in my case) used during the creation of the wlan0_ap interface. Based on that, we have to create the DHCP settings.

Conclusion

At the end, Routour🗼 has been a rewarding project. I hope this documentation helps others who are interested in building their own custom router. If you have any questions or suggestions, feel free to reach out.

What is a Lattice?

A lattice in mathematics is a regular, repeating arrangement of points in an n-dimensional space. Formally, a lattice Λ in \(\mathbb{R}^n\) is defined as the set of all integer linear combinations of n linearly independent basis vectors v₁, v₂, …, vₙ:

Here, each vector \(\mathbf{v}_i\) serves as a basis vector, and the coefficients \(a_i\) are integers. This structure forms a discrete subgroup of \(\mathbb{R}^n\), providing the foundation for various applications in cryptography, such as constructing secure cryptographic schemes based on the hardness of lattice problems. The geometric properties of lattices, including their symmetry and densest packing arrangements, play a crucial role in their cryptographic strength and efficiency.

Let’s Simplify Things

Instead of n-dimensional space, lets narrow down it to a two-dimensional space. Our basis vectors can be denoted as \(\mathbf{v}_1\) and \(\mathbf{v}_2\). So in this case, every point in this two-dimentional lattice can be expressed as an integer linear combination of these basis vectors:

This means that by scaling and adding the basis vectors with integer coefficients, you can generate all the points that make up the lattice. The choice of basis vectors determines the shape and structure of the lattice.

In the interactive lattice visualization above, you can drag the blue and green basis vectors to different positions. As you move these vectors, the entire lattice adjusts in real-time to reflect the new basis. This dynamic behavior demonstrates how altering the basis vectors directly affects the arrangement and density of the lattice points.

Observe that any combination of basis vectors points to a point on the lattice it self. You can change the coffeicients fo the \(a_1\) and \(a_2\) to see how the result falls back again on the lattice. Try entering different coefficients in the input boxes and click the “Update Vector” button to observe how linear combinations of the basis vectors generate new lattice points.

Lattice to Cryptography

Lattice-based cryptography relies on the hardness of lattice problems such as,

• Shortest Vector Problem (SVP)
• Closest Vector Problem (CVP)

which are believed to be resistant to both classical and quantum attacks. Additionally, lattice-based schemes often offer advanced functionalities like fully homomorphic encryption, which allows computations to be performed directly on encrypted data, and secure multi-party computation, enhancing their versatility and security in various applications.

Shortest Vector Problem (SVP)

The Shortest Vector Problem (SVP) is a fundamental challenge in lattice theory and cryptography. Given a lattice Λ generated by a set of basis vectors, SVP seeks to find the shortest non-zero vector within the lattice. Formally, SVP can be defined as:

Closest Vector Problem (CVP)

The Closest Vector Problem (CVP) is another challenge in lattice theory and cryptography. Given a lattice Λ generated by a set of basis vectors and a target point t in \(\mathbb{R}^n\), CVP seeks to find the lattice vector v in Λ that is closest to t in terms of Euclidean distance. Formally, CVP can be defined as:

SVP and CVP are widely recognized as computationally hard problems, especially in high-dimensional lattices. There are lattice-based cryptographic schemes that rely on the challenge of finding the closest lattice vector to a given target. In the subsequent episodes, we will explore why these problems are so challenging and how they are effectively utilized in cryptographic algorithms.

Conclusion

In this episode of the CrPT🔑 series, we explored the basics of lattices. You had the opportunity to select two basis vectors to create your own two-dimensional lattice using the interactive visualization tool. Additionally, we briefly discussed the Shortest Vector Problem (SVP) and Closest Vector Problem (CVP), which are foundational to lattice-based cryptography. In the upcoming episodes, we’ll look deeper into these problems and their applications in securing cryptographic systems.

AI Generated Image : credits to grok2

One-Time Pad

The one-time pad (OTP) is considered the only theoretically unbreakable cryptographic method when implemented correctly because it achieves perfect secrecy, meaning the ciphertext provides no information about the plaintext without the key, as proven by Claude Shannon. The key used in an OTP must be as long as the message, truly random, securely shared, and used only once.

To illustrate how a One-Time Pad (OTP) works, let’s consider a simple example involving two parties, Alice and Bob.

Step 1: Key Generation Alice and Bob agree on a random key that is as long as the message they wish to exchange. For this example, let’s use the message “HELLO”.

• Message: H E L L O
• Key: X M C K L

Step 2: Encryption Each character of the message is combined with the corresponding character of the key using a modular addition (for simplicity, we’ll use their ASCII values).

• Ciphertext: 160 146 143 151 155

Step 3: Decryption Bob, who possesses the same key, can decrypt the ciphertext by subtracting the key values from the ciphertext.

• Decrypted Message: H E L L O

Requirements of OTP:

• The key must be truly random, same size as the message and kept secret.
• The key is used only once; reusing keys compromises security.
• The security of OTP relies on the randomness and secrecy of the key.

However, if you carefully consider the first two requirements, you’ll notice a significant drawback of the OTP. The key must be as long as your message, which defeats its original purpose because transferring the key securely requires the same effort as transferring the message itself. Almost all cryptographic algorithms used today address this issue in various ways, such as through the use of asymmetric encryption, which allows secure key exchange without the need for pre-shared keys, or by employing key derivation functions and protocols like Diffie-Hellman to enable secure communication over insecure channels. Additionally, these algorithms utilize shorter keys by using complex mathematical problems and computational hardness assumptions. They help to implement robust security without the need for excessively long keys.

Artificial Intelligence (AI) and Cryptography?

Now that we understand the basics of the One-Time Pad, let’s examine whether AI will be able to take over modern cryptography. As mentioned earlier, cryptographic algorithms are designed based on hardness assumptions. For example, brute-forcing a message encrypted using AES-CTR-256 would take billions of years even for a supercomputer. The same applies to training an AI model to crack modern encryption algorithms. Let me explain why…

Cryptography removes Patterns in Data

Generative models, such as those in machine learning, cannot replicate the security of an OTP because they produce pseudo-random sequences rather than truly random ones, and they are designed to recognize and replicate patterns, which contradicts the OTP’s requirement for patternless keys. In otherwords, AI models are pre-trained on data, such that they can make a prediction on new data by understading the pattern of the data. However, the major controbution of cryptograohy is to remove the patterns from the data.

We can replicate this analogy with a simple illustration of a hash function. In the text box below we have a text string, the correspoding SHA-512 string is on the next message box. Try changing the value of the text string and observe how the hash value of the string changes with that.

As you oubserved, it a machine learning model needs to learn this using traning data, essentially it needs to learn all the patterns. At this point it becomes a table lookup rather than a prediction.

Secret Keys Add More Complexity

Making this relation more complex, the most common encryption, decryption, sign and verify mechanism uses various forms of secret keys. Unless the key is compromised, finding a non-existing pattern between plain text and cypher text has too much of complexity.

To understand this, lets look at the following illustration.

As you have seen in the above illustrations, AI is not in a position to impact modern cryptography. Someone might argue about what would happen if computing power increases to the point where AI can utilize vast resources. The answer is simple: in such situations, AI is not required, and brute force attacks can be conducted with the same effort. However, cryptographic algorithm parameters, such as key sizes, can be increased to account for potential computational power. An example of this is the deprecation of DES in favor of more secure algorithms like AES, due to the potential for brute-forcing with modern computers.

Quantum Computers and Cryptography?

Although we don’t have to worry about AI breaking cryptography, quantum computers have the potential to become a threat to some of the algorithms used to build the public key infrastructure (PKI). Cryptographic algorithms like RSA and Elliptic Curve-based Cryptography (ECC) are implemented based on assumptions about the hardness of prime factorization. Theoretically, with a quantum computer with enough qubits, Shor’s algorithm can solve the prime factorization problem.

When Quantum Computers Will Take Over?

So the next question arises: What happens to the current infrastructure that uses PKI, such as blockchain, network authentication, and secure communication systems? We don’t need to panic about this question at the moment. Current quantum computers do not have the capacity to break modern PKI yet. Even Google’s latest quantum computer, Willow, has 105 qubits, which is not capable of breaking RSA-1024, a standard that is already deprecated due to its low security strength. Quantum computers need to successfully solve the issue of “noise” in order to scale well enough to achieve this capability.

Post Quantum Cryptography

Although current quantum computers are not powerful enough yet, advancements in science may allow them to scale to a level capable of breaking PKI. As a precaution, researchers are proposing post-quantum cryptographic algorithms. The National Institute of Standards and Technology (NIST) has standardize post-quantum cryptographic algorithms. Aiming to deprecate vulnerable PKI algorithms like RSA and Elliptic Curve Cryptography (ECC) by 2030, NIST is evaluating and selecting new standards that can withstand quantum attacks. The selected algorithms include CRYSTALS-Kyber for key encapsulation and CRYSTALS-Dilithium for digital signatures.

The concepts of these algorithms are based on two main problems:

1. Lattice Problems
2. Learning with Errors

In the rest of this series, we will discuss these techniques with simplified examples and illustrations.

Conclusion

In this first episode of CrPT🔑, we have explored the fundamental principles of cryptography, the potential threats posed by advancements in artificial intelligence and quantum computing, and the proactive measures being taken to secure our digital future. While AI may not currently pose a significant threat to modern cryptographic systems, the rise of quantum computing necessitates the development of robust post-quantum algorithms. So in the subsequant articles, lets discuss more about the concepts behind these new algorithms, so that we can be familier with them before it is too late.

AI Generated Image : credits to chatGPT

Key Components and Entities

When it comes to an Android device—whether it’s a mobile phone, tablet, car entertainment system, or any other form factor—there are several key components involved in its realization:

1. Bootloader: The initial software that runs when the device powers on, responsible for starting the kernel.

2. Linux kernel, serves as the core subsystem of the Android operating system, managing communication between hardware and software.

3. Android system image, includes the Android operating system and essential applications. Android is open source, vendors can modify the implementation to suit their own hardware as they wish.

Each of these components is developed by different entities: the bootloader is provided by the hardware manufacturer (vendor), the Linux kernel is developed by the open-source community under the Linux Foundation, and the Android system image is provided by Google. Device manufacturers can modify the Android system image to suit their own hardware as they wish.

The Chain of Trust Among Components

The bootloader, Linux kernel, and Android system image work together to create a secure environment for your device. When the device powers on, the bootloader verifies the kernel’s integrity using cryptographic signatures. Subsequently, the kernel verifies the Android system image before loading it. This sequential verification establishes a chain of trust, ensuring that each component is authentic and has not been tampered with. Additionally, Over-The-Air (OTA) updates are signed with private keys and verified using public keys, maintaining the security and integrity of the updates applied to the system image.

Generic System Images (GSI)

When manufacturers stop providing updates for their devices, users can turn to Generic System Images (GSIs) to receive the latest Android versions. GSIs are system images with adjusted configurations for Android devices, compatible with Project Treble.

What Is a GSI? A GSI is a barebones Android OS image that can run on any device compliant with Project Treble, regardless of the manufacturer.

Who Provides It? While Google provides the official Android source code via Android Open Source Project (AOSP), it is utilized by several open-source projects to run the latest Android versions on devices abandoned by their vendors. There are more generic GSI versions, such as TrebleDroid and treble_aosp, which work on many different devices, and device-specific GSI versions, like DUO-DE, designed specifically for the Microsoft Surface Duo’s unique dual-screen foldable configuration. Often, people confuse these GSI images with Pixel ROMs; however, GSIs are implemented using the barebone Android images provided by Google.

GSI and Security

To install a GSI image on an Android device, you must unlock the device’s bootloader unless you are the vendor with access to the device’s private keys. Unlocking the bootloader disables certain trust mechanisms implemented in the bootloader. However, security features such as Android Debug Bridge (ADB) authorization continue to protect your device data if the device is lost or falls into the possession of an adversary.

Since unlocking the bootloader disables the security mechanisms it provides, the trust in the GSI is established independently. To ensure this trust, GSI maintainers use their own release keys to sign the GSI packages. These keys are similar to vendor keys. They provide the same level of security for operations on the device, preventing unauthorized modifications and maintaining the integrity of the system. Once you manually flash a GSI image to your device, GSI keys ensure the security of the following components.

1. They ensure that over-the-air (OTA) updates are authentic and have not been tampered with. During installation, the device verifies the signature using the embedded public key.

2. Protection of System Applications: Without the proper release keys, system applications cannot be replaced or modified.

Since the Android system of the GSI is originally from the Android, all the security features available in the lastet version of the Android is availble to the users via GSI.

Conclusion

In this guide, we’ve explored the key components that ensure the security of Android devices, including the bootloader, Linux kernel, and Android system image. We discussed how these components interact through a chain of trust, utilizing cryptographic signatures with private and public keys to verify each stage of the boot process and Over-The-Air (OTA) updates. Additionally, we discussed about Generic System Images (GSIs), highlighting their role in providing up-to-date Android versions for devices no longer receiving manufacturer updates.

Ultimately, the trustworthiness of an Android device hinges on the reliability of its manufacturers and, in the case of GSIs, the maintainers behind these open-source projects. When using a device from an unknown manufacturer, users must place a certain level of trust in that manufacturer’s commitment to security. Similarly, opting for a GSI replaces the manufacturer’s role with GSI maintainers. The advantage here is that most GSI projects are open source, allowing the public to review and contribute to their implementations, thereby enhancing transparency and security.

Key Takeaways:

• Chain of Trust: Ensures that each component of the Android system is verified and secure, preventing unauthorized modifications.
• GSIs as a Solution: Provide a way to keep devices secure and updated even after manufacturers cease support.
• Open Source Benefits: GSIs benefit from community oversight, increasing the likelihood of identifying and addressing security vulnerabilities promptly.
• Trust Considerations: Whether relying on manufacturers or GSI maintainers, users must trust that the entities managing their device’s software prioritize security and integrity.

By understanding these components and the dynamics of trust in both manufacturer-provided and community-driven updates, users can make informed decisions to maintain the security and longevity of their Android devices.

Programmable Interrupt Controller

A Programmable Interrupt Controller (PIC) is a hardware component in the system that is crucial for managing interrupt requests (IRQs) from various peripherals. Its primary function is to prioritize interrupt signals from hardware peripherals based on their urgency and importance, making sure that critical tasks are handled promptly. When an interrupt occurs, the PIC suspends the CPU’s current task and directs it to an interrupt handler, which manages the interrupt and executes necessary actions. The PIC also allows for interrupt masking and priority configuration, enabling system designers to customize interrupt handling according to specific requirements. While modern computer systems may utilize more advanced interrupt controllers like the Advanced Programmable Interrupt Controller (APIC), the fundamental role of prioritizing and managing interrupts remains essential for efficient system operation.

Interrupt

Let’s first review the types of interrupts in RISC-V, which can be broken down into several major categories:

• Local Interrupt
  • Software Interrupt
  • Timer Interrupt
• Global Interrupt
  • External Interrupt

The Exception Code of various interrupts is also defined in detail in the RISC-V specification

Specifically, the exception code will be recorded in the mcause register.

If we want system programs running in RISC-V to support interrupt processing, we also need to set the field value of the MIE Register:

// Machine-mode Interrupt Enable
#define MIE_MEIE (1 << 11) // external
#define MIE_MTIE (1 << 7)  // timer
#define MIE_MSIE (1 << 3)  // software
// enable machine-mode timer interrupts.
w_mie(r_mie() | MIE_MTIE);

PIC in RISC-V

RISC-V has its own Programmable Interrupt Controller implementation known as Platform-Level Interrupt Controller (PLIC). As we discussed earlier, there can be multiple interrupt sources (keyboard, mouse, hard disk…) connected to PLIC of a system. PLIC will determine the priority of these interrupts and then allocate them to the processor’s Hart (the minimum hardware thread in RISC-V) for processing by the CPU.

Interrupt Request

An Interrupt Request is also known as IRQ, is a mechanism used by hardware devices to signal the CPU that they need attention or service. When a hardware device requires the CPU to perform a task, such as processing incoming data or handling an event, it sends an interrupt request. The CPU then temporarily suspends its current operation, saves its state, and jumps to a predefined location in memory known as an interrupt handler. This handler executes the necessary actions to address the request from the device. IRQs are assigned unique numerical identifiers, typically ranging from 0 to 15 in legacy systems, to distinguish between different interrupt sources. Each IRQ is associated with specific hardware components, such as keyboards, mice, storage devices, or network cards, allowing the CPU to prioritize and handle interrupts appropriately. Taking the RISC-V virtual machine - Virt in Qemu as an example, its source code defines IRQs for different interrupts as follows:

enum {
    UART0_IRQ = 10,
    RTC_IRQ = 11,
    VIRTIO_IRQ = 1, /* 1 to 8 */
    VIRTIO_COUNT = 8,
    PCIE_IRQ = 0x20, /* 32 to 35 */
    VIRTIO_NDEV = 0x35 /* Arbitrary maximum number of interrupts */
};

When we are writing an operating system, we can use the IRQ code to identify the type of external interrupt and solve the problems of keyboard input and disk reading and writing.

Configuring the PIC

As the name of PIC suggests, it can be programmed. For this purpose, PLIC adopts a Memory Map mechanism, which maps some important information to Main Memory. In this way, we can communicate with PLIC by accessing the memory. We can find these memory map definitions in Virt’s source code, which defines the virtual locations of PLIC as follows,

static const MemMapEntry virt_memmap[] = {
    [VIRT_DEBUG] =       {        0x0,         0x100 },
    [VIRT_MROM] =        {     0x1000,        0xf000 },
    [VIRT_TEST] =        {   0x100000,        0x1000 },
    [VIRT_RTC] =         {   0x101000,        0x1000 },
    [VIRT_CLINT] =       {  0x2000000,       0x10000 },
    [VIRT_PCIE_PIO] =    {  0x3000000,       0x10000 },
    [VIRT_PLIC] =        {  0xc000000, VIRT_PLIC_SIZE(VIRT_CPUS_MAX * 2) },
    [VIRT_UART0] =       { 0x10000000,         0x100 },
    [VIRT_VIRTIO] =      { 0x10001000,        0x1000 },
    [VIRT_FW_CFG] =      { 0x10100000,          0x18 },
    [VIRT_FLASH] =       { 0x20000000,     0x4000000 },
    [VIRT_PCIE_ECAM] =   { 0x30000000,    0x10000000 },
    [VIRT_PCIE_MMIO] =   { 0x40000000,    0x40000000 },
    [VIRT_DRAM] =        { 0x80000000,           0x0 },
};

Each PIC interrupt source will be represented by a temporary register. By adding PLIC_BASE to the offset offset of the temporary register, we can know the location where the temporary register is mapped to the main memory.

0xc000000 (PLIC_BASE) + offset = Mapped Address of register

Interrupts to TinyOS

I think so far we looked at the background of the interrupts. Let’s add this functionality to the TinyOS operating system. First, we need to initialize Virt’s PLIC controller. For that, we use the plic_init() function, which is defined in plic.c:

void plic_init()
{
  int hart = r_tp();
  // QEMU Virt machine support 7 priority (1 - 7),
  // The "0" is reserved, and the lowest priority is "1".
  *(uint32_t *)PLIC_PRIORITY(UART0_IRQ) = 1;

  /* Enable UART0 */
  *(uint32_t *)PLIC_MENABLE(hart) = (1 << UART0_IRQ);

  /* Set priority threshold for UART0. */

  *(uint32_t *)PLIC_MTHRESHOLD(hart) = 0;

  /* enable machine-mode external interrupts. */
  w_mie(r_mie() | MIE_MEIE);

  // enable machine-mode interrupts.
  w_mstatus(r_mstatus() | MSTATUS_MIE);
}

As shown in the above example, plic_init() mainly performs following initialization actions:

• Set the priority of UART_IRQ. Since PLIC can manage multiple external interrupt sources, we must set priorities for different interrupt sources. Then in case of conflicting requests, PLIC will know which IRQ to process first.
• Enable UART interrupt for hart0
• Set threshold. IRQs less than or equal to this threshold will be ignored by PLIC. We can configure the threshold using,

  *(uint32_t *)PLIC_MTHRESHOLD(hart) = 10;
  

  In this way, the system will not process the UART’s IRQ.

• Enable external interrupts and global interrupts in Machine mode. It should be noted that this project originally used trap_init() to enable global interrupts in Machine mode. After this modification, we changed plic_init() to be responsible.

Note that the peripherals also need configuration. In the case of UART, settings such as baud rate and other actions. uart_init() is defined in lib.c.

Modify Trap Handler

We discussed about trap hander in the episode Preemptive Scheduling. You might remember the following diagram.

graph LR
    C[trap_handler] --> D[soft_handler]
    C --> E[timer_handler]
    C --> F[exter_handler]

Previously in Preemptive Scheduling, trap_handler() only supported the processing of time interrupts. This time we want to make it support the processing of external interrupts as well.

/* In trap.c */
void external_handler()
{
  int irq = plic_claim();
  if (irq == UART0_IRQ)
  {
    lib_isr();
  }
  else if (irq)
  {
    lib_printf("unexpected interrupt irq = %d\n", irq);
  }

  if (irq)
  {
    plic_complete(irq);
  }
}

Because the goal this time is to enable the operating system to process UART IRQ, we need to add that to the interrupt request as above. This will invoke the function lib_isr().

/* In lib.c */
void lib_isr(void)
{
    for (;;)
    {
        int c = lib_getc();
        if (c == -1)
        {
            break;
        }
        else
        {
            lib_putc((char)c);
            lib_putc('\n');
        }
    }
}

The principle of lib_isr() is quite simple. It just repeatedly detects whether the UART’s RHR register has received new data. If it is empty (c == -1), it jumps out of the loop. Registers related to UART are defined in riscv.h. Some register addresses have been added to support lib_getc(). The general definitions of UART registers are as follows:

 #define UART 0x10000000L
 #define UART_THR (volatile uint8_t *)(UART + 0x00) // THR:transmitter holding register
 #define UART_RHR (volatile uint8_t *)(UART + 0x00) // RHR:Receive holding register
 #define UART_DLL (volatile uint8_t *)(UART + 0x00) // LSB of Divisor Latch (write mode)
 #define UART_DLM (volatile uint8_t *)(UART + 0x01) // MSB of Divisor Latch (write mode)
 #define UART_IER (volatile uint8_t *)(UART + 0x01) // Interrupt Enable Register
 #define UART_LCR (volatile uint8_t *)(UART + 0x03) // Line Control Register
 #define UART_LSR (volatile uint8_t *)(UART + 0x05) // LSR:line status register
 #define UART_LSR_EMPTY_MASK 0x40                   // LSR Bit 6: Transmitter empty; both the THR and LSR are empty

Simulation

Let’s see the TinyOS interrupt handler in action. If you have followed the tutorial series continuously, you know the steps.

cd 07-ExterInterrupt 
make

riscv32-unknown-elf-gcc -nostdlib -fno-builtin -mcmodel=medany -march=rv32ima -mabi=ilp32 -g -Wall -T os.ld -o os.elf start.s sys.s lib.c timer.c task.c os.c user.c trap.c lock.c plic.c

Next, you can run the Virt and type letters into the terminal, which will generate interrupt requests.

make qemu

Press Ctrl-A and then X to exit QEMU
qemu-system-riscv32 -nographic -smp 4 -machine virt -bios none -kernel os.elf
OS start
OS: Activate next task
Task0: Created!
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
external interruption!
j
Task0: Running...
Task0: Running...
external interruption!
k
Task0: Running...
Task0: Running...
Task0: Running...
external interruption!
j
Task0: Running...
external interruption!
k
external interruption!
j
Task0: Running...
timer interruption!
timer_handler: 1
OS: Back to OS
QEMU: Terminated


In this episode, we have looked at configuring external peripherals and generating interrupts with that. I hope this was an interesting episode since this basic functionality is required when you are dealing with embedded systems in the future.

What is a Spinlock

A spinlock is a synchronization mechanism used to protect shared resources (such as data structures) from being accessed simultaneously by multiple threads of execution. Unlike other synchronization primitives like mutexes or semaphores, which typically put threads to sleep when the resource they’re trying to access is unavailable, a spinlock causes a thread trying to acquire the lock to repeatedly “spin” in a loop (i.e., continuously checking the lock’s state) until it becomes available.

The basic idea behind a spinlock is simple: when a thread wants to acquire the lock, it checks to see if the lock is available. If it is, the thread acquires the lock and continues execution. If the lock is not available (i.e., another thread holds it), the thread continuously polls the lock until it becomes available, at which point it acquires the lock and proceeds.

Atomic operations

Atomic operations can ensure that an operation will not be interrupted by other operations before completion. Taking RISC-V as an example, it provides RV32A Instruction set, which are all atomic operations (Atomic).

In order to avoid multiple Spinlocks accessing the same memory at the same time, atomic operations are used in the Spinlock to ensure correct locking logic implementation.

In fact, not only Spinlock, mutex lock also requires Atomic operation in implementation.

Simple Spinlock in C language

Consider the following code:

typedef struct spinlock{
    volatile uint lock;
} spinlock_t;
void lock(spinlock_t *lock){
    while(xchg(lock−>lock, 1) != 0);
}
void unlock(spinlock_t *lock){
    lock->lock = 0;
}

Through the sample code, you can notice a few points:

• Keyword volatile: volatile keyword lets the compiler know that the variable may be accessed in unexpected circumstances, so do not optimize the variable’s instructions to avoid storing the result in the Register, but write it directly to memory.
• Lock function: xchg(a,b) The contents of the two variables a and b can be swapped, and the function is an atomic operation. When the lock value is not 0, the execution thread will spin and wait until the lock is 0 (that is, it can be locked )until.
• Unlock function: Since only one thread can obtain the lock at the same time, there is no need to worry about preemption of access when unlocking. Because of this, the example does not use atomic operations.

Simple Lock

First of all, since TinyOS is a Single Hart (hardware thread) operating system, in addition to using atomic operations, there is actually a very simple way to achieve the locking effect:

void basic_lock()
{
  w_mstatus(r_mstatus() & ~MSTATUS_MIE);
}

void basic_unlock()
{
  w_mstatus(r_mstatus() | MSTATUS_MIE);
}

In lock.c, we implement a very simple lock. When we invoke basic_lock() in the program, the system’s machine mode interrupt mechanism will be turned off. In this way, we can ensure that no there are other programs accessing the Shared memory to avoid the occurrence of Race condition.

Spinlock Implementation

The above lock has an obvious flaw: When the program that acquires the lock has not released the lock, the entire system will be blocked. In order to ensure that the operating system can still maintain the multi-tasking mechanism, we must implement a bit more complex lock :

typedef struct lock
{
  volatile int locked;
} lock_t;

void lock_init(lock_t *lock)
{
  lock->locked = 0;
}

void lock_acquire(lock_t *lock)
{
  for (;;)
  {
    if (!atomic_swap(lock))
    {
      break;
    }
  }
}

void lock_free(lock_t *lock)
{
  lock->locked = 0;
}

In fact, the above program code is basically the same as the previous example of Spinlock. When we implement it in the system, we only need to deal with one more troublesome problem, which is to implement the atomic swap action atomic_swap():

.globl atomic_swap
.align 4
atomic_swap:
        li a5, 1
        amoswap.w.aq a5, a5, 0(a0)
        mv a0, a5
        ret

As shown in above assembly construct, we can read the lock in the lock structure, exchange it with the value 1, and finally return the contents of the register a5. Further summarizing the execution results of the program, we can draw two cases:

1. Case 1- Successfully acquire the lock: When lock->locked is 0, after the exchange through amoswap.w.aq, the value of lock->locked is 1 and the return value (Value of a5) is 0:

   void lock_acquire(lock_t *lock)
   {
     for (;;)
     {
    if (!atomic_swap(lock))
    {
      break;
    }
     }
   }
   

   When the return value is 0, lock_acquire() will successfully jump out of the infinite loop and enter Critical sections for execution.

2. Case 2- No lock acquired: Otherwise, continue to try to obtain the lock in an infinite loop.

Simulation

If you followed the TinyOS tutorial series contnously, you know how to run the simulation of the code. If you missed the first article about setting up the environment, you can check it from here.

Now let’s take a look at the system’s behaviour.

cd tinyos/06-Spinlock 
make

riscv32-unknown-elf-gcc -nostdlib -fno-builtin -mcmodel=medany -march=rv32ima -mabi=ilp32 -g -Wall -T os.ld -o os.elf start.s sys.s lib.c timer.c task.c os.c user.c trap.c lock.c

make qemu

Press Ctrl-A and then X to exit QEMU
qemu-system-riscv32 -nographic -smp 4 -machine virt -bios none -kernel os.elf
OS start
OS: Activate next task
Task0: Created!
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
timer interruption!
timer_handler: 1
OS: Back to OS
 
OS: Activate next task
Task1: Created!
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
Task1: Running...
timer interruption!
timer_handler: 2
OS: Back to OS
 
OS: Activate next task
Task2: Created!
The value of shared_var is: 550
The value of shared_var is: 600
The value of shared_var is: 650
The value of shared_var is: 700
The value of shared_var is: 750
The value of shared_var is: 800
The value of shared_var is: 850
The value of shared_var is: 900
The value of shared_var is: 950
The value of shared_var is: 1000
The value of shared_var is: 1050
The value of shared_var is: 1100
The value of shared_var is: 1150
The value of shared_var is: 1200
The value of shared_var is: 1250
The value of shared_var is: 1300
The value of shared_var is: 1350
The value of shared_var is: 1400
The value of shared_var is: 1450
The value of shared_var is: 1500
The value of shared_var is: 1550
The value of shared_var is: 1600
timer interruption!
timer_handler: 3
OS: Back to OS
 
OS: Activate next task
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
Task0: Running...
timer interruption!
timer_handler: 4
OS: Back to OS
QEMU: Terminated


Debug Mode and Breakpoint

With the QEMU simulation, you can run the simulation in Debug mode with added break points. Following are the steps for running the TinyOS in debug mode.

make debug

riscv32-unknown-elf-gcc -nostdlib -fno-builtin -mcmodel=medany -march=rv32ima -mabi=ilp32 -g -Wall -T os.ld -o os.elf start.s sys.s lib.c timer.c task.c os.c user.c trap.c lock.c  
Press Ctrl-C and then input 'quit' to exit GDB and QEMU
-------------------------------------------------------
Reading symbols from os.elf...
Breakpoint 1 at 0x80000000: file start.s, line 7.
0x00001000 in ?? ()
=> 0x00001000: 97 02 00 00 auipc t0,0x0
 
Thread 1 hit Breakpoint 1, _start () at start.s:7
7 csrr t0, mhartid # read current hart id
=> 0x80000000 <_start+0>: f3 22 40 f1 csrr t0,mhartid
(gdb)


You can set the breakpoint in any c file using the following command,

(gdb) b trap.c:27

Breakpoint 2 at 0x80008f78: file trap.c, line 27. (gdb)

As the example above, when process running on trap.c, line 27 (Timer Interrupt). The process will be suspended automatically until you press the key c (continue) or s (step).

In this episode, we plan to combine the two techniques of the above episodes to implement a “Preemptive” operating system with forced time interruption. Technically, TinyOS is going to be a real-time operating system (RTOS) at the end of this episode.

Simulation

As we discussed in earlier episodes, we know that where there are multple processes running parallely, they need share the same set of resources between them. So with that in mind, let’s run the simulation. Simulation steps are as usual.

If you missed the first article about setting up the environment, you can check it from here.

First let’s take a look at the system’s behaviour.

cd tinyos/05-Preemptive
make

riscv32-unknown-elf-gcc -nostdlib -fno-builtin -mcmodel=medany -march=rv32ima -mabi=ilp32 -T os.ld -o os.elf start.s sys.s lib.c timer.c task.c os.c user.c

make qemu

Press Ctrl-A and then X to exit QEMU
qemu-system-riscv32 -nographic -smp 4 -machine virt -bios none -kernel os.elf
OS start
OS: Activate next task
Task0: Created!
Task0: Running...
Task0: Running...
Task0: Running...
timer_handler: 1
OS: Back to OS
 
OS: Activate next task
Task1: Created!
Task1: Running...
Task1: Running...
Task1: Running...
timer_handler: 2
OS: Back to OS
 
OS: Activate next task
Task0: Running...
Task0: Running...
Task0: Running...
timer_handler: 3
OS: Back to OS
 
OS: Activate next task Task1: Running...
Task1: Running...
Task1: Running...
timer_handler: 4
OS: Back to OS
 
OS: Activate next task
Task0: Running...
Task0: Running...
Task0: Running...
QEMU: Terminated


As we can see, system switches the context between OS, Task0, and Task1 during the execution This situation is very similar to the simulation of MultiTasking episode, where both of which have the following execution sequence.

    stateDiagram-v2
    direction LR
    State1 :OS
	State2 : Task0
	State3 : OS
	State4 :Task1
	State5 : OS
	State6 : Task0
	State7 : OS
	State8 : Task1
	
    State1 --> State2
	State2 --> State3
	State3 --> State4
	State4 --> State5
	State5 --> State6
	State6 --> State7
	State7 --> State8

The only difference is that the user process in MultiTasking episode must actively return control to the operating system through os_kernel().

void user_task0(void)
{
	lib_puts("Task0: Created!\n");
	lib_puts("Task0: Now, return to kernel mode\n");
	os_kernel();
	while (1) {
		lib_puts("Task0: Running...\n");
		lib_delay(1000);
		os_kernel();
	}
}

However, during this simulation, the user schedule does not need to be actively handed back to the OS, but the OS forces the switching action through time interruption.

void user_task0(void)
{
	lib_puts("Task0: Created!\n");
	while (1) {
		lib_puts("Task0: Running...\n");
		lib_delay(1000);
	}
}

The lib_delay in lib.c is actually a delay loop and does not return control.

void lib_delay(volatile int count)
{
	count *= 50000;
	while (count--);
}

On the contrary, the operating system will forcefully take back control through time interruption. (Because lib_delay has a long delay, the operating system usually interrupts its while (count--) loop to take back control)

OS Kernel

The operating system os.c will initially call user_init() to allow the user to create tasks (in this example, user_task0 and user_task1 will be created in user.c.

#include "os.h"

void user_task0(void)
{
	lib_puts("Task0: Created!\n");
	while (1) {
		lib_puts("Task0: Running...\n");
		lib_delay(1000);
	}
}

void user_task1(void)
{
	lib_puts("Task1: Created!\n");
	while (1) {
		lib_puts("Task1: Running...\n");
		lib_delay(1000);
	}
}

void user_init() {
	task_create(&user_task0);
	task_create(&user_task1);
}

Then the operating system will set the time interrupt through the timer_init() function in os_start(), and then enter the main loop of os_main(), which adopts Round-Robin scheduling. In Round robin scheduling each process is assigned a fixed time slice in a cyclic manner, ensuring fairness by giving each process equal time on the CPU regardless of its priority or execution time.

#include "os.h"

void os_kernel() {
	task_os();
}

void os_start() {
	lib_puts("OS start\n");
	user_init();
	timer_init(); // start timer interrupt ...
}

int os_main(void)
{
	os_start();

	int current_task = 0;
	while (1) {
		lib_puts("OS: Activate next task\n");
		task_go(current_task);
		lib_puts("OS: Back to OS\n");
		current_task = (current_task + 1) % taskTop; // Round Robin Scheduling
		lib_puts("\n");
	}
	return 0;
}

In the interrupt mechanism of sys.s, we modified the interrupt vector table as below.

.globl trap_vector
# the trap vector base address must always be aligned on a 4-byte boundary
.align 4
trap_vector:
	# save context(registers).
	csrrw	t6, mscratch, t6	# swap t6 and mscratch
        reg_save t6
	csrw	mscratch, t6
	# call the C trap handler in trap.c
	csrr	a0, mepc
	csrr	a1, mcause
	call	trap_handler

	# trap_handler will return the return address via a0.
	csrw	mepc, a0

	# load context(registers).
	csrr	t6, mscratch
	reg_load t6
	mret

Essentially what it does is when an interrupt occurs, the interrupt vector table trap_vector() will call trap_handler() in trap.c.

reg_t trap_handler(reg_t epc, reg_t cause)
{
  reg_t return_pc = epc;
  reg_t cause_code = cause & 0xfff;

  if (cause & 0x80000000)
  {
    /* Asynchronous trap - interrupt */
    switch (cause_code)
    {
    case 3:
      lib_puts("software interruption!\n");
      break;
    case 7:
      lib_puts("timer interruption!\n");
      // disable machine-mode timer interrupts.
      w_mie(~((~r_mie()) | (1 << 7)));
      timer_handler();
      return_pc = (reg_t)&os_kernel;
      // enable machine-mode timer interrupts.
      w_mie(r_mie() | MIE_MTIE);
      break;
    case 11:
      lib_puts("external interruption!\n");
      break;
    default:
      lib_puts("unknown async exception!\n");
      break;
    }
  }
  else
  {
    /* Synchronous trap - exception */
    lib_puts("Sync exceptions!\n");
    while (1)
    {
      /* code */
    }
  }
  return return_pc;
}

After jumping to trap_handler(), it will call different handlers for different types of interrupts, so we can think of it as an interrupt dispatch task relay station.

graph LR
    C[trap_handler] --> D[soft_handler]
    C --> E[timer_handler]
    C --> F[exter_handler]

trap_handler can hand over interrupt processing to different handlers according to different interrupt types. This can greatly improve the scalability of the operating system.

#include "timer.h"

// a scratch area per CPU for machine-mode timer interrupts.
reg_t timer_scratch[NCPU][5];

#define interval 20000000 // cycles; about 2 second in qemu.

void timer_init()
{
  // each CPU has a separate source of timer interrupts.
  int id = r_mhartid();

  // ask the CLINT for a timer interrupt.
  // int interval = 1000000; // cycles; about 1/10th second in qemu.

  *(reg_t *)CLINT_MTIMECMP(id) = *(reg_t *)CLINT_MTIME + interval;

  // prepare information in scratch[] for timervec.
  // scratch[0..2] : space for timervec to save registers.
  // scratch[3] : address of CLINT MTIMECMP register.
  // scratch[4] : desired interval (in cycles) between timer interrupts.
  reg_t *scratch = &timer_scratch[id][0];
  scratch[3] = CLINT_MTIMECMP(id);
  scratch[4] = interval;
  w_mscratch((reg_t)scratch);

  // enable machine-mode timer interrupts.
  w_mie(r_mie() | MIE_MTIE);
}

static int timer_count = 0;

void timer_handler()
{
  lib_printf("timer_handler: %d\n", ++timer_count);
  int id = r_mhartid();
  *(reg_t *)CLINT_MTIMECMP(id) = *(reg_t *)CLINT_MTIME + interval;
}

If you observe the function timer_handler() in timer.c, you can see that it invokes reset MTIMECMP.

/* In trap_handler() */
// ...
case 7:
      lib_puts("timer interruption!\n");
      // disable machine-mode timer interrupts.
      w_mie(~((~r_mie()) | (1 << 7)));
      timer_handler();
      return_pc = (reg_t)&os_kernel;
      // enable machine-mode timer interrupts.
      w_mie(r_mie() | MIE_MTIE);
      break;
// ...

In order to avoid interrupt nesting in Timer Interrupt, trap_handler() will close the timer interrupt before processing the interrupt, and then open it again after the processing is completed.

After timer_handler() is executed, trap_handler() will point mepc to os_kernel() to achieve the task switching function. In other words, if the interrupt does not belong to Timer Interrupt, the Program counter will jump back to the state before entering the interrupt. This step is defined in trap_vector() as below.

csrr	a0, mepc # a0 => arg1 (return_pc) of trap_handler()

Note In RISC-V, the parameters of the function will be first stored in the a0 - a7 registers. If the space is not enough, they will be stored in the Stack. Among them, the a0 and a1 registers also serve as function return values.

Finally, we import the trap and timer initialization actions when the Kernel is started as illustrated below.

void os_start()
{
	lib_puts("OS start\n");
	user_init();
	trap_init();
	timer_init(); // start timer interrupt ...
}

By forcibly taking back control through time interruption, we don’t have to worry about a bully schedule taking over the CPU, and the system will not be stuck by the bully and completely paralyzed. This is the most important “schedule management mechanism” in modern operating systems.

Remarks

Although TinyOS is just a “tiny” embedded operating system, it still demonstrates the design principle of a specific and simple “preemptible operating system” through relatively streamlined code.

Of course, there is still a long way to go to learn “Operating System Design”. In particular, TinyOS does not have a “File System”, and we haven’t even touched on the areas related to control and switching methods of supervisor mode and user mode in RISC-V. Further, OS needs to handle virtual memory mechanisms, so that processes cannot steal other process’s data.

Fortunately, you can learn more about these more complex mechanisms by studying xv6-riscv, a teaching operating system designed by MIT. The source code of xv6-riscv has a total of more than 8,000 lines, although not too few, xv6-riscv is a very streamlined system compared to modern Linux and Windows, which can run from millions to tens of millions of lines.

I hope this episode of TinyOS tutorial series gave you the basic understanging about how the preemptive multitasking is working on RISC-V environment. In the next episode let’s discuss about Spinlocks in RISC-V.

Cooperative Multitasking

Modern operating systems have a Preemptive function that forcibly terminates the process through timed interruption, so that when a certain process occupies the CPU for too long, it is forcibly interrupted and switched to another process for execution.

However, in a system without a time interruption mechanism, the operating system cannot interrupt the current execution process, so it must rely on each process to actively return control to the operating system in order to allow all processes to have a chance to execute. This notion of multi-tasking system that relies on an automatic return mechanism is called a Coorperative Multitasking system. Windows 3.1 launched by Microsoft in 1991, Macintosh OS version 8.0-9.2, as well as HeliOS for Arduino MCU, are all operating systems that employee cooperative multitasking mechanisms.

As an illustration step in our TinyOS series, in this chapter, we will design a cooperative multitasking mechanism on a RISC-V processor.

Simulation

First let’s execute the program. For this you can navigate to the MultiTasking folder of the cloned repository from the docker image. If you missed the first article about setting up the environment, you can check it from here.

First let’s take a look at the system’s performance.

cd tinyos/03-MultiTasking
make qemu

Press Ctrl-A and then X to exit QEMU
qemu-system-riscv32 -nographic -smp 4 -machine virt -bios none -kernel os.elf
OS start
OS: Activate next task
Task0: Created!
Task0: Now, return to kernel mode
OS: Back to OS
 
OS: Activate next task
Task1: Created!
Task1: Now, return to kernel mode
OS: Back to OS
 
OS: Activate next task
Task0: Running...
OS: Back to OS
 
OS: Activate next task
Task1: Running...
OS: Back to OS
 
OS: Activate next task
Task0: Running...
OS: Back to OS
 
OS: Activate next task
Task1: Running...
OS: Back to OS
 
OS: Activate next task
Task0: Running...
OS: Back to OS
 
OS: Activate next task
Task1: Running...
OS: Back to OS
 
OS: Activate next task
Task0: Running...
QEMU: Terminated


You can see that the system keeps switching between two tasks Task0, Task1, but the actual switching process is as follows:

    stateDiagram-v2
    direction LR
    State1 :OS
	State2 : Task0
	State3 : OS
	State4 :Task1
	State5 : OS
	State6 : Task0
	State7 : OS
	State8 : Task1
	
    State1 --> State2
	State2 --> State3
	State3 --> State4
	State4 --> State5
	State5 --> State6
	State6 --> State7
	State7 --> State8

Operating system needs cordinate the two task to execute sequancially. In this episode, we will looking at the underlying logic of this implementation.

User Tasks

In user.c, we define two tasks, user_task0 and user_task1, and finally initialize these two tasks in the user_init function.

// user.c
#include "os.h"

void user_task0(void)
{
	lib_puts("Task0: Created!\n");
	lib_puts("Task0: Now, return to kernel mode\n");
	os_kernel();
	while (1) {
		lib_puts("Task0: Running...\n");
		lib_delay(1000);
		os_kernel();
	}
}

void user_task1(void)
{
	lib_puts("Task1: Created!\n");
	lib_puts("Task1: Now, return to kernel mode\n");
	os_kernel();
	while (1) {
		lib_puts("Task1: Running...\n");
		lib_delay(1000);
		os_kernel();
	}
}

void user_init() {
	task_create(&user_task0);
	task_create(&user_task1);
}

OS Kernel

Then, in the main program os.c of the operating system, we use a while loop to arrange each process to be executed sequentially.

// os.c
#include "os.h"

void os_kernel() {
	task_os();
}

void os_start() {
	lib_puts("OS start\n");
	user_init();
}

int os_main(void)
{
	os_start();
	
	int current_task = 0;
	while (1) {
		lib_puts("OS: Activate next task\n");
		task_go(current_task);
		lib_puts("OS: Back to OS\n");
		current_task = (current_task + 1) % taskTop; // Round Robin Scheduling
		lib_puts("\n");
	}
	return 0;
}

The above scheduling method is in principle consistent with Round Robin Scheduling, but Round Robin Scheduling must be equipped with a timed interruption mechanism in principle, but the code in this episode has no timed interruptions, so it can only be said to be the Round Robin Scheduling of the collaborative multitasking version.

Cooperative multitasking must rely on each task to actively return control. For example, in user_task0, whenever the os_kernel() function is called, the context switching mechanism will be called to return control to the operating system.

void user_task0(void)
{
	lib_puts("Task0: Created!\n");
	lib_puts("Task0: Now, return to kernel mode\n");
	os_kernel();
	while (1) {
		lib_puts("Task0: Running...\n");
		lib_delay(1000);
		os_kernel();
	}
}

The os_kernel() function of os.c will call the task_os() of task.c

void os_kernel() {
	task_os();
}

And task_os() will call sys_switch in assembly language sys.s to switch back to the operating system.

// switch back to os
void task_os() {
	struct context *ctx = ctx_now;
	ctx_now = &ctx_os;
	sys_switch(ctx, &ctx_os);
}

So the whole system is executed in turn letting the other process to execute under the cooperation of os_main(), user_task0(), user_task1().

os_main() function in os.c looks like this.

int os_main(void)
{
	os_start();
	
	int current_task = 0;
	while (1) {
		lib_puts("OS: Activate next task\n");
		task_go(current_task);
		lib_puts("OS: Back to OS\n");
		current_task = (current_task + 1) % taskTop; // Round Robin Scheduling
		lib_puts("\n");
	}
	return 0;
}

user_task0() and user_task1() functions in user.c looks like this.

void user_task0(void)
{
	lib_puts("Task0: Created!\n");
	lib_puts("Task0: Now, return to kernel mode\n");
	os_kernel();
	while (1) {
		lib_puts("Task0: Running...\n");
		lib_delay(1000);
		os_kernel();
	}
}

void user_task1(void)
{
	lib_puts("Task1: Created!\n");
	lib_puts("Task1: Now, return to kernel mode\n");
	os_kernel();
	while (1) {
		lib_puts("Task1: Running...\n");
		lib_delay(1000);
		os_kernel();
	}
}

The above is an example of a specific and micro cooperative multitasking system on the RISC-V processor. In the next episode of TinyOS🐞, let’s look at implementation of TimerIntterupts.

This episode will lay the foundation for a “Preemptive Multitasking System” by introducing the utilization of the “Time Interrupt Mechanism” in RISC-V processors. Through time interrupts, we gain the ability to regain control at predefined intervals, ensuring that a third-party application cannot indefinitely seize control of the system without yielding control back to the operating system.

Main Concepts for TimerInterrupts

Before learning how the system implements the time interruption mechanism, we must first understand a few things:

• Generating Timer Interrupts
• Interrupt Vector Table
• Control and Status Registers (CSR)

Lets go throgh each of the concept one by one.

Generating Timer Interrupts

The RISC-V architecture specifies that the system platform must include a timer, and this timer must feature two 64-bit registers: mtime and mtimecmp. The purpose of these registers is as follows:

1. mtime (Machine Time): This register is utilized to keep track of the current counter value of the timer. It serves as a continuously incrementing counter, recording the passage of time in the system.

2. mtimecmp (Machine Time Compare): The mtimecmp register is employed to set a comparison value against which the value of mtime is compared. When the value of mtime becomes greater than the value stored in mtimecmp, an interrupt is triggered.

These registers are integral for implementing time-based interrupt handling in RISC-V systems. By comparing mtime with the value stored in mtimecmp, the system can generate interrupts at specific time intervals, facilitating various timing-related tasks and enabling features such as preemptive multitasking and real-time scheduling. You can find the definitions for these two registers in riscv.h:

After understanding the mechanism for generating a Timer interrupt, we will examine a piece of code that defines the time interval (Interval) for each interrupt trigger in the upcoming explanation.

// ================== Timer Interrput ====================

#define NCPU 8             // maximum number of CPUs
#define CLINT 0x2000000
#define CLINT_MTIMECMP(hartid) (CLINT + 0x4000 + 4*(hartid))
#define CLINT_MTIME (CLINT + 0xBFF8) // cycles since boot.

Additionally, during system initialization, it’s essential to enable the Timer interrupt. This can be achieved by setting the corresponding field in the mie (Machine Interrupt Enable) register to 1.

What is the Interrupt Vector Table?

The interrupt vector table is a data structure managed by the system program. It serves as a mapping between interrupt numbers or types and their corresponding interrupt handlers. When a specific interrupt or exception occurs, the system will look up the corresponding Interrupt Handler in this table.

Here’s how it works:

1. When an interrupt, such as a time interrupt, occurs, the processor first stops executing the current program’s instructions.

2. It then looks up the interrupt or exception type in the interrupt vector table to find the associated Interrupt_Handler.

3. The processor transfers control to the Interrupt_Handler, which is a predefined piece of code responsible for handling that specific type of interrupt or exception.

4. The Interrupt_Handler performs the necessary processing, which may include saving the current context, handling the interrupt’s specific tasks, and eventually returning control to the interrupted program.

5. After completing the handling of the interrupt, the processor jumps back to the original instruction address in the interrupted program, allowing it to continue execution as if the interrupt never occurred.

This mechanism is essential for managing and responding to various interrupts and exceptions in a systematic and controlled manner, ensuring that the system remains stable and responsive. The interrupt vector table plays a crucial role in facilitating this process by directing the processor to the appropriate interrupt handling routines.

Note: When an exception or interrupt occurs, the processor will stop the current process, point the address of the Program counter to the address pointed by mtvec and start execution. Such behavior is like actively jumping into a trap. Therefore, this action is defined as Trap in the RISC-V architecture. In the xv6 (risc-v) operating system, we can also find a series of Operations to handle Interrupt (mostly defined in Trap.c).

Control and Status Registers (CSR)

The RISC-V architecture encompasses numerous registers, including a category known as Control and Status Registers (CSRs), as highlighted in the title. CSRs serve the crucial role of configuring and recording the processor’s operational status.

• CSR (Control and Status Registers):

  • mtvec: This register specifies the address that the Program Counter (PC) will jump to when an exception occurs, allowing exception handling to begin.
  • mcause: It records the reason for encountering an exception or anomaly.
  • mtval: This register is used to store additional information or messages related to the encountered exception.
  • mepc: Before entering an exception, it holds the address pointed to by the PC, which can be read to resume execution after handling the exception.
  • mstatus: This register’s fields are updated by hardware when an exception is entered, reflecting various status changes.
  • mie: It determines whether interrupts are enabled or disabled.
  • mip: This register indicates the pending status of different types of interrupts.

• Memory Address Mapped:

  • mtime: Records the current value of the timer.
  • mtimecmp: Stores a comparison value for the timer, against which mtime is compared to generate timer interrupts.
  • msip: Used for generating or clearing software interrupts.
  • Platform-Level Interrupt Controller (PLIC): This external hardware component handles and manages interrupts from various sources and devices in the system, ensuring that they are appropriately routed to the processor for handling.

In addition, RISC-V defines a series of instructions that allow developers to operate the CSR register:

• csrs: Set the specified bit in the CSR to 1.

csrsi mstatus, (1 << 2)

The above command will set the third position of mstatus from the LSB to 1.

• csrc Set the specified bit in the CSR to 0.

csrsi mstatus, (1 << 2)

The above instruction will set the third position of mstatus from the LSB to 0.

• csrr[c|s] Read the value of CSR into the general scratchpad.

csrr to, mscratch

• csrw Write the value of the general scratchpad to the CSR.

csrw mepc, a0

• csrrw[i] Write the value of csr to rd and the value of rs1 to csr .

csrrw rd, csr, rs1/imm

Think about it from another perspective:

csrrw t6, mscratch, t6

The above operation can interchange the values ​​of register t6 and mscratch.

Simulation

You can clone the tinyos repository if you havent already. If you missed the introduction episode of this series, you can check it out from here. Then from the docker environment, navegate to 04-TimerInterrupt folder on the mounted repo. After you use make clean, make and other commands to build the project, you can use make qemu to start simulation. The results are as follows:

make

riscv32-unknown-elf-gcc -nostdlib -fno-builtin -mcmodel=medany -march=rv32ima -mabi=ilp32 -T os.ld -o os.elf start.s sys.s lib.c timer.c os.c

makeqemu

Press Ctrl-A and then X to exit QEMU
qemu-system-riscv32 -nographic -smp 4 -machine virt -bios none -kernel os.elf
OS start
timer_handler: 1
timer_handler: 2
timer_handler: 3
timer_handler: 4
timer_handler: 5
timer_handler: 6
timer_handler: 7
timer_handler: 8
timer_handler: 9


The system will consistantly print out a message like timer_handler: i about once per second, which means that the time interrupt mechanism is successfully started and interrupts are performed regularly.

Discussion

Before explaining time interruption, let us first take a look at the contents of the operating system main program os.c.

#include "os.h"

int os_main(void)
{
lib_puts("OS start\n");
timer_init(); // start timer interrupt ...
while (1) {} // os : do nothing, just loop!
return 0;
}

Basically, after this program prints OS start, it starts the time interrupt, and then enters the os_loop() infinite loop function and gets stuck.

But why does the system print a message like timer_handler: i later?

timer_handler: 1
timer_handler: 2
timer_handler: 3

This is of course caused by the time interruption mechanism!

Let’s take a look at the contents of timer.c. Please pay special attention to the line w_mtvec((reg_t)sys_timer). When a time interrupt occurs, the program will jump to the sys_timer macro in sys.s.

#include "timer.h"

#define interval 10000000 // cycles; about 1 second in qemu.

void timer_init()
{
  // each CPU has a separate source of timer interrupts.
  int id = r_mhartid();

  // ask the CLINT for a timer interrupt.
  *(reg_t*)CLINT_MTIMECMP(id) = *(reg_t*)CLINT_MTIME + interval;

  // set the machine-mode trap handler.
  w_mtvec((reg_t)sys_timer);

  // enable machine-mode interrupts.
  w_mstatus(r_mstatus() | MSTATUS_MIE);

  // enable machine-mode timer interrupts.
  w_mie(r_mie() | MIE_MTIE);
}

The sys_timer function in sys.s will use the csrr privileged instruction to temporarily store the mepc privileged register (the address that stores the interrupt point) in a0 for storage. After timer_handler() is executed, it can do a mret return to the interruption point.

sys_timer:
	# call the C timer_handler(reg_t epc, reg_t cause)
	csrr	a0, mepc
	csrr	a1, mcause
	call	timer_handler

	# timer_handler will return the return address via a0.
	csrw	mepc, a0

	mret # back to interrupt location (pc=mepc)

Note that RISC-V defines three execution modes in their privilage level extention, namely “machine mode, super mode and user mode”.

All TinyOS tutorials are executed in machine mode, and super mode (user mode is not used).

mepc means that when an interrupt occurs in machine mode, the hardware will automatically execute the action of mepc=pc.

When sys_timer executes mret, the hardware will execute the action of pc=mepc, and then jump back to the original interruption point to continue execution. (As if nothing happened)

I’ve provided a basic overview of the RISC-V interrupt mechanism. However, to gain a deeper understanding of the process, it’s crucial to understand the machine mode-related privilege registers of the RISC-V processor, including mhartid (processor core identifier), mstatus (status register), mie (interrupt enable register), and more.

#define interval 10000000 // cycles; about 1 second in qemu.

void timer_init()
{
  // each CPU has a separate source of timer interrupts.
  int id = r_mhartid();

  // ask the CLINT for a timer interrupt.
  *(reg_t*)CLINT_MTIMECMP(id) = *(reg_t*)CLINT_MTIME + interval;

  // set the machine-mode trap handler.
  w_mtvec((reg_t)sys_timer);

  // enable machine-mode interrupts.
  w_mstatus(r_mstatus() | MSTATUS_MIE);

  // enable machine-mode timer interrupts.
  w_mie(r_mie() | MIE_MTIE);
}

In addition, it is required to understand the memory mapping area in the RISC-V QEMU virtual machine, such as CLINT_MTIME, CLINT_MTIMECMP, etc.

The time interrupt mechanism of RISC-V is to compare the two values ​​​​of CLINT_MTIME and CLINT_MTIMECMP. When CLINT_MTIME exceeds CLINT_MTIMECMP, an interrupt occurs.

Therefore, the timer_init() function has the following instructions

 *(reg_t*)CLINT_MTIMECMP(id) = *(reg_t*)CLINT_MTIME + interval;

This command is to set the first interruption time.

Similarly, in timer_handler of timer.c, you also need to set the next interrupt time as illustrated in below code.

reg_t timer_handler(reg_t epc, reg_t cause)
{
  reg_t return_pc = epc;
  // disable machine-mode timer interrupts.
  w_mie(~((~r_mie()) | (1 << 7)));
  lib_printf("timer_handler: %d\n", ++timer_count);
  int id = r_mhartid();
  *(reg_t *)CLINT_MTIMECMP(id) = *(reg_t *)CLINT_MTIME + interval;
  // enable machine-mode timer interrupts.
  w_mie(r_mie() | MIE_MTIE);
  return return_pc;
}

In this way, the next time the CLINT_MTIMECMP time comes, CLINT_MTIME will be greater than CLINT_MTIMECMP, and the interrupt will occur again.

In this episode of TinyOS, we looked the process of generating TimerInterrupts. This is a huge increment of the process of implementing preemptive muti tasking. In the Next episode, we will be specifically looking at that!