Add ISABugger documentation and make a bunch of other small changes

dev/builds.rst

@@ -8,12 +8,12 @@ The `86Box Jenkins <https://ci.86box.net/>`_ provides all kinds of pre-release t
 Standard
 --------
 
-Standard builds (**86Box**) are compiled with default options. Release versions of 86Box are based on these.
+Standard builds (**86Box**) are compiled with default options. Release versions of 86Box are based on standard builds.
 
 Debug
 -----
 
-Debug builds (**86Box-Debug**) are :ref:`standard builds <dev/builds:Standard>` compiled with debug symbols and no optimizations, to allow for debugging with ``gdb`` and other tools if you don't have a full 86Box development setup. These run slower than standard builds due to the removal of optimizations and addition of debugging features.
+Debug builds (**86Box-Debug**) are :ref:`standard builds <dev/builds:Standard>` compiled with debug symbols and no optimizations, to allow for debugging with ``gdb`` and other tools if you don't have a full 86Box development setup. Debug builds run slower than standard builds due to the removal of optimizations and addition of debugging features.
 
 Development
 -----------
@@ -23,7 +23,7 @@ Development builds (**86Box-Dev**) are compiled with ``DEV_BUILD=y``, enabling a
 Optimized
 ---------
 
-Optimized builds (**86Box-Optimized**) are :ref:`standard builds <dev/builds:Standard>` which have been optimized for use with a specific CPU family on the host machine. These provide slight performance improvements, especially on older or low-end hosts; however, the aggressive optimizations employed **may result in bugs** not present on standard builds.
+Optimized builds (**86Box-Optimized**) are :ref:`standard builds <dev/builds:Standard>` which have been optimized for use with a specific CPU family on the host machine. Optimized builds provide slight performance improvements, especially on older or low-end hosts; however, the aggressive optimizations employed **may result in bugs** not present on standard builds.
 
 There are many different optimized binaries available for each build, with each one corresponding to a CPU family. The table below lists most CPUs currently supported by optimized builds, along with the respective binaries you should use with them, as well as their codenames (as shown on an identification tool such as `CPU-Z <http://www.cpuid.com/softwares/cpu-z.html>`_).
 

hardware/ideterqua.rst

@@ -79,4 +79,4 @@ On kernels without ``libata`` (typically older than 2.6.19), add the following p
 * **Tertiary:** ``ide2=0x168,0x36e,10`` (assuming IRQ 10)
 * **Quaternary:** ``ide3=0x1e8,0x3ee,11`` (assuming IRQ 11)
 
-.. note:: Some Linux distributions may automatically detect and enable both additional channels, however, that is very rarely the case.
+.. note:: Some Linux distributions may automatically detect and enable both additional channels; however, that is very rarely the case.

hardware/isabugger.rst

