Replace OSTEP-projects with projects from the UW-Madison GitLab (#33)

luccaflower · web-flow · commit c66b1df55556 · 2026-01-21T10:21:06.000+05:30
* Introduce UW-Madison GitLab and replace filesystem project

* Introduce trial projects

Remove legacy projects from the project table. Move project details to project directory section.

* Massive rework of projects

* Fix path

* Path to STCF-scheduler page does not include xv6

* Fill out mmap url in xv6 vm intro page

* Replace broken anchors with urls

* What the hell lol
diff --git a/docs/computer-science/systems/ostep/Initial-xv6.md b/docs/computer-science/systems/ostep/Initial-xv6.md
@@ -1,7 +1,10 @@
-# Project 1B
+# Intro to xv6
 
 ### all thanks to [palladian](https://github.com/palladian1)
 
+- [Project details](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/initial-xv6)
+- [Discussion](https://www.youtube.com/watch?v=vR6z2QGcoo8)
+
 ### Linux Installation
 
 * Make sure you have a compatible compiler toolchain; if you're on Linux, gcc should work perfectly.
diff --git a/docs/computer-science/systems/ostep/Kernel-Threads-xv6.md b/docs/computer-science/systems/ostep/Kernel-Threads-xv6.md
@@ -0,0 +1,29 @@
+# Kernel Threads xv6
+**Note:** This project does not include any tests, and as a result we have decided to mark it as *optional*. We still believe it to be highly educational to complete this project, so we have provided instructions on how one might test their own implementation in the hints section.
+
+- [Project details](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/concurrency-xv6-threads)
+- [Discussion](https://www.youtube.com/watch?v=G9nW9UbkT7s)
+
+
+## Hints
+The discussion provides some critical information about x86 calling conventions and how to manipulate the stack that you *will* need in order to complete this project.
+
+The kernel stack referred to in the project description does not refer to the user stack that gets allocated on the heap. It refers to the special stack managed by the kernel to save and load the process context. What changes need to be made here in order to run the thread?
+
+When a newly created process runs for the first time, it first returns to a special routine called "forkret" which releases the lock held on the process table before finally returning to the user program. The allocproc-routine takes care of setting up the process to do this. If your process does not enter forkret, then you will cause a kernel panic.
+
+Remember that the user stack grows from top to bottom, and that the pointer you get from malloc points to the bottom. Make sure the sp-register points to the top.
+
+As of December 2025 this project does not have any tests to verify your work, so you will have to create that yourself. We suggest the creating verification steps for the following:
+1. Thread implementation  
+   - Verify that the cloned actually runs the supplied function.
+   - Verify that it shares memory with its parent
+   - Verify that the supplied stack-address gets returned by the subsequent join
+   - Verify that if a thread doesn't call exit, it returns to 0xffffffff, causing a kernel trap, as opposed to the function that created the thread.
+2. Lock
+   - Create a race condition and verify that it actually triggers
+   - Verify that the lock protects against the race condition
+
+The thread implementation itself should be straightforward to verify as it can be done by simply setting some variables and comparing them after a join. The tricky part is the race condition. You might be tempted to recreate the multi-threaded loop-counting example from the book, however, it turns out that it can be very difficult to make that race condition trigger at all. We believe this is a quirk of running xv6 inside QEMU.
+
+Instead, we recommend having a critical section of code that invokes multiple system calls. This guarantees interrupts, increasing the likelyhood of race conditions causing problems. A good candidate is printf. The xv6 implementation of printf invokes a write-syscall of a single byte for each printed character. Thus, if you use printf concurrently across multiple threads, there is a high chance that the terminal output gets garbled, unless you hold a working mutex lock for the duration of the printf-call. 
diff --git a/docs/computer-science/systems/ostep/Lottery-Scheduler-xv6.md b/docs/computer-science/systems/ostep/Lottery-Scheduler-xv6.md
@@ -1,8 +1,13 @@
-# Scheduling xv6 Lottery
+# Lottery Scheduler xv6
+**Legacy Project:** this project has been replaced by the [STCF Scheduler](../STCF-Scheduler) project.
 
-## all thanks to [palladian](https://github.com/palladian1)
 
-### General Tips
+- [Project details](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/scheduling-xv6-lottery)
+- [Discussion](https://www.youtube.com/watch?v=eYfeOT1QYmg)
+
+all thanks to [palladian](https://github.com/palladian1)
+
+## General Tips
 
 * Read chapter 9 in the OSTEP book and watch the video for discussion 5. Lottery ticket schedulers aren't discussed in the lectures, so you really do have to read the book for this one.
 
diff --git a/docs/computer-science/systems/ostep/MapReduce.md b/docs/computer-science/systems/ostep/MapReduce.md
@@ -0,0 +1,11 @@
+# MapReduce
+**Note:** This project currently does not contain any tests. A ZIP-file containing several test cases and a makefile + example C-program to run them has been uploaded to the Discord server. At some point in the future we will get it refined and published on GitHub.
+- [Project details](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/concurrency-mapreduce)
+- [Discussion](https://youtu.be/tSiJ_oBSOZE?t=34)
+- [Q/A](https://www.youtube.com/watch?v=jVmWrr8y0Uw)
+
+## Hints
+- This project is quite challenging, so don't get discouraged if you're struggling. If you find that the difficulty curve gets too steep, consider doing the [Parallel Zip](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/concurrency-pzip) project first. Use the test-files in the initial utilities zip project to check your work.
+- For this project it is highly advantageous to work in small increments: focus on making a correct sequential implementation first, and then think about how you can parallelize it. 
+- The producer-consumer queue using locks and condition variables is your central data structure for parallelizing work. It is described in detail in the chapter on **Condition Variables**.
+- Remember to make copies of the keys and values passed to your `MR_Emit` implementation, otherwise you'll end up with a heap of garbage. 
diff --git a/docs/computer-science/systems/ostep/Memory-Mapping-xv6.md b/docs/computer-science/systems/ostep/Memory-Mapping-xv6.md
@@ -0,0 +1,14 @@
+# Memory Mapping xv6
+**Trial project**: This project is currently being tried as a replacement for the xv6 virtual memory project. If you wish to do the old project instead, click [here](../Virtual-Memory-Intro-xv6).
+
+- [Project repository](https://git.doit.wisc.edu/cdis/cs/courses/cs537/fall24/public/p5)
+
+## Instructions
+1. Git clone the project repository.
+2. Read the instructions provided in the README.md file.
+3. Implement your solution in the `solution`-directory.
+4. Run the `runtests.py` script located in the `tests` directory to evaluate your work.
+
+### Hints
+- For this project you will need to have finished the **Virtual Memory** chapters of the OSTEP textbook.
+- Pay particular attention to the chapters on **Address Translation**, **Segmentation**, and **Paging**.
diff --git a/docs/computer-science/systems/ostep/Mini-WFS.md b/docs/computer-science/systems/ostep/Mini-WFS.md
@@ -0,0 +1,26 @@
+# Mini-WFS
+
+- [Project repository](https://git.doit.wisc.edu/cdis/cs/courses/cs537/fall25/p6/p6-base)
+
+In this project you will implement a basic filesystem in userspace (FUSE) not unlike the Very Simple Filesystem described in the book.
+
+## Instructions
+- Git clone the project repository
+- Follow the instructions in the README.md file.
+- Implement your solution in the solution directory.
+- Run the `run-tests.sh` script located in the `tests`-directory to check your work.
+
+#### Hints
+- This may be the most substantial project in the entire course. It is a lot of work, but in the process you will learn not just about file systems but about the FUSE framework as well, which is used in a lot of places.
+- Part 1 represents roughly 90% of the work, so don't get discouraged if you've been at it for a week and you're still "only at part 1". Part 1 is "working filesystem", and that is a big deal in its own right.
+- Work in increments. Start with the `wfs_getattr` callback and work your way down from there. If you're in doubt about what to do next, run the tests and start with the first test-failure you encounter.
+- The starter files include a bunch of useful helpers that you should use:
+  - `allocate_block`: takes a bitmap array and an array length, flips the next free bit, and returns its number. This works for both the inode and data bitmaps.
+  - `fillin_inode`: initializes the provided inode. Use this for any newly allocated inodes. 
+  - `wfs_color_from_code`: returns a color name and ansi-espace sequences for the provided color code.
+  - `parse_color_name`: takes a color name string and sets the `out_code` parameter to the parsed color code. BEWARE: this function returns `1` on success and ` 0` on failure. Check the return value. 
+- The VSFS described in the Filesystem Implementation chapter has directory entries for `.` and `..` in the data blocks for each directory inode. **You should not do this. You will get test failures**. Only start allocating data blocks for the directory inode when you start adding files and directories to it.
+- Think about how to handle direct versus indirect blocks. How do you determine when to use one over the other. What information do you have available to determine that. Do you need some sort of transition case?
+- Directory inodes need certain mode bits to be set on creation, and these will not be set by the `mode` argument passed to the callback. You can set them by setting the mode field on the inode to `mode | S_IFDIR`.
+- The "Read test for prebuilt image" test (test 25) is likely to fail due to incompatibilities between your memory layout and theirs. Feel free to skip this test in particular.
+- The timestamp tests appear to be buggy and pass no matter what. You should still implement the timestamp updates.
diff --git a/docs/computer-science/systems/ostep/STCF-Scheduler.md b/docs/computer-science/systems/ostep/STCF-Scheduler.md
@@ -0,0 +1,14 @@
+# STCF-Scheduler xv6
+
+**Trial project**: This project is currently being tried as a replacement for the xv6 lottery scheduler project. If you wish to do the old project instead, click [here](../Lottery-Scheduler-xv6).
+- [Project repository](https://git.doit.wisc.edu/cdis/cs/courses/cs537/fall25/p3/p3-base)
+
+## Instructions
+- Git clone the project repository
+- Follow the instructions in the README.md file.
+- Implement your solution in the solution directory.
+- Run the `run-tests.sh` script located in the `tests`-directory to check your work.
+
+## Hints
+- This project is very similar to the old [Lottery Scheduler](../Lottery-Scheduler-xv6) project.
+- Read the hints and watch the discussion video for that project to get an idea of how to implement this project.
diff --git a/docs/computer-science/systems/ostep/Unix-Shell.md b/docs/computer-science/systems/ostep/Unix-Shell.md
@@ -1,14 +1,9 @@
-# Project 2A
+# Unix Shell
 
 ### all thanks to [Palladian](https://github.com/palladian1/)
 
-- [x] Interactive mode
-- [x] Batch mode
-- [x] exit
-- [x] cd
-- [x] path
-- [x] Redirection
-- [x] Parallel commands
+- [Project Details](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/processes-shell)
+- [Discussion](https://youtu.be/76PfvXTwF04)
 
 ### Tips
 
diff --git a/docs/computer-science/systems/ostep/Unix-Utilities.md b/docs/computer-science/systems/ostep/Unix-Utilities.md
@@ -0,0 +1,13 @@
+# Unix Utilities
+
+- [Project description](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/initial-utilities)
+- [Discussion](https://youtu.be/rgcq9x8LtGQ)
+
+## Instructions
+1. Git clone the ostep-projects repository if you haven't already.
+2. Navigate to the initial-utilities directory.
+3. Follow the instructions in the README.md file.
+
+### Hints
+- This project is meant as a litmus-test for your proficiency at programming in C. It covers the very basics of being able to write useful programs. If you're struggling with this assignment, it may be a sign for you to take a step back, and get some more experience with C, as things will only get harder from here on out.
+- If you still feel you need more C practice after completing this project, we recommend doing the [intial reverse](https://github.com/luccaflower/ostep-projects/tree/master/initial-reverse) project. But be mindful: The error messages that are needed to pass the tests are wrong! The provided text say `"error: ..."` but the tests expect `"reverse: ..."` so make sure to match the tests' expectations in your code.
diff --git a/docs/computer-science/systems/ostep/Virtual-Memory-Intro-xv6.md b/docs/computer-science/systems/ostep/Virtual-Memory-Intro-xv6.md
@@ -1,10 +1,15 @@
-
-# Intro To xv6 Virtual Memory
+# Virtual Memory Intro xv6
+**This is a legacy project which has been replaced by the [Memory Mapping xv6 Project](../Memory-Mapping-xv6).**
 
 Credit goes to [palladian](https://github.com/palladian1)
 
+- [Project details](https://github.com/remzi-arpacidusseau/ostep-projects/tree/master/vm-xv6-intro)
+- [Discussion 1](https://youtu.be/z6dqk6iBBRY?t=1305)
+- [Discussion 2](https://www.youtube.com/watch?v=WVHRaqom0y)
+
 ### WARNING:
 
+
 ***The project doesn't match the currently available xv6 source code, which already has this project implemented in it!***
 
 [palladian](https://github.com/palladian1) tracked down a different xv6 source from the Github page of a U of Wisconsin student. We had to edit the `Makefile` to find the QEMU executable correctly. We added `null.c` to the `user` folder (also edited `makefile.mk` there), which demonstrates the lack of memory safety.
diff --git a/docs/computer-science/systems/ostep/index.md b/docs/computer-science/systems/ostep/index.md
