Overview

TODO:

Explain ned_programs folder
Mention machine specs unique to NEDsim screensaver (64k element stack, 64MB heap, etc)
General description of NED (32-bit RISC stack machine, syllable packed words, etc)
Screenshots of operation
Link to main NED1 repository for full simulator

Status

Complete. Tested on FreeBSD.

Instructions

The included Makefile includes targets for make all to build the hack, make clean to delete any build detritus, and make run to execute the hack.

If you are running on FreeBSD, simply run one of those three commands. Anywhere else, edit the Makefile to suit your environment per the comments included in that file. Note that the Makefile assumes a copy of the screenhack library source code is located at ../screenhack/ relative to this directory.

For assistance setting $(DEFINES) in the Makefile on non-FreeBSD platforms, consider downloading the XScreensaver source tarball, running ./configure in the unpacked directory, and examining the resulting config.h file.

Although NEDsim can integrate with XScreensaver, the presence of XScreensaver is not strictly required. NEDsim will both build and execute using only the included screenhack library.

Command-Line Flags

The following CLI flags customize the operation of NEDsim at runtime.

-delay N: Request N millisecond delay between each frame of NEDsim, itself equivalent to one clock cycle of the simulation. Note that this is only a request; XScreensaver reserves the right to ignore requested values, and of course we execute at the mercy of the kernel’s scheduling. In practice, non-absurd values are reasonably well respected.
-color N: Select color scheme N from color_list[] in NEDsim.c.
-binary FILENAME: Instruct NEDsim to execute FILENAME, a NED1 a.out format executable file. If this option is not specified, one of the NED1 programs embedded directly in NEDsim will be chosen at random.
-heapwindow N: Instruct NEDsim to located the window into RAM at address N. Note that allowable values depend upon the quantity of simulated RAM and must take into account the size of the heap window, itself dependent upon the size of your display. Also note that this CLI option is ignored unless the -binary FILENAME option was passed.

XScreensaver Integration

In addition to running as a standalone program, NEDsim can be integrated into the XScreensaver framework.

To accomplish this integration, begin by installing and configuring XScreensaver via whatever method is appropriate for your operating system. The following instructions assume the filesystem paths used by FreeBSD packages and ports; your paths may differ. After XScreensaver installation, ensure all pertinent config files are created by running xscreensaver-demo and configuring XScreensaver for your system.

After XScreensaver is configured and working on your system, ensure that NEDsim runs in standalone mode on your system. If you can make clean run in the screensavers/hacks/NEDsim/ folder and see the hack’s visual output, you’re ready to move on.

At this point, copy the hack into your XScreensaver hack directory. For example, with prerequisite steps spelled out:

git clone git://git.subgeniuskitty.com/screensavers
cd screensavers/hacks/NEDsim
make clean all
cp NEDsim /usr/local/bin/xscreensaver-hacks/nedsim

Now create the file nedsim.xml wherever your system stores XScreensaver config files and populate it with the contents shown below. For example, on FreeBSD:

vi /usr/local/share/xscreensaver/config/nedsim.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<screensaver name="nedsim" _label="NEDsim">

  <command arg="-root"/>

  <string  id="delay"      _label="Delay (msec):"                     arg="-delay %" />
  <string  id="color"      _label="Color index (int):"                arg="-color %" />
  <string  id="binary"     _label="NED1 a.out executable (filename):" arg="-binary %" />
  <string  id="heapwindow" _label="Heap window start address (int):"  arg="-heapwindow %" />

  <_description>
NEDsim simulates a blinkenlight front panel for a 32-bit RISC stack machine
architecture named NED. See http://subgeniuskitty.com for more information.
  </_description>
</screensaver>

The next step integrates NEDsim into an individual user’s XScreensaver config via the file ~/.xscreensaver. If preferred, it could instead be done in the global XScreensaver config.

In the ~/.xscreensaver file, create a NEDsim entry under the programs: label in the same list as all the other hacks. Position in the list is irrelevant, but ensure you don’t paste NEDsim’s entry into the middle of pre-existing, multi-line entries. For context, the example below includes a multi-line entry, a GL entry and a plain entry. All that is needed is to insert the NEDsim line somewhere in the programs: list, as demonstrated.

vi ~/.xscreensaver

<snip>
programs:                                                                     \
                                xplanet -vroot -wait 1 -timewarp 400          \
                                  -label -origin moon                       \n\
  GL:                           fireflies -root                             \n\
                                nedsim -root                                \n\
                                blitspin -root                              \n\
<snip>

That’s all. Now you can run xscreensaver-demo and select NEDsim just like any other hack.