@@ -0,0 +1,70 @@
+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 <settings/peripherals:ISABugger>`.
+
+These displays and LEDs are shown on the :ref:`status bar <usage/statusbar:ISABugger>` as described in the diagram below:
+
+.. image:: images/isabugger.png
+   :align: center
+
+Background
+----------
+
+From ``src/device/bugger.c``:
+
+.. code-block:: none
+
+ 		Implementation of the ISA Bus (de)Bugger expansion card
+ 		sold as a DIY kit in the late 1980's in The Netherlands.
+ 		This card was a assemble-yourself 8bit ISA addon card for
+ 		PC and AT systems that had several tools to aid in low-
+ 		level debugging (mostly for faulty BIOSes, bootloaders
+ 		and system kernels...)
+ 
+ 		The standard version had a total of 16 LEDs (8 RED, plus
+ 		8 GREEN), two 7-segment displays and one 8-position DIP
+ 		switch block on board for use as debugging tools.
+ 
+ 		The "Plus" version, added an extra 2 7-segment displays,
+ 		as well as a very simple RS-232 serial interface that
+ 		could be used as a mini-console terminal.
+
+Registers
+---------
+
+The ISABugger's control registers can be accessed through the following operations on I/O ports 7Ah and 7Bh:
+
+* **Writing:** write the register's index to port 7Ah, then write the value to port 7Bh.
+* **Reading:** write the register's index to port 7Ah, then read the value from port 7Bh.
+* **Index reading:** the last register index written to port 7Ah can be read back from the same port. The most significant bit is always set, as an indicator that the ISABugger is enabled.
+
+.. note:: The ISABugger I/O ports only support byte (inb/outb) operations. Word (inw/outw) and dword (inl/outl) operations will result in undefined behavior; so will selecting or attempting to read back an unknown register index, or performing an illegal operation such as reading from a write-only register.
+
+Register reference
+^^^^^^^^^^^^^^^^^^
+
+.. rubric:: Index 0x00 - Red LEDs (write-only)
+.. rubric:: Index 0x01 - Green LEDs (write-only)
+
+Each LED bank shows a binary representation of the 8-bit value written to its register, from the most significant bit on the left to the least significant bit on the right. Setting a bit will light up its corresponding LED (displayed as **G** or **R**), and clearing a bit will dim its LED (displayed as **g** or **r**).
+
+.. rubric:: Index 0x02 - Right display (write-only)
+.. rubric:: Index 0x04 - Left display (write-only)
+
+Each display shows a hexadecimal representation of the 8-bit value written to its register.
+
+.. rubric:: Index 0x20 - Serial port data (not implemented) (read/write)
+.. rubric:: Index 0x40 - Serial port configuration (not implemented) (read/write)
+
+While the aforementioned real ISABugger card is equipped with an independent RS-232 serial interface, that feature is currently not implemented on 86Box in an user-facing manner.
+
+.. rubric:: Index 0x80 - Initialize (not implemented) (write-only)
+
+This register has no effect on 86Box, as the emulated ISABugger is always enabled and ready.
+
+.. rubric:: Index 0xFF - Reset (special)
+
+Writing register index 0xFF to port 7Ah will immediately reset all registers to their startup value, clearing all displays and LED banks.
+
+This is a special register which cannot be read or written; writing to port 7Bh immediately after a reset will result in the value being sent to the default register index of 0x00, which corresponds to the red LEDs.

hardware/machinespecific.rst

@@ -10,7 +10,7 @@ This page contains important notes related to specific machine models emulated b
 
 .. rubric:: IBM AT
 
-* The IBM Personal Computer Diagnostics disks will produce a *0152 ERROR - SYSTEM BOARD* code if :ref:`time synchronization <settings/machine:Time synchronization>` is enabled, due to a lack of Y2K compliance. This code can be cleared by disabling time synchronization, then clearing the CMOS by deleting ``ibmat.nvr`` from the ``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 <settings/machine:Time synchronization>` is enabled. This code can be cleared by disabling time synchronization, then clearing the CMOS by deleting ``ibmat.nvr`` from the ``nvr`` directory.
 
 Socket 7
 --------
@@ -62,7 +62,7 @@ Slot 2
 * Hybrid motherboard supporting both Slot 1 and Slot 2 CPUs.
 * The maximum amount of RAM is limited to 2032 MB due to a BIOS bug with 2048 MB.
 * ACPI is disabled by default. It can be enabled through the *ACPI Aware O/S* option of the *Power Management Setup* menu on the BIOS setup.
-* Once enabled, ACPI does not work correctly if a VIA Cyrix III CPU is selected. See :ref:`brokenacpi` for more information.
+* Once enabled, ACPI :ref:`does not work correctly <brokenacpi>` if a non-Intel CPU is selected.
 
 Socket 370
 ----------

index.rst

@@ -40,7 +40,8 @@ to retro computing and, of course, 86Box. We look forward to hearing from you!
    hardware/machinespecific
    hardware/diskimages
    hardware/ideterqua
-   hardware/network   
+   hardware/network
+   hardware/isabugger
 
 .. toctree::
    :maxdepth: 1

settings/display.rst

@@ -20,7 +20,7 @@ The *Configure* button provides the following settings:
 * **Voodoo type:** type of Voodoo card to emulate.
 
    * **Voodoo Graphics:** the original Voodoo model, with a single Texture Mapping Unit operating at 50 MHz.
