abi.html

<!Doctype html>
<html lang="en">
    <head>
        <title>ABI Interface</title>
        <meta charset="UTF-8">
        <!--<link rel="stylesheet" href="css/bootstrap.min.css">-->
        <link rel="stylesheet" href="css/style_new.css">
        <script src="js/jquery-1.12.1.min.js" charset="utf-8"></script>
        <link rel="stylesheet" href="js/embed-2cd369fa1c0830bd3aa06c21d4f14a13e060d2d31bbaae740f4af4.css"><div id="gist28627206" class="gist"></div>
        <link rel="stylesheet" href="js/embed-cbe5b40fa72b0964f90d4919c2da8f8f94d7c9f6c2aa49c07f6fa3.css"><div id="gist28627206" class="gist"></div>
    </head>
    <div class="container">
        <header id="navtop">
            <a href="index.html" class="logo fleft"><img src="img/logo.png" alt=""></a>
            <nav class="fright">
                <ul>
                    <li><a href="index.html">Home</a></li>
                    <li><a href="about.html">About</a></li>
                      <!--  <li><a href="help.html">Help</a></li> -->
                        <li><a href="roadmap.html">Roadmap</a></li>
                        <li><a href="documentation.html" class="navactive">Documentation</a></li>
                </ul>
            </nav>
        </header>
        <div class="Services-page main grid-wrap">
            <header class="grid col-full">
                <hr/>
                <p class="fleft">Application Binary Interface</p>
                <br>
                <br>
                <!-- <a class="button" href="">Download as PDF</a> -->
            </header>
            <aside class="grid col-one-quarter mq2-col-full sticky_sidebar" style="position: static;">
              <menu>
                <ul>
                  <li><a class="sec" href="#nav-introduction">Introduction</a></li>
                  <li><a class="sec" href="#nav-XSM-instruction-set">The XSM virtual machine instruction set</a></li>
                  <li><a class="sec" href="#nav-virtual-address-space-model">The virutal address space model</a></li>
                  <li><a class="sec" href="#nav-XEXE-executable-file-format">XEXE executable file format</a></li>
                  <li><a class="sec" href="#nav-eXpOS-system-library-interface">The library interface</a></li>
                  <li><a class="sec" href="#nav-lowlevel-syscall-interface">Low level System call Interface</a></li>

              </ul>
              </menu>
            </aside>
            <section class="grid col-three-quarters mq2-col-full">
                <div class="grid-wrap">
                <article class="grid col-full" id="nav-introduction">
                    <h2>Introduction</h2>
                    <p>
                        The ExpL compiler needs to translate a given source program and generate the <b>target machine code</b> into an <b>executable file</b> in a format which is recognized by the load module of the target operating system. Thus, in order to generate the executable, the following information needs to be made available to the compiler :
                    </p>
                    <ol>
                        <li>The <b>virtual machine model</b> and the <b>instruction set</b> of the target machine.</li>
                        <li>The (virtual) <b>address space</b> model available for the target program. Conventionally, this address space is logically divided into regions like <b>code, data, stack, heap</b> etc.</li>
                        <li>The format for the target file (<b>executable format</b>). The compiler typically passes information regarding the sizes and address regions allocated to the code, data, stack, text and heap regions to the loader by setting appropriate values in the <b>header</b> of the executable file.</li>
                        <li><b>Interfaces to OS (kernel) routines</b> that needs to be invoked to get certain operations like input/output done. This is specified in <a href="#nav-eXpOS-system-library-interface">the library interface</a> documentation.</li>
                    </ol>
                    <p>
                        <b>These specifications depend not only on the target machine architecture, but also on the operating system</b> upon which the target machine code must execute. Typically these specifications are collected together in the OS specification into a document called the Application Binary Interface (ABI).
                    </p>
                    <p>
                        The following sections specify the ABI for the <a href="http://exposnitc.github.io/">eXpOS operating system</a> run on the <a href="http://exposnitc.github.io/virtual_machine_spec.html">XSM virtual machine model</a>. The executable format is called the XEXE executable format.
                    </p>
                </article>
                <article class="grid col-full" id="nav-XSM-instruction-set">
                    <h2> The XSM virtual machine model and instruction set</h2>
                    <p>
                        The virtual machine model provided to user level programs by the ExpOS on the  machine is described here. The virtual machine model explains the "view" of the machine provided to the application by the operating system.
                    </p>
                    <p>
                        The XSM virtual machine contains 20 general purpose registers (R0-R19) and three special registers - Stack pointer (SP), Base pointer (BP) and the Instruction pointer (IP).  The SP register is normally used to point to the top of the application program's stack.  The BP register is used to point to the base of the activation record of the currently executing function.  IP points to the next instruction in the user memory to be fetched and executed.  The memory address space available to the application is of 5120 words starting at (virtual) address 0 and ending at (virtual) address 5119.
                    </p>
                    <p>
                        The OS stipulates that this virtual address space must be divided into various regions called library, code, heap and stack. These will be described in detail later. The virtual machine model also allows the application to invoke traps to the operating system kernel for read, write and program termination (using the INT instruction).  The details of the implementation of the kernel routines are hidden from the application and the application needs to know only the interface to invoke these routines.  These interfaces will also be described later in this documentation.
                    </p>
                    <p>
                        The following figure gives a high level picture of the XSM virtual machine model.<br>
                    </p>
                    <p>
                        <img src="img/architecturemodel.png">
                    </p>

                    <p>
                        The XSM virtual machine instruction set specifies the set of assembly level instructions.  The compiler must translate the source ExpL program to a target program containing only these instructions.  The assembly instructions allowed include Data Transfer Instructions, Arithmetic Instructions, Logical Instructions, Stack Instructions, Sub-routine instructions, Debug instructions and Software interrupts. The machine registers available to the target program are R0-R19, SP, BP and IP.
                    </p>
                    <h4>Data Transfer Instructions</h4>
                    <table class="doctable" style="text-align:left;">
                        <tbody>
                            <tr>
                                <th>Addressing Type</th>
                                <th>Syntax</th>
                                <th>Semantics</th>
                            </tr>
                            <tr>
                                <td>Register Adressing</td>
                                <td>MOV Ri, Rj</td>
                                <td>Copies the contents of register Rj to Ri</td>
                            </tr>
                            <tr>
                                <td>Immediate Addressing</td>
                                <td>MOV Ri, INTEGER/STRING</td>
                                <td>Copies the INTEGER/STRING to the register Ri</td>
                            </tr>
                            <tr>
                                <td rowspan="2">Register Indirect Addressing</td>
                                <td>MOV Ri, [Rj]</td>
                                <td>Copy contents of memory location pointed by Rj to register Ri.</td>
                            </tr>
                            <tr>
                                <td>MOV [Ri], Rj</td>
                                <td>Copy contents of Rj to the location whose address is in Ri</td>
                            </tr>
                            <tr>
                                <td rowspan="2">Direct Addressing</td>
                                <td>MOV [LOC], Rj</td>
                                <td>Copy contents of Rj to the memory address LOC</td>
                            </tr>
                            <tr>
                                <td>MOV Rj, [LOC]</td>
                                <td>Copy contents of the memory location LOC to the register Rj</td>
                            </tr>
                            <!-- <tr>
                                <td rowspan="4">Direct Indexed Addressing</td>
                                <td>MOV [LOC] Rj, Ri</td>
                                <td>Copy contents of Ri to the memory address LOC + (value in Rj)</td>
                            </tr>
                            <tr>
                                <td>MOV [LOC] Index, Rj</td>
                                <td>Copy contents of Rj to the memory address LOC + Index. Index must be an integer value</td>
                            </tr>
                            <tr>
                                <td>MOV Ri, [LOC] Rj</td>
                                <td>Copy contents in the memory address LOC + (value in Rj) to the register Ri</td>
                            </tr>
                            <tr>
                                <td>MOV Ri, [LOC] Index</td>
                                <td>Copy contents of the memory address LOC + Index to the register Ri. Index must be an integer value</td>
                            </tr> -->
                        </tbody>
                    </table>
                    <br/>
                    <h4>Arithmetic Instructions</h4>
                    <p>
                        Arithmetic Instructions perform arithmetic operations on registers containing integers. If the register contains a non-integer value, an exception (illegal instruction) is raised.
                    </p>
                    <table class="doctable" style="text-align:left;">
                        <tbody>
                            <tr>
                                <th>Instruction</th>
                                <th>Syntax</th>
                                <th>Semantics</th>
                            </tr>
                            <tr>
                                <td rowspan="2">ADD, SUB, MUL, DIV and MOD</td>
                                <td>OP Ri, Rj</td>
                                <td>The result of Ri op Rj is stored in Ri</td>
                            </tr>
                            <tr>
                                <td>OP Ri, INTEGER</td>
                                <td>The result of Ri op INTEGER is stored in Ri</td>
                            </tr>
                            <tr>
                                <td>INR, DCR</td>
                                <td>OP Ri</td>
                                <td>Increments/Decrements the value of register Ri by 1</td>
                            </tr>
                        </tbody>
                    </table>
                    <p>
                        For all the above instructions, Ri/Rj may be any register except IP.
                    </p>
                    <br/>
                    <h4>Logical Instructions</h4>
                    <p>
                        Logical instructions are used for comparing values in registers. Strings can also be compared according to the lexicographic ordering of ASCII. If one of the operands is a string, the other operand will also be considered as a string. The logical instructions are LT, GT, EQ, NE, GE and LE.
                    </p>
                    <table class="doctable" style="text-align:left">
                        <tbody>
                            <tr>
                                <th>Type</th>
                                <th>Syntax</th>
                                <th>Semantics</th>
                            </tr>
                            <tr>
                                <td>LT, GT, EQ, NE, GE, LE</td>
                                <td>OP Ri, Rj</td>
                                <td>Stores 1 in Ri if the value stored in Ri is less than/greater than/equal to/not equal to/greater than or equal to/less than or equal to that in Rj. Ri is set to 0 otherwise</td>
                            </tr>
                        </tbody>
                    </table>
                    <br/>
                    <h4>Branching Instructions</h4>
                    <p>
                        Branching is achieved by changing the value of the IP to the word address of the target instruction specified by 'target_address'.
                    </p>
                    <table class="doctable" style="text-align:left">
                        <tbody>
                            <tr>
                                <th>Type</th>
                                <th>Syntax</th>
                                <th>Semantics</th>
                            </tr>
                            <tr>
                                <td>JZ</td>
                                <td>JZ Ri, target_address</td>
                                <td>Jumps to target_address if the contents of Ri is zero</td>
                            </tr>
                            <tr>
                                <td>JNZ</td>
                                <td>JNZ Ri, target_address</td>
                                <td>Jumps to target_address if the contents of Ri is not zero</td>
                            </tr>
                            <tr>
                                <td>JMP</td>
                                <td>JMP target_address</td>
                                <td>Unconditional jump to target_address</td>
                            </tr>
                        </tbody>
                    </table>
                    <br/>
                    <h4>Stack Instructions</h4>
                    <table class="doctable" style="text-align:left">
                        <tbody>
                            <tr>
                                <th>Type</th>
                                <th>Syntax</th>
                                <th>Semantics</th>
                            </tr>
                            <tr>
                                <td>PUSH</td>
                                <td>PUSH Ri</td>
                                <td>Increment SP by 1 and copy contents of Ri to the location pointed to by SP</td>
                            </tr>
                            <tr>
                                <td>POP</td>
                                <td>POP Ri</td>
                                <td>Copy contents of the location pointed to by SP into Ri and decrement SP by 1</td>
                            </tr>
                        </tbody>
                    </table>
                    <p>
                        For both these instructions Ri may be any register except IP.
                    </p>
                    <br/>
                    <h4>Subroutine Instructions</h4>
                    <p>
                        The CALL instruction copies the address of the next instruction to be fetched(this value must be IP + 2 since each instruction is two memory words) on to location SP + 1. It also increments SP by one and transfers control to the instruction specified by the target_address. The RET instruction restores the IP value stored at location pointed by SP, decrements SP by one and continues execution fetching the next instruction pointed to by IP
                    </p>


                    <table class="doctable" style="text-align:left">
                        <tbody>
                            <tr>
                                <th>Type</th>
                                <th>Syntax</th>
                                <th>Semantics</th>
                            </tr>
                            <tr>
                                <td>CALL</td>
                                <td>CALL target_address/ Register</td>
                                <td>Increments SP by 1, transfers IP + 2 to location pointed to by SP and jumps to instruction specified by target_address(or register containing the target address)</td>
                            </tr>
                            <tr>
                                <td>RET</td>
                                <td>RET</td>
                                <td>Sets IP to the value pointed to by SP and decrements SP</td>
                            </tr>
                        </tbody>
                    </table>
                    <br><br>
                    <h4 id="nav-debug">Debug Instruction</h4>
                        <p>
                            <i>Syntax</i> : BRKP<br>
                            <i>Semantics</i> : The machine when run in <a href="xsmusagespec.html#nav-debug" target="_blank"> debug mode </a> invokes the debugger when this intruction is executed. This instruction can be used for debugging system code.<br>
                        </p><br/>
                    <h4 id = "nav-int">Software Interrupt</h4>
                        <p>
                            <i>Syntax</i> : INT n<br>
                            <i>Semantics</i> : Generates an interrupt to the kernel with the interrupt number (n between 4 to 18) as an argument. The interrupt numbers relevant to the present project are given below.
                        </p>
                        <p>
                            <table class="doctable">
                            <tr>
                                <th>System Call</th>
                                <th>Interrupt Routine Number</th>
                            </tr>
                            <tr>
                                  <td >Read</td>
                                  <td >6</td>
                              </tr>
                            <tr>
                                  <td >Write</td>
                                  <td >7</td>
                              </tr>
                            <tr>
                                  <td >Exit</td>
                                  <td >10</td>
                              </tr>
                            </table>
                        </p>
                </article>
                <article class="grid col-full" id="nav-virtual-address-space-model">
                    <h2>The virtual address space model</h2>
                    <p>
                        The (virtual) address space of any eXpOS process is logically divided into four parts namely Library, Heap, Code and Stack.
                    </p>
                    <center><img src="img/memory_model_1.png" alt="" style="margin-left:-20%;"/></center>
                    </br>
                    <p>
                        The <b>Library</b> contains routines for implementing dynamic memory allocation functions Alloc(), Free() and Initialize() as well as the input output functions Read() and Write().  The eXpOS loader links the library routines at load time when a program is loaded into the memory for execution.  The compiler can therefore assume that the library code will be "there" at run-time and hence need not generate the code for implementing the library.  The compiler however must generate code to invoke the correct library routines with appropriate arguments while translating the high level functions Alloc(), Free(), Initialize(), Read() and Write(). The ABI specifies how this must be done.  Among these, Alloc(), Free() and Initialize() are implemented as part of the library itself.  The library will re-direct Read() and Write() to low level OS system calls. (One of the advanced stages of the ExpL project will ask you to implement the library itself.) The ABI stipulates that eXpOS will load the library between addresses 0 and 1023 of the address space.  Note that since each XSM instruction takes up two memory words, the library can be of size at most 512 instructions.
                    </p>
                    <p>
                        <b>Heap</b> is the portion of the address space reserved as the memory pool from which dynamic memory allocation is done by the allocator routine (Alloc() function) of the library.  The memory region between addresses 1024 and 2047 is reserved for the heap.  The routine Initialize() will intialize the data structures associated with the memory allocator, Alloc() will allocate memory and Free() will de-allocate a previously allocated memory block.  A discussion on dynamic memory allocation and de-allocation can be found <a href="http://silcnitc.github.io/run_data_structures/heap.html" target="_blank">here</a>.
                    </p>
                    <p>
                        The <b>Code</b> region contains the target assembly language program generated by the compiler. The OS loader loads the contents of an <a href="#nav-XEXE-executable-file-format">XEXE executable file</a> into this region (between memory addresses 2048 and 4095) of the address space.  The loader expects that the first eight words of the XEXE executable file contains a <i>header</i>. The header contains instructions to the loader like the address of the first instruction to be executed (the loader will initalize the instruction pointer to this value before execution) and so on. The total size of the code section (including the 8 word header) cannot exceed 2048 words. Since each XSM instruction occupies two words in the memory, the maximum number of assembly instructions permitted in any target program generated by the compiler shall be 1020.  Given an ExpL program as input, the job of the compiler is to generate an XEXE executable file containing the header and the target assembly language program.
                    </p>
                    <p>
                        <b>Stack</b> is the space reserved for the runtime stack of a program. Parameters and local variables associated with functions in a program are allocated in the stack. In the XSM architecture, the stack grows upwards.  The eXpOS ABI stipulates that the maximum stack size is 1024 words. Global variables must be allocated in the stack as the eXpOS ABI does not support a separate <a href="https://en.wikipedia.org/wiki/Data_segment" target="_blank">Data region</a>. The ABI stipulates that the compiler must allocate stack in the region between memory addresses 4095 and 5119 in the address space of the program.  A discussion on how the compiler must allocate variables in the stack can be found <a href="http://silcnitc.github.io/run_data_structures/run-time-stack.html" target="_blank">here</a>.
                    </p>
                </article>
                <article class="grid col-full" id="nav-XEXE-executable-file-format">
                    <h2>XEXE executable file format</h2>
                    <p>
                        The compiler must generate target code into a file in the format specified below so that the eXpOS loader recognizes the format and load the program into memory for execution correctly.   Each executable file contains a header in which the compiler adds information like the initial value to be given to the stack pointer in the virtual address space, initial value of the instruction pointer etc, the starting (virtual) addresses and sizes of various memory regions like text, stack, heap etc.
                    </p>
                    <p>
                        Executable files in eXpOS must be in the XEXE format as eXpOS executes only files of such format. An XEXE executable file in eXpOS consists of two parts:
                    </p>
                    <ul>
                        <li>Header</li>
                        <li>Code</li>
                    </ul>
                    <img src="img/exe_file.jpeg" alt="" />
                    <p>
                        The maximum size of the file (including the header) is limited by 2048 words.
                    </p>
                    <p>
                        The first eight words of an executable file are reserved for the header which describes the features of file. The structure of the header is :
                    </p>
                    <img src="img/header.png" alt="" />
                    <p>
                        <b>XMAGIC</b> is a number indicating the type of executable file. All XEXE files will have magic number 0. For more on Magic Number, click <a href="https://en.wikipedia.org/wiki/File_format#Magic_number" target="_blank"> here</a>.
                    </p>
                    <p>
                        <b>Entry point</b> contains the virtual address in memory of the first instruction to be executed (entry point) of the program after the OS loader has loaded it. During loading, the instruction pointer must be initialized to this address.
                    </p>
                    <p>
                        <b>Text Size, Data Size, Heap Size</b> and <b>Stack size</b> indicates the sizes of Text, Data, Heap and Stack regions to be allocated by the OS loader when the file is loaded for execution.
                    </p>
                    <p>
                        Note : The present eXpOS virtual address space model requires that the data and stack must be in the same memory area and must be managed by the compiler / application program (this means that the program must contain the code to initialize the value of the stack pointer). The value of Data Size field is ignored. Moreover, the eXpOS loader sets the size of text region to 2048 words and stack region to 1024 words in memory irrespective of the values present in the header.
                    </p>
                    <p>
                        If the <b>Runtime Library</b> must be included when the file is loaded, the Library Flag is set to 1 in the executable file. If this flag is not set then neither memory is allocated for the heap nor the library linked to the address space of the process at execution time.
                    </p>
                    <p>
                        In summary, the eXpOS loader maps an executable file into its virtual address according to the following table :
                    </p>
                    <table class="doctable">
                        <tbody>
                            <tr class="success">
                                <th style="text-align: center;">Region</th>
                                <th style="text-align: center;">Start Address</th>
                                <th style="text-align: center;">End Address</th>
                            </tr>
                            <tr>
                                <td>Library<!--<sup style="color:red">*</sup>--></td>
                                <td>0</td>
                                <td>1023</td>
                            </tr>
                            <tr>
                                <td>Heap</td>
                                <td>1024</td>
                                <td>2047</td>
                            </tr>
                            <tr>
                                <td>Code</td>
                                <td>2048</td>
                                <td>4095</td>
                            </tr>
                            <tr>
                                <td>Stack<sup style="color:blue">†</sup></td>
                                <td>4096</td>
                                <td>5119</td>
                            </tr>
                        </tbody>
                    </table>
                  <!--  <p><span style="color:red">*</span> If Library Flag is set to 1 in the executable header.</p> -->
                    <p><span style="color:blue">†</span> The Stack Pointer is not initialised to the address 4096 by the eXpOS loader.</p>
                </article>
                <article class="grid col-full" id="nav-eXpOS-system-library-interface">
                    <h2>The library interface</h2>
                    <p>
                        The library provides a <b>uniform  interface</b> through which an application program can invoke dynamic memory allocation / de-allocation routines (Alloc(), Free() and Initialize()), input - output routines (Read() and Write()) and program exit (Exit()).  Thus, while translating a high level ExpL program containing calls to the above functions, a compiler needs to be concerned only about how to translate these high level function calls to the corresponding library function calls.
                    </p>

                    <p>
                        <center> <img src="./img/memory_management.png" style="width:350px !important"></center>
                        <br>
                    </p>
                    <p>
                        The ABI stipulates that all calls to the library functions must be translated by the compiler to a CALL to virtual address 0, with an appropriate function code that identifies the service requested (Alloc(), Free(), Initalize(), Read(), Write() or Exit()). This is because the library is linked to <b>virtual address 0</b> of the address space of a process by the OS loader.  A call to the library requires four arguments (a function code to identify the service and three arguments) to be passed through the stack. The library will invoke the corresponding low level system call / memory management routine and returns to the user program the return value of the system call / memory management routine through the stack. The figure above shows the contents of the stack immediately before a call to this library routine.
                    </p>

                    <h3 style="clear:right">Invoking a library module</h3>

                    <script src="js/f20916a0b864642f1cb04ff2ceebe46c.js"></script>
                    <p>
                        A library module invocation using the high level application programmer's interface of a programming language like ExpL must be translated by the compiler to a set of machine instructions as given above.
                    </p>
                    <p>
                        Following are the library functions and details relevant for ExpL Compilation:
                    </p>
                    <p>
                        <table class="doctable">
                            <tr>
                                <th>Library Function</th>
                                <th>Function Code</th>
                                <th>Argument 1</th>
                                <th>Argument 2</th>
                                <th>Argument 3</th>
                                <th>Return Values</th>
                            </tr>
                            <tr>
                                  <td rowspan="3">Read</td>
                                  <td rowspan="3">"Read"</td>
                                  <td rowspan="3">-1</td>
                                  <td rowspan="3">Buffer (int/str)<font color="red">*</font></td>
                                  <td rowspan="3">-</td>
                                  <td>0 - Success</tr>
                                  <td>-1 - File Descriptor given is invalid</tr>
                                  <td>-2 - Read error</tr>
                              </tr>
                            <tr>
                                  <td rowspan="2">Write</td>
                                  <td rowspan="2"> "Write"</td>
                                  <td rowspan="2">-2</td>
                                  <td rowspan="2">Data<font color="red">+</font></td>
                                  <td rowspan="2">-</td>
                                  <td>0 - Success</tr>
                                  <td>-1 - File Descriptor given is invalid</tr>
                              </tr>
                            <tr class = "active">
                                  <td rowspan="1">Exit</td>
                                  <td rowspan="1">"Exit"</td>
                                  <td rowspan="1">-</td>
                                  <td rowspan="1">-</td>
                                  <td rowspan="1">-</td>
                                  <td>-</tr>
                              </tr>
                            <tr class = "active">
                                  <td rowspan="2">Initialize</td>
                                  <td rowspan="2">"Heapset"</td>
                                  <td rowspan="2">-</td>
                                  <td rowspan="2">-</td>
                                  <td rowspan="2">-</td>
                                  <td>0 - Success</tr>
                                  <td>-1 - Failure</tr>
                              </tr>
                              <tr class = "active">
                                  <td rowspan="2">Alloc</td>
                                  <td rowspan="2">"Alloc"</td>
                                  <td rowspan="2">Size (int)</td>
                                  <td rowspan="2">-</td>
                                  <td rowspan="2">-</td>
                                  <td>Address in the heap allocated (int) </tr>
                                  <td>-1 - No allocation</tr>
                              </tr>
                              <tr class = "active">
                                  <td rowspan="2">Free</td>
                                  <td rowspan="2">"Free"</td>
                                  <td rowspan="2">Pointer (int)</td>
                                  <td rowspan="2">-</td>
                                  <td rowspan="2">-</td>
                                  <td>0 - Success</tr>
                                  <td>-1 - Failure</tr>
                              </tr>
                        </table>
                        <sup>
                            *Note:  The Read() library function expects a memory address from (or to) which read is performed.
                            <br>
                            +Note:  The Write() library function expects Data (final value to be printed) as argument.
                        </sup>
                    </p>

                    <h3 style="clear:left">After return from the library module </h3>
                    <p>
                        The following machine instructions are present after the CALL instruction in the ExpL compiled machine code given in the previous step.
                    </p>
                    <script src="js/7cab9602bc70ca74fefbc7956a53fe93.js"></script>
                    <p>
                        The machine code shown above is executed upon return from the library call and pops out the values that were pushed before the call. The function code and arguments were inputs to the library module and hence they may be discarded now. The return value which is stored in the stack by the system call must be popped out and saved to some register.  This value will be the only relevant information after return from the call.
                    </p>
                    <p>
                        Note:  The eXpOS library interface permits many more functions (interfaces to eXpOS system calls).  Since these functions are not relevant for the implementation of the ExpL specification here, those details are left out.  The full details of eXpOS library are given <a href="http://exposnitc.github.io/os_spec-files/dynamicmemoryroutines.html" target="_blank">here</a>.
                    </p>
                 </article>

                <article class="grid col-full" id="nav-lowlevel-syscall-interface">
                    <h2>Low Level System Call Interface</h2>
                    <p>
                        The ExpL library file <i>library.lib</i> contains assembly instructions to implement the library functions
                        <i>Alloc(), Free() and Initialize()</i>.  For the input/output functions Read()/Write() as well as the program exit system call Exit(), the library code invokes the corresponding ExpOS system calls for console read/write/exit. Thus, the library simply converts the library call to a low level call to the operating system. This is because console input/ouput functions are implemented at the OS level.
                    </p>

                    <p>
                        In order to implement the library, one must know the low level system call interface to the operating
                        system so that the input/ouput calls to the library can be correctly translated to the corresponding
                        low level OS system calls.  This section specifices the low level OS interface provided by the ExpOS
                        Operating System running on the XSM machine architecture.  The interface describes the software interrupt instruction (trap) corresponding to the consolve input/output system calls and the calling conventions for passing arguments and extracting return values of the system call through the application program's stack. This part is architecture as well as operating system dependent.
                    </p>

                    <h3>System Calls</h3>

                    <p>
                        For an application program, there are two stages in executing a system call:
                    </p>

                    <ul id="otis">
                        <li>1. <b>Before the system call</b> :   The calling application must set up the arguments in the (user) stack before executing the trap instruction.  </li>
                        <li>2. <b>After the system call</b> :   The return value of the system call must be extracted from the stack.  </li>

                    </ul>

                    <h3>Invoking a system call</h3>
                      <p>
                        A user program invokes a system call by first pushing the system call number and then the arguments into the stack and then invoking the <b>INT</b> machine instruction corresponding to the system call. The eXpOS ABI stipulates that the number of arguments pushed into the stack is fixed at three.
                    </p>
                    <p>
                        <pre style = "float:right;width:600px">
    PUSH System_Call_Number     // Push system call number
    PUSH Argument_1             // Push argument 1 to the stack
    PUSH Argument_2             // Push argument 2 to the stack
    PUSH Argument_3             // Push argument 3 to the stack
    <b>PUSH R0                     // Push an empty space for RETURN VALUE</b>
    INT number                  // Invoke the corresponding INT instruction.
                                // The number can be any number between 4 and 18
                        </pre>
                        The ExpL library must translate Read() and Write() calls to a set of machine instructions (see the instructions to the right). These are the stack operations that must be performed by the user program before the INT instruction is executed.
                    </p>
                    <br/>
                    <div>
                        <p style="clear:right">
                            <img src="img/system_call_stack1.png" style="float:left;margin-right:3px;width:350px !important;height:350px !important">
                            <br/><br/>
                            The arguments must be pushed into the stack in  such a way that the last argument comes on the top. An additional push instruction ('PUSH R0') is inserted to have an empty space in the stack for the return value. The system call implementation stores the return value in this space. The system call number must be pushed to the stack before the call because the interrupt routine needs this value to identify the system call. The figure to the left shows the data stored in stack just before an INT instruction.
                        </p>
                     </div>

                    <div style="clear:left">
                        <p>
                            <img src="img/system_call_stack2.png" style="float:right;margin-left:3px;width:350px !important;height:350px !important">
                            <br/>The INT instruction in XSM will push the value of IP + 2 on to the stack. This is the address of the instruction immediately following the INT instruction in the calling program. Each instruction is 2 words, hence IP is incremented by 2. Upon execution of the IRET instruction from the system call, execution resumes from this value of IP. The INT instruction changes mode from <b>User</b> mode to <b>Kernel</b> mode and passes control to the Interrupt Routine corresponding to the system call. The figure to the right shows the contents of the stack immediately after the execution of the INT instruction.
                        </p>
                    </div>

                    <br/>

                    <h3 style="clear:right">After return from the system call</h3>

                    <p>
                        The IRET instruction transfers control back to the instruction that immediately follows the INT instruction. The following machine instructions are present after the INT instruction in the ExpL compiled machine code given in the previous step.
                    </p>

                    <div>
                        <p>
                            <pre style="float:left;margin-right:5px">
    POP Ri           // Pop and save the return value into some register Ri
    POP Rj           // Pop and discard argument 3
    POP Rj           // Pop and discard argument 2
    POP Rj           // Pop and discard argument 1
    POP Rj           // Pop and discard the system call number
                     // Now the stack is popped back to the state before call
                            </pre>

                            The machine code to the left pops the values from the stack. The system call number and arguments were inputs to the system call and hence they may be discarded now. The return value which is stored in the stack by the system call is fetched and used by the user program by popping out to some register.
                        </p>

                        <h3 style="clear:left">System calls and their translation</h3>
                        <p>
                            Associated with each system call, there is a system call number and interrupt routine number. The system call number is used to identify a system call. The interrupt routine number denotes the number of the interrupt routine which  handles the system call.
                        </p>
                        <p id="syscalltable">
                            <table class="doctable">
                            <tr>
                                <th>System Call</th>
                                <th>System Call Number</th>
                                <th>Interrupt Routine Number</th>
                                <th>Argument 1</th>
                                <th>Argument 2</th>
                                <th>Argument 3</th>
                                <th>Return Values</th>
                            </tr>
                            <tr>
                                  <td rowspan="3">Read</td>
                                  <td rowspan="3">7</td>
                                  <td rowspan="3">6</td>
                                  <td rowspan="3">-1</td>
                                  <td rowspan="3">Buffer (int/str)<font color="red">*</font></td>
                                  <td rowspan="3">-</td>
                                  <td>0 - Success</tr>
                                  <td>-1 - File Descriptor given is invalid</tr>
                                  <td>-2 - Read error</tr>
                              </tr>
                            <tr>
                                  <td rowspan="2">Write</td>
                                  <td rowspan="2">5</td>
                                  <td rowspan="2">7</td>
                                  <td rowspan="2">-2</td>
                                  <td rowspan="2">Data<font color="red">+</font></td>
                                  <td rowspan="2">-</td>
                                  <td>0 - Success</tr>
                                  <td>-1 - File Descriptor given is invalid</tr>
                              </tr>
                            <tr>
                                  <td rowspan="1">Exit</td>
                                  <td rowspan="1">10</td>
                                  <td rowspan="1">10</td>
                                  <td rowspan="1">-</td>
                                  <td rowspan="1">-</td>
                                  <td rowspan="1">-</td>
                                  <td>-</tr>
                              </tr>
                            </table>
                            <sup>
                                *Note:  The Read() library function expects a memory address from (or to) which read is performed.
                                <br>
                                +Note:  The Write() library function expects Data (final value to be printed) as argument.
                            </sup>
                        </p>
                    </div>
                </article>
                </div>
            </section>
        </div>
        <script src="js/sticky_sidebar.js" charset="utf-8"></script>
    </div>
  

    <footer class="center part clearfix">
            <ul class="grid col-one-third social">
                <li><a href="http://github.com/silcnitc">Github</a></li>
                <li>  <a rel="license" href="http://creativecommons.org/licenses/by-nc/4.0/">
                    <img alt="Creative Commons License" style="border-width:0" src="img/creativecommons.png" /></a></li>
            </ul>
            <div class="grid col-one-third" style="color:black;">
                <p style="font-weight: bold;">Contributed By : <a href="https://www.linkedin.com/in/dattathallam">Thallam Sai Sree Datta</a>, <a href="https://www.linkedin.com/in/n-ruthviik-0a0539100">N Ruthvik</a>
                </p>
            </div>
            <nav class="grid col-one-third ">
                <ul >
                    <li><a href="index.html">Home</a></li>
                    <li><a href="about.html">About</a></li>
                    <!-- <li><a href="uc.html">Contact</a></li> -->
                </ul>
            </nav>
            <br>
        </footer>


    <script>window.jQuery || document.write('<script src="js/jquery-1.7.2.min.js"><\/script>')</script>
    <script src="js/scripts.js"></script>
    <script src="js/inject.js"></script>
</html>