documentation: labs: create SO2 lab1 from introduction and kernel_modules labs

valighita · dbaluta · commit 1cf09197fbbf · 2021-02-23T13:55:33.000+02:00
Signed-off-by: Valentin Ghita &lt;valx92@gmail.com&gt;
diff --git a/Documentation/teaching/index.rst b/Documentation/teaching/index.rst
@@ -40,10 +40,13 @@ tools/labs/docs/Dockerfile for dependencies):
 
    cd tools/labs && make docs
 
+.. toctree::
+
+   so2/index.rst
+
 .. toctree::
    :caption: Lectures
 
-   lectures/so2.cs.pub.ro.rst
    lectures/intro.rst
    lectures/syscalls.rst
    lectures/interrupts.rst
diff --git a/Documentation/teaching/labs/introduction.rst b/Documentation/teaching/labs/introduction.rst
@@ -17,6 +17,9 @@ Keywords
 *  cscope, LXR
 *  gdb, /proc/kcore, addr2line, dump\_stack
 
+..
+  _[SECTION-ABOUT-BEGIN]
+
 About this laboratory
 =====================
 
@@ -38,8 +41,14 @@ For best laboratory performance, we recommend that you read the related slides.
 To fully understand a laboratory, we recommend going through the lab support. For
 in-depth study, use the supporting documentation.
 
-Documentation
-=============
+..
+  _[SECTION-ABOUT-END]
+
+..
+  _[SECTION-REFERENCES-BEGIN]
+
+References
+==========
 
 -  Linux
 
@@ -55,6 +64,12 @@ Documentation
    -  `mailing list <http://cursuri.cs.pub.ro/cgi-bin/mailman/listinfo/pso>`__
       (`searching the mailing list <http://blog.gmane.org/gmane.education.region.romania.operating-systems-design>`__)
 
+..
+  _[SECTION-REFERENCES-END]
+
+..
+  _[SECTION-CODE-NAVIGATION-BEGIN]
+
 Source code navigation
 ======================
 
@@ -248,8 +263,14 @@ a copy, because SourceWeb doesn't have, at this moment, the capability
 to regenerate the index for a single file and you will have to regenerate
 the complete index.
 
-Debugging
-=========
+..
+  _[SECTION-CODE-NAVIGATION-END]
+
+..
+  _[SECTION-DEBUGGING-BEGIN]
+
+Kernel Debugging
+================
 
 Debugging a kernel is a much more difficult process than the debugging
 of a program, because there is no support from the operating system.
@@ -402,6 +423,12 @@ execution paths, which makes this method difficult.
 In these situations, it is useful to get a stack trace, which can be
 simply done using the function :code:`dump_stack()`.
 
+..
+  _[SECTION-DEBUGGING-END]
+
+..
+  _[SECTION-DOCUMENTATION-BEGIN]
+
 Documentation
 =============
 
@@ -426,9 +453,15 @@ A few links related to the Linux kernel are shown bellow:
 The links are not comprehensive. Using  `The Internet <http://www.google.com>`__ and
 `kernel source code <http://lxr.free-electrons.com/>`__ is essential.
 
+..
+  _[SECTION-DOCUMENTATION-END]
+
 Exercises
 =========
 
+..
+  _[SECTION-EXERCISES-REMARKS-BEGIN]
+
 Remarks
 -------
 
@@ -455,8 +488,14 @@ Remarks
 .. important::
     Before solving an exercice, **carefully** read all its bullets.
 
-1. Booting the virtual machine
-------------------------------
+..
+  _[SECTION-EXERCISES-REMARKS-END]
+
+..
+  _[EXERCISE1-BEGIN]
+
+Booting the virtual machine
+---------------------------
 
 A summary of the virtual machine infrastructure:
 
@@ -495,8 +534,14 @@ the :command:`QEMU_DISPLAY=sdl make boot`.
     The virtual machine will start with the permissions of the
     root account.
 
-2. Adding and using a virtual disk
-----------------------------------
+..
+  _[EXERCISE1-END]
+
+..
+  _[EXERCISE2-BEGIN]
+
+Adding and using a virtual disk
+-------------------------------
 
 .. note:: If you don't have the file :file:`mydisk.img`, you can download
           it from the address http://elf.cs.pub.ro/so2/res/laboratoare/mydisk.img.
@@ -579,8 +624,14 @@ With support for the :command:`btrfs` filesystem, now :command:`mount` will fini
           you to return to the initial setup in order to have an environment
           identical to the one used by vmchecker.
 
-3. GDB and QEMU
----------------
+..
+  _[EXERCISE2-END]
+
+..
+  _[EXERCISE3-BEGIN]
+
+GDB and QEMU
+------------
 
 We can investigate and troubleshoot the QEMU virtual machine in real time.
 
@@ -636,6 +687,12 @@ such as :command:`list` and :command:`backtrace` to trace the execution.
 .. hint:: At the :command:`gdb` prompt, you can press :command:`Enter`
           (without anything else) to rerun the last command.
 
+..
+  _[EXERCISE3-END]
+
+..
+  _[EXERCISE4-BEGIN]
+
 4. GDB spelunking
 -----------------
 
@@ -681,6 +738,13 @@ The :code:`jiffies` variable holds the number of ticks (clock beats) since the s
 
               x/wx & jiffies
 
+..
+  _[EXERCISE4-END]
+
+..
+  _[EXERCISE5-BEGIN]
+
+
 5. Cscope spelunking
 --------------------
 
diff --git a/Documentation/teaching/labs/kernel_modules.rst b/Documentation/teaching/labs/kernel_modules.rst
@@ -10,8 +10,11 @@ Lab objectives
 * presenting how a module can be used with a kernel
 * simple kernel debugging methods
 