-   * **Obsidian SB50 + Amethyst:** a variant of the Voodoo Graphics, equipped with a second Texture Mapping Unit like the Voodoo 2.
+   * **Obsidian SB50 + Amethyst:** a variant of the Voodoo Graphics, with two Texture Mapping Units operating at 50 MHz.
    * **Voodoo 2:** the second Voodoo model, with two Texture Mapping Units operating at 90 MHz, as well as SLI support.
 
 * **Framebuffer memory size** / **Texture memory size**: amount of video memory to give the Frame Buffer Interface and Texture Mapping Unit(s), respectively.
@@ -30,4 +30,4 @@ The *Configure* button provides the following settings:
 * **SLI:** add a second Voodoo 2 card to the system, connected to the first one through Scan Line Interleave (SLI).
 * **Recompiler:** enable the Voodoo recompiler for faster emulation.
 
-.. note:: The Voodoo recompiler requires a host CPU with SSE2 support. SSE2 is present in most CPUs made since 2005.
+.. note:: The Voodoo recompiler requires a host CPU with SSE2 support. SSE2 is present in most CPUs released since 2005.

settings/floppycdrom.rst

@@ -8,7 +8,7 @@ Floppy drives
 
 Up to four floppy disk drives can be attached to the emulated system, although not all BIOSes provide support for more than two drives. The following settings apply to the selected drive:
 
-* **Type:** floppy drive to emulate. Some types have special properties and therefore should only be used if you know what you're doing:
+* **Type:** floppy drive to emulate. Some types have special properties and therefore should only be used in very specific applications:
 
    * **5.25" 1.2M PS/2** and **3.5" 1.44M PS/2:** IBM PS/2 drives, which invert the polarity of the Density Select pin.
    * **5.25" 1.2M 300/360 RPM** and **3.5" 1.44M 300/360 RPM**: "3-mode" drives, which are capable of reading 360K 5.25" or PC-98 3.5" disks if the emulated machine's BIOS supports 3-mode operation.

settings/machine.rst

@@ -6,7 +6,7 @@ The *Machine* page contains settings related to the emulated machine as a whole,
 Machine type / Machine
 ----------------------
 
-Machine/motherboard to emulate. The *Machine type* box lists all available processor classes, while the *Machine* box lists all available machines of the selected processor class.
+Machine/motherboard to emulate. The *Machine type* box lists all available machine classes, while the *Machine* box lists all available machines on the selected class.
 
 The *Configure* button opens a new window with settings specific to the machine's onboard devices, such as the amount of installed video memory for an onboard video chip.
 
@@ -23,7 +23,7 @@ Math co-processor to emulate. This box will not be enabled if a processor with a
 Wait states
 -----------
 
-Number of memory wait states. This box is only enabled and relevant if a 286- or 386-class CPU is selected.
+Number of memory wait states to use on a 286- or 386-class processor. This box will not be enabled if any other processor family is selected.
 
 Memory
 ------
@@ -38,8 +38,8 @@ Enable the dynamic recompiler, which provides faster but less accurate CPU emula
 Time synchronization
 --------------------
 
-Time synchronization automatically copies your host system's date and time settings over to the emulated machine's hardware real-time clock. Synchronization is performed every time the emulated machine's operating system reads the hardware clock to calibrate its own internal clock, which usually happens once on every boot.
+Time synchronization automatically copies your host system's date and time settings over to the emulated machine's hardware real-time clock. Synchronization is performed every time the guest operating system reads the hardware clock to calibrate its own internal clock, which usually happens once on every boot.
 
 * **Disabled:** do not perform time synchronization.
-* **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.
+* **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.

settings/peripherals.rst

@@ -24,7 +24,7 @@ FD Controller
 
 Floppy disk drive controller card to emulate.
 
-Selecting a controller is not usually necessary. The DTK controllers are useful for adding high-density 1.44 MB floppy support to XT machines.
+Selecting a controller is not usually necessary. The DTK controllers are useful for adding high-density 1.44M floppy support to XT machines.
 
 The BIOS option ROM address used by the selected controller can be configured through the *Settings* button.
 
@@ -40,27 +40,22 @@ The IRQ used by each controller can be configured through its respective *Settin
 ISABugger
 ---------
 
