Welcome to the Net Machine Emulator (NME)!

This is meant to be a quickstart guide to using NME, the networked, modular, extensible computer emulator. It currently supports Sun2, Sun3, SPARC and UltraSPARC machines. More detailed information and background history can be found in the Info page that is installed with NME by using either the standalone Info program or the Info reader in Emacs. It can also be found online at the NME web page. These documents are generated by the Texinfo file, that is distributed with the NME source tree and will be updated within there going forward.

Here is a quick rundown of how to install & run nme.

---

Installation

There are a couple of ways to install nme.

Source Tree

From any POSIX or Unix-like environment, you should be able to build & install from source using the included autotools configuration. It is available from the NME GitHub Repository. You may either clone the repo directly or download the latest release tarball nme-<version>. If you clone, you will have to autoreconf before continuing (see below). In either case, you will first have to build & install the libopenvpn package in the same way with libopenvpn-<version>. For convenience, the Releases also include a tarball version with both packages that can be built and installed from one source directory nme-<version>-libopenvpn-<version>. These are all meant to be portable and should work on most POSIX-like environments using the standard configure/make/install procedure:

To start from the main branch of the github repo:

git clone https://github.com/phabrics/libopenvpn.git
autoreconf -fi libopenvpn
git clone https://github.com/phabrics/nme.git
autoreconf -fi nme

Note that the main branch is not guaranteed to be working. There is currently no development branch, so you will have to be aware if you do this. To start from a stable release tarball:

tar xJf libopenvpn-<version>.tar.xz
tar xJf nme-<version>.tar.xz

Then change into the top source directory (or another directory for v-path builds) and configure/make:

cd libopenvpn-<version>
./configure [<options>]
make [-j n] 
make install
cd nme-<version>
./configure [<options>]
make [-j n] 
make install

Useful configure options are as follows:

• --enable-threads=<threading model> where threading model can be one of sdl, pthreads, or glib. Default threading model if not specified is glib, which is the same as --disable-threads. Note that this only affects multi-threading mode; by default, nmesh runs in single-threaded mode which is always with fibers now but you can dynamically select multi-threaded mode on the command-line with the -m option (see options).
• --enable-hosts=<hosts> where hosts can be one or more of gtk, rfb, sdl, bsd, tun, or openvpn. The first three are display types and the second three are ethernet types. Default is whatever is supported by the host platform.

Parallel builds are supported by the -j option to make. V-path builds are supported by creating a separate build directory outside the source directory and configuring & making from there as is documented in the autoconf Info pages.

Package Manager

Alternatively, if your platform has a package manager, and NME is in it, you can use that instead to automatically download, build & install from source or binary. For instance, if you are on Windows, you may install prebuilt native binaries in the msys2 environment using the pacman installer:

pacman -S ${MINGW_PACKAGE_PREFIX}-nme

This installs for the four main msys2 environments, depending upon which one you are in: ucrt64, mingw64, clang64, clangarm64. To install all at once, use .* in place of the MINGW_PACKAGE_PREFIX variable. Note that you can also use the Autotools method in the previous section to build & install from source in any of the msys2 environments as well.

Running

You should be able to run it straight out of the box after this, according to the instructions at The Original TME Page. Here is a high-level summary of the steps involved.

1. Configuration

Create your work directory and copy the example machine descriptions to it. Copy all the necessary config files and firmware binaries.

  mkdir <machine_dir>
  cd <machine_dir>
  cp <machine_desc> .
  cp <configs> .
  cp <bins> .

2. Execution

To see options, run nmesh --help.

You can just run like this:

  nmesh [-mfic] [--log <file>] [<machine_desc>]

• The -m option enables multi-threaded mode in which nmesh will distribute tasks among parallel threads for better efficiency and smoother operationx. Default is single-threaded (fiber) mode.
• The -f option starts nmesh in fullscreen mode which can be toggled using F11.
• The -i option opens the interactive shell to view the current nmesh config and perform other configuration options in real-time.
• The -c option is mainly an internal option for use in tuning the timing for specific architectures by using a specified cycle counter when available.
• The --log option logs informational and error messages to the specified <file>
• The <machine_desc> is the input configuration file(s) which can also be input from the interactive shell using the source command.

3. Guest OS Install

If you made it this far, you should now be ready to install a guest OS. This is a quick outline of how install the latest version of NetBSD. Other guest OSes that can be installed include Solaris & OpenBSD. Separate steps would be required to set those up, and may be documented later.

Next, download the NetBSD installation files for the given platform. For instance, you can get the files needed for NetBSD installation on Sun2/3 machines by issuing the following command to download in <arch> subdir.

  wget -R "*.html" -np -r -nH --cut-dirs=3 https://<netbsd_mirror_site>/pub/NetBSD/NetBSD-<release>/<arch>/

