bgould · Erhannis · Feb 9, 2022 · Feb 9, 2022 · Feb 11, 2022 · bgould
diff --git a/README.md b/README.md
@@ -42,6 +42,17 @@ specify the `prefix` environment variable.  For example, to install to
 
 Below are some system-specific build instructions for this repository; pull
 requests with steps for other environments are certainly welcome.
+([Erhannis:] The easiest way I've found to build this, as of 2022, is to
+install Ubuntu 14.04.6 in VirtualBox and follow the Debian 8 instructions.
+I think that route gave me the least fuss.)
+
+There IS a Docker container, which was easier to build:
+```bash
+cd docker/debian
+docker build .
+```
+...but as of this writing, I don't yet know how to actually USE it once built,
+so until I figure that out, Debian VM remains my recommendation.
 
 ### Debian 8 etc:
 
@@ -62,6 +73,207 @@ requests with steps for other environments are certainly welcome.
     cd /usr/local/src/nestedvm
     make dist 
 
+
+
+
+[Erhannis:] After this point is information reconstituted by people discovering this
+repo later, and reading the tests and code and so forth.  God speed.
+
+## Usage
+
+### Compile C source
+`mips-unknown-elf-gcc -O3 -mmemcpy -ffunction-sections -fdata-sections -falign-functions=512 -fno-rename-registers -fno-schedule-insns -fno-delayed-branch -march=mips1 -specs=/usr/local/nestedvm/mips-unknown-elf/lib/crt0-override.spec -I. -Wall -Wno-unused -c -o build/com/test/Test.o test.c`
+
+### Link to a MIPS binary
+`mips-unknown-elf-gcc -o build/com/test/Test.mips build/com/test/Test.o -march=mips1 -specs=/usr/local/nestedvm/mips-unknown-elf/lib/crt0-override.spec --static -Wl,--gc-sections`
+
+### Compile to a Java class
+`java -cp "/usr/local/nestedvm/share/java/nestedvm-compiler.jar:build" org.ibex.nestedvm.Compiler -outformat class -d build com.test.Test build/com/test/Test.mips`
+
+### Running the resulting Java application
+`java -cp /usr/local/nestedvm/share/java/nestedvm-runtime.jar:build com.test.Test`
+
+### Using the Java classes
+You can create a jar around a class `Test` at e.g. `com/test/Test.class` with `jar cf Test.jar com`.
+You can then install that jar into your maven local repository with
+```bash
+mvn install:install-file \
+    -Dfile=Test.jar \
+    -DgroupId=test.test.test \
+    -DartifactId=nestedvm-test-classes \
+    -Dversion=0.0.0-SNAPSHOT \
+    -Dpackaging=jar
+```
+Likewise install a copy of the e.g. unix_runtime.jar with
+```bash
+mvn install:install-file \
+    -Dfile=unix_runtime.jar \
+    -DgroupId=org.ibex.nestedvm \
+    -Dversion=1.0.0-SNAPSHOT \
+    -DartifactId=unix-runtime \
+    -Dpackaging=jar
+```
+(If you create a jar out of the sources in `src/`, in the same way you'd make one for classes,
+you can add
+```
+    -Dsources=nestedvm_src.jar \
+    -Djavadoc=nestedvm_src.jar \
+```
+in the middle of that command to install the sources, as well.)
+Once you have those two jars installed to your local maven repo, you can
+pull them in as dependencies with
+```
+<dependency>
+    <groupId>org.ibex.nestedvm</groupId>
+    <artifactId>unix-runtime</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+</dependency>
+<dependency>
+    <groupId>test.test.test</groupId>
+    <artifactId>nestedvm-test-classes</artifactId>
+    <version>0.0.0-SNAPSHOT</version>
+</dependency>
+```
+You can then run the file in your Java code with e.g.
+```
+int result = new Test.run("com.test.Test", new String[]{});
+```
+That's not particularly useful, though.  See `src/tests/` for examples of
+more intricate usage.  I've gone through the tests and filtered
+out some use case examples - I haven't tested all of these myself, so
+buyer beware.  See original tests if you encounter problems.
+
+#### Calling functions
+Given c method
+```c
+int test(int x) {
+    return x*4;
+}
+```
+you can call it from Java if you first prepend it
+with a declaration flagged to prevent it being optimized away, like:
+```c
+int x4(int x) __attribute__((section(".text")));
+int x4(int x) {
+    return x*4;
+}
+```
+Then you can call it like:
+```java
+Test test = new Test();
+test.start();
+int r = test.call("x4",new int[]{17});
+```
+I think there are ways of calling functions with more complicated parameters and returns,
+but I don't yet know how.
+
+#### Piping
+If you want to pipe into or out of a program, you can call like
+```java
+Runtime task = (Runtime) Class.forName("tests.EchoHelper").newInstance();
+task.closeFD(0);
+task.closeFD(1);
+//task.closeFD(2);
+task.addFD(new Runtime.InputOutputStreamFD(sock.getInputStream()));
+task.addFD(new Runtime.InputOutputStreamFD(sock.getOutputStream()));
+//task.dupFD(1);
+int status = task.run(new String[]{"EchoHelper"} );
+```
+stdin, stdout, and stderr are originally created like:
+```java
+addFD(new TerminalFD(stdin));
+addFD(new TerminalFD(System.out));
+addFD(new TerminalFD(System.err));
+```
+
+#### Shared array
+Apparently there's an array you can declare in your C code with N elements:
+```c
+char * user_info[2];
+```
+and access it in C like
+```c
+char *fontdata;
+int fontsize;
+
+_pause(); // I don't know whether this is necessary or what
+
+fontdata = user_info[0];
+fontsize = (int)user_info[1];
+```
+You can then access it from Java like
+```java
+byte[] font = InputStreamToByteArray.convert(new FileInputStream(argv[0]));
+int fontAddr = rt.malloc(font.length);
+if(fontAddr == 0) throw new Error("malloc() failed");
+rt.copyout(font,fontAddr,font.length);
+
+rt.setUserInfo(0,fontAddr);
+rt.setUserInfo(1,font.length);
+```
+
+#### Memory management
+There's a bunch of memory functions I'm sorta hazy on, like
+`malloc`, `free`, `realloc`, `xmalloc`, `xrealloc`, `brk`, `sbrk`,
+`memRead`, `memWrite`, `memset`, `memcpy`,
+`copyin`, `copyout`,
+and some string functions like `cstring`, `utfstring`, and `strdup`.
+
+#### Pausing
+I think you can pass control back to Java at will, by calling `_pause()`.
+In C:
+```c
+extern void _pause();
+
+// Then somewhere in code:
+_pause();
+```
+In Java, I think:
+```java
+rt.start();
+boolean exited = rt.execute();
+```
+If exited is false, the code simply paused.  (Or maybe something else
+happened that had the same result?)
+
+#### Callback to Java
+You can add a callback in Java that your C programs can call.  In Java:
+```java
+rt.setCallJavaCB(new Runtime.CallJavaCB() {
+    public int call(int a, int b, int c, int d) {
+        switch(a) {
+            case 1: return rt.strdup("OS: " + System.getProperty("os.name"));
+            case 2: return rt.strdup(System.getProperty("os.version"));
+            case 3: return rt.strdup(new Date().toString());
+            case 4: return rt.addFD(new Runtime.InputOutputStreamFD(null,new CustomOS()));
+            case 5:
+                System.out.println("In callJava() in Java");
+                try { rt.call("backinmips"); } catch(Runtime.CallException e) { }
+                System.out.println("Back in callJava() in Java");
+                return 0;
+            default: return 0;
+        }
+    }
+});
+```
+In C:
+```c
+extern int _call_java(int a, int b, int c, int d);
+
+// Then somewhere in code:
+char *s = (char*)_call_java(i,0,0,0);
+```
+It feels a little stilted and cramped, but the former could probably be solved by wrapper
+methods, and the latter by passing addresses to structures.  It seems sufficient, to me,
+if not perfect.
+
+#### Probably some other stuff
+There are probably other things it can do that you'll eventually want to do, which I haven't
+covered here and probably don't know about, but I think I covered most of the functions I've
+seen.
+
+
+
 [1]: http://nestedvm.ibex.org/
 [2]: http://article.gmane.org/gmane.comp.java.nestedvm/185
 [3]: https://github.com/ehrmann/nestedvm

