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

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

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.