DOCSITE: Reorganise tutorials and add inline solutions

Hardware/Beaglebone.md

@@ -27,7 +27,7 @@ a community-supported port.
 
 ### Requirements
 We suggest using the `arm-linux-gnueabi-` cross-compilers. Use
-[the instructions on getting a toolchain](/GettingStarted#getting-cross-compilers).
+[the instructions on getting a toolchain](/Resources#getting-cross-compilers).
 
 ### Building
 

Hardware/HiKey/index.md

@@ -23,7 +23,7 @@ SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 - One HiKey Board. See
         [Hikey 96Board](http://www.96boards.org/products/ce/hikey/)
 - Fully working development environment. See
-        [Getting started](/GettingStarted)
+        [Resources](/Resources)
 
 ### Getting Started
  The Hikey board is based around the
@@ -87,12 +87,12 @@ gedit LinaroPkg/platforms.config
 BUILDFLAGS=-DSERIAL_BASE=0xF8015000
 ATF_BUILDFLAGS=CONSOLE_BASE=PL011_UART0_BASE CRASH_CONSOLE_BASE=PL011_UART0_BASE
 ```
-## 5. Patching the UEFI for the Hikey 
+## 5. Patching the UEFI for the Hikey
 Obtain the patch from [edk2.patch](edk2.patch) and follow the below steps.
 
 ```bash
-cd linaro-edk2 
-patch -p1 < ~/Downloads/edk2.patch 
+cd linaro-edk2
+patch -p1 < ~/Downloads/edk2.patch
 # Then return to the main directory hikey-flash
 ```
 
@@ -206,8 +206,8 @@ sudo minicom -s
   7.  Three terminals are then required for the following commands
 
 ```bash
-# In the first terminal 
-ls 
+# In the first terminal
+ls
 # Note the next ttyUSBY that is observed, in addition to the current ttyUSBX
 
 # In the third terminal

Hardware/IA32.md

@@ -29,7 +29,7 @@ menuentry "Load seL4 VM" --class os {
     insmod part_msdos
     insmod ext2
     set root='(hd0,msdos2)'
-    multiboot /boot/sel4kernel
+    multiboot /boot/seL4
     module /boot/sel4rootserver
 }
 ```
@@ -59,13 +59,13 @@ install-mbr /dev/sdb
 syslinux --install /dev/sdb1
 mount /dev/sdb1 /mnt
 cp images/sel4test-driver-image-ia32-pc99 /mnt/rootserver
-cp images/kernel-ia32-pc99 /mnt/sel4kernel
+cp images/kernel-ia32-pc99 /mnt/seL4
 cat > /mnt/syslinux.cfg <<EOF
 SERIAL 0 115200
 DEFAULT seL4test
 LABEL seL4test
     kernel mboot.c32
-    append sel4kernel --- rootserver
+    append seL4 --- rootserver
 EOF
 cp /usr/lib/syslinux/modules/bios/mboot.c32 /mnt
 cp /usr/lib/syslinux/modules/bios/libcom32.c32 /mnt

Hardware/VMware/index.md

@@ -14,7 +14,7 @@ and for a Linux host machine. May work on Mac host machine, won't work
 for Windows host (although general idea should be similar).
 
 This guide assumes that your project is all set up and configured to
-build for x86. Read [Getting started](/GettingStarted) otherwise.
+build for x86. Read [Resources](/Resources) otherwise.
 
 ## Setting up a VM
 
@@ -55,7 +55,7 @@ There are three options for the serial port
 set up). You'll want to apt-get install socat and then run something
 like:
 ```bash
-#!/bin/bash 
+#!/bin/bash
 while true; do
     socat -d -d UNIX-CONNECT:/tmp/vsock,forever PTY:link=/dev/tty99
 done

Hardware/jetsontk1.md

@@ -20,10 +20,10 @@ SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 
 The [Jetson TK1](http://www.nvidia.com/object/jetson-tk1-embedded-dev-kit.html) is a affordable embedded system developed by NVIDIA. It runs
 seL4. We will explain how to run seL4 on the Tegra.
- 
+
 ### Pre-Requisites
 * One Tegra Board. See [Jetson TK1](http://www.nvidia.com/object/jetson-tk1-embedded-dev-kit.html)
-* The development environment fully working.  See [Getting started](/GettingStarted)
+* The development environment fully working.  See [Resources](/Resources)
 
 ## Getting Started
  To get started, check out the
@@ -94,7 +94,7 @@ to boot in nonsecure (HYP)
 mode. This also enables kvm if you boot Linux.
 
 To go back to secure mode booting do
-``` 
+```
 setenv bootm_boot_mode sec
 saveenv
 ```

Makefile

@@ -1,7 +1,7 @@
 # Copyright 2020 seL4 Project a Series of LF Projects, LLC.
 # SPDX-License-Identifier: BSD-2-Clause
 
-default: serve
+default: serve --trace
 
 .PHONY: ruby_deps
 ruby_deps: Gemfile Gemfile.lock
@@ -51,7 +51,7 @@ _repos/tutes:
 _repos/tutes/%.md: _repos/sel4proj/sel4-tutorials/tutorials/% _repos/tutes
 	PYTHONPATH=_repos/sel4/capdl/python-capdl-tool _repos/sel4proj/sel4-tutorials/template.py --docsite --out-dir _repos/tutes --tut-file $</$(@F)
 
-TUTORIALS:= $(filter-out index.md,$(notdir $(wildcard Tutorials/*.md)))
+TUTORIALS:= $(filter-out index.md get-the-tutorials.md how-to.md pathways.md sel4-overview.md setting-up.md,$(notdir $(wildcard Tutorials/*.md)))
 tutorials: ${TUTORIALS:%=_repos/tutes/%}
 
 _generate_api_pages: $(REPOSITORIES)

GettingStarted.md → Resources.md

@@ -5,9 +5,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 
-# Getting Started
+# Resources
 
-This page is a quick start for working with seL4 and its ecosystem.
+This page provides an overview on working with seL4 and its ecosystem.
 
 ## Background and terminology
 
@@ -168,7 +168,12 @@ You can find a long list of seL4 publications here:
 - [seL4 is free: What does this mean for you? (2015)](https://www.youtube.com/watch?v=lRndE7rSXiI).
 - [From L3 to seL4: What have we learned in 20 years of L4 microkernels? (2014)](https://www.youtube.com/watch?v=RdoaFc5-1Rk).
 
-## Get Help
+## Contact
+
+### Forums
+
+- [Discourse forum](https://sel4.discourse.group/)
+- [Mattermost channel](https://mattermost.trustworthy.systems/sel4-external/)
 
 ### Mailing lists
 

SuggestedProjects.md

@@ -6,7 +6,7 @@ SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 # Suggested Projects
 
 
-After trying the existing projects (especially those listed on [Getting started](GettingStarted))
+After trying the existing projects (e.g. the [Tutorials](Tutorials))
 a good way to learn the intricacies of programming on
 top of seL4 is to do the exercises in the
 [UNSW Advanced

Tutorials/camkes-vm-crossvm.md

@@ -3,9 +3,9 @@ toc: true
 title: Camkes Cross-VM communication
 tutorial: camkes-vm-crossvm
 tutorial-order: vm-2
+layout: tutorial
 description: walkthrough of adding communication between Linux guests in separate VMs.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
-{% include tutorial.md %}
-
+{% include tutorial.md %}

Tutorials/camkes-vm-linux.md

@@ -3,9 +3,12 @@ toc: true
 title: Camkes VM Linux
 tutorial: camkes-vm-linux
 tutorial-order: vm-1
+layout: tutorial
 description: using Linux as a guest in the Camkes VM.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+Next tutorial: <a href="camkes-vm-crossvm">CAmkES Cross VM</a>

Tutorials/capabilities.md

@@ -4,7 +4,11 @@ title: Capabilities
 tutorial: capabilities
 tutorial-order: mechanisms-1
 description: an introduction to capabilities in the seL4 kernel API.
+layout: tutorial
 SPDX-License-Identifier: CC-BY-SA-4.0
-SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
+SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC.
 ---
+
 {% include tutorial.md %}
+
+Next tutorial: <a href="untyped">Untyped</a>

Tutorials/dynamic-1.md

@@ -3,9 +3,13 @@ toc: true
 title: Dynamic Libraries 1
 tutorial: dynamic-1
 tutorial-order: dynamic-1
+layout: tutorial
 description: system initialisation & threading with seL4_libs.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+
+Next tutorial: <a href="dynamic-2">IPC</a>

Tutorials/dynamic-2.md

@@ -3,9 +3,13 @@ toc: true
 title: Dynamic Libraries 2
 tutorial: dynamic-2
 tutorial-order: dynamic-2
+layout: tutorial
 description: IPC with seL4_libs.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+
+Next tutorial: <a href="dynamic-3">Processes & Elf loading</a>

Tutorials/dynamic-3.md

@@ -3,9 +3,12 @@ toc: true
 title: Dynamic Libraries 3
 tutorial: dynamic-3
 tutorial-order: dynamic-3
-description: process management with seL4_libs.
+layout: tutorial
+description: IPC with seL4_libs.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+Next tutorial: <a href="dynamic-4">Timer</a>

Tutorials/dynamic-4.md

@@ -3,9 +3,12 @@ toc: true
 title: Dynamic Libraries 4
 tutorial: dynamic-4
 tutorial-order: dynamic-4
-description: timers and timeouts with seL4_libs.
+layout: tutorial
+description: IPC with seL4_libs.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+Next tutorial: <a href="hello-camkes-0">Hello CAmkES</a>

Tutorials/fault-handlers.md

@@ -3,8 +3,12 @@ toc: true
 title: Faults
 tutorial: fault-handlers
 tutorial-order: mechanisms-8
+layout: tutorial
 description: fault (e.g virtual memory fault) handling and fault endpoints.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
+
+
+Next tutorial: <a href="mcs">MCS</a>

Tutorials/get-the-tutorials.md

@@ -0,0 +1,32 @@
+---
+toc: true
+title: Getting the tutorials
+layout: tutorial
+SPDX-License-Identifier: CC-BY-SA-4.0
+SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC.
+---
+
+# Getting the tutorials
+## Python Dependencies
+Additional python and CAmkES dependencies are required to build [tutorials](ReworkedTutorials). To install you can run:
+```
+pip3 install --user aenum pyelftools camkes-deps
+```
+*Hint:* This step only needs to be done once, i.e. before doing your first tutorial
+
+## Get the code
+All tutorials are in the <a href="https://github.com/seL4/sel4-tutorials-manifest">sel4-tutorials-manifest</a>. Get the code with:
+```
+mkdir sel4-tutorials-manifest
+cd sel4-tutorials-manifest
+repo init -u https://github.com/seL4/sel4-tutorials-manifest
+repo sync
+```
+
+`repo sync` may take a few moments to run
+
+*Hint:* The **Get the code** step only needs to be done once, i.e. before doing your first tutorial.
+
+<p>
+    Next: <a href="hello-world">Hello world</a>
+</p>

Tutorials/hello-camkes-0.md

@@ -3,9 +3,12 @@ toc: true
 title: Camkes
 tutorial: hello-camkes-0
 tutorial-order: camkes-0
+layout: tutorial
 description: an introduction to Camkes concepts.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+Next tutorial: <a href="hello-camkes-1">CAmkES 1: Introduction to CAmkES</a>

Tutorials/hello-camkes-1.md

@@ -3,9 +3,12 @@ toc: true
 title: Camkes 1
 tutorial: hello-camkes-1
 tutorial-order: camkes-1
+layout: tutorial
 description: an introduction to Camkes concepts.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+Next tutorial: <a href="hello-camkes-2">CAmkES 2: Events</a>

Tutorials/hello-camkes-2.md

@@ -3,9 +3,12 @@ toc: true
 title: Camkes 2
 tutorial: hello-camkes-2
 tutorial-order: camkes-2
+layout: tutorial
 description: an introduction to Camkes concepts.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+Next tutorial: <a href="hello-camkes-timer">CAmkES 3: Timer</a>

Tutorials/hello-camkes-timer.md

@@ -3,9 +3,13 @@ toc: true
 title: Camkes 3
 tutorial: hello-camkes-timer
 tutorial-order: camkes-3
+layout: tutorial
 description: introduce Camkes hardware components.
 SPDX-License-Identifier: CC-BY-SA-4.0
 SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
 ---
 {% include tutorial.md %}
 
+
+
+Next tutorial: <a href="camkes-vm-linux">CAmkES VM</a>

Tutorials/hello-world.md

@@ -4,7 +4,12 @@ title: Hello, World!
 tutorial: hello-world
 tutorial-order: 0-hello
 description: an introduction to seL4 projects and tutorials.
+layout: tutorial
 SPDX-License-Identifier: CC-BY-SA-4.0
-SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
+SPDX-FileCopyrightText: 2024 seL4 Project a Series of LF Projects, LLC.
 ---
+
 {% include tutorial.md %}
+
+
+Next tutorial: <a href="capabilities">Capabilities</a>