Added ability to directly embed NED programs in NEDsim binary for runtime execution.

[screensavers] / hacks / NEDsim / ned_programs / README.md

diff --git a/hacks/NEDsim/ned_programs/README.md b/hacks/NEDsim/ned_programs/README.md
new file mode 100644 (file)
index 0000000..859201c
--- /dev/null
+++ b/hacks/NEDsim/ned_programs/README.md
@@ -0,0 +1,50 @@
+Overview
+========
+
+This directory contains programs written in NED1 assembly for use with the
+NEDsim screensaver.
+
+
+Status
+======
+
+All programs in this directory are complete and verified to run on NEDsim.
+
+
+Instructions
+============
+
+First, note that none of this is necessary if you simply wish to run a custom
+program on the NEDsim screensaver. Any NED1 a.out format executable may be
+passed to the screensaver on the CLI using the flag `-binary filename.out`.
+
+The instructions that follow explain how to directly embed NED machine code in
+the NEDsim binary as built-in, default programs.
+
+The first step is simply copying a NED1 assembly file into the present
+directory with a `.ned_asm` suffix. The filename (minus the suffix) determines
+the identifier name in C. For example, if you add a file named
+`example.ned_asm`, then in C it would be accessed as `example[]` and its size
+would be tracked in `example_size`.
+
+The second step requires editing `NEDsim.c` in the parent directory, adding a
+new entry to the `ned_programs[]` array based on the name chosen in the
+previous step. Continuing the previous example, the new entry would resemble
+this:
+
+    {
+        example,
+        &example_size,
+        0x20000000
+    }
+
+Note that `0x20000000` is the address of the RAM Window displayed by the
+screensaver. You may move this window around if you wish to display a different
+region of system memory; it has no bearing on code execution, only on the
+screensaver's display. Since code is loaded starting at `0x20000000`, using
+this value will display the machine code and is a suitable fallback for
+programs without interesting memory patterns.
+
+With your NED1 assembly file in this directory and an appropriate entry added
+to the `NEDsim.c` file, simply recompile NEDsim and your code will be embedded
+in the NEDsim binary as a new default program.