Note that <netbsd_mirror_site> may have robots.txt active; wget respects this, so if you run into trouble downloading the files, you will either have to get the files manually, or by downloading the iso and mounting it to the appropriate mount point so that the installation files can be found. Afterwards, you can install it by tape or netboot. The instructions to make the boot & install tapes are at the above address given at the above address. Basically, they are similar to the !MakeBootTape and !MakeInstallTape shell scripts that are in the installation/tapeboot subdir of the <arch> directory. The instructions there are for making actual tapes. NME emulates this with individual files for each sector, so you will have to create a file per sector, according to the instructions above or in the scripts. To make the boot tape:

   mkdir tape
   cd tape
   ln -s ../<arch>/installation/tapeimage/tapeboot 01
   touch 02 03
   gzip -c -d ../<arch>/installation/miniroot/miniroot.fs.gz > 04
   gzip -c -d ../<arch>/binary/kernel/netbsd-RAMDISK.gz > 05 (or 02 for sun3)

Making the install tape follows a similar procedure; see the MakeInstallTape script and replace the commands similarly. You can load the tapes and power up using the appropriate commands in the machine file. See the INSTALL.* docs in the <arch> dir for more instructions on the actual installation procedure inside the emulated machine!

4. Build Emulated Machines with nme-make-machs

As this can be kind of a tedious process to reproduce from scratch, a bash script has been created that automates most of this process for expediency. This is the nme-make-machs script. This script performs all the necessary steps for a basic setup of a new NME install:

1. Downloads all the firmwares for supported machines.
2. Downloads all the OS install files needed for each machine.
3. Creates new machines for you to use for each supported architecture.
4. Makes all the auxiliary configuration files.
5. Links the tape sector or cdrom iso files.
6. Sets up the disks needed for starting the machine.

This should provide some added incentive for getting started using NME! Note that for the time being, you should obtain it at the link above. It will be available in future revisions of NME as well...

5. Running Guest OS

Assuming you have successfully installed the guest, you are now ready to run the installed OS! You may run using a GUI with a gtk, sdl or rfb (vnc) host interface. See NME Graphics for more details. You can also set up a console interface through the serial port.

Console Interface

On most Unix-like systems, the POSIX serial port interface should be available. These are usually pseudoterminal device pairs with names like /dev/ptyXX & /dev/ttyXX. Most modern systems support Unix98-style terminals in which the pairs can be automatically created by opening the special pseudoterminal "master" device /dev/ptmx, which will create the "slave" device /dev/ttyXX. NME will open this device and connect to it, if available. Then, you can connect to the console by opening the corresponding /dev/ttyXX device with a viewer like screen, tip or tmux. Otherwise, you must manually specify the device pairs to connect to.

On Windows, you would have to get a serial port emulator. The com0com Null-modem emulator is known to work. If you get it, be sure to get the signed 2.2.2.0 version, as the 3.0.0.0 version signature does not appear to be valid. You can then set up the port pairs to use for hooking up to NME on one side and viewing on the other with a terminal emulator. A good one to use is Tera Term.

For example, if you set up a COM2/COM4 port pair using com0com, then you could use the following line for your serial port configuration in NME:

console0 at zs0 channel A: nme/host/posix/serial device //./COM2 break-carats timeouts 50 50 50 10 10

Then, you can configure your terminal emulator to use COM4. Please see the example machine descriptions distributed with NME for more info.

Networking

There are a few ways to do networking with NME. You can use a bpf, tap, or link connection, which each provide host interfaces to the ethernet ports of the emulated machine. For more information on their usage, visit NME Networking. The preferred method is using a tap interface via OpenVPN. This is the most portable method as it can be used to set up the link automatically on any platform that supports tap devices. This includes most Unix-like systems, which usually have a dedicated device node for creating tap network interfaces. They usually have names like /dev/tap. The other methods are supported for legacy purposes or in case the respective interfaces are supported or not. Once connected, you can perform various network operations, including configuration, network address translation (NAT), etc. You should even be able to connect your emulated machine to the Internet. See

You can also set up a TAP ethernet port by using OpenVPN. It comes with a driver called TAP-Windows which creates a virtual network interface. You may have to create your own using the tapctl program that comes with OpenVPN. You might have to do this anyway, as NME assumes that the hardware id of the interface is "tap0901", whereas OpenVPN sets it up as "root\tap0901" by default. You can alternately give it a name, like "nme", so that you can have more than one tap interface:

tapctl.exe create --hwid tap0901 --name nme

Afterwards, you will have a TAP interface that you can use like any other regular network interface. You can manage it in the same way; for more info, see ManagingWindowsTapDrivers. The OpenVPN configuration interface can be used to configure it automatically. NME has this same interface built into it, so you should simply be able to use the same configuration line to set up an OpenVPN TUN/TAP interface in the NME config file or nmesh shell:

 tap0 at le0: nme/host/openvpn/tun/tap --dev tap --dev-node nme --ifconfig 10.0.77.1 255.255.255.0 --tun-ipv6 --ifconfig-ipv6 "2001:db8::1/64" "2001:db8::2"

Although it comes with OpenVPN, you may also get TAP-Windows independently; see GettingTapWindows.