Oak.js/manual.html at master · loshya/Oak.js · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
<!doctype HTML>
<html>
    <head>
        <title>Oak.js - Manual</title>
        <meta charset="UTF-8">
        <link rel="stylesheet" type="text/css" href="Styles/style.css"></link>
        <link rel="stylesheet" type="text/css" href="Styles/dos.css" id="theme2" disabled></link>
        <link rel="stylesheet" type="text/css" href="Styles/dark.css" id="theme1" disabled></link>
        <link rel="stylesheet" type="text/css" href="Styles/light.css" id="theme0"></link>

        <link rel="icon" type="image/png" sizes="16x16" href="Images/favicon.ico">
    </head>
    <body>
        <header>
            <a href="https://skyus.github.io/Oak.js/"><img src='Images/iconShadow.png' /></a><a class='noFloat' href="https://github.com/Skyus/Oak.js">Source</a>
            <select id='themes'>
                <option value='0'>Light Theme</option>
                <option value='1'>Dark Theme</option>
                <option value='2'>DOS</option>
            </select>
        </header>
        <main class='helpMain'>
            <h2>Oak.js Manual</h2>
            <p>
                Oak.js is a web-based assembler, disassembler and simulator for the RISCV instruction set architecture. It is designed after version 2.1 and currently supports most of the RV32I base integer instruction set.
            </p>
            <p>
                Oak.js starts executing from address 0 and implements an "amorphous" structure; i.e., there is no distinction between program data and machine code in binary files. It is the programmer's responsibility to make sure static data is not interpreted as instructions (to halt execution, see environment call 10).
            </p>
            <h3>Instruction Support</h3>
            <h4>RISC-V</h4>
            <p>
                Oak.js supports the RV32I base integer instruction set, save for the following instructions:
            </p>
            <p><i>
                fence, fence.i, ebreak, csrrw, csrrs, cssrc, csrrwi, csrrsi, csrrci
            </i></p>
            <h4>MIPS</h4>
            <p>
                MIPS support is in progress.
            </p>
            <h4>Pseudoinstructions</h4>
            <p>
                As a limitation of Oak.js's architecture, very few pseudoinstructions are supported, and they all expand into only one instruction. The currently supported pseudoinstructions are li, mv, la, jr, scall, and syscall (the last two just mirror ecall).
            </p>
            <h4>Environment Calls</h4>
            <p>
                The calling convention for RISC-V is as follows:
            </p>
            <p>
                a7 - Service Number <br />
                a0-a6 - Arguments
            </p>
            <p>
                The return value will be placed in a7 as well. This was a project requirement- ideally the return value would be in another register.
            </p>
            <p>
                Oak.js supports four environment calls at the moment.
                <ul>
                    <li><b>1: Print Integer.</b> Arguments: 0 - Integer to print.  Prints integer to console.</li>
                    <li><b>4: Print String.</b> Arguments: 0 - Address of string to print in memory.  Prints string to console.</li>
                    <li><b>5: Read Integer.</b> Arguments: None.  Reads integer from user, stores in a7.</li>
                    <li><b>8: Read String.</b> Arguments: 0 - Address in memory to read string to.</li>
                    <li><b>10: Exit.</b> Arguments: None. Concludes execution of the current program.</li>
                </ul>
            </p>
            <h3>Usage</h3>
            <p>
                Input text into the main editor field. Assemble using the <img src="Images/assembleHelp.png" style="height: 16pt; vertical-align:middle;" /> button. Then you can press <img src="Images/playHelp.png" style="height: 16pt; vertical-align:middle;" /> start simulation.
            </p>
            <p>
                You can create new tabs to manage multiple files as well, and the tabs do not share any memory or registers so you can keep different things running, no problem. You can add a new tab by going to file and pressing add tab.
            </p>
            <p>
                The output panel has three output modes: console, memory and instructions. The console shows the output generated by environment calls and shows the status of the editor. The memory shows the state of the memory following simulation. The Instruction Log shows the step by step disassembly of the program. You can switch between them in the select drop down menu in the top right of the output panel.
            </p>
            <p>
                Registers are also displayed to the right side menu. Simply press the register tab. You can select the view type under the dropdown menu.
            </p>
            <h4>Uploading</h4>
            <p>
                You can also upload either assembly code or binary files directly to Oak.js.
            </p>
            <p>
                To do it, go to the file menu in the top left of the editor, and and press "Load Binary" or "Load Assembly" to upload a file. Keep in mind, binaries and assembly files must be in the correct file. After assembly files are uploaded, you need to press the assemble <img src="Images/assembleHelp.png" style="height: 16pt; vertical-align:middle;" /> button. After either that or the binary file, you must press play <img src="Images/playHelp.png" style="height: 16pt; vertical-align:middle;" />.
            </p>
            <h4>Downloading</h4>
            <p>
                Downloading is similar. Simply open the file menu, and press "Download RAM", "Download Binary", or "Download Assembly". The first two must be opened in a hex editor or other program capable of opening binaries. Assembly files can be loaded in any text editor.
            </p>
        </main>
        <script type="text/javascript" charset="utf-8" src="Scripts/jquery.js"></script>
        <script type="text/javascript" charset="utf-8">
            for (var i = 1; i < 3; i++)
                $("#theme"+i).prop('disabled', true);

            $("#themes").change(function() {
                var themeID = $(this).val();
                for (var i = 0; i < 3; i++)
                    $("#theme"+i).prop('disabled', i!=themeID);
            });
        </script>
    </body>
</html>