Merge pull request #149 from manuelmohr/fix/hal-docs

Fix various small issues found in the tutorial docs

doc/overview/tutorials/creating-a-new-mux-target/adapting-target-pass-pipeline.rst

@@ -28,6 +28,7 @@ The scheduling struct looks like:
     struct sched_struct {
       size_t   group_id[3];
       size_t   num_groups[3];
+      size_t   global_offset[3];
       size_t   local_size[3];
       uint32_t work_dim;
     }
@@ -49,9 +50,9 @@ follows:
 
 .. code:: cpp
 
-  group_id[0] = slice id
-  group_id[1] = instance id % num_groups[1]
-  group_id[2] = instance id / num_groups[1]
+  group_id[0] = instance id
+  group_id[1] = slice id % num_groups[1]
+  group_id[2] = slice id / num_groups[1]
 
 We thus need to write an additional pass which takes the *RefSi* function
 signature, sets the ``group_id`` parts of the ``sched_struct`` and calls the

doc/overview/tutorials/creating-new-hal/hal-operations-step-03-loading-programs.rst

@@ -74,7 +74,7 @@ entry point function:
       if (program == hal::hal_invalid_program) {
         return hal::hal_invalid_kernel;
       }
-      ELFProgram *elf = (ELFProgram )program;
+      ELFProgram *elf = (ELFProgram *)program;
       hal::hal_addr_t kernel = elf->find_symbol(name);
       if (kernel == hal::hal_nullptr) {
         return hal::hal_invalid_kernel;

doc/overview/tutorials/creating-new-hal/initial-setup.rst

@@ -12,7 +12,7 @@ of the creation of the RefSi HAL:
 * hal_refsi_tutorial: contains the skeleton for the RefSi HAL we will create in
   this tutorial. This is under ``examples/hals/hal_refsi_tutorial``.
 * refsidrv: contains a driver that controls a virtual RefSi device. This is under
-  ``modules/mux/external/refsidrv``.
+  ``examples/refsi/hal_refsi/external/refsidrv``.
 * hal: contains headers needed to interface with a HAL. At top level of the oneAPI
   Construction Kit.
 * riscv-isa-sim: contains the Spike RISC-V simulator, used to simulate the
@@ -29,8 +29,8 @@ assume that the environment variable ``OCK`` has been set to the base of the
     $ mkdir refsi_tutorial_part1
     $ cd refsi_tutorial_part1
     $ export OCK=<path_to_oneapi-construction-kit>
-    $ cp $OCK/examples/hal/hal_refsi_tutorial .
-    $ cp $OCK/modules/mux/external/refsidrv hal_refsi_tutorial/external
+    $ cp -a $OCK/examples/hals/hal_refsi_tutorial .
+    $ cp -a $OCK/examples/refsi/hal_refsi/external/refsidrv hal_refsi_tutorial/external
 
 The resulting source code layout from running the above commands is the following:
 
@@ -41,7 +41,7 @@ The resulting source code layout from running the above commands is the followin
             external/
                 refsidrv/ -> refsidrv repository, 'tutorial1' branch
                     external/
-                        riscv-isa-sim/ -> submodule of refsidrv
+                        riscv-isa-sim/ -> submodule of refsidrv, will be fetched by cmake
 
 Installing a RISC-V toolchain
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/overview/tutorials/creating-new-hal/running-kernels/kernel-argument-packing.rst

@@ -72,7 +72,7 @@ be added:
     cb.addWRITE_REG64(CMP_REG_KUB_DESC, kub_desc);
     cb.addWRITE_REG64(CMP_REG_KARGS_INFO, kargs_info);    // Added
     cb.addWRITE_REG64(CMP_REG_TSD_INFO, tsd_info);
-    cb.addRUN_KERNEL_SLICE(* num_harts */ 0, num_instances, 0);
+    cb.addRUN_KERNEL_SLICE(/* num_harts */ 0, num_instances, 0);
     cb.addFINISH();
 
 Please note that the ``kargs_info`` value is set to zero instead of being

doc/overview/tutorials/creating-new-hal/running-kernels/simple-kernel-scheduling.rst

@@ -168,7 +168,7 @@ of parallel harts to use is set to the device's default value:
       cb.addWRITE_REG64(CMP_REG_RETURN_ADDR, elf->find_symbol("kernel_exit"));
       cb.addWRITE_REG64(CMP_REG_KUB_DESC, kub_desc); // Added
       cb.addWRITE_REG64(CMP_REG_TSD_INFO, tsd_info); // Added
-      cb.addRUN_KERNEL_SLICE(* num_harts */ 0, num_instances, 0); // Changed
+      cb.addRUN_KERNEL_SLICE(/* num_harts */ 0, num_instances, 0); // Changed
       cb.addFINISH();
 
       // Execute the command buffer.

hal/docs/hal.md

@@ -10,7 +10,7 @@ abstracting at this level, there are a number of benefits:
 - Tested and proven code can be shared between HALs for faster bring-up.
 
 Currently the HAL is used exclusively as part of the RISC-V MUX target and in
-the CLIK tool. The HAL specification makes no demands on the the executable used
+the CLIK tool. The HAL specification makes no demands on the executable used
 except for its use in RISC-V target. Since the RISC-V target will be used as a
 template for future targets this is also detailed
 [here](#hal-kernel-abi-used-in-the-current-risc-v-mux).
@@ -294,8 +294,8 @@ hal->program_free(program2);
 A HAL writer can also expect that when `program_load` is called it becomes the
 responsibility of the callee to call `program_free` to release any resources
 used. All currently loaded programs will be freed by the callee prior to any
-call being made to `hal_device_t::device_delete`. The intension of this rule is
-to simplify HAL implementations so they dont have to track allocations.
+call being made to `hal_device_t::device_delete`. The intention of this rule is
+to simplify HAL implementations so they don't have to track allocations.
 
 
 -----
@@ -314,7 +314,7 @@ next API call was processed.
 When invoking a kernel with `kernel_exec` the kernel arguments are passed as a
 list of argument descriptors to the HAL. These descriptors are intentionally
 neutral regarding the details of how the data will be passed to the kernel. This
-breaks the direct coupling between the ABI and the HAL API, leading to less
+breaks the direct coupling between the ABI and the HAL API, leading to fewer
 changes when we change the kernel ABI.
 
 ```cpp
@@ -424,7 +424,7 @@ to provide more target specific information. By querying the
 downcast correctly to the correct type, giving access to ISA specific
 information.
 
-The rational behind this is to avoid multiple ISAs turning the `hal_device_info_t`
+The rationale behind this is to avoid multiple ISAs turning the `hal_device_info_t`
 struct into a "god" struct, while still allowing common information to be
 shared. If the oneAPI Construction Kit target needs to execute a target specific
 code-path the HAL can be downcast accordingly to access any target specific
@@ -557,7 +557,7 @@ Currently the following is adhered to:
 
 
 ----
-## Multiple kernel Variants
+## Multiple Kernel Variants
 
 For performance reasons it can be useful to create multiple distinct variants of
 kernels. While they are equivalent in operation, they vary in terms of

source/cl/test/UnitCL/README.md

@@ -1,3 +1,3 @@
 # UnitCL
 
-Documentation can be found [here](../../doc/source/cl/test/unitcl.md).
+Documentation can be found [here](../../../../doc/source/cl/test/unitcl.rst).