From 77641441300b24e491bbdc6383602f49a1c7a24c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Hrdli=C4=8Dka?= Date: Sun, 13 Nov 2022 19:43:20 +0100 Subject: [PATCH 1/9] Move the FAQ to docs --- index.rst | 1 + usage/faq.rst | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 usage/faq.rst diff --git a/index.rst b/index.rst index 65cc9c4..ea12aea 100644 --- a/index.rst +++ b/index.rst @@ -25,6 +25,7 @@ Contents :caption: Using 86Box usage/gettingstarted + usage/faq usage/roms usage/menubar usage/toolbar diff --git a/usage/faq.rst b/usage/faq.rst new file mode 100644 index 0000000..fcc3a1a --- /dev/null +++ b/usage/faq.rst @@ -0,0 +1,52 @@ +Frequently asked questions +========================== + +What is the difference between 86Box and applications like VirtualBox or Virtual PC? +------------------------------------------------------------------------------------ + +VirtualBox, Virtual PC and similar applications are *hypervisors*. For the most part, they execute code running in the virtual machine as is, and only step in whenever it is required to enforce the separation of a virtual machine from the rest of the system. This also means that the virtual machine sees the same CPU as the host system. + +They also mostly implement peripherals that are custom designed to let the guest take full potential of the virtualizer as long as appropriate drivers, which are distributed with the provided additions, are installed. This is great for modern operating systems and software that does is not designed for a specific hardware target, but rather an abstraction interface such as DirectX; however, running older applications and games will often lead to a suboptimal experience, as hypervisors don't tend to be designed with this usecase in mind. + +On the other hand, 86Box is a *system emulator*. It implements a whole system in software, which includes the CPU, chipset and additional cards, if any. Furthermore, it interprets every single instruction running in the virtual machine, and while that comes with the obvious tradeoff of emulation being more CPU intensive than virtualization, it also makes it possible to simulate authentic behavior of the original hardware, including its speed. This in turn allows running countless games and demos that wouldn't have ran in a hypervisor before, as they simply run too fast or fail to make use of various hardware quirks that don't exist in modern processors. + +In addition, the large variety of peripherals emulated by 86Box also makes it possible to use existing software, games and drivers that had been specifically designed for such peripherals. However, this obviously means that the emulator is also stuck with the limitations of the original hardware, and therefore it is not possible to offer advanced features such as mouse pointer integration. + +What is the difference between 86Box and QEMU? +---------------------------------------------- + +86Box and QEMU are both emulators, as they can both implement a whole computer system in software. However, QEMU is primarily designed to performantly translate between different instruction sets by implementing a generic CPU, and therefore doesn't try to emulate all the various quirks of the real hardware like 86Box. + +Similarly to hypervisors, QEMU also implements certain fictional peripherals that are designed to reduce the emulation overhead. Again, this all is great for modern software that is not designed for a specific hardware target, but not so great for older software. + +A common point of confusion is also QEMU's option to pick a specific CPU to be emulated, similarly to 86Box. This however only has the effect of changing the reported CPU identification (``CPUID`` instruction in x86) and does not impact the behavior of the emulation in any way. + +What is the difference between 86Box and PCem? +---------------------------------------------- + +86Box and PCem are both PC system emulators. In fact, 86Box originally started out as a fork of PCem in 2016. However, the codebases of both emulators have since then diverted by a lot. Because of this, features and bugs found in one emulator do not necessarily have to be present in the other. + +In general, 86Box focuses more on the accuracy of emulation, especially for older 8088/8086 based systems. This makes it more compatible with older applications, games and demos that make use of clever hardware tricks to make do with the limited computing power of the time. + +Meanwhile, PCem often takes various shortcuts to improve performance at the cost of accuracy, which does end up limiting the selection of software it can run. + +My virtual machine does not run at 100% speed, what do I do? +------------------------------------------------------------ + +If the emulation speed is consistently way under 100%, then your configuration is too demanding for your host system. Try to pick a slower emulated CPU speed. + +However, if you only experience casual drops in emulation speeds, you should not instantly worry, as the guest might simply be doing some heavy I/O operations. + +What is the top VM configuration my system will handle? +------------------------------------------------------- + +There is no formula that would tell you this. In general, the higher the host's IPC (instructions per clock) rating, the higher emulated CPU speeds it can handle. However, the emulation speeds also depend on the kind of software that runs in the virtual machine. + +Therefore, the best way to optimize your virtual machine configuration is simply trial and error. + +Are you going to add emulation of the Pentium 3 and/or newer CPUs? +------------------------------------------------------------------ + +In short, no. Newer CPUs are way too powerful and even the top-end systems that are currently on the market are not nearly performant enough to be able to emulate them at usable speeds. In fact, we already had to add some low-clocked variants of the Pentium 2 that never actually existed, just so more people could use it! + +For further reading, team member RichardG wrote a `blog post <86box.net/2022/03/21/why-not-p3>`_ that goes into the details of what makes the emulation of newer CPUs so controversial. From 47caf5d15f39d5b1ff22a68301206c6b9906f0b8 Mon Sep 17 00:00:00 2001 From: RichardG867 Date: Sat, 26 Nov 2022 03:12:37 -0300 Subject: [PATCH 2/9] machinespecific: Add proprietary keyboards --- hardware/machinespecific.rst | 49 ++++++++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/hardware/machinespecific.rst b/hardware/machinespecific.rst index 21f9ef9..be950f9 100644 --- a/hardware/machinespecific.rst +++ b/hardware/machinespecific.rst @@ -5,6 +5,51 @@ This page contains important notes related to specific machine models emulated b ---- +8088 +---- + +.. _t1000: +.. rubric:: Toshiba T1000 + +The function keys can be accessed by holding Right Alt or Right Ctrl: + +* ``Right Alt/Ctrl + Num Lock``: Show/hide numeric keypad overlay +* ``Right Alt/Ctrl + Right``: Change internal display font +* ``Right Alt/Ctrl + Home``: Use internal display +* ``Right Alt/Ctrl + End``: Use external display + +8086 +---- + +.. _m24: +.. rubric:: Olivetti M21/24/24SP + +The special keys on Olivetti keyboards are mapped as such: + +* ``Page Up``: CLEAR +* ``Page Down``: BREAK +* ``Print Screen``: SCR PRT +* ``Menu``: HELP +* ``Left Windows``: 00 +* ``Insert``: F13 +* ``Home``: F14 +* ``Del``: F15 +* ``End``: F16 +* ``Right Alt``: F17 +* ``Right Win``: F18 + +.. rubric:: Olivetti M240 + +See: :ref:`m24` + +.. rubric:: Toshiba T1200 + +All function keys from the :ref:`T1000 ` are present, plus: + +* ``Right Alt/Ctrl + Page Up``: Turbo mode on +* ``Right Alt/Ctrl + Page Down``: Turbo mode off +* ``Right Alt/Ctrl + Print Screen``: Show/hide pop-up window + 80286 ----- @@ -20,8 +65,8 @@ Socket 7 * Modular motherboard, consisting of a **P/I-P65UP5** baseboard and one of the following CPU cards: - * **C-P55T2D:** Socket 7 with Intel 430HX northbridge. - * **C-P6ND:** Socket 8 with Intel 440FX northbridge. + * **C-P55T2D:** Socket 7 with Intel 430HX northbridge; + * **C-P6ND:** Socket 8 with Intel 440FX northbridge; * **C-PKND:** Slot 1 with Intel 440FX northbridge. * While the northbridge depends on the selected CPU card, the southbridge always remains the Intel PIIX3, as it is located on the baseboard. From 97ad449c6febf734f3e2749a0effb3624968df9f Mon Sep 17 00:00:00 2001 From: Cacodemon345 Date: Wed, 28 Dec 2022 22:56:06 +0600 Subject: [PATCH 3/9] It is expansion cards, not extension cards --- usage/gettingstarted.rst | 2 +- usage/roms.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/usage/gettingstarted.rst b/usage/gettingstarted.rst index ac5285f..c79ce06 100644 --- a/usage/gettingstarted.rst +++ b/usage/gettingstarted.rst @@ -5,7 +5,7 @@ Here are the basic steps to help you get started with 86Box. The user interface .. 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 extension 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 `. +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 `. .. rubric:: Step 2: Meet the main window diff --git a/usage/roms.rst b/usage/roms.rst index da91147..cf838d1 100644 --- a/usage/roms.rst +++ b/usage/roms.rst @@ -1,7 +1,7 @@ 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 extension cards. +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. The ROM set is organized into several directories for each device type, each of which contains futher subdirectories for each machine or device model or category. @@ -41,4 +41,4 @@ The following locations are searched on macOS: 1. ``~/Library/Application Support/net.86box.86Box/roms`` 2. ``/Library/Application Support/net.86box.86Box/roms`` -.. tip:: The list of all paths searched when loading ROMs is printed to the log and standard output when 86Box starts. \ No newline at end of file +.. tip:: The list of all paths searched when loading ROMs is printed to the log and standard output when 86Box starts. From 3c40288e47f3d70809b797cab4addd11cd3b5537 Mon Sep 17 00:00:00 2001 From: Tiaan Louw Date: Thu, 22 Dec 2022 07:14:20 +0100 Subject: [PATCH 4/9] Fix grammatic error in docs --- dev/buildguide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev/buildguide.rst b/dev/buildguide.rst index 857ab38..4bdf6f4 100644 --- a/dev/buildguide.rst +++ b/dev/buildguide.rst @@ -13,7 +13,7 @@ Toolchain files Toolchain files are contained in the ``cmake`` directory. They define compiler flags and the 86Box-specific ``Release``, ``Debug`` and ``Optimized`` build types. -It is not required to required to use the included toolchain files, but it is highly recommended to make sure your build is compiled with the same configuration as used by the rest of the team and our userbase. +It is not required to use the included toolchain files, but it is highly recommended to make sure your build is compiled with the same configuration as used by the rest of the team and our userbase. The currently included files are: From fb257594373309b4f38eb24475e885e6b346b848 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miran=20Gr=C4=8Da?= Date: Thu, 19 Jan 2023 05:41:20 +0100 Subject: [PATCH 5/9] Update network.rst for 3.11. --- hardware/network.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hardware/network.rst b/hardware/network.rst index 5c337de..c68b2a8 100644 --- a/hardware/network.rst +++ b/hardware/network.rst @@ -70,7 +70,7 @@ With the exception of **[LPT] Parallel Port Internet Protocol**, every emulated SLiRP port forwarding ^^^^^^^^^^^^^^^^^^^^^ -Port forwarding allows the host system and other devices on its network to access TCP and UDP servers running on the emulated machine. This feature is configured through the ``[SLiRP Port Forwarding]`` section of the configuration file. +Port forwarding allows the host system and other devices on its network to access TCP and UDP servers running on the emulated machine. This feature is configured through the ``[SLiRP Port Forwarding #x]`` section of the configuration file, where x is the number of the emulated network card, in the range of 1 to 4. Each port forward must be assigned a number, starting at 0 and counting up (skipping a number will result in all subsequent port forwards being ignored), which replaces ``X`` on the following directives: From b70f98a08c09ed7fa5eceb47459fa7c6e8e535b7 Mon Sep 17 00:00:00 2001 From: RichardG867 Date: Tue, 28 Feb 2023 12:12:17 -0300 Subject: [PATCH 6/9] dev/api/io: Add missing formatting --- dev/api/io.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dev/api/io.rst b/dev/api/io.rst index e984994..fb415d3 100644 --- a/dev/api/io.rst +++ b/dev/api/io.rst @@ -3,7 +3,7 @@ Port I/O 86Box handles the x86 port I/O space through **I/O handlers**. These handlers can be added with the ``io_sethandler`` function and removed with the ``io_removehandler`` function, both provided by ``86box/io.h``. -.. flat-table:: io_sethandler / io_removehandler +.. flat-table:: ``io_sethandler`` / ``io_removehandler`` :header-rows: 1 :widths: 1 999 @@ -203,7 +203,7 @@ A second type of I/O handler, **I/O traps** allow a device (usually System Manag /* ... */ }; -.. flat-table:: io_trap_add +.. flat-table:: ``io_trap_add`` :header-rows: 1 :widths: 1 999 @@ -228,7 +228,7 @@ A second type of I/O handler, **I/O traps** allow a device (usually System Manag * - **Return value** - Opaque (``void``) pointer representing the newly-created I/O trap. -.. flat-table:: io_trap_remap +.. flat-table:: ``io_trap_remap`` :header-rows: 1 :widths: 1 999 From a7c8c26645186db65313d1d6f7f9503b33038a9b Mon Sep 17 00:00:00 2001 From: RichardG867 Date: Tue, 28 Feb 2023 12:13:29 -0300 Subject: [PATCH 7/9] dev/api/pci: Remove redundant example code line --- dev/api/pci.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/dev/api/pci.rst b/dev/api/pci.rst index 8768e6f..cd21c41 100644 --- a/dev/api/pci.rst +++ b/dev/api/pci.rst @@ -19,8 +19,6 @@ PCI devices can be added with the ``pci_add_card`` function in the device's ``in #include <86box/device.h> #include <86box/pci.h> - #define FOO_ONBOARD 0x80000000 /* most significant bit set = on-board */ - typedef struct { int slot; uint8_t pci_regs[256]; /* 256*8-bit configuration register array */ From c95e2d1cc3e469ae1b038840d7eb7fa8ebc8e375 Mon Sep 17 00:00:00 2001 From: RichardG867 Date: Tue, 28 Feb 2023 12:16:06 -0300 Subject: [PATCH 8/9] dev/api/pci: Fix small mistake in multifunction example --- dev/api/pci.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev/api/pci.rst b/dev/api/pci.rst index cd21c41..6a8ec2b 100644 --- a/dev/api/pci.rst +++ b/dev/api/pci.rst @@ -319,7 +319,7 @@ The ``func`` parameter passed to a device's configuration space read/write callb /* Reset PCI configuration registers. */ memset(dev->pci_regs[0], 0, sizeof(dev->pci_regs[0])); - memset(dev->pci_regs[0], 0, sizeof(dev->pci_regs[0])); + memset(dev->pci_regs[1], 0, sizeof(dev->pci_regs[1])); /* Write default vendor IDs, device IDs, etc. */ From 94b0fac5432df117d519e85df0a9aaef6e36f4b8 Mon Sep 17 00:00:00 2001 From: RichardG867 Date: Sun, 16 Apr 2023 14:32:28 -0300 Subject: [PATCH 9/9] hardware/network: Fix note about forwarding IP on multi-card setups --- hardware/network.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hardware/network.rst b/hardware/network.rst index c68b2a8..d8a93e9 100644 --- a/hardware/network.rst +++ b/hardware/network.rst @@ -80,7 +80,7 @@ Each port forward must be assigned a number, starting at 0 and counting up (skip The host system can access forwarded ports through 127.0.0.1 or its own IP address, while other devices on the network can access them through the host's IP address. -.. note:: The emulated machine's IP address must be set to 10.0.2.15 (the default IP provided through DHCP) for port forwarding to work. +.. note:: The emulated machine's IP address must be set to 10.0.\ *x*\ .15 (the default IP provided through DHCP) for port forwarding to work. .. container:: toggle-always-show