A machine can be set up in three ways:
A configuration file describes one machine. Several machines are run as several GXemul processes, connected with their network settings (UDP ports and remote hosts), as in the diskless examples in the machine documentation.
(The older configuration file format, gxemul @configfile, is no longer supported.)
The window lists the machines used recently. Select one to see a summary of it, and:
The editor has a page for each part of the configuration: General (name, architecture, machine type and model, memory, CPU), Firmware (a system ROM image and the option ROM images of the TURBOchannel cards, or PROM emulation with files to load and the boot file name and argument, and the NVRAM file, with a button to reset it), Drives (disks, CD-ROMs, tapes, and floppies; on a DECstation, a drive can be one of DEC's, e.g. an RZ26 disk, which a new disk image gets the size of, or say it is any other drive; missing disk images can be created with a given size), Display (the framebuffer window, its size, the number of graphics cards, and serial ports on telnet ports), Network, and Advanced. The line above the buttons says what's missing before the machine can be started. Save writes the file, and creates the disk images that are missing; Save and Start also starts the machine. The first time a new machine is saved, a file chooser asks where: the name given is a folder for the machine (with its machine.json, and its new disk images), or, if it ends in .json, the configuration file itself. File choosers start in the folder used last. Escape or Cancel leaves the editor without saving.
The machine is chosen on the General page, with an architecture (MIPS, PowerPC, ...), a machine type of that architecture (e.g. DECstation/DECsystem), and a model, if the type has models (e.g. DECstation 5000/200). Only the models known to work are offered: the DECstations 3100, 5000/200, and 5000/1xx, the SGI O2, and the MIPS test machine. Show all machines also offers the others, which may not work. A new machine starts as a DECstation 5000/200, and until it is saved, choosing another model gives it that model's defaults (memory, drives, firmware, and display). A new DECstation runs a real system ROM image, chosen on the Firmware page; with PROM emulation (a checkbox there), no ROM image is needed, and gxemul boots a kernel itself, from a drive or from files to load.
A running machine's window has these menus:
A running machine started from a configuration file has Edit Configuration... in its window's Machine menu. This opens its configuration in the editor, in a window of its own, while the machine keeps running; the changes take effect when the machine is started again.
File names can be typed or chosen with Browse..., which uses the desktop's file chooser. Text fields are edited at the end (backspace and typing), and Ctrl+V (Command+V on macOS) pastes.
A machine is usually a folder with its machine.json, and its disk images. File names in machine.json are relative to its folder, unless they are absolute. When it is saved, a file in its folder (or below it) is kept relative to it, so the folder can be moved or copied as a whole, and other files by their absolute names. New machines are saved in ~/GXemul (Documents\GXemul on Windows), unless another place is chosen.
ROM images (the "rom" and "slots" files) given by a relative name are looked for in the machine's folder, then in the common ROM folder, ~/GXemul/ROMs by default, and then in other folders. These are set with Settings... in the machines window. A ROM image in one of these folders is kept by its name relative to that folder, so several machines can use the same ROM images, wherever they are.
The list of recently used machines (recent.json), and the settings (settings.json: the ROM folders, and the folder last used in a file chooser) are kept in:
A machine.json is a JSON object with a "gxemul" key (the format version, 1). Every other key is optional, and has the default shown here, except for the machine type:
{
"gxemul": 1,
"name": "My DECstation",
"machine": {
"type": "decstation", the machine type and model, as for -E and -e
"model": "3max", (see gxemul -H)
"cpu": "", "" = the machine's default
"cpus": 0, 0 = 1
"memory_mb": 0, 0 = the machine's default
"emulated_hz": 0,
"byte_order": "", "", "big", or "little"
"random_memory": false,
"random_bootstrap_cpu": false,
"serial_nr": 0 0 = automatic
},
"boot": {
"prom_emulation": true, false = run a real ROM (as -Q)
"rom": "", the system ROM image (loaded at 0xbfc00000 on DECstations)
"load": [], other files to load, e.g. "netbsd" or "0xbfc00000:rom.bin"
"bootname": "", as -j
"bootarg": null, as -o; null = the default
"netboot": false, as -O
"start_paused": false,
"nvram": "", a file for the RTC's NVRAM (the firmware's settings), "" = not kept
"skip_failing_tests": false load copies of known ROMs whose tests that fail in gxemul pass
},
"drives": [
{ "file": "disk.img", "" for a CD-ROM or tape drive without a medium
"kind": "disk", "disk", "cdrom", "tape", or "floppy"
"bus": "default", "default", "scsi", or "ide"
"id": -1, the SCSI ID, -1 = the next free one
"readonly": false,
"overlay": false, writes go to a temporary overlay (as the R prefix of -d)
"boot": false,
"vendor": "", what a SCSI drive says it is (INQUIRY), "" = the usual:
"product": "", e.g. "DEC", "RZ26 (C) DEC", "T386" (up to 8, 16,
"revision": "" } and 4 characters)
],
"display": {
"enabled": false, framebuffer windows (as -X)
"scale": 0, the window size in percent (e.g. 50, 100, 200), 0 = fit the screen
"cards": -1 graphics cards, -1 = the default (as -Z)
},
"serial": { "telnet": false }, serial ports on telnet ports (as -x; on with the framebuffer)
"slots": { "0": "PMAG-BA.bin" }, option ROM images, by TURBOchannel slot (see the 5000/200's slots 5 and 6)
"network": {
"enabled": true,
"ipv4": "10.0.0.0",
"ipv4len": 8,
"local_port": 0, a UDP port for connecting emulators, 0 = none
"remotes": [], e.g. "localhost:12345"
"tapdev": "", as -L
"l2tp": { "enabled": false, "session": 1, "cookie": "", "counter": true }
},
"devices": [] extra devices, as for the debugger's device add
}
|
(The comments in blue are not part of the file: JSON has no comments.)
This starts NetBSD/pmax from a disk image in the same directory, on an emulated DECstation 5000/200, with PROM emulation and a framebuffer:
{
"gxemul": 1,
"name": "NetBSD/pmax",
"machine": { "type": "decstation", "model": "3max", "memory_mb": 64 },
"boot": { "bootname": "netbsd" },
"drives": [ { "file": "netbsd-pmax.img", "kind": "disk", "id": 0 } ],
"display": { "enabled": true }
}
|
And this runs the real ROM of a DECstation 5000/1xx, with the option ROM image of a PMAG-BA framebuffer in slot 0, and a CD-ROM to install from:
{
"gxemul": 1,
"name": "DECstation 5000/133",
"machine": { "type": "decstation", "model": "3min", "memory_mb": 32 },
"boot": { "prom_emulation": false, "rom": "decstation5000_133.bin" },
"drives": [ { "file": "disk.img", "kind": "disk", "id": 0 },
{ "file": "ultrix-4.5.iso", "kind": "cdrom", "id": 4 } ],
"display": { "enabled": true },
"slots": { "0": "PMAG-BA_V5.3a.bin" }
}
|