Merge branch '86Box:master' into master

dev/buildguide.rst

@@ -168,9 +168,9 @@ FreeBSD
 
 .. code-block:: bash
 
-    $ pkg install pkgconf freetype-gl sdl2 libspng openal-soft rtmidi qt5 libslirp fluidsynth libsndfile
+    $ pkg install cmake pkgconf freetype-gl sdl2 libspng openal-soft rtmidi qt5 libslirp fluidsynth libsndfile
 
-.. note:: If you get an error about ``linux/input.h``, edit ``/usr/local/include/libevdev/libevdev.h`` to replace the ``linux/input.h`` reference with ``dev/evdev/input.h`` and try building again.
+.. note:: If you get an error about ``linux/input.h`` while building, this is due to ``libevdev.h`` mistakenly importing a Linux header file on FreeBSD. Copy the full path of ``libevdev.h`` from the error and open it with an editor. Within the file, replace the ``linux/input.h`` reference with ``dev/evdev/input.h`` and try building again.
 
 Building
 --------

dev/builds.rst

@@ -25,11 +25,12 @@ Variants
 Discontinued variants
 ^^^^^^^^^^^^^^^^^^^^^
 
-The following variants are no longer built by Jenkins and can only be :doc:`compiled from source <buildguide>`:
+The following variants are no longer built by Jenkins and can only be :doc:`compiled from source <buildguide>` where applicable:
 
 * 32-bit architectures (**x86** and **ARM32**) as of September 3rd 2024.
 
   * These were eliminated to better focus development on relevant 64-bit architectures, since systems old enough to be 32-bit-only lack the performance for a satisfactory emulation experience.
+  * The dynamic recompiler and other components no longer support 32-bit architectures as of September 13th 2025.
 
 * Debug variants (**86Box-Debug**) as of April 2nd 2023.
 

hardware/externalopl.rst

@@ -1,19 +1,16 @@
-External OPL Audio Support
-==========================
+External OPL audio
+==================
 
-86Box now supports the **OPL2Board** as an external audio device.  
-This allows users to connect a real OPL2 (YM3812) chip through the board and use it alongside the emulator for authentic FM synthesis output.
+The **YMOPL2Board** :ref:`sound card <settings/sound:Sound card #1-#4>` allows for a real Yamaha OPL2 (YM3812) chip to be connected to the emulated machine for authentic FM synthesis output.
 
 Usage
 -----
 
-1. Connect your OPL2Board to the host system.  
-2. Select the sound card **[ISA] OPL2Board [External Device]**.  
-3. In the **Configure** button, select the serial port to which the board is connected.
+1. Connect the `OPL2 Audio Board from Cheerful Electronic <https://www.cheerful.nl/OPL2_Audio_Board/>`_ to a `supported Arduino board <https://github.com/DhrBaksteen/ArduinoOPL2/wiki/Connecting-the-OPL2-Audio-Board>`_.
+2. Connect the Arduino board to the host system.
+3. Select the **YMOPL2Board (External Device)** sound card on the :ref:`emulated machine's configuration <settings/sound:Sound card #1-#4>`.
+4. Use the *Configure* button to select the Arduino's serial port.
 
-Notes for OPL2Board
--------------------
-
-- You need an **Arduino Nano** and an **OPL2Board** from Cheerful Electronic.
-- Follow the **instructions from the manufacturer** and upload ``SerialPassthrough.ino`` to the Arduino Nano.
-- If you want **PCM audio**, you can add an **additional sound card** and disable the OPL output.
+.. note::
+  * The **OPL3 Duo!** board is currently not supported.
+  * Regular **PCM/wave audio** still requires an emulated sound card to be configured. If the emulated sound card provides its own OPL, it can often be **muted** through a mixer utility within the machine.

settings/floppycdrom.rst

@@ -18,6 +18,7 @@ Up to four floppy disk drives can be attached to the emulated machine, although
 
 * **Turbo timings:** run the drive mechanism as fast as possible. This decreases access times and makes some incorrectly-dumped floppies readable, but may cause issues with some operating systems and applications.
 * **Check BPB:** if unchecked, 86Box will ignore the `DOS BIOS Parameter Block <https://en.wikipedia.org/wiki/BIOS_parameter_block>`_ when determining the physical media format for a floppy image on this drive. See :ref:`hardware/diskimages:Floppy disk detection` for more details.
+* **Audio:** emulate the mechanical sounds of a real floppy drive. A list of drive models to choose from is provided; the *None* option disables these sounds.
 
 .. note:: Disabling "Check BPB" may be required in order to access UNIX/Linux installation floppies or other non-DOS disks, as outlined on :ref:`hardware/diskimages:Floppy disk detection`.
 

settings/machine.rst

@@ -5,10 +5,10 @@
 
 The **Machine** page contains settings related to the emulated machine as a whole, such as the machine type, CPU type and amount of memory.
 