diff --git a/doc/ivme04.aux b/doc/ivme04.aux
@@ -0,0 +1,49 @@
+\relax 
+\bibstyle{amsplain}
+\citation{ibex}
+\citation{jni}
+\citation{cni}
+\citation{j2me}
+\citation{msil}
+\citation{parrot}
+\citation{python}
+\@writefile{toc}{\contentsline {section}{\numberline {1}Introduction}{1}\protected@file@percent }
+\citation{jazillian}
+\citation{mohca}
+\citation{c2j}
+\citation{capp}
+\citation{ephedra}
+\@writefile{toc}{\contentsline {section}{\numberline {2}Existing Work}{2}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {2.1}Source-to-Source Translation}{2}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {2.1.1}Human-Assisted Translation}{2}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsubsection}{\numberline {2.1.2}Partial-Domain Translation}{2}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {2.2}Source-to-Binary Translation}{2}\protected@file@percent }
+\citation{egcsjvm}
+\citation{lcc}
+\@writefile{toc}{\contentsline {section}{\numberline {3}NestedVM}{3}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.1}Mapping the R2000 onto the JVM}{3}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.2}Binary-to-Source Mode}{4}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {3.3}Binary-to-Binary Mode}{4}\protected@file@percent }
+\@writefile{toc}{\contentsline {section}{\numberline {4}The NestedVM Runtime}{4}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {4.1}The ANSI C Runtime}{4}\protected@file@percent }
+\citation{jmm}
+\@writefile{lof}{\contentsline {figure}{\numberline {1}{\ignorespaces  Trampoline transformation necessitated by Java's 64kb method size limit}}{5}\protected@file@percent }
+\newlabel{code1}{{1}{5}}
+\@writefile{toc}{\contentsline {subsection}{\numberline {4.2}The Unix Runtime}{5}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {4.3}Security Concerns}{5}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {4.4}Threading}{5}\protected@file@percent }
+\citation{hotspot}
+\@writefile{toc}{\contentsline {section}{\numberline {5}Optimization and Performance}{6}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {5.1}Binary-to-Source Mode}{6}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {5.2}Binary-to-Binary Mode}{7}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {5.3}Compiler Flags}{7}\protected@file@percent }
+\citation{msil}
+\@writefile{toc}{\contentsline {subsection}{\numberline {5.4}Overall Performance}{8}\protected@file@percent }
+\@writefile{toc}{\contentsline {section}{\numberline {6}Sample Applications}{8}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {6.1}FreeType, {\tt  libmspack}, and {\tt  libjpeg}}{8}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {6.2}The GNU Compiler Collection}{8}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {6.3}\TeX  and LINPACK}{8}\protected@file@percent }
+\@writefile{toc}{\contentsline {section}{\numberline {7}Conclusion}{8}\protected@file@percent }
+\bibdata{ivme04}
+\@writefile{toc}{\contentsline {subsection}{\numberline {7.1}Future Directions}{9}\protected@file@percent }
+\@writefile{toc}{\contentsline {subsection}{\numberline {7.2}Availability}{9}\protected@file@percent }
diff --git a/doc/ivme04.dvi b/doc/ivme04.dvi