Merge pull request #8 from imbev/main

Misc improvements

Author: fwsGonzo

docs/concepts/_category_.json

@@ -4,6 +4,6 @@
 	"position": 3,
 	"link": {
 		"type": "generated-index",
-		"description": "Learn more about the libriscv APIs."
+		"description": "Learn more about libriscv concepts and important parts of the C++ API."
 	}
 }

docs/concepts/vmcalls.md

@@ -272,79 +272,8 @@ inline std::optional<Script::sgaddr_t> Script::call(gaddr_t address, Args&&... a
 ```
 From `script.call(...)` as implemented in the [gamedev example](https://github.com/libriscv/libriscv/blob/master/examples/gamedev/script.hpp). `ScriptDepthMeter` measures the current call depth in order to avoid too many recursive calls back into the script, while also using the faster `vmcall()` on the first call.
 
-## VM Calls with the C API
 
-In the C API each argument register has to be populated manually, and the return value(s) have to be read as well.
+## Examples
 
-A general rule for passing data to a function is that:
-1. Each integer goes into the next free integer register
-2. Each pointer goes into the next free integer register
-
-```c
-LIBRISCV_ARG_REGISTER(regs, 0) = 1;
-LIBRISCV_ARG_REGISTER(regs, 1) = true;
-LIBRISCV_ARG_REGISTER(regs, 2) = libriscv_stack_push(machine, regs, mystruct, sizeof(mystruct));
-LIBRISCV_ARG_REGISTER(regs, 3) = libriscv_address_of(machine, "my_function");
-```
-A function address is also a pointer, which goes into the integer register file.
-
-
-3. Each float goes into the next free float register of that type
-
-```c
-LIBRISCV_FP32_ARG_REG(regs, 0) = 1.0f;
-LIBRISCV_FP32_ARG_REG(regs, 1) = 2.0f;
-LIBRISCV_FP64_ARG_REG(regs, 2) = 3.0;
-LIBRISCV_FP64_ARG_REG(regs, 3) = 4.0;
-```
-32- and 64-bit floating point values use the same register file.
-
-
-### Example
-
-Function:
-```c
-long my_function(const char* arg1, const bool arg2, const struct my_struct* arg3, size_t arg4, float arg5);
-```
-
-Input values:
-```c
-const char* mystring = "";
-const bool  mybool = true;
-const struct mystruct s;
-const size_t mysize = 4;
-const float  myfloat = 5.0f;
-```
-
-C++ API:
-```cpp
-long result = machine.vmcall(guest_function_address,
-	mystring, mybool, mystruct, mysize, myfloat);
-```
-
-C API:
-```c
-/* We start by setting up the call, providing the address of the function */
-libriscv_setup_vmcall(machine, guest_function_address);
-
-/**
- * We push structs on the stack, and get a guest pointer in return.
- * Guest pointers go into integer registers along with other integers
-**/
-LIBRISCV_ARG_REGISTER(regs, 0) = libriscv_stack_push(machine, regs, ...);
-LIBRISCV_ARG_REGISTER(regs, 1) = true;
-LIBRISCV_ARG_REGISTER(regs, 2) = libriscv_stack_push(machine, regs, ...);
-LIBRISCV_ARG_REGISTER(regs, 3) = 4;
-/* Floating point values go into their own registers */
-LIBRISCV_FP32_ARG_REG(regs, 0) = 5.0f;
-
-/* Running the VM will now execute the function with the above arguments as input */
-if (libriscv_run(machine, ~0)) {
-	fprintf(stderr, "Ooops! Function call failed!\n");
-	exit(1);
-}
-
-/* Integer return values are in A0. */
-long result = LIBRISCV_ARG_REGISTER(regs, 0);
-printf("The function returned: %ld\n", result);
-```
+- [C](/docs/host_langs/c_lang#vm-call-example)
+- [C++](/docs/host_langs/cpp_lang#vm-call-example)

docs/getting_started/_category_.json

@@ -4,6 +4,6 @@
 	"position": 2,
 	"link": {
 		"type": "generated-index",
-		"description": "Learn more about libriscv performance."
+		"description": "Get started with libriscv here! This tutorial will guide you through a simple C++ host and C guest program."
 	}
 }

docs/getting_started/guest.md

@@ -41,4 +41,4 @@ zig cc -target riscv64-linux guest.c -o guest.bin
 
 ### Note
 
-Guest binaries may also be written in other [languages](/docs/category/guest-languages).
+Guest programs may also be written in other [languages](/docs/category/guest-languages).

docs/getting_started/host.md

@@ -111,3 +111,8 @@ Hello from host!
 Hello world!
 Hello from riscv64 guest!
 ```
+
+### Note
+
+Host programs may also be written in other [languages](/docs/category/host-languages).
+

docs/getting_started/intro.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # C
@@ -24,6 +24,84 @@ Visual Studio is a proprietary C & C++ compiler for Windows. Learn more at https
 
 The C header for the libriscv C API can be found at https://github.com/libriscv/libriscv/blob/master/c/libriscv.h
 
+### VM Calls
+
+In the C API each argument register has to be populated manually, and the return value(s) have to be read as well.
+
+A general rule for passing data to a function is that:
+1. Each integer goes into the next free integer register
+2. Each pointer goes into the next free integer register
+
+```c
+LIBRISCV_ARG_REGISTER(regs, 0) = 1;
+LIBRISCV_ARG_REGISTER(regs, 1) = true;
+LIBRISCV_ARG_REGISTER(regs, 2) = libriscv_stack_push(machine, regs, mystruct, sizeof(mystruct));
+LIBRISCV_ARG_REGISTER(regs, 3) = libriscv_address_of(machine, "my_function");
+```
+A function address is also a pointer, which goes into the integer register file.
+
+
+3. Each float goes into the next free float register of that type
+
+```c
+LIBRISCV_FP32_ARG_REG(regs, 0) = 1.0f;
+LIBRISCV_FP32_ARG_REG(regs, 1) = 2.0f;
+LIBRISCV_FP64_ARG_REG(regs, 2) = 3.0;
+LIBRISCV_FP64_ARG_REG(regs, 3) = 4.0;
+```
+32- and 64-bit floating point values use the same register file.
+
 ## Examples
 
-An advanced example can be found at https://github.com/libriscv/libriscv/blob/master/examples/advanced/src/example.c
+### VM call example
+
+Guest Function:
+```c
+long my_function(
+    const char* arg1, 
+    const bool arg2, 
+    const struct my_struct* arg3, 
+    size_t arg4, 
+    float arg5
+    );
+```
+
+Input values:
+```c
+const char* mystring = "";
+const bool  mybool = true;
+const struct mystruct s;
+const size_t mysize = 4;
+const float  myfloat = 5.0f;
+```
+
+C Host:
+```c
+/* We start by setting up the call, providing the address of the function */
+libriscv_setup_vmcall(machine, guest_function_address);
+
+/**
+ * We push structs on the stack, and get a guest pointer in return.
+ * Guest pointers go into integer registers along with other integers
+**/
+LIBRISCV_ARG_REGISTER(regs, 0) = libriscv_stack_push(machine, regs, ...);
+LIBRISCV_ARG_REGISTER(regs, 1) = true;
+LIBRISCV_ARG_REGISTER(regs, 2) = libriscv_stack_push(machine, regs, ...);
+LIBRISCV_ARG_REGISTER(regs, 3) = 4;
+/* Floating point values go into their own registers */
+LIBRISCV_FP32_ARG_REG(regs, 0) = 5.0f;
+
+/* Running the VM will now execute the function with the above arguments as input */
+if (libriscv_run(machine, ~0)) {
+	fprintf(stderr, "Ooops! Function call failed!\n");
+	exit(1);
+}
+
+/* Integer return values are in A0. */
+long result = LIBRISCV_ARG_REGISTER(regs, 0);
+printf("The function returned: %ld\n", result);
+```
+
+### Advanced example
+
+https://github.com/libriscv/libriscv/blob/master/examples/advanced/src/example.c

docs/host_langs/c_lang.md

@@ -26,4 +26,34 @@ C++ headers for libriscv can be found at https://github.com/libriscv/libriscv/tr
 
 ## Examples
 
+### VM call example
+
+Guest Function:
+```c
+long my_function(
+    const char* arg1, 
+    const bool arg2, 
+    const struct my_struct* arg3, 
+    size_t arg4, 
+    float arg5
+    );
+```
+
+Input values:
+```c
+const char* mystring = "";
+const bool  mybool = true;
+const struct mystruct s;
+const size_t mysize = 4;
+const float  myfloat = 5.0f;
+```
+
+C++ Host:
+```cpp
+long result = machine.vmcall(guest_function_address,
+	mystring, mybool, mystruct, mysize, myfloat);
+```
+
+### Misc examples
+
 Most examples located here are written for a C++ host: https://github.com/libriscv/libriscv/tree/master/examples

docs/host_langs/cpp_lang.md

@@ -1,7 +1,7 @@
 {
     "label": "GDScript",
     "collapsed": true,
-    "position": 2,
+    "position": 3,
     "link": {
       "type": "generated-index",
       "description": "GDScript is a scripting language to be used with the Godot Game engine."