-Machine type / Machine
-----------------------
+Search / Machine type / Machine
+-------------------------------
 
-Machine/motherboard model to emulate. The *Machine* box lists all available models for the machine class selected on the *Machine type* box.
+Machine/motherboard model to emulate. The *Machine* box lists all available models for the machine class selected on the *Machine type* box, while the *Search* box allows for finding and selecting a model from any class directly by name.
 
 The *Configure* button opens a new window with settings specific to the machine, such as BIOS type selection.
 
@@ -49,14 +49,6 @@ Softfloat FPU
 
 Enable a slower but more accurate math co-processor emulation, for running a limited set of operating systems and applications which demand full 80-bit precision from the floating point unit.
 
-CPU frame size
---------------
-
-Change the emulator's frame timing behavior. This mostly affects the smoothness of the emulated mouse and other input peripherals.
-
-* **Larger frames (less smooth):** same behavior as previous 86Box versions. Switching to it may improve performance on low-end host systems, at the expense of reduced input smoothness.
-* **Smaller frames (smoother):** the new default behavior, which improves input smoothness.
-
 Time synchronization
 --------------------
 
@@ -65,3 +57,11 @@ Automatically copy your host system's date and time over to the emulated machine
 * **Disabled:** do not perform time synchronization. The emulated machine's date and time can be set through its operating system or BIOS setup utility. Time only ticks while the emulated machine is running.
 * **Enabled (local time):** synchronize the time in your host system's configured timezone. Use this option when emulating an operating system which stores *local time* in the hardware clock, such as DOS or Windows.
 * **Enabled (UTC):** synchronize the time in Coordinated Universal Time (UTC). Use this option when emulating an operating system which stores *UTC time* in the hardware clock, such as Linux.
+
+CPU frame size
+--------------
+
+Change the emulator's frame timing behavior. This mostly affects the smoothness of the emulated mouse and other input peripherals.
+
+* **Larger frames (less smooth):** same behavior as 86Box 4.2.1 and older. Switching to it may improve performance on low-end host systems, at the expense of reduced input smoothness.
+* **Smaller frames (smoother):** the new default behavior introduced in 86Box 5.0, which improves input smoothness.

settings/sound.rst

@@ -16,8 +16,7 @@ The *Configure* button opens a new window with settings specific to the selected
 
 Emulation for the Yamaha OPL series of synthesizers (used by many of the emulated cards) is provided by a modified `Nuked OPL3 <https://github.com/nukeykt/Nuked-OPL3>`_ or `ymfm <https://github.com/aaronsgiles/ymfm>`_ library, per the :ref:`selection below <settings/sound:FM synth driver>`. MOS Technology 6581 SID emulation for the Innovation SSI-2001 and The Entertainer is provided by the reSIDfp component of the `libsidplayfp <https://github.com/libsidplayfp/libsidplayfp>`_ library. General Instrument AY-3-8913 emulation for the Mindscape Music Board is provided by the `Ayumi <http://sovietov.com/app/ayumi/ayumi.html>`_ library.
 
-You can also select an external OPL sound card by choosing the sound cards that have **(External Device)** at the end of their name.  
-See more information in the :ref:`External OPL audio device documentation </hardware/externalopl:External OPL Audio Support>`.
+The **YMOPL2Board** requires an external hardware device containing an OPL2 chip. See :doc:`../hardware/externalopl` for more information.
 
 MIDI Out Device
 ---------------

usage/faq.rst

@@ -44,6 +44,17 @@ There is no formula that would tell you this. In general, the higher the host's
 
 Therefore, the best way to optimize your virtual machine configuration is simply trial and error.
 
+Can I use 86Box to run a Windows XP system?
+-------------------------------------------
+
+We strongly discourage the use of 86Box to run Windows XP or newer Windows operating systems.
+
+While the operating system does run, the Windows XP system requirements are steep compared to what 86Box can offer, and what most host systems are capable of running at 100%. Microsoft publishes the *minimum* system requirements of Windows XP to include a 233 MHz Pentium.  The recommended requirements of Windows XP bump the requirements up to include a 300 MHz Pentium or better.
+
+Even though these requirements seem modest in the present day, only some of the newest AMD (Ryzen 5000 series or better), Intel (Core 12th generation or better), and Apple (M2 or better) processors are capable of meeting the bare minimum Windows XP requirements under 86Box’s full system emulation.  On top of the operating system requirements, most software and games that require Windows XP will demand even more out of the hardware than Windows XP alone, reducing the utility of Windows XP in 86Box to a very narrow set of software.
+
+It is almost always better to run Windows XP in a different virtualizer or emulator.  On AMD and Intel based PCs, software such as `VirtualBox <https://www.virtualbox.org/>`_ or `Hyper-V <https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/Install-Hyper-V?tabs=powershell&pivots=windows/>`_ can run Windows XP close to bare-metal performance, as most CPU instructions can run unmodified.  On Apple macOS computers, `UTM <https://mac.getutm.app/>`_ is capable of either running Windows XP in full hardware virtualization on Intel Macs, or with highly optimized x86 emulation on M-series Macs.  UTM does not chase the fine-detail historic accuracy of 86Box and as such, is able to take “shortcuts” that can allow Windows XP and software on it to run with acceptable performance even under x86 emulation.
+
 Are you going to add emulation of the Pentium 3 and/or newer CPUs?
 ------------------------------------------------------------------
 

