Initial system call comprehensive documentations

docs/md_misc_2system__calls.html

@@ -5,7 +5,7 @@
 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
 <meta name="generator" content="Doxygen 1.10.0"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
-<title>librishka: System Calls</title>
+<title>librishka: Runtime System Calls</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
@@ -92,10 +92,57 @@
 </div>
 
 <div><div class="header">
-  <div class="headertitle"><div class="title">System Calls</div></div>
+  <div class="headertitle"><div class="title">Runtime System Calls</div></div>
 </div><!--header-->
 <div class="contents">
+<div class="toc"><h3>Table of Contents</h3>
+<ul><li class="level1"><a href="#autotoc_md10">Under The Hood</a></li>
+<li class="level1"><a href="#autotoc_md11">Complete List of System Calls</a></li>
+</ul>
+</div>
 <div class="textblock"><p><a class="anchor" id="autotoc_md9"></a></p>
+<h1><a class="anchor" id="autotoc_md10"></a>
+Under The Hood</h1>
+<p>Rishka system calls provide a mechanism for user-level applications to request services or functionality from the underlying operating system (Jessy OS) running on the ESP32-WROVER microcontroller. Through these system calls, applications can request various services, functionalities, or access to system resources that are otherwise restricted from user-level code. This includes operations such as file I/O, memory management, device control, and system information retrieval. By leveraging system calls, applications can harness the full capabilities of the operating system while maintaining a clear separation between user-level and kernel-level code, ensuring system integrity, security, and reliability.</p>
+<ol type="1">
+<li><p class="startli"><b>Invocation</b></p>
+<p class="startli">User-level applications on the ESP32-WROVER microcontroller can request privileged operations or access system-level functionality through system calls. These requests are made by the application directly to the underlying operating system, Jessy OS. Rather than executing system calls directly, applications rely on an abstraction layer provided by the Rishka SDK to facilitate communication with the operating system.</p>
+</li>
+<li><p class="startli"><b>Arguments</b></p>
+<p class="startli">When invoking a system call, the user-level application provides any necessary parameters or data to the operating system. These parameters convey important information to the system call handler, enabling it to perform the requested operation. The specific arguments required for each system call depend on the nature of the operation being requested and are documented in the Rishka SDK.</p>
+</li>
+<li><p class="startli"><b>Registers</b></p>
+<p class="startli">Before initiating a system call, the user-level application prepares the arguments and system call identifier according to the RISC-V calling convention. This convention dictates the usage of specific registers to pass function arguments and system call identifiers to the operating system. By adhering to this convention, applications ensure that the operating system can correctly interpret and process the provided information.</p>
+</li>
+<li><p class="startli"><b>Triggering the System Call</b></p>
+<p class="startli">Once the necessary arguments are prepared, the user-level application initiates the system call by triggering a special instruction known as the scall. This instruction serves as a signal to the processor that a system call is being requested. Upon encountering the scall instruction, the processor transitions from user mode to privileged mode and transfers control to the operating system's system call handler.</p>
+</li>
+<li><p class="startli"><b>System Call Handler</b></p>
+<p class="startli">The system call handler within the operating system receives control when the scall instruction is encountered. It is responsible for interpreting the system call identifier provided by the user-level application and executing the corresponding functionality or service. The handler interacts with kernel resources, hardware peripherals, and other system components as necessary to fulfill the requested operation.</p>
+</li>
+<li><p class="startli"><b>Result</b></p>
+<p class="startli">After processing the system call, the system call handler returns the result of the operation to the user-level application. This result communicates the outcome of the system call execution, indicating whether the requested operation was successful or encountered an error. The user-level application can then proceed with its execution based on this feedback.</p>
+</li>
+<li><p class="startli"><b>Return to User-Level Code</b></p>
+<p class="startli">Upon completing the system call handler's execution, control returns to the user-level application. The application resumes its execution, continuing with its tasks or responding to the outcome of the system call as needed. This seamless return to user-level code ensures that applications can interact with the operating system efficiently and access privileged functionality while maintaining a clear separation between user and kernel space.</p>
+</li>
+</ol>
+<h1><a class="anchor" id="autotoc_md11"></a>
+Complete List of System Calls</h1>
+<p>The Rishka virtual runtime kernel provides an extensive array of system calls, offering a rich set of functionalities and services for user-level applications on the ESP32-WROVER microcontroller platform.</p>
+<p>The below table is a comprehensive listing with details of the diverse range of system calls available within the Rishka kernel. Note that this is subject to changes since Rishka is still underdevelopment.</p>
+<table class="markdownTable">
+<tr class="markdownTableHead">
+<th class="markdownTableHeadNone">Address (A7)   </th><th class="markdownTableHeadNone">Name   </th><th class="markdownTableHeadNone">A0   </th><th class="markdownTableHeadNone">A1   </th><th class="markdownTableHeadNone">A2   </th><th class="markdownTableHeadNone">A3   </th><th class="markdownTableHeadNone">Implementation    </th></tr>
+<tr class="markdownTableRowOdd">
+<td class="markdownTableBodyNone">0x00   </td><td class="markdownTableBodyNone">PRINTS   </td><td class="markdownTableBodyNone">(string) text   </td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"><a class="el" href="class_i_o.html#af67b36507b53221d03a5b7f1fd6638f0" title="Print text to the output stream.">IO::print(string)</a>    </td></tr>
+<tr class="markdownTableRowEven">
+<td class="markdownTableBodyNone">0x01   </td><td class="markdownTableBodyNone">PRINTN   </td><td class="markdownTableBodyNone">(i64) number   </td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"><a class="el" href="class_i_o.html#a30f60dd764ba3cb47b19849297dbb7d5" title="Print an integer number to the output stream.">IO::print(i64)</a>    </td></tr>
+<tr class="markdownTableRowOdd">
+<td class="markdownTableBodyNone">0x02   </td><td class="markdownTableBodyNone">PRINTD   </td><td class="markdownTableBodyNone">(double) number   </td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"><a class="el" href="class_i_o.html#a60ac760446a47d3e1926ffe0120ff854" title="Print a floating-point number to the output stream.">IO::print(double)</a>    </td></tr>
+<tr class="markdownTableRowEven">
+<td class="markdownTableBodyNone">0x03   </td><td class="markdownTableBodyNone">READCH   </td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"></td><td class="markdownTableBodyNone"><a class="el" href="class_i_o.html#abd2fd0dfb704cad591e256cb8074f5b2" title="Read a Unicode character from the input stream.">IO::readch()</a>   </td></tr>
+</table>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 </div><!-- doc-content -->

