diff --git a/Lars.jar b/Lars.jar index eda6424c0cfa145d81472a195e87da2148a2e209..17ee64c82e192225b17773bc00a999f179421b5f 100644 Binary files a/Lars.jar and b/Lars.jar differ diff --git a/out/production/LARS/help/LarsHelpDebugging.html b/out/production/LARS/help/LarsHelpDebugging.html new file mode 100644 index 0000000000000000000000000000000000000000..9b6606093684117f7dc2e8044eeb86d47a0b660b --- /dev/null +++ b/out/production/LARS/help/LarsHelpDebugging.html @@ -0,0 +1,111 @@ +<html> +<title>LARS 4.5 help contents +</title> +<body> +<center> +<h3>LARS - LoongArch Assembly and Runtime Simulator</h3> +<h4>Release 4.5</h4> +<h4>May 2024</h4> +<h4>Interactive Debugging Features</h4> +</center> + +<p> +LARS provides many features for interactive debugging through its Execute pane. +Features include: +<ul> +<li>In <i>Step</i> mode, the next instruction to be simulated is highlighted and +memory content displays are updated at each step.</li> + +<li>Select the <i>Go</i> option if you want to simulate continually. +It can also be used to continue simulation +from a paused (step, breakpoint, pause) state.</li> + +<li>Breakpoints are easily set and reset using the check boxes next to each instruction displayed +in the Text Segment window. <i>New in Release 3.8:</i> You can temporarily suspend breakpoints +using Toggle Breakpoints in the Run menu or by clicking the "Bkpt" column header in the Text Segment +window. Repeat, to re-activate.</li> + +<li>When running in the <i>Go</i> mode, you can select the simulation +speed using the Run Speed slider. Available speeds range +from .05 instructions per second (20 seconds between steps) up to 30 +instructions per second, then above this offers an "unlimited" speed. +When using "unlimited" speed, code highlighting and memory display updating +are turned off while simulating (but it executes really fast!). +When a breakpoint is reached, highlighting and updating occur. +Run speed can be adjusted while the program is running.</li> + +<li>When running in the <i>Go</i> mode, you can pause or stop +simulation at any time using the <i>Pause</i> or <i>Stop</i> features. +The former will pause execution and update the display, as if you +were stepping or at a breakpoint. The latter will terminate execution +and display final memory and register values. If running at "unlimited" +speed, the system may not respond immediately but it will respond.</li> + + +<li>You have the ability to interactively step "backward" through program execution +one instruction at a time to "undo" execution steps. It will buffer up to 2000 of the most +recent execution steps (this limit is stored in a properties file and can be changed). +It will undo changes made to LoongArch memory, registers or condition flags, +but not console or file I/O. This should be a great debugging aid. +It is available anytime execution is paused and at termination (even if terminated due to +exception). + +<li>When program execution is paused or terminated, select <i>Reset</i> +to reset all memory cells and registers to their initial post-assembly values. +In fact, Reset is implemented by re-assembling the program.</li> + +<li>Memory addresses and values, and register values, can be viewed in either decimal +or hexadecimal format. All data are stored in little-endian byte order (each +word consists of byte 3 followed by byte 2 then 1 then 0). Note that each word +can hold 4 characters of a string and those 4 characters will appear in the +reverse order from that of the string literal.</li> + +<li>Data segment contents are displayed 512 bytes +at a time (with scrolling) starting with the data segment base address (0x10010000). +Navigation buttons are provided to change the display to the next +section of memory, the previous, or back to the initial (home) range. A combo box is +also provided to view memory contents in the vicinity of the stack pointer +(contents of LoongArch $sp register), thread pointer(contents of LoongArch $tp register), +the heap base address (0x10040000), .extern globals (0x10000000), +the kernel data segment (0x90000000), or memory-mapped IO (MMIO, 0xFFFF0000). +Meanwhile, raw text segment contents can also be displayed.</li> + +<li>Contents of any data segment memory word and almost any LoongArch register can be modified by +editing its displayed table cell. Double-click on a cell to edit it and press the Enter key +when finished typing the new value. If you +enter an invalid 32-bit integer, the word INVALID appears in the cell +and memory/register contents are not affected. Values can be entered +in either decimal or hexadecimal (leading "0x"). Negative hexadecimal +values can be entered in either two's complement or signed format. Note +that three of the integer registers (zero, program counter, return address) +cannot be edited.</li> + +<li>If the setting for Self-Modifying Code is enabled +(disabled by default, look in the Settings menu), text segment binary +code can be modified using the same technique described above. It can also +be modified by double-clicking on a cell in the Text Segment display's Code +column.</li> + +<li>Contents of cells representing floating point registers can be edited +as described above and will accept valid hexadecimal or decimal floating point +values. Since each double-precision register overlays two single-precision +registers, any changes to a double-precision register will affect one or both +of the displayed contents of its corresponding single-precision registers. +Changes to a single-precision register will affect the display of its +corresponding double-precision register. Values entered in hexadecimal +need to conform to IEEE-754 format. Values entered in decimal are entered +using decimal points and E-notation (e.g. 12.5e3 is 12.5 times 10 cubed).</li> + +<li>Cell contents can be edited during program execution and once accepted +will apply starting with the next instruction to be executed.</li> + +<li>Clicking on a Labels window entry will cause the location associated with +that label to be centered and highlighted in the Text Segment or Data Segment +window as appropriate. Note the Labels window is not displayed by default but +can be by selecting it from the Settings menu.</li> + +</ul> + +<hr> +</body> +</html> \ No newline at end of file diff --git a/out/production/LARS/help/LarsHelpHistory.html b/out/production/LARS/help/LarsHelpHistory.html new file mode 100644 index 0000000000000000000000000000000000000000..b720d1c8b0ac39918fa019641910ae050c9476ca --- /dev/null +++ b/out/production/LARS/help/LarsHelpHistory.html @@ -0,0 +1,67 @@ +<html> +<title>LARS Release History and Notes +</title> +<body> +<center> +<h3>LARS - LoongArch Assembly and Runtime Simulator</h3> +<h4>Release 4.5</h4> +<h4>May 2024</h4> +<h4>LARS Release History</h4> +</center> + +<p>LARS 4.5 was released in May 2024. Enhancements and bug fixes include: +<ul> +<li>The Keyboard and Display MMIO Simulator tool has been enhanced at the suggestion of Eric Wang at +Washington State University. Until now, all characters written to the display via the Data Transmitter +location (low order byte of memory word 0xFFFF000C) were simply streamed to the tools' display window. +Mr. Wang requested the ability to treat the display window as a virtual text-based terminal by +being able to programmatically clear the window or set the (x,y) position of a text cursor. Controlled +placement of the text cursor (which is not displayed) allows you to, among other things, develop +2D text-mode games. + <ul> + <li>To clear the window, place ASCII/Unicode 12 decimal in the Data Transmitter byte. This is the non-printing + Form Feed character. + </li> + <li>To set the text cursor to a specified (x,y) position, where x is the column and y is the row, + place ASCII/Unicode 7 in the Data Transmitter byte, and place the (x,y) position in the unused + upper 24 bits of the Data Transmitter word. Place the X-position in bits 20-31 and the Y-position in bits 8-19. + Position (0,0) is the upper-left corner of the display. + </li> + <li>You can resize the display window to desired dimensions prior to running your LoongArch program. + Dimensions are dynamically displayed in the upper border. Note that the tool now contains a splitter between + the display window and the keyboard window. Once the program is running, changes to the display size + does not affect cursor positioning.</li> + </ul> + The Help window for this tool is no longer modal, so you can view it while working in other windows. + The Help window contains a lot of information so you + will find it useful to be able to refer to it while working on your program. +</li> +<li>Installed the LoongArch X-ray Tool developed by Marcio Roberto and colleagues at the Federal Center of +Technological Education of Minas Gerais in Brazil. This tool animates a display of the LoongArch datapath. +The animation occurs while stepping through program execution. Search the Internet for "LoongArch X-ray" +to find relevant publications and other information. +</li> +<li>Context-sensitive help in the editor should now be easier to read. It was implemented as a menu of +disabled items, which caused their text to be dimmed. The items are now enabled for greater visibility +but clicking them will only make the list disappear. +</li> +<li>Bug Fix: Fixed an editor problem that affects certain European keyboards. The syntax-highlighting editor +ignored the Alt key, which some European keyboards require to produce the # or $ characters in particular. +I had no means of testing this, but Torsten Maehne in France send me a solution and Umberto +Villano in Italy affirmed that it worked for him as well. +</li> +<li>Bug Fix: Source code references to Coprocessor 1 floating point registers (e.g. $f12) +within macro definitions were erroneously flagged as syntax errors. LARS permits SPIM-style +macro parameters (which start with $ instead of %) and did not correctly distinguish them +from floating point register names. This has been fixed. Thanks to Rudolf Biczok in Germany for alerting +me to the bug. +</li> +<li>Bug Fix: Corrected a bug that caused the Data Segment window to sometimes display incorrect values +at the upper boundary of simulated memory segments. Thanks to Yi-Yu (James) Liu from Taiwan for alerting +me to the bug, which was introduced in LARSLARS 4.4. +</li> + +</ul> +</body> +</html> + diff --git a/out/production/LARS/help/LarsHelpIDE.html b/out/production/LARS/help/LarsHelpIDE.html new file mode 100644 index 0000000000000000000000000000000000000000..faa852f707a8b6d65101888e2defbc3c3b55e95e --- /dev/null +++ b/out/production/LARS/help/LarsHelpIDE.html @@ -0,0 +1,82 @@ +<html> +<title>LARS 4.5 help contents +</title> +<body> +<center> +<h3>LARS - LoongArch Assembly and Runtime Simulator</h3> +<h4>Release 4.5</h4> +<h4>May 2024</h4> +<h4>Using LARS through its Integrated Development Environment (IDE)</h4> +</center> + +The IDE is invoked when LARS is run with no command arguments, e.g. <tt>java -jar LARS.jar</tt>. +It may also be launched from a graphical interface by double-clicking the <tt>LARS.jar</tt> icon +that represents this executable JAR file. +The IDE provides basic editing, assembling and execution capabilities. Hopefully it +is intuitive to use. Here are comments on some features. +<ul> +<li><b>Menus and Toolbar</b>: Most menu items have equivalent toolbar icons. +If the function of a toolbar icon is not obvious, djust hover the mouse over it an +a tool tip will soon appear. Nearly all menu items also have keyboard shortcuts. +Any menu item not appropriate in a given situation is disabled.</li> +<li><b>Editor</b>: LARS includes two integrated text editors. The default editor, new +in Release 4.0, features syntax-aware color highlighting of most LoongArch language elements +and popup instruction guides. The original, generic, text editor without these features +is still available and can be selected in the Editor Settings dialog. It supports a single +font which can be modified in the Editor Settings dialog. +The bottom border of either editor includes the cursor line +and column position and there is a checkbox to display line numbers. +They are displayed outside the editing area. If you use an external editor, LARS provides +a convenience setting that will automatically assemble a file as soon as it is opened. See +the Settings menu. +<li><b>Message Areas</b>: There are two tabbed message areas at the +bottom of the screen. The <i>Run I/O</i> tab is used at runtime for +displaying console output and entering console input as program execution progresses. +You have the option of entering console input into a pop-up dialog then echoes to the message area. +The <i>LARS Messages</i> tab is used for other messages such as assembly or +runtime errors and informational messages. You can click on assembly error messages to +select the corresponding line of code in the editor. +<li><b>LoongArch Registers</b>: LoongArch registers are displayed at all times, even +when you are editing and not running a program. While writing your program, +this serves as a useful reference for register names and their conventional +uses (hover mouse over the register name to see tool tips). There are three +register tabs: the Register File (integer registers $0 through $31 plus StableCountHigh, +StableCountLow and the Program Counter), selected Coprocesor 0 registers (exceptions and +interrupts), and Coprocessor 1 floating point registers. + +<li><b>Assembly</b>: Select <i>Assemble</i> from the <i>Run</i> menu or the +corresponding toolbar icon to assemble the file currently in the Edit tab. +Prior to Release 3.1, only one file could be assembled and run at a time. +Releases 3.1 and later provide a primitive Project capability. To use it, go to the +<i>Settings</i> menu and check <i>Assemble operation applies to all +files in current directory.</i> Subsequently, the assembler will assemble +the current file as the "main" program and also assemble all other assembly +files (*.asm; *.s) +in the same directory. The results are linked and if all these +operations were successful the program can be executed. Labels that are +declared global with the ".globl" directive may be referenced in any of the +other files in the project. There is also a setting that permits +automatic loading and assembly of a selected exception handler file. LARS uses +the LoongArch32 starting address for exception handlers: 0x80000180. + + +<li><b>Execution</b>: Once a LoongArch program successfully assembles, the +registers are initialized and three windows +in the Execute tab are filled: <i>Text Segment</i>, <i>Data Segment</i>, +and <i>Program Labels</i>. The major execution-time features are described below. + +<li><b>Labels Window</b>: Display of the Labels window (symbol table) is +controlled through the Settings menu. When displayed, you can click on any label +or its associated address to center and highlight the contents of that address +in the Text Segment window or Data Segment window as appropriate. +</ul> + +<p>The assembler and simulator are invoked from the IDE +when you select the <i>Assemble</i>, <i>Go</i>, +or <i>Step</i> operations from the <i>Run</i> menu or their corresponding +toolbar icons or keyboard shortcuts. LARS messages are displayed on the +<i>LARS Messages</i> tab of the message area at the bottom of the screen. +Runtime console input and output is handled in the <i>Run I/O</i> tab. + +</body> +</html> \ No newline at end of file diff --git a/out/production/LARS/help/LarsHelpIntro.html b/out/production/LARS/help/LarsHelpIntro.html new file mode 100644 index 0000000000000000000000000000000000000000..20441756cc9b08634ae29a2c3e00399e094b4401 --- /dev/null +++ b/out/production/LARS/help/LarsHelpIntro.html @@ -0,0 +1,41 @@ +<html> +<title>LARS 4.5 help contents +</title> +<body> +<center> +<h3>LARS - LoongArch Assembly and Runtime Simulator</h3> +<h4>Release 4.5</h4> +<h4>May 2024</h4> +<h4>Introduction</h4> +</center> + +LARS, the <b>L</b>oongArch <b>A</b>ssembly and <b>R</b>untime <b>S</b>imulator, +will assemble and simulate the execution of LoongArch assembly language programs. +It can be used either from a command line or through its +integrated development environment (IDE). LARS is written in Java and +requires at least Release 1.5 of the J2SE Java Runtime Environment (JRE) to work. +It is distributed as an executable JAR file. + +<p>As of Release 4.0, LARS assembles and simulates approximately 50 basic instructions of the LoongArch-32 +instruction set, 13 pseudo-instructions or instruction variations, the 22 syscall functions +mainly for console and file I/O defined by SPIM, and an additional 18 syscalls for other uses such as MIDI +output, random number generation and more. These are listed in separate help tabs. It supports seven +different memory addressing modes for load and store instructions: <tt>label</tt>, <tt>immed</tt>, +<tt>label+immed</tt>, <tt>($reg)</tt>, <tt>label($reg)</tt>, <tt>immed($reg)</tt>, and <tt>label+immed($reg)</tt>, where <tt>immed</tt> +is an integer up to 32 bits. A setting is available to disallow use of pseudo-instructions +and extended instruction formats and memory addressing modes. +<p> + +Our guiding reference in implementing the instruction set has been +<i>Fundamentals of Assembly Language Programming Based on LoongArch' (by Sun Guoyun, Ao Qi, and Wang Rui) summarizes the +integer instructions of LoongArch-32 in Chapter 3, which focuses on the basic integer instructions of LoongArch. +At the same time, the 'la-asm-manual' summarizes the pseudo-instructions of LoongArch-32. + + +<p>The LARS IDE provides program editing and assembling but its real +strength is its support for interactive debugging. The programmer can easily set and +remove execution breakpoints or step through execution forward or backward (undo) while +viewing and directly editing register and memory contents. + +</body> +</html> \ No newline at end of file diff --git a/out/production/LARS/help/LarsHelpLimits.html b/out/production/LARS/help/LarsHelpLimits.html new file mode 100644 index 0000000000000000000000000000000000000000..b557161610bbcb5e3bf2dbe0d1794e3731cb47dd --- /dev/null +++ b/out/production/LARS/help/LarsHelpLimits.html @@ -0,0 +1,64 @@ +<html> +<title>LARS 4.5 help contents +</title> +<body> +<center> +<h3>LARS - LoongArch Assembly and Runtime Simulator</h3> +<h4>Release 4.5</h4> +<h4>May 2024</h4> + +<h4>Operating Requirements</h4> +</center> +<p>LARS is written in Java and +requires at least Release 1.5 of the J2SE Java Runtime Environment (JRE) to work. +The graphical IDE is implemented using Swing. It has been +tested on Windows XP, Vista and 7; Mac OS X; and is also being used under Linux. + +<center> +<h4>Some LARS Assembler and Simulator Limitations</h4> +</center> + +Releases 3.0 and later assemble and simulate nearly Assembly and simulation of nearly all the LoongArch32 basic instructions +and pseudo-instructions recorded in the LoongArch Architecture 32-bit Simplified Edition Reference Manual V1.02 have been implemented. +The instructions listed in Appendix B regarding the LoongArch32 simplified edition, as well as +the pseudo-instructions from CHAPTER 9 Pseudo Instruction in la-asm-manual, have been realized. + +<p>Limitations of LARS as of Release 4.5 include: +<ul> +<li>Memory segments (text, data, stack, kernel text, kernel data) are limited to 4MB each starting at their +respective base addresses.</li> +<li>There is no pipelined mode (but delayed branching is supported).</li> +<li>If you open a file which is a link or shortcut to another file, LARS will <em>not</em> +open the target file. The file open dialog is implemented using Java Swing's JFileChooser, +which does not support links.</li> + +<li>Very few configuration changes, besides those in the Settings menu, are saved from one session to the next. +The editor settings, which include font settings and display of line numbers, are saved.</li> + +<li>The IDE will work only with the LARS assembler. It cannot be used +with any other compiler, assembler, or simulator. The LARS assembler and simulator +can be used either through the IDE or from a command prompt.</li> + +<li><em>Bug:</em>The error message highlighter does not automatically select the code for the first assembly +error if the file containing the error is not open at the time of assembly (assemble-on-open, assemble-all).</li> + +<li><em>Bug:</em> The Screen Magnifier screen capture feature does not appear to work properly under Windows Vista.</li> + +<li><em>Bug:</em> There appears to be a memory leak in the Editor. Several different people have independently +reported the same behavior: severe slowdown in editor response during an extended interactive session. +If LARS is exited and restarted, this behavior disappears and the editor responds instantly to actions.</li> + +<li><em>Not a bug, but documented here anyway:</em> LoongArch Branch instruction target addresses are represented by +the relative number of words to branch. With Release 3.4, this value reflects delayed branching, +regardless of whether the Delayed Branching setting is enabled or not. +The generated binary code for branches will now match that of examples in the <em>Computer Organization +and Design</em> textbook. This is a change from the past, and was made after extensive discussions +with several faculty adopters of LARS. Previously, the branch offset was 1 lower if the Delayed Branching setting +was enabled -- the instruction <tt>label: beq $0,$0,label</tt> would generate <tt>0x1000FFFF</tt> if +Delayed Branching was enabled and <tt>0x10000000</tt> if it was disabled. Now it will generate <tt>0x1000FFFF</tt> in +either case. The simulator will always branch to the correct location; LARS does not allow assembly under one +setting and simulation under the other to occur.</li> +</ul> + +</body> +</html> \ No newline at end of file diff --git a/out/production/LARS/help/LarsHelpSettings.html b/out/production/LARS/help/LarsHelpSettings.html new file mode 100644 index 0000000000000000000000000000000000000000..356e8c3366a96dff4f374f37ea5c2afa440d0fa6 --- /dev/null +++ b/out/production/LARS/help/LarsHelpSettings.html @@ -0,0 +1,79 @@ +<html> +<title>LARS 4.5 help contents +</title> +<body> +<center> +<h3>LARS - LoongArch Assembly and Runtime Simulator</h3> +<h4>Release 4.5</h4> +<h4>May 2024</h4> +<h4>Configuration Settings</h4> +</center> + +Releases 3.0 and later include a Settings menu. The Editor and Exception Handler items launch a dialog but the rest are each +controlled by a checkbox for selecting or deselecting it (checked means true, unchecked means false). Settings and their default +values are: + <ol> + <li><b>Display the Labels window in the Execute tab.</b> Default value is <b>false</b>. If selected, the Labels window, + which shows the name and associated address for each label defined in the program, will be + displayed to the right of the Text Segment.</li> + <li><b>Provide program arguments to the LoongArch program.</b> Default value is <b>false</b>. New in Release 3.5. + If selected, a text field will appear at the top of the Text Segment Display. Any argument values in this + text field at the time of program execution will be stored in LoongArch memory prior to execution. The argument + count (argc) will be placed in register $a0, and the address of an array of null-terminated strings containing + the arguments (argv) will be placed in register $a1. These values are also available on the runtime stack ($sp). + <li><b>Popup Dialog for input syscalls (5,6,7,8,12).</b> New in Release 4.0. Default value is <b>false</b>. If selected, runtime console +input will be entered using popup dialogs (this was the only option prior to Release 4.0). Otherwise, input is entered +directly into the Run I/O tab at the bottom of the screen.</li> +<li><b>Display memory addresses in hexadecimal.</b> Default value is <b>true</b>. If deselected, addresses will be displayed in decimal. + This setting can also be toggled in a checkbox on the lower border of the Data Segment Window.</li> + <li><b>Display memory and register contents in hexadecimal.</b> Default value is <b>true</b>. If deselected, vlaues will be displayed in decimal. + This setting can also be toggled in a checkbox on the lower border of the Data Segment Window.</li> + <li><b>Assemble a file automatically as soon as it is opened,</b> and initialize the File Open dialog with the most-recently opened file. + Default value is <b>false</b>. This is convenient if you use an external editor for composing your programs.</li> + <li><b>Assemble applies to all files in directory.</b> Default value is <b>false</b>. + If selected, the file currently open in the + editor will become the "main" program in a multi-file assemble-and-link operation involving all + assembly files (*.asm; *.s) in its directory. If successful, execution will begin with the currently open file. </li> + <li><b>Assembler warnings are considered errors.</b> Default value is <b>false</b>. New in Release 3.5. + If selected, the assemble operation will fail if any warnings are produced. At this time, all assembler warnings + relate to unrecognized or ignored directives. LARS may be able to assemble code produced by compilers for other LoongArch + assemblers if this setting is deselected. + <li><b>Initialize Program Counter to global 'main' if defined.</b> Default value is <b>false</b>. New in Release 3.8. + If selected, the Program Counter will be initialized to the address of the text segment statement with the global label 'main' if it + exists. If it does not exist or if the setting is not selected, the Program Counter will be initialized to the default text segment + starting address. + <li><b>Permit programs to use extended (pseudo) instructions and formats.</b> Default value is <b>true</b>. This includes all memory addressing + modes other than the LoongArch native mode (16 bit constant offset added to register content).</li> + <li><b>Assemble and execute programs using delayed branching.</b> Default value is <b>false</b>. LoongArch processors use delayed branches + as part of the pipelined design, but it can be confusing to programmers. With delayed branching, the instruction + following a branch or jump instruction <i>will always be executed</i> even if the branch condition is true! Assemblers + and, failing that, programmers, often deal with this by following branches and jumps with a "<tt>nop</tt>" instruction. The LARS + assembler does <i>not</i> insert a <tt>nop</tt>. When delayed branching was introduced in Release 3.3, the machine code generated + for a branch instruction depended on this setting since + its target value is relative to the Program Counter (<i>PC-relative addressing</i>). Although technically correct, this led to + confusion in the LARS community because the generated code did not match textbook examples. Starting with Release 3.4, the relative branching + offset is always calculated as if delayed branching is enabled even when it is not. The runtime simulation adjusts accordingly.</li> + <li><b>Self-modifying code.</b> Default value is <b>false</b>. New in Release 4.4. + If selected, a running LoongArch program can write to a user text segment address and can branch/jump to a user data segment address. + These capabilities permit a program to dynamically generate and/or modify its binary code. Also permits interactive modification of + text segment contents through either the Data Segment or Text Segment windows. + <li><b>The Editor dialog.</b> Use it to view and modify editor font settings. New with Release 3.3.</li> + <li><b>The Highlighting dialog.</b> Use it to modify color and font settings for the highlighting of table items in the + Text Segment window, Data Segment window, Registers window, Coprocessor0 window and Coprocessor1 window. + Highlighting occurs during timed, stepped, and backstepped simulation. Color and font for normal (non-highlighted) + display can also be set separately for even-numbered and odd-numbered display rows but not individually by windows. + New with Release 3.6.</li> + <li><b>The Exception Handler dialog.</b> It has the setting: Include this +exception handler in all assemble operations. Default value is <b>false</b>. If selected, a button to browse to the desired + file is enabled. New with Release 3.2</li> + <li><b>The Memory Configuration dialog.</b> Use it to select from among available LoongArch address space configurations. + The default configuration is derived from SPIM; it was only one available from LARS 1.0 through LARS 3.6. + New with Release 3.7. + </ol> +Beginning with Release 3.2, settings are retained from one interactive session to the next. Settings are stored in a system-dependent +way as specified by <tt>java.util.prefs.Preferences</tt>. Windows systems use the Registry. +These settings are independent of command options given when using LARS from a command line; +neither affects the other. We anticipate future releases will include additional settings and preferences. + +</body> +</html> \ No newline at end of file diff --git a/out/production/LARS/help/LarsHelpTools.html b/out/production/LARS/help/LarsHelpTools.html new file mode 100644 index 0000000000000000000000000000000000000000..8aa5f4ee33f37bc257b71410e7a6b6a43a441234 --- /dev/null +++ b/out/production/LARS/help/LarsHelpTools.html @@ -0,0 +1,101 @@ +<html> +<title>LARS 4.5 help contents +</title> +<body> +<center> +<h3>LARS - LoongArch Assembly and Runtime Simulator</h3> +<h4>Release 4.5</h4> +<h4>May 2024</h4> +<h4>Cool Capability: Plug-in Tools</h4> +</center> + +Beginning with Release 2.0, LARS is capable of running externally-developed +software that interacts with an executing LoongArch program and LoongArch system +resources. +The requirements for such a program are: +<ol> +<li>It implements the <tt>LARS.tools.LARSTool</tt> interface. +<li>It is part of the <tt>LARS.tools</tt> package. +<li>It compiles cleanly into a ".class" file, stored in the <tt>LARS/tools</tt> directory. +</ol> +LARS will detect all qualifying tools upon startup and include them in +its Tools menu. +When a tool's menu item is selected, an instance of it will be created using its no-argument +constructor and its <tt>action()</tt> method will be invoked. +If no qualifying tools are found at LARS startup, the Tools menu will not +appear. + +<p>To use such a tool, load and assemble a LoongArch program of interest then select the desired tool +from the Tools menu. The tool's window will open and depending on how it is written it will either +need to be "connected" to the LoongArch program by clicking a button or will already be connected. Run +the LoongArch program as you normally would, to initiate tool interaction with the executing program. + +<p>Beginning with Release 3.2, the abstract class <tt>LARS.tools.AbstractLARSToolAndApplication</tt> +is included in the LARS distribution to provide +a substantial framework for implementing your own LARS Tool. A subclass that extends it by +implementing at least its two abstract methods can be run not only from the Tools menu but also +as a free-standing application that uses the LARS assembler and simulator in the background. + +<p>Several Tools developed by subclassing <tt>AbstractLARSToolAndApplication</tt> are included +with LARS: an Introduction to Tools, a Data Cache Simulator, a Memory Reference Visualizer, and +a Floating Point tool. The last one is quite useful even when not connected to a LoongArch program +because it displays binary, hexadecimal and decimal representations for a 32 bit floating point +value; when any of them is modified the other two are updated as well. + +<p>Release 3.5 includes new tools, most notably a keyboard and display simulator that allows you +to perform memory-mapped I/O (MMIO) using polled and interrupt-driven techniques as described +in various references. Click its Help button for more details. + +<p>If you wish to develop your own LARS Tool, you will first need to extract the LARS distribution +from its JAR file if you have not already done so. All LARS tools must +be stored in the <tt>LARS/tools</tt> directory. + +<p>Follow the Tutorial Materials link on the LARS homepage to find a tutorial +that covers development of LARS Tools. + +<h4>Cool Capability: Extending the syscall set or reassigning syscall numbers</h4> + +Beginning with Release 3.1, system calls (<tt>syscall</tt> instruction) are implemented using +a technique similar to that for tools. This permits anyone to add a new syscall by defining +a new class that meets these requirements: +<ol> +<li>It implements the <tt>LARS.LoongArch.instructions.syscalls.Syscall</tt> interface, or +extends the <tt>LARS.LoongArch.instructions.syscalls.AbstractSyscall</tt> class (which +provides default implementations of everything except the <tt>simulate()</tt> method). +<li>It is part of the <tt>LARS.LoongArch.instructions.syscalls</tt> package. +<li>It compiles cleanly into a ".class" file, stored in the +<tt>LARS/LoongArch/instructions/syscalls</tt> directory. +</ol> +LARS will detect all qualifying syscall classes upon startup and the runtime simulator +will invoke them when the <tt>syscall</tt> instruction is simulated and register <tt>$v0</tt> +contains the corresponding integer service number. + +<p>Syscalls and syscall number assignments in LARS match those of SPIM for syscalls 1 through 17. +However if you wish to change syscall number assignments, you may do so by editing the +<tt>Syscall.properties</tt> file included in the release (this requires extraction from the JAR +file). + +<p>Follow the Tutorial Materials link on the LARS homepage to find a tutorial +that covers development of system calls. + +<h4>Cool Capability: Extending the instruction set</h4> + +You can add customized pseudo-instructions to the LoongArch instruction set by editing +the <tt>PseudoOps.txt</tt> file included in the LARS distribution. Instruction +specification formats are explained in the file itself. +The specification of a pseudo-instruction is one line long. It consists of +an example of the instruction, constructed using +available instruction specification symbols, followed by a tab-separated +list of the basic LoongArch instructions it will expand to. Each is an instruction template +constructed using +instruction specification symbols combined with special template +specification symbols. The latter permit substitution at program +assembly time of operands from the user's program into the expanded +pseudo-instruction. + +<p><tt>PseudoOps.txt</tt> is read and processed at LARS startup, and error messages will +be produced if a specification is not correctly formatted. Note that if you wish to +edit it you first have to extract it from the JAR file. + +</body> +</html> \ No newline at end of file