TUTORIALS: Reorganise tutorials and add inline solutions #106

bbrcknl · 2024-05-27T07:22:30Z

The updates in this PR were written in conjunction with those in seL4/docs#231

The aim of both PRs is:

To arrange the tutorial material on the docsite such that it is clear and easy to follow. Inspired by the Rust book https://doc.rust-lang.org/book/, the user can see the chapters in the index on the left, and go straight to the sections that they need.

Specifically, the updates on the docsite provide:

a streamlined guide to completing the tutorials
a streamlined "setting up your machine" page
a how-to page with solutions to tutorial questions
more organised landing page

The tutorials have been slightly rewritten to:

correct minor errors
provide inline solutions for readers wishing to understand the material and/or get quick solutions

Remaining issues:

camkes-timer part 2 fails to compile (ninja) with current solutions - need someone with know-how to check what's going on
I didn't test camkes-vm-linux; wasn't sure whether to spend a lot of time investigating KVM alternative for Mac
the tutorial camkes-vm-crossvm fails to initialise - need someone with know-how to check what's going on

A note on using the rewritten docsite (from seL4/docs#231):
While the docsite in this PR has the new tutorial layout, the Makefile clones the old tutorials from https://github.com/seL4/sel4-tutorials.

You’ll need to integrate the updated tutorials (from this PR) in the Makefile from seL4/docs#231
I can’t offer code for this because I’m a Makefile noob. I tested the new tutorials by having the Makefile call in and manipulate tutorial files from local directories.

Signed-off-by: Birgit Brecknell <b@brck.nl>

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

Signed-off-by: Birgit Brecknell <b@brck.nl>

Indanz

Other than changing copyright holders, overall it seems fine. I haven't seen it rendered yet though.

Indanz · 2024-07-29T10:35:42Z

tutorials/hello-camkes-2/hello-camkes-2.md

+
+```
+/*-- filter TaskContent("hello", TaskContentType.BEFORE, subtask="event-task3") -*/
+    /* TASK 3: the event interfaces */


I'm not sure about the discontinuous task numbering, maybe it makes sense on the rendered page. Why isn't this TASK 2?

I left this numbering in there so as not to mess with the original tutorials. The ordering makes more sense if you look at the .c, .camkes and .txt files that are generated from the .md file. Should we mention this on the tutorial pages?
The current camkes tutorial overview (https://docs.sel4.systems/Tutorials/#camkes-tutorials) points to a slide presentation, which is no longer available and may have had more detail.

The presentations still seem to be available here: https://github.com/seL4/sel4-tutorials/tree/master/docs. It's in old D61 layout, but the content is still Ok, I think.

Indanz · 2024-07-29T10:55:10Z

tutorials/hello-world/hello-world.md

-/*? macros.simulate_block() ?*/
+### Run Hello, World using QEMU
+
+The final image can be run *inside* the container using the command:


QEMU is not a container, it is a hardware CPU emulator. The text below already says that it will be run within QEMU simulator, so I'd keep the original text "The final image can be run by:".

Indanz · 2024-07-29T10:59:39Z

tutorials/hello-world/hello-world.md

-Once you have made your change, rerun `ninja` to rebuild the project:
+Once you have made your change, use Terminal B to rebuild the project.
+
+*Hint:* Remember to exit the QEMU siumator before rerunning the project with `ctrl-A,x`.


Suggested change

*Hint:* Remember to exit the QEMU siumator before rerunning the project with `ctrl-A,x`.

*Hint:* Remember to exit the QEMU simulator before rerunning the project with `ctrl-A,x`.

Indanz · 2024-07-29T11:12:43Z

tutorials/hello-world/hello-world.md

+
+*Hint:* Remember to exit the QEMU siumator before rerunning the project with `ctrl-A,x`.
+
+Then rebuild using ninja and run the simulator again:


Was this one supposed to replace the next line?

I've removed line 208

Indanz · 2024-07-29T11:20:02Z

tutorials/mcs/mcs.md

 'mcs-server','mcs-badge','mcs-fault']) ?*/

+This tutorial presents the features in the upcoming MCS extensions for seL4, which are currently undergoing


Suggested change

This tutorial presents the features in the upcoming MCS extensions for seL4, which are currently undergoing

This tutorial presents the features in the Mixed-Criticality System (MCS) extensions for seL4, which are currently undergoing

Indanz · 2024-07-29T11:30:16Z

tutorials/camkes-vm-kernel-module/camkes-vm-kernel-module.md

@@ -1,7 +1,7 @@
 <!--
  Copyright 2021 Michael Neises

-  SPDX-License-Identifier: BSD-2-Clause
+  SPDX-License-Identifier: CC-BY-SA-4.0


CC-BY-SA-4.0 seems to be compatible with BSD-2-Clause, so the above change is probably legal.

Doesn't seem very polite to do though, especially if there are no other changes.

Indanz · 2024-07-29T11:51:23Z

tutorials/dynamic-2/dynamic-2.md


 /*- filter ExcludeDocs() -*/
 /*? ExternalFile("CMakeLists.txt") ?*/
 ```
 /*-- filter File("main.c") -*/
 /*
- * Copyright 2017, Data61, CSIRO (ABN 41 687 119 230)
+ * Copyright 2024, seL4 Project a Series of LF Projects, LLC.


Legally dubious.

Indanz · 2024-07-29T11:52:57Z

tutorials/dynamic-3/dynamic-3.md

 /*-- filter ExcludeDocs() -*/
 /*? ExternalFile("CMakeLists.txt") ?*/
 ```
 /*-- filter File("main.c") -*/
 /*
- * Copyright 2017, Data61, CSIRO (ABN 41 687 119 230).
+ * Copyright 2024, seL4 Project a Series of LF Projects, LLC..


Legally dubious.

Indanz · 2024-07-29T11:53:08Z

tutorials/dynamic-3/dynamic-3.md

@@ -640,9 +697,9 @@ int main(void) {
 /*-- endfilter -*/
 /*-- filter File("app.c") -*/
 /*
- * Copyright 2017, Data61, CSIRO (ABN 41 687 119 230).
+ * Copyright 2024, seL4 Project a Series of LF Projects, LLC..


Legally dubious.

Indanz · 2024-07-29T11:54:05Z

tutorials/dynamic-4/dynamic-4.md

@@ -435,9 +485,9 @@ int main(void) {
 /*-- endfilter -*/
 /*-- filter File("client.c") -*/
 /*
- * Copyright 2017, Data61, CSIRO (ABN 41 687 119 230).
+ * Copyright 2024, seL4 Project a Series of LF Projects, LLC..


Legally dubious.

Signed-off-by: Birgit Brecknell <b@brck.nl>

bbrcknl · 2024-07-31T06:17:24Z

@Indanz
Minor fixes made to hello-world and mcs as per your suggestions. Original copyright restore for tute files.

Signed-off-by: Birgit Brecknell <b@brck.nl>

bbrcknl · 2024-07-31T07:31:05Z

Dynamic libraries filenames need changing. It's on my to-dos for Friday.

template.py

Co-authored-by: Gerwin Klein <gerwin.klein@proofcraft.systems> Signed-off-by: bbrcknl <32238793+bbrcknl@users.noreply.github.com>

Signed-off-by: Birgit Brecknell <b@brck.nl>

Indanz

Thanks for doing this gargantuan job!

I checked the rendered pages and the diff, those look good. I haven't checked whether the commit history makes sense or not. If it's too much of a mess we can always squash it.

bbrcknl and others added 30 commits April 19, 2024 11:51

update dynamic-libraries-1

316e67f

Signed-off-by: Birgit Brecknell <b@brck.nl>

update dynamic-libraries-2

13aaf81

Signed-off-by: Birgit Brecknell <b@brck.nl>

update dynamic-libraries-3

d7c3e60

Signed-off-by: Birgit Brecknell <b@brck.nl>

update dynamic-libraries-4

b96bd72

Signed-off-by: Birgit Brecknell <b@brck.nl>

update hello-camkes

ca003e0

Signed-off-by: Birgit Brecknell <b@brck.nl>

update hello-camkes-1 - missing one solution

76b2d48

Signed-off-by: Birgit Brecknell <b@brck.nl>

update hello-camkes-2

487920a

Signed-off-by: Birgit Brecknell <b@brck.nl>

update hello-camkes-timer

5917493

Signed-off-by: Birgit Brecknell <b@brck.nl>

update camkes-vm

afb746e

Signed-off-by: Birgit Brecknell <b@brck.nl>

update camkes-cross-vm

ea0d14f

Signed-off-by: Birgit Brecknell <b@brck.nl>

update hello-world.md

fa98bab

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update hello-world.md

d584045

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

merge tutorials accidentally committed to origin/master

c79fa1e

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update capabilities.md

b737147

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update hello-world - minor change

844c926

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update capabilities - minor change

930604a

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update untyped

aa918b6

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update mapping tutorial

6b85b9e

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update threads tutorial

ff150f7

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update ipc tutorial

5dbd89c

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update notifications tutorial

e1859a4

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update interrupts tutorial

27b9b0f

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update fault-handlers tutorial

64b5b5a

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update mcs tutorial

02e04ea

Signed-off-by: Birgit Brecknell <bbrcknl@gmail.com>

update hello-world with new instructions

5e8e6cc

Signed-off-by: Birgit Brecknell <b@brck.nl>

add tutorials solutions call macro

74528cd

Signed-off-by: Birgit Brecknell <b@brck.nl>

add macro - init with solutions - to md files

fc3890a

Signed-off-by: Birgit Brecknell <b@brck.nl>

update link in macros

5f09c69

Signed-off-by: Birgit Brecknell <b@brck.nl>

remove out of date help block

bfc0125

Signed-off-by: Birgit Brecknell <b@brck.nl>

reorder section on containers

c7472b3

Signed-off-by: Birgit Brecknell <b@brck.nl>

bbrcknl added 2 commits July 29, 2024 16:51

attempt fix of template str error

576caf4

Signed-off-by: Birgit Brecknell <b@brck.nl>

attempt fix of template str error

2f28430

Signed-off-by: Birgit Brecknell <b@brck.nl>

Indanz requested changes Jul 29, 2024

View reviewed changes

bbrcknl added 3 commits July 31, 2024 15:59

minor fixes for clarity

857ac4c

Signed-off-by: Birgit Brecknell <b@brck.nl>

minor fixes for clarity - mcs

5afd603

Signed-off-by: Birgit Brecknell <b@brck.nl>

restore original copyright

3380115

Signed-off-by: Birgit Brecknell <b@brck.nl>

replace dynamic-libraries with libraries

caa47e9

Signed-off-by: Birgit Brecknell <b@brck.nl>

lsf37 reviewed Jul 31, 2024

View reviewed changes

template.py Outdated Show resolved Hide resolved

bbrcknl and others added 8 commits August 2, 2024 09:12

Update template.py

d04cc82

Co-authored-by: Gerwin Klein <gerwin.klein@proofcraft.systems> Signed-off-by: bbrcknl <32238793+bbrcknl@users.noreply.github.com>

change filenames - dynamic-libraries to libraries

7eda41c

Signed-off-by: Birgit Brecknell <b@brck.nl>

fix error - hello-camkes-1

0e94207

Signed-off-by: Birgit Brecknell <b@brck.nl>

fix error - hello-camkes-2

4809eec

Signed-off-by: Birgit Brecknell <b@brck.nl>

fix error - hello-camkes-timer

2d70097

Signed-off-by: Birgit Brecknell <b@brck.nl>

fix code errors hello-camkes-1

5199f2d

Signed-off-by: Birgit Brecknell <b@brck.nl>

revert accidental commit of old hello-camkes-timer code

cc1dab3

Signed-off-by: Birgit Brecknell <b@brck.nl>

add link to slide presentation to camkes0-2 tutes

2955796

Signed-off-by: Birgit Brecknell <b@brck.nl>

bbrcknl force-pushed the update_tutorials branch from ed0c2e1 to 2955796 Compare August 2, 2024 03:21

bbrcknl and others added 9 commits August 5, 2024 17:15

fix error

ad950e3

Signed-off-by: Birgit Brecknell <b@brck.nl>

fix inline content for hello-camkes-timer to pass test

847e643

Signed-off-by: Birgit Brecknell <b@brck.nl>

add instruction for camkes-vm tutes

002b2e7

Signed-off-by: Birgit Brecknell <b@brck.nl>

change tutorials/ -> Tutorials/

ab0dace

Signed-off-by: Birgit Brecknell <b@brck.nl>

fix style errors

59352eb

Signed-off-by: Birgit Brecknell <b@brck.nl>

fix camkes 2 truncation issue

999c9fd

Signed-off-by: Birgit Brecknell <b@brck.nl>

remove solution style

57b5b84

Signed-off-by: Birgit Brecknell <b@brck.nl>

Merge branch 'master' into update_tutorials

3d6f196

update camkes and library headers

b2f91ad

Signed-off-by: Birgit Brecknell <b@brck.nl>

Indanz approved these changes Sep 30, 2024

View reviewed changes

Merge branch 'master' into update_tutorials

8acabc1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TUTORIALS: Reorganise tutorials and add inline solutions #106

TUTORIALS: Reorganise tutorials and add inline solutions #106

bbrcknl commented May 27, 2024

Indanz left a comment

Indanz Jul 29, 2024

bbrcknl Jul 31, 2024

lsf37 Aug 1, 2024

Indanz Jul 29, 2024

Indanz Jul 29, 2024

Indanz Jul 29, 2024

bbrcknl Jul 31, 2024

Indanz Jul 29, 2024

Indanz Jul 29, 2024

Indanz Jul 29, 2024

Indanz Jul 29, 2024

Indanz Jul 29, 2024

Indanz Jul 29, 2024

bbrcknl commented Jul 31, 2024

bbrcknl commented Jul 31, 2024

Indanz left a comment

	Hint: Remember to exit the QEMU siumator before rerunning the project with `ctrl-A,x`.
	Hint: Remember to exit the QEMU simulator before rerunning the project with `ctrl-A,x`.


		Hint: Remember to exit the QEMU siumator before rerunning the project with `ctrl-A,x`.

		Then rebuild using ninja and run the simulator again:

		'mcs-server','mcs-badge','mcs-fault']) ?*/

		This tutorial presents the features in the upcoming MCS extensions for seL4, which are currently undergoing

TUTORIALS: Reorganise tutorials and add inline solutions #106

Are you sure you want to change the base?

TUTORIALS: Reorganise tutorials and add inline solutions #106

Conversation

bbrcknl commented May 27, 2024

Indanz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bbrcknl commented Jul 31, 2024

bbrcknl commented Jul 31, 2024

Indanz left a comment

Choose a reason for hiding this comment