usage/manager.rst

@@ -19,6 +19,11 @@ The **left-hand side** of the manager window displays a list of all machines fou
 
 The following options are available by **right-clicking** a machine:
 
+* **Start:** start the machine.
+* **Hard reset:** force a reset of the machine.
+* **Force shutdown:** force a shutdown of the machine. If this fails due to a frozen 86Box process, try *Kill*.
+* **Ctrl+Alt+Del:** send a *Ctrl+Alt+Del* key combination to the machine.
+* **Settings:** open the :doc:`Settings <../settings/index>` window to configure the machine.
 * **Change display name:** change the name by which the machine is identified on the manager and 86Box window. Changing this will not rename the machine's folder.
 * **Set icon:** change the icon displayed next to the machine on the list.
 
@@ -75,8 +80,10 @@ Tools
 
   * **System Directory:** view or change the folder where emulated machines are stored.
   * **Language:** select a language for the 86Box user interface.
+  * **Remember size & position:** automatically save the manager window's size and position and the machine list's width.
   * **Check for updates on startup:** automatically check for 86Box updates when starting the manager.
   * **Use regular expressions in search box:** enable the use of Perl-syntax regexes to perform more complex searches with the search box.
+  * **Color scheme:** select a visual style for the 86Box user interface. *System* uses the operating system's global preference if possible.
 
 .. note::
   * The manager **must be restarted** for any changes to the system directory to take effect.

usage/menubar.rst

@@ -25,7 +25,7 @@ View
 * **Hide status bar:** hides the :doc:`status bar <statusbar>` at the bottom of the window.
 * **Show non-primary monitors:** shows or hides the secondary display window if a :ref:`secondary video card <settings/display:Video #2>` is configured.
 * **Resizeable window:** allow the 86Box window to be freely resized. Unchecking this option will also return the window to its normal size.
-* **Remember size & position:** automatically save the size and position of the 86Box window to the emulated machine's configuration file.
+* **Remember size & position:** automatically save the 86Box window's size and position for this emulated machine.
 * **Renderer:** select a graphical renderer for the emulated display.
 
    * **Qt (Software)** is recommended in most cases.
@@ -88,7 +88,7 @@ Tools
 * **Update status bar icons:** enable the activity lights on :doc:`status bar <statusbar>` icons. Unchecking this option may improve emulation performance on low-end host systems.
 * **Enable Discord integration:** enable Discord Rich Presence. 86Box shares the emulated machine's name, model and CPU with other Discord users.
 
-.. note:: Integration requires the Discord desktop app, running on x64 Windows, ``x86_64`` Linux or Intel macOS. Discord does not provide integration support for other operating systems / architectures or the browser app. Additionally, integration will not be available on Windows if the included ``discord_game_sdk.dll`` file is missing from the 86Box directory.
+.. note:: Integration requires the Discord desktop app, running on Windows, Linux (``x86_64`` only) or macOS. Discord does not provide integration support for other operating systems / architectures or the browser app. Additionally, integration will not be available on Windows if the included ``discord_game_sdk.dll`` file is missing from the 86Box directory.
 
 * **Take screenshot:** take a screenshot of the emulated display. Screenshots are saved as .png images in the ``screenshots`` subdirectory found in the emulated machine's directory, which can be opened with the **Open screenshots folder** option below. You can alternatively press :kbd:`Ctrl`\ +\ :kbd:`F11` (:ref:`customizable <settings/input:Key bindings>`) to take a screenshot.
 * **Sound:** provides the same options that are accessible by clicking the :ref:`sound icon on the status bar <usage/statusbar:|sound| Sound>`.
@@ -99,6 +99,7 @@ Tools
    * **Select media images from program working directory:** if checked, starts any file open/save prompts on the emulated machine's directory. This option is particularly useful for macOS users.
    * **Inhibit multimedia keys:** if checked, multimedia keys such as **Volume Up/Down** will not be passed through to the emulated machine.
    * **Ask for confirmation before saving settings / quitting / hard resetting:** enable confirmation messages for certain actions. These options can reenable confirmations after they have been disabled through the *Don't show this message again* box.
+   * **Color scheme:** select a visual style for the 86Box user interface. *System* uses the operating system's global preference if possible.
 
 .. note:: The *Preferences* window options are **saved system-wide** and apply to all machines on all copies of 86Box 5.0 and newer. Any changes made with previous versions (saved per-machine) have been reset.