# Release notes for GXemul 0.7.0

Copyright (C) 2003-2021 Anders Gavare

GXemul is a framework for full-system computer architecture emulation. Several processor architectures and machine types have been implemented. It is working well enough to allow unmodified "guest" operating systems to run inside the emulator, as if they were running on real hardware.

The emulator emulates (networks of) real machines. The machines may consist of ARM, MIPS, Motorola 88K, PowerPC, and SuperH processors, and various surrounding hardware components such as framebuffers, busses, interrupt controllers, ethernet controllers, disk controllers, and serial port controllers.

The changes between release 0.6.3.1 and 0.7.0 include:

- The LUNA-88K machine now has working SCSI emulation. This allows OpenBSD/luna88k to be installed and run using a harddisk image. (Previously, a more complicated root-on-nfs setup had to be used.)

- There is now a shorthand disk image prefix 'R' (uppercase), to reduce the amount of typing when one wants to use a temporary throwaway disk image overlay, that is when one does not want to allow writes to a disk image. Previously, this would require something like:

  -     touch overlay.img overlay.img.map
        gxemul -e ..... -d disk.img -d V0:overlay.img
        rm overlay.img overlay.img.map

  which now becomes just:

  -     gxemul -e ..... -d R:disk.img

  The difference to using an explicit V: overlay is that the temporary file is removed automatically when the GXemul process exits. A guest operating system will still perceive the disk as writable.

- Networking using a tap device can now be enabled directly on the command line using a new `-L` option. Previously, tap devices could only be enabled when using configuration files.

- A bug has been fixed for MIPS R2000/R3000 when writing to coprocessor 0's ENTRY LO register. This fixes a regression introduced between 0.6.1 and 0.6.2 where running `xinit` inside Sprite (on an emulated DECstation) suddenly failed.

- A "mouse grab" mechanism has been implemented for X11 framebuffer windows. Previously, mouse movements occuring inside a framebuffer window were always forwarded to the guest OS. Interaction was akward, in particular due to mouse acceleration being performed by the guest OS. Now, instead, the framebuffer window needs to be clicked in, in order to activate mouse pointer grabbing. When the grab mode is active, mouse movements (and button clicks) are forwarded to the guest OS, and the host's mouse cursor is hidden. Grab mode is released when typing Left CTRL + ALT, or when otherwise changing focus to another X11 window.

- Previously, the behavior when using configuration files was to always start new terminal windows (xterms) for emulated serial I/O ports, similar to the `-x` command line option. This has now been changed, so that new terminal windows are only used if there are two or more machines in the same configuration file. If you still want separate terminal windows to be launched when using a configuration file with a single machine in it, you now need to add `-x` to the command line.

- Some cleanup to make the `-K` command line option work more like it was always supposed to. This option should cause the emulator to show the `GXemul>` debugger prompt whenever the emulated program or guest operating system ends, regardless of whether it was a normal shutdown or some form of error. This is useful for example if you wish to disassemble the code, or inspect register or memory content, at the point of failure. Starting the emulator with `-V` also implicitly sets `-K`. If neither `-V` nor `-K` is used, and the guest OS halts with powerdown or "reboots", the emulator should exit gracefully (for the machine modes where shutdown functionality has been implemented via device support or prom emulation support).

  (There are still many explicit `exit()` calls throughout the code, which over time will need to be manually converted to work with `-K`, but the most common ones are fixed.)

- `-T` has been fixed to work the way it was always intended to work, namely to abort immediately on the first load or store to non-existant memory. This is useful in combination with `-K`, for example when implementing new machine modes in the emulator or trying out unsupported guest operating systems that access memory or devices in a not-yet-implemented way.

- Debug messages have traditionally been printed using the rather course-grained `debug()` and `fatal()` functions. Work has now begun to separate this into a number of subsystems, which can have their verbosity levels be individually controlled using the new `verbosity` debugger command. This also standardizes the way debug messages are formatted:

  -     [ machine-and-cpu-path: subsystem-name component-or-function-name: text ]

  Most of the time, not all of these are shown. machine-and-cpu-path, for example, is only shown if the message comes from a context where a CPU is known to cause the message, and there are multiple machines or CPUs being emulated. The [ ] brackets are only shown when intermixing debug messages with serial I/O coming from the emulated program or guest operating system.

  (There are still a huge amount of `debug()` and `fatal()` calls in the code, especially in the less commonly used code paths.)

- Output from the emulator is now subtly colorized, to make it easier to quickly interpret the text. This is enabled by launching the emulator with the environment variable CLICOLOR set, or by usign the `-G` command line option. The choice of colors was done to a) be reasonably subtle, and b) work with both light and dark terminal backgrounds. Coloring can be explicitly disabled using `-A` (overriding the presence of CLICOLOR), and it is also disabled when outputting to a non-tty.

The source code has been switched back from C++ to plain C:

- The "new" framework was removed. Instead of two different emulators in the same program, there's just the traditional emulation framework.

- A C compiler supporting the C99 standard is needed in order to build GXemul.

- For third parties that package GXemul (e.g. for package managing systems used by operating systems or distributions), build scripts may need to be modified:
  - The unit tests (`make test`) are gone.
  - The (optional) dependency on Valgrind is gone. It was used for running leak detection during unit test execution, but the unit tests were for the C++ framework.
  - The (optional) dependency on Doxygen is gone. It was used for building documentation of the source code in the C++ framework.
  - Automatic generation of machine and component documentation is gone (`make documentation`).
  - In summary: the `doc/` directory is now just a single level without sub-directories, containing static content; nothing is generated at build time.

Please read the HISTORY file for more details.

Regarding files in the `src/include/thirdparty/` directory: most of these are from other open source projects such as NetBSD. See individual source files for details, if you plan to redistribute GXemul in binary form, or reuse the source code.

GXemul's homepage is http://gavare.se/gxemul/.