Welcome to nme Wiki

nme

Welcome to The Machine Emulator (TME)!

The Phabrics TME Page gives more background information about this project. Here is a quick rundown of how to install & run tme.

---

Installation

There are a couple of ways to install tme.

Source Tarball

First, you can install from source tarball available here. This is the most portable method and should work on most POSIX-like environments using the standard configure/make/install procedure:

 wget https://osdn.net/dl/nme/tme-<version>.tar.xz
 tar xJf tme-<version>.tar.xz
 cd tme-<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 sjlj, pthreads, or glib. Default threading model is sjlj, which is cooperative multithreading or fibers, which is the same as --disable-threads
• --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.

Package Manager

Alternatively, if your platform has a package manager, and TME is in it, you can use that instead. For instance, if you are using a mingw64 environment from MSYS2, you can use the wonderful pacman installer to directly install the latest built release as follows:

 pacman -S ${MINGW_PACKAGE_PREFIX}-tme

This installs for the five main mingw64 environments, depending upon which one you are in: ucrt64, mingw32, mingw64, clang32, clang64, clangarm64. To install all at once, use ".*" in place of the MINGW_PACKAGE_PREFIX variable.

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

Normally, you can just run like this:

 tmesh --log - [<machine_desc>]

On mingw64, you will have to use some built-in environment variables to point things at the right place for the environment:

 export TME_MODULE_PATH=${MINGW_PREFIX}/lib

Setting the TME_MODULE_PATH environment variable is so that the plugin modules can be found at the given value. Unfortunately, it is needed right now because the file interface requires the full system path rather than just the POSIX-relative paths (cygpath). This may be remedied in future versions, but for now, you can use this method. You may also use the LTDL_LIBRARY_PATH instead of TME_MODULE_PATH if you wish, but the first is preferred to avoid possible clashes.

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. TME 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 tme-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 tme-make-machs script. This script performs all the necessary steps for a basic setup of a new tme 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 TME! Note that for the time being, you should obtain it at the link above. It will be available in future revisions of TME 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+, SDL2 or VNC host interface. See TME 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. TME 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 TME 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 TME:

console0 at zs0 channel A: tme/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 TME for more info.

Networking

There are a few ways to do networking with TME. 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 TME 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 TME 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 "tme", so that you can have more than one tap interface:

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

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. TME 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 TME config file or tmesh shell:

tap0 at le0: tme/host/openvpn/tun/tap --dev tap --dev-node tme --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.