-Emulate an **ISABugger** debugging card. Documentation on the card's functionality can be found in the `header comment <https://github.com/86Box/86Box/blob/master/src/device/bugger.c#L1>`_ of ``src/device/bugger.c`` in the 86Box source code.
-
-The following information is displayed on the status bar (from left to right) when the ISABugger is enabled:
-
-* Hexadecimal values corresponding to the left and right 7-segment displays, respectively.
-* Green LED bank, from the most significant to the least significant bit: **G** if the LED is lit, **g** if it's not lit.
-* Red LED bank, from the most significant to the least significant bit: **R** if the LED is lit, **r** if it's not lit.
+Emulate an **ISABugger** debugging interface card, equipped with two hexadecimal displays and two LED banks, all controlled by the emulated machine. See :doc:`../hardware/isabugger` for documentation on the card's features.
 
 POST card
 ---------
 
-Emulate a diagnostic POST card, which displays POST code values issued by the emulated machine's BIOS on the status bar. The leftmost hexadecimal value is the most recent POST code reported, while the rightmost value is the second most recent code, like on a real dual-display POST card. A value of ``--`` indicates that no POST code has been reported yet.
+Emulate a diagnostic POST card, which displays POST code values issued by the emulated machine's BIOS on the status bar. See :ref:`Status bar: POST card <usage/statusbar:POST card>` for more information.
 
 The POST card will automatically use the correct diagnostic I/O port for the emulated machine:
 
 * Port 80h on the IBM AT, clones and the XT-based Xi 8088;
 * Port 84h on early Compaq machines;
-* Port 0190h on IBM PS/1 and PS/2 machines not based on Micro Channel Architecture;
+* Port 0190h on IBM PS/1 and PS/2 machines not based on the Micro Channel Architecture;
 * Port 0680h on Micro Channel Architecture machines.
 
-.. note:: Some guest operating systems (such as Linux before kernel 3.0) rely heavily on the first DMA extra page register, which is shared with the POST card. If you notice the POST code display is flickering and the emulation speed has decreased drastically, try disabling the POST card.
+.. note:: Some guest operating systems (such as Linux before kernel 3.0) rely heavily on a DMA register which shares port 80h with the POST card. If you notice the POST code display is flickering and the emulation speed has decreased drastically, try disabling the POST card.
+
 
 ISA RTC
 -------

settings/sound.rst

@@ -65,4 +65,4 @@ The type of UltraSound to emulate (Classic or MAX), I/O port and amount of onboa
 Use FLOAT32 sound
 -----------------
 
-Use the 32-bit floating point (instead of 16-bit integer) data type for audio output, which is less prone to clipping but may not work at all on some host systems. Try disabling this option if you're getting no audio output from 86Box whatsoever.
+Use the 32-bit floating point (instead of 16-bit integer) data type for audio output, which is less prone to clipping but may not work at all on some host systems. Try disabling this if you're getting no audio output from 86Box at all.

usage/statusbar.rst

@@ -69,4 +69,21 @@ This icon will appear if :doc:`networking <../settings/network>` is enabled. No
 
 This icon is always present. Double-clicking it opens a sound gain control, which allows you to increase the loudness of all audio produced by the emulated machine's PC speaker, :doc:`sound cards <../settings/sound>` and other sound hardware.
 
-.. note:: The gain control does not apply to MIDI music sent to a software synthesizer through the :ref:`System MIDI <settings/sound:MIDI Out Device>` device, as these synthesizers are external to 86Box.
+.. note:: The gain control does not apply to MIDI music sent to a software synthesizer through the :ref:`System MIDI <settings/sound:MIDI Out Device>` device, as these synthesizers are external to 86Box.
+
+Additional information area
+---------------------------
+
+When enabled, the :ref:`settings/peripherals:ISABugger` and :ref:`settings/peripherals:POST card` display additional information on the status bar, to the right of the icons described above.
+
+ISABugger
+^^^^^^^^^
+
+The ISABugger's hexadecimal displays and LED banks are displayed here. See :doc:`../hardware/isabugger` for more information.
+
+POST card
+^^^^^^^^^
+
+The leftmost hexadecimal value is the most recent POST code reported, while the rightmost value is the second most recent code, like on a real dual-display POST card. A value of ``--`` indicates that no POST code has been reported yet.
+
+.. note:: The additional information area can only be used by one peripheral at a time. If both are enabled simultaneously, the POST card takes over whenever a POST code is reported, and the ISABugger takes over whenever one of its registers is written to.