docs/navtreedata.js

@@ -26,7 +26,10 @@ var NAVTREE =
 [
   [ "librishka", "index.html", [
     [ "Rishka SDK", "index.html", null ],
-    [ "System Calls", "md_misc_2system__calls.html", null ],
+    [ "Runtime System Calls", "md_misc_2system__calls.html", [
+      [ "Under The Hood", "md_misc_2system__calls.html#autotoc_md10", null ],
+      [ "Complete List of System Calls", "md_misc_2system__calls.html#autotoc_md11", null ]
+    ] ],
     [ "Topics", "topics.html", "topics" ],
     [ "Classes", "annotated.html", [
       [ "Class List", "annotated.html", "annotated_dup" ],

docs/navtreeindex0.js

@@ -72,6 +72,8 @@ var NAVTREEINDEX0 =
 "librishka_8h.html":[4,0,0,1],
 "librishka_8h_source.html":[4,0,0,1],
 "md_misc_2system__calls.html":[1],
+"md_misc_2system__calls.html#autotoc_md10":[1,0],
+"md_misc_2system__calls.html#autotoc_md11":[1,1],
 "memory_8h.html":[4,0,0,0,6],
 "memory_8h_source.html":[4,0,0,0,6],
 "pages.html":[],

docs/pages.html

@@ -97,7 +97,7 @@
 <div class="contents">
 <div class="textblock">Here is a list of all related documentation pages:</div><div class="directory">
 <table class="directory">
-<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md_misc_2system__calls.html" target="_self">System Calls</a></td><td class="desc"></td></tr>
+<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md_misc_2system__calls.html" target="_self">Runtime System Calls</a></td><td class="desc"></td></tr>
 </table>
 </div><!-- directory -->
 </div><!-- contents -->

docs/search/all_10.js

@@ -1,12 +1,13 @@
 var searchData=
 [
-  ['tone_0',['tone',['../class_gpio.html#afb20af73d4a9f27fc55027f950693ab5',1,'Gpio']]],
-  ['tool_1',['Using rishka-cc tool',['../index.html#autotoc_md4',1,'']]],
-  ['transfer16_2',['transfer16',['../class_s_p_i.html#a747d3de0d24155afeff9071b57fca47a',1,'SPI']]],
-  ['transfer32_3',['transfer32',['../class_s_p_i.html#a7941fffa96ff21e0c047d0b8b3335b97',1,'SPI']]],
-  ['transfer8_4',['transfer8',['../class_s_p_i.html#aeca87cf870578ed6639122474228c749',1,'SPI']]],
-  ['transfer_5fbits_5',['transfer_bits',['../class_s_p_i.html#af9f279f68f6fa78ff5c5748eef25a8e0',1,'SPI']]],
-  ['transfer_5fbytes_6',['transfer_bytes',['../class_s_p_i.html#a9a95bf4840cb3ca3caf5e0d4aa01f6c5',1,'SPI']]],
-  ['true_7',['true',['../types_8h.html#a41f9c5fb8b08eb5dc3edce4dcb37fee7',1,'types.h']]],
-  ['types_2eh_8',['types.h',['../types_8h.html',1,'']]]
+  ['the_20hood_0',['Under The Hood',['../md_misc_2system__calls.html#autotoc_md10',1,'']]],
+  ['tone_1',['tone',['../class_gpio.html#afb20af73d4a9f27fc55027f950693ab5',1,'Gpio']]],
+  ['tool_2',['Using rishka-cc tool',['../index.html#autotoc_md4',1,'']]],
+  ['transfer16_3',['transfer16',['../class_s_p_i.html#a747d3de0d24155afeff9071b57fca47a',1,'SPI']]],
+  ['transfer32_4',['transfer32',['../class_s_p_i.html#a7941fffa96ff21e0c047d0b8b3335b97',1,'SPI']]],
+  ['transfer8_5',['transfer8',['../class_s_p_i.html#aeca87cf870578ed6639122474228c749',1,'SPI']]],
+  ['transfer_5fbits_6',['transfer_bits',['../class_s_p_i.html#af9f279f68f6fa78ff5c5748eef25a8e0',1,'SPI']]],
+  ['transfer_5fbytes_7',['transfer_bytes',['../class_s_p_i.html#a9a95bf4840cb3ca3caf5e0d4aa01f6c5',1,'SPI']]],
+  ['true_8',['true',['../types_8h.html#a41f9c5fb8b08eb5dc3edce4dcb37fee7',1,'types.h']]],
+  ['types_2eh_9',['types.h',['../types_8h.html',1,'']]]
 ];

docs/search/all_11.js

@@ -4,6 +4,7 @@ var searchData=
   ['u32_1',['u32',['../types_8h.html#a449a74b72ed931d627eca7efcc6f8c9d',1,'types.h']]],
   ['u64_2',['u64',['../types_8h.html#ad9a16e74d880983f276dce5b0344b8bd',1,'types.h']]],
   ['u8_3',['u8',['../types_8h.html#ab9f930ae0484417a1883fd3f7cdb490e',1,'types.h']]],
-  ['using_20rishka_20cc_20tool_4',['Using rishka-cc tool',['../index.html#autotoc_md4',1,'']]],
-  ['usize_5',['usize',['../types_8h.html#adcb5ace4cccb93f392414ee472be10bc',1,'types.h']]]
+  ['under_20the_20hood_4',['Under The Hood',['../md_misc_2system__calls.html#autotoc_md10',1,'']]],
+  ['using_20rishka_20cc_20tool_5',['Using rishka-cc tool',['../index.html#autotoc_md4',1,'']]],
+  ['usize_6',['usize',['../types_8h.html#adcb5ace4cccb93f392414ee472be10bc',1,'types.h']]]
 ];

docs/search/all_2.js

@@ -1,11 +1,12 @@
 var searchData=
 [
   ['calloc_0',['calloc',['../class_memory.html#af8365b5845b980ce2ccc5b77369bc4a6',1,'Memory']]],
-  ['calls_1',['System Calls',['../md_misc_2system__calls.html',1,'']]],
+  ['calls_1',['Calls',['../md_misc_2system__calls.html#autotoc_md11',1,'Complete List of System Calls'],['../md_misc_2system__calls.html',1,'Runtime System Calls']]],
   ['cc_20tool_2',['Using rishka-cc tool',['../index.html#autotoc_md4',1,'']]],
   ['close_3',['close',['../class_file.html#a83cbce54d6c3b8c2f417b51f6b3f488c',1,'File']]],
   ['compiling_4',['Manually Compiling',['../index.html#autotoc_md5',1,'']]],
   ['compiling_20examples_5',['Compiling Examples',['../index.html#autotoc_md3',1,'']]],
-  ['contributing_6',['Contributing',['../index.html#autotoc_md7',1,'']]],
-  ['count_7',['count',['../class_args.html#a107b1f8ed9f9eaf269380e14f6668793',1,'Args']]]
+  ['complete_20list_20of_20system_20calls_6',['Complete List of System Calls',['../md_misc_2system__calls.html#autotoc_md11',1,'']]],
+  ['contributing_7',['Contributing',['../index.html#autotoc_md7',1,'']]],
+  ['count_8',['count',['../class_args.html#a107b1f8ed9f9eaf269380e14f6668793',1,'Args']]]
 ];

docs/search/all_7.js

@@ -1,4 +1,5 @@
 var searchData=
 [
-  ['how_20does_20it_20work_0',['How Does It Work?',['../index.html#autotoc_md0',1,'']]]
+  ['hood_0',['Under The Hood',['../md_misc_2system__calls.html#autotoc_md10',1,'']]],
+  ['how_20does_20it_20work_1',['How Does It Work?',['../index.html#autotoc_md0',1,'']]]
 ];

docs/search/all_9.js

@@ -2,5 +2,6 @@ var searchData=
 [
   ['lastwrite_0',['lastwrite',['../class_file.html#a75953d4d4e3993b6084323ea494a627f',1,'File']]],
   ['librishka_2eh_1',['librishka.h',['../librishka_8h.html',1,'']]],
-  ['license_2',['License',['../index.html#autotoc_md8',1,'']]]
+  ['license_2',['License',['../index.html#autotoc_md8',1,'']]],
+  ['list_20of_20system_20calls_3',['Complete List of System Calls',['../md_misc_2system__calls.html#autotoc_md11',1,'']]]
 ];

docs/search/all_c.js

@@ -1,6 +1,7 @@
 var searchData=
 [
-  ['on_5freceive_0',['on_receive',['../class_i2_c.html#af9ff84397093ccd077543fe01961cd5d',1,'I2C']]],
-  ['on_5frequest_1',['on_request',['../class_i2_c.html#a390ff0ee890ab39ab28cd4c543af8e9e',1,'I2C']]],
-  ['open_2',['open',['../class_file.html#a02bd0d435a62edd38c7d740d78b0e2b2',1,'File']]]
+  ['of_20system_20calls_0',['Complete List of System Calls',['../md_misc_2system__calls.html#autotoc_md11',1,'']]],
+  ['on_5freceive_1',['on_receive',['../class_i2_c.html#af9ff84397093ccd077543fe01961cd5d',1,'I2C']]],
+  ['on_5frequest_2',['on_request',['../class_i2_c.html#a390ff0ee890ab39ab28cd4c543af8e9e',1,'I2C']]],
+  ['open_3',['open',['../class_file.html#a02bd0d435a62edd38c7d740d78b0e2b2',1,'File']]]
 ];

docs/search/all_e.js

@@ -11,5 +11,6 @@ var searchData=
   ['rishka_20sdk_8',['Rishka SDK',['../group___rishka___s_d_k.html',1,'Rishka SDK'],['../index.html',1,'Rishka SDK']]],
   ['rishka_20vm_9',['Rishka VM',['../index.html#autotoc_md2',1,'']]],
   ['rmdir_10',['rmdir',['../class_f_s.html#a24f4d7fe44e698f6467ce673be778de5',1,'FS']]],
-  ['rune_11',['rune',['../types_8h.html#a405b10d09d9298aac12e28a2e92c4641',1,'types.h']]]
+  ['rune_11',['rune',['../types_8h.html#a405b10d09d9298aac12e28a2e92c4641',1,'types.h']]],
+  ['runtime_20system_20calls_12',['Runtime System Calls',['../md_misc_2system__calls.html',1,'']]]
 ];

docs/search/pages_0.js

@@ -1,4 +1,4 @@
 var searchData=
 [
-  ['calls_0',['System Calls',['../md_misc_2system__calls.html',1,'']]]
+  ['calls_0',['Runtime System Calls',['../md_misc_2system__calls.html',1,'']]]
 ];

docs/search/pages_1.js

@@ -1,4 +1,5 @@
 var searchData=
 [
-  ['rishka_20sdk_0',['Rishka SDK',['../index.html',1,'']]]
+  ['rishka_20sdk_0',['Rishka SDK',['../index.html',1,'']]],
+  ['runtime_20system_20calls_1',['Runtime System Calls',['../md_misc_2system__calls.html',1,'']]]
 ];

docs/search/pages_2.js

@@ -1,5 +1,5 @@
 var searchData=
 [
   ['sdk_0',['Rishka SDK',['../index.html',1,'']]],
-  ['system_20calls_1',['System Calls',['../md_misc_2system__calls.html',1,'']]]
+  ['system_20calls_1',['Runtime System Calls',['../md_misc_2system__calls.html',1,'']]]
 ];