-Overview
-========
+..
+  _[SECTION-OVERVIEW-BEGIN]
+
+Kernel Modules Overview
+=======================
 
 A monolithic kernel, though faster than a microkernel, has the disadvantage of
 lack of modularity and extensibility. On modern monolithic kernels, this has
@@ -25,6 +28,12 @@ For the development of Linux device drivers, it is recommended to download the
 kernel sources, configure and compile them and then install the compiled version
 on the test /development tool machine.
 
+..
+  _[SECTION-OVERVIEW-END]
+
+..
+  _[SECTION-MODULE-EXAMPLE-BEGIN]
+
 An example of a kernel module
 =============================
 
@@ -72,6 +81,12 @@ by the logging daemon (syslog). To display kernel messages, you can use the
    Hi
    Bye
 
+..
+  _[SECTION-MODULE-EXAMPLE-END]
+
+..
+  _[SECTION-COMPILE-MODULES-BEGIN]
+
 Compiling kernel modules
 ========================
 
@@ -173,6 +188,11 @@ follows:
 For more details, see the :file:`Documentation/kbuild/makefiles.txt` and
 :file:`Documentation/kbuild/modules.txt` files within the kernel sources.
 
+..
+  _[SECTION-COMPILE-MODULES-END]
+
+..
+  _[SECTION-LOAD-MODULES-BEGIN]
 
 Loading/unloading a kernel module
 =================================
@@ -230,8 +250,14 @@ Information about modules loaded into the kernel can be found using the
 :command:`lsmod` command or by inspecting the :file:`/proc/modules`,
 :file:`/sys/module` directories.
 
-Debugging
-=========
+..
+  _[SECTION-LOAD-MODULES-END]
+
+..
+  _[SECTION-DEBUG-MODULES-BEGIN]
+
+Kernel Module Debugging
+=======================
 
 Troubleshooting a kernel module is much more complicated than debugging a
 regular program. First, a mistake in a kernel module can lead to blocking the
@@ -908,6 +934,9 @@ breakpoint to monitor the changes of the ``mVar`` variable.
   # return from KDB
   kdb> go
 
+..
+  _[SECTION-DEBUG-MODULES-END]
+
 Exercises
 =========
 
@@ -958,6 +987,9 @@ in the Linux kernel source code:
   For more info on using :command:`cscope`, read the
   :ref:`cscope section <cscope_intro>` in the previous lab.
 
+..
+  _[EXERCISE1-BEGIN]
+
 1. Kernel module
 ----------------
 
@@ -999,6 +1031,13 @@ using `minicom -D serial.pts` and perform the following tasks:
           a kernel module, you can specify only the module name
           (without extension).
 
+..
+  _[EXERCISE1-END]
+
+..
+  _[EXERCISE2-BEGIN]
+
+
 2. Printk
 ---------
 
@@ -1017,6 +1056,12 @@ Load/unload the module again.
 The messages should not be printed to the virtual machine console,
 but they should be visible when running ``dmesg``.
 
+..
+  _[EXERCISE2-END]
+
+..
+  _[EXERCISE3-BEGIN]
+
 3. Error
 --------
 
@@ -1029,6 +1074,12 @@ errors occurred? **Hint:** How does this module differ from the previous module?
 Modify the module to solve the cause of those errors, then compile and test
 the module.
 
+..
+  _[EXERCISE3-END]
+
+..
+  _[EXERCISE4-BEGIN]
+
 4. Sub-modules
 --------------
 
@@ -1043,6 +1094,12 @@ two C source files.
 Compile, copy, boot the VM, load and unload the kernel module. Make sure messages
 are properly displayed on the console.
 
+..
+  _[EXERCISE4-END]
+
+..
+  _[EXERCISE5-BEGIN]
+
 5. Kernel oops
 --------------
 
@@ -1073,6 +1130,12 @@ kernel since the oops; Until the release of those references (which is
 almost impossible in the case of an oops), the module can not be
 unloaded.
 
+..
+  _[EXERCISE5-END]
+
+..
+  _[EXERCISE6-BEGIN]
+
 6. Module parameters
 --------------------
 
@@ -1090,6 +1153,12 @@ message shown is ``Early bird gets tired``.
 
 .. _proc-info:
 
+..
+  _[EXERCISE6-END]
+
+..
+  _[EXERCISE7-BEGIN]
+
 7. Proc info
 ------------
 
@@ -1126,6 +1195,12 @@ from the executable :file:`/sbin/insmod` when the module is loaded and
 when the module is unloaded a process is created from the executable
 :file:`/sbin/rmmod`.
 
+..
+  _[EXERCISE7-END]
+
+..
+  _[EXTRA-EXERCISE-BEGIN]
+
 Extra Exercises
 ===============
 
@@ -1268,3 +1343,6 @@ Without unloading the module, deactivate :c:func:`pr_debug` calls.
 
 .. hint::
     You can delete the set flags. Unload the kernel module.
+
+..
+  _[EXTRA-EXERCISE-END]
diff --git a/Documentation/teaching/so2/index.rst b/Documentation/teaching/so2/index.rst
@@ -0,0 +1,16 @@
+===================
+Operating Systems 2
+===================
+
+
+.. toctree::
+   :caption: Lectures
+   :maxdepth: 1
+
+   ../lectures/so2.cs.pub.ro.rst
+
+.. toctree::
+   :caption: Labs
+   :maxdepth: 1
+
+   lab1-intro.rst
diff --git a/Documentation/teaching/so2/lab1-intro.rst b/Documentation/teaching/so2/lab1-intro.rst
