From e3ad191cf838bc2b0a7f60d1d59ae969064ba401 Mon Sep 17 00:00:00 2001 From: RichardG867 Date: Sun, 24 Aug 2025 19:54:30 -0300 Subject: [PATCH] Initial manager documentation --- hardware/isabugger.rst | 2 +- hardware/machinespecific.rst | 4 +- index.rst | 1 + usage/gettingstarted.rst | 4 +- usage/manager.rst | 93 ++++++++++++++++++++++++++++++++++++ usage/menubar.rst | 4 +- 6 files changed, 102 insertions(+), 6 deletions(-) create mode 100644 usage/manager.rst diff --git a/hardware/isabugger.rst b/hardware/isabugger.rst index 5c824de..e55c673 100644 --- a/hardware/isabugger.rst +++ b/hardware/isabugger.rst @@ -3,7 +3,7 @@ ISABugger The ISABugger card provides a debugging interface for software developers, consisting of two 8-bit hexadecimal displays and two banks of 8 LEDs, all controlled by the emulated machine. It can be enabled through the :ref:`Peripherals settings page `. -These displays and LEDs are displayed on the :ref:`status bar ` as described in the diagram below: +These displays and LEDs are displayed in the :ref:`status bar ` as described in the diagram below: .. image:: images/isabugger.png :align: center diff --git a/hardware/machinespecific.rst b/hardware/machinespecific.rst index 2d477f5..e0c4732 100644 --- a/hardware/machinespecific.rst +++ b/hardware/machinespecific.rst @@ -34,7 +34,7 @@ This page contains important notes related to specific machine models emulated b .. rubric:: IBM AT * On-board RAM is limited to 512 KB; more can be added through :ref:`ISA memory expansion ` cards. -* The IBM Personal Computer Diagnostics disks are not Y2K-compliant and will produce a *0152 ERROR - SYSTEM BOARD* code if :ref:`time synchronization ` is enabled. This code can be cleared by disabling time synchronization, then clearing the CMOS by deleting ``ibmat.nvr`` from the machine's ``nvr`` directory. +* The IBM Personal Computer Diagnostics disks are not Y2K-compliant and will produce a *0152 ERROR - SYSTEM BOARD* code if :ref:`time synchronization ` is enabled. This code can be cleared by disabling time synchronization, then wiping NVRAM :ref:`through the VM manager ` or by deleting ``ibmat.nvr`` from the machine's ``nvr`` directory. .. rubric:: IBM XT Model 286 @@ -80,7 +80,7 @@ Socket 7 .. rubric:: MSI MS-5119 -* 86Box versions prior to 4.0.1 used BIOS version *A37E*, which has PS/2 mouse issues. The fixed *A37EB* BIOS is not applied automatically to existing setups; it can be applied by deleting ``ms5119.bin`` from the machine's ``nvr`` directory. +* 86Box versions prior to 4.0.1 used BIOS version *A37E*, which has PS/2 mouse issues. The fixed *A37EB* BIOS is not applied automatically to existing setups; it can be applied by wiping NVRAM :ref:`through the VM manager ` or deleting ``ms5119.bin`` from the machine's ``nvr`` directory. .. _p65up5: .. rubric:: ASUS P/I-P65UP5 (C-P55T2D) diff --git a/index.rst b/index.rst index 93be648..e1f7d01 100644 --- a/index.rst +++ b/index.rst @@ -34,6 +34,7 @@ Contents usage/gettingstarted usage/faq usage/roms + usage/manager usage/menubar usage/toolbar usage/statusbar diff --git a/usage/gettingstarted.rst b/usage/gettingstarted.rst index 3a17afb..e491227 100644 --- a/usage/gettingstarted.rst +++ b/usage/gettingstarted.rst @@ -3,6 +3,8 @@ Getting started Here are the basic steps to help you get started with 86Box. The user interface has been designed to resemble Virtual PC, VirtualBox and other virtualizers, so if you used those programs before, this should all look familiar to you. +.. important:: The steps on this guide are outdated and will be updated soon to reflect the :doc:`manager`. + .. rubric:: Step 1: Get the ROM set 86Box relies on a set of ROM dumps gathered from physical hardware to emulate it. This includes the system BIOS, as well as any option ROMs used by expansion cards. If you try to start 86Box without one, you'll receive an error and 86Box will close. You need to download the ROM set from `here `_, and extract it into one of the :doc:`supported locations `. @@ -35,7 +37,7 @@ Now you're ready to do some stuff inside the emulated machine. Keyboard input is Mouse input has to be manually "captured" and "released". To capture the mouse in the emulated mahine, simply click inside the renderer area. Your host mouse cursor will disappear and your mouse movement and clicks will be redirected into the emulated machine. Now you can use the mouse inside the emulated machine - if the software and hardware configuration supports it, of course. -To release the mouse, press :kbd:`F8 + F12` simultaneously. You can also use the middle mouse button for this if the emulated mouse only has two buttons. +To release the mouse, press :kbd:`Ctrl` + :kbd:`End` simultaneously. You can also use the middle mouse button for this if the emulated mouse only has two buttons. .. rubric:: Step 7: What now? diff --git a/usage/manager.rst b/usage/manager.rst new file mode 100644 index 0000000..63dd7e8 --- /dev/null +++ b/usage/manager.rst @@ -0,0 +1,93 @@ +VM manager +========== + +Opening 86Box will start the **virtual machine manager**, which allows for creating, managing, starting and controlling multiple emulated machine configurations. + +.. note:: + * This manager is currently a preview, with a limited feature set expanding upon the previous standalone `86Box Manager `_ app. Other managers with more features can still be used. + * Running 86Box directly no longer creates or starts an emulated machine in the current folder like on previous versions. The ``-P``/``--vmpath`` command line option can be used to start a machine directly instead. + +Machine list +------------ + +The **left-hand side** of the manager window displays a list of all machines found in the :ref:`system directory `, along with their current state and icon. Click on a machine to select it. + +The following options are available by **right-clicking** a 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. + + * Select an icon from the preset list, or click **Reset** to restore the default icon. + +* **Clone:** make a copy of the machine. +* **Kill:** forcibly terminate the machine's 86Box process if one is running. +* **Wipe NVRAM:** clear the machine's CMOS non-volatile memory. On models with Flash ROM, the original BIOS is also reflashed. +* **Delete:** delete the machine, along with **everything** stored within its directory. +* **Open folder:** open the directory where the machine's configuration file is stored. +* **Open printer tray**: open the directory where documents printed by the machine's :ref:`emulated printers ` are saved. +* **Open screenshots folder**: open the directory where screenshots of the machine are saved. +* **Show config file:** display the contents of the machine's ``86box.cfg`` file for sharing, support requests and bug reports. + +Search +^^^^^^ + +The **search box** at the bottom of the machine list allows for filtering the machine list by any of the following criteria: + +* **Display name** and **folder name**. +* Names of **hardware components** present in the machines, as displayed in the :ref:`details pane `. +* **Image file names** for any media inserted into the machines, including hard disks, floppies and CDs. + +Advanced users can :ref:`enable regular expressions ` to perform more complex searches. + +Machine details +--------------- + +The **right-hand side** of the manager window displays information and controls for the selected machine: + +* A **summary** of the machine's :doc:`configuration <../settings/index>`. +* A gallery of **screenshots** saved through :ref:`Take screenshot ` or the respective keyboard shortcut. +* A small text area for writing any **notes** about the machine. +* Controls for the machine: **Settings**, **Hard reset**, **Force shutdown**, **Start**/**Pause**, **Ctrl+Alt+Del**. +* The machine's current **status**, with the 86Box process ID if one is running. + +Menu bar +-------- + +The **menu bar** located at the top of the manager window provides controls for the manager as a whole. + +File +^^^^ + +* **New machine:** create a new machine from scratch or from an existing configuration file. +* **Exit:** quit the manager. Requires confirmation if any machines are currently running. + +Tools +^^^^^ + +.. _preferences: + +* **Preferences:** open the *Preferences* window, which provides the following options: + + * **System Directory:** view or change the folder where emulated machines are stored. + * **Language:** select a language for the 86Box user interface. + * **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. + +.. note:: + * The manager **must be restarted** for any changes to the system directory to take effect. + * The system directory is **scanned recursively** for machines through their ``86box.cfg`` files. + +* **Check for updates:** check for and download any available 86Box version update. + +Help +^^^^ + +* **Documentation:** open the very documentation you're reading. +* **About 86Box:** show credits, license and build information about 86Box. + +Status bar +---------- + +The **status bar** located at the bottom of the manager window displays a **count** of running, paused and total available machines. + +Additionally, any information about **available updates** will be displayed in the status bar if :ref:`checking for updates on startup ` is enabled. diff --git a/usage/menubar.rst b/usage/menubar.rst index 7a6a67a..5af4a54 100644 --- a/usage/menubar.rst +++ b/usage/menubar.rst @@ -88,7 +88,7 @@ Tools * **Update status bar icons:** enable the activity lights on :doc:`status bar ` 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 x86 or 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 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. * **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 *Ctrl+F11* (:ref:`customizable `) to take a screenshot. * **Sound:** provides the same options that are accessible by clicking the :ref:`sound icon on the status bar `. @@ -104,7 +104,7 @@ Tools * **MCA devices**: open the *MCA devices* window, which lists the IDs and required `Adapter Definition Files `_ of all Micro Channel devices installed on the emulated machine. This option will only be available when emulating a Micro Channel Architecture-based machine. * **Open printer tray**: open the host system's file browser on the directory where documents printed by :ref:`emulated printers ` are saved. -* **Open screenshots folder**: open the host system's file browser on the directory where screenshots of this emulated machine are saved. +* **Open screenshots folder**: open the host system's file browser on the directory where screenshots of this emulated machine are saved. Screenshots can also be viewed through the :doc:`manager`. Help ----